@zq-silk/yui 0.13.9 → 0.14.0

package/dist/storage/upgrade/pseudoLayoutRepair.js

@@ -1,241 +0,0 @@
-/**
- * Deterministic repair for a *pseudo-layout-7* Home (Issue 01).
- *
- * A pseudo-layout-7 Home declares layout 7 in `schema.json` but has no `yui.db`;
- * its `state.json` is still the only authoritative copy. The classifier reports
- * this as `NEEDS_STORAGE_REPAIR`. This module rebuilds the SQLite database from
- * the pinned `state.json`, verifies every record family against an independent
- * re-read, promotes the staged database atomically, certifies the switch with a
- * persistent migration receipt, read-backs through a fresh store, and archives
- * `state.json` to a timestamped backup so it can never serve as a writable
- * fallback again.
- *
- * Failure semantics (issue: 最简失败语义):
- *  - staging/verification failure: `state.json` stays authoritative, the staged
- *    database is discarded, the manifest is untouched;
- *  - a stale staged database from a crashed attempt is always rebuilt, never
- *    reused;
- *  - any failure after the atomic promote quarantines the promoted database and
- *    removes the receipt, returning the Home to its exact pre-repair shape;
- *  - the one non-fatal tail is archiving `state.json`: if that rename fails the
- *    database is already promoted, verified, and receipt-certified, and the
- *    result is `blocked` with the exact manual finishing step.
- */
-import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { readStorageSchemaManifest } from "../storageSchema.js";
-import { STORAGE_STATE_FILE } from "../taskStore.js";
-import { SqliteTaskStore } from "../sqliteStore.js";
-import { migrationReceiptPath, writeMigrationReceipt } from "./migrationReceipt.js";
-import { COMMITTED_DATABASE_FILENAME, STAGED_DATABASE_FILENAME, computeDbFamilyChecksums, populateSqliteFromState, verifySqliteChecksums } from "./sqliteStateMigration.js";
-/**
- * Run the staged state.json→SQLite repair. Never throws for an expected
- * blocker; a malformed manifest or an unreadable `state.json` is a `blocked`
- * result, not an exception.
- */
-export function repairPseudoLayout7(options) {
-    const { home, latest, mode } = options;
-    const now = options.now ?? (() => new Date());
-    const statePath = join(home, STORAGE_STATE_FILE);
-    const stagedPath = join(home, STAGED_DATABASE_FILENAME);
-    const committedPath = join(home, COMMITTED_DATABASE_FILENAME);
-    // 1. Re-verify the preconditions fail-closed; the repair never trusts a
-    //    classifier verdict produced by an earlier process.
-    let manifest;
-    try {
-        manifest = readStorageSchemaManifest(home);
-    }
-    catch (error) {
-        return blocked("validate", `The storage manifest could not be read: ${messageOf(error)}`, "Restore schema.json from a backup; the repair requires a readable layout-7 manifest.");
-    }
-    if (manifest.storageVersion !== latest.layout) {
-        return blocked("validate", `Pseudo-layout-7 repair requires a layout-${latest.layout} manifest; found layout ${manifest.storageVersion}.`, "Re-run `yui doctor`; this repair only applies to a pseudo-layout-7 Home.");
-    }
-    if (existsSync(committedPath)) {
-        return blocked("validate", `Refusing to repair: ${COMMITTED_DATABASE_FILENAME} already exists.`, "The Home already has a SQLite database. If it is damaged, restore it from a backup; do not rebuild over it.");
-    }
-    if (!existsSync(statePath)) {
-        return blocked("validate", `Pseudo-layout-7 repair requires a readable ${STORAGE_STATE_FILE}; none exists.`, `Restore ${STORAGE_STATE_FILE} from a backup; the repair cannot rebuild a database without its source.`);
-    }
-    // 2. Pin state.json (revision, size, sha256). A document that is not a
-    //    strictly readable JSON object fails the repair.
-    const pin = pinStateFile(statePath);
-    if (pin === null) {
-        return blocked("validate", `${STORAGE_STATE_FILE} is not a strictly readable JSON object.`, "The source document is damaged; restore it from a backup before repairing.");
-    }
-    // 3. A stale staged database from a crashed attempt is rebuilt, never reused.
-    discardStaged(stagedPath);
-    // 4. Stage: populate yui.db.staged from the pinned document.
-    try {
-        populateSqliteFromState(home, pin.state, STAGED_DATABASE_FILENAME);
-    }
-    catch (error) {
-        discardStaged(stagedPath);
-        return blocked("validate", `Staging the SQLite database failed: ${messageOf(error)}`, `${STORAGE_STATE_FILE} remains the authoritative store; the staged database was discarded.`);
-    }
-    // 5. Verify: the pinned bytes must be unchanged (no concurrent writer), and
-    //    every record family must match an independent state.json re-read by
-    //    count and content checksum.
-    try {
-        if (sha256(readFileSync(statePath, "utf8")) !== pin.sha256) {
-            discardStaged(stagedPath);
-            return blocked("validate", `${STORAGE_STATE_FILE} changed during the repair; a concurrent writer is active.`, "Quiesce all writers and retry; the staged database was discarded and state.json remains authoritative.");
-        }
-        verifySqliteChecksums(pin.state, home, STAGED_DATABASE_FILENAME);
-    }
-    catch (error) {
-        discardStaged(stagedPath);
-        return blocked("validate", `Staged database verification failed: ${messageOf(error)}`, `${STORAGE_STATE_FILE} remains the authoritative store; the staged database was discarded.`);
-    }
-    const verifiedFamilies = Object.keys(computeDbFamilyChecksums(home, STAGED_DATABASE_FILENAME)).length;
-    if (mode === "dry-run") {
-        discardStaged(stagedPath);
-        return { outcome: "dry-run", verifiedFamilies, sourceRevision: pin.revision };
-    }
-    // 6. Promote: atomic rename staged -> yui.db. From here the database exists;
-    //    any failure rolls the promotion back so the Home keeps its pre-repair
-    //    shape (manifest 7, no yui.db, state.json authoritative).
-    try {
-        renameSync(stagedPath, committedPath);
-        // The staged connection may leave empty WAL/SHM sidecars behind even
-        // after a clean close; they are dead once the main file is promoted.
-        rmSync(`${stagedPath}-wal`, { force: true });
-        rmSync(`${stagedPath}-shm`, { force: true });
-    }
-    catch (error) {
-        discardStaged(stagedPath);
-        return blocked("switch", `Promoting the staged database failed: ${messageOf(error)}`, `${STORAGE_STATE_FILE} remains the authoritative store; the staged database was discarded.`);
-    }
-    // 7. Write the persistent migration receipt. A dual-copy Home without a
-    //    receipt is a conflict, so a receipt-write failure rolls the promotion
-    //    back rather than leaving an uncertified database behind.
-    try {
-        writeMigrationReceipt(home, {
-            kind: "pseudo-layout-7-repair",
-            completedAt: now().toISOString(),
-            sourceRevision: pin.revision,
-            targetLayoutVersion: latest.layout,
-            sourceStateSha256: pin.sha256,
-            verifiedFamilies
-        });
-    }
-    catch (error) {
-        rollbackPromotion(home, committedPath, now);
-        return blocked("post-verify", `The database was promoted but the migration receipt could not be written: ${messageOf(error)}`, `The promoted database was quarantined and the receipt removed; ${STORAGE_STATE_FILE} remains authoritative. Retry the repair.`);
-    }
-    // 8. Read-back through a fresh store, including revision continuity.
-    try {
-        const store = new SqliteTaskStore(home);
-        try {
-            store.getConfig();
-            store.listTasks();
-            store.listProjects();
-            store.listConfiguredAgents();
-            store.listWorkMailboxes();
-            const dbRevision = store.getRevision();
-            if (dbRevision !== pin.revision) {
-                throw new Error(`revision mismatch: ${STORAGE_STATE_FILE}=${pin.revision} database=${dbRevision}`);
-            }
-        }
-        finally {
-            store.close();
-        }
-    }
-    catch (error) {
-        rollbackPromotion(home, committedPath, now);
-        return blocked("post-verify", `Post-promote read-back failed: ${messageOf(error)}`, `The promoted database was quarantined and the receipt removed; ${STORAGE_STATE_FILE} remains authoritative. Retry the repair.`);
-    }
-    // 9. Archive state.json so it can never serve as a writable fallback. The
-    //    receipt certifies the dual-copy window, so a failure here leaves a
-    //    usable Home: the database is authoritative and the repair is finished by
-    //    moving the file manually.
-    const stamp = now().toISOString().replace(/[:.]/g, "-");
-    const stateBackupPath = join(home, `${STORAGE_STATE_FILE}.backup-${stamp}`);
-    try {
-        if (existsSync(stateBackupPath)) {
-            throw new Error(`refusing to overwrite an existing state backup: ${stateBackupPath}`);
-        }
-        renameSync(statePath, stateBackupPath);
-    }
-    catch (error) {
-        return blocked("post-verify", `The database was promoted and verified, but ${STORAGE_STATE_FILE} could not be archived: ${messageOf(error)}`, `The database is authoritative and the migration receipt certifies it. Move ${STORAGE_STATE_FILE} to ${stateBackupPath} manually to finish the repair.`);
-    }
-    return {
-        outcome: "repaired",
-        stateBackupPath,
-        verifiedFamilies,
-        sourceRevision: pin.revision
-    };
-}
-/** The newest `state.json.backup-*` path in a Home, or `null` when none exists. */
-export function latestStateBackupPath(home) {
-    const entries = listStateBackups(home);
-    return entries.length === 0 ? null : entries[entries.length - 1];
-}
-/** All `state.json.backup-*` paths in a Home, sorted oldest-first. */
-export function listStateBackups(home) {
-    let names;
-    try {
-        names = readdirSync(home);
-    }
-    catch {
-        return [];
-    }
-    return names
-        .filter((name) => name.startsWith(`${STORAGE_STATE_FILE}.backup-`))
-        .sort()
-        .map((name) => join(home, name));
-}
-function pinStateFile(statePath) {
-    let raw;
-    try {
-        raw = readFileSync(statePath, "utf8");
-    }
-    catch {
-        return null;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return null;
-    }
-    const state = parsed;
-    return {
-        state,
-        revision: typeof state.revision === "number" ? state.revision : 0,
-        sha256: createHash("sha256").update(raw, "utf8").digest("hex"),
-        size: Buffer.byteLength(raw, "utf8")
-    };
-}
-function sha256(raw) {
-    return createHash("sha256").update(raw, "utf8").digest("hex");
-}
-function discardStaged(stagedPath) {
-    rmSync(stagedPath, { force: true });
-    rmSync(`${stagedPath}-wal`, { force: true });
-    rmSync(`${stagedPath}-shm`, { force: true });
-}
-function quarantine(committedPath, now) {
-    const stamp = now().toISOString().replace(/[:.]/g, "-");
-    const quarantinePath = `${committedPath}.quarantine-${stamp}`;
-    renameSync(committedPath, quarantinePath);
-    rmSync(`${committedPath}-wal`, { force: true });
-    rmSync(`${committedPath}-shm`, { force: true });
-    return quarantinePath;
-}
-function rollbackPromotion(home, committedPath, now) {
-    quarantine(committedPath, now);
-    rmSync(migrationReceiptPath(home), { force: true });
-}
-function blocked(stage, message, action) {
-    return { outcome: "blocked", stage, message, action };
-}
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/storage/upgrade/recordVersionScan.js

