What Happens to Legacy Data During Workspace Upgrades in Maka

During workspace upgrades, Apache Maka isolates legacy tables, migrates compatible data to new schema versions, and drops obsolete structures while aborting upgrades if legacy bindings create inconsistencies.

Apache Maka manages workspace state through a SQLite-backed storage layer that evolves between versions. When you initiate a workspace upgrade, the system must reconcile data written by previous runtime generations—referred to as legacy data—to ensure deterministic migration without corruption.

Legacy Data Strategy in Maka's Storage Layer

Maka implements a defensive migration strategy that prioritizes data integrity over preservation of obsolete structures.

Legacy Table Isolation and Migration

In packages/storage/src/sqlite-runtime-schema.ts, the schema definition maintains separate tables for legacy data, such as runtime_legacy_invocation_openings. During an upgrade, the migration engine copies rows that can be mapped to the new schema into current tables, then explicitly drops the legacy tables using DROP TABLE statements. This ensures the upgraded workspace contains only the active schema while eliminating orphaned structures.

Data Retention Rules

The system applies three strict rules to legacy data during migration:

• Preserve: Rows that align with the new schema structure are migrated to current tables.
• Drop: Tables marked as obsolete are removed entirely after data extraction.
• Ignore: Individual rows that cannot be transformed to the new schema—for example, due to missing required columns—are silently discarded to prevent upgrade failures.

Runtime Host Validation During Upgrade Preparation

Before any schema changes occur, the runtime host kernel validates the safety of the upgrade.

Legacy Binding Verification

The host.upgrade.prepare operation, implemented in packages/runtime-host/src/server/host-kernel.ts, inspects existing workspace bindings for legacy references. If the kernel detects a legacy binding without a corresponding deployment generation—indicated by the legacyBindingHasNoDeployment check—it immediately aborts the upgrade and returns an error requiring the user to re-onboard the host. This prevents inconsistent states where legacy bindings reference non-existent resources in the new schema.

Code Implementation Examples

The following patterns demonstrate how Maka handles legacy data transitions in production code.

// From host-kernel.ts: Validating legacy bindings before upgrade
'host.upgrade.prepare': async (input) => {
  // Verify that legacy bindings are safe before proceeding
  if (legacyBindingHasNoDeployment(input)) {
    throw new Error('Re‑onboard this Runtime Host before changing it; its legacy binding has no deployment generation');
  }
  // Continue with upgrade...
}

-- From sqlite-runtime-schema.ts: Migrating and cleaning legacy invocation data
INSERT INTO runtime_invocation_openings (invocation_id, opened_at, opening_json)
SELECT invocation_id, opened_at, opening_json
FROM runtime_legacy_invocation_openings;

DROP TABLE runtime_legacy_invocation_openings;

Testing Legacy Data Migration

Maka's test suite verifies that workspace upgrades handle legacy data correctly without data loss or schema corruption.

• workspace-version-authority-persistence.test.ts: Validates that workspace authority data persists correctly across schema version bumps, ensuring that critical metadata survives the migration process according to the source code in packages/storage/src/__tests__/.
• sqlite-runtime-store.test.ts: Confirms that the runtime_legacy_invocation_openings table is properly merged into the current invocation table and subsequently removed, preventing table accumulation across upgrades.

Summary

• Legacy tables like runtime_legacy_invocation_openings are retained temporarily during workspace upgrades to prevent data loss.
• The schema migration in sqlite-runtime-schema.ts copies compatible data to new tables, then drops obsolete legacy tables.
• The host.upgrade.prepare operation in host-kernel.ts validates legacy bindings and aborts upgrades if inconsistencies are detected.
• Unmappable legacy rows are ignored rather than blocking the upgrade process.
• Comprehensive tests in packages/storage/src/__tests__/ verify correct behavior across version transitions.

Frequently Asked Questions

What is legacy data in Apache Maka?

Legacy data refers to information written by previous runtime generations and stored in tables suffixed with "legacy," such as runtime_legacy_invocation_openings. This data follows older schema conventions that may differ from the current workspace structure.

Does Maka delete legacy data during workspace upgrades?

Maka migrates compatible legacy data into current tables before dropping obsolete legacy tables. Data that cannot be mapped to the new schema is silently discarded, while successfully migrated data is preserved in the updated structure.

How does Maka prevent corrupted upgrades when legacy bindings exist?

The system validates legacy bindings during the host.upgrade.prepare phase. If a legacy binding lacks a deployment generation, the upgrade aborts immediately with an error instructing the user to re-onboard the runtime host.

Where is the workspace upgrade logic implemented?

The upgrade logic spans packages/storage/src/sqlite-runtime-schema.ts for database migrations and packages/runtime-host/src/server/host-kernel.ts for pre-upgrade validation. Test coverage exists in packages/storage/src/__tests__/workspace-version-authority-persistence.test.ts and related files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}