@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/migration/report.js

@@ -0,0 +1,54 @@
+/**
+ * Pure helpers for building and describing {@link MigrationReport}s.
+ *
+ * These never perform I/O and never interpret domain data — they only shape the
+ * structured evidence the engine emits.
+ */
+/** Reduce a planned step to the concise summary carried in reports. */
+export function toStepSummary(planned) {
+    return {
+        axis: planned.axis,
+        ...(planned.recordKind ? { recordKind: planned.recordKind } : {}),
+        fromVersion: planned.fromVersion,
+        toVersion: planned.toVersion,
+        transition: planned.transition,
+        declaredEffects: planned.step.declaredEffects
+    };
+}
+/**
+ * The de-duplicated union of every planned step's declared effects, in
+ * first-seen deterministic order. This is exactly what the engine forwards to
+ * the injected `rebuildDerivedState` — the generic core keeps no domain list.
+ */
+export function collectEffects(steps) {
+    const seen = new Set();
+    const effects = [];
+    for (const planned of steps) {
+        for (const effect of planned.step.declaredEffects) {
+            if (!seen.has(effect)) {
+                seen.add(effect);
+                effects.push(effect);
+            }
+        }
+    }
+    return effects;
+}
+/** A short, human-readable one-line description of a report outcome. */
+export function describeReport(report) {
+    switch (report.outcome) {
+        case "already-current":
+            return "Storage is already at the current version; nothing to migrate.";
+        case "blocked":
+            return `Migration blocked (${report.blocker.reason}): ${report.blocker.message} ${report.blocker.action}`;
+        case "active-runtime":
+            return `Migration refused: a live runtime is active${report.detail ? ` (${report.detail})` : ""}.`;
+        case "dry-run":
+            return `Dry run validated ${report.steps.length} step(s); fresh output discarded, source unchanged.`;
+        case "migrated":
+            return `Migrated through ${report.steps.length} step(s); source backed up at ${report.switch.backupPath ?? "(unspecified)"}.`;
+        case "failed":
+            return `Migration failed at ${report.stage}: ${report.error} Source is unchanged; delete any partial output and retry.`;
+        case "switch-ambiguous":
+            return `Migration switch is AMBIGUOUS: ${report.error} Recover from the backup at ${report.backupPath}.`;
+    }
+}

package/dist/storage/migration/types.js

@@ -0,0 +1,31 @@
+/**
+ * Generic, pure migration-core vocabulary.
+ *
+ * This module is deliberately domain-agnostic: it knows about three independent
+ * monotonic version axes and how to chain adjacent steps, but it never encodes a
+ * list of concrete Yui records, derived-state fields, or reference invariants.
+ * Those live behind the injected {@link MigrationTarget} boundary so a new record
+ * family can be added without editing the generic engine.
+ */
+/**
+ * Thrown by a target's `atomicSwitchWithBackup` when the switch is left in a
+ * partially-applied, ambiguous state (the original was moved aside but the
+ * promotion and its rollback both failed). It carries the exact recovery path so
+ * the orchestrator can report a truthful, actionable manual recovery rather than
+ * a false "the Home is unchanged".
+ */
+export class AmbiguousSwitchError extends Error {
+    /** The logical Home path that is now partially switched. */
+    homePath;
+    /** Where the original Home currently lives (the recovery source). */
+    backupPath;
+    /** The staged output that was not promoted. */
+    stagingPath;
+    constructor(options) {
+        super(options.detail);
+        this.name = "AmbiguousSwitchError";
+        this.homePath = options.homePath;
+        this.backupPath = options.backupPath;
+        this.stagingPath = options.stagingPath;
+    }
+}

package/dist/storage/storageSchema.js

