@zq-silk/yui 0.13.9 → 0.14.0

package/dist/storage/migration/engine.js

@@ -1,147 +0,0 @@
-/**
- * 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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,154 +0,0 @@
-/**
- * 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";
-}