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

package/dist/services/memory-retained-second-repairs.js

@@ -0,0 +1,162 @@
+import { createHash } from "node:crypto";
+import { assertMemorySqlCustody } from "./memory-custody-snapshot.js";
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedHistoricalOriginalMemoryReview } from "./memory-historical-original-review.js";
+import { PreparedHistoricalCorrectedMemoryReview } from "./memory-historical-corrected-review.js";
+import { readRetainedCorrectedMemoryReviewRegistration } from "./memory-corrected-review-registration.js";
+import { validateMemoryReviewCorrectionPlan, memoryRepairCanonicalPaths } from "./memory-review-correction-plan.js";
+import { memoryRepairBatch, memoryRepairWorkerSchema } from "./memory-repair-registration.js";
+import { readWorkBatchCustody } from "./work-registry.js";
+const token = Symbol("retained-second-memory-repairs");
+function refuse(reason) {
+    throw new AppError("memory_retained_second_repairs_invalid", "Second repair history lacks independent plan, review and allocation custody", 2, { reason, effect: "no_effect" });
+}
+function selected(context, scope) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.second_repair_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? LIMIT 2", [scope.project_id, scope.run_id, scope.attempt, scope.parent_work_id]);
+    if (!rows.length)
+        refuse("registration_missing");
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+        refuse("ambiguous_or_unbounded_registration");
+    let receipt;
+    try {
+        receipt = JSON.parse(rows[0].payload_json);
+    }
+    catch {
+        return refuse("invalid_registration");
+    }
+    if (!receipt || receipt.schema_id !== "dd-flow/memory-second-repair-registration@1" || receipt.run_id !== scope.run_id
+        || receipt.wave !== 2 || hybridDigest(receipt.scope) !== hybridDigest(scope)
+        || [receipt.first_review_registration_sha256, receipt.first_review_input_sha256, receipt.first_check_receipt_sha256,
+            receipt.review_sha256, receipt.projection_sha256, receipt.plan_sha256, receipt.batch_sha256].some(hash => typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash))
+        || typeof receipt.plan_base64 !== "string")
+        refuse("changed_registration");
+    const bytes = Buffer.from(receipt.plan_base64, "base64");
+    if (!bytes.length || bytes.length > 1024 * 1024 || bytes.toString("base64") !== receipt.plan_base64
+        || createHash("sha256").update(bytes).digest("hex") !== receipt.plan_sha256)
+        refuse("changed_plan_bytes");
+    return receipt;
+}
+function assertAllocation(context, receipt, batch) {
+    const ids = receipt.work_ids, scope = receipt.scope;
+    if (!ids || typeof ids !== "object" || Array.isArray(ids) || Object.keys(ids).length !== batch.works.length
+        || Object.values(ids).some(id => typeof id !== "string" || !id) || new Set(Object.values(ids)).size !== batch.works.length
+        || hybridDigest(batch.works) !== receipt.batch_sha256)
+        refuse("changed_repair_batch");
+    for (const item of batch.works) {
+        const id = ids[item.key];
+        if (!id)
+            refuse("missing_repair_work");
+        const custody = readWorkBatchCustody(context, id);
+        if (custody.item_key !== item.key || custody.batch_sha256 !== receipt.batch_sha256
+            || hybridDigest(custody.work_ids) !== hybridDigest(ids) || hybridDigest(custody.scope) !== hybridDigest({
+            project_id: scope.project_id, run_id: scope.run_id, stage: "review", attempt: scope.attempt, cycle: "",
+            parent_work_id: scope.parent_work_id, request_key: "memory-repair-wave-2"
+        }))
+            refuse("changed_work_custody");
+    }
+}
+/** Retained second graph only. Does not grant current source/write admission,
+ * allocate replacement Works or dispatch providers after receipt loss. */
+export class PreparedRetainedSecondMemoryRepairs {
+    #custodyKey = {};
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #receipt in value;
+    }
+    #history;
+    #receipt;
+    #batch;
+    #plan;
+    #bundle;
+    constructor(key, history, receipt, batch, plan) {
+        if (key !== token)
+            refuse("retained_token_required");
+        this.#history = history;
+        this.#receipt = structuredClone(receipt);
+        this.#batch = structuredClone(batch);
+        this.#plan = structuredClone(plan);
+        this.#bundle = history.bundle();
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        return this.#prepare(context, input, false);
+    }
+    /** Closed-review history only. The original owner pins closed SQL custody;
+     * this never reopens review or grants new writer/launch admission. */
+    static prepareAfterReview(context, input) {
+        return this.#prepare(context, input, true);
+    }
+    static #prepare(context, input, closed) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(input.bundle.descriptor.descriptor.id))
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const original = closed ? PreparedHistoricalOriginalMemoryReview.prepare(context, input)
+            : PreparedHistoricalOriginalMemoryReview.prepareWhileReviewOpen(context, input);
+        const scope = original.registration().scope;
+        const receipt = context.db.readSnapshot(() => selected(context, scope)), bytes = Buffer.from(receipt.plan_base64, "base64");
+        if (input.expectedBytes !== undefined && (!(input.expectedBytes instanceof Uint8Array) || !bytes.equals(Buffer.from(input.expectedBytes))))
+            refuse("plan_replay_conflict");
+        const first = readRetainedCorrectedMemoryReviewRegistration(context, scope, receipt.first_review_input_sha256, receipt.first_check_receipt_sha256);
+        if (!first || hybridDigest(first) !== receipt.first_review_registration_sha256)
+            refuse("changed_first_registration");
+        const history = PreparedHistoricalCorrectedMemoryReview.prepare(context, { original, correctedInputSha256: first.input_sha256,
+            checkReceiptSha256: first.check_receipt_sha256 });
+        if (history.reviewSha256() !== receipt.review_sha256 || hybridDigest(history.projection()) !== receipt.projection_sha256)
+            refuse("changed_first_review");
+        const view = first.view, assignments = new Map(view.assignments.map(item => [item.unit.id, item.unit]));
+        const plan = validateMemoryReviewCorrectionPlan(bytes, input.bundle.engine(), { runId: scope.run_id, wave: 2,
+            canonicalPaths: memoryRepairCanonicalPaths(context, input.bundle),
+            reviewSha256: receipt.review_sha256, units: view.unit_inventory.map(unit => assignments.get(unit.id) ?? unit), findings: history.projection().findings });
+        if (history.projection().outcome === "blocked")
+            refuse("blocked_first_review");
+        for (const item of plan.works)
+            input.bundle.execution.work("review", item.profile_id ?? undefined);
+        if (JSON.parse(input.bundle.engine().schema("memory-repair-work-result").toString("utf8")).$id !== memoryRepairWorkerSchema)
+            refuse("frozen_worker_schema_required");
+        const refs = new Map(view.run_inputs.map(ref => [`${ref.root}:${ref.path}`, ref]));
+        for (const worker of history.settlementProof(context).workers) {
+            const ref = { root: "run", ...worker.result }, key = `run:${ref.path}`, prior = refs.get(key);
+            if (prior && prior.sha256 !== ref.sha256)
+                refuse("conflicting_review_reference");
+            refs.set(key, ref);
+        }
+        const batch = memoryRepairBatch({ scope, plan, planSha256: receipt.plan_sha256, originalRegistrationSha256: hybridDigest(first),
+            references: [...refs.values()], findings: history.projection().findings });
+        const expected = { schema_id: "dd-flow/memory-second-repair-registration@1", run_id: scope.run_id, scope, wave: 2,
+            first_review_registration_sha256: hybridDigest(first), first_review_input_sha256: first.input_sha256,
+            first_check_receipt_sha256: first.check_receipt_sha256, review_sha256: history.reviewSha256(), projection_sha256: hybridDigest(history.projection()),
+            plan_sha256: receipt.plan_sha256, plan_base64: bytes.toString("base64"), batch_sha256: hybridDigest(batch.works), work_ids: receipt.work_ids };
+        if (hybridDigest(expected) !== hybridDigest(receipt))
+            refuse("changed_registration");
+        const prepared = new PreparedRetainedSecondMemoryRepairs(token, history, receipt, batch, plan);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    receipt() { return structuredClone(this.#receipt); }
+    get sha256() { return hybridDigest(this.#receipt); }
+    bundle() { return this.#bundle; }
+    batch() { return structuredClone(this.#batch); }
+    plan() { return structuredClone(this.#plan); }
+    /** The first wave's actual settled baseline, with only this registered
+     * second plan's admitted write paths. No current bytes are adopted here. */
+    initialDocumentBaseline() {
+        const paths = [...new Set(this.#batch.works.flatMap(item => item.payload.memory_repair.write_paths))].sort();
+        return this.#history.settledDocumentBaseline().withWritePaths(paths);
+    }
+    initialInputView() { return this.#history.retainedInputView(); }
+    firstReviewProof(context) { this.assertCustody(context); return this.#history.settlementProof(context); }
+    firstEffectiveReviewProof(context) { this.assertCustody(context); return this.#history.effectiveReviewProof(context); }
+    verificationProfileHash(context) { this.assertCustody(context); return this.#history.verificationProfileHash(context); }
+    assertCustody(context) {
+        const history = this.#history;
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            history.assertCustody(context);
+            if (hybridDigest(selected(context, this.#receipt.scope)) !== hybridDigest(this.#receipt))
+                refuse("registration_changed");
+            assertAllocation(context, this.#receipt, this.#batch);
+        });
+    }
+    revalidate(context) { this.#history.revalidate(context); this.assertCustody(context); }
+}

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

@@ -0,0 +1,214 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedMemoryInitialReviewInputs } from "./memory-review-inputs.js";
+import { readRegisteredMemoryReview, memoryReviewBatch, memoryReviewWorkerSchema } from "./memory-review-registration.js";
+import { readWorkBatchCustody } from "./work-registry.js";
+import { validateMemoryReviewWorkResult } from "./memory-review-work-results.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { PreparedMemoryStageResult, memorySourceKey } from "./memory-stage-results.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const preparationToken = Symbol("memory-initial-review-acceptance");
+function refuse(reason) {
+    throw new AppError("memory_review_acceptance_invalid", "Independent review lacks registered and settled result custody", 2, { reason, effect: "no_effect" });
+}
+function json(bytes, bound) {
+    try {
+        if (typeof bytes !== "string" || !bytes.length || Buffer.byteLength(bytes) > bound)
+            refuse("unbounded_receipt");
+        const value = JSON.parse(bytes);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            refuse("invalid_receipt");
+        return value;
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_receipt");
+    }
+}
+/** SQL-only historical settlement selection, not a status-only completion
+ * check. No current Session activity or obsolete copy is required after the
+ * Work writer committed its unchanged-copy proof and result atomically.
+ */
+export function readMemoryReviewWorkSettlement(context, registration, workId, harness) {
+    const scope = registration.scope, allocation = readWorkBatchCustody(context, workId);
+    const run = context.db.get("SELECT run_root,run_dir FROM runs WHERE project_id=? AND id=?", [scope.project_id, scope.run_id]);
+    const root = run?.run_root ?? run?.run_dir;
+    const work = context.db.get("SELECT status,result,result_schema FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.project_id, scope.run_id, workId]);
+    if (!root || !path.isAbsolute(root) || !work || work.status !== "completed" || work.result_schema !== memoryReviewWorkerSchema
+        || typeof work.result !== "string" || !work.result.length || Buffer.byteLength(work.result) > 1024 * 1024)
+        refuse("review_work_not_settled");
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.review_work_settlement' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [scope.project_id, scope.run_id, workId]);
+    if (rows.length !== 1)
+        refuse("review_settlement_missing_or_ambiguous");
+    const receipt = json(rows[0].payload_json, 32768);
+    const links = context.db.all("SELECT id,session_id,hook_event_id,result_path,result_receipt_json,start_receipt_json,start_publication_status FROM work_sessions WHERE work_id=? AND status='completed' LIMIT 2", [workId]);
+    if (links.length !== 1 || context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? AND status='running' LIMIT 1", [workId]))
+        refuse("completed_reviewer_session_missing");
+    const link = links[0], publication = json(link.result_receipt_json, 32768), start = json(link.start_receipt_json, 8 * 1024 * 1024);
+    const session = context.db.get("SELECT provider_session_id FROM sessions WHERE project_id=? AND run_id=? AND session_id=? AND harness=?", [scope.project_id, scope.run_id, link.session_id, harness]);
+    if (!session?.provider_session_id || link.start_publication_status !== "published" || link.result_path !== path.join(root, "works", workId, "result.json"))
+        refuse("review_session_or_publication_changed");
+    if (!context.db.get("SELECT 1 FROM hook_events WHERE project_id=? AND event_key=? AND session_id=? AND harness=? AND provider_session_id=? AND status='claimed' AND event_name='PreToolUse'", [scope.project_id, link.hook_event_id, link.session_id, harness, session.provider_session_id]))
+        refuse("review_start_hook_missing");
+    if (context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=w.project_id WHERE w.project_id=? AND w.run_id=? AND w.work_id<>? AND s.harness=? AND s.provider_session_id=? LIMIT 1", [scope.project_id, scope.run_id, workId, harness, session.provider_session_id]))
+        refuse("reviewer_not_independent");
+    if (start.version !== 2 || typeof start.context !== "string" || start.context_sha256 !== hash(start.context)
+        || !Number.isSafeInteger(start.generation) || start.generation < 0)
+        refuse("review_start_receipt_changed");
+    const input = json(start.context, 4 * 1024 * 1024);
+    const view = registration.view;
+    const expectedInput = { schema_id: "dd-flow/review-input@3", parent_work_id: scope.parent_work_id, kind: "memory-review",
+        cycle: `memory-review-wave-${registration.wave}`, generation: start.generation,
+        workspace_fingerprint: view.source_sha256, source_policy: view.source_policy, source_sha256: view.source_sha256, run_inputs: view.run_inputs };
+    if (input.run_id !== scope.run_id || input.work_id !== workId || input.parent_work_id !== scope.parent_work_id
+        || input.read_only !== true || input.result_schema !== memoryReviewWorkerSchema || hybridDigest(input.review_input) !== hybridDigest(expectedInput))
+        refuse("review_start_input_changed");
+    const value = json(work.result, 1024 * 1024), bytes = Buffer.from(work.result), sha256 = hash(bytes);
+    const expected = { schema_id: "dd-flow/memory-review-work-settlement@1", run_id: scope.run_id, work_id: workId,
+        work_session_id: link.id, session_id: link.session_id, harness, provider_session_id: session.provider_session_id,
+        scope, wave: registration.wave, unit_id: value.unit_id, input_sha256: registration.input_sha256,
+        registration_sha256: hybridDigest(registration), allocation_sha256: hybridDigest(allocation), start_receipt_sha256: hash(link.start_receipt_json), result_sha256: sha256 };
+    if (hybridDigest(receipt) !== hybridDigest(expected))
+        refuse("review_settlement_changed");
+    if (publication.work_id !== workId || publication.work_session_id !== link.id || publication.status !== "completed"
+        || publication.result_sha256 !== sha256 || publication.previous_sha256 !== null && (typeof publication.previous_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(publication.previous_sha256)))
+        refuse("review_result_publication_changed");
+    return { workId, bytes, result: { path: path.relative(root, link.result_path).split(path.sep).join("/"), sha256 },
+        authority: hybridDigest({ receipt, publication, start }), root };
+}
+const settled = readMemoryReviewWorkSettlement;
+/** Initial-wave fan-in only. This is not repair admission or Stage settlement.
+ * Every applicable assignment must have its own independent settled Work.
+ */
+export class PreparedMemoryInitialReviewAcceptance {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #inputs in value;
+    }
+    #inputs;
+    #registration;
+    #harness;
+    #workers;
+    #results;
+    #observed;
+    constructor(token, inputs, registration, harness, workers, results, observed) {
+        if (token !== preparationToken)
+            refuse("prepared_wave_token_required");
+        this.#inputs = inputs;
+        this.#registration = structuredClone(registration);
+        this.#harness = harness;
+        this.#workers = workers;
+        this.#results = results;
+        this.#observed = observed;
+        Object.freeze(this);
+    }
+    static prepare(context, inputs, bundle) {
+        if (!(inputs instanceof PreparedMemoryInitialReviewInputs) || !(bundle instanceof RetainedExecutionBundle))
+            refuse("prepared_wave_required");
+        const view = inputs.value();
+        if (view.scope.bundle_sha256 !== bundle.sha256 || view.scope.execution_sha256 !== bundle.execution.sha256)
+            refuse("foreign_wave_bundle");
+        inputs.revalidate(context);
+        const registration = readRegisteredMemoryReview(context, view.scope, view.wave);
+        if (registration.input_sha256 !== inputs.sha256)
+            refuse("review_registration_changed");
+        const harness = runtimeHarness(bundle.execution.work("review").worker), batch = memoryReviewBatch(view);
+        const workers = context.db.readSnapshot(() => batch.works.map(item => settled(context, registration, registration.work_ids[item.key], harness)));
+        const results = workers.map((worker, index) => validateMemoryReviewWorkResult(worker.bytes, bundle.engine(), {
+            workId: worker.workId, packet: batch.works[index].payload.memory_review, references: view.run_inputs
+        }));
+        const root = context.db.get("SELECT run_root,run_dir FROM runs WHERE project_id=? AND id=?", [view.scope.project_id, view.scope.run_id]);
+        if (!root)
+            refuse("owned_run_missing");
+        const observed = ObservedMemorySources.capture({ run: root.run_root ?? root.run_dir }, workers.map(worker => ({ root: "run", path: worker.result.path })));
+        const hashes = observed.hashes();
+        if (workers.some(worker => hashes.get(memorySourceKey("run", worker.result.path)) !== worker.result.sha256))
+            refuse("published_review_result_changed");
+        const prepared = new PreparedMemoryInitialReviewAcceptance(preparationToken, inputs, registration, harness, workers, results, observed);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    results() { return structuredClone(this.#results); }
+    resultProjection() { return memoryInitialReviewProjection(this.#registration.view, this.#results, this.references()); }
+    references() {
+        return this.#workers.map(worker => ({ reviewer_work_id: worker.workId, input_sha256: this.#registration.input_sha256,
+            result: { ...worker.result }, unit_ids: [this.#results.find(result => result.work_id === worker.workId).unit_id] }));
+    }
+    /** A coordinator cannot suppress reviewer findings or resolve them without
+     * an admitted correction wave. Initial-wave findings are still open.
+     */
+    assertResult(result) {
+        if (!(result instanceof PreparedMemoryStageResult))
+            refuse("prepared_result_required");
+        assertMemoryInitialReviewProjection(result.value(), this.#registration.view, this.#results, this.references());
+    }
+    /** SQL-only facts for an independent Stage acceptance receipt. This does
+     * not itself accept the Stage or authorize a correction/another wave. */
+    settlementProof(context, result) {
+        this.assertCustody(context);
+        this.assertResult(result);
+        return { registration_scope: structuredClone(this.#registration.scope), registration_sha256: hybridDigest(this.#registration),
+            wave: 0, workers: this.#workers.map(worker => ({ work_id: worker.workId, authority_sha256: worker.authority, result: { ...worker.result } })) };
+    }
+    assertCustody(context) {
+        this.#inputs.assertCustody(context);
+        if (hybridDigest(readRegisteredMemoryReview(context, this.#registration.scope, this.#registration.wave)) !== hybridDigest(this.#registration))
+            refuse("review_registration_changed");
+        for (const worker of this.#workers)
+            if (settled(context, this.#registration, worker.workId, this.#harness).authority !== worker.authority)
+                refuse("review_settlement_changed");
+    }
+    revalidate(context) { this.#inputs.revalidate(context); this.#observed.revalidate(); this.assertCustody(context); }
+}
+/** CLI-owned fan-in: narrative proposals cannot suppress or merge independent findings. */
+export function memoryInitialReviewProjection(view, results, references) {
+    return { ...memoryReviewWaveProjection(results, view.diagnostic_findings),
+        units: view.unit_inventory.map(unit => ({ ...structuredClone(unit), outcome: unit.applicability === "not-applicable"
+                ? "not-applicable" : results.find(result => result.unit_id === unit.id)?.outcome })),
+        details: { reviews: structuredClone(references), repair_wave: 0, repair_work_ids: [] } };
+}
+export function projectMemoryReviewResult(proposal, projection) {
+    return { ...proposal, units: projection.units, findings: projection.findings, outcome: projection.outcome, details: projection.details };
+}
+/** Pure projection validation, not registration or settlement authority. */
+export function assertMemoryInitialReviewProjection(value, view, results, references) {
+    const projection = memoryReviewWaveProjection(results, view.diagnostic_findings);
+    const details = value.details;
+    if (!details || !Array.isArray(details.repair_work_ids) || !Array.isArray(value.findings) || !Array.isArray(value.units))
+        refuse("invalid_review_projection");
+    if (value.run_id !== view.scope.run_id || value.stage !== "review" || value.input_sha256 !== view.scope.input_sha256
+        || value.outcome !== projection.outcome || details.repair_wave !== 0 || details.repair_work_ids.length
+        || hybridDigest(value.findings) !== hybridDigest(projection.findings)
+        || hybridDigest(details.reviews) !== hybridDigest(references))
+        refuse("review_claim_differs_from_settled_wave");
+    const units = value.units;
+    const inventory = view.unit_inventory;
+    if (!Array.isArray(inventory) || units.length !== inventory.length || new Set(units.map(unit => unit.id)).size !== inventory.length)
+        refuse("review_unit_coverage_changed");
+    for (const original of inventory) {
+        const unit = units.find(unit => unit.id === original.id), review = results.find(item => item.unit_id === original.id);
+        const expectedOutcome = original.applicability === "not-applicable" ? "not-applicable" : review?.outcome;
+        if (!unit || !expectedOutcome || unit.outcome !== expectedOutcome
+            || hybridDigest([unit.id, unit.aspect, unit.applicability, unit.evidence, unit.artifacts])
+                !== hybridDigest([original.id, original.aspect, original.applicability, original.evidence, original.artifacts]))
+            refuse("review_unit_claim_changed");
+        if (original.applicability === "not-applicable" && hybridDigest([unit.reason, unit.next_action]) !== hybridDigest([original.reason, original.next_action]))
+            refuse("review_unit_applicability_changed");
+    }
+}
+/** Stable projection only, never a substitute for SQL/physical fan-in proof.
+ * Hash-scoped finding ids avoid collisions between local reviewer namespaces.
+ */
+export function memoryReviewWaveProjection(results, diagnostics = []) {
+    return { outcome: results.some(result => result.outcome === "blocked") ? "blocked"
+            : diagnostics.length || results.some(result => result.outcome === "needs_repair") ? "needs_repair" : "accepted",
+        findings: [...diagnostics.map(finding => ({ ...structuredClone(finding), id: `MVF-${hybridDigest({ id: finding.id, unit_id: finding.unit_id }).slice(0, 32)}`, status: "open", resolution_refs: [] })), ...results.flatMap(result => result.findings.map(finding => ({
+                id: `MRF-${hybridDigest({ work_id: result.work_id, finding_id: finding.id }).slice(0, 32)}`,
+                unit_id: result.unit_id, severity: finding.severity, statement: finding.summary,
+                evidence: structuredClone(finding.evidence), status: "open", resolution_refs: []
+            })))] };
+}

package/dist/services/memory-review-correction-plan.js

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { PreparedRetainedMemoryReviewResults } from "./memory-retained-review-results.js";
+import { memoryReviewWaveProjection } from "./memory-review-acceptance.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { reviewSourceHash, reviewEnvironmentAllowed } from "./review-copy.js";
+import { memoryProjectConfigurationPath } from "./memory-composition-graph.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { upgradeAuthoringPaths } from "./memory-upgrade-inventory.js";
+function refuse(reason) {
+    throw new AppError("memory_review_correction_invalid", "Correction plan differs from retained material findings", 2, { reason, effect: "no_effect" });
+}
+const alias = (value) => value.normalize("NFC").toLowerCase();
+const overlapAliases = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+const overlap = (a, b) => overlapAliases(alias(a), alias(b));
+/** Exact project-owned document paths shared by graph and physical admission. */
+export function assertMemoryRepairWritePaths(paths, canonicalPaths = new Set()) {
+    if (!Array.isArray(paths) || !paths.length || paths.length > 512)
+        refuse("foreign_correction_write");
+    if (paths.some(logical => typeof logical !== "string"))
+        refuse("foreign_correction_write");
+    const normalizedPaths = paths.map(alias);
+    if (new Set(normalizedPaths).size !== paths.length)
+        refuse("aliased_correction_paths");
+    for (const [index, logical] of paths.entries()) {
+        if (typeof logical !== "string")
+            refuse("foreign_correction_write");
+        const parts = logical.split("/");
+        if (!logical.startsWith(".memory-bank/") || logical.includes("\\") || logical.includes("\0")
+            || logical.length > 4096 || parts.some(part => !part || part === "." || part === "..")
+            || parts.some(part => { const normalized = alias(part); return !reviewEnvironmentAllowed(normalized) || [".git", "node_modules", ".dd-flow"].includes(normalized); })
+            || !memoryProjectConfigurationPath(logical) && !canonicalPaths.has(logical)
+                && [".memory-bank/dd-flow", ".memory-bank/mbb"].some(canonical => overlapAliases(normalizedPaths[index], canonical)))
+            refuse("foreign_correction_write");
+    }
+}
+/** Exact exceptions from the original CLI-selected ownership inventory, not
+ * path names or authority fields supplied in a repair proposal. Canonical
+ * defaults, generated markers, links and directory aliases remain excluded. */
+export function memoryRepairCanonicalPaths(context, bundle) {
+    if (!(bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    if (bundle.descriptor.descriptor.id === "mb-init")
+        return new Set();
+    const frozen = bundle.execution.snapshot().scope;
+    const storage = readUpgradeStorageReadiness(context, { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace }), selected = storage?.selection;
+    if (!selected || selected.payload.execution.sha256 !== bundle.execution.sha256)
+        refuse("retained_upgrade_selection_required");
+    const data = readAcceptedStageData(context, { projectId: storage.receipt.project_id, runId: bundle.manifest.run_id, stage: "diff-analysis" });
+    const diff = JSON.parse(data.bytes.toString("utf8"));
+    if (data.data_schema_id !== "dd-flow/mb-upgrade-stage-result@1" || diff.stage !== "diff-analysis" || diff.outcome !== "accepted")
+        refuse("accepted_upgrade_diff_required");
+    const inventory = selected.payload.current.inventory.inventory;
+    const paths = [...upgradeAuthoringPaths(inventory, diff.details.path_map).values()].flat();
+    return new Set(paths.filter(logical => {
+        const entry = inventory.entries.find(entry => `.memory-bank/${entry.path}` === logical);
+        return [".memory-bank/dd-flow/", ".memory-bank/mbb/"].some(prefix => logical.startsWith(prefix))
+            && logical.split("/").every(part => reviewEnvironmentAllowed(alias(part)) && ![".git", "node_modules", ".dd-flow"].includes(alias(part)))
+            && (!entry || ["project", "local-customized"].includes(entry.ownership));
+    }));
+}
+/** Semantic graph checks after strict frozen-schema admission. This projection
+ * is not Work allocation, source-byte admission or filesystem permission.
+ */
+export function validateMemoryReviewCorrectionGraph(plan, units, findings, canonicalPaths = new Set()) {
+    const material = new Map(findings.filter(finding => finding.severity !== "minor" && finding.status === "open").map(finding => [finding.id, finding]));
+    if (!material.size)
+        refuse("no_material_correction_required");
+    const inventory = new Map(units.filter(unit => unit.applicability === "applicable").map(unit => [unit.id, unit]));
+    const byKey = new Map(plan.works.map(work => [work.key, work]));
+    if (byKey.size !== plan.works.length || new Set(plan.works.map(work => alias(work.key))).size !== plan.works.length)
+        refuse("duplicate_correction_work");
+    const assigned = new Set();
+    for (const work of plan.works) {
+        if (!work.task.trim() || work.task.includes("\0"))
+            refuse("missing_correction_task");
+        if (work.depends_on.some(key => !byKey.has(key) || key === work.key))
+            refuse("foreign_correction_dependency");
+        assertMemoryRepairWritePaths(work.write_paths, canonicalPaths);
+        const targetUnits = new Set();
+        for (const id of work.finding_ids) {
+            const finding = material.get(id);
+            if (!finding || assigned.has(id))
+                refuse("foreign_or_repeated_correction_finding");
+            assigned.add(id);
+            targetUnits.add(finding.unit_id);
+        }
+        if (targetUnits.size !== work.unit_ids.length || work.unit_ids.some(id => !targetUnits.has(id) || !inventory.has(id)))
+            refuse("correction_unit_scope_changed");
+    }
+    if (assigned.size !== material.size)
+        refuse("missing_material_correction");
+    const remaining = new Map(plan.works.map(work => [work.key, work.depends_on.length]));
+    const children = new Map();
+    for (const work of plan.works)
+        for (const dependency of work.depends_on)
+            children.set(dependency, [...(children.get(dependency) ?? []), work.key]);
+    const ready = plan.works.filter(work => !work.depends_on.length).map(work => work.key), ancestors = new Map();
+    for (let cursor = 0; cursor < ready.length; cursor++) {
+        const work = byKey.get(ready[cursor]), prior = new Set(work.depends_on);
+        for (const dependency of work.depends_on)
+            for (const key of ancestors.get(dependency) ?? [])
+                prior.add(key);
+        ancestors.set(work.key, prior);
+        for (const child of children.get(work.key) ?? []) {
+            const count = remaining.get(child) - 1;
+            remaining.set(child, count);
+            if (!count)
+                ready.push(child);
+        }
+    }
+    if (ready.length !== plan.works.length)
+        refuse("cyclic_correction_graph");
+    for (let index = 0; index < plan.works.length; index++) {
+        const left = plan.works[index];
+        for (const right of plan.works.slice(index + 1)) {
+            if (ancestors.get(left.key).has(right.key) || ancestors.get(right.key).has(left.key))
+                continue;
+            const readPaths = (work) => work.unit_ids.flatMap(id => {
+                const unit = inventory.get(id);
+                return [...unit.evidence, ...unit.artifacts].filter(ref => ["project", "workspace"].includes(ref.root)).map(ref => ref.path);
+            });
+            if (left.write_paths.some(a => right.write_paths.some(b => overlap(a, b)))
+                || left.write_paths.some(a => readPaths(right).some(b => overlap(a, b)))
+                || right.write_paths.some(a => readPaths(left).some(b => overlap(a, b))))
+                refuse("unordered_correction_work");
+        }
+    }
+}
+export function validateMemoryReviewCorrectionPlan(bytes, engine, binding) {
+    try {
+        if (!(bytes instanceof Uint8Array) || !bytes.byteLength || bytes.byteLength > 1024 * 1024 || !(engine instanceof AdmittedFrozenEngine)
+            || ![1, 2].includes(binding.wave))
+            refuse("invalid_correction_binding");
+        const schema = JSON.parse(engine.schema("memory-review-correction-plan").toString("utf8"));
+        const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        if (schema.$id !== "dd-flow/memory-review-correction-plan@1" || !new Ajv2020({ strict: true, validateFormats: false }).compile(schema)(value))
+            refuse("invalid_correction_schema");
+        if (value.run_id !== binding.runId || value.wave !== binding.wave || value.review_sha256 !== binding.reviewSha256)
+            refuse("foreign_correction_identity");
+        validateMemoryReviewCorrectionGraph(value, binding.units, binding.findings, binding.canonicalPaths);
+        return structuredClone(value);
+    }
+    catch (error) {
+        if (error instanceof AppError && ["memory_review_correction_invalid", "frozen_engine_invalid"].includes(error.code))
+            throw error;
+        return refuse("invalid_correction_plan_or_binding");
+    }
+}
+/** First correction admission before document mutation/Work registration.
+ * Restart after writes must restore the independently registered repair plan;
+ * it cannot reprepare this initial-byte view or rebase unexplained changes.
+ */
+export class PreparedMemoryInitialCorrectionPlan {
+    sha256;
+    #review;
+    #bytes;
+    #value;
+    #observed;
+    constructor(review, bytes, value, observed) {
+        this.#review = review;
+        this.#bytes = bytes;
+        this.#value = value;
+        this.#observed = observed;
+        this.sha256 = createHash("sha256").update(bytes).digest("hex");
+        Object.freeze(this);
+    }
+    static prepare(context, review, bytes) {
+        if (!(review instanceof PreparedRetainedMemoryReviewResults))
+            refuse("prepared_review_results_required");
+        review.revalidate(context);
+        const results = review.results(), original = review.original(), registration = original.registration(), bundle = original.bundle();
+        if (results.some(result => result.outcome === "blocked"))
+            refuse("blocked_review_requires_resolution");
+        const value = validateMemoryReviewCorrectionPlan(bytes, bundle.engine(), { runId: registration.run_id, wave: 1,
+            canonicalPaths: memoryRepairCanonicalPaths(context, bundle),
+            reviewSha256: review.sha256, units: registration.view.unit_inventory, findings: memoryReviewWaveProjection(results, registration.view.diagnostic_findings).findings });
+        for (const work of value.works)
+            bundle.execution.work("review", work.profile_id ?? undefined);
+        const refs = registration.view.run_inputs.filter(ref => ref.root === "workspace");
+        const observed = ObservedMemorySources.capture({ workspace: bundle.execution.snapshot().scope.workspace }, refs.map(ref => ({ root: "workspace", path: ref.path })));
+        const hashes = observed.hashes();
+        if (refs.some(ref => hashes.get(memorySourceKey("workspace", ref.path)) !== ref.sha256))
+            refuse("original_documents_changed_before_correction");
+        const prepared = new PreparedMemoryInitialCorrectionPlan(review, Buffer.from(bytes), value, observed);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    bytes() { return Buffer.from(this.#bytes); }
+    value() { return structuredClone(this.#value); }
+    review() { return this.#review; }
+    assertCustody(context) { this.#review.assertCustody(context); }
+    revalidate(context) {
+        this.#review.revalidate(context);
+        this.#observed.revalidate();
+        const original = this.#review.original(), view = original.registration().view;
+        if (reviewSourceHash(original.bundle().execution.snapshot().scope.workspace, view.run_inputs.filter(ref => ref.root === "workspace").map(ref => ref.path), view.base) !== view.source_sha256)
+            refuse("original_copy_source_changed_before_correction");
+        this.assertCustody(context);
+    }
+}