@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/delivery-result.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { types } from "node:util";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { resolveDeliveryBinding } from "./delivery-policy.js";
+import { executeDeliveryStep } from "./delivery-execution.js";
+import { readDeliveryIntent } from "./delivery-intents.js";
+import { appendAudit } from "./audit.js";
+import { managedProcessStatus, managedProcessBinding, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && Boolean(value.trim()) && value.length <= 4096 && !value.includes("\0");
+const reference = (value) => value === null || record(value) && Object.keys(value).sort().join() === "id,kind" && text(value.id) && text(value.kind);
+function validRollback(value, operation) {
+    if (operation !== "deploy")
+        return !Object.hasOwn(value, "rollback");
+    const rollback = value.rollback;
+    return record(rollback) && Object.keys(rollback).sort().join() === "reason,reference,status,strategy"
+        && typeof rollback.strategy === "string" && ["rollback", "roll_forward", "operator_handoff"].includes(rollback.strategy)
+        && typeof rollback.status === "string" && ["not_needed", "required", "completed", "failed", "unknown"].includes(rollback.status)
+        && text(rollback.reason) && reference(rollback.reference)
+        && (rollback.status !== "completed" || rollback.reference !== null)
+        && (value.status === "complete" ? rollback.status === "not_needed" : rollback.status !== "not_needed");
+}
+function refuse(reason) {
+    throw new AppError("delivery_result_unproven", "Read back the original delivery; do not repeat its mutation", 2, { reason, effect: "unknown", next_action: "reconcile_original_delivery" });
+}
+/** Settlement reads the latest owned observation, never a supplied filename
+ * or an older optimistic answer after a newer uncertain readback. A changed
+ * operation log needs a new observation; this is not a retry authorization. */
+export function readDeliveryResult(context, scope) {
+    const intent = readDeliveryIntent(context, scope);
+    if (!intent)
+        refuse("original_intent_required");
+    const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='delivery.operation_readback' AND json_extract(payload_json,'$.run_id')=? ORDER BY id DESC LIMIT 1", [scope.projectId, scope.runId]);
+    if (!row || Buffer.byteLength(row.payload_json) > 131072)
+        refuse("retained_readback_required");
+    let receipt;
+    try {
+        receipt = JSON.parse(row.payload_json);
+    }
+    catch {
+        return refuse("retained_readback_invalid");
+    }
+    const grant = intent.plan.approval.scope, observed = receipt?.observation;
+    if (receipt?.schema_id !== "dd-flow/delivery-result@1" || receipt.run_id !== scope.runId || receipt.intent_sha256 !== intent.identity
+        || receipt.operation_head_sha256 !== intent.head || !observed || observed.schema_id !== "dd-flow/delivery-result-observation@1"
+        || observed.operation_id !== grant.operation_id || observed.binding_id !== grant.binding_id
+        || hybridDigest(observed.artifact) !== hybridDigest(grant.artifact) || hybridDigest(observed.selector) !== hybridDigest(grant.selector)
+        || !["complete", "absent", "partial", "unknown"].includes(observed.status)
+        || !reference(observed.reference) || observed.status === "complete" && observed.reference === null
+        || !validRollback(observed, grant.selector.operation)
+        || !Number.isFinite(Date.parse(receipt.observed_at)) || !Array.isArray(receipt.processes) || !receipt.processes.length
+        || receipt.processes.length > 16 || receipt.processes.some(id => typeof id !== "string" || !id.startsWith("PROC-")))
+        refuse("retained_readback_changed");
+    return { sha256: hybridDigest(receipt), receipt: structuredClone(receipt) };
+}
+/** Private result/reconciliation observation. The caller proves the actual
+ * Stage/coordinator authority and project readback safety. No new approval,
+ * login, retry, rollback or terminal Stage/RUN decision is inferred here.
+ * Reconciliation intentionally does not require unexpired mutation approval
+ * or local artifact availability: an earlier effect must remain observable. */
+export async function observeDeliveryResult(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("observation_outside_writer_required");
+    const binding = resolveDeliveryBinding({ schema_id: "dd-flow/delivery-policy@1", bindings: [input.binding] }, input.binding.selector);
+    const original = readDeliveryIntent(context, input);
+    if (!original)
+        refuse("original_intent_required");
+    const grant = original.plan.approval.scope;
+    if (hybridDigest(binding) !== grant.binding_sha256)
+        refuse("original_binding_required");
+    const assertOwner = () => {
+        const checked = input.assertCurrent();
+        if (types.isPromise(checked)) {
+            void checked.catch(() => { });
+            refuse("synchronous_owner_fence_required");
+        }
+        const current = readDeliveryIntent(context, input);
+        if (!current || current.identity !== original.identity || current.head !== original.head)
+            refuse("original_operation_changed");
+        return current;
+    };
+    const assertCurrent = () => {
+        const current = assertOwner();
+        // The old command may lack a result event after interruption. Readback is
+        // allowed only after every originally admitted process is physically quiet.
+        const processes = managedProcessStatus(context);
+        for (const event of current.events) {
+            if (event.kind !== "admitted")
+                continue;
+            const process = processes.find(item => item.id === event.process.process_id);
+            if (event.process.resource_home !== resourceHome(context) || !process || process.state !== "stopped"
+                || managedProcessBinding(process, resourceHome(context)).registration_sha256 !== event.process.registration_sha256
+                || processTreeIsAlive(process))
+                refuse("original_process_not_settled");
+        }
+    };
+    assertCurrent();
+    const procedure = binding.procedures.result_readback, deadline = Date.now() + procedure.timeout_ms, processes = [];
+    let observed;
+    for (const step of procedure.procedure_steps) {
+        let value;
+        try {
+            const result = await executeDeliveryStep(context, { projectId: input.projectId, runId: input.runId,
+                operationId: `result-${randomUUID()}`, stepId: step.id, workspace: original.plan.artifact.workspace,
+                procedure, deadlineAt: deadline, assertCurrent, admit() { }, consumeOutput(bytes) {
+                    value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+                } });
+            processes.push(result.process_id);
+        }
+        catch {
+            return refuse("readback_failed");
+        }
+        const keys = binding.selector.operation === "deploy" ? "artifact,binding_id,operation_id,reference,rollback,schema_id,selector,status"
+            : "artifact,binding_id,operation_id,reference,schema_id,selector,status";
+        if (!record(value) || Object.keys(value).sort().join() !== keys
+            || value.schema_id !== "dd-flow/delivery-result-observation@1" || value.operation_id !== grant.operation_id || value.binding_id !== binding.id
+            || hybridDigest(value.artifact) !== hybridDigest(grant.artifact) || hybridDigest(value.selector) !== hybridDigest(grant.selector)
+            || !["complete", "absent", "partial", "unknown"].includes(value.status)
+            || !reference(value.reference) || !validRollback(value, binding.selector.operation)
+            || value.status === "complete" && value.reference === null)
+            refuse("result_context_mismatch_or_unsafe_output");
+        const next = value;
+        // Ordered steps may confirm the same result; a conflicting earlier answer
+        // is not silently overwritten by a more optimistic later command.
+        if (observed && hybridDigest(observed) !== hybridDigest(next))
+            refuse("conflicting_readback");
+        observed = structuredClone(next);
+    }
+    assertCurrent();
+    if (!observed || Date.now() >= deadline)
+        refuse("readback_incomplete");
+    const receipt = { schema_id: "dd-flow/delivery-result@1", run_id: input.runId, intent_sha256: original.identity,
+        operation_head_sha256: original.head, observed_at: context.now(), observation: observed, processes };
+    if (!Number.isFinite(Date.parse(receipt.observed_at)))
+        refuse("observation_clock_invalid");
+    return context.db.writeTransaction(() => {
+        // Physical observation is already settled. Only current SQL/owner fences
+        // run in this short writer; receipt persistence does not close the intent.
+        assertOwner();
+        appendAudit(context, { projectId: input.projectId, eventType: "delivery.operation_readback", payload: receipt });
+        return structuredClone(receipt);
+    });
+}

package/dist/services/delivery-stage-commands.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+import { deliveryFlowStages } from "../domain/delivery-flows.js";
+import { AppError } from "../shared/errors.js";
+import { runtimeCommand } from "./runtime-command.js";
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+/** Packet candidates are not invocation admission or mutation approval. */
+export function deliveryStageCommands(context, input) {
+    if (!deliveryFlowStages[input.flowId].includes(input.stage))
+        throw new AppError("delivery_stage_invalid", "Unknown delivery Stage", 2, { effect: "no_effect" });
+    const command = (operation, file) => runtimeCommand(context, ["delivery", operation, input.runId,
+        "--project-root", input.projectRoot, "--stage", input.stage, ...(file ? ["--result-file", file] : []), "--json"]);
+    return {
+        inputs: command("inputs"),
+        ...(["prepare", "verify"].includes(input.stage) ? { checks: command("checks", path.join(input.stageRoot, "delivery-artifact.json")) } : {}),
+        ...(["publish", "deploy"].includes(input.stage) ? { execute: command("execute", path.join(input.stageRoot, "delivery-approval.json")) } : {}),
+        ...(["publish", "deploy", "verify", "finish"].includes(input.stage) ? { reconcile: command("reconcile") } : {})
+    };
+}
+/** Issue only after the native Stage coordinator is bound. Keep assignments
+ * out of immutable semantic packets and include literal commands for custody. */
+export function issueDeliveryStageCommands(context, input) {
+    const commands = Object.fromEntries(Object.entries(deliveryStageCommands(context, input))
+        .map(([operation, candidate]) => [operation, operation === "inputs" ? candidate : managedLifecycleCommand(context, candidate)]));
+    const instructions = `\n## Bound delivery command candidates\n\n\`\`\`json\n${JSON.stringify(commands, null, 2)}\n\`\`\`\n\nWrite the exact artifact/approval JSON to the issued result-file before checks/execute. Starting this Stage grants no mutation approval. Reconcile the original intent; never retry an unknown effect.\n\n## Current issued delivery commands\n\n${Object.values(commands).join("\n\n")}\n`;
+    return { commands, instructions };
+}

package/dist/services/delivery-stage-entry.js

@@ -0,0 +1,56 @@
+import { AppError } from "../shared/errors.js";
+import { deliveryFlowStages } from "../domain/delivery-flows.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+import { readActiveDescriptorStageCoordinator } from "./descriptor-stage-settlement.js";
+import { currentLifecycleAdmission, lifecycleInvocationScope, assertLifecycleInvocationCurrent } from "./lifecycle-invocations.js";
+function refuse(reason) {
+    throw new AppError("delivery_stage_invalid", "Delivery requires its registered flow, original request and current Stage owner", 2, { reason, effect: "no_effect" });
+}
+/** Internal family entry, not a public launcher or permission to publish.
+ * The ordinary descriptor runtime owns attempt, coordinator Work and Session.
+ * Delivery uses its actual workspace, not a read-only diagnostic clone. */
+export function readDeliveryStageScope(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const bundle = readFlowRunExecutionBundle(context, input), flow = bundle?.manifest.flow_id;
+    if (!bundle || !flow || !Object.hasOwn(deliveryFlowStages, flow)
+        || !deliveryFlowStages[flow].includes(input.stage))
+        refuse("registered_delivery_stage_required");
+    const flowId = flow, scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    bundle.descriptor.stage(input.stage);
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const users = readPreparedMemoryFlowUserInputs(context, scope, flowId, bundle), userInputsSha256 = hybridDigest(users);
+    return { scope, bundle, run, flowId, users, userInputsSha256,
+        assertCustody(writer) {
+            assertPreparedRunBundleSqlAuthority(writer, scope, bundle);
+            if (hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, flowId, bundle)) !== userInputsSha256)
+                refuse("user_inputs_changed_during_entry");
+        }
+    };
+}
+export function startDeliveryStage(context, input) {
+    const selected = readDeliveryStageScope(context, input);
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context, selected.assertCustody);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, selected.assertCustody);
+    return { ...start, ...coordinator, flow_id: selected.flowId, user_inputs_sha256: selected.userInputsSha256 };
+}
+/** A matching SQL coordinator or ambient scope is not a command capability.
+ * The ordinary lifecycle gate must already have admitted this exact CLI process. */
+export function assertDeliveryCommandOwner(context, input) {
+    const id = context.env.DD_FLOW_CURRENT_INVOCATION;
+    if (!id || !currentLifecycleAdmission(context, id))
+        refuse("issued_coordinator_command_required");
+    const native = lifecycleInvocationScope(context, id);
+    assertLifecycleInvocationCurrent(context, native, input.command);
+    const selected = readDeliveryStageScope(context, input), actor = readActiveDescriptorStageCoordinator(context, selected.scope, selected.bundle);
+    const hook = context.db.get("SELECT daemon_id FROM hook_events WHERE project_id=? AND event_key=?", [selected.scope.projectId, actor.start_hook]);
+    if (native.projectRoot !== input.projectRoot || native.runId !== input.runId || native.rootSessionId !== actor.provider_session_id
+        || !hook?.daemon_id || hook.daemon_id !== native.daemonId)
+        refuse("current_physical_coordinator_required");
+    return selected;
+}

