@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/services/memory-upgrade-storage-readiness.js

@@ -0,0 +1,340 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { assertUpgradeRunStorageReady } from "./migrations.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { restoreMemoryUpgradeSelection, restoreMemoryUpgradeSelectionData, decodeMemoryUpgradeSelection } from "./memory-upgrade-selection.js";
+import { prepareMemoryUpgradeInventory, matchesRetainedMemoryUpgradeInventory } from "./memory-upgrade-inventory.js";
+import { observeDescriptorWorkspace } from "./descriptor-run-start.js";
+import { PreparedMemoryInitRuntimeStorage } from "./memory-init-storage.js";
+import { PreparedMemoryInitResourceStorage } from "./memory-init-resource-storage.js";
+import { resourceHome } from "./managed-processes.js";
+import semver from "semver";
+import { PreparedMemoryLayer } from "./memory-layer.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { observeMemoryGitPolicySelection } from "./memory-init-git-policy.js";
+import { readRunStartRequest, hasRunStartTable } from "./run-start-custody.js";
+import { runContextRelocations, projectPacketLocators } from "./stage-context.js";
+// One historical decode per connection. SQL bytes, logical scope and audit
+// custody are still observed on every read; callers receive private copies.
+const retainedDecodes = new WeakMap();
+function refuse(reason) {
+    throw new AppError("upgrade_storage_request_invalid", "Upgrade storage readiness must retain its original request", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+function project(context, scope) {
+    if (!scope || Object.keys(scope).sort().join() !== "projectRoot,requestId,workspaceRoot"
+        || typeof scope.requestId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId))
+        refuse("invalid_scope");
+    if ([scope.projectRoot, scope.workspaceRoot].some(root => typeof root !== "string" || !path.isAbsolute(root) || path.resolve(root) !== root))
+        refuse("invalid_scope");
+    const selected = context.db.get("SELECT id FROM projects WHERE root = ? AND status = 'active'", [scope.projectRoot]);
+    if (selected)
+        return selected.id;
+    const candidates = hasRunStartTable(context) ? context.db.all("SELECT p.id,p.root,s.run_id FROM projects p JOIN run_start_requests s ON s.project_id=p.id WHERE p.status='active' AND s.request_id=? AND json_extract(s.payload_json,'$.project_root')=? AND json_extract(s.payload_json,'$.workspace_root')=?", [scope.requestId, scope.projectRoot, scope.workspaceRoot]) : [];
+    const matches = candidates.filter(row => {
+        const request = readRunStartRequest(context, row.id, scope.requestId);
+        return request?.published && request.payload.initial_index.flow_kind === 'mb-upgrade'
+            && projectPacketLocators(scope.projectRoot, runContextRelocations(context, row.id, row.run_id)) === row.root;
+    });
+    if (matches.length !== 1)
+        refuse("project_not_active");
+    return matches[0].id;
+}
+/** Physical imports use the source request's immutable logical scope. This is
+ * a historical read projection, never new storage/RUN admission. */
+export function resolveUpgradeHistoricalScope(context, scope) {
+    const projectId = project(context, scope);
+    const row = hasRunStartTable(context) ? context.db.get("SELECT run_id FROM run_start_requests WHERE project_id=? AND request_id=?", [projectId, scope.requestId]) : undefined;
+    const relocations = row ? runContextRelocations(context, projectId, row.run_id) : [];
+    if (relocations.length) {
+        const request = readRunStartRequest(context, projectId, scope.requestId);
+        if (request?.published && request.payload.initial_index.flow_kind === 'mb-upgrade') {
+            const original = { requestId: scope.requestId, projectRoot: request.payload.project_root, workspaceRoot: request.payload.workspace_root };
+            if (projectPacketLocators(original.projectRoot, relocations) === scope.projectRoot && projectPacketLocators(original.workspaceRoot, relocations) === scope.workspaceRoot)
+                return { projectId, scope: original };
+        }
+    }
+    return { projectId, scope };
+}
+function scopeDirectories(scope) {
+    for (const root of [scope.projectRoot, scope.workspaceRoot]) {
+        try {
+            if (typeof root !== "string" || fs.realpathSync(root) !== root || !fs.statSync(root).isDirectory())
+                refuse("noncanonical_scope");
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            refuse("scope_unavailable");
+        }
+    }
+}
+const key = (projectId, requestId) => `mb-upgrade.storage.${projectId}.${requestId}`;
+/** The selected engine issues these facts; SQL custody preserves them after
+ * the pre-context files are retired. Never rebuild historical evidence. */
+export function upgradeStorageMigration(value, selectionSha256) {
+    const migration = value, sha = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+    if (!migration || !migration.request || !path.isAbsolute(migration.request.path) || !sha(migration.request.sha256)
+        || !migration.proof?.reference || migration.proof.reference.path !== migration.request.path + ".result.json"
+        || !sha(migration.proof.reference.sha256) || !Array.isArray(migration.proof.evidence) || migration.proof.evidence.length !== 5)
+        refuse("invalid_migration_proof");
+    const kinds = ["writer-drain", "storage-backup", "storage-plan", "storage-apply", "storage-verification"];
+    migration.proof.evidence.forEach((entry, index) => {
+        if (!entry || typeof entry.base64 !== "string" || entry.base64.length > 1024 * 1024)
+            refuse("invalid_migration_evidence");
+        const raw = Buffer.from(entry.base64, "base64");
+        if (entry.kind !== kinds[index] || entry.path !== `receipts/${entry.kind}.json` || raw.toString("base64") !== entry.base64
+            || createHash("sha256").update(raw).digest("hex") !== entry.sha256)
+            refuse("invalid_migration_evidence");
+        let evidence;
+        try {
+            evidence = JSON.parse(raw.toString("utf8"));
+        }
+        catch {
+            return refuse("invalid_migration_evidence");
+        }
+        if (evidence.schema_id !== "dd-flow/paired-storage-evidence@1" || evidence.kind !== entry.kind
+            || evidence.request_sha256 !== migration.request.sha256 || evidence.selection_sha256 !== selectionSha256)
+            refuse("foreign_migration_evidence");
+    });
+    return migration;
+}
+/** Shared read-only project fence before either storage bootstrap or cutover. */
+export function assertMemoryUpgradeProjectCurrent(selected, scope, env) {
+    const p = selected.payload;
+    if (p.git && createHash("sha256").update(readBoundedReleaseFile(p.git.executable, 64 * 1024 * 1024)).digest("hex") !== p.git.probe.executable_sha256)
+        refuse("selected_git_changed");
+    if (p.git && hybridDigest(observeMemoryGitPolicySelection(env, { scope, gitExecutable: p.git.executable,
+        selection: { route: p.git.policy.route, integrationBranch: p.git.policy.integration_branch } })) !== hybridDigest(p.git.policy))
+        refuse("git_policy_changed");
+    if (hybridDigest(observeDescriptorWorkspace({ env }, scope.projectRoot, scope.workspaceRoot, p.git?.executable)) !== hybridDigest(p.workspace)
+        || !matchesRetainedMemoryUpgradeInventory(prepareMemoryUpgradeInventory(scope.workspaceRoot, selected.layer, selected.baselineLayer ?? undefined), p.current.inventory))
+        refuse("current_context_changed");
+}
+/** Current physical admission in the bound engine, separate from historical
+ * migration receipts. Shared by initial bootstrap and relocated RUN stages. */
+export function assertUpgradeExecutionStorage(context, engine) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const proof = engine.admitMemoryUpgradeStorage(context.ddFlowHome, resourceHome(context));
+    const stores = [PreparedMemoryInitRuntimeStorage.prepareUpgrade(context).facts(), PreparedMemoryInitResourceStorage.prepare(context).facts()];
+    const runProof = proof.facts.run, resourceProof = proof.facts.resource;
+    if (stores.some(local => {
+        const remote = local.store_kind === "run" ? runProof : resourceProof;
+        return local.store_path !== remote.store_path || local.schema_sha256 !== remote.schema_sha256
+            || local.executing_writer_version !== remote.executing_writer_version;
+    }))
+        refuse("executing_store_context_changed");
+    return proof;
+}
+/** New bootstrap path: source/target policy comes only from retained input.
+ * Physical stores are observed now, not inferred from a project's MB version. */
+function frozenProof(context, scope, retained, retainedMigration) {
+    const original = retained ? null : restoreMemoryUpgradeSelection(context.ddFlowHome, scope);
+    const selected = original ?? restoreMemoryUpgradeSelectionData(Buffer.from(retained.payload_json, "utf8"), retained.sha256, retained.request_input, scope), p = selected.payload;
+    const requestInput = retained?.request_input ?? original.original.input;
+    if (p.impact.chain.status !== "ok")
+        refuse("incomplete_retained_impact_chain");
+    if (!retained && selected.baselineLayer) {
+        const baseline = PreparedMemoryLayer.fromCommittedCanon(context.ddFlowHome, JSON.parse(Buffer.from(p.current.manifest_base64, "base64").toString("utf8")), selected.baselineLayer.installationSha256);
+        if (!baseline || baseline.sha256 !== selected.baselineLayer.sha256 || baseline.installationSha256 !== selected.baselineLayer.installationSha256)
+            refuse("canonical_baseline_changed");
+    }
+    assertMemoryUpgradeProjectCurrent(selected, scope, context.env);
+    const compatibility = JSON.parse(selected.layer.files().get("dd-flow/compatibility.json").toString("utf8"));
+    const contract = JSON.parse(selected.layer.files().get("dd-flow/flow-contract.json").toString("utf8"));
+    const manifest = selected.engine.manifest();
+    if (compatibility.memory_bank_version !== selected.release.canon.version || compatibility.dd_flow_cli.flow_contract !== contract.id
+        || compatibility.dd_flow_cli.package_name !== manifest.package_name || compatibility.engine.package_name !== manifest.package_name
+        || !semver.valid(compatibility.dd_flow_cli.min_version) || semver.lt(manifest.package_version, compatibility.dd_flow_cli.min_version)
+        || !semver.satisfies(manifest.package_version, compatibility.engine.version_range, { includePrerelease: true }))
+        refuse("retained_engine_incompatible");
+    const proof = assertUpgradeExecutionStorage(context, selected.engine);
+    let migration;
+    const file = original ? path.join(path.dirname(original.original.candidate.retain().file), "storage-migration.json")
+        : retainedMigration ? upgradeStorageMigration(retainedMigration, selected.sha256).request.path : undefined;
+    if (file && fs.existsSync(file)) {
+        const request = { path: file, sha256: createHash("sha256").update(readBoundedReleaseFile(file, 16 * 1024 * 1024)).digest("hex") };
+        const response = selected.engine.transitionMemoryUpgradeStorage({ home: context.ddFlowHome, resourceHome: resourceHome(context), scope,
+            selectionSha256: selected.sha256, action: "status", expectedSha256: request.sha256 });
+        const result = response.result;
+        if (result?.status !== "applied" || !result.proof)
+            refuse("migration_evidence_incomplete");
+        migration = upgradeStorageMigration({ request, proof: result.proof }, selected.sha256);
+        if (retainedMigration && hybridDigest(migration) !== hybridDigest(retainedMigration))
+            refuse("migration_evidence_changed");
+    }
+    else if (retainedMigration)
+        refuse("migration_request_unavailable");
+    return { selectionSha256: selected.sha256, selection: { sha256: selected.sha256,
+            payload_json: selected.bytes.toString("utf8"), request_input: requestInput }, proof: {
+            schema_id: migration ? "dd-flow/mb-upgrade-storage-readiness@2" : "dd-flow/mb-upgrade-storage-readiness@1",
+            route: migration ? "migration" : "verified-no-op", ...(migration ? { migration } : {}), selection_sha256: selected.sha256,
+            source_version: p.current.canon_version, target_version: selected.release.canon.version,
+            chain: p.impact.chain.steps, current_provenance: p.current.inventory.inventory.current_manifest,
+            target: { canon: selected.source.canonProvenance(), installation_sha256: p.release.manifest_sha256,
+                layer_sha256: selected.layer.sha256, pack_sha256: selected.layer.packSha256 }, selected_engine_storage: proof,
+            stores: [proof.facts.run, proof.facts.resource].map(store => ({ store_kind: store.store_kind, store_path: store.store_path,
+                store_dev: store.store_dev, store_ino: store.store_ino, schema_sha256: store.schema_sha256, executing_writer_version: store.executing_writer_version }))
+        } };
+}
+/** Historical evidence, not present-day physical admission. Project sync may
+ * change current files without rewriting the original upgrade's storage proof.
+ * Workspace/repository eligibility belongs to the upgrade target preflight.
+ */
+export function readUpgradeStorageReadiness(context, scope) {
+    return context.db.readSnapshot(() => retainedStorage(context, scope));
+}
+function retainedStorage(context, scope) {
+    let logical;
+    try {
+        logical = resolveUpgradeHistoricalScope(context, scope);
+    }
+    catch (error) {
+        // A first upgrade may observe an existing MB in a new runtime Home. This
+        // is absence of history, not registration or permission to revive it.
+        if (error instanceof AppError && error.details.reason === 'project_not_active'
+            && !context.db.get('SELECT 1 FROM projects WHERE root=?', [scope.projectRoot])
+            && !(hasRunStartTable(context) && context.db.get("SELECT 1 FROM run_start_requests WHERE request_id=? AND json_extract(payload_json,'$.project_root')=?", [scope.requestId, scope.projectRoot])))
+            return null;
+        throw error;
+    }
+    const projectId = logical.projectId;
+    scope = logical.scope;
+    const row = context.db.get("SELECT value_json FROM runtime_config WHERE key = ?", [key(projectId, scope.requestId)]);
+    if (!row) {
+        if (context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.upgrade_storage_ready' AND json_extract(payload_json,'$.request_id')=? AND json_extract(payload_json,'$.selection_sha256') IS NOT NULL LIMIT 1", [projectId, scope.requestId]))
+            refuse("storage_readiness_custody_missing");
+        return null;
+    }
+    if (Buffer.byteLength(row.value_json) > 68 * 1024 * 1024)
+        refuse("unbounded_retained_receipt");
+    const cached = retainedDecodes.get(context.db);
+    if (cached?.raw === row.value_json && cached.value.receipt.project_id === projectId
+        && hybridDigest(cached.value.receipt.scope) === hybridDigest(scope)) {
+        assertRetainedReadinessAudit(context, projectId, scope, cached.value);
+        return structuredClone(cached.value);
+    }
+    let receipt;
+    try {
+        receipt = JSON.parse(row.value_json);
+    }
+    catch {
+        return refuse("invalid_retained_receipt");
+    }
+    const frozen = receipt?.schema_id === "dd-flow/mb-upgrade-storage-request@2" || receipt?.schema_id === "dd-flow/mb-upgrade-storage-request@3";
+    const migrated = receipt?.schema_id === "dd-flow/mb-upgrade-storage-request@3";
+    if (!receipt || Object.keys(receipt).sort().join() !== (frozen ? "project_id,proof,schema_id,scope,selection" : "project_id,proof,schema_id,scope")
+        || !["dd-flow/mb-upgrade-storage-request@1", "dd-flow/mb-upgrade-storage-request@2", "dd-flow/mb-upgrade-storage-request@3"].includes(receipt.schema_id) || receipt.project_id !== projectId
+        || hybridDigest(receipt.scope) !== hybridDigest(scope) || !receipt.proof
+        || receipt.proof.schema_id !== (migrated ? "dd-flow/mb-upgrade-storage-readiness@2" : "dd-flow/mb-upgrade-storage-readiness@1")
+        || receipt.proof.route !== (migrated ? "migration" : "verified-no-op"))
+        refuse("changed_request");
+    if (receipt.proof.selection_sha256 !== undefined && (typeof receipt.proof.selection_sha256 !== "string"
+        || !/^[a-f0-9]{64}$/.test(receipt.proof.selection_sha256)))
+        refuse("changed_request");
+    const sha256 = hybridDigest(receipt);
+    if (!frozen)
+        return { receipt, sha256 };
+    const retained = receipt.selection;
+    if (!retained || Object.keys(retained).sort().join() !== "payload_json,request_input,sha256" || typeof retained.payload_json !== "string"
+        || retained.sha256 !== receipt.proof.selection_sha256)
+        refuse("invalid_retained_selection");
+    const selection = decodeMemoryUpgradeSelection(Buffer.from(retained.payload_json, "utf8"), retained.sha256, retained.request_input, scope);
+    if (migrated)
+        upgradeStorageMigration(receipt.proof.migration, retained.sha256);
+    const value = { receipt, sha256, selection };
+    assertRetainedReadinessAudit(context, projectId, scope, value);
+    retainedDecodes.set(context.db, { raw: row.value_json, value });
+    return structuredClone(value);
+}
+function assertRetainedReadinessAudit(context, projectId, scope, value) {
+    const { receipt, sha256 } = value, retained = receipt.selection;
+    if (!retained)
+        refuse("invalid_retained_selection");
+    const audits = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.upgrade_storage_ready' AND json_extract(payload_json,'$.request_id')=? LIMIT 2", [projectId, scope.requestId]);
+    if (audits.length !== 1 || audits.some(event => Buffer.byteLength(event.payload_json) > 16 * 1024)
+        || hybridDigest(JSON.parse(audits[0].payload_json)) !== hybridDigest({ request_id: scope.requestId, project_root: scope.projectRoot,
+            workspace_root: scope.workspaceRoot, receipt_sha256: sha256, route: receipt.proof.route, selection_sha256: retained.sha256 }))
+        refuse("storage_readiness_custody_missing");
+}
+/** Retains physical admission plus selected-engine phase evidence when storage
+ * changed. Legacy apply markers are insufficient for migration bootstrap.
+ * This is a storage dependency, not complete bootstrap or provider readiness.
+ */
+export class PreparedUpgradeStorageReadiness {
+    #receipt;
+    #engine;
+    #selectionSha256;
+    constructor(receipt, engine, selectionSha256) {
+        if (Buffer.byteLength(JSON.stringify(receipt)) > 68 * 1024 * 1024)
+            refuse("unbounded_retained_receipt");
+        this.#receipt = structuredClone(receipt);
+        this.#engine = engine;
+        this.#selectionSha256 = selectionSha256;
+        Object.freeze(this);
+    }
+    static prepareFromSelection(context, scope) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const projectId = project(context, scope);
+        scopeDirectories(scope);
+        const prior = readUpgradeStorageReadiness(context, scope);
+        const selected = frozenProof(context, scope, prior?.receipt.selection, prior?.receipt.proof.migration);
+        const receipt = { schema_id: selected.proof.route === "migration" ? "dd-flow/mb-upgrade-storage-request@3" : "dd-flow/mb-upgrade-storage-request@2", scope: { ...scope }, project_id: projectId,
+            proof: selected.proof, selection: selected.selection };
+        if (prior && prior.sha256 !== hybridDigest(receipt))
+            refuse("changed_request");
+        return new PreparedUpgradeStorageReadiness(receipt, undefined, selected.selectionSha256);
+    }
+    static prepare(context, scope, engine) {
+        const projectId = project(context, scope);
+        scopeDirectories(scope);
+        const proof = assertUpgradeRunStorageReady(context, scope.projectRoot, engine);
+        if (proof.route !== "verified-no-op")
+            refuse("storage_migration_requires_physical_proof");
+        const receipt = { schema_id: "dd-flow/mb-upgrade-storage-request@1", scope: { ...scope }, project_id: projectId, proof };
+        const prior = readUpgradeStorageReadiness(context, scope);
+        if (prior && prior.sha256 !== hybridDigest(receipt))
+            refuse("changed_request");
+        return new PreparedUpgradeStorageReadiness(receipt, engine);
+    }
+    apply(context) {
+        const scope = this.#receipt.scope;
+        if (this.#selectionSha256 !== undefined) {
+            const prior = readUpgradeStorageReadiness(context, scope);
+            if (prior) {
+                if (prior.sha256 !== hybridDigest(this.#receipt))
+                    refuse("changed_request");
+                // Historical acknowledgement only, never fresh RUN/storage admission.
+                return { ...prior, changed: false };
+            }
+        }
+        const proof = this.#selectionSha256 === undefined ? assertUpgradeRunStorageReady(context, scope.projectRoot, this.#engine)
+            : frozenProof(context, scope).proof;
+        if (project(context, scope) !== this.#receipt.project_id
+            || hybridDigest(proof) !== hybridDigest(this.#receipt.proof))
+            refuse("changed_after_preparation");
+        return context.db.writeTransaction(() => {
+            const prior = readUpgradeStorageReadiness(context, scope);
+            if (prior) {
+                if (prior.sha256 !== hybridDigest(this.#receipt))
+                    refuse("changed_request");
+                return { ...prior, changed: false };
+            }
+            const now = context.now();
+            context.db.run("INSERT INTO runtime_config (key,value_json,created_at,updated_at) VALUES (?,?,?,?)", [key(this.#receipt.project_id, scope.requestId), JSON.stringify(this.#receipt), now, now]);
+            appendAudit(context, { projectId: this.#receipt.project_id, eventType: "memory.upgrade_storage_ready", payload: {
+                    request_id: scope.requestId, project_root: scope.projectRoot, workspace_root: scope.workspaceRoot,
+                    receipt_sha256: hybridDigest(this.#receipt), route: this.#receipt.proof.route,
+                    ...(this.#selectionSha256 ? { selection_sha256: this.#selectionSha256 } : {})
+                } });
+            const accepted = readUpgradeStorageReadiness(context, scope);
+            if (!accepted || accepted.sha256 !== hybridDigest(this.#receipt))
+                refuse("storage_readiness_readback_failed");
+            return { ...accepted, changed: true };
+        }, "memoryUpgrade.storageReadiness");
+    }
+}

package/dist/services/memory-verification-acceptance.js

@@ -0,0 +1,156 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedCheckEvidence } from "./code-checks.js";
+import { PreparedMemoryStageResult, memorySourceKey } from "./memory-stage-results.js";
+import { PreparedAcceptedMemoryComposition } from "./memory-accepted-composition.js";
+function refuse(reason) {
+    throw new AppError("memory_verification_acceptance_invalid", "Verification lacks current check proof or accepted per-unit assessments", 2, { reason, effect: "no_effect" });
+}
+/** Check references are a CLI projection of the selected current owner, not
+ * agent-generated proof. Admit an optional echo only when it names those bytes. */
+export function projectMemoryVerificationChecks(value, references, directory, resultSha256) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const candidate = value;
+    if (!candidate.details || typeof candidate.details !== "object" || Array.isArray(candidate.details))
+        return value;
+    if (candidate.details.checks !== undefined && (!Array.isArray(candidate.details.checks) || candidate.details.checks.some(reference => {
+        if (!reference || typeof reference !== "object" || Array.isArray(reference) || Object.keys(reference).some(key => !["path", "sha256"].includes(key)))
+            return true;
+        const matches = references.filter(current => current.sha256 === reference.sha256 && (current.path === reference.path
+            || current.path.startsWith(`${directory}/checks/`) && current.path.slice(directory.length + 1) === reference.path));
+        return new Set(matches.map(current => hybridDigest(current))).size !== 1;
+    })))
+        throw new AppError("memory_verification_acceptance_invalid", "Use only the selected current CLI check references; correct the proposed result without rerunning settled checks", 2, { reason: "checks_not_selected_current_receipts", phase: "prepare", effect: "no_effect", recoverable: true, check_references: references, result_sha256: resultSha256 });
+    return { ...candidate, details: { ...candidate.details, checks: references } };
+}
+/** Pure reference comparison; the caller must obtain admitted outputs from
+ * the current accepted composition owner, never from proposed result bytes. */
+export function assertMemoryVerificationArtifactReferences(original, proposed, outputs) {
+    const identities = (sources) => sources.map(source => hybridDigest(source));
+    const declared = new Set(identities(proposed)), accepted = new Set(identities([...original, ...outputs]));
+    if (identities(original).some(identity => !declared.has(identity))
+        || [...declared].some(identity => !accepted.has(identity)))
+        refuse("changed_composed_artifacts");
+}
+/** Accepted compose owns these associations; the verifier owns assessments. */
+export function projectMemoryVerificationArtifacts(value, units, outputs, resultSha256) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const candidate = value;
+    if (!Array.isArray(candidate.units))
+        return value;
+    const originals = new Map(units.map(unit => [unit.id, unit.artifacts]));
+    return { ...candidate, units: candidate.units.map(unit => {
+            if (!unit || typeof unit !== "object" || Array.isArray(unit) || unit.artifacts !== undefined && !Array.isArray(unit.artifacts))
+                return unit;
+            const original = originals.get(unit.id);
+            if (!original)
+                return unit;
+            const allowed = new Set([...original, ...outputs].map(reference => hybridDigest(reference)));
+            const provided = unit.artifacts ?? [];
+            if (provided.some((reference) => !allowed.has(hybridDigest(reference)))) {
+                if (resultSha256 === undefined)
+                    refuse("changed_composed_artifacts");
+                throw new AppError("memory_verification_acceptance_invalid", "Omit units[].artifacts: the CLI preserves accepted compose outputs. Cite preserved source documents in semantic assessment evidence, not as new artifacts; correct the proposal without rerunning settled checks", 2, { reason: "changed_composed_artifacts", phase: "prepare", effect: "no_effect", recoverable: true, unit_id: unit.id,
+                    output_references: structuredClone(original), result_sha256: resultSha256 });
+            }
+            const merged = new Map([...original, ...provided].map(reference => [hybridDigest(reference), reference]));
+            return { ...unit, artifacts: [...merged.values()] };
+        }) };
+}
+/** Admission of the verifier's claims, not an independent judgment of their
+ * semantic truth. The handler must independently select and fence accepted
+ * compose SQL custody and current output observations; REVIEW/Eval still own
+ * their separate gates. Lint alone cannot supply these unit assessments.
+ */
+export class PreparedMemoryVerificationAcceptance {
+    #resultSha256;
+    #checks;
+    constructor(result, checks) {
+        this.#resultSha256 = result.sha256;
+        this.#checks = checks;
+        Object.freeze(this);
+    }
+    static prepare(input) {
+        if (!(input.result instanceof PreparedMemoryStageResult) || !(input.compose instanceof PreparedMemoryStageResult)
+            || !(input.checks instanceof PreparedCheckEvidence))
+            refuse("prepared_authority_required");
+        const result = input.result.value(), compose = input.compose.value();
+        if (input.composition !== undefined && (!(input.composition instanceof PreparedAcceptedMemoryComposition)
+            || input.composition.result().sha256 !== input.compose.sha256))
+            refuse("prepared_authority_required");
+        const outputs = input.composition?.outputReferences() ?? [];
+        const upgrade = compose.stage === "upgrade", authoring = upgrade ? "upgrade" : "compose";
+        input.checks.assertOwner({ ...input.scope, scope: "aggregate" });
+        const diagnostic = result.outcome === "needs_repair";
+        if (!["compose", "upgrade"].includes(compose.stage) || compose.outcome !== "accepted" || result.stage !== "verify" || !["accepted", "needs_repair"].includes(result.outcome)
+            || result.run_id !== compose.run_id || result.run_id !== input.scope.runId || result.predecessors.length !== 1 || result.predecessors[0].stage !== authoring
+            || result.predecessors[0].input_sha256 !== compose.input_sha256 || result.predecessors[0].result.sha256 !== input.compose.sha256
+            || compose.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved"))
+            refuse("unaccepted_or_foreign_predecessor");
+        if (!diagnostic && (!input.checks.qualityPassed() || result.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved")))
+            throw new AppError("memory_verification_acceptance_invalid", "Accepted verification requires passed selected checks and no unresolved material findings. For a real gap use needs_repair with an open material finding; a pending later REVIEW is a separate gate, not a current defect. Do not mark unresolved findings resolved or rerun settled checks merely to pass", 2, { reason: "verification_not_accepted", phase: "prepare", effect: "no_effect", recoverable: true, result_sha256: input.proposalSha256 ?? input.result.sha256 });
+        const expected = input.checks.resultReferences().map(reference => hybridDigest(reference)), actual = result.details.checks.map(reference => hybridDigest(reference));
+        const allowedChecks = new Set(input.checks.sourceReferences().map(({ path, sha256 }) => hybridDigest({ path, sha256 })));
+        if (expected.some(reference => !actual.includes(reference))
+            || actual.some(reference => !allowedChecks.has(reference)))
+            refuse("checks_not_selected_current_receipts");
+        const units = new Map(compose.units.map(unit => [unit.id, unit]));
+        if (result.units.length !== units.size || new Set(result.units.map(unit => unit.id)).size !== units.size)
+            refuse("changed_unit_coverage");
+        const selectedAssessments = upgrade ? result.details.preservation_assessments?.map(item => ({ ...item, verdict: item.outcome === "preserved" ? "accepted" : item.outcome })) : result.details.semantic_assessments;
+        if (!selectedAssessments)
+            refuse("missing_unit_assessments");
+        const assessments = new Map();
+        for (const assessment of selectedAssessments)
+            assessments.set(assessment.unit_id, [...assessments.get(assessment.unit_id) ?? [], assessment]);
+        if (!upgrade && assessments.size !== selectedAssessments.length || [...assessments.keys()].some(id => !units.has(id))
+            || compose.units.some(unit => unit.applicability !== "not-applicable" && !assessments.has(unit.id)))
+            refuse("incomplete_or_duplicate_assessments");
+        if (upgrade && hybridDigest(input.result.preservationInvariants()) !== hybridDigest(input.compose.preservationInvariants()))
+            refuse("changed_preservation_invariants");
+        const key = (source) => memorySourceKey(input.roots && input.roots.projectRoot === input.roots.workspace && source.root === "project" ? "workspace" : source.root, source.path);
+        for (const unit of result.units) {
+            const original = units.get(unit.id), selected = assessments.get(unit.id) ?? [];
+            // IDs bind assessments to accepted units; aspect is descriptive prose.
+            // REVIEW derives its assignments from composition, not this wording.
+            if (!original || unit.applicability !== original.applicability || unit.applicability === "unknown"
+                || (unit.applicability === "not-applicable" ? unit.outcome !== "not-applicable" : !["accepted", ...(diagnostic ? ["needs_repair"] : [])].includes(unit.outcome))
+                || selected.some(assessment => !["accepted", ...(diagnostic ? ["needs_repair"] : [])].includes(assessment.verdict) || !assessment.summary.trim()))
+                refuse("unit_not_accepted_or_changed");
+            assertMemoryVerificationArtifactReferences(original.artifacts, unit.artifacts, outputs);
+            for (const assessment of selected) {
+                // PreparedMemoryStageResult already binds every evidence reference to
+                // admitted bytes. Cross-unit and earlier-stage evidence is useful context,
+                // but cannot replace examination of this unit's own composed output.
+                if (unit.applicability !== "not-applicable" && !assessment.evidence.some(source => original.artifacts.some(artifact => key(artifact) === key(source) && artifact.sha256 === source.sha256))) {
+                    throw new AppError("memory_verification_acceptance_invalid", "Assess the composed documents themselves and cite a direct output reference for EACH applicable unit; the listed references identify this unit's outputs. Work result receipts do not replace direct output examination", 2, { reason: "assessment_does_not_examine_composed_output", phase: "prepare", effect: "no_effect", recoverable: true,
+                        unit_id: unit.id, output_references: structuredClone(original.artifacts), result_sha256: input.result.sha256 });
+                }
+                if (upgrade) {
+                    const id = assessment.invariant_id;
+                    const invariant = input.result.preservationInvariants().find(item => item.id === id);
+                    const old = invariant?.evidence;
+                    // A current output alone cannot substantiate old-to-new preservation.
+                    // Identical old bytes may be examined through the retained RUN copy.
+                    if (!old?.some(before => assessment.evidence.some(source => source.sha256 === before.sha256 && (key(source) === key(before) || source.root === "run"))))
+                        throw new AppError("memory_verification_acceptance_invalid", "Compare the retained old evidence as well as the current unit output; correct the assessment without rerunning settled checks", 2, { reason: "preservation_assessment_does_not_examine_old_evidence", phase: "prepare", effect: "no_effect", recoverable: true,
+                            unit_id: unit.id, invariant_id: id, old_references: structuredClone(old ?? []), result_sha256: input.result.sha256 });
+                }
+            }
+        }
+        if (diagnostic && !result.findings.some(finding => finding.severity !== "minor" && finding.status === "open")) {
+            throw new AppError("memory_verification_acceptance_invalid", "needs_repair requires an open material finding; correct the proposed outcome and unit assessments without inventing severity", 2, { reason: "repair_requires_material_finding", phase: "prepare", effect: "no_effect", recoverable: true });
+        }
+        return new PreparedMemoryVerificationAcceptance(input.result, input.checks);
+    }
+    assertCustody(context, result, checks) {
+        if (!(result instanceof PreparedMemoryStageResult) || result.sha256 !== this.#resultSha256)
+            refuse("verification_result_changed");
+        if (checks !== undefined && checks !== this.#checks)
+            refuse("foreign_check_owner");
+        this.#checks.assertCustody(context);
+    }
+    revalidate(context) { this.#checks.revalidate(context); }
+}