@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

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); });
+}

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

@@ -0,0 +1,199 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { PreparedMemoryStageResult, memorySourceKey } from "./memory-stage-results.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { readWorkBatchCustody } from "./work-registry.js";
+import { readMemoryCompositionRegistration, readRegisteredMemoryComposition } from "./memory-composition-registration.js";
+import { validateMemoryCompositionWorkResult } from "./memory-composition-work-results.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_composition_acceptance_invalid", "Composition lacks registered, settled and current output custody", 2, { reason, effect: "no_effect" });
+}
+function object(bytes, reason) {
+    try {
+        const value = JSON.parse(bytes);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            refuse(reason);
+        return value;
+    }
+    catch {
+        return refuse(reason);
+    }
+}
+function roots(context, scope) {
+    const row = context.db.get("SELECT workspace_root,run_root,run_dir FROM runs WHERE project_id=? AND id=?", [scope.project_id, scope.run_id]);
+    if (!row || !path.isAbsolute(row.workspace_root) || !path.isAbsolute(row.run_root ?? row.run_dir))
+        refuse("assigned_roots_missing");
+    return { workspace: row.workspace_root, run: row.run_root ?? row.run_dir };
+}
+/** SQL-only selection. Neither a completed status nor a mutable result file
+ * can substitute for the output-preparation receipt committed by the memory
+ * Work writer together with its result and WorkSession.
+ */
+function settled(context, scope, workId, harness, registrationSha256, assigned) {
+    const allocation = readWorkBatchCustody(context, workId);
+    if (hybridDigest(allocation.scope) !== hybridDigest(scope))
+        refuse("foreign_work_allocation");
+    const work = context.db.get("SELECT status,result,result_schema FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.project_id, scope.run_id, workId]);
+    if (!work || work.status !== "completed" || work.result_schema !== "dd-flow/memory-composition-work-result@1"
+        || typeof work.result !== "string" || !work.result.length || Buffer.byteLength(work.result) > 1024 * 1024)
+        refuse("work_not_settled");
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.composition_work_settlement' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.work_id')=? LIMIT 2", [scope.project_id, scope.run_id, workId]);
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 32768)
+        refuse("work_settlement_receipt_missing");
+    const receipt = object(rows[0].payload_json, "invalid_work_settlement_receipt");
+    const links = context.db.all("SELECT id,session_id,status,result_path,result_receipt_json FROM work_sessions WHERE work_id=? AND status='completed' LIMIT 2", [workId]);
+    if (links.length !== 1 || !links[0].result_receipt_json || Buffer.byteLength(links[0].result_receipt_json) > 32768
+        || context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? AND status='running'", [workId]))
+        refuse("completed_work_session_missing");
+    const link = links[0], publication = object(link.result_receipt_json, "invalid_work_result_receipt");
+    const session = context.db.get("SELECT provider_session_id FROM sessions WHERE project_id=? AND session_id=? AND run_id=? AND harness=?", [scope.project_id, link.session_id, scope.run_id, harness]);
+    if (!session)
+        refuse("work_session_identity_changed");
+    const bytes = Buffer.from(work.result), resultSha256 = hash(bytes);
+    if (hybridDigest(receipt) !== hybridDigest({ schema_id: "dd-flow/memory-composition-work-settlement@1", run_id: scope.run_id, work_id: workId,
+        work_session_id: link.id, session_id: link.session_id, harness, provider_session_id: session.provider_session_id,
+        scope, registration_sha256: registrationSha256, allocation_sha256: hybridDigest(allocation), roots: assigned, result_sha256: resultSha256 }))
+        refuse("work_settlement_custody_changed");
+    if (publication.work_id !== workId || publication.work_session_id !== link.id || publication.status !== "completed" || publication.result_sha256 !== resultSha256
+        || publication.previous_sha256 !== null && (typeof publication.previous_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(publication.previous_sha256)))
+        refuse("work_result_receipt_changed");
+    if (link.result_path !== path.join(assigned.run, "works", workId, "result.json"))
+        refuse("work_result_path_changed");
+    return { bytes, authority: hybridDigest({ receipt, publication }), assigned,
+        evidence: { root: "run", path: `works/${workId}/result.json`, sha256: resultSha256 } };
+}
+/** Final compose output custody, not semantic verification/review/finish.
+ * The blueprint is restored from registration; it is never rewritten using
+ * the final result. Historical worker bytes are schema-checked without
+ * asserting that a dependent assembly left their artifacts untouched.
+ */
+export class PreparedMemoryCompositionAcceptance {
+    #scope;
+    #original;
+    #registrationSha256;
+    #workers;
+    #artifacts;
+    #observed;
+    constructor(scope, original, registrationSha256, workers, artifacts, observed) {
+        this.#scope = structuredClone(scope);
+        this.#original = original;
+        this.#registrationSha256 = registrationSha256;
+        this.#workers = workers;
+        this.#artifacts = artifacts;
+        this.#observed = observed;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        const registration = readMemoryCompositionRegistration(context, input.scope);
+        const original = readRegisteredMemoryComposition(context, input), value = original.value();
+        const works = value.details.works;
+        const batch = original.compositionBatch({ runId: input.scope.run_id, inputSha256: input.binding.inputSha256, executionSha256: input.binding.executionSha256, resultSchema: "dd-flow/memory-composition-work-result@1" });
+        const routes = new Map(original.compositionRoutes().map(route => [route.key, runtimeHarness(route.execution.worker)]));
+        const registrationSha256 = hybridDigest(registration), assigned = roots(context, input.scope);
+        const selected = context.db.readSnapshot(() => works.map(work => {
+            const id = registration.work_ids[work.key], harness = routes.get(work.key);
+            return { key: work.key, id, harness, ...settled(context, input.scope, id, harness, registrationSha256, assigned) };
+        }));
+        const outputs = new Map(selected.map(item => [item.key, validateMemoryCompositionWorkResult(item.bytes, input.engine, {
+                runId: input.scope.run_id, inputSha256: input.binding.inputSha256, executionSha256: input.binding.executionSha256,
+                workId: item.id, workKey: item.key, composition: original, compositionSha256: original.sha256
+            })]));
+        // The admitted graph has ordered all overlapping writers. Use its real
+        // dependencies, not array order, wall-clock timestamps or agent claims.
+        const remaining = new Map(works.map(work => [work.key, work.depends_on.length])), children = new Map();
+        for (const work of works)
+            for (const dependency of work.depends_on)
+                children.set(dependency, [...(children.get(dependency) ?? []), work.key]);
+        const ready = works.filter(work => !work.depends_on.length).map(work => work.key);
+        const current = new Map(), aliases = new Map();
+        for (let index = 0; index < ready.length; index++) {
+            const key = ready[index], output = outputs.get(key), emitted = new Map();
+            for (const unit of output.units)
+                for (const artifact of unit.artifacts) {
+                    const identity = memorySourceKey(artifact.root, artifact.path), alias = memorySourceKey(artifact.root, artifact.path.normalize("NFC").toLowerCase());
+                    if (aliases.has(alias) && aliases.get(alias) !== identity)
+                        refuse("aliased_output_paths");
+                    aliases.set(alias, identity);
+                    const record = emitted.get(identity) ?? { artifact, units: new Set() };
+                    record.units.add(unit.id);
+                    emitted.set(identity, record);
+                }
+            for (const [identity, record] of emitted)
+                current.set(identity, record);
+            for (const child of children.get(key) ?? []) {
+                const count = remaining.get(child) - 1;
+                remaining.set(child, count);
+                if (!count)
+                    ready.push(child);
+            }
+        }
+        if (ready.length !== batch.works.length)
+            refuse("registered_graph_changed");
+        const artifacts = new Map();
+        for (const record of current.values())
+            for (const id of record.units)
+                artifacts.set(id, [...(artifacts.get(id) ?? []), record.artifact]);
+        const observed = ObservedMemorySources.capture(assigned, [...current.values()].map(record => ({ root: record.artifact.root, path: record.artifact.path })));
+        const hashes = observed.hashes();
+        if ([...current.values()].some(record => hashes.get(memorySourceKey(record.artifact.root, record.artifact.path)) !== record.artifact.sha256))
+            refuse("current_output_bytes_changed");
+        const prepared = new PreparedMemoryCompositionAcceptance(input.scope, original, registrationSha256, selected.map(item => ({ id: item.id, harness: item.harness, authority: item.authority, evidence: item.evidence })), artifacts, observed);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    /** Only these independently settled output locations may supplement baseline
+     * evidence in the final result binding. The returned map is a defensive copy.
+     */
+    outputHashes() { return this.#observed.hashes(); }
+    historicalEvidence() {
+        const units = this.#original.value().units;
+        return new Set(units.flatMap(unit => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`)));
+    }
+    resultEvidence() { return this.#workers.map(worker => structuredClone(worker.evidence)); }
+    outputLocations() {
+        const selected = new Map();
+        for (const artifacts of this.#artifacts.values())
+            for (const artifact of artifacts)
+                selected.set(memorySourceKey(artifact.root, artifact.path), { root: artifact.root, path: artifact.path });
+        return [...selected.values()];
+    }
+    assertResult(result) {
+        if (!(result instanceof PreparedMemoryStageResult))
+            refuse("prepared_result_required");
+        const original = this.#original.value(), final = result.value(), value = final;
+        const identity = ["schema_id", "run_id", "input_sha256", "predecessors"];
+        if (hybridDigest(identity.map(field => original[field])) !== hybridDigest(identity.map(field => final[field])))
+            refuse("foreign_result_identity");
+        if (value.stage !== "compose" || value.outcome !== "accepted" || hybridDigest(value.details) !== hybridDigest(original.details)
+            || value.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved"))
+            refuse("composition_not_accepted_or_plan_changed");
+        const inventory = new Map(original.units.map(unit => [unit.id, unit]));
+        if (value.units.length !== inventory.size || new Set(value.units.map(unit => unit.id)).size !== inventory.size)
+            refuse("changed_unit_coverage");
+        for (const unit of value.units) {
+            const initial = inventory.get(unit.id);
+            if (!initial || unit.aspect !== initial.aspect || unit.applicability !== initial.applicability || unit.applicability === "unknown"
+                || unit.outcome !== (unit.applicability === "not-applicable" ? "not-applicable" : "accepted"))
+                refuse("unaccepted_unit_or_changed_assignment");
+            const expected = this.#artifacts.get(unit.id) ?? [], identities = new Set(unit.artifacts.map(artifact => hybridDigest(artifact)));
+            if (unit.applicability !== "not-applicable" && !expected.length || identities.size !== expected.length
+                || expected.some(artifact => !identities.has(hybridDigest(artifact))))
+                refuse("unit_outputs_not_settled");
+        }
+    }
+    assertCustody(context) {
+        context.db.readSnapshot(() => {
+            if (hybridDigest(readMemoryCompositionRegistration(context, this.#scope)) !== this.#registrationSha256)
+                refuse("registration_changed");
+            const assigned = roots(context, this.#scope);
+            for (const worker of this.#workers)
+                if (settled(context, this.#scope, worker.id, worker.harness, this.#registrationSha256, assigned).authority !== worker.authority)
+                    refuse("work_settlement_changed");
+        });
+    }
+    revalidate(context) { this.#observed.revalidate(); this.assertCustody(context); }
+}

package/dist/services/memory-composition-graph.js

@@ -0,0 +1,134 @@
+import { AppError } from "../shared/errors.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+function refuse(reason) {
+    throw new AppError("memory_stage_result_invalid", "Memory composition graph cannot be dispatched", 2, { reason, phase: "prepare", effect: "no_effect" });
+}
+// Portable scopes must remain safe on case-insensitive/normalizing filesystems.
+const physicalPath = (value) => value.normalize("NFC").toLowerCase();
+const projectConfigurationPaths = [".memory-bank/dd-flow/project-execution.json", ".memory-bank/dd-flow/project-workspace.json"];
+/** Exact project-owned defaults, never directory or case aliases of canon. */
+export function memoryProjectConfigurationPath(value) { return projectConfigurationPaths.includes(value); }
+/** Check both assigned directories and their concrete output descendants. */
+export function memoryCompositionOutputAllowed(value) {
+    if (overlaps(value, ".memory-bank/dd-flow") && !memoryProjectConfigurationPath(value))
+        return false;
+    return value.split("/").every(part => localEnvironmentAllowed(part)
+        && ![".git", "node_modules", ".dd-flow"].includes(physicalPath(part)));
+}
+function overlaps(left, right) {
+    const a = physicalPath(left), b = physicalPath(right);
+    return a === "." || b === "." || a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+/** Called only after strict result-schema and contained-path admission. These
+ * semantic graph checks precede Work allocation, not merely worker dispatch.
+ * They do not grant filesystem access or replace frozen profile/Work custody.
+ */
+export function validateMemoryCompositionGraph(value) {
+    const result = value;
+    const unresolved = result.units.findIndex(unit => unit.applicability === "unknown");
+    if (unresolved !== -1)
+        throw new AppError("memory_stage_result_invalid", "Resolve the composition target before assigning Work; missing facts may remain explicit in its content", 2, { reason: "unresolved_composition_applicability", phase: "prepare", effect: "no_effect", unit_id: result.units[unresolved].id,
+            pointer: `/units/${unresolved}/applicability`, hint: "Choose applicable for an intended document or compact shelf, or not-applicable with a reason and no assigned writer. Do not invent missing project facts." });
+    const works = result.details.works;
+    const byKey = new Map(works.map(work => [work.key, work]));
+    if (byKey.size !== works.length || new Set(works.map(work => physicalPath(work.key))).size !== works.length)
+        refuse("duplicate_composition_work");
+    for (const work of works) {
+        if (work.depends_on.some(key => !byKey.has(key)))
+            refuse("unknown_composition_dependency");
+        for (const scopes of [work.read_scopes, work.write_scopes]) {
+            if (new Set(scopes.map(scope => `${scope.root}\0${physicalPath(scope.path)}`)).size !== scopes.length)
+                refuse("duplicate_composition_scope");
+        }
+        for (const scope of work.write_scopes) {
+            if (scope.path === ".")
+                refuse("unbounded_composition_write");
+            if (scope.root === "workspace" && (scope.path !== ".memory-bank" && !scope.path.startsWith(".memory-bank/")))
+                refuse("foreign_composition_write");
+            // These exact files are project-owned defaults consumed by ordinary
+            // entry, not selected canon. Never grant their enclosing directory or
+            // case/normalization aliases; the installed prompt/schema pack is sealed.
+            const projectConfig = memoryProjectConfigurationPath(scope.path);
+            if (scope.root === "workspace" && !projectConfig && [".memory-bank/mbb", ".memory-bank/dd-flow"].some(canonical => overlaps(scope.path, canonical)))
+                refuse("canonical_composition_write");
+            // A contained semantic scope is not permission to alter credentials,
+            // repository metadata, installed dependencies or runtime state.
+            if (!memoryCompositionOutputAllowed(scope.path))
+                refuse("private_composition_write");
+            if (scope.root === "run" && ["execution-bundle", "run.json"].some(authority => overlaps(scope.path, authority)))
+                refuse("authority_composition_write");
+            // Mechanical RUN files and another Work's evidence are never semantic outputs.
+            if (scope.root === "run") {
+                const namespace = `memory-artifacts/compose/${work.key}`;
+                if (scope.path !== namespace && !scope.path.startsWith(`${namespace}/`))
+                    refuse("foreign_composition_run_write");
+            }
+        }
+    }
+    // Iterative topological order avoids recursion on an agent-sized graph.
+    const remaining = new Map(works.map(work => [work.key, work.depends_on.length]));
+    const children = new Map();
+    for (const work of works)
+        for (const dependency of work.depends_on) {
+            const list = children.get(dependency) ?? [];
+            list.push(work.key);
+            children.set(dependency, list);
+        }
+    const ready = works.filter(work => !work.depends_on.length).map(work => work.key);
+    const positions = new Map(works.map((work, index) => [work.key, index]));
+    const ancestors = new Map();
+    const dependsOn = (work, dependency) => {
+        const position = positions.get(dependency);
+        return Boolean(ancestors.get(work)[position >>> 5] & (1 << (position & 31)));
+    };
+    for (let cursor = 0; cursor < ready.length; cursor++) {
+        const key = ready[cursor], work = byKey.get(key);
+        const inherited = new Uint32Array(Math.ceil(works.length / 32));
+        for (const dependency of work.depends_on) {
+            const position = positions.get(dependency);
+            inherited[position >>> 5] |= 1 << (position & 31);
+            const prior = ancestors.get(dependency);
+            for (let word = 0; word < prior.length; word++)
+                inherited[word] |= prior[word];
+        }
+        ancestors.set(key, inherited);
+        for (const child of children.get(key) ?? []) {
+            const count = remaining.get(child) - 1;
+            remaining.set(child, count);
+            if (!count)
+                ready.push(child);
+        }
+    }
+    if (ready.length !== works.length)
+        refuse("cyclic_composition_dependency");
+    const assemblies = works.filter(work => work.role === "index-assembly");
+    const declared = new Set(result.details.assembly_work_keys);
+    if (declared.size !== result.details.assembly_work_keys.length || declared.size !== assemblies.length
+        || assemblies.some(work => !declared.has(work.key)))
+        refuse("invalid_assembly_membership");
+    const applicable = new Set(result.units.filter(unit => unit.applicability !== "not-applicable").map(unit => unit.id));
+    for (const work of works)
+        if (work.unit_ids.some(id => !applicable.has(id)))
+            refuse("inapplicable_composition_work");
+    for (const unit of applicable) {
+        const authors = works.filter(work => work.unit_ids.includes(unit));
+        const writers = authors.filter(work => work.role === "writer");
+        const collectors = assemblies.filter(work => work.unit_ids.includes(unit));
+        if (!authors.length || !collectors.length)
+            refuse("incomplete_composition_coverage");
+        if (collectors.some(collector => writers.some(writer => !dependsOn(collector.key, writer.key))))
+            refuse("assembly_precedes_unit_writers");
+    }
+    for (let index = 0; index < works.length; index++) {
+        const left = works[index];
+        for (const right of works.slice(index + 1)) {
+            if (dependsOn(left.key, right.key) || dependsOn(right.key, left.key))
+                continue;
+            if (left.write_scopes.some(a => right.write_scopes.some(b => a.root === b.root && overlaps(a.path, b.path))))
+                refuse("unordered_composition_writers");
+            if (left.write_scopes.some(a => right.read_scopes.some(b => a.root === b.root && overlaps(a.path, b.path)))
+                || right.write_scopes.some(a => left.read_scopes.some(b => a.root === b.root && overlaps(a.path, b.path))))
+                refuse("unordered_composition_read_write");
+        }
+    }
+}