@@ -1,176 +0,0 @@
-/**
- * Pure, read-only structural scan of raw `state.json`, never through the strict
- * `parseState`/`FileTaskStore` gate. The durable manifest remains authoritative;
- * this scanner supplies member versions and counts so callers can detect
- * manifest/state contradictions without treating an empty locator as current.
- * Older member versions remain version evidence rather than a strict-loader
- * parse failure, while malformed JSON/containers/schemaVersion fields are real
- * `CORRUPTED` evidence.
- *
- * The `path` for each family (from `recordVersions.ts`) is a small locator into
- * `state.json`: segments are `/`-separated after the `state.json#/` prefix, and a
- * `*` segment fans out over every member of the map at that level (so the locator
- * `state.json#/tasks/{star}/workItems` visits the `workItems` map of every task,
- * where `{star}` is a literal `*`).
- */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { STORAGE_STATE_FILE } from "../taskStore.js";
-/**
- * Scan per-family member versions and counts from raw `state.json`.
- *
- * Rules, per family, evaluated purely (no strict parser):
- *  - family absent or empty on disk  -> latest as an internal scan sentinel,
- *    with count zero so the manifest combiner never infers source currency;
- *  - every member at one older/current/newer version -> report that version;
- *  - members carrying different versions             -> corruption.
- *
- * A family is one durable schema boundary, so a manifest cannot make a mixed
- * member set trustworthy by matching either its minimum or maximum. Mixed
- * members are partial-write/corruption evidence, not a migration source version.
- *
- * Returns a `corruption` instead when the JSON is unparseable, the root is not an
- * object, a path container is not the shape the locator describes, or a record is
- * missing/has an invalid `schemaVersion`.
- */
-export function scanSourceRecordVersions(home, latestRecord) {
-    const statePath = join(home, STORAGE_STATE_FILE);
-    if (!existsSync(statePath)) {
-        // No state.json means zero persisted members. The latest-valued scan entry
-        // is only a sentinel; counts preserve absence for the manifest combiner.
-        return {
-            record: cloneRecord(latestRecord),
-            counts: Object.fromEntries(Object.keys(latestRecord).map((kind) => [kind, 0]))
-        };
-    }
-    let root;
-    try {
-        root = JSON.parse(readFileSync(statePath, "utf8"));
-    }
-    catch (error) {
-        return corruption(`state.json is not valid JSON: ${messageOf(error)}`);
-    }
-    if (!isObject(root)) {
-        return corruption("state.json is not a JSON object.");
-    }
-    return scanRecordVersionsFromState(root, latestRecord);
-}
-/** Extract record versions from an already-parsed state snapshot, read-only. */
-export function scanRecordVersionsFromState(root, latestRecord) {
-    if (!isObject(root))
-        return corruption("state snapshot is not a JSON object.");
-    const record = {};
-    const counts = {};
-    for (const [kind, entry] of Object.entries(latestRecord)) {
-        const scan = scanFamily(root, entry.path, entry.version);
-        if ("corruption" in scan) {
-            return corruption(`record family '${kind}' (${entry.path}): ${scan.corruption}`);
-        }
-        record[kind] = { version: scan.version, path: entry.path };
-        counts[kind] = scan.count;
-    }
-    return { record, counts };
-}
-/** Resolve one family's source version from `root` following `path`. */
-function scanFamily(root, path, latestVersion) {
-    const segments = parseLocator(path);
-    if (segments === null)
-        return { corruption: `unrecognized path syntax "${path}"` };
-    // Resolve the path to the family's endpoint node(s). A `*` fans out over the
-    // members of the map at that level; an absent named key contributes nothing
-    // (that branch simply has no records), but a present-but-wrong-typed node is
-    // structural damage.
-    let nodes = [root];
-    for (const segment of segments) {
-        const next = [];
-        for (const node of nodes) {
-            if (segment === "*") {
-                if (!isObject(node))
-                    return { corruption: `expected an object to enumerate at "*"` };
-                next.push(...Object.values(node));
-            }
-            else {
-                if (!isObject(node))
-                    return { corruption: `expected an object at "${segment}"` };
-                if (!Object.hasOwn(node, segment))
-                    continue; // absent branch: no records here
-                next.push(node[segment]);
-            }
-        }
-        nodes = next;
-    }
-    // Each endpoint is either a single record (it carries `schemaVersion`, e.g.
-    // tasks/* (the StoredTask aggregate), tasks/*/task, tasks/*/brief) or a map of records (its values carry
-    // `schemaVersion`, e.g. configuredAgents, tasks/*/workItems).
-    let min = Number.POSITIVE_INFINITY;
-    let max = Number.NEGATIVE_INFINITY;
-    let count = 0;
-    for (const endpoint of nodes) {
-        if (endpoint === null || endpoint === undefined)
-            continue; // e.g. brief: null
-        if (!isObject(endpoint))
-            return { corruption: "family endpoint is not an object" };
-        if (typeof endpoint.schemaVersion === "number") {
-            const version = readSchemaVersion(endpoint);
-            if (version === null)
-                return { corruption: `record has an invalid schemaVersion` };
-            min = Math.min(min, version);
-            max = Math.max(max, version);
-            count += 1;
-            continue;
-        }
-        for (const member of Object.values(endpoint)) {
-            if (member === null)
-                continue;
-            if (!isObject(member))
-                return { corruption: "record member is not an object" };
-            const version = readSchemaVersion(member);
-            if (version === null)
-                return { corruption: "record member has a missing/invalid schemaVersion" };
-            min = Math.min(min, version);
-            max = Math.max(max, version);
-            count += 1;
-        }
-    }
-    if (count === 0)
-        return { version: latestVersion, count }; // zero-count sentinel only
-    if (min !== max) {
-        return {
-            corruption: `family contains mixed schemaVersion values ${min} and ${max}`
-        };
-    }
-    return { version: min, count };
-}
-/** Parse a `state.json#/`-prefixed locator into path segments, or `null`. */
-function parseLocator(path) {
-    const prefix = `${STORAGE_STATE_FILE}#/`;
-    if (!path.startsWith(prefix))
-        return null;
-    const body = path.slice(prefix.length);
-    if (body.length === 0)
-        return null;
-    return body.split("/");
-}
-/** A positive-integer `schemaVersion`, or `null` when missing/invalid. */
-function readSchemaVersion(record) {
-    const version = record.schemaVersion;
-    if (typeof version !== "number" || !Number.isInteger(version) || version < 1)
-        return null;
-    return version;
-}
-function cloneRecord(record) {
-    const copy = {};
-    for (const [kind, entry] of Object.entries(record)) {
-        copy[kind] = { version: entry.version, path: entry.path };
-    }
-    return copy;
-}
-function corruption(detail) {
-    return { corruption: { corrupted: true, detail } };
-}
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/storage/upgrade/sqliteFileSet.js

