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

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

@@ -81,14 +81,16 @@ export class PreparedMemoryVerificationAcceptance {
             || 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.stage !== "compose" || 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 !== "compose"
+        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")
-            || (!diagnostic && (!input.checks.qualityPassed() || result.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved"))))
+            || 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))
@@ -97,26 +99,45 @@ export class PreparedMemoryVerificationAcceptance {
         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 assessments = new Map(result.details.semantic_assessments.map(assessment => [assessment.unit_id, assessment]));
-        if (assessments.size !== result.details.semantic_assessments.length || [...assessments.keys()].some(id => !units.has(id))
+        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), assessment = assessments.get(unit.id);
-            if (!original || unit.aspect !== original.aspect || unit.applicability !== original.applicability || unit.applicability === "unknown"
+            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))
-                || (assessment && (!["accepted", ...(diagnostic ? ["needs_repair"] : [])].includes(assessment.verdict) || !assessment.summary.trim())))
+                || 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);
-            if (!assessment)
-                continue;
-            // 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 });
+            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")) {

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

@@ -14,15 +14,29 @@ import { PreparedMemoryBaselinePreservation } from "./memory-baseline-preservati
 import { readBoundedReleaseFile } from "./release-source.js";
 import { codeCheckProfileHash, projectPolicyCheckDeclarationsFromProfile, readCodeCheckProfile, runCodeChecks, PreparedCheckEvidence } from "./code-checks.js";
 import { ObservedMemorySources } from "./memory-source-observations.js";
-import { memoryVerificationActivePaths, validateMemoryLintConfig } from "./memory-lint-config.js";
+import { memoryVerificationActivePaths, memoryUpgradeLintGuidance, memoryVerificationSupplementalLintFiles, memoryCanonicalLintExceptions, memoryCanonicalTemplatePaths } from "./memory-lint-config.js";
 import { isMemoryCorrectionInputOwner } from "./memory-correction-input-owner.js";
