@deksden-com/dd-flow-cli 0.9.0-beta.137 → 0.9.0-beta.138

package/dist/services/memory-completed-correction-wave.js

@@ -0,0 +1,320 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedRegisteredMemoryCorrections } from "./memory-repair-registration.js";
+import { PreparedRetainedSecondMemoryRepairs } from "./memory-retained-second-repairs.js";
+import { PreparedSettledMemoryRepair } from "./memory-repair-history.js";
+import { PreparedMemoryRepairWorkspace } from "./memory-repair-workspace.js";
+import { reviewSourcePaths } from "./review-copy.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+const token = Symbol("completed-memory-correction-wave");
+const historicalToken = Symbol("historical-second-memory-correction-wave");
+function refuse(reason) {
+    throw new AppError("memory_correction_wave_invalid", "Re-review lacks a completely settled correction graph and current document custody", 2, { reason, effect: "no_effect" });
+}
+/** Pure selection only. A repair claim does not establish current bytes or
+ * resolve a finding. Registered wave custody must validate these claims first.
+ * Assigned units always need independent re-review; previously accepted units
+ * only need it when their own evidence/artifacts intersect an actual delta. */
+export function memoryCorrectionCurrentUnits(units, assignments) {
+    if (!Array.isArray(units) || !units.length || units.length > 256 || !Array.isArray(assignments) || assignments.length > 256
+        || units.some(unit => !unit || typeof unit.id !== "string" || !unit.id)
+        || new Set(units.map(unit => unit.id)).size !== units.length
+        || assignments.some(item => !item?.unit || !units.some(unit => unit.id === item.unit.id && unit.aspect === item.unit.aspect
+            && unit.applicability === item.unit.applicability))
+        || new Set(assignments.map(item => item.unit.id)).size !== assignments.length)
+        refuse("invalid_current_unit_inventory");
+    const current = new Map(assignments.map(item => [item.unit.id, item.unit]));
+    return units.map(unit => structuredClone(current.get(unit.id) ?? unit));
+}
+export function memoryCorrectionAffectedUnits(units, repairs, composition = []) {
+    if (!Array.isArray(units) || !units.length || units.length > 256 || !Array.isArray(repairs) || !repairs.length || repairs.length > 256
+        || units.some(unit => !unit || typeof unit.id !== "string" || !unit.id || !["applicable", "not-applicable"].includes(unit.applicability)
+            || !Array.isArray(unit.evidence) || !Array.isArray(unit.artifacts)
+            || [...unit.evidence, ...unit.artifacts].some(ref => !ref || typeof ref.root !== "string"
+                || !["project", "workspace", "canon", "run"].includes(ref.root) || typeof ref.path !== "string" || !ref.path
+                || ref.path.startsWith("/") || /^[A-Za-z]:/.test(ref.path) || ref.path.includes("\\") || ref.path.includes("\0")
+                || ref.path.split("/").some((part) => !part || part === "." || part === "..")
+                || typeof ref.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(ref.sha256)))
+        || new Set(units.map(unit => unit.id)).size !== units.length)
+        refuse("invalid_unit_inventory");
+    const applicable = new Set(units.filter(unit => unit.applicability === "applicable").map(unit => unit.id));
+    const affected = new Set(), changed = new Set();
+    for (const repair of repairs) {
+        if (!repair || !Array.isArray(repair.unit_ids) || !repair.unit_ids.length || new Set(repair.unit_ids).size !== repair.unit_ids.length
+            || repair.unit_ids.some((id) => !applicable.has(id)) || repair.result?.outcome !== "accepted"
+            || !Array.isArray(repair.result.changes) || !repair.result.changes.length)
+            refuse("invalid_settled_repair_projection");
+        for (const id of repair.unit_ids)
+            affected.add(id);
+        for (const delta of repair.result.changes) {
+            if (!delta || typeof delta.path !== "string" || !delta.path.startsWith(".memory-bank/") || delta.path.includes("\\")
+                || delta.path.includes("\0") || delta.path.split("/").some((part) => !part || part === "." || part === "..")
+                || [delta.before_sha256, delta.after_sha256].some(hash => hash !== null && (typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash)))
+                || delta.before_sha256 === delta.after_sha256)
+                refuse("invalid_settled_delta_projection");
+            changed.add(delta.path);
+        }
+    }
+    for (const unit of units)
+        if (unit.applicability === "applicable" && [...unit.evidence, ...unit.artifacts].some(ref => ["project", "workspace"].includes(ref.root) && changed.has(ref.path)))
+            affected.add(unit.id);
+    if (!Array.isArray(composition) || composition.length > 256 || composition.some(work => !work || typeof work.key !== "string" || !work.key
+        || !Array.isArray(work.unit_ids) || !work.unit_ids.length || work.unit_ids.some((id) => !applicable.has(id))
+        || !Array.isArray(work.depends_on) || new Set(work.depends_on).size !== work.depends_on.length)
+        || new Set(composition.map(work => work.key)).size !== composition.length)
+        refuse("invalid_composition_dependencies");
+    const remaining = new Map(composition.map(work => [work.key, work])), done = new Set(), impacted = new Set();
+    if (composition.some(work => work.depends_on.some((key) => !remaining.has(key) || key === work.key)))
+        refuse("invalid_composition_dependencies");
+    while (remaining.size) {
+        const ready = [...remaining.values()].filter(work => work.depends_on.every((key) => done.has(key)));
+        if (!ready.length)
+            refuse("invalid_composition_dependencies");
+        for (const work of ready) {
+            remaining.delete(work.key);
+            done.add(work.key);
+        }
+    }
+    // Units may span several composition Works. Reach a fixed point rather
+    // than making coverage depend on which independent branch sorted first.
+    let expanded;
+    do {
+        expanded = false;
+        for (const work of composition) {
+            const dependent = work.depends_on.some((key) => impacted.has(key));
+            if (!impacted.has(work.key) && (dependent || work.unit_ids.some((id) => affected.has(id)))) {
+                impacted.add(work.key);
+                expanded = true;
+            }
+            // Co-packing independent units into one Work is not a dependency.
+            // Only a declared changed predecessor expands its consumer units.
+            if (dependent)
+                for (const id of work.unit_ids)
+                    if (!affected.has(id)) {
+                        affected.add(id);
+                        expanded = true;
+                    }
+        }
+    } while (expanded);
+    return units.filter(unit => affected.has(unit.id)).map(unit => unit.id);
+}
+function assertNoActiveChildren(context, registration) {
+    const scope = registration.receipt().scope;
+    if (context.db.get("SELECT 1 FROM works w JOIN stage_work_memberships m ON m.work_id=w.work_id AND m.project_id=w.project_id AND m.run_id=w.run_id WHERE w.project_id=? AND w.run_id=? AND w.parent_work_id=? AND m.stage='review' AND m.attempt=? AND w.status IN ('created','running','paused') LIMIT 1", [scope.project_id, scope.run_id, scope.parent_work_id, scope.attempt]))
+        refuse("review_children_active");
+}
+function selection(context, registration) {
+    registration.assertCustody(context);
+    const receipt = registration.receipt(), batch = registration.batch(), scope = receipt.scope;
+    if (receipt.wave !== (PreparedRetainedSecondMemoryRepairs.isPrepared(registration) ? 2 : 1))
+        refuse("unsupported_correction_wave");
+    const states = batch.works.map(item => {
+        const workId = receipt.work_ids[item.key];
+        const row = context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=? AND parent_work_id=?", [scope.project_id, scope.run_id, workId, scope.parent_work_id]);
+        if (row?.status !== "completed")
+            refuse("correction_graph_not_completed");
+        return { key: item.key, work_id: workId };
+    });
+    const ids = new Set(states.map(item => item.work_id));
+    if (!ids.size)
+        refuse("settlement_history_missing_or_ambiguous");
+    const all = context.db.all(`SELECT id,json_extract(payload_json,'$.work_id') AS work_id FROM audit_events WHERE project_id=? AND event_type='memory.repair_work_settlement' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id') IN (${[...ids].map(() => "?").join(",")}) ORDER BY id LIMIT 257`, [scope.project_id, scope.run_id, ...ids]);
+    if (all.length > 256)
+        refuse("unbounded_settlement_history");
+    const settlements = all.filter(row => ids.has(row.work_id));
+    if (!states.length || settlements.length !== states.length || new Set(settlements.map(row => row.work_id)).size !== states.length)
+        refuse("settlement_history_missing_or_ambiguous");
+    const order = new Map(settlements.map((row, index) => [row.work_id, index]));
+    for (const item of batch.works)
+        for (const dependency of item.depends_on) {
+            const predecessor = receipt.work_ids[dependency], workId = receipt.work_ids[item.key];
+            if (!predecessor || order.get(predecessor) >= order.get(workId))
+                refuse("dependency_settlement_order_changed");
+        }
+    return { registration_sha256: registration.sha256, states, settlements };
+}
+const nonMemory = (entry) => entry.path !== ".memory-bank" && !entry.path.startsWith(".memory-bank/");
+/** Closed second graph custody, not current workspace admission or accepted
+ * review. Reconstruction starts at independently retained first-wave state;
+ * neither current files nor a second writer's claimed before-view are anchors. */
+export class PreparedHistoricalSecondMemoryCorrectionWave {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #registration in value;
+    }
+    #registration;
+    #selected;
+    #histories;
+    #baseline;
+    #affected;
+    constructor(key, registration, selected, histories, baseline, affected) {
+        if (key !== historicalToken)
+            refuse("historical_second_wave_token_required");
+        this.#registration = registration;
+        this.#selected = structuredClone(selected);
+        this.#histories = histories;
+        this.#baseline = baseline;
+        this.#affected = [...affected];
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const registration = PreparedRetainedSecondMemoryRepairs.prepareAfterReview(context, input);
+        const selected = context.db.readSnapshot(() => selection(context, registration));
+        const histories = selected.settlements.map(row => PreparedSettledMemoryRepair.prepare(context, registration, row.work_id));
+        let baseline = registration.initialDocumentBaseline();
+        const prefixes = new Set([hybridDigest(baseline.entries())]);
+        for (const history of histories) {
+            if (!prefixes.has(hybridDigest(history.before().entries())))
+                refuse("unexplained_historical_input_view");
+            baseline = baseline.composeSettledDelta(history.before(), history.after());
+            prefixes.add(hybridDigest(baseline.entries()));
+        }
+        const batch = registration.batch(), receipt = registration.receipt(), first = registration.initialInputView();
+        const compose = readAcceptedStageData(context, { ...input.scope, stage: "compose" });
+        const affected = memoryCorrectionAffectedUnits(memoryCorrectionCurrentUnits(first.unit_inventory, first.assignments), histories.map(history => ({ result: history.result(),
+            unit_ids: batch.works.find(item => receipt.work_ids[item.key] === history.workId).payload.memory_repair.unit_ids })), JSON.parse(compose.bytes.toString("utf8")).details.works);
+        const prepared = new PreparedHistoricalSecondMemoryCorrectionWave(historicalToken, registration, selected, histories, baseline, affected);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    registration() { return this.#registration; }
+    baseline() { return this.#baseline; }
+    histories() { return [...this.#histories]; }
+    affectedUnitIds() { return [...this.#affected]; }
+    repairResults() {
+        const batch = this.#registration.batch(), receipt = this.#registration.receipt();
+        return this.#histories.map(history => ({ work_id: history.workId, result: history.result(), reference: history.reference(),
+            authority_sha256: history.sha256,
+            unit_ids: batch.works.find(item => receipt.work_ids[item.key] === history.workId).payload.memory_repair.unit_ids }));
+    }
+    assertCustody(context) {
+        if (hybridDigest(selection(context, this.#registration)) !== hybridDigest(this.#selected))
+            refuse("historical_second_graph_changed");
+        for (const history of this.#histories)
+            history.assertCustody(context);
+    }
+    revalidate(context) {
+        this.#registration.revalidate(context);
+        for (const history of this.#histories)
+            history.revalidate(context);
+        this.assertCustody(context);
+    }
+}
+/** Current post-correction admission, not a historical acceptance receipt.
+ * Every Work must have independently settled publication custody. Shared
+ * documents are compared with composed retained transitions, never adopted
+ * from today's filesystem. This owner neither allocates reviewers nor marks
+ * repair findings resolved; independent re-review must consume it separately. */
+export class PreparedCompletedMemoryCorrectionWave {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #selected in value;
+    }
+    sha256;
+    #registration;
+    #selected;
+    #histories;
+    #baseline;
+    #workspace;
+    #root;
+    #input;
+    #affected;
+    constructor(key, registration, selected, histories, baseline, workspace, root, input, affected) {
+        if (key !== token)
+            refuse("completed_wave_token_required");
+        this.#registration = registration;
+        this.#selected = structuredClone(selected);
+        this.#histories = histories;
+        this.#baseline = baseline;
+        this.#workspace = workspace;
+        this.#root = root;
+        this.#input = structuredClone(input);
+        this.#affected = [...affected];
+        this.sha256 = hybridDigest({ selected, histories: histories.map(history => history.sha256), baseline_sha256: baseline.sha256,
+            workspace_sha256: workspace.sha256, input, affected_unit_ids: affected });
+        Object.freeze(this);
+    }
+    static prepare(context, registration) {
+        if (!PreparedRegisteredMemoryCorrections.isPrepared(registration)
+            && !PreparedRetainedSecondMemoryRepairs.isPrepared(registration))
+            refuse("registered_corrections_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        // Preparing a read-only current view must also work after its successor
+        // reviewers have been allocated. Only fresh allocation requires no active
+        // children; that fence is consumed by its writer below.
+        const selected = context.db.readSnapshot(() => selection(context, registration));
+        const histories = selected.settlements.map(row => PreparedSettledMemoryRepair.prepare(context, registration, row.work_id));
+        const paths = [...new Set(registration.plan().works.flatMap(work => work.write_paths))].sort();
+        let baseline = (PreparedRetainedSecondMemoryRepairs.isPrepared(registration)
+            ? registration.initialDocumentBaseline() : histories[0].before()).withWritePaths(paths);
+        const known = new Set([hybridDigest(baseline.entries())]);
+        for (const history of histories) {
+            if (!known.has(hybridDigest(history.before().entries())))
+                refuse("unexplained_historical_input_view");
+            baseline = baseline.composeSettledDelta(history.before(), history.after());
+            known.add(hybridDigest(baseline.entries()));
+        }
+        const view = PreparedRetainedSecondMemoryRepairs.isPrepared(registration) ? registration.initialInputView()
+            : registration.review().original().registration().view;
+        const bundle = PreparedRetainedSecondMemoryRepairs.isPrepared(registration) ? registration.bundle()
+            : registration.review().original().bundle();
+        const root = bundle.execution.snapshot().scope.workspace;
+        baseline.revalidate(root);
+        const input = { base: view.base, explicit_inputs: view.run_inputs.filter(ref => ref.root === "workspace").map(ref => ref.path) };
+        const candidates = reviewSourcePaths(root, input.explicit_inputs, input.base);
+        if (!candidates)
+            refuse("source_inventory_unavailable");
+        const available = new Set(baseline.entries().filter(entry => entry.kind === "file").map(entry => entry.path));
+        const exported = baseline.exported(candidates.filter(logical => logical.startsWith(".memory-bank/") && available.has(logical)));
+        const workspace = PreparedMemoryRepairWorkspace.capture(root, input, exported);
+        const sourceSha256 = hybridDigest(workspace.entries().filter(nonMemory));
+        if (histories.some(history => hybridDigest(history.workspaceManifest().entries().filter(nonMemory)) !== sourceSha256))
+            refuse("non_memory_source_changed");
+        const batch = registration.batch(), receipt = registration.receipt();
+        const compose = readAcceptedStageData(context, { projectId: receipt.scope.project_id, runId: receipt.run_id, stage: "compose" });
+        const dependencies = JSON.parse(compose.bytes.toString("utf8")).details.works;
+        const currentUnits = PreparedRetainedSecondMemoryRepairs.isPrepared(registration)
+            ? memoryCorrectionCurrentUnits(registration.initialInputView().unit_inventory, registration.initialInputView().assignments)
+            : view.unit_inventory;
+        const affected = memoryCorrectionAffectedUnits(currentUnits, histories.map(history => ({
+            unit_ids: batch.works.find(item => receipt.work_ids[item.key] === history.workId).payload.memory_repair.unit_ids,
+            result: history.result()
+        })), dependencies);
+        const prepared = new PreparedCompletedMemoryCorrectionWave(token, registration, selected, histories, baseline, workspace, root, input, affected);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    registration() { return this.#registration; }
+    affectedUnitIds() { return [...this.#affected]; }
+    baseline() { return this.#baseline; }
+    workspaceManifest() { return this.#workspace; }
+    repairResults() { return this.#histories.map(history => ({ work_id: history.workId, result: history.result(), reference: history.reference(), authority_sha256: history.sha256 })); }
+    /** Only SQL custody is inspected inside the future review-allocation writer. */
+    assertCustody(context) {
+        const selected = this.#selected;
+        if (hybridDigest(selection(context, this.#registration)) !== hybridDigest(selected))
+            refuse("completed_wave_custody_changed");
+        for (const history of this.#histories)
+            history.assertCustody(context);
+    }
+    /** Fresh allocation fence, before adding successor reviewers. General
+     * custody deliberately stays valid when those admitted children exist. */
+    assertAllocationAllowed(context) {
+        this.assertCustody(context);
+        assertNoActiveChildren(context, this.#registration);
+    }
+    revalidate(context) {
+        const root = this.#root;
+        this.assertCustody(context);
+        this.#registration.revalidate(context);
+        for (const history of this.#histories)
+            history.revalidate(context);
+        this.#baseline.revalidate(root);
+        this.#workspace.revalidateSource();
+        // Re-read the selected inventory as well as observed files: a newly added
+        // non-MB source must not slip between preparation and reviewer allocation.
+        this.#workspace.verifySelectedSourceInputs(root, this.#input, this.#baseline);
+        this.assertCustody(context);
+    }
+}

package/dist/services/memory-compose-handler.js

@@ -0,0 +1,258 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertMemoryOrdinaryConfigurationCoverage, assertMemoryOrdinaryConfigurationOutputs } from "./memory-ordinary-defaults.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { PreparedMemoryStageResult, memorySourceKey } from "./memory-stage-results.js";
+import { captureMemoryPreflightSources } from "./memory-preflight-handler.js";
+import { registerMemoryComposition, selectMemoryCompositionRegistration } from "./memory-composition-registration.js";
+import { PreparedMemoryBaselinePreservation } from "./memory-baseline-preservation.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedMemoryCompositionAcceptance } from "./memory-composition-acceptance.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { PreparedCheckEvidence } from "./code-checks.js";
+function refuse(reason) {
+    throw new AppError("memory_compose_handler_invalid", "Memory composition lacks retained scope, plan or output custody", 2, { reason, effect: "no_effect" });
+}
+function selected(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("discover", "accepted") !== "compose"
+        || bundle.descriptor.successor("compose", "accepted") !== "verify")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage: "compose" };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    return { bundle, scope, run, accepted: index.stage_runs.find((stage) => stage.stage === "compose")?.status === "done" };
+}
+/** SQL-only physical binding proof; allocation/prompt custody is checked
+ * separately. No new Session, hook claim or provider invocation is created.
+ */
+function coordinatorSession(context, scope, bundle, workId) {
+    const rows = context.db.all("SELECT ws.id,ws.session_id,ws.hook_event_id,ws.prompt_path,ws.result_path,s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=? WHERE ws.work_id=? AND ws.status='running' AND s.run_id=? AND s.current_stage=? AND s.status='active' LIMIT 2", [scope.projectId, workId, scope.runId, scope.stage]);
+    if (rows.length !== 1)
+        refuse("active_coordinator_session_required");
+    const session = rows[0], route = bundle.execution.stage(scope.stage);
+    const input = readDescriptorStageInput(context, scope, bundle), directory = bundle.descriptor.stage(scope.stage).directory;
+    if (session.prompt_path !== path.join(input.runRoot, directory, "coordinator-prompt.md")
+        || session.result_path !== path.join(input.runRoot, directory, "result-input.json"))
+        refuse("coordinator_packet_link_changed");
+    if (session.harness !== runtimeHarness(route.profile)
+        || !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.projectId, session.hook_event_id, session.session_id, session.harness, session.provider_session_id]))
+        refuse("coordinator_start_custody_missing");
+    const bindings = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='stage.coordinator_binding' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')=? AND json_extract(payload_json,'$.work_session_id')=? LIMIT 33", [scope.projectId, scope.runId, scope.stage, session.id]);
+    if (!bindings.length || bindings.length > 32 || bindings.some(row => Buffer.byteLength(row.payload_json) > 32768))
+        refuse("physical_binding_missing");
+    const binding = JSON.parse(bindings[0].payload_json);
+    if (bindings.some(row => hybridDigest(JSON.parse(row.payload_json)) !== hybridDigest(binding))
+        || binding.work_id !== workId || binding.session_id !== session.session_id || binding.harness !== session.harness || binding.provider_session_id !== session.provider_session_id
+        || binding.execution_sha256 !== bundle.execution.sha256 || binding.profile_id !== route.profile.id || binding.profile_sha256 !== hybridDigest(route.profile)
+        || binding.session_mode !== route.session_mode || hybridDigest(binding.scope) !== hybridDigest({ ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: scope.stage }))
+        refuse("physical_binding_changed");
+    return hybridDigest({ session, binding });
+}
+/** Actual registration path for the composition handler, awaiting complete
+ * memory-flow admission. Registers the immutable blueprint before workers run;
+ * it is NOT final composition acceptance or proof of produced artifacts.
+ */
+export function registerMemoryCompositionFromStage(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_plan_bytes");
+    const { bundle, scope, accepted } = selected(context, input);
+    if (accepted)
+        refuse("use_accepted_finish_replay");
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "compose" });
+    const allocated = context.db.readSnapshot(() => {
+        coordinator.assertAllocatedCustody(context);
+        const root = readDescriptorRootWork(context, scope, bundle);
+        return { workId: root.workId, physical: coordinatorSession(context, scope, bundle, root.workId) };
+    });
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
+        sources: captureMemoryPreflightSources(context, bundle, input.bytes) });
+    let composition;
+    try {
+        composition = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    }
+    catch (error) {
+        // Only proposal validation is correctable here: no registration writer has
+        // run. Source/coordinator custody failures and registration conflicts remain
+        // outside this boundary and cannot authorize another authoring attempt.
+        if (error instanceof AppError && error.code === "memory_stage_result_invalid"
+            && error.details.phase === "prepare" && error.details.effect === "no_effect")
+            error.details.recoverable = true;
+        throw error;
+    }
+    const ordinaryDefaults = readDescriptorStageInput(context, scope, bundle).input.ordinary_defaults;
+    if (ordinaryDefaults) {
+        assertMemoryOrdinaryConfigurationCoverage(composition.value(), ordinaryDefaults);
+        if (ordinaryDefaults.missing.length && !context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_resumed' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='compose' LIMIT 1", [scope.projectId, scope.runId])) {
+            throw new AppError("memory_stage_result_invalid", "Resolve the missing ordinary configuration choice through the existing compose pause/answer path before registering Work", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_choice_required", missing: ordinaryDefaults.missing });
+        }
+    }
+    binding.revalidate(context);
+    return registerMemoryComposition(context, { parentWorkId: allocated.workId, requestKey: input.requestKey, composition,
+        binding: { runId: input.runId, inputSha256: binding.binding().inputSha256, executionSha256: bundle.execution.sha256 } }, writer => {
+        binding.assertCustody(writer);
+        coordinator.assertAllocatedCustody(writer);
+        if (coordinatorSession(writer, scope, bundle, allocated.workId) !== allocated.physical)
+            refuse("coordinator_changed");
+    });
+}
+/** Unregistered until all six memory handlers are complete. Entry consumes
+ * accepted discovery/preflight; it does not create a second RUN or dispatch.
+ */
+export function startMemoryComposition(context, input) {
+    const { bundle, scope, accepted } = selected(context, input);
+    if (accepted)
+        refuse("use_accepted_finish_replay");
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const inherited = context.db.readSnapshot(() => ({ discovery: readAcceptedStageData(context, { ...scope, stage: "discover" }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
+    const preflight = JSON.parse(inherited.preflight.bytes.toString("utf8")), discovery = JSON.parse(inherited.discovery.bytes.toString("utf8"));
+    if (preflight.schema_id !== "dd-flow/mb-init-preflight-result@1" || preflight.run_id !== input.runId || preflight.outcome !== "accepted"
+        || discovery.schema_id !== "dd-flow/mb-init-discover-result@1"
+        || discovery.run_id !== input.runId || discovery.outcome !== "accepted")
+        refuse("accepted_discovery_and_baseline_required");
+    const fence = (writer) => {
+        preservation.assertCustody(writer);
+        if (readAcceptedStageData(writer, { ...scope, stage: "discover" }).authority_sha256 !== inherited.discovery.authority_sha256
+            || readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== inherited.preflight.authority_sha256)
+            refuse("inherited_custody_changed");
+    };
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "compose" });
+    preservation.revalidate(context);
+    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "compose" });
+    preservation.revalidate(context);
+    return { ...stage, ...coordinator.apply(context, fence) };
+}
+/** Agent references are selectors, not permissions. Supplement independent
+ * baseline evidence only with current outputs admitted by completed Work.
+ */
+export function captureMemoryCompositionSources(context, bundle, runRoot, bytes, outputs, checks, proposalSha256) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        refuse("invalid_result_json");
+    }
+    const pending = [{ value, role: "source" }], hashes = outputs.outputHashes(), historical = outputs.historicalEvidence();
+    let count = 0;
+    const rejectSelectedReference = (reason, root, path, sha256) => {
+        if (proposalSha256 === undefined)
+            refuse(reason);
+        throw new AppError("memory_compose_handler_invalid", "Correct the proposed evidence reference to the selected bytes below, or omit the unsupported citation. Do not rerun settled checks or change the accepted output", 2, { reason, phase: "prepare", effect: "no_effect", recoverable: true, result_sha256: proposalSha256, selected_reference: { root, path, sha256 } });
+    };
+    const executionScope = bundle.execution.snapshot().scope;
+    const sharedProjectWorkspace = resolveProjectRoot(executionScope.projectRoot) === resolveProjectRoot(executionScope.workspace);
+    const workResults = new Map(outputs.resultEvidence().map(ref => [memorySourceKey(ref.root, ref.path), ref.sha256])), resultLocations = new Map();
+    if (checks !== undefined) {
+        if (!(checks instanceof PreparedCheckEvidence))
+            refuse("prepared_checks_required");
+        const scope = bundle.execution.snapshot().scope;
+        checks.assertOwner({ projectId: requireProjectByRoot(context, scope.projectRoot).id, runId: bundle.manifest.run_id });
+        checks.assertCustody(context);
+        for (const ref of checks.sourceReferences()) {
+            hashes.set(memorySourceKey(ref.root, ref.path), ref.sha256);
+            resultLocations.set(memorySourceKey(ref.root, ref.path), { root: ref.root, path: ref.path });
+        }
+    }
+    while (pending.length) {
+        if (++count > 100000)
+            refuse("result_tree_exceeds_bound");
+        const { value: node, role } = pending.pop();
+        if (Array.isArray(node)) {
+            for (const child of node)
+                pending.push({ value: child, role });
+            continue;
+        }
+        if (!node || typeof node !== "object")
+            continue;
+        const record = node;
+        if (typeof record.root === "string" && typeof record.path === "string" && typeof record.sha256 === "string") {
+            // Inherited blueprint evidence describes the prior input, not today's
+            // artifact bytes. Its prepared original owner retains source custody.
+            const inherited = role === "evidence" && historical.has(`${memorySourceKey(record.root, record.path)}\0${record.sha256}`);
+            const resultSha = role === "evidence" ? workResults.get(memorySourceKey(record.root, record.path)) : undefined;
+            if (resultSha !== undefined) {
+                if (record.sha256 !== resultSha)
+                    rejectSelectedReference("unsettled_work_result_reference", record.root, record.path, resultSha);
+                resultLocations.set(memorySourceKey(record.root, record.path), { root: record.root, path: record.path });
+            }
+            const key = memorySourceKey(record.root, record.path);
+            const expected = hashes.get(key) ?? (sharedProjectWorkspace && record.root === "project"
+                && ["evidence", "artifacts"].includes(role) ? hashes.get(memorySourceKey("workspace", record.path)) : undefined);
+            if (expected !== undefined && !inherited) {
+                if (record.sha256 !== expected)
+                    rejectSelectedReference("unsettled_output_reference", record.root, record.path, expected);
+                hashes.set(key, expected);
+                resultLocations.set(key, { root: record.root, path: record.path });
+            }
+            if (expected !== undefined || inherited || resultSha !== undefined) {
+                delete record.root;
+                delete record.path;
+                delete record.sha256;
+            }
+        }
+        for (const [key, child] of Object.entries(record))
+            pending.push({ value: child, role: key === "evidence" || key === "artifacts" ? key : role });
+    }
+    // Keep evidence/artifact roles for the shared collector; settled child output
+    // references already have their independent output owner above.
+    const observedBaseline = captureMemoryPreflightSources(context, bundle, Buffer.from(JSON.stringify(value))), locations = new Map();
+    for (const key of observedBaseline.hashes().keys()) {
+        const [root, logical] = key.split("\0");
+        locations.set(key, { root: root, path: logical });
+    }
+    for (const location of outputs.outputLocations())
+        locations.set(memorySourceKey(location.root, location.path), location);
+    for (const [key, location] of resultLocations)
+        locations.set(key, location);
+    const scope = bundle.execution.snapshot().scope, observations = ObservedMemorySources.capture({ project: scope.projectRoot, workspace: scope.workspace,
+        canon: path.join(scope.workspace, ".memory-bank"), run: runRoot }, [...locations.values()]);
+    const actual = observations.hashes();
+    for (const [key, expected] of [...observedBaseline.hashes(), ...hashes, ...[...workResults].filter(([key]) => resultLocations.has(key))])
+        if (actual.get(key) !== expected)
+            refuse("source_changed_during_final_preparation");
+    return observations;
+}
+/** Final acceptance keeps the registration blueprint immutable. Fresh/replay
+ * RUN/input/coordinator authority is selected independently; registered child
+ * outputs and their current bytes are rechecked before and within settlement.
+ * Semantic quality remains the following VERIFY and independent REVIEW gates.
+ */
+export function finishMemoryComposition(context, input) {
+    const { bundle, scope, run, accepted } = selected(context, input), root = readDescriptorRootWork(context, scope, bundle);
+    if (!input.bytes.length)
+        refuse("invalid_result_bytes");
+    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: "compose", parent_work_id: root.workId });
+    const registrationScope = registration.scope;
+    const blueprintBinding = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
+        registrationScope, acceptedReplay: accepted });
+    const outputs = PreparedMemoryCompositionAcceptance.prepare(context, { scope: registrationScope, flow: bundle.descriptor, engine: bundle.engine(), binding: blueprintBinding.binding() });
+    const sources = captureMemoryCompositionSources(context, bundle, run.run_root ?? run.run_dir, input.bytes, outputs);
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, sources, acceptedReplay: accepted, historicalEvidence: outputs.historicalEvidence() });
+    const replay = binding.acceptedBytes();
+    if (replay && !replay.equals(input.bytes))
+        refuse("accepted_result_changed");
+    const result = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    outputs.assertResult(result);
+    const ordinaryDefaults = readDescriptorStageInput(context, scope, bundle, true, accepted).input.ordinary_defaults;
+    if (ordinaryDefaults && !replay) {
+        const selected = bundle.execution.snapshot().scope;
+        assertMemoryOrdinaryConfigurationOutputs(context, selected.workspace, ordinaryDefaults, result.value().units.flatMap(unit => unit.artifacts), { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace });
+    }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "compose", bytes: result.bytes() });
+    blueprintBinding.revalidate(context);
+    binding.revalidate(context);
+    outputs.revalidate(context);
+    return settlement.apply(context, writer => { blueprintBinding.assertCustody(writer); binding.assertCustody(writer); outputs.assertCustody(writer); outputs.assertResult(result); });
+}