@zq-silk/yui 0.6.0 → 0.6.2

package/dist/storage/upgrade/homeClassification.js

@@ -23,12 +23,15 @@
  * non-empty families agree. This keeps a record-only-older Home on its version
  * axis without letting an empty target family masquerade as current.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import Database from "better-sqlite3";
 import { classifyStorage } from "../migration/index.js";
 import { inspectStorageSchema } from "../storageSchema.js";
-import { FileTaskStore, StorageRecordError } from "../taskStore.js";
+import { FileTaskStore, STORAGE_STATE_FILE, StorageRecordError } from "../taskStore.js";
 import { SqliteTaskStore } from "../sqliteStore.js";
 import { inspectSourceVersionState } from "./homeMigrationTarget.js";
+import { readMigrationReceipt } from "./migrationReceipt.js";
 /**
  * Classify a real Home. Reads `schema.json` (and, for a current Home,
  * `state.json` through the strict loader) read-only; never mutates the Home.
@@ -78,6 +81,36 @@ export function classifyHome(options) {
         };
     }
     const source = inspected.source;
+    // Layout 7 physical-backend invariant (Issue 01): the manifest claims SQLite
+    // WAL as the authoritative store, so `yui.db` must exist and be healthy. A
+    // layout-7 Home without `yui.db` is a *pseudo-layout-7* Home — repairable
+    // when `state.json` is strictly readable, corrupted otherwise. A Home with
+    // both `state.json` and `yui.db` but no persistent migration receipt is an
+    // ambiguous dual-copy conflict. These are physical-backend facts, not
+    // version verdicts, so they are decided before the pure classifier runs.
+    //
+    // The invariant binds a Home whose *layout* is current (7), regardless of
+    // whether the record/aggregate axes are also current. A layout-7 Home with
+    // older record versions and no yui.db is still a pseudo-layout-7 Home: it
+    // needs the state.json→SQLite repair first, then the record-family migration
+    // (multi-phase orchestration in the upgrade executor). Routing it to the
+    // pure version classifier would select the SQLite record target, which
+    // cannot read a yui.db that does not exist yet. A Home with an older/future
+    // *layout* is fenced by version policy below, as before.
+    if (schema.currentLayoutVersion === latest.layout && latest.layout >= 7) {
+        const physical = inspectLayout7PhysicalBackend(home);
+        if (physical !== undefined) {
+            return {
+                ...base,
+                classification: physical,
+                layoutVersion: schema.currentLayoutVersion,
+                aggregateVersion: schema.currentAggregateSchemaVersion,
+                ...(incompatibleComponentOf(schema) === undefined
+                    ? {}
+                    : { incompatibleComponent: incompatibleComponentOf(schema) })
+            };
+        }
+    }
     // The reference graph can only be validated by the strict loader, which only
     // understands the current versions. So run it exactly when every axis is
     // already current (the plan would be a no-op); a throw there is genuine
@@ -177,6 +210,91 @@ function isFullyCurrent(source, latest) {
 function incompatibleComponentOf(schema) {
     return schema.status === "unsupported" ? schema.incompatibleComponent : undefined;
 }
+/**
+ * Inspect the physical-backend invariant of a layout-7 Home (Issue 01):
+ * `yui.db` must exist and be healthy. Returns a classification verdict when
+ * the invariant is violated, or `undefined` when the Home is physically sound
+ * (the pure classifier then decides the version verdict).
+ *
+ *  - manifest=7, no `yui.db`, `state.json` strictly readable →
+ *    `NEEDS_STORAGE_REPAIR` (pseudo-layout-7);
+ *  - manifest=7, no `yui.db`, no readable `state.json` → `CORRUPTED`
+ *    (no authoritative backend);
+ *  - `yui.db` unopenable or failing `PRAGMA quick_check` → `CORRUPTED`
+ *    (damaged database);
+ *  - both `state.json` and `yui.db` without a persistent migration receipt →
+ *    `CORRUPTED` (dual-copy conflict; never guess which copy is newer).
+ */
+function inspectLayout7PhysicalBackend(home) {
+    const dbPath = join(home, "yui.db");
+    const statePath = join(home, STORAGE_STATE_FILE);
+    if (!existsSync(dbPath)) {
+        if (isReadableStateObject(statePath)) {
+            return {
+                verdict: "NEEDS_STORAGE_REPAIR",
+                status: "needs-storage-repair",
+                detail: "Storage declares layout 7 but has no yui.db; state.json is the only "
+                    + "authoritative copy (pseudo-layout-7). Run `yui upgrade` to rebuild "
+                    + "the SQLite database."
+            };
+        }
+        return {
+            verdict: "CORRUPTED",
+            status: "unsupported",
+            detail: "Storage declares layout 7 but has neither yui.db nor a readable "
+                + "state.json; there is no authoritative backend."
+        };
+    }
+    // `yui.db` exists: it must open and pass an integrity check.
+    try {
+        const db = new Database(dbPath, { readonly: true });
+        try {
+            const integrity = db.pragma("quick_check", { simple: true });
+            if (integrity !== "ok") {
+                return {
+                    verdict: "CORRUPTED",
+                    status: "unsupported",
+                    detail: `SQLite integrity check failed: ${String(integrity)}.`
+                };
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (error) {
+        return {
+            verdict: "CORRUPTED",
+            status: "unsupported",
+            detail: `SQLite database cannot be opened: ${error instanceof Error ? error.message : String(error)}.`
+        };
+    }
+    // A healthy `yui.db` plus `state.json` is only legitimate right after a
+    // certified switch; without the persistent migration receipt it is a
+    // dual-copy conflict.
+    if (existsSync(statePath) && readMigrationReceipt(home) === null) {
+        return {
+            verdict: "CORRUPTED",
+            status: "unsupported",
+            detail: "Both state.json and yui.db exist without a migration receipt; the "
+                + "authoritative copy is ambiguous. Restore one copy from a backup; do "
+                + "not guess which is newer."
+        };
+    }
+    return undefined;
+}
+/** True when `state.json` exists and parses as a strict JSON object. */
+function isReadableStateObject(statePath) {
+    if (!existsSync(statePath))
+        return false;
+    try {
+        const value = JSON.parse(readFileSync(statePath, "utf8"));
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    catch {
+        return false;
+    }
+}
 /** A structural corruption check over an already-read snapshot (for tests/reports). */
 export function snapshotHasState(snapshot) {
     return snapshot.state !== null;

package/dist/storage/upgrade/migrationReceipt.js

@@ -0,0 +1,67 @@
+/**
+ * The persistent migration receipt — a durable, in-Home record of the
+ * physical-backend transition that produced the current `yui.db`.
+ *
+ * ## Why (the dual-copy ambiguity problem)
+ *
+ * A layout-7 Home may legitimately contain both `state.json` and `yui.db`
+ * during the narrow switch window, or illegitimately after a crashed/torn
+ * transition. Without durable evidence, a reader cannot tell "the SQLite
+ * database was just promoted from this exact state.json" from "two
+ * authoritative copies drifted apart". The receipt is written only after the
+ * staged database is fully verified and atomically promoted, so its presence
+ * (correlating the source revision and checksum) certifies the dual-copy state
+ * as a fresh, intentional switch rather than a conflict.
+ *
+ * Unlike the temporary upgrade completion receipt (`<home>.upgrade-receipt.json`,
+ * a sibling of the Home used by the update flow), this receipt lives INSIDE the
+ * Home at `migration-receipt.json` and persists for the Home's lifetime: it is
+ * the physical-backend provenance that `doctor` and the classifier read.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeTextFileAtomically } from "../durableFile.js";
+/** The persistent receipt path inside a Home. */
+export function migrationReceiptPath(home) {
+    return join(home, "migration-receipt.json");
+}
+/** Write the persistent receipt atomically, just after the database promotes. */
+export function writeMigrationReceipt(home, receipt) {
+    writeTextFileAtomically(migrationReceiptPath(home), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+/**
+ * Read the persistent receipt, or `null` when absent. A malformed or
+ * untrustworthy receipt reads as `null`: the receipt is provenance evidence,
+ * not an authority, and a Home whose receipt cannot be parsed must fail closed
+ * to the dual-copy conflict diagnosis rather than trust a torn write.
+ */
+export function readMigrationReceipt(home) {
+    const path = migrationReceiptPath(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if ((value.kind !== "layout6-to-7" && value.kind !== "pseudo-layout-7-repair")
+            || typeof value.completedAt !== "string"
+            || !Number.isInteger(value.sourceRevision)
+            || !Number.isInteger(value.targetLayoutVersion)
+            || typeof value.sourceStateSha256 !== "string"
+            || !Number.isInteger(value.verifiedFamilies)) {
+            return null;
+        }
+        return {
+            kind: value.kind,
+            completedAt: value.completedAt,
+            sourceRevision: value.sourceRevision,
+            targetLayoutVersion: value.targetLayoutVersion,
+            sourceStateSha256: value.sourceStateSha256,
+            verifiedFamilies: value.verifiedFamilies,
+            ...(typeof value.stateBackupPath === "string"
+                ? { stateBackupPath: value.stateBackupPath }
+                : {})
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/storage/upgrade/pseudoLayoutRepair.js

@@ -0,0 +1,241 @@
+/**
+ * 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/recordVersions.js

@@ -16,9 +16,10 @@
  * transform in the production migration graph.
  */
 import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storageVersions.js";
-import { CURRENT_AGENT_RUN_SCHEMA_VERSION, CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION, CURRENT_CHANGE_SET_SCHEMA_VERSION, CURRENT_DECISION_SCHEMA_VERSION, CURRENT_EVENT_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_INPUT_REQUEST_SCHEMA_VERSION, CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION, CURRENT_MESSAGE_SCHEMA_VERSION, CURRENT_MILESTONE_SCHEMA_VERSION, CURRENT_PROJECT_SCHEMA_VERSION, CURRENT_REVIEW_ROUND_SCHEMA_VERSION, CURRENT_STORED_TASK_SCHEMA_VERSION, CURRENT_TASK_BRIEF_SCHEMA_VERSION, CURRENT_TASK_ROLE_SCHEMA_VERSION, CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_TASK_SCHEMA_VERSION, CURRENT_WORK_ITEM_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION } from "../taskStore.js";
+import { CURRENT_AGENT_RUN_SCHEMA_VERSION, CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, CURRENT_CAPABILITY_GRANT_SCHEMA_VERSION, CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION, CURRENT_CHANGE_SET_SCHEMA_VERSION, CURRENT_DECISION_SCHEMA_VERSION, CURRENT_EVENT_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_INPUT_REQUEST_SCHEMA_VERSION, CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, CURRENT_INTEGRATION_QUEUE_SCHEMA_VERSION, CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION, CURRENT_MESSAGE_SCHEMA_VERSION, CURRENT_MILESTONE_SCHEMA_VERSION, CURRENT_PROJECT_SCHEMA_VERSION, CURRENT_RELEASE_WORKFLOW_SCHEMA_VERSION, CURRENT_REVIEW_ROUND_SCHEMA_VERSION, CURRENT_STORED_TASK_SCHEMA_VERSION, CURRENT_TASK_BRIEF_SCHEMA_VERSION, CURRENT_TASK_ROLE_SCHEMA_VERSION, CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_TASK_SCHEMA_VERSION, CURRENT_WORK_ITEM_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION } from "../taskStore.js";
 import { CURRENT_LEADER_FAILURE_SCHEMA_VERSION } from "../../scheduler/leaderFailure.js";
 import { CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION } from "../../scheduler/operatorNotification.js";
+import { CURRENT_DURABLE_JOB_SCHEMA_VERSION } from "../../job/durableJob.js";
 function descriptor(version, path) {
     return Object.freeze({ version, path });
 }
@@ -46,12 +47,16 @@ const EXPECTED_DIRECT_RECORD_LOCATORS = Object.freeze({
     reviewRound: "state.json#/tasks/*/reviewRounds",
     changeSet: "state.json#/tasks/*/changeSets",
     integrationAttempt: "state.json#/tasks/*/integrationAttempts",
+    integrationQueue: "state.json#/tasks/*/integrationQueue",
+    durableJob: "state.json#/tasks/*/durableJobs",
     activeRunPointer: "state.json#/tasks/*/activeRuns",
     message: "state.json#/tasks/*/messages",
     inputRequest: "state.json#/tasks/*/inputRequests",
     decision: "state.json#/tasks/*/decisions",
     milestone: "state.json#/tasks/*/milestones",
     event: "state.json#/tasks/*/events",
+    capabilityGrant: "state.json#/tasks/*/capabilityGrants",
+    releaseWorkflow: "state.json#/tasks/*/releaseWorkflows",
     leaderFailure: "state.json#/tasks/*/leaderFailure",
     operatorNotification: "state.json#/tasks/*/operatorNotification",
     workMailbox: "state.json#/mailboxes"
@@ -95,12 +100,16 @@ function getCurrentRecordDescriptors() {
             reviewRound: descriptor(CURRENT_REVIEW_ROUND_SCHEMA_VERSION, "state.json#/tasks/*/reviewRounds"),
             changeSet: descriptor(CURRENT_CHANGE_SET_SCHEMA_VERSION, "state.json#/tasks/*/changeSets"),
             integrationAttempt: descriptor(CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, "state.json#/tasks/*/integrationAttempts"),
+            integrationQueue: descriptor(CURRENT_INTEGRATION_QUEUE_SCHEMA_VERSION, "state.json#/tasks/*/integrationQueue"),
+            durableJob: descriptor(CURRENT_DURABLE_JOB_SCHEMA_VERSION, "state.json#/tasks/*/durableJobs"),
             activeRunPointer: descriptor(CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION, "state.json#/tasks/*/activeRuns"),
             message: descriptor(CURRENT_MESSAGE_SCHEMA_VERSION, "state.json#/tasks/*/messages"),
             inputRequest: descriptor(CURRENT_INPUT_REQUEST_SCHEMA_VERSION, "state.json#/tasks/*/inputRequests"),
             decision: descriptor(CURRENT_DECISION_SCHEMA_VERSION, "state.json#/tasks/*/decisions"),
             milestone: descriptor(CURRENT_MILESTONE_SCHEMA_VERSION, "state.json#/tasks/*/milestones"),
             event: descriptor(CURRENT_EVENT_SCHEMA_VERSION, "state.json#/tasks/*/events"),
+            capabilityGrant: descriptor(CURRENT_CAPABILITY_GRANT_SCHEMA_VERSION, "state.json#/tasks/*/capabilityGrants"),
+            releaseWorkflow: descriptor(CURRENT_RELEASE_WORKFLOW_SCHEMA_VERSION, "state.json#/tasks/*/releaseWorkflows"),
             leaderFailure: descriptor(CURRENT_LEADER_FAILURE_SCHEMA_VERSION, "state.json#/tasks/*/leaderFailure"),
             operatorNotification: descriptor(CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION, "state.json#/tasks/*/operatorNotification"),
             workMailbox: descriptor(CURRENT_WORK_MAILBOX_SCHEMA_VERSION, "state.json#/mailboxes")

package/dist/storage/upgrade/sqliteMigrationTarget.js

@@ -20,7 +20,10 @@
  *               a timestamped backup of any prior database) and advances
  *               `schema.json` to layout 7.
  *  - Rollback:  `rollbackSqliteMigration` quarantines `yui.db` and flips
- *               `schema.json` back to layout 6; `state.json` is never touched.
+ *               `schema.json` back to layout 6. A layout-6→7 migration retains
+ *               `state.json` in place (never touched); a pseudo-layout-7 repair
+ *               archived it to `state.json.backup-*`, so rollback restores the
+ *               newest backup when `state.json` is absent.
  *
  * The source `state.json` is retained read-only throughout: it is never
  * overwritten, truncated, or deleted by the migration. This preserves the
@@ -29,6 +32,7 @@
  */
 import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 import { writeTextFileAtomically } from "../durableFile.js";
 import { STORAGE_SCHEMA_FILE } from "../storageSchema.js";
 import { STORAGE_STATE_FILE } from "../taskStore.js";
@@ -36,6 +40,8 @@ import { planMigration } from "../migration/planner.js";
 import { AmbiguousSwitchError } from "../migration/index.js";
 import { describeActiveRuntime, homeRuntimeIsActive, inspectHomeRuntime, inspectSourceVersionState, inspectSnapshotVersionState } from "./homeMigrationTarget.js";
 import { COMMITTED_DATABASE_FILENAME, STAGED_DATABASE_FILENAME, computeDbFamilyChecksums, computeStateFamilyChecksums, populateSqliteFromState } from "./sqliteStateMigration.js";
+import { latestStateBackupPath } from "./pseudoLayoutRepair.js";
+import { migrationReceiptPath, writeMigrationReceipt } from "./migrationReceipt.js";
 /** Build the SQLite-backed migration target. */
 export function createSqliteMigrationTarget(options) {
     const home = options.home;
@@ -48,6 +54,11 @@ export function createSqliteMigrationTarget(options) {
     // The transformed schema manifest is cached during writeFreshOutput so the
     // switch can advance schema.json without re-reading or re-deriving it.
     let stagedSchemaManifest = null;
+    // The source document's revision and sha256, cached during writeFreshOutput
+    // so the switch can certify the dual-copy state with a persistent receipt
+    // (Issue 01: a layout-7 Home that retains state.json must carry the receipt
+    // that proves yui.db was promoted from that exact document).
+    let stagedReceiptSource = null;
     return {
         stagedDbPath,
         inspectVersions() {
@@ -87,10 +98,19 @@ export function createSqliteMigrationTarget(options) {
                 updatedAt: now().toISOString()
             };
             if (snapshot.state !== null) {
+                // Hash the actual on-disk bytes (the file is retained read-only
+                // throughout the migration), not a re-serialization of the parsed
+                // snapshot, so the receipt can be compared against the file itself.
+                const stateRaw = readFileSync(join(home, STORAGE_STATE_FILE), "utf8");
+                stagedReceiptSource = {
+                    revision: typeof snapshot.state.revision === "number" ? snapshot.state.revision : 0,
+                    sha256: createHash("sha256").update(stateRaw, "utf8").digest("hex")
+                };
                 populateSqliteFromState(home, snapshot.state, STAGED_DATABASE_FILENAME);
             }
             else {
                 // An empty Home (no state.json) still gets a schema-ready database.
+                stagedReceiptSource = { revision: 0, sha256: "" };
                 populateSqliteFromState(home, {}, STAGED_DATABASE_FILENAME);
             }
         },
@@ -138,6 +158,10 @@ export function createSqliteMigrationTarget(options) {
                     renameSync(committedDbPath, backupPath);
                 }
                 renameSync(stagedDbPath, committedDbPath);
+                // The staged connection may leave empty WAL/SHM sidecars behind
+                // even after a clean close; they are dead once promoted.
+                rmSync(`${stagedDbPath}-wal`, { force: true });
+                rmSync(`${stagedDbPath}-shm`, { force: true });
             }
             catch (error) {
                 // Pre-promotion failure: restore the original database if we moved it.
@@ -162,6 +186,21 @@ export function createSqliteMigrationTarget(options) {
                 if (stagedSchemaManifest !== null) {
                     writeTextFileAtomically(join(home, STORAGE_SCHEMA_FILE), `${JSON.stringify(stagedSchemaManifest, null, 2)}\n`);
                 }
+                // Certify the dual-copy state (Issue 01): the 6→7 migration retains
+                // state.json read-only, so the Home legitimately holds both copies.
+                // The persistent receipt is the evidence that lets the classifier and
+                // doctor distinguish this certified switch from a drifted conflict.
+                if (stagedReceiptSource !== null) {
+                    const familyCount = Object.keys(computeDbFamilyChecksums(home, COMMITTED_DATABASE_FILENAME)).length;
+                    writeMigrationReceipt(home, {
+                        kind: "layout6-to-7",
+                        completedAt: now().toISOString(),
+                        sourceRevision: stagedReceiptSource.revision,
+                        targetLayoutVersion: latest.layout,
+                        sourceStateSha256: stagedReceiptSource.sha256,
+                        verifiedFamilies: familyCount
+                    });
+                }
             }
             catch (error) {
                 // The database is promoted but schema.json could not be advanced.
@@ -255,12 +294,14 @@ export function createSqliteMigrationTarget(options) {
 }
 /**
  * Roll back a committed layout-7 SQLite migration: quarantine `yui.db` and
- * flip `schema.json` back to layout 6. The `state.json` document is never
- * touched — it was retained read-only during the migration and remains the
- * authoritative source after rollback.
+ * flip `schema.json` back to layout 6. A layout-6→7 migration retained
+ * `state.json` read-only in place, so it is untouched there. A pseudo-layout-7
+ * repair archived it to `state.json.backup-*`; when `state.json` is absent the
+ * newest backup is restored so the layout-6 File store recovers every
+ * pre-switch committed revision. The persistent migration receipt is removed.
  *
- * Returns the quarantine path. Throws if the Home is not at layout 7 or has
- * no `yui.db` to quarantine.
+ * Returns the quarantine path. Throws if the Home is not at layout 7, has no
+ * `yui.db` to quarantine, or has neither `state.json` nor a backup to restore.
  */
 export function rollbackSqliteMigration(home, options = {}) {
     const now = options.now ?? (() => new Date());
@@ -282,6 +323,17 @@ export function rollbackSqliteMigration(home, options = {}) {
     // Clean up WAL/SHM sidecars.
     rmSync(`${dbPath}-wal`, { force: true });
     rmSync(`${dbPath}-shm`, { force: true });
+    // Restore the file-store authoritative document when the repair archived it.
+    const statePath = join(home, STORAGE_STATE_FILE);
+    if (!existsSync(statePath)) {
+        const backupPath = latestStateBackupPath(home);
+        if (backupPath === null) {
+            throw new Error(`Rollback requires ${STORAGE_STATE_FILE} or a state.json.backup-* archive; neither exists.`);
+        }
+        renameSync(backupPath, statePath);
+    }
+    // The persistent receipt certified the switch being rolled back.
+    rmSync(migrationReceiptPath(home), { force: true });
     // Flip schema.json back to layout 6.
     const rolledBack = { ...manifest, storageVersion: 6 };
     writeTextFileAtomically(schemaPath, `${JSON.stringify(rolledBack, null, 2)}\n`);