@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/migration/productionRegistry.js

@@ -0,0 +1,486 @@
+/** The one production transition registry and its baseline-to-current delivery gate. */
+import { latestStorageVersionState } from "../upgrade/recordVersions.js";
+import { assertBaselineConsistency, baselineStorageVersionState } from "./baseline.js";
+import { planMigration } from "./planner.js";
+import { MigrationRegistry } from "./registry.js";
+const FINAL_REVIEW_AGGREGATE_FROM_VERSION = 16;
+const FINAL_REVIEW_AGGREGATE_TO_VERSION = 17;
+const WORK_ITEM_FROM_VERSION = 6;
+const WORK_ITEM_TO_VERSION = 7;
+const WORK_ITEM_GIT_SNAPSHOT_FROM_VERSION = 7;
+const WORK_ITEM_GIT_SNAPSHOT_TO_VERSION = 8;
+const WORK_ITEM_GROUP_HISTORY_FROM_VERSION = 8;
+const WORK_ITEM_GROUP_HISTORY_TO_VERSION = 9;
+const AGENT_RUN_FROM_VERSION = 5;
+const AGENT_RUN_TO_VERSION = 6;
+const REVIEW_ROUND_FROM_VERSION = 2;
+const REVIEW_ROUND_TO_VERSION = 3;
+const REVIEW_ROUND_GIT_SNAPSHOT_FROM_VERSION = 3;
+const REVIEW_ROUND_GIT_SNAPSHOT_TO_VERSION = 4;
+const ACTIVE_RUN_POINTER_FROM_VERSION = 1;
+const ACTIVE_RUN_POINTER_TO_VERSION = 2;
+const ACTIVE_RUN_POINTER_NAMESPACE_FROM_VERSION = 2;
+const ACTIVE_RUN_POINTER_NAMESPACE_TO_VERSION = 3;
+const MANAGED_WORKSPACE_FROM_VERSION = 1;
+const MANAGED_WORKSPACE_TO_VERSION = 2;
+/**
+ * Build the authoritative production graph. Transition intent and executable
+ * transforms are registered together here; compatible loading and offline
+ * migration consume this same graph.
+ */
+export function createProductionStorageRegistry() {
+    assertBaselineConsistency();
+    const registry = new MigrationRegistry().registerOfflineMigration({
+        axis: "aggregate",
+        fromVersion: FINAL_REVIEW_AGGREGATE_FROM_VERSION,
+        toVersion: FINAL_REVIEW_AGGREGATE_TO_VERSION,
+        preconditions: requireAggregateV16Snapshot,
+        transform: migrateAggregateV16ToV17,
+        declaredEffects: []
+    })
+        .registerOfflineMigration(recordFamilyStep("workItem", WORK_ITEM_FROM_VERSION, WORK_ITEM_TO_VERSION, "workItems"))
+        .registerOfflineMigration(recordFamilyStep("workItem", WORK_ITEM_GIT_SNAPSHOT_FROM_VERSION, WORK_ITEM_GIT_SNAPSHOT_TO_VERSION, "workItems"))
+        .registerOfflineMigration(workItemExecutionGroupHistoryStep())
+        .registerOfflineMigration(recordFamilyStep("agentRun", AGENT_RUN_FROM_VERSION, AGENT_RUN_TO_VERSION, "agentRuns"))
+        .registerOfflineMigration(recordFamilyStep("reviewRound", REVIEW_ROUND_FROM_VERSION, REVIEW_ROUND_TO_VERSION, "reviewRounds"))
+        .registerOfflineMigration(recordFamilyStep("reviewRound", REVIEW_ROUND_GIT_SNAPSHOT_FROM_VERSION, REVIEW_ROUND_GIT_SNAPSHOT_TO_VERSION, "reviewRounds"))
+        .registerOfflineMigration(recordFamilyStep("activeRunPointer", ACTIVE_RUN_POINTER_FROM_VERSION, ACTIVE_RUN_POINTER_TO_VERSION, "activeRuns"))
+        .registerOfflineMigration(managedWorkspaceFamilyStep())
+        .registerOfflineMigration(activeRunPointerNamespaceStep());
+    assertRegistryCoversBaselineToCurrent(registry);
+    return registry;
+}
+function workItemExecutionGroupHistoryStep() {
+    return {
+        axis: "record",
+        recordKind: "workItem",
+        fromVersion: WORK_ITEM_GROUP_HISTORY_FROM_VERSION,
+        toVersion: WORK_ITEM_GROUP_HISTORY_TO_VERSION,
+        preconditions: (snapshot) => requireRecordFamilyVersion(snapshot, "workItem", WORK_ITEM_GROUP_HISTORY_FROM_VERSION, "workItems"),
+        transform: migrateWorkItemExecutionGroupHistory,
+        declaredEffects: []
+    };
+}
+/**
+ * ManagedWorkspace is stored once in the owner-keyed workspace map and copied
+ * into Candidates, AgentRuns, and ReviewRounds as immutable lifecycle
+ * evidence.  Those copies are the same record family, not independent parent
+ * records: advancing only the map leaves an otherwise legal historical Home
+ * unreadable by the strict current parser.
+ */
+function managedWorkspaceFamilyStep() {
+    return {
+        axis: "record",
+        recordKind: "managedWorkspace",
+        fromVersion: MANAGED_WORKSPACE_FROM_VERSION,
+        toVersion: MANAGED_WORKSPACE_TO_VERSION,
+        preconditions: requireLegacyManagedWorkspaceFamily,
+        transform: migrateManagedWorkspaceFamily,
+        declaredEffects: []
+    };
+}
+function requireLegacyManagedWorkspaceFamily(snapshot) {
+    requireRecordFamilyVersion(snapshot, "managedWorkspace", MANAGED_WORKSPACE_FROM_VERSION, "managedWorkspaces");
+    visitEmbeddedManagedWorkspaces(snapshot, (workspace, label) => {
+        requireManagedWorkspaceVersion(workspace, MANAGED_WORKSPACE_FROM_VERSION, label);
+        return workspace;
+    });
+}
+function migrateManagedWorkspaceFamily(snapshot) {
+    requireLegacyManagedWorkspaceFamily(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...manifestVersions,
+            managedWorkspace: MANAGED_WORKSPACE_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const migrated = visitEmbeddedManagedWorkspaces(snapshot, (workspace) => ({ ...workspace, schemaVersion: MANAGED_WORKSPACE_TO_VERSION }));
+    return { schemaManifest, state: migrated.state };
+}
+/**
+ * Rewrite every persisted ManagedWorkspace occurrence while preserving the
+ * surrounding record bytes.  The direct map is handled by the ordinary
+ * record-family migration; this traversal covers the immutable embedded
+ * snapshots which the strict validators also treat as ManagedWorkspace.
+ */
+function visitEmbeddedManagedWorkspaces(snapshot, visit) {
+    if (snapshot.state === null)
+        return snapshot;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const nextTask = { ...task };
+        if (task.managedWorkspaces !== undefined) {
+            const workspaces = asObject(task.managedWorkspaces, `managedWorkspace map ${taskId}`);
+            nextTask.managedWorkspaces = Object.fromEntries(Object.entries(workspaces).map(([recordId, rawWorkspace]) => [
+                recordId,
+                visit(asObject(rawWorkspace, `managedWorkspace ${taskId}/${recordId}`), `managedWorkspace ${taskId}/${recordId}`)
+            ]));
+        }
+        if (task.workItems !== undefined) {
+            const workItems = asObject(task.workItems, `workItem map ${taskId}`);
+            nextTask.workItems = Object.fromEntries(Object.entries(workItems).map(([workItemId, rawWorkItem]) => {
+                const workItem = asObject(rawWorkItem, `workItem ${taskId}/${workItemId}`);
+                if (workItem.candidates === undefined)
+                    return [workItemId, { ...workItem }];
+                if (!Array.isArray(workItem.candidates)) {
+                    throw new Error(`workItem ${taskId}/${workItemId} candidates must be an array.`);
+                }
+                return [workItemId, {
+                        ...workItem,
+                        candidates: workItem.candidates.map((rawCandidate, index) => {
+                            const candidate = asObject(rawCandidate, `Candidate ${taskId}/${workItemId}/${index}`);
+                            return migrateOptionalManagedWorkspace(candidate, `Candidate ${taskId}/${workItemId}/${index}`, visit);
+                        })
+                    }];
+            }));
+        }
+        for (const mapKey of ["agentRuns", "reviewRounds"]) {
+            if (task[mapKey] === undefined)
+                continue;
+            const records = asObject(task[mapKey], `${mapKey} map ${taskId}`);
+            nextTask[mapKey] = Object.fromEntries(Object.entries(records).map(([recordId, rawRecord]) => [
+                recordId,
+                migrateOptionalManagedWorkspace(asObject(rawRecord, `${mapKey} ${taskId}/${recordId}`), `${mapKey} ${taskId}/${recordId}`, visit)
+            ]));
+        }
+        nextTasks[taskId] = nextTask;
+    }
+    return {
+        schemaManifest: snapshot.schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
+function migrateOptionalManagedWorkspace(record, label, visit) {
+    if (record.workspace === undefined)
+        return { ...record };
+    return {
+        ...record,
+        workspace: visit(asObject(record.workspace, `${label} workspace`), `${label} workspace`)
+    };
+}
+function requireManagedWorkspaceVersion(workspace, version, label) {
+    if (workspace.schemaVersion !== version) {
+        throw new Error(`${label} must use schemaVersion ${version}.`);
+    }
+}
+function migrateWorkItemExecutionGroupHistory(snapshot) {
+    requireRecordFamilyVersion(snapshot, "workItem", WORK_ITEM_GROUP_HISTORY_FROM_VERSION, "workItems");
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...manifestVersions, workItem: WORK_ITEM_GROUP_HISTORY_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        if (task.workItems === undefined) {
+            nextTasks[taskId] = { ...task };
+            continue;
+        }
+        const workItems = asObject(task.workItems, `workItem map ${taskId}`);
+        const nextWorkItems = {};
+        for (const [recordId, rawRecord] of Object.entries(workItems)) {
+            const record = asObject(rawRecord, `workItem ${taskId}/${recordId}`);
+            const { executionGroup, ...rest } = record;
+            if (executionGroup !== undefined
+                && (executionGroup === null || typeof executionGroup !== "object" || Array.isArray(executionGroup))) {
+                throw new Error(`workItem ${taskId}/${recordId} executionGroup must be an object.`);
+            }
+            const groupId = executionGroup === undefined
+                ? undefined
+                : asObject(executionGroup, `ExecutionGroup ${taskId}/${recordId}`).id;
+            if (groupId !== undefined && (typeof groupId !== "string" || groupId.trim().length === 0)) {
+                throw new Error(`workItem ${taskId}/${recordId} executionGroup id is invalid.`);
+            }
+            nextWorkItems[recordId] = {
+                ...rest,
+                schemaVersion: WORK_ITEM_GROUP_HISTORY_TO_VERSION,
+                executionGroups: executionGroup === undefined ? [] : [executionGroup],
+                ...(groupId === undefined ? {} : { currentExecutionGroupId: groupId })
+            };
+        }
+        nextTasks[taskId] = { ...task, workItems: nextWorkItems };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
+/**
+ * Move the legacy `lane:<group>:<lane>` keys into a namespace that cannot be
+ * mistaken for a legal Role identity.  A legacy key is only rewritten when
+ * its pointed Run proves the lane lineage; otherwise a legal Role with that
+ * exact name is retained.  Ambiguous or malformed lane-looking records fail
+ * closed instead of guessing which active Run the old bytes meant.
+ */
+function activeRunPointerNamespaceStep() {
+    return {
+        axis: "record",
+        recordKind: "activeRunPointer",
+        fromVersion: ACTIVE_RUN_POINTER_NAMESPACE_FROM_VERSION,
+        toVersion: ACTIVE_RUN_POINTER_NAMESPACE_TO_VERSION,
+        preconditions: (snapshot) => requireActiveRunPointerNamespaceVersion(snapshot),
+        transform: (snapshot) => migrateActiveRunPointerNamespace(snapshot),
+        declaredEffects: []
+    };
+}
+function requireActiveRunPointerNamespaceVersion(snapshot) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (manifestVersions.activeRunPointer !== ACTIVE_RUN_POINTER_NAMESPACE_FROM_VERSION) {
+        throw new Error(`Record activeRunPointer migration requires manifest version ${ACTIVE_RUN_POINTER_NAMESPACE_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const activeRuns = task.activeRuns;
+        if (activeRuns === undefined)
+            continue;
+        const pointers = asObject(activeRuns, `activeRunPointer map ${taskId}`);
+        for (const [key, rawPointer] of Object.entries(pointers)) {
+            const pointer = asObject(rawPointer, `Active run ${taskId}/${key}`);
+            if (pointer.schemaVersion !== ACTIVE_RUN_POINTER_NAMESPACE_FROM_VERSION) {
+                throw new Error(`Active run ${taskId}/${key} must use schemaVersion ${ACTIVE_RUN_POINTER_NAMESPACE_FROM_VERSION}.`);
+            }
+            if (typeof pointer.runId !== "string" || pointer.runId.trim().length === 0) {
+                throw new Error(`Active run ${taskId}/${key} has an invalid runId.`);
+            }
+        }
+    }
+}
+function migrateActiveRunPointerNamespace(snapshot) {
+    requireActiveRunPointerNamespaceVersion(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...manifestVersions,
+            activeRunPointer: ACTIVE_RUN_POINTER_NAMESPACE_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const rawActiveRuns = task.activeRuns;
+        if (rawActiveRuns === undefined) {
+            nextTasks[taskId] = { ...task };
+            continue;
+        }
+        const activeRuns = asObject(rawActiveRuns, `activeRunPointer map ${taskId}`);
+        const rawAgentRuns = asObject(task.agentRuns, `agentRun map ${taskId}`);
+        const nextActiveRuns = {};
+        for (const [key, rawPointer] of Object.entries(activeRuns)) {
+            const pointer = asObject(rawPointer, `Active run ${taskId}/${key}`);
+            const runId = typeof pointer.runId === "string" ? pointer.runId : "";
+            const run = asObject(rawAgentRuns[runId], `Agent run ${taskId}/${runId}`);
+            const lane = legacyLaneKeyParts(key);
+            const migratedPointer = {
+                ...pointer,
+                schemaVersion: ACTIVE_RUN_POINTER_NAMESPACE_TO_VERSION
+            };
+            const addPointer = (nextKey) => {
+                if (nextActiveRuns[nextKey] !== undefined) {
+                    throw new Error(`Active run pointer key collides after migration: ${taskId}/${nextKey}.`);
+                }
+                nextActiveRuns[nextKey] = migratedPointer;
+            };
+            if (lane !== null) {
+                const laneBacked = run.executionGroupId === lane.executionGroupId
+                    && run.executionLaneId === lane.executionLaneId;
+                // The prior writer used the same map key for a legal Role and a Lane
+                // when the Role itself happened to contain the `lane:g:l` shape.  The
+                // v3 namespace must retain both identities instead of rejecting the
+                // record or silently dropping the Role pointer.
+                const roleBacked = run.roleName === key;
+                if (!laneBacked && !roleBacked) {
+                    throw new Error(`Active run pointer lineage is invalid: ${taskId}/${key}.`);
+                }
+                if (roleBacked)
+                    addPointer(key);
+                if (laneBacked) {
+                    addPointer(executionLaneNamespaceKey(lane.executionGroupId, lane.executionLaneId));
+                }
+            }
+            else if (key.startsWith("lane:")) {
+                // A malformed lane-looking key is allowed only when it is a legal
+                // legacy Role pointer. It must not be silently reinterpreted.
+                if (run.roleName !== key) {
+                    throw new Error(`Active run pointer key is malformed: ${taskId}/${key}.`);
+                }
+                addPointer(key);
+            }
+            else {
+                // Role pointers remain keyed by the Role even when the pointed Run
+                // also carries execution lineage (a shape emitted by the prior
+                // writer).  The lane namespace above preserves that second identity.
+                if (run.roleName !== key) {
+                    throw new Error(`Active run Role pointer is invalid: ${taskId}/${key}.`);
+                }
+                addPointer(key);
+            }
+        }
+        nextTasks[taskId] = { ...task, activeRuns: nextActiveRuns };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
+function legacyLaneKeyParts(key) {
+    const match = /^lane:([^:]+):([^:]+)$/u.exec(key);
+    if (match === null)
+        return null;
+    return { executionGroupId: match[1], executionLaneId: match[2] };
+}
+function executionLaneNamespaceKey(executionGroupId, executionLaneId) {
+    return `/execution-lane/${encodeLaneKeyPart(executionGroupId)}:${encodeLaneKeyPart(executionLaneId)}`;
+}
+function encodeLaneKeyPart(value) {
+    return encodeURIComponent(value).replace(/:/gu, "%3A");
+}
+/**
+ * Upgrade one nested Task record family without guessing fields or repairing
+ * malformed state. The new execution lineage fields are optional, so legal
+ * old single-lane records retain their direct shape; the next dispatch creates
+ * the unified one-lane Group explicitly. The version transition is still
+ * durable and centralized, which keeps old Homes out of the strict current
+ * parser until this step has run.
+ */
+function recordFamilyStep(recordKind, fromVersion, toVersion, taskMapKey) {
+    return {
+        axis: "record",
+        recordKind,
+        fromVersion,
+        toVersion,
+        preconditions: (snapshot) => requireRecordFamilyVersion(snapshot, recordKind, fromVersion, taskMapKey),
+        transform: (snapshot) => migrateRecordFamily(snapshot, recordKind, fromVersion, toVersion, taskMapKey),
+        declaredEffects: []
+    };
+}
+/**
+ * The snapshot boundary is nested inside WorkItem/ReviewRound ExecutionGroup
+ * results.  The parent record versions make that persisted shape explicit;
+ * this adjacent step intentionally performs no field rewrite, preserving old
+ * records while preventing a pre-v8/pre-v4 Home from entering the strict
+ * current parser without the declared transition.
+ */
+function requireRecordFamilyVersion(snapshot, recordKind, fromVersion, taskMapKey) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (manifestVersions[recordKind] !== fromVersion) {
+        throw new Error(`Record ${recordKind} migration requires manifest version ${fromVersion}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const records = task[taskMapKey];
+        if (records === undefined)
+            continue;
+        const map = asObject(records, `${recordKind} map ${taskId}`);
+        for (const [recordId, rawRecord] of Object.entries(map)) {
+            const record = asObject(rawRecord, `${recordKind} ${taskId}/${recordId}`);
+            if (record.schemaVersion !== fromVersion) {
+                throw new Error(`Record ${recordKind} ${taskId}/${recordId} must use schemaVersion ${fromVersion}.`);
+            }
+        }
+    }
+}
+function migrateRecordFamily(snapshot, recordKind, fromVersion, toVersion, taskMapKey) {
+    // Keep the same source-shape checks in the transform so a direct caller
+    // cannot bypass the migration's precondition contract.
+    requireRecordFamilyVersion(snapshot, recordKind, fromVersion, taskMapKey);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...manifestVersions,
+            [recordKind]: toVersion
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const records = task[taskMapKey];
+        if (records === undefined) {
+            nextTasks[taskId] = { ...task };
+            continue;
+        }
+        const map = asObject(records, `${recordKind} map ${taskId}`);
+        const nextMap = {};
+        for (const [recordId, rawRecord] of Object.entries(map)) {
+            nextMap[recordId] = {
+                ...asObject(rawRecord, `${recordKind} ${taskId}/${recordId}`),
+                schemaVersion: toVersion
+            };
+        }
+        nextTasks[taskId] = { ...task, [taskMapKey]: nextMap };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
+function asObject(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+/** Historical public spelling retained as an alias to the single graph. */
+export const createProductionRegistry = createProductionStorageRegistry;
+/** Advance the aggregate identity after proving manifest/root agreement at v16. */
+function migrateAggregateV16ToV17(snapshot) {
+    return {
+        schemaManifest: {
+            ...snapshot.schemaManifest,
+            aggregateSchemaVersion: FINAL_REVIEW_AGGREGATE_TO_VERSION
+        },
+        state: snapshot.state === null
+            ? null
+            : {
+                ...snapshot.state,
+                schemaVersion: FINAL_REVIEW_AGGREGATE_TO_VERSION
+            }
+    };
+}
+function requireAggregateV16Snapshot(snapshot) {
+    if (snapshot.schemaManifest.aggregateSchemaVersion
+        !== FINAL_REVIEW_AGGREGATE_FROM_VERSION) {
+        throw new Error("Aggregate 16->17 migration requires schema.json aggregateSchemaVersion 16.");
+    }
+    if (snapshot.state !== null
+        && snapshot.state.schemaVersion !== FINAL_REVIEW_AGGREGATE_FROM_VERSION) {
+        throw new Error("Aggregate 16->17 migration requires state.json schemaVersion 16 to match schema.json.");
+    }
+}
+/**
+ * A version bump is deliverable only when the shared planner resolves the full
+ * adjacent path. This also covers target-only record families as explicit 0->1
+ * introductions and rejects offline declarations without executable steps.
+ */
+export function assertRegistryCoversBaselineToCurrent(registry, baseline = baselineStorageVersionState(), current = latestStorageVersionState()) {
+    const plan = planMigration(registry, baseline, current);
+    if (plan.kind !== "blocked")
+        return;
+    const coordinate = plan.blocker.axis === "record"
+        ? `record/${plan.blocker.recordKind ?? "?"}`
+        : plan.blocker.axis;
+    throw new Error(`Storage migration delivery gate failed for ${coordinate}: ${plan.blocker.message}`);
+}

package/dist/storage/migration/registry.js

@@ -0,0 +1,169 @@
+/**
+ * The central migration registry.
+ *
+ * Declarations and offline transforms are discoverable strictly by
+ * `axis + (recordKind) + fromVersion`. There is no version-magnitude or semver
+ * guessing: only an explicitly declared chain of adjacent transitions is
+ * usable. A fresh registry is EMPTY, so every older version fails closed until
+ * its compatible normalization or offline migration is authored explicitly.
+ */
+export class MigrationRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MigrationRegistryError";
+    }
+}
+/**
+ * Explicit key-field delimiter: the ASCII Unit Separator (U+001F), built with
+ * `String.fromCharCode` so this source file stays pure printable ASCII (no raw
+ * control byte embedded in the text). The Unit Separator never appears in an
+ * `axis` literal, a `recordKind`, or a decimal version, so the three key fields
+ * cannot run together and the composite key is unambiguous.
+ */
+const KEY_SEPARATOR = String.fromCharCode(0x1f);
+/**
+ * Composite lookup key. The record axis includes its `recordKind`; the layout
+ * and aggregate axes use a fixed sentinel so a single map serves all axes.
+ */
+function stepKey(axis, recordKind, fromVersion) {
+    const family = axis === "record" ? requireRecordKind(recordKind) : "-";
+    return `${axis}${KEY_SEPARATOR}${family}${KEY_SEPARATOR}${fromVersion}`;
+}
+function requireRecordKind(recordKind) {
+    if (typeof recordKind !== "string" || recordKind.trim().length === 0) {
+        throw new MigrationRegistryError("A record-axis migration step must declare a non-empty recordKind.");
+    }
+    return recordKind;
+}
+/**
+ * A discoverable set of adjacent migration steps. Register at most one step per
+ * `(axis, recordKind, fromVersion)`; lookup returns only that exact adjacent
+ * step (or `undefined`) — it never infers a step from version ordering.
+ */
+export class MigrationRegistry {
+    #steps = new Map();
+    #declarations = new Map();
+    /** Backward-compatible spelling: explicitly registers one offline transition and its transform. */
+    register(step) {
+        this.#validateMigrationStep(step);
+        const key = stepKey(step.axis, step.recordKind, step.fromVersion);
+        this.#assertDeclarationAvailable(step, key);
+        this.#assertStepAvailable(step, key);
+        // Publish the declaration and transform together only after every check has
+        // passed. A rejected combined registration must not leave a newly-runnable
+        // half update behind in the registry.
+        this.#declarations.set(key, { ...step, kind: "offline-migration" });
+        this.#steps.set(key, step);
+        return this;
+    }
+    /** Explicitly register the declaration and transform for an offline change. */
+    registerOfflineMigration(step) {
+        return this.register(step);
+    }
+    /** Declare an offline change. A missing transform remains fail-closed. */
+    declareOfflineMigration(declaration) {
+        this.#validateCoordinates(declaration);
+        this.#registerDeclaration({ ...declaration, kind: "offline-migration" });
+        return this;
+    }
+    /** Declare an online-compatible normalization with deterministic defaults. */
+    registerCompatible(step) {
+        const runtimeAxis = step.axis;
+        if (runtimeAxis !== "record") {
+            throw new MigrationRegistryError("A compatible transition must use the record axis; layout and aggregate changes require offline migration.");
+        }
+        this.#validateCoordinates(step);
+        if (!Array.isArray(step.defaults)
+            || step.defaults.length === 0
+            || step.defaults.some((value) => typeof value !== "string" || value.trim().length === 0)) {
+            throw new MigrationRegistryError("A compatible transition must declare at least one deterministic default or rebuild rule.");
+        }
+        if (typeof step.normalize !== "function" || typeof step.validateSource !== "function") {
+            throw new MigrationRegistryError("A compatible transition must provide a strict source validator and normalizer.");
+        }
+        this.#registerDeclaration({ ...step, kind: "compatible" });
+        return this;
+    }
+    /** Register a transform without inferring its operational declaration. */
+    registerMigrationStep(step) {
+        this.#validateMigrationStep(step);
+        const key = stepKey(step.axis, step.recordKind, step.fromVersion);
+        this.#assertStepAvailable(step, key);
+        this.#steps.set(key, step);
+        return this;
+    }
+    #validateMigrationStep(step) {
+        this.#validateCoordinates(step);
+        if (!Array.isArray(step.declaredEffects)
+            || typeof step.transform !== "function"
+            || typeof step.preconditions !== "function") {
+            throw new MigrationRegistryError("A migration step must provide its transform contract.");
+        }
+    }
+    #assertStepAvailable(step, key) {
+        if (!this.#steps.has(key))
+            return;
+        throw new MigrationRegistryError(`A migration step is already registered for ${step.axis}` +
+            `${step.recordKind ? `/${step.recordKind}` : ""} ${step.fromVersion}->${step.toVersion}.`);
+    }
+    #assertDeclarationAvailable(declaration, key) {
+        if (!this.#declarations.has(key))
+            return;
+        throw new MigrationRegistryError(`A transition is already registered for ${declaration.axis}` +
+            `${declaration.recordKind ? `/${declaration.recordKind}` : ""} ` +
+            `${declaration.fromVersion}->${declaration.toVersion}.`);
+    }
+    #validateCoordinates(step) {
+        if (step.axis === "record") {
+            requireRecordKind(step.recordKind);
+        }
+        else if (step.recordKind !== undefined) {
+            throw new MigrationRegistryError(`A ${step.axis}-axis transition must not declare a recordKind.`);
+        }
+        if (!Number.isSafeInteger(step.fromVersion) || step.fromVersion < 0) {
+            throw new MigrationRegistryError(`Transition fromVersion must be a non-negative integer: ${String(step.fromVersion)}.`);
+        }
+        if (step.fromVersion === 0) {
+            if (step.axis !== "record" || step.introduction !== true || step.toVersion !== 1) {
+                throw new MigrationRegistryError("Only an explicit record-family introduction may use the 0->1 transition.");
+            }
+        }
+        else if (step.introduction === true) {
+            throw new MigrationRegistryError("A record-family introduction must be the explicit 0->1 transition.");
+        }
+        if (step.toVersion !== step.fromVersion + 1) {
+            throw new MigrationRegistryError(`Transitions must be adjacent and one-directional: ${step.axis}` +
+                `${step.recordKind ? `/${step.recordKind}` : ""} ${step.fromVersion}->${step.toVersion} ` +
+                `(expected ${step.fromVersion}->${step.fromVersion + 1}).`);
+        }
+    }
+    #registerDeclaration(declaration) {
+        const key = stepKey(declaration.axis, declaration.recordKind, declaration.fromVersion);
+        this.#assertDeclarationAvailable(declaration, key);
+        this.#declarations.set(key, declaration);
+    }
+    /** Look up the exact adjacent step advancing `fromVersion -> fromVersion + 1`. */
+    lookup(axis, recordKind, fromVersion) {
+        return this.#steps.get(stepKey(axis, recordKind, fromVersion));
+    }
+    /** Look up the exact compatible/offline declaration for one adjacent change. */
+    lookupDeclaration(axis, recordKind, fromVersion) {
+        return this.#declarations.get(stepKey(axis, recordKind, fromVersion));
+    }
+    /** Total number of declared adjacent transitions (0 for an EMPTY registry). */
+    get size() {
+        return this.#declarations.size;
+    }
+    /** True when neither declarations nor offline transforms are registered. */
+    isEmpty() {
+        return this.#declarations.size === 0 && this.#steps.size === 0;
+    }
+}
+/**
+ * Create a fresh, EMPTY registry for isolated planning or callers that
+ * authorize no transitions. Production wiring builds its explicit graph in a
+ * separate factory.
+ */
+export function createEmptyRegistry() {
+    return new MigrationRegistry();
+}