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

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

@@ -0,0 +1,400 @@
+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";
+import { captureMemoryUpgradeSources } from "./memory-upgrade-analysis-handler.js";
+import { PreparedMemoryUpgradeBootstrapReadiness, readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { PreparedMemoryUpgradePublication } from "./memory-upgrade-publication.js";
+import { PreparedMemoryLayer } from "./memory-layer.js";
+import { appendAudit } from "./audit.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+import { readMemoryUpgradePublication, upgradePublicationKey, upgradePublicationReceipt, upgradePublicationIntentEvent, upgradePublicationCompleteEvent } from "./memory-upgrade-publication-custody.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 || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const stage = bundle.descriptor.descriptor.id === "mb-init" ? "compose" : "upgrade";
+    if (bundle.descriptor.successor(stage === "compose" ? "discover" : "diff-analysis", "accepted") !== stage
+        || bundle.descriptor.successor(stage, "accepted") !== "verify")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    return { bundle, scope, run, accepted: index.stage_runs.find((item) => item.stage === stage)?.status === "done" };
+}
+function compositionBaseline(context, bundle) {
+    if (bundle.descriptor.descriptor.id === "mb-init")
+        return PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const selected = bundle.execution.snapshot().scope;
+    const scope = { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, scope);
+    if (!ready?.hasPreservationBaseline || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const authority = hybridDigest(ready.authority);
+    return {
+        assertCustody(writer) { const current = readMemoryUpgradeBootstrapReadiness(writer, scope); if (!current || hybridDigest(current.authority) !== authority)
+            refuse("upgrade_bootstrap_changed"); },
+        revalidate(reader) { PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(reader, bundle); this.assertCustody(reader); }
+    };
+}
+/** 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: scope.stage });
+    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: scope.stage === "compose" ? captureMemoryPreflightSources(context, bundle, input.bytes) : captureMemoryUpgradeSources(context, bundle, scope.stage, 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 (scope.stage === "compose" && 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 = compositionBaseline(context, bundle), discoveryStage = scope.stage === "compose" ? "discover" : "diff-analysis";
+    const inherited = context.db.readSnapshot(() => ({ discovery: readAcceptedStageData(context, { ...scope, stage: discoveryStage }), 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 !== (scope.stage === "compose" ? "dd-flow/mb-init-preflight-result@1" : "dd-flow/mb-upgrade-stage-result@1") || preflight.run_id !== input.runId || preflight.outcome !== "accepted"
+        || discovery.schema_id !== (scope.stage === "compose" ? "dd-flow/mb-init-discover-result@1" : "dd-flow/mb-upgrade-stage-result@1")
+        || preflight.stage !== "preflight" || discovery.stage !== discoveryStage
+        || 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: discoveryStage }).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: scope.stage });
+    preservation.revalidate(context);
+    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: scope.stage });
+    preservation.revalidate(context);
+    return { ...stage, ...coordinator.apply(context, fence) };
+}
+/** Mechanical upgrade continuation, not final Stage acceptance. Reuses the
+ * registered blueprint and settled Work; the plan is retained in SQL before
+ * the first filesystem effect. No provider or second controller is launched.
+ * Kept outside the registry until the complete upgrade lifecycle is admitted.
+ */
+export function publishMemoryUpgradeFromStage(context, input) {
+    const { bundle, scope, accepted } = selected(context, { ...input, bytes: Buffer.alloc(0) });
+    if (scope.stage !== "upgrade" || accepted)
+        refuse("active_upgrade_publication_required");
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "upgrade" });
+    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 registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, "upgrade"), stage: "upgrade", parent_work_id: allocated.workId });
+    const binding = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, registrationScope: registration.scope });
+    const outputs = PreparedMemoryCompositionAcceptance.prepareForUpgradePublication(context, { scope: registration.scope, flow: bundle.descriptor, engine: bundle.engine(), binding: binding.binding() });
+    const frozen = bundle.execution.snapshot().scope, bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope), storage = readUpgradeStorageReadiness(context, bootstrapScope);
+    if (!ready || !storage?.selection || ready.authority.binding.storage_sha256 !== storage.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const identity = { scope: registration.scope, selection_sha256: storage.selection.sha256, execution_sha256: bundle.execution.sha256,
+        registration_sha256: hybridDigest(registration), bootstrap_sha256: hybridDigest(ready.authority),
+        work_custody_sha256: outputs.custodySha256() };
+    const fence = (writer) => {
+        assertPreparedRunBundleSqlAuthority(writer, scope, bundle);
+        coordinator.assertAllocatedCustody(writer);
+        binding.assertCustody(writer);
+        outputs.assertCustody(writer);
+        if (readDescriptorRootWork(writer, scope, bundle).workId !== allocated.workId
+            || coordinatorSession(writer, scope, bundle, allocated.workId) !== allocated.physical)
+            refuse("upgrade_publication_coordinator_changed");
+        const current = readMemoryUpgradeBootstrapReadiness(writer, bootstrapScope), retained = readUpgradeStorageReadiness(writer, bootstrapScope);
+        if (!current || hybridDigest(current.authority) !== identity.bootstrap_sha256 || retained?.selection?.sha256 !== identity.selection_sha256)
+            refuse("upgrade_publication_dependencies_changed");
+    };
+    const read = (reader) => readMemoryUpgradePublication(reader, identity);
+    let plan = read(context)?.plan;
+    if (!plan) {
+        binding.revalidate(context);
+        outputs.revalidate(context);
+        const selected = storage.selection.payload, layer = selected.layer;
+        if (!selected.current.old_tree || !selected.current.version_source)
+            refuse("upgrade_publication_baseline_required");
+        const target = PreparedMemoryLayer.restoreRetained(new Map(layer.files.map(file => [file.path, Buffer.from(file.base64, "base64")])), layer.sha256, layer.installation_sha256);
+        const diff = readAcceptedStageData(context, { ...scope, stage: "diff-analysis" }), details = JSON.parse(diff.bytes.toString("utf8")).details;
+        plan = PreparedMemoryUpgradePublication.prepare({ selectionSha256: storage.selection.sha256, inventory: selected.current.inventory,
+            oldTree: selected.current.old_tree, layer: target, changes: details.path_map, versionSource: selected.current.version_source });
+        const before = new Map(plan.beforeFiles().map(file => [file.path, file]));
+        const settled = new Map(outputs.settledArtifacts().filter(item => item.artifact.root === "workspace").map(item => [item.artifact.path, item.artifact.sha256]));
+        for (const entry of selected.current.inventory.inventory.entries)
+            if (entry.current && !before.has(entry.path))
+                refuse("unsettled_semantic_removal");
+        for (const [name, file] of before) {
+            const original = selected.current.inventory.inventory.entries.find(entry => entry.path === name)?.current;
+            if (original && file.kind === original.kind && file.mode === original.mode && file.sha256 === original.sha256)
+                continue;
+            if (file.kind !== "file" || original && file.mode !== original.mode || settled.get(`.memory-bank/${name}`) !== file.sha256)
+                refuse("unsettled_semantic_change");
+        }
+        const prepared = plan;
+        plan = context.db.writeTransaction(() => {
+            fence(context);
+            const prior = read(context)?.plan;
+            if (prior) {
+                if (prior.sha256 !== prepared.sha256)
+                    refuse("upgrade_publication_plan_changed");
+                return prior;
+            }
+            const now = context.now();
+            context.db.run("INSERT INTO runtime_config (key,value_json,created_at,updated_at) VALUES (?,?,?,?)", [upgradePublicationKey(identity), JSON.stringify({ binding: identity, plan_json: prepared.bytes().toString("utf8"), plan_sha256: prepared.sha256 }), now, now]);
+            appendAudit(context, { projectId: scope.projectId, eventType: upgradePublicationIntentEvent, payload: upgradePublicationReceipt(identity, prepared) });
+            const retained = read(context);
+            if (!retained)
+                refuse("upgrade_publication_intent_readback_failed");
+            return retained.plan;
+        });
+    }
+    const publication = plan;
+    try {
+        while (true) {
+            assertImportAdmission(context.ddFlowHome);
+            context.db.readSnapshot(() => { fence(context); if (read(context)?.plan.sha256 !== publication.sha256)
+                refuse("upgrade_publication_intent_changed"); });
+            if (publication.applyNextAction().status === "applied")
+                break;
+        }
+        context.db.writeTransaction(() => {
+            fence(context);
+            if (read(context)?.plan.sha256 !== publication.sha256)
+                refuse("upgrade_publication_intent_changed");
+            if (!read(context)?.completed)
+                appendAudit(context, { projectId: scope.projectId, eventType: upgradePublicationCompleteEvent, payload: upgradePublicationReceipt(identity, publication, true) });
+            if (!read(context)?.completed)
+                refuse("upgrade_publication_completion_readback_failed");
+        });
+        const state = publication.classify();
+        if (state.completed !== state.total)
+            refuse("upgrade_publication_not_complete");
+        const record = publication.outputs().find(output => output.path === `archive/mb-upgrade/${identity.selection_sha256}/migration.json`);
+        if (!record)
+            refuse("upgrade_migration_record_missing");
+        return { status: "applied", publication_sha256: publication.sha256, migration_record: { path: `.memory-bank/${record.path}`, sha256: record.sha256 },
+            artifacts: publication.outputs().map(output => ({ root: "workspace", path: `.memory-bank/${output.path}`, sha256: output.sha256 })) };
+    }
+    catch (error) {
+        throw new AppError("memory_upgrade_publication_pending", "Preserve the accepted SQL plan and reconcile this upgrade continuation", 1, { effect: "publication_pending", publication_sha256: publication.sha256, cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+/** 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 = bundle.descriptor.descriptor.id === "mb-upgrade"
+        ? captureMemoryUpgradeSources(context, bundle, value.stage, Buffer.from(JSON.stringify(value)))
+        : captureMemoryPreflightSources(context, bundle, Buffer.from(JSON.stringify(value)));
+    const 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);
+    const 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: scope.stage, 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 bytes = outputs.projectResult(input.bytes);
+    const sources = captureMemoryCompositionSources(context, bundle, run.run_root ?? run.run_dir, 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(bytes))
+        refuse("accepted_result_changed");
+    const result = PreparedMemoryStageResult.prepare(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: scope.stage, 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); });
+}