package/dist/services/delivery-stage-handlers.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { deliveryFlowStages } from "../domain/delivery-flows.js";
+import { readDeliveryStageScope, startDeliveryStage } from "./delivery-stage-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { readAcceptedStageData, prepareStageReport, acceptStageReport, publishStageReport } from "./stage-report-renderer.js";
+import { prepareDeliveryStageResult } from "./delivery-stage-results.js";
+import { prepareDeliveryProjectBinding } from "./delivery-policy.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareDeliveryChecks, prepareDeliveryHistoricalChecks } from "./delivery-checks.js";
+import { deliveryApprovalScope } from "./delivery-approval.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { readDeliveryIntent } from "./delivery-intents.js";
+import { readDeliveryResult } from "./delivery-result.js";
+import { appendAudit } from "./audit.js";
+export const deliveryStageHandlers = Object.freeze(Object.entries(deliveryFlowStages).flatMap(([flowId, stages]) => stages.map(stage => Object.freeze({ flowId, stage, entryId: "delivery-stage-entry", finishId: "delivery-stage-finish",
+    entry: startDeliveryStage, finish: finishDeliveryStage }))));
+function refuse(reason) {
+    throw new AppError("delivery_stage_invalid", "Delivery Stage requires observed project policy and owned evidence", 2, { reason, effect: "no_effect", phase: "prepare", recoverable: true });
+}
+/** Family settlement never runs the protected command. Only the operation
+ * owner can retain its original effect/readback; Stage reports cannot invent it.
+ * Public family admission/launch still requires its separate installed gates. */
+export function finishDeliveryStage(context, input) {
+    const selected = readDeliveryStageScope(context, input), { scope, bundle, flowId } = selected;
+    const stages = deliveryFlowStages[flowId], index = stages.indexOf(input.stage);
+    const packet = readDescriptorStageInput(context, scope, bundle, true, true);
+    const previous = index ? readAcceptedStageData(context, { ...scope, stage: stages[index - 1] }) : null;
+    let decision = null;
+    let policy;
+    if (index === 1) {
+        if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+            refuse("result_exceeds_bound");
+        try {
+            decision = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes)).details?.decision;
+        }
+        catch {
+            return refuse("invalid_result_json");
+        }
+        if (!decision?.policy || typeof decision.policy.path !== "string" || typeof decision.policy.sha256 !== "string"
+            || !decision.binding?.selector || typeof decision.version !== "string" || !decision.version.trim())
+            refuse("project_policy_required");
+        const workspace = bundle.execution.snapshot().scope.workspace;
+        policy = prepareDeliveryProjectBinding(workspace, decision.policy, decision.binding.selector);
+        if (hybridDigest(policy.binding) !== hybridDigest(decision.binding))
+            refuse("project_policy_binding_mismatch");
+    }
+    const prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+    let checks;
+    let verification;
+    let artifact = null;
+    let historical;
+    if (index > 1) {
+        decision = prior?.details?.decision;
+        artifact = prior?.details?.artifact;
+    }
+    if (["prepare", "verify"].includes(input.stage)) {
+        decision = prior?.details?.decision;
+        if (input.stage === "prepare") {
+            if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+                refuse("result_exceeds_bound");
+            try {
+                artifact = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes)).details?.artifact;
+            }
+            catch {
+                return refuse("invalid_result_json");
+            }
+        }
+        else
+            artifact = prior?.details?.artifact;
+        if (!artifact || !decision)
+            refuse("accepted_artifact_required");
+        checks = prepareDeliveryChecks(context, { ...input, artifact });
+        verification = checks.evidence();
+    }
+    const afterEffect = index >= stages.indexOf(flowId === "deploy" ? "deploy" : "publish");
+    const intent = afterEffect ? readDeliveryIntent(context, scope) : null;
+    const readback = afterEffect ? readDeliveryResult(context, scope) : null;
+    const operation = decision && artifact ? deliveryApprovalScope(scope, bundle, { operationId: decision.operation_id, binding: decision.binding,
+        artifact: { subject_ref: artifact.subject_ref, version: artifact.version, sha256: artifact.sha256 } }) : null;
+    if (afterEffect && (!intent || hybridDigest(intent.plan.approval.scope) !== hybridDigest(operation)))
+        refuse("original_delivery_scope_required");
+    if (afterEffect && !checks)
+        historical = prepareDeliveryHistoricalChecks(context, { ...input,
+            sourceStage: input.stage === "deploy" ? "prepare" : "verify", operationScopeSha256: hybridDigest(operation) });
+    const binding = { flowId, runId: input.runId, stage: input.stage,
+        inputSha256: packet.inputSha256, userInputsSha256: selected.userInputsSha256,
+        predecessors: packet.input.predecessor ? [{ stage: packet.input.predecessor.stage, ...packet.input.predecessor.result }] : [],
+        decision, artifact, deliveryScopeSha256: operation ? hybridDigest(operation) : null,
+        verificationSha256: verification ? hybridDigest(verification.receipt) : historical?.sha256 ?? null, intentSha256: intent?.identity ?? null,
+        readbackSha256: readback?.sha256 ?? null, readbackStatus: readback?.receipt.observation.status ?? null,
+        rollback: readback?.receipt.observation.rollback ?? null, retainedLimitations: prior?.details?.limitations ?? [] };
+    const bytes = prepareDeliveryStageResult(input.bytes, bundle.descriptor.stageBlob(input.stage, "result_schema"), binding);
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes });
+    policy?.assertCurrent();
+    checks?.revalidate();
+    verification?.proof.revalidate(context);
+    historical?.revalidate();
+    const reportRoot = input.stage === "finish" ? path.join(packet.runRoot, bundle.descriptor.stage(input.stage).directory) : "";
+    const report = input.stage === "finish" ? prepareStageReport({ run_id: input.runId, stage: "finish", verdict: "completed",
+        summary: JSON.parse(bytes.toString("utf8")).summary, delivery: { result: JSON.parse(bytes.toString("utf8")), readback: readback?.receipt,
+            verification: historical?.receipt }, semantic: { next_action: "The exact operation was observed; this report grants no new effect or retry." } }) : null;
+    const fence = (writer) => {
+        selected.assertCustody(writer);
+        if (previous && hybridDigest(readAcceptedStageData(writer, { ...scope, stage: stages[index - 1] })) !== hybridDigest(previous))
+            refuse("accepted_predecessor_changed");
+        checks?.assertCustody(writer);
+        verification?.proof.assertCustody(writer);
+        historical?.assertCustody(writer);
+        if (intent && readDeliveryIntent(writer, scope)?.identity !== intent.identity || readback && readDeliveryResult(writer, scope).sha256 !== readback.sha256)
+            refuse("delivery_readback_changed");
+        if (verification) {
+            const payload = { run_id: input.runId, stage: input.stage, sha256: hybridDigest(verification.receipt), receipt: verification.receipt };
+            const rows = writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='delivery.stage_checks' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? LIMIT 2", [scope.projectId, scope.runId, input.stage]);
+            if (rows.length > 1 || rows.length && hybridDigest(JSON.parse(rows[0].payload_json)) !== hybridDigest(payload))
+                refuse("accepted_verification_changed");
+            if (!rows.length)
+                appendAudit(writer, { projectId: scope.projectId, eventType: "delivery.stage_checks", payload });
+        }
+        if (report) {
+            const rows = writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_report' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='finish' AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, scope.runId, packet.attempt]);
+            if (rows.length > 1 || rows.length && JSON.parse(rows[0].payload_json).sha256 !== report.sha256)
+                refuse("terminal_report_changed");
+            if (!rows.length)
+                acceptStageReport(writer, { ...scope, root: reportRoot, prepared: report });
+        }
+    };
+    const accepted = settlement.apply(context, fence);
+    if (!report)
+        return accepted;
+    const complete = PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence);
+    publishStageReport(context, scope.projectId, input.runId, "finish", reportRoot);
+    return { ...accepted, ...complete, reports: ["json", "md", "html"].map(extension => path.join(reportRoot, `stage-report.${extension}`)) };
+}