+import { readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { PreparedAcceptedMemoryComposition } from "./memory-accepted-composition.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
 const token = Symbol("memory-verification-checks");
 const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
 const profilePath = ".memory-bank/spec/engineering/code-check-profile.json";
+export function memorySupplementalLintCommand(executable, workspace, files, exceptions = []) {
+    const config = JSON.stringify(exceptions.length ? { ignoreFindings: exceptions } : {});
+    return `printf '%s\\n' ${quote(config)} > "$DD_FLOW_EVIDENCE_DIR/mb-lint-active-config.json" && ${quote(executable)} --root ${quote(workspace)} --config "$DD_FLOW_EVIDENCE_DIR/mb-lint-active-config.json" --files ${files.map(quote).join(" ")} --format json > "$DD_FLOW_EVIDENCE_DIR/mb-lint-active.json"`;
+}
 function refuse(reason) {
     throw new AppError("memory_verification_checks_invalid", "Verification checks lack admitted tool, policy or accepted composition custody", 2, { reason, effect: "no_effect" });
 }
+/** First introduction adds obligations to mandatory lint; an existing policy
+ * remains immutable, including in the next correction wave. */
+export function assertRetainedMemoryVerificationPolicy(previous, current) {
+    if (previous !== null && current !== previous)
+        refuse("correction_policy_requires_readmission");
+}
 /** Finite project checks use the original Codex home, never a temporary
  * provider Session overlay. Keep every other application environment input. */
 export function memoryCheckEnvironment(context, projectId, runId) {
@@ -86,19 +100,29 @@ function accepted(context, input) {
     }
     const frozen = input.execution.snapshot(), scope = { requestId: frozen.scope.requestId, projectRoot: frozen.scope.projectRoot, workspaceRoot: frozen.scope.workspace };
     const run = context.db.get("SELECT workspace_root,project_root,run_root,run_dir,index_json FROM runs WHERE project_id=? AND id=?", [input.projectId, input.runId]);
-    const bootstrap = readMemoryInitBootstrapReadiness(context, scope), lint = readMemoryInitProjectBootstrapLintCapability(context, scope);
+    const upgrade = input.flow.descriptor.id === "mb-upgrade";
+    const init = upgrade ? null : readMemoryInitBootstrapReadiness(context, scope);
+    const updated = upgrade ? readMemoryUpgradeBootstrapReadiness(context, scope) : null;
+    const bootstrap = init ?? updated;
+    const lint = upgrade ? updated?.authority.binding.lint ? { facts: updated.authority.binding.lint, sha256: hybridDigest(updated.authority.binding.lint) } : null
+        : readMemoryInitProjectBootstrapLintCapability(context, scope);
     if (!run || run.project_root !== scope.projectRoot || run.workspace_root !== scope.workspaceRoot || !bootstrap || !lint
         || bootstrap.projectId !== input.projectId || bootstrap.authority.binding.execution_sha256 !== input.execution.sha256)
         refuse("accepted_bootstrap_scope_required");
-    const compose = readAcceptedStageData(context, { projectId: input.projectId, runId: input.runId, stage: "compose" });
-    if (compose.data_schema_id !== "dd-flow/mb-init-compose-result@1")
+    const authoring = upgrade ? "upgrade" : "compose";
+    const compose = readAcceptedStageData(context, { projectId: input.projectId, runId: input.runId, stage: authoring });
+    if (compose.data_schema_id !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : "dd-flow/mb-init-compose-result@1"))
         refuse("accepted_composition_required");
+    const baselineProfile = upgrade ? readUpgradeStorageReadiness(context, scope)?.selection?.payload.current.inventory.inventory.entries
+        .find(entry => entry.path === profilePath.slice(13))?.current?.sha256 ?? null : null;
     const active = input.corrected ? "review" : "verify";
     const { index_json, ...roots } = run, index = JSON.parse(index_json), stage = index.stage_runs.find((stage) => stage.stage === active);
     if (index.current_stage !== active || stage?.status !== "running" || typeof stage.input_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(stage.input_sha256))
         refuse(input.corrected ? "active_corrected_review_required" : "active_verification_required");
     const phase = { attempt: stage.attempt ?? null, cycle: stage.cycle ?? null, input_sha256: stage.input_sha256 };
-    return { run: roots, bootstrap, lint, compose, scope, authority: hybridDigest({ run: roots, phase, bootstrap: bootstrap.authority, lint, compose: compose.authority_sha256,
+    const probe = init?.authority.binding.target.tool_probes?.["mb-lint"] ?? updated?.authority.binding.lint;
+    const executable = init?.authority.binding.target.tools["mb-lint"] ?? updated?.authority.binding.lint?.executable;
+    return { run: roots, bootstrap, lint, compose, scope, probe, executable, baselineProfile, authority: hybridDigest({ run: roots, phase, bootstrap: bootstrap.authority, lint, compose: compose.authority_sha256,
             ...(input.corrected ? { corrected_sha256: input.corrected.sha256 } : {}) }) };
 }
 /** Owning CLI policy, not agent-proposed commands. The bootstrap-selected
@@ -147,30 +171,52 @@ export class PreparedMemoryVerificationChecks {
         if (context.db.isOwnedWriteTransaction?.())
             refuse("preparation_outside_writer_required");
         if (!(input.execution instanceof FrozenGenericExecution) || !(input.flow instanceof ResolvedFlowDescriptor)
-            || input.flow.descriptor.id !== "mb-init" || input.execution.settings.flow_id !== "mb-init"
+            || !["mb-init", "mb-upgrade"].includes(input.flow.descriptor.id) || input.execution.settings.flow_id !== input.flow.descriptor.id
             || input.execution.settings.descriptor_sha256 !== input.flow.sha256)
             refuse("frozen_memory_selection_required");
         input.corrected?.revalidate(context);
         const selected = context.db.readSnapshot(() => accepted(context, input)), value = JSON.parse(selected.compose.bytes.toString("utf8"));
-        const schema = JSON.parse(input.flow.stageBlob("compose", "result_schema").toString("utf8"));
+        const upgrade = input.flow.descriptor.id === "mb-upgrade", authoring = upgrade ? "upgrade" : "compose";
+        const schema = JSON.parse(input.flow.stageBlob(authoring, "result_schema").toString("utf8"));
         if (!new Ajv2020({ strict: true, strictRequired: false, validateFormats: false }).compile(schema)(value))
             refuse("accepted_composition_required");
         const compose = value;
-        if (compose.run_id !== input.runId || compose.stage !== "compose" || compose.outcome !== "accepted")
+        if (compose.run_id !== input.runId || compose.stage !== authoring || compose.outcome !== "accepted")
             refuse("accepted_composition_required");
-        const probe = selected.bootstrap.authority.binding.target.tool_probes?.["mb-lint"];
-        if (!probe || selected.bootstrap.authority.binding.target.tools["mb-lint"] !== selected.lint.facts.executable
+        const probe = selected.probe;
+        if (!probe || selected.executable !== selected.lint.facts.executable
             || probe.executable_sha256 !== selected.lint.facts.executable_sha256 || probe.version !== selected.lint.facts.version
             || hash(readBoundedReleaseFile(selected.lint.facts.executable, 64 * 1024 * 1024)) !== probe.executable_sha256)
             refuse("selected_linter_changed");
-        const preservation = PreparedMemoryBaselinePreservation.prepare(context, input.execution);
+        const bundle = input.bundle ?? input.corrected?.bundle();
+        if (upgrade && (!(bundle instanceof RetainedExecutionBundle) || bundle.execution.sha256 !== input.execution.sha256 || bundle.descriptor.sha256 !== input.flow.sha256))
+            refuse("registered_upgrade_bundle_required");
+        if (input.composition && (!(input.composition instanceof PreparedAcceptedMemoryComposition) || input.composition.result().sha256 !== selected.compose.result.sha256))
+            refuse("foreign_accepted_composition");
+        const preservation = upgrade ? input.corrected ?? input.composition ?? PreparedAcceptedMemoryComposition.prepare(context, { scope: input, bundle: bundle }) : PreparedMemoryBaselinePreservation.prepare(context, input.execution);
         const workspace = selected.run.workspace_root;
         const config = lintConfig(workspace);
         const corrected = input.corrected?.value();
-        if (config)
-            validateMemoryLintConfig(config, corrected
-                ? memoryVerificationActivePaths(corrected.unit_inventory, corrected.assignments)
-                : memoryVerificationActivePaths(compose.units));
+        let guidance;
+        let canonicalEntries = [];
+        let canonicalFiles = new Map();
+        let templates;
+        if (upgrade) {
+            const storage = readUpgradeStorageReadiness(context, selected.scope);
+            if (!storage?.selection)
+                refuse("retained_upgrade_inventory_required");
+            const diff = readAcceptedStageData(context, { projectId: input.projectId, runId: input.runId, stage: "diff-analysis" });
+            guidance = memoryUpgradeLintGuidance(storage.selection.payload.current.inventory.inventory.entries, JSON.parse(diff.bytes.toString("utf8")).details.path_map);
+            canonicalEntries = storage.selection.payload.current.inventory.inventory.entries;
+            canonicalFiles = new Map(storage.selection.payload.layer.files.map(file => [file.path, Buffer.from(file.base64, "base64")]));
+            const current = new Map(canonicalEntries.filter(entry => /^mbb\/templates\/.+\.(?:md|markdown)$/.test(entry.path) && entry.current?.kind === "file" && entry.target && ["canonical", "local-customized"].includes(entry.ownership))
+                .map(entry => [entry.path, readBoundedReleaseFile(path.join(workspace, ".memory-bank", entry.path), 64 * 1024 * 1024)]));
+            templates = memoryCanonicalTemplatePaths(canonicalEntries, canonicalFiles, current);
+        }
+        const supplementalFiles = config ? memoryVerificationSupplementalLintFiles(config, corrected
+            ? memoryVerificationActivePaths(corrected.unit_inventory, corrected.assignments, guidance, templates)
+            : memoryVerificationActivePaths(compose.units, [], guidance, templates)) : [];
+        const canonicalExceptions = memoryCanonicalLintExceptions(canonicalEntries, canonicalFiles, supplementalFiles);
         let observed = null;
         let exists = false;
         try {
@@ -183,6 +229,8 @@ export class PreparedMemoryVerificationChecks {
         }
         const profileRefs = input.corrected ? input.corrected.value().run_inputs : compose.units.flatMap(unit => unit.artifacts);
         const expectedProfiles = new Set(profileRefs.filter(artifact => artifact.root === "workspace" && artifact.path === profilePath).map(artifact => artifact.sha256));
+        if (upgrade && exists && !expectedProfiles.size && selected.baselineProfile)
+            expectedProfiles.add(selected.baselineProfile);
         if (expectedProfiles.size !== (exists ? 1 : 0))
             refuse("profile_presence_differs_from_composition");
         if (exists) {
@@ -194,21 +242,27 @@ export class PreparedMemoryVerificationChecks {
         const { profile: policy, hash: profileHash } = readCodeCheckProfile(workspace);
         if (profileHash !== (observed?.hashes().get(`workspace\0${profilePath}`) ?? null))
             refuse("profile_changed_during_preparation");
-        const checks = [{ id: "MEMORY/verify/lint-schema-links", canonical_ref: "MEMORY/verify/lint-schema-links",
-                command: `${quote(selected.lint.facts.executable)} --root ${quote(workspace)} --format json > "$DD_FLOW_EVIDENCE_DIR/mb-lint.json"`,
-                purpose: "Mandatory bootstrap-selected Memory Bank lint, frontmatter/schema and Markdown target checks", run_at: "readiness", availability: "available", required_artifacts: ["mb-lint.json"], inputs: ["."],
-                // The pinned linter reads project files/config and invokes Git; provider
-                // Session configuration is not one of its execution dependencies.
-                environment_inputs: ["PATH", "PATHEXT", "HOME", "XDG_CONFIG_HOME", "NODE_*", "UV_*", "GIT_*", "LANG", "LC_*", "TZ", "DYLD_*", "LD_*", "SYSTEMROOT", "COMSPEC", "TMPDIR", "TMP", "TEMP"] },
+        const lintCheck = { id: "MEMORY/verify/lint-schema-links", canonical_ref: "MEMORY/verify/lint-schema-links",
+            command: `${quote(selected.lint.facts.executable)} --root ${quote(workspace)} --format json > "$DD_FLOW_EVIDENCE_DIR/mb-lint.json"`,
+            purpose: "Mandatory bootstrap-selected Memory Bank lint, frontmatter/schema and Markdown target checks", run_at: "readiness", availability: "available", required_artifacts: ["mb-lint.json"], inputs: ["."],
+            // The pinned linter reads project files/config and invokes Git; provider
+            // Session configuration is not one of its execution dependencies.
+            environment_inputs: ["PATH", "PATHEXT", "HOME", "XDG_CONFIG_HOME", "NODE_*", "UV_*", "GIT_*", "LANG", "LC_*", "TZ", "DYLD_*", "LD_*", "SYSTEMROOT", "COMSPEC", "TMPDIR", "TMP", "TEMP"] };
+        const checks = [lintCheck,
+            ...(supplementalFiles.length ? [{ ...lintCheck, id: "MEMORY/verify/lint-active-documents", canonical_ref: "MEMORY/verify/lint-active-documents",
+                    command: memorySupplementalLintCommand(selected.lint.facts.executable, workspace, supplementalFiles, canonicalExceptions),
+                    purpose: "Mandatory independent lint of active Markdown excluded by preserved project policy",
+                    required_artifacts: ["mb-lint-active-config.json", "mb-lint-active.json"] }] : []),
             ...projectPolicyCheckDeclarationsFromProfile(policy, "readiness")];
-        if (input.corrected && codeCheckProfileHash(workspace, checks) !== input.corrected.verificationProfileHash(context))
-            refuse("correction_policy_requires_readmission");
+        if (input.corrected)
+            assertRetainedMemoryVerificationPolicy(input.corrected.verificationProfileHash(context), codeCheckProfileHash(workspace, checks));
         const prepared = new PreparedMemoryVerificationChecks(token, input, selected, observed, preservation, checks, config ? hash(config) : null);
         prepared.#checkEnvironment = memoryCheckEnvironment(context, input.projectId, input.runId);
         prepared.revalidate(context);
         return prepared;
     }
     declarations() { return structuredClone(this.#checks); }
+    profileHash() { return this.#profileSha256; }
     assertCorrectionOwner(corrected) {
         if (!isMemoryCorrectionInputOwner(corrected) || this.#input.corrected !== corrected)
             refuse("foreign_correction_check_owner");