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

package/dist/services/memory-second-repair-registration.js

@@ -0,0 +1,88 @@
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedMemorySecondCorrectionPlan } from "./memory-second-correction-plan.js";
+import { memoryRepairBatch, memoryRepairWorkerSchema } from "./memory-repair-registration.js";
+import { addWorkBatch, prepareWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+const event = "memory.second_repair_registration";
+function refuse(reason) {
+    throw new AppError("memory_second_repair_registration_invalid", "Second repair allocation lacks independently settled first-wave custody", 2, { reason, effect: "no_effect" });
+}
+/** Allocation only. The generic repair dispatch guard remains closed until
+ * wave-two baseline/copy/publication and re-review owners are implemented. */
+export function registerMemorySecondCorrections(context, plan) {
+    if (!PreparedMemorySecondCorrectionPlan.isPrepared(plan))
+        refuse("prepared_second_plan_required");
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const history = plan.historicalReview(context), review = plan.review(), registration = review.registration();
+    const first = registration.receipt(), view = first.view, scope = first.scope, bundle = registration.inputs().bundle();
+    const schema = JSON.parse(bundle.engine().schema("memory-repair-work-result").toString("utf8"));
+    if (schema.$id !== memoryRepairWorkerSchema)
+        refuse("frozen_repair_worker_schema_required");
+    const references = new Map(view.run_inputs.map(ref => [`${ref.root}:${ref.path}`, ref]));
+    for (const item of review.references()) {
+        const ref = { root: "run", ...item.result }, key = `run:${ref.path}`, prior = references.get(key);
+        if (prior && prior.sha256 !== ref.sha256)
+            refuse("conflicting_review_reference");
+        references.set(key, ref);
+    }
+    const batch = memoryRepairBatch({ scope, plan: plan.value(), planSha256: plan.sha256,
+        originalRegistrationSha256: hybridDigest(first), references: [...references.values()], findings: history.projection().findings });
+    const requestKey = "memory-repair-wave-2", batchScope = { 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: requestKey };
+    const batchInput = { parentWorkId: scope.parent_work_id, requestKey, stage: "review", value: batch };
+    const prepared = prepareWorkBatch(context, batchInput);
+    const identity = { 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: plan.sha256, plan_base64: plan.bytes().toString("base64"),
+        batch_sha256: hybridDigest(batch.works) };
+    function selected() {
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? 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, event, scope.run_id, scope.attempt, scope.parent_work_id]);
+        if (!rows.length)
+            return null;
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+            refuse("ambiguous_or_unbounded_registration");
+        let retained;
+        try {
+            retained = JSON.parse(rows[0].payload_json);
+        }
+        catch {
+            return refuse("invalid_registration");
+        }
+        const ids = retained.work_ids;
+        if (!ids || typeof ids !== "object" || Array.isArray(ids) || Object.keys(ids).length !== batch.works.length
+            || new Set(Object.values(ids)).size !== batch.works.length || Object.values(ids).some(id => typeof id !== "string" || !id)
+            || hybridDigest(retained) !== hybridDigest({ ...identity, work_ids: ids }))
+            refuse("registration_replay_conflict");
+        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 !== identity.batch_sha256
+                || hybridDigest(custody.scope) !== hybridDigest(batchScope) || hybridDigest(custody.work_ids) !== hybridDigest(ids))
+                refuse("changed_work_custody");
+        }
+        return retained;
+    }
+    plan.revalidate(context);
+    history.revalidate(context);
+    return context.db.writeTransaction(() => {
+        plan.assertCustody(context);
+        history.assertCustody(context);
+        const prior = selected();
+        if (!prior && context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND json_extract(payload_json,'$.kind')='memory-repair' AND json_extract(payload_json,'$.memory_repair.wave')=2 LIMIT 1", [scope.project_id, scope.run_id, scope.parent_work_id]))
+            refuse("repair_registration_missing");
+        const allocated = addWorkBatch(context, { ...batchInput, prepared });
+        if (Boolean(prior) !== allocated.replayed || prior && hybridDigest(prior.work_ids) !== hybridDigest(allocated.work_ids))
+            refuse("repair_registration_missing");
+        if (!prior)
+            appendAudit(context, { projectId: scope.project_id, eventType: event, payload: { ...identity, work_ids: allocated.work_ids } });
+        const retained = selected();
+        if (!retained)
+            refuse("repair_registration_missing");
+        return { wave: 2, plan_sha256: retained.plan_sha256, work_ids: { ...retained.work_ids }, replayed: Boolean(prior) };
+    });
+}