@@ -1,20 +1,10 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeTextFileAtomically } from "./durableFile.js";
-/** Version of the on-disk layout (`schema.json`, root `state.json`, and locks). */
-export const CURRENT_STORAGE_LAYOUT_VERSION = 5;
-/** Version of the authoritative aggregate stored in `state.json`. */
-export const CURRENT_AGGREGATE_SCHEMA_VERSION = 1;
-/** @deprecated Use CURRENT_STORAGE_LAYOUT_VERSION for new code. */
-export const CURRENT_STORAGE_SCHEMA_VERSION = CURRENT_STORAGE_LAYOUT_VERSION;
+import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "./storageVersions.js";
+import { currentRecordVersions } from "./upgrade/recordVersions.js";
+export { CURRENT_STORAGE_LAYOUT_VERSION, CURRENT_AGGREGATE_SCHEMA_VERSION };
 export const STORAGE_SCHEMA_FILE = "schema.json";
-/**
- * The dispatcher is intentionally present from the first v5 release. There
- * are no v4-to-v5 migrations: v5 is a fresh authoritative storage contract.
- */
-export const STORAGE_MIGRATIONS = Object.freeze([]);
-/** No historical aggregate is supported by this development release yet. */
-export const AGGREGATE_MIGRATIONS = Object.freeze([]);
 export class StorageSchemaError extends Error {
     code;
     constructor(code, message, options) {
@@ -35,65 +25,113 @@ export function inspectStorageSchema(rootDir) {
             manifestPath
         };
     }
+    let manifest;
     try {
-        const manifest = parseStorageManifest(raw);
-        if (manifest.storageVersion !== CURRENT_STORAGE_LAYOUT_VERSION) {
+        manifest = parseStorageManifest(raw);
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            manifestPath,
+            detail: error instanceof Error ? error.message : String(error)
+        };
+    }
+    if (manifest.storageVersion !== CURRENT_STORAGE_LAYOUT_VERSION) {
+        return {
+            status: "unsupported",
+            incompatibleComponent: "layout",
+            direction: manifest.storageVersion < CURRENT_STORAGE_LAYOUT_VERSION ? "older" : "newer",
+            currentVersion: manifest.storageVersion,
+            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            currentLayoutVersion: manifest.storageVersion,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            manifestPath
+        };
+    }
+    if (manifest.aggregateSchemaVersion !== CURRENT_AGGREGATE_SCHEMA_VERSION) {
+        return {
+            status: "unsupported",
+            incompatibleComponent: "aggregate",
+            direction: manifest.aggregateSchemaVersion < CURRENT_AGGREGATE_SCHEMA_VERSION
+                ? "older"
+                : "newer",
+            currentVersion: manifest.aggregateSchemaVersion,
+            latestVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            currentLayoutVersion: manifest.storageVersion,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            manifestPath
+        };
+    }
+    const currentRecords = currentRecordVersions();
+    if (manifest.recordVersions === undefined) {
+        return {
+            status: "unsupported",
+            incompatibleComponent: "record",
+            direction: "older",
+            currentVersion: 0,
+            latestVersion: 1,
+            currentLayoutVersion: manifest.storageVersion,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            manifestPath
+        };
+    }
+    for (const [kind, currentEntry] of Object.entries(currentRecords)) {
+        const persisted = manifest.recordVersions[kind];
+        if (persisted === undefined) {
             return {
                 status: "unsupported",
-                incompatibleComponent: "layout",
-                direction: manifest.storageVersion < CURRENT_STORAGE_LAYOUT_VERSION ? "older" : "newer",
-                currentVersion: manifest.storageVersion,
-                latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+                incompatibleComponent: "record",
+                direction: "older",
+                currentVersion: 0,
+                latestVersion: currentEntry.version,
                 currentLayoutVersion: manifest.storageVersion,
                 latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
                 currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
                 latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+                recordFamily: kind,
                 manifestPath
             };
         }
-        if (manifest.aggregateSchemaVersion !== CURRENT_AGGREGATE_SCHEMA_VERSION) {
+        if (persisted !== currentEntry.version) {
             return {
                 status: "unsupported",
-                incompatibleComponent: "aggregate",
-                direction: manifest.aggregateSchemaVersion < CURRENT_AGGREGATE_SCHEMA_VERSION
-                    ? "older"
-                    : "newer",
-                currentVersion: manifest.aggregateSchemaVersion,
-                latestVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+                incompatibleComponent: "record",
+                direction: persisted < currentEntry.version ? "older" : "newer",
+                currentVersion: persisted,
+                latestVersion: currentEntry.version,
                 currentLayoutVersion: manifest.storageVersion,
                 latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
                 currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
                 latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+                recordFamily: kind,
                 manifestPath
             };
         }
-        return {
-            status: "current",
-            currentVersion: manifest.storageVersion,
-            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-            currentLayoutVersion: manifest.storageVersion,
-            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-            currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
-            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
-            activeGeneration: manifest.activeGeneration,
-            manifestPath
-        };
-    }
-    catch (error) {
-        return {
-            status: "invalid",
-            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
-            manifestPath,
-            detail: error instanceof Error ? error.message : String(error)
-        };
     }
+    return {
+        status: "current",
+        currentVersion: manifest.storageVersion,
+        latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+        currentLayoutVersion: manifest.storageVersion,
+        latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+        currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+        latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+        manifestPath
+    };
 }
 export function ensureStorageSchema(rootDir, now = new Date()) {
     const state = inspectStorageSchema(rootDir);
     if (state.status === "uninitialized") {
-        writeStorageManifest(rootDir, now);
+        writeCurrentStorageManifest(rootDir, now);
         return;
     }
     requireInspectedSchema(state);
@@ -101,70 +139,31 @@ export function ensureStorageSchema(rootDir, now = new Date()) {
 export function requireStorageSchema(rootDir) {
     requireInspectedSchema(inspectStorageSchema(rootDir));
 }
-export function dispatchStorageMigrations(rootDir, fromVersion, targetVersion = CURRENT_STORAGE_LAYOUT_VERSION, migrations = STORAGE_MIGRATIONS) {
-    assertLayoutVersion(fromVersion, "Migration source");
-    assertLayoutVersion(targetVersion, "Migration target");
-    if (fromVersion > targetVersion) {
-        throw unsupportedVersion(fromVersion, targetVersion, "layout");
-    }
-    // Build and validate the complete plan before invoking any filesystem mutation.
-    const bySource = new Map();
-    for (const migration of migrations) {
-        assertLayoutVersion(migration.fromVersion, "Migration fromVersion");
-        assertLayoutVersion(migration.toVersion, "Migration toVersion");
-        if (migration.toVersion !== migration.fromVersion + 1) {
-            throw invalidMigration(`Migration ${migration.fromVersion}->${migration.toVersion} must advance exactly one layout version.`);
-        }
-        if (bySource.has(migration.fromVersion)) {
-            throw invalidMigration(`Duplicate migration from layout version ${migration.fromVersion}.`);
-        }
-        bySource.set(migration.fromVersion, migration);
-    }
-    const plan = [];
-    for (let current = fromVersion; current < targetVersion; current += 1) {
-        const migration = bySource.get(current);
-        if (migration === undefined || migration.toVersion !== current + 1) {
-            throw unsupportedVersion(current, targetVersion, "layout");
-        }
-        plan.push(migration);
-    }
-    for (const migration of plan)
-        migration.migrate(rootDir);
+/**
+ * Compatible readers may bypass only a record-axis mismatch. Layout,
+ * aggregate, syntax, and initialization remain strict.
+ */
+export function requireCompatibleStorageSchema(rootDir) {
+    const state = inspectStorageSchema(rootDir);
+    if (state.status === "current")
+        return;
+    if (state.status === "unsupported"
+        && state.incompatibleComponent === "record"
+        && state.direction === "older")
+        return;
+    requireInspectedSchema(state);
 }
-export function dispatchAggregateMigrations(state, fromVersion, targetVersion = CURRENT_AGGREGATE_SCHEMA_VERSION, migrations = AGGREGATE_MIGRATIONS) {
-    assertLayoutVersion(fromVersion, "Aggregate migration source");
-    assertLayoutVersion(targetVersion, "Aggregate migration target");
-    if (fromVersion > targetVersion) {
-        throw unsupportedVersion(fromVersion, targetVersion, "aggregate");
+/** Persist the current three-axis manifest through the existing atomic-file seam. */
+export function writeCurrentStorageManifest(rootDir, now = new Date()) {
+    const recordVersions = {};
+    for (const [kind, entry] of Object.entries(currentRecordVersions())) {
+        recordVersions[kind] = entry.version;
     }
-    const bySource = new Map();
-    for (const migration of migrations) {
-        assertLayoutVersion(migration.fromVersion, "Aggregate migration fromVersion");
-        assertLayoutVersion(migration.toVersion, "Aggregate migration toVersion");
-        if (migration.toVersion !== migration.fromVersion + 1) {
-            throw invalidMigration(`Aggregate migration ${migration.fromVersion}->${migration.toVersion} must advance exactly one schema version.`);
-        }
-        if (bySource.has(migration.fromVersion)) {
-            throw invalidMigration(`Duplicate migration from aggregate schema version ${migration.fromVersion}.`);
-        }
-        bySource.set(migration.fromVersion, migration);
-    }
-    const plan = [];
-    for (let current = fromVersion; current < targetVersion; current += 1) {
-        const migration = bySource.get(current);
-        if (migration === undefined || migration.toVersion !== current + 1) {
-            throw unsupportedVersion(current, targetVersion, "aggregate");
-        }
-        plan.push(migration);
-    }
-    return plan.reduce((current, migration) => migration.migrate(current), state);
-}
-function writeStorageManifest(rootDir, now) {
     const manifest = {
         schemaVersion: 1,
         storageVersion: CURRENT_STORAGE_LAYOUT_VERSION,
         aggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
-        activeGeneration: null,
+        recordVersions,
         updatedAt: now.toISOString()
     };
     writeTextFileAtomically(join(rootDir, STORAGE_SCHEMA_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -178,11 +177,18 @@ function requireInspectedSchema(state) {
         case "invalid":
             throw new StorageSchemaError("STORAGE_SCHEMA_INVALID", `Invalid storage schema manifest at ${state.manifestPath}: ${state.detail}`);
         case "unsupported":
-            throw unsupportedVersion(state.currentVersion, state.latestVersion, state.incompatibleComponent);
+            throw unsupportedVersion(state.currentVersion, state.latestVersion, state.incompatibleComponent, state.recordFamily);
     }
 }
-function unsupportedVersion(current, required, component) {
-    const label = component === "layout" ? "Storage layout" : "Aggregate schema";
+function unsupportedVersion(current, required, component, recordFamily) {
+    if (component === "record" && recordFamily === undefined) {
+        return new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", "This Home predates the durable record-version manifest and cannot be opened without explicit introduction migrations.");
+    }
+    const label = component === "layout"
+        ? "Storage layout"
+        : component === "aggregate"
+            ? "Aggregate schema"
+            : `Record family '${recordFamily}'`;
     if (current < required) {
         return new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", `${label} ${current} is older than required ${component} version ${required}; no migration is available in this Yui release.`);
     }
@@ -190,7 +196,13 @@ function unsupportedVersion(current, required, component) {
 }
 function parseStorageManifest(raw) {
     const value = parseJsonObject(raw, "Storage schema manifest");
-    assertKeys(value, ["schemaVersion", "storageVersion", "aggregateSchemaVersion", "updatedAt"], ["activeGeneration"], "Storage schema manifest");
+    return parseStorageSchemaManifest(value);
+}
+/** Strictly parse one already-decoded manifest object through the shared contract. */
+export function parseStorageSchemaManifest(value) {
+    if (!isRecord(value))
+        throw new Error("Storage schema manifest must be an object");
+    assertKeys(value, ["schemaVersion", "storageVersion", "aggregateSchemaVersion", "updatedAt"], ["recordVersions"], "Storage schema manifest");
     if (value.schemaVersion !== 1)
         throw new Error("schemaVersion must be 1");
     if (!Number.isInteger(value.storageVersion) || value.storageVersion < 1) {
@@ -200,21 +212,41 @@ function parseStorageManifest(raw) {
     if (!Number.isInteger(aggregateSchemaVersion) || aggregateSchemaVersion < 1) {
         throw new Error("aggregateSchemaVersion must be a positive integer");
     }
-    const activeGeneration = value.activeGeneration ?? null;
-    if (activeGeneration !== null) {
-        throw new Error(`activeGeneration is not supported by storage layout ${String(value.storageVersion)}`);
-    }
     if (typeof value.updatedAt !== "string" || !Number.isFinite(Date.parse(value.updatedAt))) {
         throw new Error("updatedAt must be an ISO timestamp");
     }
+    let recordVersions;
+    if (Object.hasOwn(value, "recordVersions")) {
+        if (!isRecord(value.recordVersions))
+            throw new Error("recordVersions must be an object");
+        const known = currentRecordVersions();
+        const kinds = Object.keys(value.recordVersions);
+        const unknown = kinds.filter((kind) => !Object.hasOwn(known, kind));
+        if (unknown.length > 0) {
+            throw new Error(`recordVersions has unknown family: ${unknown[0]}`);
+        }
+        const parsed = {};
+        for (const kind of kinds) {
+            const version = value.recordVersions[kind];
+            if (!Number.isInteger(version) || version < 1) {
+                throw new Error(`recordVersions['${kind}'] must be a positive integer`);
+            }
+            parsed[kind] = version;
+        }
+        recordVersions = Object.freeze(parsed);
+    }
     return {
         schemaVersion: 1,
         storageVersion: value.storageVersion,
         aggregateSchemaVersion: aggregateSchemaVersion,
-        activeGeneration,
+        ...(recordVersions === undefined ? {} : { recordVersions }),
         updatedAt: value.updatedAt
     };
 }
+/** Read and strictly parse the durable manifest through the same contract. */
+export function readStorageSchemaManifest(rootDir) {
+    return parseStorageManifest(readFileSync(join(rootDir, STORAGE_SCHEMA_FILE), "utf8"));
+}
 function parseJsonObject(raw, label) {
     let value;
     try {
@@ -236,14 +268,6 @@ function assertKeys(value, requiredKeys, optionalKeys, label) {
     if (missing.length > 0)
         throw new Error(`${label} is missing field: ${missing[0]}`);
 }
-function assertLayoutVersion(version, label) {
-    if (!Number.isInteger(version) || version < 1) {
-        throw invalidMigration(`${label} must be a positive integer.`);
-    }
-}
-function invalidMigration(message) {
-    return new StorageSchemaError("STORAGE_MIGRATION_INVALID", message);
-}
 function readOptionalText(path) {
     try {
         return readFileSync(path, "utf8");

package/dist/storage/storageVersions.js

@@ -0,0 +1,11 @@
+/**
+ * Scalar storage version constants.
+ *
+ * These live in their own module so that `storageSchema.ts`, `recordVersions.ts`,
+ * and `taskStore.ts` can all import them without creating a circular dependency.
+ * `storageSchema.ts` re-exports them for backward compatibility.
+ */
+/** Version of the on-disk layout (`schema.json`, root `state.json`, and locks). */
+export const CURRENT_STORAGE_LAYOUT_VERSION = 6;
+/** Version of the authoritative aggregate stored in `state.json`. */
+export const CURRENT_AGGREGATE_SCHEMA_VERSION = 17;