@@ -1,50 +0,0 @@
-import { existsSync, renameSync, rmSync } from "node:fs";
-const SQLITE_FILE_SUFFIXES = ["", "-wal", "-shm"];
-/**
- * Move a SQLite database together with any live WAL/SHM sidecars.
- *
- * A WAL database is one logical file set. Moving only the main file can leave
- * the old WAL under the promoted database name, causing SQLite to replay it
- * against an unrelated database. The migration fence guarantees there are no
- * writers while this bounded rename runs.
- */
-export function moveSqliteFileSet(sourcePath, targetPath, rename = renameSync) {
-    const suffixes = SQLITE_FILE_SUFFIXES.filter((suffix) => existsSync(`${sourcePath}${suffix}`));
-    for (const suffix of suffixes) {
-        if (existsSync(`${targetPath}${suffix}`)) {
-            throw new Error(`Refusing to overwrite an existing SQLite switch target: ${targetPath}${suffix}.`);
-        }
-    }
-    const moved = [];
-    try {
-        for (const suffix of suffixes) {
-            rename(`${sourcePath}${suffix}`, `${targetPath}${suffix}`);
-            moved.push(suffix);
-        }
-    }
-    catch (error) {
-        let rollbackError;
-        for (const suffix of moved.reverse()) {
-            try {
-                rename(`${targetPath}${suffix}`, `${sourcePath}${suffix}`);
-            }
-            catch (candidate) {
-                rollbackError ??= candidate;
-            }
-        }
-        if (rollbackError !== undefined) {
-            throw new Error(`SQLite file-set move failed and rollback was incomplete: ${messageOf(error)}; `
-                + `rollback failed: ${messageOf(rollbackError)}`);
-        }
-        throw error;
-    }
-}
-/** Remove a promoted SQLite file set before restoring its timestamped backup. */
-export function removeSqliteFileSet(databasePath) {
-    for (const suffix of SQLITE_FILE_SUFFIXES) {
-        rmSync(`${databasePath}${suffix}`, { force: true });
-    }
-}
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}