@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/storage/paired-writer-migration.js

@@ -0,0 +1,424 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { AppError } from "../shared/errors.js";
+import { PreparedStoreWriterMigration, assertStoreWriterDrain } from "./writer-migration.js";
+import { publishImmutableInput } from "./immutable-input.js";
+import { beginStorageMaintenance, beginStorageRecovery, completeStorageMaintenance, importGuardPath } from "./import-guard.js";
+import { processTreeIsAlive } from "../services/managed-processes.js";
+import { STORE_WRITER_VERSION } from "./writer-contract.js";
+import { PreparedStoreWriterRestore } from "./writer-restore.js";
+import { acquireInstallationLock } from "../services/installation-lock.js";
+import { withStoreCleanup } from "./native-cleanup.js";
+import { bootstrapMemoryUpgradeSchema } from "./memory-upgrade-schema-bootstrap.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("paired_storage_migration_invalid", "Reconcile the exact paired migration; recovery is a separate operation", 1, { reason, effect: "unknown", next_action: "reconcile_exact_request" });
+}
+function canonical(file) {
+    if (!path.isAbsolute(file) || path.join(fs.realpathSync(path.dirname(file)), path.basename(file)) !== file)
+        refuse("noncanonical_path");
+    return file;
+}
+function children(intent) {
+    return intent.stores.map(store => {
+        const bytes = Buffer.from(store.input.base64, "base64");
+        if (bytes.toString("base64") !== store.input.base64)
+            refuse("invalid_child_bytes");
+        const value = JSON.parse(bytes.toString("utf8"));
+        if (value.database !== store.database || value.backup !== store.backup || value.request_id !== `${intent.request_id}.${store.kind}`)
+            refuse("foreign_child_scope");
+        return PreparedStoreWriterMigration.restoreInput(store.input.path, bytes.toString("utf8"), store.input.sha256);
+    });
+}
+/** Existing logical drain plus actual physical owner observation. Never kills
+ * a process or infers drain from expired/terminal metadata alone. */
+export function observeDrainedMigrationStores(stores) {
+    const observations = [];
+    for (const store of stores) {
+        const db = new DatabaseSync(store.database, { readOnly: true });
+        try {
+            db.exec("BEGIN");
+            assertStoreWriterDrain(db);
+            let processes = 0;
+            if (db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='managed_processes'").get())
+                for (const row of db.prepare("SELECT * FROM managed_processes").all()) {
+                    processes++;
+                    if (processTreeIsAlive(row))
+                        refuse("physical_owner_alive");
+                }
+            observations.push({ database: store.database, unsettled_writers: 0, live_processes: 0, registered_processes: processes });
+        }
+        finally {
+            db.close();
+        }
+    }
+    return observations;
+}
+const drained = observeDrainedMigrationStores;
+const evidenceKinds = ["writer-drain", "storage-backup", "storage-plan", "storage-apply", "storage-verification"];
+function schemaStep(intent) { return intent.bootstrap_schema ? { bootstrap_schema: intent.bootstrap_schema } : {}; }
+function plannedStores(intent) {
+    return intent.stores.map(store => ({ kind: store.kind, database: store.database, backup: store.backup,
+        source_request_sha256: store.input.sha256, ...schemaStep(intent) }));
+}
+/** Two existing one-store migrations under the existing shared admission fence.
+ * Default is writer-only. Memory upgrade may explicitly bind the executing
+ * engine's fixed additive bootstrap; it runs under the same retained permits,
+ * backup and old-data verification, never as a readonly admission side effect. */
+export class PreparedPairedWriterMigration {
+    sha256;
+    #file;
+    #intent;
+    #children;
+    constructor(file, intent) {
+        this.#file = file;
+        this.#intent = structuredClone(intent);
+        this.#children = children(intent);
+        const bytes = JSON.stringify(intent);
+        if (Buffer.byteLength(bytes) > 16 * 1024 * 1024)
+            refuse("intent_exceeds_bound");
+        this.sha256 = hash(bytes);
+        Object.freeze(this);
+    }
+    static prepare(input) {
+        if (input.bootstrapSchema !== undefined && input.bootstrapSchema !== "memory-upgrade@1")
+            refuse("unsupported_schema_bootstrap");
+        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,85}$/.test(input.requestId) || !/^[a-f0-9]{64}$/.test(input.selectionSha256))
+            refuse("invalid_identity");
+        const file = canonical(input.requestFile);
+        if (fs.existsSync(file) || fs.existsSync(file + ".result.json"))
+            refuse("restore_original_request");
+        for (const root of [input.projectRoot, input.workspaceRoot, input.runHome, input.resourceHome])
+            if (fs.realpathSync(root) !== root || !fs.statSync(root).isDirectory())
+                refuse("noncanonical_scope");
+        const stores = ["run", "resource"].map(kind => {
+            const home = kind === "run" ? input.runHome : input.resourceHome;
+            const database = path.join(home, kind === "run" ? "db.sqlite" : "runtime.sqlite"), backup = `${file}.${kind}.backup.sqlite`;
+            const child = PreparedStoreWriterMigration.prepare({ requestId: `${input.requestId}.${kind}`, requestFile: `${file}.${kind}.json`, database, backup });
+            return { kind, home, database, backup, input: child.inputArtifact() };
+        });
+        const occupied = stores.flatMap(store => [store.database, store.database + "-wal", store.database + "-shm", store.database + "-journal", importGuardPath(store.home), importGuardPath(store.home) + ".lock"]);
+        if (stores.some(store => occupied.includes(store.backup) || occupied.includes(store.input.path)) || occupied.includes(file) || occupied.includes(file + ".result.json"))
+            refuse("path_alias");
+        if (stores.every(store => JSON.parse(Buffer.from(store.input.base64, "base64").toString("utf8")).source.writer_version === STORE_WRITER_VERSION))
+            refuse("content_only_route_required");
+        drained(stores);
+        return new PreparedPairedWriterMigration(file, { schema_id: "dd-flow/paired-writer-migration@1", request_id: input.requestId,
+            permit_id: randomUUID(), selection_sha256: input.selectionSha256, project_root: input.projectRoot, workspace_root: input.workspaceRoot, stores,
+            ...(input.bootstrapSchema ? { bootstrap_schema: input.bootstrapSchema } : {}) });
+    }
+    static restore(file, expectedSha256) {
+        canonical(file);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024 * 1024)
+            refuse("invalid_intent_file");
+        const bytes = fs.readFileSync(file, "utf8");
+        if (!/^[a-f0-9]{64}$/.test(expectedSha256) || hash(bytes) !== expectedSha256)
+            refuse("intent_changed");
+        const intent = JSON.parse(bytes);
+        if (Object.keys(intent).sort().join() !== ["permit_id", "project_root", "request_id", "schema_id", "selection_sha256", "stores", "workspace_root",
+            ...(intent.bootstrap_schema !== undefined ? ["bootstrap_schema"] : [])].sort().join()
+            || intent.bootstrap_schema !== undefined && intent.bootstrap_schema !== "memory-upgrade@1"
+            || intent.schema_id !== "dd-flow/paired-writer-migration@1" || !/^[0-9a-f-]{36}$/.test(intent.permit_id)
+            || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,85}$/.test(intent.request_id) || !/^[a-f0-9]{64}$/.test(intent.selection_sha256)
+            || !Array.isArray(intent.stores) || intent.stores.length !== 2 || intent.stores[0]?.kind !== "run" || intent.stores[1]?.kind !== "resource")
+            refuse("invalid_intent");
+        for (const store of intent.stores) {
+            if (Object.keys(store).sort().join() !== "backup,database,home,input,kind" || Object.keys(store.input).sort().join() !== "base64,path,sha256"
+                || fs.realpathSync(store.home) !== store.home || !fs.statSync(store.home).isDirectory()
+                || store.database !== path.join(store.home, store.kind === "run" ? "db.sqlite" : "runtime.sqlite")
+                || store.backup !== `${file}.${store.kind}.backup.sqlite` || store.input.path !== `${file}.${store.kind}.json`)
+                refuse("foreign_store_binding");
+        }
+        const prepared = new PreparedPairedWriterMigration(file, intent);
+        if (prepared.sha256 !== expectedSha256)
+            refuse("intent_changed");
+        return prepared;
+    }
+    retain() {
+        canonical(this.#file);
+        // Parent first: a crash before child publication can be reconstructed from
+        // these independently retained exact bytes without selecting new sources.
+        publishImmutableInput(this.#file, Buffer.from(JSON.stringify(this.#intent)), "paired_migration_request_conflict");
+        for (const child of this.#children)
+            child.retain();
+        return { request_file: this.#file, sha256: this.sha256, selection_sha256: this.#intent.selection_sha256 };
+    }
+    reconcile() {
+        // Physical outcomes only: "applied" does not itself release admission.
+        const outcomes = this.#children.map(child => child.reconcile());
+        const count = outcomes.filter(outcome => outcome.status === "applied").length;
+        return { status: outcomes.some(outcome => outcome.status === "unknown") ? "unknown" : count === 2 ? "applied" : count ? "partial" : "not_applied", outcomes };
+    }
+    recoveryMaterial() { return { file: this.#file, sha256: this.sha256, intent: structuredClone(this.#intent), children: [...this.#children] }; }
+    apply() {
+        const lease = acquireInstallationLock(this.#file + ".lock", this.sha256);
+        return withStoreCleanup(() => this.applyLocked(lease.assertOwnership), () => lease.release());
+    }
+    applyLocked(assertOwnership) {
+        assertOwnership();
+        if (fs.existsSync(this.#file + ".recovery.json"))
+            refuse("recovery_selected");
+        for (const store of this.#intent.stores)
+            canonical(store.database);
+        this.retain();
+        const before = this.reconcile();
+        if (before.status === "unknown")
+            refuse("unknown_child_outcome");
+        const resultFile = this.#file + ".result.json";
+        if (fs.existsSync(resultFile) && before.status !== "applied")
+            refuse("completed_migration_changed");
+        const scope = { projectRoot: this.#intent.project_root, workspaceRoot: this.#intent.workspace_root, sourceManifestSha256: this.sha256, importId: this.#intent.permit_id };
+        const homes = [...new Set(this.#intent.stores.map(store => store.home))];
+        for (const home of homes)
+            beginStorageMaintenance({ home, ...scope });
+        let evidence;
+        if (!fs.existsSync(resultFile)) {
+            const drain = drained(this.#intent.stores);
+            for (const child of this.#children) {
+                assertOwnership();
+                drained(this.#intent.stores);
+                child.backup();
+            }
+            const backups = this.#children.map(child => child.backupFacts());
+            for (const child of this.#children) {
+                assertOwnership();
+                drained(this.#intent.stores);
+                child.apply();
+            }
+            if (this.#intent.bootstrap_schema) {
+                assertOwnership();
+                drained(this.#intent.stores);
+                bootstrapMemoryUpgradeSchema(this.#intent.stores[0].home, this.#intent.stores[1].home, this.#intent.permit_id);
+            }
+            const verification = this.#children.map(child => ({ ...child.verifyAppliedData(), ...schemaStep(this.#intent) }));
+            const applied = this.reconcile();
+            if (applied.status !== "applied")
+                refuse("verification_incomplete");
+            const plans = plannedStores(this.#intent);
+            const stores = plans.map((store, i) => ({ ...store,
+                receipt_sha256: hash(JSON.stringify(applied.outcomes[i].receipt)) }));
+            const payloads = [drain, backups, plans, stores, verification];
+            evidence = evidenceKinds.map((kind, i) => {
+                const bytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/paired-storage-evidence@1", kind, request_sha256: this.sha256,
+                    selection_sha256: this.#intent.selection_sha256, stores: payloads[i] }));
+                return { kind, path: `receipts/${kind}.json`, sha256: hash(bytes), base64: bytes.toString("base64") };
+            });
+        }
+        else
+            evidence = this.readEvidence().evidence;
+        const after = this.reconcile();
+        if (after.status !== "applied")
+            refuse("verification_incomplete");
+        const receipt = { schema_id: "dd-flow/paired-writer-migration-result@2", request_sha256: this.sha256,
+            selection_sha256: this.#intent.selection_sha256, stores: this.#intent.stores.map((store, i) => ({ kind: store.kind, database: store.database, backup: store.backup,
+                receipt_sha256: hash(JSON.stringify(after.outcomes[i].receipt)) })), evidence };
+        publishImmutableInput(resultFile, Buffer.from(JSON.stringify(receipt)), "paired_migration_result_conflict");
+        for (const home of homes)
+            completeStorageMaintenance({ home, ...scope });
+        return receipt;
+    }
+    /** Historical evidence is verified against original request/backup custody,
+     * not re-issued from today's mutable runtime data after bootstrap writes. */
+    readEvidence() {
+        if (fs.existsSync(this.#file + ".recovery.json"))
+            refuse("recovery_selected");
+        const file = this.#file + ".result.json", stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            refuse("invalid_migration_evidence_file");
+        const bytes = fs.readFileSync(file), receipt = JSON.parse(bytes.toString("utf8")), observed = this.reconcile();
+        if (observed.status !== "applied" || receipt.schema_id !== "dd-flow/paired-writer-migration-result@2" || receipt.request_sha256 !== this.sha256
+            || receipt.selection_sha256 !== this.#intent.selection_sha256 || !Array.isArray(receipt.evidence) || receipt.evidence.length !== evidenceKinds.length
+            || JSON.stringify(receipt.stores) !== JSON.stringify(this.#intent.stores.map((store, i) => ({ kind: store.kind, database: store.database, backup: store.backup,
+                receipt_sha256: hash(JSON.stringify(observed.outcomes[i].receipt)) }))))
+            refuse("migration_evidence_custody_changed");
+        const evidence = receipt.evidence;
+        for (let i = 0; i < evidence.length; i++) {
+            const entry = evidence[i], raw = Buffer.from(entry.base64, "base64"), value = JSON.parse(raw.toString("utf8"));
+            if (entry.kind !== evidenceKinds[i] || entry.path !== `receipts/${entry.kind}.json` || raw.toString("base64") !== entry.base64 || hash(raw) !== entry.sha256
+                || value.schema_id !== "dd-flow/paired-storage-evidence@1" || value.kind !== entry.kind || value.request_sha256 !== this.sha256
+                || value.selection_sha256 !== this.#intent.selection_sha256 || !Array.isArray(value.stores) || value.stores.length !== 2
+                || value.stores.some((store, index) => store.database !== this.#intent.stores[index].database))
+                refuse("migration_evidence_changed");
+        }
+        const backups = this.#children.map(child => child.backupFacts());
+        const facts = evidence.map(entry => JSON.parse(Buffer.from(entry.base64, "base64").toString("utf8")).stores);
+        if (JSON.stringify(facts[1]) !== JSON.stringify(backups))
+            refuse("backup_evidence_changed");
+        const plans = plannedStores(this.#intent);
+        const applies = plans.map((store, i) => ({ ...store, receipt_sha256: hash(JSON.stringify(observed.outcomes[i].receipt)) }));
+        const verification = backups.map(store => ({ database: store.database, source_request_sha256: store.source_request_sha256,
+            writer_version: STORE_WRITER_VERSION, source_data_sha256: store.source_data_sha256, integrity: "ok", foreign_key_violations: 0, ...schemaStep(this.#intent) }));
+        if (JSON.stringify(facts[2]) !== JSON.stringify(plans) || JSON.stringify(facts[3]) !== JSON.stringify(applies)
+            || JSON.stringify(facts[4]) !== JSON.stringify(verification)
+            || facts[0].some((store) => store.unsettled_writers !== 0 || store.live_processes !== 0 || !Number.isSafeInteger(store.registered_processes) || store.registered_processes < 0))
+            refuse("migration_evidence_changed");
+        return { reference: { path: file, sha256: hash(bytes) }, evidence: structuredClone(evidence) };
+    }
+}
+function assertOriginal(child, store) {
+    child.recoveryReference();
+    const db = new DatabaseSync(store.database, { readOnly: true });
+    try {
+        db.exec("BEGIN");
+        child.assertOriginal(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/** Separate, explicitly selected recovery. A never-applied child is verified
+ * against its original state, not restored from a nonexistent backup. */
+export class PreparedPairedWriterRecovery {
+    sha256;
+    #file;
+    #migration;
+    #intent;
+    #restores;
+    constructor(migration, file, intent) {
+        this.#file = file;
+        this.#migration = migration;
+        this.#intent = structuredClone(intent);
+        const material = migration.recoveryMaterial();
+        this.#restores = intent.stores.map((store, i) => {
+            if (Object.keys(store).sort().join() !== "input,kind" || store.kind !== material.intent.stores[i].kind)
+                refuse("recovery_child_scope_changed");
+            if (store.input === null)
+                return null;
+            if (!store.input || Object.keys(store.input).sort().join() !== "base64,path,sha256")
+                refuse("recovery_child_scope_changed");
+            const bytes = Buffer.from(store.input.base64, "base64");
+            if (store.input.path !== `${file}.${store.kind}.json` || bytes.toString("base64") !== store.input.base64
+                || JSON.parse(bytes.toString("utf8")).recovery_id !== `${intent.recovery_id}.${store.kind}`)
+                refuse("recovery_child_scope_changed");
+            return PreparedStoreWriterRestore.restoreInput(material.children[i], store.input.path, bytes.toString("utf8"), store.input.sha256);
+        });
+        const bytes = JSON.stringify(intent);
+        if (Buffer.byteLength(bytes) > 128 * 1024)
+            refuse("recovery_intent_exceeds_bound");
+        this.sha256 = hash(bytes);
+        Object.freeze(this);
+    }
+    migrationReference() { return { ...this.#intent.migration }; }
+    static prepare(migration, recoveryId) {
+        if (!(migration instanceof PreparedPairedWriterMigration) || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,85}$/.test(recoveryId))
+            refuse("invalid_recovery_identity");
+        const material = migration.recoveryMaterial(), file = material.file + ".recovery.json";
+        const lease = acquireInstallationLock(material.file + ".lock", material.sha256);
+        return withStoreCleanup(() => {
+            lease.assertOwnership();
+            if (fs.existsSync(file) || fs.existsSync(file + ".result.json"))
+                refuse("restore_original_recovery");
+            migration.retain();
+            drained(material.intent.stores);
+            const stores = material.intent.stores.map((store, i) => {
+                const child = material.children[i];
+                try {
+                    assertOriginal(child, store);
+                    return { kind: store.kind, input: null };
+                }
+                catch (error) {
+                    if (!(error instanceof AppError) || error.code !== "store_migration_outcome_unknown" || error.details.reason !== "source_changed")
+                        throw error;
+                }
+                if (!fs.existsSync(store.backup))
+                    refuse("changed_store_has_no_backup");
+                const restore = PreparedStoreWriterRestore.prepare(child, { recoveryId: `${recoveryId}.${store.kind}`, requestFile: `${file}.${store.kind}.json` });
+                return { kind: store.kind, input: restore.inputArtifact() };
+            });
+            return new PreparedPairedWriterRecovery(migration, file, { schema_id: "dd-flow/paired-writer-recovery@1", recovery_id: recoveryId,
+                migration: { path: material.file, sha256: material.sha256 }, stores });
+        }, () => lease.release());
+    }
+    static restore(file, expectedSha256) {
+        canonical(file);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 128 * 1024)
+            refuse("invalid_recovery_intent");
+        const bytes = fs.readFileSync(file, "utf8");
+        if (hash(bytes) !== expectedSha256)
+            refuse("recovery_intent_changed");
+        const intent = JSON.parse(bytes);
+        if (Object.keys(intent).sort().join() !== "migration,recovery_id,schema_id,stores" || intent.schema_id !== "dd-flow/paired-writer-recovery@1"
+            || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,85}$/.test(intent.recovery_id) || Object.keys(intent.migration).sort().join() !== "path,sha256"
+            || file !== intent.migration.path + ".recovery.json"
+            || !Array.isArray(intent.stores) || intent.stores.length !== 2)
+            refuse("invalid_recovery_intent");
+        const migration = PreparedPairedWriterMigration.restore(intent.migration.path, intent.migration.sha256);
+        const prepared = new PreparedPairedWriterRecovery(migration, file, intent);
+        if (prepared.sha256 !== expectedSha256)
+            refuse("recovery_intent_changed");
+        return prepared;
+    }
+    retainLocked() {
+        canonical(this.#file);
+        this.#migration.retain();
+        const material = this.#migration.recoveryMaterial();
+        drained(material.intent.stores);
+        for (let i = 0; i < this.#restores.length; i++) {
+            const restore = this.#restores[i];
+            if (restore)
+                restore.revalidatePrepared();
+            else
+                assertOriginal(material.children[i], material.intent.stores[i]);
+        }
+        publishImmutableInput(this.#file, Buffer.from(JSON.stringify(this.#intent)), "paired_recovery_request_conflict");
+        // Selecting recovery fences the drained stores before returning its prepared
+        // apply command; it is not a promise to restore while new writers keep running.
+        for (const home of new Set(material.intent.stores.map(store => store.home)))
+            beginStorageRecovery({ home,
+                projectRoot: material.intent.project_root, workspaceRoot: material.intent.workspace_root, importId: material.intent.permit_id,
+                originalSha256: material.sha256, recoverySha256: this.sha256 });
+        for (const restore of this.#restores)
+            restore?.retain();
+        return { request_file: this.#file, sha256: this.sha256, migration_sha256: material.sha256 };
+    }
+    retain() {
+        const material = this.#migration.recoveryMaterial(), lease = acquireInstallationLock(material.file + ".lock", material.sha256);
+        return withStoreCleanup(() => { lease.assertOwnership(); return this.retainLocked(); }, () => lease.release());
+    }
+    /** Read-only physical outcome, not proof that admission was reopened. */
+    reconcile() {
+        const material = this.#migration.recoveryMaterial();
+        const outcomes = this.#restores.map((restore, i) => {
+            if (restore)
+                return { kind: material.intent.stores[i].kind, ...restore.reconcile() };
+            try {
+                assertOriginal(material.children[i], material.intent.stores[i]);
+                return { kind: material.intent.stores[i].kind, status: "restored" };
+            }
+            catch (error) {
+                return { kind: material.intent.stores[i].kind, status: "unknown", reason: error instanceof AppError ? String(error.details.reason ?? error.code) : "source_unavailable" };
+            }
+        });
+        return { status: outcomes.some(outcome => outcome.status === "unknown") ? "unknown" : outcomes.every(outcome => outcome.status === "restored") ? "restored" : "not_restored", outcomes };
+    }
+    apply() {
+        const material = this.#migration.recoveryMaterial(), lease = acquireInstallationLock(material.file + ".lock", material.sha256);
+        return withStoreCleanup(() => {
+            lease.assertOwnership();
+            this.retainLocked();
+            const scope = { projectRoot: material.intent.project_root, workspaceRoot: material.intent.workspace_root, importId: material.intent.permit_id };
+            const homes = [...new Set(material.intent.stores.map(store => store.home))];
+            const stores = this.#restores.map((restore, i) => {
+                lease.assertOwnership();
+                drained(material.intent.stores);
+                if (!restore) {
+                    assertOriginal(material.children[i], material.intent.stores[i]);
+                    return { kind: material.intent.stores[i].kind, status: "unchanged", migration_sha256: material.children[i].sha256 };
+                }
+                const receipt = restore.apply();
+                if (restore.reconcile().status !== "restored")
+                    refuse("recovery_readback_failed");
+                return { kind: material.intent.stores[i].kind, status: "restored", receipt_sha256: hash(JSON.stringify(receipt)) };
+            });
+            const receipt = { schema_id: "dd-flow/paired-writer-recovery-result@1", request_sha256: this.sha256, migration_sha256: material.sha256, stores };
+            publishImmutableInput(this.#file + ".result.json", Buffer.from(JSON.stringify(receipt)), "paired_recovery_result_conflict");
+            for (const home of homes)
+                completeStorageMaintenance({ home, ...scope, sourceManifestSha256: this.sha256 });
+            return receipt;
+        }, () => lease.release());
+    }
+}

package/dist/storage/paths.js

@@ -15,6 +15,8 @@ export function resolveProjectRoot(root) {
     if (!fs.existsSync(absolute)) {
         throw new AppError("not_found", `Project root does not exist: ${absolute}`, 1);
     }
+    if (!fs.statSync(absolute).isDirectory())
+        throw new AppError("validation", "Project root must be a directory", 2, { project_root: absolute });
     return fs.realpathSync(absolute);
 }
 /** Resolve an existing path to its filesystem identity, or normalize a future path. */
@@ -24,10 +26,16 @@ export function canonicalPath(value, mustExist = true) {
         return fs.realpathSync(absolute);
     if (mustExist)
         throw new AppError("not_found", `Path does not exist: ${absolute}`, 1, { path: absolute });
-    const parent = path.dirname(absolute);
-    if (!fs.existsSync(parent))
-        return absolute;
-    return path.join(fs.realpathSync(parent), path.basename(absolute));
+    const missing = [];
+    let parent = absolute;
+    while (!fs.existsSync(parent)) {
+        missing.unshift(path.basename(parent));
+        const next = path.dirname(parent);
+        if (next === parent)
+            return absolute;
+        parent = next;
+    }
+    return path.join(fs.realpathSync(parent), ...missing);
 }
 export function assertPathWithin(root, candidate, label = "path") {
     const canonicalRoot = canonicalPath(root);
@@ -100,6 +108,11 @@ export function stateJsonPath(projectRoot, protocolId) {
 export function planJsonPath(projectRoot, protocolId) {
     return path.join(protocolDir(projectRoot, protocolId), "plan.json");
 }
+/** Project canonical plan takes precedence over a retained workspace location. */
+export function resolveProtocolPlanPath(projectRoot, protocolId, recordedPath) {
+    const canonical = planJsonPath(projectRoot, protocolId);
+    return fs.existsSync(canonical) ? canonical : recordedPath;
+}
 export function projectHome(ddFlowHome, projectId) {
     return path.join(ddFlowHome, "projects", projectId);
 }

package/dist/storage/projection-lock.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { processStartedAt } from "../services/managed-processes.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+/** One filesystem publisher per entity; no SQLite writer is held while waiting. */
+export function withProjectionLock(lockPath, operation) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const owner = { pid: process.pid, started_at: selfStartedAt() };
+    const wait = new Int32Array(new SharedArrayBuffer(4));
+    const observed = new Map();
+    for (let tries = 0;; tries++) {
+        try {
+            fs.mkdirSync(lockPath);
+            try {
+                fs.writeFileSync(`${lockPath}/owner.json`, JSON.stringify(owner));
+            }
+            catch (error) {
+                fs.rmdirSync(lockPath);
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let stale = false;
+            let observedInode;
+            try {
+                observedInode = fs.statSync(lockPath).ino;
+                const current = JSON.parse(fs.readFileSync(`${lockPath}/owner.json`, "utf8"));
+                try {
+                    process.kill(current.pid, 0);
+                    if (!observed.has(current.pid))
+                        observed.set(current.pid, processStartedAt(current.pid));
+                    stale = Boolean(current.started_at && observed.get(current.pid) !== current.started_at);
+                }
+                catch (probe) {
+                    stale = probe.code === "ESRCH";
+                }
+            }
+            catch {
+                stale = false;
+            }
+            if (stale) {
+                try {
+                    if (observedInode !== undefined && fs.statSync(lockPath).ino === observedInode) {
+                        const moved = `${lockPath}.stale-${crypto.randomUUID()}`;
+                        fs.renameSync(lockPath, moved);
+                        fs.rmSync(moved, { recursive: true });
+                    }
+                }
+                catch { /* Another publisher may own it now. */ }
+                continue;
+            }
+            if (tries >= 80)
+                throw new AppError("publication_pending", "Projection publisher is busy", 1, { effect: "committed", lock_path: lockPath });
+            Atomics.wait(wait, 0, 0, 50);
+        }
+    }
+    try {
+        return operation();
+    }
+    catch (error) {
+        throw new AppError("publication_pending", "Committed projection needs reconciliation", 1, { effect: "committed", cause: errorRecord(error), lock_path: lockPath });
+    }
+    finally {
+        fs.rmSync(lockPath, { recursive: true, force: true });
+    }
+}
+let ownStart;
+function selfStartedAt() { if (ownStart === undefined)
+    ownStart = processStartedAt(process.pid); return ownStart; }

package/dist/storage/work-references.js

@@ -0,0 +1,23 @@
+import { AppError } from "../shared/errors.js";
+/** Read-only lookup; scope applies to exact IDs as well as short aliases. */
+export function resolveWorkReference(context, id, scope = {}) {
+    const clauses = ["1 = 1"];
+    const params = [];
+    if (scope.projectId) {
+        clauses.push("project_id = ?");
+        params.push(scope.projectId);
+    }
+    if (scope.runId) {
+        clauses.push("run_id = ?");
+        params.push(scope.runId);
+    }
+    const where = clauses.join(" AND ");
+    const exact = context.db.get(`SELECT * FROM works WHERE ${where} AND work_id = ?`, [...params, id]);
+    if (exact)
+        return exact;
+    const matches = /^WRK-\d{3,}$/.test(id)
+        ? context.db.all(`SELECT * FROM works WHERE ${where} AND work_id LIKE ? ORDER BY work_id`, [...params, `${id}-%`]) : [];
+    if (matches.length !== 1)
+        throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous in the current RUN" : "Work is not registered in the current RUN", 1, { work_id: id, matches: matches.map(work => work.work_id) });
+    return matches[0];
+}

package/dist/storage/writer-contract.js

@@ -0,0 +1,96 @@
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { rollbackStoreTransaction } from "./native-cleanup.js";
+export const STORE_WRITER_VERSION = 2;
+const version = STORE_WRITER_VERSION;
+const table = "dd_flow_writer_contract";
+const admissions = new WeakMap();
+/** Change admission without adopting a different writer version after cutover. */
+export function bindStoreWriterAdmission(db, admission) { admissions.set(db, admission); }
+const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+/** The executing writer's fence definition, also used for readonly admission. */
+export function storeWriterTriggerSql(name, action) {
+    const key = crypto.createHash("sha256").update(name).digest("hex").slice(0, 24);
+    const trigger = `dd_flow_writer_${key}_${action.toLowerCase()}`;
+    return { name: trigger, sql: `CREATE TRIGGER ${quote(trigger)} BEFORE ${action} ON ${quote(name)} BEGIN
+          SELECT CASE WHEN dd_flow_writer_version() <> (SELECT version FROM ${table} WHERE id = 1)
+            OR (SELECT COUNT(*) FROM ${table}) <> 1 THEN RAISE(ABORT, 'store_writer_incompatible') END;
+        END;` };
+}
+/** Publish additive schema and its writer fences in the same transaction. */
+export function executeStoreSchema(db, sql, initialize = false) {
+    const ownsTransaction = !db.isTransaction;
+    db.exec(ownsTransaction ? "BEGIN IMMEDIATE" : "SAVEPOINT dd_flow_schema_change");
+    try {
+        const protectedStore = readStoreWriterContract(db) !== null;
+        if (initialize && !protectedStore && db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get()) {
+            throw new AppError("store_initialization_conflict", "Another writer initialized this store; explicit migration is required", 1);
+        }
+        const before = db.prepare("PRAGMA schema_version").get();
+        if (typeof sql === "string")
+            db.exec(sql);
+        else
+            sql();
+        const after = db.prepare("PRAGMA schema_version").get();
+        if (initialize || (protectedStore && before.schema_version !== after.schema_version))
+            installStoreWriterContract(db);
+        db.exec(ownsTransaction ? "COMMIT" : "RELEASE dd_flow_schema_change");
+    }
+    catch (error) {
+        rollbackStoreTransaction(db, ownsTransaction ? "ROLLBACK" : "ROLLBACK TO dd_flow_schema_change; RELEASE dd_flow_schema_change", error);
+    }
+}
+/** Registration is connection-local and never changes historical input bytes. */
+export function registerStoreWriter(db, admission) {
+    const current = readStoreWriterContract(db);
+    if (current !== null && current !== version)
+        throw new AppError("store_writer_incompatible", "This CLI cannot write the store's required contract", 1, { required: current, supported: version });
+    if (admission)
+        admissions.set(db, admission);
+    db.function("dd_flow_writer_version", () => { admissions.get(db)?.(); return version; });
+}
+/** Health maintenance uses only verified legacy lifecycle columns and never
+ * migrates schema. Keep the retained writer fence, including version 1. */
+export function registerReconciliationWriter(db, admission) {
+    const current = readStoreWriterContract(db);
+    if (current !== null && current !== 1 && current !== version)
+        throw new AppError("store_writer_incompatible", "Unsupported reconciliation writer contract", 1, { required: current, supported: [1, version] });
+    if (admission)
+        admissions.set(db, admission);
+    db.function("dd_flow_writer_version", () => { admissions.get(db)?.(); return current ?? version; });
+}
+export function readStoreWriterContract(db) {
+    if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table))
+        return null;
+    const rows = db.prepare(`SELECT id, version FROM ${table}`).all();
+    if (rows.length !== 1 || rows[0]?.id !== 1 || !Number.isSafeInteger(rows[0].version) || rows[0].version < 1)
+        throw new AppError("store_writer_contract_invalid", "Store writer contract is malformed", 1);
+    return rows[0].version;
+}
+/** Install only at an explicit migration boundary; ordinary reads never call it. */
+export function installStoreWriterContract(db) {
+    registerStoreWriter(db);
+    const ownsTransaction = !db.isTransaction;
+    if (ownsTransaction)
+        db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`CREATE TABLE IF NOT EXISTS ${table} (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL);
+      INSERT OR IGNORE INTO ${table} (id, version) VALUES (1, ${version});`);
+        if (readStoreWriterContract(db) !== version)
+            throw new AppError("store_writer_incompatible", "Store writer contract changed before migration", 1);
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
+        for (const target of tables) {
+            for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+                const trigger = storeWriterTriggerSql(target.name, action);
+                db.exec(`DROP TRIGGER IF EXISTS ${quote(trigger.name)}; ${trigger.sql}`);
+            }
+        }
+        if (ownsTransaction)
+            db.exec("COMMIT");
+    }
+    catch (error) {
+        if (ownsTransaction)
+            rollbackStoreTransaction(db, "ROLLBACK", error);
+        throw error;
+    }
+}