@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/migration/classifier.js

@@ -0,0 +1,51 @@
+/**
+ * The pure four-state compatibility classifier.
+ *
+ * Given the source and target (latest-supported) version states, an EMPTY-or-
+ * populated registry, and an optional caller-supplied corruption signal, it
+ * returns exactly one verdict:
+ *
+ * - `USABLE`            — every axis is already at the current version.
+ * - `COMPATIBLE`        — strictly older record axes whose complete adjacent
+ *   path consists only of compatible normalizations.
+ * - `MIGRATABLE`        — at least one adjacent hop requires offline migration,
+ *   and every axis has a complete deterministic path.
+ * - `NEEDS_NEW_VERSION` — any axis is newer than supported (`future-version`),
+ *   or older with a broken/absent step path (`missing-step`). Carries a precise
+ *   reason + action. Under an EMPTY registry, any strictly-older version lands
+ *   here via a missing transition contract.
+ * - `CORRUPTED`         — only when the caller reports real JSON/structural/
+ *   reference-invariant damage. The classifier never infers corruption from
+ *   version numbers.
+ *
+ * There are no baseline/pre-release special cases: compatibility is decided
+ * solely by explicit registry step-paths, never by version magnitude or semver.
+ */
+import { planMigration } from "./planner.js";
+/**
+ * Classify a storage target. Pure: no I/O, no mutation, deterministic.
+ *
+ * `corruption` is supplied by the caller when parsing/structural/reference
+ * validation has already failed; when present it takes precedence, because a
+ * corrupted target's version numbers cannot be trusted.
+ */
+export function classifyStorage(registry, source, target, corruption) {
+    if (corruption?.corrupted === true) {
+        return { verdict: "CORRUPTED", status: "unsupported", detail: corruption.detail };
+    }
+    const plan = planMigration(registry, source, target);
+    switch (plan.kind) {
+        case "no-op":
+            return { verdict: "USABLE", status: "current" };
+        case "runnable":
+            return plan.path === "compatible"
+                ? { verdict: "COMPATIBLE", status: "compatible-old", stepCount: plan.steps.length }
+                : { verdict: "MIGRATABLE", status: "migration-required", stepCount: plan.steps.length };
+        case "blocked":
+            return {
+                verdict: "NEEDS_NEW_VERSION",
+                status: "unsupported",
+                blocker: plan.blocker
+            };
+    }
+}

package/dist/storage/migration/compatibleCodec.js

@@ -0,0 +1,53 @@
+import { isDeepStrictEqual } from "node:util";
+import { planMigration } from "./planner.js";
+export class StorageCompatibilityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StorageCompatibilityError";
+    }
+}
+/**
+ * Apply an all-compatible declaration chain in memory. This never writes the
+ * source. It rejects offline paths, missing declarations/steps, non-fresh
+ * normalizers, and output which does not pass the strict current-model gate.
+ */
+export function loadCompatibleSnapshot(options) {
+    const plan = planMigration(options.registry, options.source, options.latest);
+    if (plan.kind === "blocked") {
+        throw new StorageCompatibilityError(plan.blocker.message);
+    }
+    if (plan.kind === "runnable" && plan.path !== "compatible") {
+        throw new StorageCompatibilityError("Storage requires an offline migration and cannot be normalized by the compatible loader.");
+    }
+    let current = options.snapshot;
+    if (plan.kind === "runnable") {
+        for (const planned of plan.steps) {
+            planned.step.preconditions(current);
+            const next = planned.step.transform(current);
+            if (next === current && typeof next === "object" && next !== null) {
+                throw new StorageCompatibilityError(`Compatible normalizer ${planned.axis}` +
+                    `${planned.recordKind ? `/${planned.recordKind}` : ""} ` +
+                    `${planned.fromVersion}->${planned.toVersion} returned its input object.`);
+            }
+            current = next;
+        }
+    }
+    assertCurrentVersions(options.inspectVersions(current), options.latest, "normalized model");
+    options.validateCurrent(current);
+    return current;
+}
+/**
+ * Encode only the current record contract. There is intentionally no old
+ * writer or dual-write branch: a non-current encoding fails before persistence.
+ */
+export function writeCurrentSnapshot(options) {
+    const snapshot = options.encode(options.model);
+    assertCurrentVersions(options.inspectVersions(snapshot), options.latest, "writer output");
+    options.validateCurrent(snapshot);
+    return snapshot;
+}
+function assertCurrentVersions(actual, latest, label) {
+    if (!isDeepStrictEqual(actual, latest)) {
+        throw new StorageCompatibilityError(`Compatible ${label} is not at the current storage versions; old-version writing is forbidden.`);
+    }
+}

