# What Happens to Legacy Data During Workspace Upgrades in Maka

> Learn how Apache Maka handles legacy data during workspace upgrades. Maka isolates old tables, migrates compatible data, and drops obsolete structures for a smooth transition.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: migration-guide
- Published: 2026-09-04

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```typescript
// 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...
}

```

```sql
-- 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts) copies compatible data to new tables, then drops obsolete legacy tables.
- The `host.upgrade.prepare` operation in [`host-kernel.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-schema.ts) for database migrations and [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/__tests__/workspace-version-authority-persistence.test.ts) and related files.