@zq-silk/yui 0.14.2 → 0.15.0

package/dist/storage/storageSchema.js

@@ -1,10 +1,10 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { writeTextFileAtomically } from "./durableFile.js";
-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";
+import Database from "better-sqlite3";
+import { inspectSqliteSchemaMigrations, storageMigrationPlan } from "./sqliteSchema.js";
+import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";
+export { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";
+export const CURRENT_DATABASE_FILENAME = "yui.db";
 export class StorageSchemaError extends Error {
     code;
     constructor(code, message, options) {
@@ -13,250 +13,119 @@ export class StorageSchemaError extends Error {
         this.code = code;
     }
 }
+/**
+ * Inspect the one authoritative SQLite migration head without changing it.
+ *
+ * `schema.json` and `state.json` are recognized only to prevent setup from
+ * overwriting an old Home whose SQLite authority is missing. They are not
+ * version authorities for current Homes.
+ */
 export function inspectStorageSchema(rootDir) {
-    const manifestPath = join(rootDir, STORAGE_SCHEMA_FILE);
-    const raw = readOptionalText(manifestPath);
-    if (raw === null) {
+    const databasePath = join(rootDir, CURRENT_DATABASE_FILENAME);
+    const hasPreBaselineEvidence = existsSync(join(rootDir, "schema.json")) || existsSync(join(rootDir, "state.json"));
+    if (hasPreBaselineEvidence) {
         return {
-            status: "uninitialized",
-            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
-            manifestPath
+            status: "unsupported",
+            direction: "older",
+            currentVersion: 0,
+            latestVersion: CURRENT_STORAGE_VERSION,
+            minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
+            databasePath
         };
     }
-    let manifest;
-    try {
-        manifest = parseStorageManifest(raw);
-    }
-    catch (error) {
+    if (!existsSync(databasePath)) {
+        if (existsSync(rootDir)) {
+            try {
+                if (readdirSync(rootDir).length > 0) {
+                    return invalid(databasePath, new Error("The authoritative yui.db is missing from a non-empty Home."));
+                }
+            }
+            catch (error) {
+                return invalid(databasePath, 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)
+            status: "uninitialized",
+            latestVersion: CURRENT_STORAGE_VERSION,
+            minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
+            databasePath
         };
     }
-    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
-        };
+    let database;
+    try {
+        database = new Database(databasePath, { readonly: true, fileMustExist: true });
     }
-    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
-        };
+    catch (error) {
+        return invalid(databasePath, error);
     }
-    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
+    try {
+        const migration = inspectSqliteSchemaMigrations(database);
+        const fields = {
+            currentVersion: migration.currentVersion,
+            latestVersion: CURRENT_STORAGE_VERSION,
+            minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
+            databasePath
         };
-    }
-    for (const [kind, currentEntry] of Object.entries(currentRecords)) {
-        const persisted = manifest.recordVersions[kind];
-        if (persisted === undefined) {
-            return {
-                status: "unsupported",
-                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 (migration.currentVersion === CURRENT_STORAGE_VERSION) {
+            return { status: "current", ...fields };
+        }
+        if (migration.currentVersion > CURRENT_STORAGE_VERSION) {
+            return { status: "unsupported", direction: "newer", ...fields };
         }
-        if (persisted !== currentEntry.version) {
+        if (migration.currentVersion < MIN_SUPPORTED_STORAGE_VERSION) {
+            return { status: "unsupported", direction: "older", ...fields };
+        }
+        const plan = storageMigrationPlan(migration.currentVersion);
+        if (plan === null) {
             return {
-                status: "unsupported",
-                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
+                status: "invalid",
+                latestVersion: CURRENT_STORAGE_VERSION,
+                minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
+                databasePath,
+                detail: `Storage migration registry has no complete path from `
+                    + `${migration.currentVersion} to ${CURRENT_STORAGE_VERSION}.`
             };
         }
+        return {
+            status: "upgradeable",
+            pendingVersions: plan.map(({ toVersion }) => toVersion),
+            ...fields
+        };
     }
-    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") {
-        writeCurrentStorageManifest(rootDir, now);
-        return;
+    catch (error) {
+        return invalid(databasePath, error);
     }
-    requireInspectedSchema(state);
-}
-/** 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;
+    finally {
+        database.close();
     }
-    const manifest = {
-        schemaVersion: 1,
-        storageVersion: CURRENT_STORAGE_LAYOUT_VERSION,
-        aggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
-        recordVersions,
-        updatedAt: now.toISOString()
-    };
-    writeTextFileAtomically(join(rootDir, STORAGE_SCHEMA_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
 }
-function requireInspectedSchema(state) {
+/** Require the current storage contract without normalizing historical data. */
+export function requireCurrentStorageSchema(rootDir) {
+    const state = inspectStorageSchema(rootDir);
     switch (state.status) {
         case "current":
             return;
         case "uninitialized":
             throw new StorageSchemaError("STORAGE_UNINITIALIZED", "Yui storage is not initialized. Run `yui setup`.");
         case "invalid":
-            throw new StorageSchemaError("STORAGE_SCHEMA_INVALID", `Invalid storage schema manifest at ${state.manifestPath}: ${state.detail}`);
+            throw new StorageSchemaError("STORAGE_SCHEMA_INVALID", `Invalid storage at ${state.databasePath}: ${state.detail}`);
+        case "upgradeable":
+            throw new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", `Storage version ${state.currentVersion} requires an explicit upgrade to `
+                + `${state.latestVersion}. Run \`yui upgrade\` or \`yui update\`.`);
         case "unsupported":
-            throw unsupportedVersion(state.currentVersion, state.latestVersion, state.incompatibleComponent, state.recordFamily);
+            throw new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", state.direction === "newer"
+                ? `Storage version ${state.currentVersion} is newer than supported `
+                    + `${state.latestVersion}; use a newer Yui release.`
+                : `Storage version ${state.currentVersion} is older than the minimum supported `
+                    + `${state.minimumSupportedVersion}.`);
     }
 }
-function unsupportedVersion(current, required, component, recordFamily) {
-    if (component === "record" && recordFamily === undefined) {
-        return new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", "This Home predates the current record-version manifest. Preserve it for inspection and initialize a new Home.");
-    }
-    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}; use the matching Yui version or initialize a new Home.`);
-    }
-    return new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", `${label} ${current} is newer than supported ${component} version ${required}; use a newer Yui release.`);
-}
-function parseStorageManifest(raw) {
-    const value = parseJsonObject(raw, "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) {
-        throw new Error("storageVersion must be a positive integer");
-    }
-    const aggregateSchemaVersion = value.aggregateSchemaVersion;
-    if (!Number.isInteger(aggregateSchemaVersion) || aggregateSchemaVersion < 1) {
-        throw new Error("aggregateSchemaVersion must be a positive integer");
-    }
-    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);
-    }
+function invalid(databasePath, error) {
     return {
-        schemaVersion: 1,
-        storageVersion: value.storageVersion,
-        aggregateSchemaVersion: aggregateSchemaVersion,
-        ...(recordVersions === undefined ? {} : { recordVersions }),
-        updatedAt: value.updatedAt
+        status: "invalid",
+        latestVersion: CURRENT_STORAGE_VERSION,
+        minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
+        databasePath,
+        detail: error instanceof Error ? error.message : String(error)
     };
 }
-function parseJsonObject(raw, label) {
-    let value;
-    try {
-        value = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`${label} is not valid JSON`, { cause: error });
-    }
-    if (!isRecord(value))
-        throw new Error(`${label} must be an object`);
-    return value;
-}
-function assertKeys(value, requiredKeys, optionalKeys, label) {
-    const expected = new Set([...requiredKeys, ...optionalKeys]);
-    const unknown = Object.keys(value).filter((key) => !expected.has(key));
-    const missing = requiredKeys.filter((key) => !Object.hasOwn(value, key));
-    if (unknown.length > 0)
-        throw new Error(`${label} has unknown field: ${unknown[0]}`);
-    if (missing.length > 0)
-        throw new Error(`${label} is missing field: ${missing[0]}`);
-}
-function readOptionalText(path) {
-    try {
-        return readFileSync(path, "utf8");
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/storage/storageVersions.js

@@ -1,20 +1,16 @@
 /**
- * Scalar storage version constants.
+ * The one durable compatibility axis for a Yui Home.
  *
- * 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 as the public storage-contract boundary.
- */
-/**
- * Version of the on-disk layout (`schema.json` plus the SQLite database).
+ * Version 1 is the clean baseline introduced by Yui 0.15.0: SQLite's migration
+ * ledger is authoritative and the historical layout/aggregate/record-version
+ * manifest is not part of the active Home. Pre-0.15.0 Homes are outside this
+ * compatibility line and remain untouched.
  *
- * Layout 8 is the current SQLite WAL control-plane layout: the authoritative
- * store is `yui.db`. Layout 8 is the only physical layout this release reads
- * and writes. Historical aggregate contracts are rejected without mutation.
- */
-export const CURRENT_STORAGE_LAYOUT_VERSION = 8;
-/**
- * Aggregate 31 makes Agent results opaque, removes parsed Review/finding
- * authority, and intentionally has no upgrade path from earlier contracts.
+ * Runtime code reads only {@link CURRENT_STORAGE_VERSION}. The explicit
+ * upgrade boundary carries every forward migration from
+ * {@link MIN_SUPPORTED_STORAGE_VERSION} to the current version so one target
+ * CLI can upgrade any valid Home in that interval without installing
+ * intermediate Yui releases.
  */
-export const CURRENT_AGGREGATE_SCHEMA_VERSION = 31;
+export const MIN_SUPPORTED_STORAGE_VERSION = 1;
+export const CURRENT_STORAGE_VERSION = 1;