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

package/dist/services/memory-verification-receipt.js

@@ -0,0 +1,159 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { PreparedCheckEvidence, PreparedRetainedCheckEvidence } from "./code-checks.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedMemoryVerificationAcceptance } from "./memory-verification-acceptance.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+const event = "memory.verification_acceptance";
+function refuse(reason) {
+    throw new AppError("memory_verification_receipt_invalid", "Verification lacks committed historical check custody", 2, { reason, effect: "no_effect" });
+}
+function stage(context, scope) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+    if (!run)
+        refuse("run_missing");
+    const index = JSON.parse(run.index_json), selected = index.stage_runs.find((value) => value.stage === "verify");
+    if (!selected || typeof selected.attempt !== "string" || !/^try-[0-9]{3,}$/.test(selected.attempt)
+        || typeof selected.input_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(selected.input_sha256))
+        refuse("verify_identity_missing");
+    return { current: index.current_stage, attempt: selected.attempt, input_sha256: selected.input_sha256, status: selected.status };
+}
+function receiptRows(context, scope) {
+    return context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+}
+/** Independent receipt written in the same transaction as fresh acceptance.
+ * A later replay does not re-evaluate today's policy or repaired workspace.
+ * It proves only that these exact bytes/checks were accepted historically.
+ */
+export class PreparedMemoryVerificationReceipt {
+    #scope;
+    #receipt;
+    #checks;
+    #acceptance;
+    #result;
+    constructor(scope, receipt, checks, acceptance, result) {
+        this.#scope = { ...scope };
+        this.#receipt = structuredClone(receipt);
+        this.#checks = checks;
+        this.#acceptance = acceptance;
+        this.#result = result;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.result instanceof PreparedMemoryStageResult) || !(input.checks instanceof PreparedCheckEvidence)
+            || !(input.acceptance instanceof PreparedMemoryVerificationAcceptance))
+            refuse("prepared_acceptance_required");
+        input.checks.assertOwner({ ...input.scope, scope: "aggregate" });
+        input.acceptance.assertCustody(context, input.result, input.checks);
+        const selected = context.db.readSnapshot(() => stage(context, input.scope)), value = input.result.value();
+        if (selected.current !== "verify" || selected.status !== "running" || value.stage !== "verify" || (value.outcome !== "accepted" && value.outcome !== "needs_repair")
+            || value.run_id !== input.scope.runId || value.input_sha256 !== selected.input_sha256)
+            refuse("active_result_required");
+        if (receiptRows(context, input.scope).length)
+            refuse("fresh_receipt_already_exists");
+        const receipt = { schema_id: "dd-flow/memory-verification-acceptance@1", run_id: input.scope.runId, stage: "verify", project_id: input.scope.projectId,
+            attempt: selected.attempt, input_sha256: selected.input_sha256, result_sha256: input.result.sha256, checks: input.checks.retainedReferences(context) };
+        if (!receipt.checks.length || receipt.checks.length > 4096 || Buffer.byteLength(JSON.stringify(receipt)) > 2 * 1024 * 1024)
+            refuse("receipt_exceeds_bound");
+        return new PreparedMemoryVerificationReceipt(input.scope, receipt, input.checks, input.acceptance, input.result);
+    }
+    record(context) {
+        this.#checks.assertCustody(context);
+        this.#acceptance.assertCustody(context, this.#result);
+        const selected = stage(context, this.#scope);
+        if (selected.current !== "verify" || selected.status !== "running" || selected.attempt !== this.#receipt.attempt
+            || selected.input_sha256 !== this.#receipt.input_sha256 || receiptRows(context, this.#scope).length)
+            refuse("fresh_custody_changed");
+        if (hybridDigest(this.#checks.retainedReferences(context)) !== hybridDigest(this.#receipt.checks))
+            refuse("selected_checks_changed");
+        appendAudit(context, { projectId: this.#scope.projectId, eventType: event, payload: this.#receipt });
+    }
+}
+export class PreparedAcceptedMemoryVerification {
+    #scope;
+    #authority;
+    #receiptSha256;
+    #checks;
+    constructor(scope, authority, receiptSha256, checks) {
+        this.#scope = { ...scope };
+        this.#authority = authority;
+        this.#receiptSha256 = receiptSha256;
+        this.#checks = checks;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+            refuse("invalid_replay_bytes");
+        const selected = context.db.readSnapshot(() => accepted(context, input));
+        if (!selected.data.bytes.equals(input.bytes))
+            refuse("accepted_result_changed");
+        const checks = PreparedRetainedCheckEvidence.prepare(context, { projectId: input.projectId, runId: input.runId, references: selected.receipt.checks,
+            ...(JSON.parse(selected.data.bytes.toString("utf8")).outcome === "needs_repair" ? { mode: "diagnostic" } : {}) });
+        const prepared = new PreparedAcceptedMemoryVerification(input, selected.authority, selected.sha256, checks);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    assertCustody(context) {
+        const selected = context.db.readSnapshot(() => accepted(context, this.#scope));
+        if (selected.sha256 !== this.#receiptSha256 || selected.authority !== this.#authority)
+            refuse("accepted_custody_changed");
+        this.#checks.assertCustody(context);
+    }
+    revalidate(context) { this.#checks.revalidate(context); this.assertCustody(context); }
+    qualityPassed(context) { this.assertCustody(context); return JSON.parse(accepted(context, this.#scope).data.bytes.toString("utf8")).outcome === "accepted"; }
+    diagnosticFindings(context) {
+        this.assertCustody(context);
+        const findings = JSON.parse(accepted(context, this.#scope).data.bytes.toString("utf8")).findings;
+        return findings.map(finding => ({ ...structuredClone(finding), evidence: finding.evidence.map(source => ({ ...source, root: source.root === "run" ? "run" : "workspace", path: source.root === "canon" ? `.memory-bank/${source.path}` : source.path })) }));
+    }
+    finalChecks(context) { if (!this.qualityPassed(context))
+        refuse("verification_quality_not_passed"); return structuredClone(accepted(context, this.#scope).receipt.checks); }
+    /** SQL-only policy identity from the independently accepted check rows,
+     * not today's mutable project profile or coordinator result JSON. */
+    profileHash(context) {
+        this.assertCustody(context);
+        const selected = accepted(context, this.#scope);
+        const hashes = selected.receipt.checks.map(reference => {
+            const row = context.db.get("SELECT profile_hash FROM check_receipts WHERE project_id=? AND run_id=? AND id=?", [this.#scope.projectId, this.#scope.runId, reference.id]);
+            if (!row || (row.profile_hash !== null && (typeof row.profile_hash !== "string" || !/^[a-f0-9]{64}$/.test(row.profile_hash))))
+                refuse("accepted_policy_hash_missing");
+            return row.profile_hash;
+        });
+        if (!hashes.length || hashes.some(value => value !== hashes[0]))
+            refuse("accepted_policy_hash_inconsistent");
+        return hashes[0];
+    }
+}
+function accepted(context, scope) {
+    const selected = stage(context, scope), data = readAcceptedStageData(context, { ...scope, stage: "verify" }), rows = receiptRows(context, scope);
+    if (selected.status !== "done" || rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+        refuse("accepted_receipt_missing");
+    let receipt;
+    try {
+        receipt = JSON.parse(rows[0].payload_json);
+    }
+    catch {
+        return refuse("invalid_receipt_json");
+    }
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt) || hybridDigest({ ...receipt, checks: undefined }) !== hybridDigest({ schema_id: "dd-flow/memory-verification-acceptance@1", run_id: scope.runId, stage: "verify", project_id: scope.projectId,
+        attempt: selected.attempt, input_sha256: selected.input_sha256, result_sha256: data.result.sha256 }) || data.data_schema_id !== "dd-flow/mb-init-verify-result@1"
+        || data.input_sha256 !== selected.input_sha256)
+        refuse("accepted_receipt_changed");
+    const value = JSON.parse(data.bytes.toString("utf8"));
+    const compose = readAcceptedStageData(context, { ...scope, stage: "compose" }), composed = JSON.parse(compose.bytes.toString("utf8"));
+    if (compose.data_schema_id !== "dd-flow/mb-init-compose-result@1"
+        || composed.schema_id !== compose.data_schema_id || composed.stage !== "compose" || composed.run_id !== scope.runId
+        || composed.outcome !== "accepted" || composed.input_sha256 !== compose.input_sha256
+        || hybridDigest(value.predecessors) !== hybridDigest([{ stage: "compose", result: compose.result, input_sha256: compose.input_sha256 }]))
+        refuse("accepted_predecessor_changed");
+    if (value.stage !== "verify" || value.run_id !== scope.runId || !["accepted", "needs_repair"].includes(value.outcome) || value.input_sha256 !== selected.input_sha256
+        || !Array.isArray(receipt.checks) || receipt.checks.some(reference => !reference || typeof reference !== "object" || Array.isArray(reference)
+        || Object.keys(reference).some(key => !["id", "path", "sha256", "sql_sha256"].includes(key))
+        || typeof reference.id !== "string" || !reference.id || typeof reference.path !== "string"
+        || typeof reference.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(reference.sha256)
+        || typeof reference.sql_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(reference.sql_sha256)) || !Array.isArray(value.details?.checks)
+        || receipt.checks.some(({ path, sha256 }) => !value.details.checks.some((reference) => reference.path === path && reference.sha256 === sha256)))
+        refuse("accepted_check_references_changed");
+    return { data, receipt, sha256: hybridDigest(receipt), authority: hybridDigest({ verify: data.authority_sha256, compose: compose.authority_sha256 }) };
+}

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

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { AppError } from "../shared/errors.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { PreparedMemoryBaselinePreservation } from "./memory-baseline-preservation.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+import { PreparedMemoryVerificationChecks } from "./memory-verification-checks.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedAcceptedMemoryComposition } from "./memory-accepted-composition.js";
+import { PreparedMemoryVerificationAcceptance, projectMemoryVerificationChecks, projectMemoryVerificationArtifacts } from "./memory-verification-acceptance.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedMemoryVerificationReceipt, PreparedAcceptedMemoryVerification } from "./memory-verification-receipt.js";
+function refuse(reason) {
+    throw new AppError("memory_verify_handler_invalid", "Memory verification lacks registered scope or accepted composition", 2, { reason, effect: "no_effect" });
+}
+/** CLI-owned finite checks for the active verifier. Callers supply no command,
+ * profile hash, receipt path or alternate executable. Public routing remains
+ * pending complete memory handler registration.
+ */
+export function runMemoryVerificationChecks(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("compose", "accepted") !== "verify"
+        || bundle.descriptor.successor("verify", "accepted") !== "review")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    if (index.current_stage !== "verify" || index.stage_runs.find((stage) => stage.stage === "verify")?.status !== "running")
+        refuse("active_verification_required");
+    return PreparedMemoryVerificationChecks.prepare(context, { ...scope, execution: bundle.execution, flow: bundle.descriptor }).execute(context);
+}
+/** Productive entry implementation, not registered until the complete six-stage
+ * memory group is ready. Checks and semantic assessment acceptance belong to
+ * its finish path, not this allocation of a verifier coordinator.
+ */
+export function startMemoryVerification(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("compose", "accepted") !== "verify"
+        || bundle.descriptor.successor("verify", "accepted") !== "review")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage: "verify" };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    if (index.stage_runs.find((stage) => stage.stage === "verify")?.status === "done")
+        refuse("use_accepted_finish_replay");
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const inherited = context.db.readSnapshot(() => ({ compose: readAcceptedStageData(context, { ...scope, stage: "compose" }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
+    const compose = JSON.parse(inherited.compose.bytes.toString("utf8")), preflight = JSON.parse(inherited.preflight.bytes.toString("utf8"));
+    if (compose.schema_id !== "dd-flow/mb-init-compose-result@1" || compose.run_id !== input.runId || compose.outcome !== "accepted"
+        || preflight.schema_id !== "dd-flow/mb-init-preflight-result@1" || preflight.run_id !== input.runId || preflight.outcome !== "accepted")
+        refuse("accepted_composition_and_baseline_required");
+    const fence = (writer) => {
+        preservation.assertCustody(writer);
+        if (readAcceptedStageData(writer, { ...scope, stage: "compose" }).authority_sha256 !== inherited.compose.authority_sha256
+            || readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== inherited.preflight.authority_sha256)
+            refuse("inherited_custody_changed");
+    };
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "verify" });
+    preservation.revalidate(context);
+    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "verify" });
+    preservation.revalidate(context);
+    return { ...stage, ...coordinator.apply(context, fence) };
+}
+/** Verification settlement. Restore composition from committed SQL and
+ * its original registration, never from verifier-proposed predecessor bytes.
+ * Replay consumes independent historical acceptance/check custody instead of
+ * current workspace policy. No partial registry is enabled by this path.
+ */
+export function finishMemoryVerification(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_result_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("compose", "accepted") !== "verify"
+        || bundle.descriptor.successor("verify", "accepted") !== "review")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    if (index.stage_runs.find((stage) => stage.stage === "verify")?.status === "done") {
+        const data = readAcceptedStageData(context, { ...scope, stage: "verify" });
+        const accepted = PreparedAcceptedMemoryVerification.prepare(context, { ...scope, bytes: data.bytes });
+        const value = JSON.parse(data.bytes.toString("utf8"));
+        let proposal;
+        try {
+            proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+        }
+        catch {
+            refuse("invalid_result_bytes");
+        }
+        if (hybridDigest(projectMemoryVerificationChecks(projectMemoryVerificationArtifacts(proposal, value.units, value.units.flatMap((unit) => unit.artifacts)), value.details.checks, bundle.descriptor.stage("verify").directory, createHash("sha256").update(input.bytes).digest("hex"))) !== hybridDigest(value))
+            refuse("accepted_result_changed");
+        const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "verify", bytes: data.bytes });
+        accepted.revalidate(context);
+        return settlement.apply(context, writer => accepted.assertCustody(writer));
+    }
+    const composition = PreparedAcceptedMemoryComposition.prepare(context, { scope, bundle }), compose = composition.result();
+    const composedUnits = compose.value().units;
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const policy = PreparedMemoryVerificationChecks.prepare(context, { ...scope, execution: bundle.execution, flow: bundle.descriptor });
+    const checks = policy.evidence(context, "diagnostic");
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, stage: "verify", flow: bundle.descriptor, execution: bundle.execution, bundle,
+        sources: composition.captureSources(context, input.bytes, checks), checks });
+    let proposal;
+    try {
+        proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+    }
+    catch {
+        PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+        refuse("invalid_result_bytes");
+    }
+    const references = checks.sourceReferences().map(({ path, sha256 }) => ({ path, sha256 }));
+    const result = PreparedMemoryStageResult.prepare(Buffer.from(JSON.stringify(projectMemoryVerificationChecks(projectMemoryVerificationArtifacts(proposal, composedUnits, composition.outputReferences(), createHash("sha256").update(input.bytes).digest("hex")), references, bundle.descriptor.stage("verify").directory, createHash("sha256").update(input.bytes).digest("hex")))), bundle.descriptor, binding.binding());
+    const acceptance = PreparedMemoryVerificationAcceptance.prepare({ scope, result, compose, checks, composition, roots: bundle.execution.snapshot().scope });
+    const receipt = PreparedMemoryVerificationReceipt.prepare(context, { scope, result, checks, acceptance });
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "verify", bytes: result.bytes() });
+    composition.revalidate(context);
+    binding.revalidate(context);
+    // Binding owns the check artifact references and has just revalidated the
+    // same checks; acceptance adds SQL custody, not another physical pass.
+    preservation.revalidate(context);
+    policy.revalidate(context);
+    acceptance.assertCustody(context, result);
+    return settlement.apply(context, writer => {
+        composition.assertCustody(writer);
+        binding.assertCustody(writer);
+        preservation.assertCustody(writer);
+        policy.assertCustody(writer);
+        acceptance.assertCustody(writer, result);
+        receipt.record(writer);
+    });
+}

package/dist/services/memory-work-result-preparation.js

@@ -0,0 +1,63 @@
+import { AppError } from "../shared/errors.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { readWorkBatchCustody } from "./work-registry.js";
+import { selectMemoryCompositionRegistration } from "./memory-composition-registration.js";
+import { PreparedRegisteredMemoryCompositionWorkResult } from "./memory-composition-work-custody.js";
+import { PreparedRegisteredMemoryReviewWorkResult } from "./memory-review-work-custody.js";
+import { PreparedPublishedMemoryRepairWorkResult } from "./memory-repair-work-custody.js";
+import { restoreMemoryRepairPublicationFromStage, prepareMemorySecondRepairPublicationFromStage } from "./memory-review-handler.js";
+/** Public Work finish selects authority from SQL and the retained bundle, not
+ * from worker JSON, mutable schemas, caller profile or a supplied request key.
+ * Preparation is read-only and occurs before the settlement writer.
+ */
+export function prepareRegisteredMemoryWorkResult(context, work, result) {
+    if (!["dd-flow/memory-composition-work-result@1", "dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"].includes(work.result_schema ?? ""))
+        return null;
+    const bytes = Buffer.from(result, "utf8");
+    if (work.result_schema === "dd-flow/memory-repair-work-result@1") {
+        if (!bytes.length || bytes.length > 1024 * 1024)
+            throw new AppError("memory_work_result_preparation_required", "Repair finish requires bounded published result bytes", 1, { effect: "no_effect" });
+        const run = context.db.get("SELECT project_root FROM runs WHERE project_id=? AND id=?", [work.project_id, work.run_id]);
+        const link = context.db.get("SELECT id,start_receipt_json FROM work_sessions WHERE work_id=? AND status='running'", [work.work_id]);
+        let wave, workspaceRoot;
+        try {
+            const payload = JSON.parse(work.payload_json ?? "null");
+            if (payload?.kind !== "memory-repair" || payload.read_only !== false)
+                throw new Error("Invalid repair payload");
+            wave = payload.memory_repair?.wave;
+            if (!link?.start_receipt_json || Buffer.byteLength(link.start_receipt_json) > 32 * 1024 * 1024)
+                throw new Error("Missing bounded start receipt");
+            const receipt = JSON.parse(link.start_receipt_json);
+            if (typeof receipt.context !== "string" || Buffer.byteLength(receipt.context) > 16 * 1024 * 1024)
+                throw new Error("Missing bounded context");
+            workspaceRoot = JSON.parse(receipt.context).workspace_root;
+        }
+        catch {
+            throw new AppError("memory_work_result_preparation_required", "Repair finish requires retained physical start scope", 1, { effect: "no_effect" });
+        }
+        if (!run || !link || wave !== 1 && wave !== 2 || typeof workspaceRoot !== "string" || !workspaceRoot)
+            throw new AppError("memory_work_result_preparation_required", "Repair finish requires its exact wave and WorkSession", 1, { effect: "no_effect" });
+        const input = { projectRoot: run.project_root, runId: work.run_id, workId: work.work_id, workSessionId: link.id, workspaceRoot };
+        const publication = wave === 1 ? restoreMemoryRepairPublicationFromStage(context, input) : prepareMemorySecondRepairPublicationFromStage(context, input);
+        if (!publication.bytes().equals(bytes))
+            throw new AppError("memory_work_result_preparation_required", "Submitted repair bytes differ from the retained publication", 1, { effect: "no_effect" });
+        return PreparedPublishedMemoryRepairWorkResult.prepare(context, publication);
+    }
+    if (work.result_schema === "dd-flow/memory-review-work-result@1") {
+        return PreparedRegisteredMemoryReviewWorkResult.prepare(context, { workId: work.work_id, bytes });
+    }
+    const run = context.db.get("SELECT project_root FROM runs WHERE project_id=? AND id=?", [work.project_id, work.run_id]);
+    const bundle = run && readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: work.run_id });
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+        throw new AppError("memory_work_result_preparation_required", "Composition finish requires its retained memory flow", 1, { effect: "no_effect" });
+    const custody = readWorkBatchCustody(context, work.work_id);
+    const registration = selectMemoryCompositionRegistration(context, {
+        project_id: work.project_id, run_id: work.run_id, stage: "compose", attempt: custody.scope.attempt,
+        cycle: custody.scope.cycle, parent_work_id: custody.scope.parent_work_id
+    });
+    return PreparedRegisteredMemoryCompositionWorkResult.prepareFromStageCustody(context, bytes, bundle.engine(), {
+        projectId: work.project_id, runId: work.run_id, workId: work.work_id,
+        coordinatorWorkId: registration.scope.parent_work_id, requestKey: registration.scope.request_key,
+        flow: bundle.descriptor, execution: bundle.execution, bundle
+    });
+}

package/dist/services/projects.js

@@ -11,9 +11,24 @@ import { loadProjectFlowContract } from "../domain/flow-contract.js";
 import { buildStaticFlowGuidance } from "./flow-guidance.js";
 import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 import { buildProjectSummary, projectRegistrySummary, readPublishedProjectSummary } from "./project-summary.js";
+/** Resolve filesystem identity before entering a composite SQL writer. */
+export class PreparedProjectRegistration {
+    #root;
+    constructor(root) { this.#root = root; Object.freeze(this); }
+    static prepare(input) {
+        return new PreparedProjectRegistration(resolveProjectRoot(input.root));
+    }
+    root() { return this.#root; }
+}
 export function registerProject(context, input) {
-    const root = resolveProjectRoot(input.root);
-    const existing = findProjectByRoot(context, root);
+    return registerPreparedProject(context, PreparedProjectRegistration.prepare(input));
+}
+/** Metadata-only registration; the composite caller owns its SQL transaction. */
+export function registerPreparedProject(context, prepared) {
+    if (!(prepared instanceof PreparedProjectRegistration))
+        throw new AppError("validation", "Project registration must be prepared", 2);
+    const root = prepared.root();
+    const existing = context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
     const now = context.now();
     const project = existing ?? newProjectRecord(context, root, now);
     if (existing) {