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

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

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

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { addWorkBatch, prepareWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+const workerSchema = "dd-flow/memory-composition-work-result@1";
+function refuse(reason) {
+    throw new AppError("memory_composition_registration_invalid", "Retained composition registration cannot authorize this graph", 1, { reason, effect: "no_effect" });
+}
+const bytesHash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function readReceipt(context, scope) {
+    const requestSha256 = hybridDigest(scope);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'memory.composition_registration' AND json_extract(payload_json, '$.request_sha256') = ?", [scope.project_id, requestSha256]);
+    if (!rows.length)
+        return null;
+    try {
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+            refuse("ambiguous_or_unbounded_receipt");
+        const receipt = JSON.parse(rows[0].payload_json);
+        if (receipt.schema_id !== "dd-flow/memory-composition-registration@1" || receipt.request_sha256 !== requestSha256
+            || receipt.run_id !== scope.run_id || hybridDigest(receipt.scope) !== requestSha256 || receipt.result_schema !== workerSchema
+            || [receipt.batch_sha256, receipt.compose_result_sha256, receipt.input_sha256, receipt.execution_sha256].some(hash => typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash))
+            || typeof receipt.result_base64 !== "string" || !receipt.work_ids || Array.isArray(receipt.work_ids)
+            || typeof receipt.work_ids !== "object" || !Object.keys(receipt.work_ids).length || Object.keys(receipt.work_ids).length > 4096
+            || Object.values(receipt.work_ids).some(id => typeof id !== "string")
+            || new Set(Object.values(receipt.work_ids)).size !== Object.keys(receipt.work_ids).length)
+            refuse("foreign_receipt_binding");
+        const bytes = Buffer.from(receipt.result_base64, "base64");
+        if (!bytes.length || bytes.length > 1024 * 1024 || bytes.toString("base64") !== receipt.result_base64
+            || bytesHash(bytes) !== receipt.compose_result_sha256)
+            refuse("changed_result_bytes");
+        for (const [key, id] of Object.entries(receipt.work_ids)) {
+            const custody = readWorkBatchCustody(context, id);
+            if (custody.item_key !== key || custody.request_sha256 !== requestSha256 || custody.batch_sha256 !== receipt.batch_sha256
+                || hybridDigest(custody.work_ids) !== hybridDigest(receipt.work_ids) || hybridDigest(custody.scope) !== requestSha256)
+                refuse("changed_work_custody");
+        }
+        return receipt;
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_composition_registration_invalid")
+            throw error;
+        return refuse("invalid_receipt_or_work_custody");
+    }
+}
+/** SQL-only identity check for the settlement writer; no schema or filesystem I/O. */
+export function memoryCompositionRegistrationDigest(context, scope) {
+    const receipt = readReceipt(context, scope);
+    if (!receipt)
+        refuse("composition_receipt_missing");
+    return hybridDigest(receipt);
+}
+/** Independent SQL blueprint bytes, never the final result or mutable file. */
+export function readMemoryCompositionRegistration(context, scope) {
+    const receipt = readReceipt(context, scope);
+    if (!receipt)
+        refuse("composition_receipt_missing");
+    return structuredClone(receipt);
+}
+/** Finish selects the sole original plan for this independently owned stage
+ * attempt; an agent result does not choose a request key or its Work graph.
+ */
+export function selectMemoryCompositionRegistration(context, scope) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')=? AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? LIMIT 2", [scope.project_id, scope.run_id, scope.stage, scope.attempt, scope.cycle, scope.parent_work_id]);
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+        refuse("original_composition_missing_or_ambiguous");
+    let retained;
+    try {
+        retained = JSON.parse(rows[0].payload_json);
+    }
+    catch {
+        return refuse("invalid_receipt_or_work_custody");
+    }
+    if (typeof retained?.scope?.request_key !== "string" || hybridDigest(retained.scope) !== hybridDigest({ ...scope, request_key: retained.scope.request_key }))
+        refuse("foreign_receipt_binding");
+    return readMemoryCompositionRegistration(context, { ...scope, request_key: retained.scope.request_key });
+}
+/** Registration custody, not semantic stage acceptance. The caller must first
+ * establish accepted predecessor/source and coordinator/Session authority.
+ * Prepared bytes and Work allocation commit together; no mutable file is read
+ * under the writer. An existing generic batch cannot be retroactively adopted.
+ */
+export function registerMemoryComposition(context, input, assertHandlerCustody) {
+    if (!(input.composition instanceof PreparedMemoryStageResult))
+        refuse("foreign_prepared_result");
+    const value = input.composition.compositionBatch({ ...input.binding, resultSchema: workerSchema });
+    const bytes = input.composition.bytes();
+    const batchInput = { parentWorkId: input.parentWorkId, requestKey: input.requestKey, stage: "compose", value };
+    const prepared = prepareWorkBatch(context, batchInput);
+    return context.db.writeTransaction(() => {
+        assertHandlerCustody?.(context);
+        const parent = context.db.get("SELECT project_id, run_id FROM works WHERE work_id = ?", [input.parentWorkId]);
+        if (!parent || parent.run_id !== input.binding.runId)
+            refuse("foreign_coordinator");
+        const scope = { ...stageGraphScope(context, parent.project_id, parent.run_id, "compose"),
+            stage: "compose", parent_work_id: input.parentWorkId, request_key: input.requestKey };
+        // One immutable blueprint per coordinator/attempt. A different request key
+        // cannot create another productive graph or bypass a lost original receipt.
+        const originals = context.db.all("SELECT json_extract(payload_json,'$.request_sha256') AS request_sha256 FROM audit_events WHERE project_id=? AND event_type='memory.composition_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')='compose' AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.cycle')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? LIMIT 2", [scope.project_id, scope.run_id, scope.attempt, scope.cycle, scope.parent_work_id]);
+        if (originals.length > 1 || originals.length === 1 && originals[0].request_sha256 !== hybridDigest(scope))
+            refuse("original_composition_already_registered");
+        const prior = readReceipt(context, scope);
+        if (!prior && 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 w.result_schema=? AND m.stage='compose' AND m.attempt=? AND m.cycle=? LIMIT 1", [scope.project_id, scope.run_id, scope.parent_work_id, workerSchema, scope.attempt, scope.cycle]))
+            refuse("composition_receipt_missing");
+        if (prior && (prior.compose_result_sha256 !== input.composition.sha256 || prior.batch_sha256 !== hybridDigest(value.works)
+            || prior.input_sha256 !== input.binding.inputSha256 || prior.execution_sha256 !== input.binding.executionSha256))
+            refuse("request_conflict");
+        const allocation = addWorkBatch(context, { ...batchInput, prepared });
+        const workIds = allocation.work_ids;
+        if (prior) {
+            if (hybridDigest(prior.work_ids) !== hybridDigest(workIds))
+                refuse("changed_allocation");
+        }
+        else {
+            if (allocation.replayed)
+                refuse("composition_receipt_missing");
+            const receipt = { schema_id: "dd-flow/memory-composition-registration@1", scope, run_id: parent.run_id,
+                request_sha256: hybridDigest(scope), batch_sha256: hybridDigest(value.works), compose_result_sha256: input.composition.sha256,
+                result_base64: bytes.toString("base64"), input_sha256: input.binding.inputSha256,
+                execution_sha256: input.binding.executionSha256, result_schema: workerSchema, work_ids: workIds };
+            appendAudit(context, { projectId: parent.project_id, eventType: "memory.composition_registration", payload: { ...receipt } });
+        }
+        return { scope, compose_result_sha256: input.composition.sha256, work_ids: { ...workIds }, replayed: Boolean(prior) };
+    });
+}
+/** Restore the exact registered bytes and re-prepare with independently selected
+ * frozen schema/execution and predecessor/source observations. No file or settings
+ * fallback; restored registration does not attest completed Works or stage acceptance.
+ */
+export function readRegisteredMemoryComposition(context, input) {
+    const receipt = readReceipt(context, input.scope);
+    if (!receipt)
+        refuse("composition_receipt_missing");
+    if (input.binding.runId !== input.scope.run_id || input.binding.stage !== "compose"
+        || input.binding.inputSha256 !== receipt.input_sha256 || input.binding.executionSha256 !== receipt.execution_sha256)
+        refuse("foreign_restore_binding");
+    const result = PreparedMemoryStageResult.prepare(Buffer.from(receipt.result_base64, "base64"), input.flow, input.binding);
+    const batch = result.compositionBatch({ runId: input.binding.runId, inputSha256: receipt.input_sha256,
+        executionSha256: receipt.execution_sha256, resultSchema: workerSchema });
+    if (result.sha256 !== receipt.compose_result_sha256 || hybridDigest(batch.works) !== receipt.batch_sha256
+        || batch.works.length !== Object.keys(receipt.work_ids).length || batch.works.some(item => !Object.hasOwn(receipt.work_ids, item.key)))
+        refuse("changed_registered_graph");
+    return result;
+}

package/dist/services/memory-composition-work-custody.js

@@ -0,0 +1,151 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedMemoryCompositionWorkResult } from "./memory-composition-work-results.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { readRegisteredMemoryComposition, memoryCompositionRegistrationDigest } from "./memory-composition-registration.js";
+import { readWorkBatchCustody } from "./work-registry.js";
+import { stageWorkIds } from "./stage-work-graph.js";
+import { assertRunBundleSqlAuthority } from "./runs.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { appendAudit } from "./audit.js";
+import { runtimeHarness } from "./execution-policy.js";
+function refuse() {
+    throw new AppError("memory_composition_work_custody_invalid", "Registered Work differs from the independently selected composition", 1, { phase: "prepare", effect: "no_effect" });
+}
+function assignedRoots(context, custody) {
+    const run = context.db.get("SELECT workspace_root, run_root, run_dir FROM runs WHERE project_id = ? AND id = ?", [custody.scope.project_id, custody.scope.run_id]);
+    if (!run || !path.isAbsolute(run.workspace_root) || !path.isAbsolute(run.run_root ?? run.run_dir))
+        refuse();
+    return { workspace: run.workspace_root, run: run.run_root ?? run.run_dir };
+}
+/** Bridges independent SQL allocation custody and physical output preparation.
+ * The caller must independently select the accepted composition and frozen engine.
+ * This is not stage acceptance, Session settlement, or semantic completeness.
+ */
+export class PreparedRegisteredMemoryCompositionWorkResult {
+    sha256;
+    workId;
+    #custody;
+    #result;
+    #roots;
+    #registration = null;
+    #stageBinding = null;
+    #harness;
+    constructor(custody, roots, result, harness) {
+        this.#custody = custody;
+        this.#roots = roots;
+        this.#result = result;
+        this.#harness = harness;
+        this.sha256 = result.sha256;
+        this.workId = custody.work_id;
+        Object.freeze(this);
+    }
+    /** Restart path: composition bytes come from CLI registration, while its
+     * predecessor/source/schema/execution binding still comes from the controller.
+     */
+    static prepareFromStageCustody(context, input, engine, binding) {
+        const custody = readWorkBatchCustody(context, binding.workId);
+        const selected = binding.bundle ? PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...binding, bundle: binding.bundle,
+            registrationScope: { project_id: binding.projectId, run_id: binding.runId, stage: "compose", attempt: custody.scope.attempt, cycle: custody.scope.cycle,
+                parent_work_id: binding.coordinatorWorkId, request_key: binding.requestKey } })
+            : binding.sources ? PreparedMemoryResultBinding.prepare(context, { ...binding, sources: binding.sources, stage: "compose" }) : refuse();
+        const prepared = this.prepareFromRegistration(context, input, engine, { ...binding, resultBinding: selected.binding() });
+        prepared.#stageBinding = selected;
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    static prepareFromRegistration(context, input, engine, binding) {
+        const custody = readWorkBatchCustody(context, binding.workId);
+        if (custody.scope.stage !== "compose" || custody.scope.parent_work_id !== binding.coordinatorWorkId
+            || custody.scope.request_key !== binding.requestKey || !binding.resultBinding.executionSha256)
+            refuse();
+        const scope = { project_id: custody.scope.project_id, run_id: custody.scope.run_id,
+            stage: "compose", attempt: custody.scope.attempt, cycle: custody.scope.cycle,
+            parent_work_id: binding.coordinatorWorkId, request_key: binding.requestKey };
+        const registrationSha256 = memoryCompositionRegistrationDigest(context, scope);
+        const composition = readRegisteredMemoryComposition(context, { scope, flow: binding.flow, binding: binding.resultBinding });
+        const prepared = this.prepare(context, input, engine, { workId: binding.workId, coordinatorWorkId: binding.coordinatorWorkId, requestKey: binding.requestKey,
+            composition, compositionSha256: composition.sha256, runId: binding.resultBinding.runId,
+            inputSha256: binding.resultBinding.inputSha256, executionSha256: binding.resultBinding.executionSha256 });
+        prepared.#registration = { scope, sha256: registrationSha256 };
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    static prepare(context, input, engine, binding) {
+        const custody = readWorkBatchCustody(context, binding.workId);
+        if (!(binding.composition instanceof PreparedMemoryStageResult) || binding.composition.sha256 !== binding.compositionSha256
+            || custody.scope.run_id !== binding.runId || custody.scope.stage !== "compose"
+            || custody.scope.parent_work_id !== binding.coordinatorWorkId || custody.scope.request_key !== binding.requestKey)
+            refuse();
+        const batch = binding.composition.compositionBatch({ ...binding, resultSchema: "dd-flow/memory-composition-work-result@1" });
+        if (hybridDigest(batch.works) !== custody.batch_sha256 || batch.works.length !== Object.keys(custody.work_ids).length
+            || batch.works.some(item => !Object.hasOwn(custody.work_ids, item.key)))
+            refuse();
+        const assigned = batch.works.find(item => item.key === custody.item_key);
+        const row = context.db.get("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [custody.scope.project_id, binding.runId, binding.workId]);
+        if (!assigned || !row || row.parent_work_id !== binding.coordinatorWorkId || row.task !== assigned.task
+            || row.launch_policy !== assigned.launch_policy || row.result_schema !== assigned.result_schema
+            || hybridDigest(JSON.parse(row.depends_on_json)) !== hybridDigest(assigned.depends_on.map(key => custody.work_ids[key]))
+            || hybridDigest(JSON.parse(row.payload_json)) !== hybridDigest({ ...assigned.payload, _dd_flow_batch_request: {
+                    request_sha256: custody.request_sha256, batch_sha256: custody.batch_sha256, item_key: custody.item_key
+                } }))
+            refuse();
+        const roots = assignedRoots(context, custody);
+        const result = PreparedMemoryCompositionWorkResult.prepare(input, engine, { ...binding, workKey: custody.item_key,
+            roots });
+        const route = binding.composition.compositionRoutes().find(item => item.key === custody.item_key);
+        if (!route)
+            refuse();
+        return new PreparedRegisteredMemoryCompositionWorkResult(custody, roots, result, runtimeHarness(route.execution.worker));
+    }
+    bytes() { return this.#result.bytes(); }
+    /** Physical I/O stays outside the writer; the reservation rechecks SQL only. */
+    revalidate(context) { this.#stageBinding?.revalidate(context); this.assertCustody(context); this.#result.revalidate(); }
+    assertCustody(context) {
+        if (hybridDigest(readWorkBatchCustody(context, this.#custody.work_id)) !== hybridDigest(this.#custody)
+            || hybridDigest(assignedRoots(context, this.#custody)) !== hybridDigest(this.#roots))
+            refuse();
+        if (this.#registration && memoryCompositionRegistrationDigest(context, this.#registration.scope) !== this.#registration.sha256)
+            refuse();
+        this.#stageBinding?.assertCustody(context);
+    }
+    /** Active settlement authority is separate from immutable allocation custody. */
+    assertSettlementScope(context, sessionId, workSessionId) {
+        this.assertCustody(context);
+        const scope = this.#custody.scope;
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [scope.project_id, scope.run_id]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        assertRunBundleSqlAuthority(context, { projectId: scope.project_id, runId: scope.run_id }, index?.execution_bundle);
+        const stage = index?.stage_runs?.findLast((item) => item.stage === "compose" && item.status === "running");
+        if (!this.#registration || !this.#stageBinding || index?.current_stage !== "compose" || !stage || (stage.attempt ?? "try-001") !== scope.attempt
+            || !stageWorkIds(context, scope.project_id, scope.run_id, "compose").has(this.workId)
+            || !stageWorkIds(context, scope.project_id, scope.run_id, "compose").has(scope.parent_work_id)
+            || !context.db.get("SELECT 1 FROM work_sessions WHERE id = ? AND work_id = ? AND session_id = ? AND status = 'running'", [workSessionId, this.workId, sessionId])
+            || !context.db.get("SELECT 1 FROM works WHERE work_id = ? AND project_id = ? AND run_id = ? AND status = 'running'", [scope.parent_work_id, scope.project_id, scope.run_id])
+            || !context.db.get("SELECT 1 FROM sessions s JOIN runs r ON r.project_id = s.project_id AND r.id = s.run_id WHERE s.project_id = ? AND s.session_id = ? AND s.run_id = ? AND s.worker_id = ? AND s.harness = ? AND s.status = 'active' AND s.current_stage = 'work' AND s.project_root = r.project_root AND s.workspace_path = r.workspace_root", [scope.project_id, sessionId, scope.run_id, this.workId, this.#harness])) {
+            throw new AppError("memory_work_settlement_scope_invalid", "Composition Work settlement no longer belongs to its active stage and Session", 1, { work_id: this.workId, effect: "no_effect" });
+        }
+    }
+    /** Called inside the Work settlement writer, before its status CAS. The
+     * receipt commits or rolls back with the result and physical WorkSession.
+     * It retains successful output preparation without requiring an obsolete
+     * writer artifact to survive a declared dependent assembly unchanged.
+     */
+    recordSettlement(context, sessionId, workSessionId) {
+        this.assertSettlementScope(context, sessionId, workSessionId);
+        const registration = this.#registration;
+        const rows = context.db.all("SELECT 1 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 1", [this.#custody.scope.project_id, this.#custody.scope.run_id, this.workId]);
+        if (rows.length)
+            refuse();
+        const session = context.db.get("SELECT provider_session_id FROM sessions WHERE project_id=? AND session_id=?", [this.#custody.scope.project_id, sessionId]);
+        if (!session || typeof session.provider_session_id !== "string" || !session.provider_session_id)
+            refuse();
+        appendAudit(context, { projectId: this.#custody.scope.project_id, eventType: "memory.composition_work_settlement", payload: {
+                schema_id: "dd-flow/memory-composition-work-settlement@1", run_id: this.#custody.scope.run_id, work_id: this.workId,
+                work_session_id: workSessionId, session_id: sessionId, harness: this.#harness, provider_session_id: session.provider_session_id,
+                scope: registration.scope, registration_sha256: registration.sha256,
+                allocation_sha256: hybridDigest(this.#custody), roots: this.#roots, result_sha256: this.sha256
+            } });
+    }
+}