package/dist/services/delivery-stage-results.js

@@ -0,0 +1,94 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { deliveryFlowStages } from "../domain/delivery-flows.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { resolveDeliveryBinding } from "./delivery-policy.js";
+function refuse(reason, parameter, message = "Delivery Stage requires its accepted selection and observed operation evidence") {
+    throw new AppError("delivery_stage_result_invalid", message, 2, { reason, ...(parameter ? { parameter } : {}), effect: "no_effect", phase: "prepare", recoverable: true });
+}
+/** Projection only. Bindings must be independently read from accepted Stage,
+ * check, approval, intent and readback owners, not copied from a model result.
+ * This validator does not authorize execution or prove semantic sufficiency. */
+export function prepareDeliveryStageResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || !schemaBytes.length || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    let proposal, validate;
+    try {
+        proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+        if (schema.$id !== "dd-flow/delivery-stage-result@1")
+            refuse("frozen_schema_invalid");
+        validate = new Ajv2020({ strict: true, validateFormats: false }).compile(schema);
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_schema");
+    }
+    if (!proposal || typeof proposal !== "object" || Array.isArray(proposal) || !proposal.details
+        || typeof proposal.details !== "object" || Array.isArray(proposal.details))
+        refuse("invalid_schema");
+    const stages = deliveryFlowStages[binding.flowId], index = stages.indexOf(binding.stage);
+    if (index < 0 || binding.predecessors.length !== (index ? 1 : 0)
+        || index && binding.predecessors[0]?.stage !== stages[index - 1])
+        refuse("foreign_stage_predecessor");
+    const owned = { schema_id: "dd-flow/delivery-stage-result@1", flow_id: binding.flowId, run_id: binding.runId,
+        stage: binding.stage, input_sha256: binding.inputSha256, user_inputs_sha256: binding.userInputsSha256, predecessors: binding.predecessors };
+    const details = proposal.details;
+    const proof = { decision: binding.decision, artifact: binding.artifact, delivery_scope_sha256: binding.deliveryScopeSha256,
+        intent_sha256: binding.intentSha256, readback_sha256: binding.readbackSha256, verification_sha256: binding.verificationSha256,
+        rollback: binding.rollback };
+    for (const [target, values] of [[proposal, owned], [details, proof]]) {
+        for (const [key, value] of Object.entries(values)) {
+            if (Object.hasOwn(target, key) && hybridDigest(target[key]) !== hybridDigest(value)) {
+                const parameter = target === proposal ? key : `details.${key}`;
+                refuse("unowned_stage_claim", parameter, value === null
+                    ? `${binding.stage} has no accepted ${parameter}. Omit this CLI-owned field or set it to null; do not advance selection or operation evidence into this Stage.`
+                    : `${parameter} differs from the CLI-owned Stage evidence. Use the current Stage and project-policy values, or omit a projected field; do not invent or copy a different binding.`);
+            }
+            target[key] = structuredClone(value);
+        }
+    }
+    if (!Array.isArray(details.limitations) || details.limitations.some(value => typeof value !== "string" || !value.trim()))
+        refuse("invalid_schema");
+    details.limitations = [...new Set([...binding.retainedLimitations, ...details.limitations])];
+    if (!validate(proposal) || typeof proposal.summary !== "string" || !proposal.summary.trim())
+        refuse("invalid_schema");
+    if (binding.stage === "preflight") {
+        if (Object.values(proof).some(value => value !== null) || binding.readbackStatus !== null)
+            refuse("preflight_cannot_grant_delivery");
+    }
+    else {
+        const decision = binding.decision;
+        if (!decision)
+            refuse("accepted_decision_required");
+        const normalized = resolveDeliveryBinding({ schema_id: "dd-flow/delivery-policy@1", bindings: [decision.binding] }, decision.binding.selector);
+        if (normalized.selector.operation !== binding.flowId)
+            refuse("foreign_delivery_decision");
+        if (binding.flowId === "deploy" ? !decision.rollback : decision.rollback !== undefined)
+            refuse("deployment_rollback_plan_required");
+        if (decision.rollback && (!decision.rollback.reason.trim()
+            || decision.rollback.strategy !== "operator_handoff" && !decision.rollback.procedure_ref?.trim()))
+            refuse("deployment_rollback_plan_required");
+        if (index >= 2) {
+            const artifact = binding.artifact;
+            if (!artifact || artifact.subject_ref !== normalized.selector.subject_ref || artifact.version !== decision.version
+                || !binding.deliveryScopeSha256 || !binding.verificationSha256)
+                refuse("verified_artifact_required");
+        }
+        else if (binding.artifact !== null || binding.deliveryScopeSha256 !== null || binding.verificationSha256 !== null)
+            refuse("premature_artifact_claim");
+        const mutationIndex = stages.indexOf(binding.flowId === "deploy" ? "deploy" : "publish");
+        if (index >= mutationIndex) {
+            if (!binding.intentSha256 || !binding.readbackSha256 || binding.readbackStatus !== "complete")
+                refuse("completed_delivery_readback_required");
+            if (binding.flowId === "deploy" && binding.rollback?.status !== "not_needed")
+                refuse("deployment_recovery_unresolved");
+        }
+        else if (binding.intentSha256 !== null || binding.readbackSha256 !== null || binding.readbackStatus !== null)
+            refuse("premature_delivery_claim");
+        if ((binding.flowId !== "deploy" || index < mutationIndex) && binding.rollback !== null)
+            refuse("premature_rollback_claim");
+    }
+    return Buffer.from(JSON.stringify(proposal));
+}