package/dist/services/memory-second-repair-source.js

@@ -0,0 +1,187 @@
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedRetainedSecondMemoryRepairs } from "./memory-retained-second-repairs.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+import { readDescriptorCoordinatorSession } from "./descriptor-coordinator-session.js";
+import { readMemoryReviewPhase } from "./memory-review-inputs.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { reviewSourceHash, reviewSourcePaths } from "./review-copy.js";
+import { readWorkBatchCustody } from "./work-registry.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { PreparedMemoryRepairCurrentView } from "./memory-repair-current-view.js";
+const token = Symbol("second-memory-repair-source");
+function refuse(reason) {
+    throw new AppError("memory_second_repair_source_invalid", "Second repair source lacks explained settled documents and active coordinator custody", 2, { reason, effect: "no_effect" });
+}
+/** Initial or independently registered post-peer source admission.
+ * Dependent second Works cannot rebase unexplained current bytes.
+ * No baseline receipt, copy, Work start or provider dispatch is performed. */
+export class PreparedSecondMemoryRepairSource {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #registration in value;
+    }
+    #registration;
+    #bundle;
+    #workId;
+    #generation;
+    #coordinator;
+    #session;
+    #baseline;
+    #observed;
+    #current;
+    constructor(key, registration, bundle, workId, generation, coordinator, session, baseline, observed, current = null) {
+        if (key !== token)
+            refuse("source_token_required");
+        this.#registration = registration;
+        this.#bundle = bundle;
+        this.#workId = workId;
+        this.#generation = generation;
+        this.#coordinator = coordinator;
+        this.#session = session;
+        this.#baseline = baseline;
+        this.#observed = observed;
+        this.#current = current;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        return this.#prepare(context, input, null);
+    }
+    static prepareCurrent(context, input) {
+        if (!PreparedMemoryRepairCurrentView.isPrepared(input.current))
+            refuse("registered_second_current_view_required");
+        return this.#prepare(context, input, input.current);
+    }
+    static #prepare(context, input, current) {
+        if (!PreparedRetainedSecondMemoryRepairs.isPrepared(input.registration))
+            refuse("retained_second_registration_required");
+        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 registration = input.registration, bundle = input.bundle, scope = registration.receipt().scope;
+        registration.revalidate(context);
+        const assigned = registration.batch().works.find(item => registration.receipt().work_ids[item.key] === input.workId);
+        if (!assigned)
+            refuse("foreign_second_repair_work");
+        const phase = readMemoryReviewPhase(context, { projectId: scope.project_id, runId: scope.run_id }, bundle);
+        if (hybridDigest(phase) !== hybridDigest(scope))
+            refuse("foreign_review_phase");
+        const generation = assertRunMutationAllowed(context, scope.project_id, scope.run_id);
+        const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { projectRoot: bundle.execution.snapshot().scope.projectRoot,
+            runId: scope.run_id, stage: "review" });
+        coordinator.assertAllocatedCustody(context);
+        const session = readDescriptorCoordinatorSession(context, { scope: { projectId: scope.project_id, runId: scope.run_id, stage: "review" },
+            bundle, workId: scope.parent_work_id }, refuse);
+        const view = registration.initialInputView(), workspace = bundle.execution.snapshot().scope.workspace;
+        if (current) {
+            if (current.workId !== input.workId || current.receipt().registration_sha256 !== registration.sha256)
+                refuse("foreign_second_current_view");
+            current.revalidate(context);
+        }
+        // A settled peer changes the source view before another writer is admitted.
+        // Request its existing owner before comparing original bytes. That owner
+        // still rejects unexplained physical drift; never promote an old baseline.
+        if (!current && (assigned.depends_on.length || registration.batch().works.some(item => context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id=? AND status='completed'", [scope.project_id, scope.run_id, registration.receipt().work_ids[item.key]])))) {
+            if (context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.project_id, scope.run_id, input.workId])?.status !== "created")
+                refuse("unstarted_target_required");
+            if (context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='memory.repair_work_baseline' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 1", [scope.project_id, scope.run_id, input.workId]))
+                refuse("settled_second_peer_view_required");
+            refuse("registered_second_current_view_required");
+        }
+        const baseline = current ? current.baseline() : registration.initialDocumentBaseline().withWritePaths(assigned.payload.memory_repair.write_paths), refs = view.run_inputs.filter(ref => ref.root === "workspace");
+        const paths = current ? current.workspaceManifest().entries().filter(entry => entry.kind === "file").map(entry => entry.path) : refs.map(ref => ref.path);
+        const observed = ObservedMemorySources.capture({ workspace }, paths.map(path => ({ root: "workspace", path })));
+        const hashes = observed.hashes();
+        if (!current && refs.some(ref => hashes.get(memorySourceKey("workspace", ref.path)) !== ref.sha256))
+            refuse("first_wave_source_changed");
+        const prepared = new PreparedSecondMemoryRepairSource(token, registration, bundle, input.workId, generation, coordinator, session, baseline, observed, current);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    baseline() { return this.#baseline; }
+    copyInput() {
+        if (this.#current)
+            return this.#current.copyInput();
+        const view = this.#registration.initialInputView();
+        return { source_sha256: view.source_sha256, base: view.base, explicit_inputs: view.run_inputs.filter(ref => ref.root === "workspace").map(ref => ref.path) };
+    }
+    workerRoute() {
+        const receipt = this.#registration.receipt(), assigned = this.#registration.batch().works.find(item => receipt.work_ids[item.key] === this.#workId);
+        return this.#bundle.execution.work("review", assigned.payload.execution_override?.agent_profile_id);
+    }
+    exportedBaseline() {
+        if (this.#current)
+            return this.#current.exportedBaseline();
+        const view = this.#registration.initialInputView(), workspace = this.#bundle.execution.snapshot().scope.workspace;
+        const selected = reviewSourcePaths(workspace, view.run_inputs.filter(ref => ref.root === "workspace").map(ref => ref.path), view.base);
+        if (selected === null)
+            refuse("export_source_inventory_unavailable");
+        const files = new Set(this.#baseline.entries().filter(entry => entry.kind === "file").map(entry => entry.path));
+        return this.#baseline.exported(selected.filter(path => path.startsWith(".memory-bank/") && files.has(path)));
+    }
+    /** SQL-only identity for an independent pre-launch baseline receipt. */
+    baselineBinding(context) {
+        this.assertCustody(context);
+        const receipt = this.#registration.receipt(), assigned = this.#registration.batch().works.find(item => receipt.work_ids[item.key] === this.#workId);
+        return { project_id: receipt.scope.project_id, run_id: receipt.run_id, work_id: this.#workId, generation: this.#generation,
+            registration_sha256: hybridDigest(receipt), allocation_sha256: hybridDigest(readWorkBatchCustody(context, this.#workId)),
+            packet_sha256: assigned.payload.memory_repair.packet_sha256, workspace_root: this.#bundle.execution.snapshot().scope.workspace,
+            first_review_input_sha256: receipt.first_review_input_sha256, first_check_receipt_sha256: receipt.first_check_receipt_sha256,
+            ...(this.#current ? { current_view_sha256: this.#current.sha256, current_view_receipt_sha256: hybridDigest(this.#current.receipt()) } : {}) };
+    }
+    assertCustody(context) {
+        this.#registration.assertCustody(context);
+        const receipt = this.#registration.receipt(), scope = receipt.scope;
+        assertRunMutationAllowed(context, scope.project_id, scope.run_id, this.#generation);
+        this.#coordinator.assertAllocatedCustody(context);
+        if (hybridDigest(readMemoryReviewPhase(context, { projectId: scope.project_id, runId: scope.run_id }, this.#bundle)) !== hybridDigest(scope)
+            || readDescriptorCoordinatorSession(context, { scope: { projectId: scope.project_id, runId: scope.run_id, stage: "review" },
+                bundle: this.#bundle, workId: scope.parent_work_id }, refuse) !== this.#session)
+            refuse("coordinator_custody_changed");
+        const batch = this.#registration.batch(), target = batch.works.find(item => receipt.work_ids[item.key] === this.#workId);
+        if (!target)
+            refuse("foreign_second_repair_work");
+        if (this.#current) {
+            this.#current.assertCustody(context);
+            const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.repair_current_view' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [scope.project_id, scope.run_id, this.#workId]);
+            if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 40 * 1024 * 1024)
+                refuse("registered_second_current_view_required");
+            try {
+                if (hybridDigest(JSON.parse(rows[0].payload_json)) !== hybridDigest(this.#current.receipt()))
+                    refuse("registered_second_current_view_changed");
+            }
+            catch (error) {
+                if (error instanceof AppError)
+                    throw error;
+                refuse("registered_second_current_view_changed");
+            }
+        }
+        else if (target.depends_on.length)
+            refuse("settled_second_dependency_view_required");
+        if (context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? LIMIT 1", [this.#workId])
+            || (context.db.get("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='work_launches'")
+                && context.db.get("SELECT 1 FROM work_launches WHERE work_id=? LIMIT 1", [this.#workId])))
+            refuse("unstarted_target_required");
+        for (const item of batch.works) {
+            const id = receipt.work_ids[item.key], row = context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.project_id, scope.run_id, id]);
+            if (!row || !(this.#current ? ["created", "running", "completed"] : ["created", "running"]).includes(row.status))
+                refuse("settled_second_peer_view_required");
+            if (id === this.#workId && row.status !== "created")
+                refuse("unstarted_target_required");
+        }
+    }
+    revalidate(context) {
+        this.assertCustody(context);
+        this.#registration.revalidate(context);
+        this.#observed.revalidate();
+        const workspace = this.#bundle.execution.snapshot().scope.workspace;
+        this.#baseline.revalidate(workspace);
+        if (this.#current)
+            this.#current.revalidate(context);
+        const input = this.copyInput();
+        if (reviewSourceHash(workspace, input.explicit_inputs, input.base) !== input.source_sha256)
+            refuse("first_wave_source_changed");
+    }
+}

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

@@ -0,0 +1,115 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { PreparedRegisteredCorrectedMemoryReview } from "./memory-corrected-review-registration.js";
+import { PreparedSecondCorrectedMemoryReviewInputs } from "./memory-second-corrected-review-inputs.js";
+import { readMemoryReviewWorkSettlement } from "./memory-review-acceptance.js";
+import { validateMemoryReviewWorkResult } from "./memory-review-work-results.js";
+import { assertSelectiveMemoryReviewCoverage } from "./memory-corrected-review-acceptance.js";
+import { correctedMemoryReviewFindings } from "./memory-corrected-review-findings.js";
+import { correctedMemoryReviewUnits } from "./memory-corrected-review-projection.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+const token = Symbol("second-memory-review-acceptance");
+function refuse(reason) {
+    throw new AppError("memory_second_review_acceptance_invalid", "Final selective review lacks independent second settlements and first-review history", 2, { reason, effect: "no_effect" });
+}
+/** Independent second fan-in only. Material defects block the final review;
+ * this owner cannot allocate another correction wave or close the Stage. */
+export class PreparedSecondMemoryReviewAcceptance {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #registration in value;
+    }
+    sha256;
+    #registration;
+    #workers;
+    #results;
+    #previous;
+    #harness;
+    #observed;
+    constructor(key, registration, workers, results, previous, harness, observed) {
+        if (key !== token)
+            refuse("acceptance_token_required");
+        this.#registration = registration;
+        this.#workers = workers;
+        this.#results = structuredClone(results);
+        this.#previous = structuredClone(previous);
+        this.#harness = harness;
+        this.#observed = observed;
+        this.sha256 = hybridDigest({ registration_sha256: registration.sha256, previous, workers: workers.map(worker => ({
+                work_id: worker.workId, authority_sha256: worker.authority, result: worker.result
+            })), results });
+        Object.freeze(this);
+    }
+    static prepare(context, registration) {
+        if (!PreparedRegisteredCorrectedMemoryReview.isPrepared(registration)
+            || !PreparedSecondCorrectedMemoryReviewInputs.isPrepared(registration.inputs()))
+            refuse("prepared_second_registration_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        registration.revalidate(context);
+        const receipt = registration.receipt(), view = receipt.view, bundle = registration.inputs().bundle(), batch = registration.batch();
+        if (receipt.wave !== 2 || view.scope.bundle_sha256 !== bundle.sha256 || view.scope.execution_sha256 !== bundle.execution.sha256)
+            refuse("foreign_second_bundle");
+        const harness = runtimeHarness(bundle.execution.work("review").worker);
+        const workers = context.db.readSnapshot(() => batch.works.map(item => readMemoryReviewWorkSettlement(context, receipt, receipt.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
+        }));
+        assertSelectiveMemoryReviewCoverage(view.affected_unit_ids, results);
+        const previous = registration.inputs().completedWave().registration().firstEffectiveReviewProof(context);
+        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_result_changed");
+        const prepared = new PreparedSecondMemoryReviewAcceptance(token, registration, workers, results, previous, harness, observed);
+        prepared.resultProjection();
+        prepared.revalidate(context);
+        return prepared;
+    }
+    registration() { return this.#registration; }
+    results() { return structuredClone(this.#results); }
+    references() {
+        return this.#workers.map((worker, index) => ({ reviewer_work_id: worker.workId,
+            input_sha256: this.#registration.receipt().input_sha256, result: { ...worker.result }, unit_ids: [this.#results[index].unit_id] }));
+    }
+    resultProjection() {
+        const wave = this.#registration.inputs().completedWave(), registration = wave.registration(), receipt = registration.receipt(), batch = registration.batch();
+        const view = this.#registration.receipt().view, references = this.references();
+        const coverage = correctedMemoryReviewUnits({ view, original: this.#previous.results, current: this.results(),
+            originalReferences: this.#previous.references, currentReferences: references, repairWorkIds: wave.repairResults().map(repair => repair.work_id) });
+        const findings = correctedMemoryReviewFindings({ original: this.#previous.results, current: this.results(), affected: view.affected_unit_ids,
+            originalReferences: this.#previous.references, currentReferences: references, findingHistory: this.#previous.projection.findings,
+            repairs: wave.repairResults().map(repair => ({ ...repair, unit_ids: batch.works.find(item => receipt.work_ids[item.key] === repair.work_id).payload.memory_repair.unit_ids })) });
+        return { ...coverage, ...findings, outcome: findings.outcome === "accepted" ? "accepted" : "blocked" };
+    }
+    assertResult(result) {
+        if (!(result instanceof PreparedMemoryStageResult))
+            refuse("prepared_result_required");
+        const value = result.value(), receipt = this.#registration.receipt();
+        if (value.run_id !== receipt.run_id || value.stage !== "review" || value.input_sha256 !== receipt.scope.input_sha256
+            || hybridDigest({ units: value.units, findings: value.findings, outcome: value.outcome, details: value.details }) !== hybridDigest(this.resultProjection()))
+            refuse("review_claim_differs_from_settled_second_wave");
+    }
+    settlementProof(context) {
+        this.assertCustody(context);
+        const receipt = this.#registration.receipt();
+        return { registration_scope: structuredClone(receipt.scope), registration_sha256: this.#registration.sha256, wave: 2,
+            check_receipt_sha256: receipt.check_receipt_sha256, first_review_proof_sha256: hybridDigest(this.#previous),
+            workers: this.#workers.map(worker => ({ work_id: worker.workId, authority_sha256: worker.authority, result: { ...worker.result } })) };
+    }
+    assertCustody(context) {
+        this.#registration.assertCustody(context);
+        if (hybridDigest(this.#registration.inputs().completedWave().registration().firstEffectiveReviewProof(context)) !== hybridDigest(this.#previous))
+            refuse("first_review_history_changed");
+        const receipt = this.#registration.receipt();
+        for (const worker of this.#workers)
+            if (readMemoryReviewWorkSettlement(context, receipt, worker.workId, this.#harness).authority !== worker.authority)
+                refuse("second_settlement_changed");
+    }
+    revalidate(context) { this.#registration.revalidate(context); this.#observed.revalidate(); this.assertCustody(context); }
+}

package/dist/services/memory-source-observations.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+function refuse(reason) {
+    throw new AppError("memory_source_observation_failed", "Selected Memory Bank evidence cannot be observed", 2, { reason, phase: "prepare", effect: "no_effect" });
+}
+function contained(logical) {
+    if (!logical || path.posix.isAbsolute(logical) || path.win32.isAbsolute(logical) || logical.includes("\\") || logical.includes("\0")
+        || logical.split("/").some(segment => !segment || segment === "." || segment === ".."))
+        refuse("unsafe_source_path");
+    if (logical.split("/").some(segment => !localEnvironmentAllowed(segment)))
+        refuse("private_source_path");
+}
+function directory(file) { if (!fs.lstatSync(file).isDirectory())
+    refuse("linked_or_non_directory_source"); }
+function read(file, remaining) {
+    const selected = fs.lstatSync(file);
+    if (!selected.isFile())
+        refuse("linked_or_non_regular_source");
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = fs.fstatSync(fd);
+        if (before.dev !== selected.dev || before.ino !== selected.ino)
+            refuse("source_changed_during_observation");
+        if (!before.isFile() || before.size > 16 * 1024 * 1024 || before.size > remaining)
+            refuse("source_size_exceeds_bound");
+        const content = Buffer.alloc(before.size + 1);
+        let length = 0;
+        while (length < content.length) {
+            const count = fs.readSync(fd, content, length, content.length - length, length);
+            if (!count)
+                break;
+            length += count;
+        }
+        const after = fs.fstatSync(fd);
+        const retained = fs.lstatSync(file);
+        if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs
+            || after.ctimeMs !== before.ctimeMs || !retained.isFile() || retained.dev !== before.dev
+            || retained.ino !== before.ino)
+            refuse("source_changed_during_observation");
+        return content.subarray(0, length);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Byte observations for a CLI-selected inventory, not arbitrary paths proposed by an agent.
+ * No directory scan, Git mutation, implicit root fallback or symlink following occurs.
+ * Receipt bytes do not establish authorship, settled Work or semantic/check success.
+ */
+export class ObservedMemorySources {
+    sha256;
+    #roots;
+    #locations;
+    #bytes;
+    #hashes;
+    constructor(roots, locations, content) {
+        this.#roots = structuredClone(roots);
+        this.#locations = structuredClone(locations);
+        this.#bytes = content;
+        this.#hashes = new Map([...content].map(([key, bytes]) => [key, createHash("sha256").update(bytes).digest("hex")]));
+        this.sha256 = hybridDigest({ roots, sources: [...this.#hashes] });
+        Object.freeze(this);
+    }
+    static capture(roots, selected) {
+        try {
+            if (!Array.isArray(selected) || selected.length > 20_000 || !roots || Object.keys(roots).some(key => !["project", "workspace", "canon", "run"].includes(key)))
+                refuse("invalid_inventory");
+            const locations = structuredClone([...selected]).sort((a, b) => memorySourceKey(a.root, a.path).localeCompare(memorySourceKey(b.root, b.path), "en"));
+            const content = new Map();
+            let total = 0;
+            for (const location of locations) {
+                if (!location || Object.keys(location).some(key => !["root", "path"].includes(key)))
+                    refuse("invalid_source_location");
+                contained(location.path);
+                if (!Object.hasOwn(roots, location.root))
+                    refuse("missing_or_noncanonical_root");
+                const root = roots[location.root];
+                if (typeof root !== "string" || !path.isAbsolute(root) || fs.realpathSync(root) !== path.resolve(root))
+                    refuse("missing_or_noncanonical_root");
+                directory(root);
+                const key = memorySourceKey(location.root, location.path);
+                if (content.has(key))
+                    refuse("duplicate_source_location");
+                let parent = root;
+                for (const segment of location.path.split("/").slice(0, -1)) {
+                    parent = path.join(parent, segment);
+                    directory(parent);
+                }
+                const bytes = read(path.join(root, location.path), 64 * 1024 * 1024 - total);
+                total += bytes.length;
+                content.set(key, Buffer.from(bytes));
+            }
+            return new ObservedMemorySources(roots, locations, content);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_source_observation_failed")
+                throw error;
+            return refuse("source_unavailable");
+        }
+    }
+    hashes() { return new Map(this.#hashes); }
+    bytes(location) {
+        const content = this.#bytes.get(memorySourceKey(location.root, location.path));
+        if (!content)
+            refuse("unselected_source_location");
+        return Buffer.from(content);
+    }
+    revalidate() {
+        if (ObservedMemorySources.capture(this.#roots, this.#locations).sha256 !== this.sha256)
+            refuse("source_changed_after_observation");
+    }
+}

package/dist/services/memory-stage-dispatch.js

@@ -0,0 +1,65 @@
+import { AppError } from "../shared/errors.js";
+import { startMemoryPreflight, finishMemoryPreflight } from "./memory-preflight-handler.js";
+import { startMemoryDiscovery, finishMemoryDiscovery } from "./memory-discover-handler.js";
+import { startMemoryComposition, finishMemoryComposition } from "./memory-compose-handler.js";
+import { startMemoryVerification, finishMemoryVerification } from "./memory-verify-handler.js";
+import { startMemoryReview, finishMemoryReview } from "./memory-review-handler.js";
+import { startMemoryFinish, finishMemoryFinish } from "./memory-finish-handler.js";
+import { memoryInitHandlerIdentities as ids } from "../domain/stage-handler-identities.js";
+import { memoryUpgradeHandlerIdentities as upgradeIds } from "../domain/stage-handler-identities.js";
+import { startMemoryUpgradeAnalysis, finishMemoryUpgradeAnalysis } from "./memory-upgrade-analysis-handler.js";
+import { parseMemoryWorkResultProposal } from "./memory-work-result-json.js";
+// Engine-owned functions only; this is dispatch, not descriptor admission.
+export const memoryInitStageHandlers = Object.freeze({
+    preflight: Object.freeze({ ...ids.preflight, entry: startMemoryPreflight, finish: finishMemoryPreflight }),
+    discover: Object.freeze({ ...ids.discover, entry: startMemoryDiscovery, finish: finishMemoryDiscovery }),
+    compose: Object.freeze({ ...ids.compose, entry: startMemoryComposition, finish: finishMemoryComposition }),
+    verify: Object.freeze({ ...ids.verify, entry: startMemoryVerification, finish: finishMemoryVerification }),
+    review: Object.freeze({ ...ids.review, entry: startMemoryReview, finish: finishMemoryReview }),
+    finish: Object.freeze({ ...ids.finish, entry: startMemoryFinish, finish: finishMemoryFinish })
+});
+export const memoryUpgradeStageHandlers = Object.freeze({
+    preflight: Object.freeze({ ...upgradeIds.preflight,
+        entry: (context, input) => startMemoryUpgradeAnalysis(context, { ...input, stage: "preflight" }),
+        finish: (context, input) => finishMemoryUpgradeAnalysis(context, { ...input, stage: "preflight" }) }),
+    "diff-analysis": Object.freeze({ ...upgradeIds["diff-analysis"],
+        entry: (context, input) => startMemoryUpgradeAnalysis(context, { ...input, stage: "diff-analysis" }),
+        finish: (context, input) => finishMemoryUpgradeAnalysis(context, { ...input, stage: "diff-analysis" }) }),
+    upgrade: Object.freeze({ ...upgradeIds.upgrade, entry: startMemoryComposition, finish: finishMemoryComposition }),
+    verify: Object.freeze({ ...upgradeIds.verify, entry: startMemoryVerification, finish: finishMemoryVerification }),
+    review: Object.freeze({ ...upgradeIds.review, entry: startMemoryReview, finish: finishMemoryReview }),
+    finish: Object.freeze({ ...upgradeIds.finish, entry: startMemoryFinish, finish: finishMemoryFinish })
+});
+function stage(input) {
+    if (!Object.hasOwn(memoryInitStageHandlers, input.stage) || !(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        throw new AppError("memory_stage_dispatch_invalid", "Memory stage dispatch requires a bounded declared stage input", 2, { effect: "no_effect", phase: "prepare" });
+    return input.stage;
+}
+export function startMemoryStage(context, input) {
+    return memoryInitStageHandlers[stage(input)].entry(context, input);
+}
+export function finishMemoryStage(context, input) {
+    const selected = stage(input);
+    validateFinishProposal(input.bytes);
+    return memoryInitStageHandlers[selected].finish(context, input);
+}
+// Syntax belongs to the submitted proposal, not retained composition/receipt
+// custody. Validate it before any stage-specific projection parses the bytes.
+function validateFinishProposal(bytes) {
+    if (!bytes.length)
+        throw new AppError("memory_stage_dispatch_invalid", "Memory finish requires a nonempty result proposal", 2, { effect: "no_effect", phase: "prepare" });
+    parseMemoryWorkResultProposal(bytes, "memory_stage_result_invalid");
+}
+function upgradeStage(input) {
+    if (!Object.hasOwn(memoryUpgradeStageHandlers, input.stage) || !(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        throw new AppError("memory_stage_dispatch_invalid", "Memory stage dispatch requires a bounded declared stage input", 2, { effect: "no_effect", phase: "prepare" });
+    return input.stage;
+}
+export function startMemoryUpgradeStage(context, input) {
+    return memoryUpgradeStageHandlers[upgradeStage(input)].entry(context, input);
+}
+export function finishMemoryUpgradeStage(context, input) {
+    const selected = upgradeStage(input);
+    validateFinishProposal(input.bytes);
+    return memoryUpgradeStageHandlers[selected].finish(context, input);
+}