package/dist/storage/migration/engine.js

@@ -0,0 +1,147 @@
+/**
+ * The transactional migration engine.
+ *
+ * The engine is parameterized over the abstract {@link MigrationTarget} and the
+ * `latest` supported {@link StorageVersionState}; it never touches a real Home
+ * and holds no domain list of derived-state fields. All domain knowledge lives
+ * behind the injected `rebuildDerivedState` / `validateCurrentState` boundary,
+ * and every step only *declares* its effects.
+ *
+ * Flow (execute mode):
+ *   inspect -> plan (reject on missing step) -> detectLiveRuntime (fail-closed
+ *   if active) -> read immutable source -> apply step transforms into a fresh
+ *   output -> rebuildDerivedState(effects) -> validateCurrentState() ->
+ *   atomicSwitchWithBackup -> structured MigrationReport.
+ *
+ * Dry-run mode runs the same pipeline through the validation gate, then discards
+ * the fresh output and never switches.
+ *
+ * Invariants: on any failure the source is never switched and stays byte-for-
+ * byte unchanged, and — because input is immutable and output is fresh — an
+ * interrupted run is safely retriable (delete partial output and re-run). Once
+ * the source already equals `latest`, the run is a no-op (`already-current`).
+ */
+import { planMigration } from "./planner.js";
+import { collectEffects, toStepSummary } from "./report.js";
+import { AmbiguousSwitchError } from "./types.js";
+/** Run the transactional migration and return a structured report. Never throws. */
+export function runMigration(options) {
+    const { registry, target, latest, mode } = options;
+    // 1) inspect — read-only.
+    const source = target.inspectVersions();
+    // 2) plan — a missing adjacent step or a future version fails closed here.
+    const plan = planMigration(registry, source, latest);
+    if (plan.kind === "blocked") {
+        return { outcome: "blocked", mode, source, target: latest, blocker: plan.blocker };
+    }
+    if (plan.kind === "no-op") {
+        return { outcome: "already-current", mode, source, target: latest };
+    }
+    const stepSummaries = plan.steps.map(toStepSummary);
+    const effects = collectEffects(plan.steps);
+    // 3) detectLiveRuntime — refuse to migrate a target a live runtime is holding.
+    const live = target.detectLiveRuntime();
+    if (live.active) {
+        return {
+            outcome: "active-runtime",
+            mode,
+            source,
+            target: latest,
+            steps: stepSummaries,
+            ...(live.detail ? { detail: live.detail } : {})
+        };
+    }
+    // 4) apply steps to a fresh output; the source is only ever read.
+    let stage = "precondition";
+    const applied = [];
+    try {
+        let snapshot = target.readSource();
+        for (const planned of plan.steps) {
+            stage = "precondition";
+            planned.step.preconditions(snapshot);
+            stage = "transform";
+            const next = planned.step.transform(snapshot);
+            assertFreshOutput(next, snapshot, planned);
+            snapshot = next;
+            applied.push(toStepSummary(planned));
+        }
+        stage = "write-fresh-output";
+        target.writeFreshOutput(snapshot);
+        // 5) injected canonical derived-state rebuild over the fresh output.
+        stage = "rebuild";
+        const derived = target.rebuildDerivedState(effects);
+        // 6) injected canonical validation gate (the real post-migration loader).
+        stage = "validate";
+        const validation = target.validateCurrentState();
+        if (mode === "dry-run") {
+            // Validate only; never switch. Discard the staged output.
+            target.discardFreshOutput();
+            return {
+                outcome: "dry-run",
+                mode: "dry-run",
+                source,
+                target: latest,
+                steps: stepSummaries,
+                effects,
+                derived,
+                validation
+            };
+        }
+        // 7) atomic switch with timestamped backup — the only write to the source.
+        stage = "switch";
+        const switched = target.atomicSwitchWithBackup();
+        return {
+            outcome: "migrated",
+            mode: "execute",
+            source,
+            target: latest,
+            steps: stepSummaries,
+            effects,
+            derived,
+            validation,
+            switch: switched
+        };
+    }
+    catch (error) {
+        // A partially-applied, ambiguous switch is NOT a clean "source unchanged"
+        // failure: the original was moved aside and could not be restored. Surface it
+        // as its own outcome so the orchestrator reports a truthful manual recovery
+        // instead of a false "unchanged" (P1-4).
+        if (error instanceof AmbiguousSwitchError) {
+            return {
+                outcome: "switch-ambiguous",
+                mode,
+                source,
+                target: latest,
+                steps: stepSummaries,
+                homePath: error.homePath,
+                backupPath: error.backupPath,
+                stagingPath: error.stagingPath,
+                error: error.message
+            };
+        }
+        return {
+            outcome: "failed",
+            mode,
+            source,
+            target: latest,
+            stage,
+            stepsApplied: applied,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+/**
+ * Defend the pure `immutable-input -> fresh-output` contract: a transform must
+ * return a value distinct from its input (never mutate-and-return the source).
+ */
+function assertFreshOutput(next, previous, planned) {
+    if (next === previous &&
+        typeof next === "object" &&
+        next !== null) {
+        throw new Error(`Migration step ${planned.axis}` +
+            `${planned.recordKind ? `/${planned.recordKind}` : ""} ` +
+            `${planned.fromVersion}->${planned.toVersion} returned its input object; ` +
+            "transforms must produce a fresh output.");
+    }
+}

package/dist/storage/migration/index.js

@@ -0,0 +1,33 @@
+/**
+ * Generic, pure storage-migration core.
+ *
+ * A future-facing, fully unit-testable migration framework over three
+ * independent monotonic version axes (layout / aggregate / record, where the
+ * record axis is a `recordKind -> {version, path}` map). The transactional engine
+ * is parameterized over an abstract {@link MigrationTarget}, so it neither
+ * touches a real Home nor hardcodes any domain derived-state list. Real wiring
+ * (the production step graph, canonical rebuild/validate boundary, and target)
+ * is injected elsewhere.
+ */
+import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storageVersions.js";
+export * from "./types.js";
+export { MigrationRegistry, MigrationRegistryError, createEmptyRegistry } from "./registry.js";
+export { planMigration } from "./planner.js";
+export { classifyStorage } from "./classifier.js";
+export { runMigration } from "./engine.js";
+export { collectEffects, describeReport, toStepSummary } from "./report.js";
+export { BASELINE_STORAGE_LAYOUT_VERSION, BASELINE_AGGREGATE_SCHEMA_VERSION, BASELINE_RECORD_VERSIONS, BASELINE_STORAGE_VERSION_STATE, baselineStorageVersionState, assertBaselineConsistency } from "./baseline.js";
+export { createProductionRegistry, createProductionStorageRegistry, assertRegistryCoversBaselineToCurrent } from "./productionRegistry.js";
+export { loadCompatibleSnapshot, writeCurrentSnapshot, StorageCompatibilityError } from "./compatibleCodec.js";
+/**
+ * The current baseline scalar versions, sourced from the single authoritative
+ * definitions in `storageSchema.ts` (never re-hardcoded here). Callers compose a
+ * full {@link StorageVersionState} by supplying the record-family map for the
+ * families they own — the generic core intentionally holds no record list.
+ */
+export function latestScalarVersions() {
+    return {
+        layout: CURRENT_STORAGE_LAYOUT_VERSION,
+        aggregate: CURRENT_AGGREGATE_SCHEMA_VERSION
+    };
+}

package/dist/storage/migration/planner.js

@@ -0,0 +1,154 @@
+/**
+ * The cross-axis migration path planner.
+ *
+ * Given the source and target (latest-supported) {@link StorageVersionState}s and
+ * a {@link MigrationRegistry}, it produces a deterministically-ordered plan or a
+ * precise fail-closed blocker. It performs no I/O and interprets no domain data.
+ *
+ * Deterministic order encodes the axis dependency: `layout -> aggregate ->
+ * record`. Record families are nested inside the aggregate, so their steps run
+ * after the aggregate reaches its target version; record kinds are visited in
+ * sorted order and each family's steps ascend by version. Any single missing
+ * adjacent step, or any axis whose source is newer than supported, fails closed.
+ */
+/**
+ * Plan the migration from `source` to `target`.
+ *
+ * Returns `no-op` when every axis is already current, `runnable` with a fully
+ * ordered adjacent step chain, or `blocked` with the first fail-closed reason in
+ * deterministic axis order (`layout`, then `aggregate`, then record kinds sorted).
+ */
+export function planMigration(registry, source, target) {
+    const ordered = [];
+    // 1) layout, then 2) aggregate — scalars migrate before any nested record.
+    for (const axis of ["layout", "aggregate"]) {
+        const chain = planScalarAxis(registry, axis, source[axis], target[axis]);
+        if (chain.kind === "blocked")
+            return { kind: "blocked", blocker: chain.blocker };
+        ordered.push(...chain.steps);
+    }
+    // 3) record families — nested inside the aggregate; visit target kinds in
+    // sorted order so the plan is deterministic. A target-only family starts at
+    // the explicit pre-introduction version 0 and therefore requires a registered
+    // `introduction` step. It is not an aggregate transform or an implicit
+    // no-op: the record family must pass the same fail-closed delivery gate as
+    // every later version transition.
+    const targetKinds = Object.keys(target.record).sort();
+    for (const recordKind of targetKinds) {
+        const sourceEntry = source.record[recordKind];
+        const chain = planRecordFamily(registry, recordKind, sourceEntry?.version ?? 0, target.record[recordKind].version);
+        if (chain.kind === "blocked")
+            return { kind: "blocked", blocker: chain.blocker };
+        ordered.push(...chain.steps);
+    }
+    return ordered.length === 0
+        ? { kind: "no-op" }
+        : {
+            kind: "runnable",
+            path: ordered.some(({ transition }) => transition === "offline-migration")
+                ? "offline-migration"
+                : "compatible",
+            steps: ordered
+        };
+}
+function planScalarAxis(registry, axis, from, to) {
+    return planChain(registry, axis, undefined, from, to);
+}
+function planRecordFamily(registry, recordKind, from, to) {
+    return planChain(registry, "record", recordKind, from, to);
+}
+/**
+ * Resolve the adjacent step chain that advances one axis from `from` to `to`.
+ * A source newer than supported is `future-version`; a gap with no registered
+ * adjacent step is `missing-step`. Both carry a precise reason and action.
+ */
+function planChain(registry, axis, recordKind, from, to) {
+    const label = axisLabel(axis, recordKind);
+    if (from > to) {
+        return {
+            kind: "blocked",
+            blocker: {
+                reason: "future-version",
+                axis,
+                ...(recordKind ? { recordKind } : {}),
+                found: from,
+                supported: to,
+                message: `${label} version ${from} is newer than this release supports (${to}).`,
+                action: "Upgrade to a newer Yui release that understands this version."
+            }
+        };
+    }
+    const steps = [];
+    for (let version = from; version < to; version += 1) {
+        const declaration = registry.lookupDeclaration(axis, recordKind, version);
+        const registeredStep = registry.lookup(axis, recordKind, version);
+        if (declaration === undefined && registeredStep !== undefined) {
+            return {
+                kind: "blocked",
+                blocker: {
+                    reason: "missing-declaration",
+                    axis,
+                    ...(recordKind ? { recordKind } : {}),
+                    from: version,
+                    to: version + 1,
+                    message: `No compatible/offline-migration declaration is registered for ` +
+                        `${label} ${version}->${version + 1}.`,
+                    action: "Declare the adjacent change explicitly; do not infer compatibility from its version."
+                }
+            };
+        }
+        if (declaration === undefined) {
+            return {
+                kind: "blocked",
+                blocker: {
+                    reason: "missing-step",
+                    axis,
+                    ...(recordKind ? { recordKind } : {}),
+                    from: version,
+                    to: version + 1,
+                    message: `No migration step is registered for ${label} ${version}->${version + 1}.`,
+                    action: "This version cannot be migrated by this release; a newer release must provide the step."
+                }
+            };
+        }
+        const step = declaration.kind === "compatible"
+            ? {
+                axis,
+                ...(recordKind ? { recordKind } : {}),
+                fromVersion: version,
+                toVersion: version + 1,
+                preconditions: declaration.validateSource,
+                transform: declaration.normalize,
+                declaredEffects: []
+            }
+            : registeredStep;
+        if (step === undefined) {
+            return {
+                kind: "blocked",
+                blocker: {
+                    reason: "missing-step",
+                    axis,
+                    ...(recordKind ? { recordKind } : {}),
+                    from: version,
+                    to: version + 1,
+                    message: `No migration step is registered for ${label} ${version}->${version + 1}.`,
+                    action: "This offline transition cannot run until this release provides its migration step."
+                }
+            };
+        }
+        steps.push({
+            axis,
+            ...(recordKind ? { recordKind } : {}),
+            fromVersion: version,
+            toVersion: version + 1,
+            transition: declaration.kind,
+            step
+        });
+    }
+    return { kind: "ok", steps };
+}
+function axisLabel(axis, recordKind) {
+    if (axis === "record")
+        return `record family '${recordKind ?? "?"}'`;
+    return axis === "layout" ? "storage layout" : "aggregate schema";
+}