package/dist/services/descriptor-coordinator-session.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { readDescriptorStageInput, readDescriptorStageInputForRecovery } from "./descriptor-stage-coordinator.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { hasAssignedCoordinatorLaunch } from "./assigned-lifecycle.js";
+/** SQL-only physical coordinator proof, independent of allocation/prompt
+ * custody. It creates no Session, hook claim or provider operation.
+ */
+export function readDescriptorCoordinatorSession(context, input, refuse = reason => {
+    throw new AppError("descriptor_coordinator_session_invalid", "Coordinator has no matching physical Session custody", 1, { reason, effect: "no_effect" });
+}) {
+    const { scope, bundle, workId } = input;
+    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 selected = input.recoveryRead ? readDescriptorStageInputForRecovery(context, scope, bundle, input.recoveryRead) : readDescriptorStageInput(context, scope, bundle), directory = bundle.descriptor.stage(scope.stage).directory;
+    if (session.prompt_path !== path.join(selected.runRoot, directory, "coordinator-prompt.md")
+        || session.result_path !== path.join(selected.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])
+            && !hasAssignedCoordinatorLaunch(context, { projectId: scope.projectId, runId: scope.runId, stage: scope.stage, workSessionId: session.id, sessionId: session.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 });
+}

package/dist/services/descriptor-root-work.js

