@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

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/writer-contract.js

@@ -4,6 +4,9 @@ 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) {
@@ -38,19 +41,23 @@ export function executeStoreSchema(db, sql, initialize = false) {
     }
 }
 /** Registration is connection-local and never changes historical input bytes. */
-export function registerStoreWriter(db) {
+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 });
-    db.function("dd_flow_writer_version", () => 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) {
+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] });
-    db.function("dd_flow_writer_version", () => current ?? 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))