@@ -0,0 +1,53 @@
+import { AppError } from "../shared/errors.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { nextWorkId } from "./ids.js";
+import { appendAudit } from "./audit.js";
+const event = "flow_run.descriptor_root_work";
+function refuse(reason) {
+    throw new AppError("descriptor_root_work_invalid", "RUN root Work lacks independent allocation custody", 1, { reason, effect: "no_effect" });
+}
+const binding = (scope, bundle) => ({ projectId: scope.projectId, runId: scope.runId, bundle_sha256: bundle.sha256 });
+/** SQL-only read. Root identity is retained independently, never discovered
+ * from an arbitrary root row or reconstructed after receipt loss.
+ */
+export function readDescriptorRootWork(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const receipts = 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]);
+        if (receipts.length !== 1 || Buffer.byteLength(receipts[0].payload_json) > 16 * 1024)
+            refuse("root_work_receipt_missing");
+        const receipt = JSON.parse(receipts[0].payload_json);
+        const expected = binding(scope, bundle);
+        if (typeof receipt.work_id !== "string" || hybridDigest(receipt) !== hybridDigest({ run_id: scope.runId, work_id: receipt.work_id, binding: expected }))
+            refuse("root_work_changed");
+        const roots = context.db.all("SELECT work_id,task,payload_json,status,launch_policy,result_schema,depends_on_json FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL LIMIT 2", [scope.projectId, scope.runId]);
+        if (roots.length !== 1)
+            refuse("ambiguous_root_work");
+        const root = roots[0];
+        if (root.work_id !== receipt.work_id || root.task !== `Coordinate ${bundle.descriptor.descriptor.id}`
+            || root.payload_json !== JSON.stringify({ descriptor_run_coordinator: expected })
+            || root.launch_policy !== "reuse_allowed" || root.result_schema !== null || root.depends_on_json !== "[]")
+            refuse("root_work_custody_missing");
+        if (JSON.parse(run.index_json).root_work_id !== root.work_id)
+            refuse("root_work_anchor_missing");
+        return { workId: root.work_id, status: root.status };
+    });
+}
+/** Called only in the same writer as fresh descriptor RUN allocation. Stage
+ * handlers consume this identity; they never allocate a second RUN root.
+ */
+export function allocateDescriptorRootWork(context, scope, bundle) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL", [scope.projectId, scope.runId])
+        || context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=?", [scope.projectId, event, scope.runId]))
+        refuse("root_work_already_allocated");
+    const workId = nextWorkId(context, scope.projectId, bundle.descriptor.descriptor.id), now = context.now();
+    const expected = binding(scope, bundle);
+    context.db.run("INSERT INTO works (work_id,project_id,run_id,parent_work_id,task,launch_policy,depends_on_json,status,payload_json,created_at,updated_at) VALUES (?,?,?,NULL,?,'reuse_allowed','[]','created',?,?,?)", [workId, scope.projectId, scope.runId, `Coordinate ${bundle.descriptor.descriptor.id}`, JSON.stringify({ descriptor_run_coordinator: expected }), now, now]);
+    context.db.run("UPDATE runs SET index_json=json_set(index_json,'$.root_work_id',?) WHERE project_id=? AND id=?", [workId, scope.projectId, scope.runId]);
+    appendAudit(context, { projectId: scope.projectId, eventType: event, payload: { run_id: scope.runId, work_id: workId, binding: expected } });
+    if (readDescriptorRootWork(context, scope, bundle).workId !== workId)
+        refuse("root_work_not_retained");
+    return workId;
+}