@deksden-com/dd-flow-cli 0.9.0-beta.151 → 0.9.0-beta.155

package/dist/services/delivery-checks.js

@@ -0,0 +1,178 @@
+import { AppError } from "../shared/errors.js";
+import { readDeliveryStageScope } from "./delivery-stage-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readActiveDescriptorStageCoordinator, readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { prepareDeliveryProjectBinding } from "./delivery-policy.js";
+import { PreparedDeliveryArtifact } from "./delivery-artifact.js";
+import { deliveryApprovalScope } from "./delivery-approval.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { codeCheckProfileHash, projectPolicyCheckDeclarations, runCodeChecks, PreparedCheckEvidence, PreparedRetainedCheckEvidence } from "./code-checks.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { assertDiagnosticSessionIndependence } from "./diagnostic-work-collection.js";
+import { memoryCheckEnvironment } from "./memory-verification-checks.js";
+function refuse(reason) {
+    throw new AppError("delivery_checks_invalid", "Delivery verification needs current project checks for the exact selected artifact", 2, { reason, effect: "no_effect" });
+}
+/** Compare actual provider Sessions, not model names or distinct logical IDs.
+ * Accepted generic settlement proves the author; current coordinator custody
+ * proves the verifier. Lifecycle match keys resolve paths before the writer. */
+export function prepareDeliveryVerifierIndependence(context, input) {
+    if (input.stage !== "verify" || context.db.isOwnedWriteTransaction?.())
+        refuse("verification_stage_required");
+    const selected = readDeliveryStageScope(context, input), { scope, bundle } = selected;
+    const stages = selected.flowId === "deploy" ? ["prepare", "deploy"] : ["prepare"];
+    const sources = stages.map(stage => ({ stage, keys: entityReferenceVariants(input.runId)
+            .map(reference => stageLifecycleMatchKey("stage_finish", reference, stage, input.projectRoot)) }));
+    const observe = (reader) => {
+        selected.assertCustody(reader);
+        const physical = (sessionId) => {
+            const session = reader.db.get("SELECT harness,provider_session_id FROM sessions WHERE project_id=? AND run_id=? AND session_id=?", [scope.projectId, scope.runId, sessionId]);
+            if (!session?.harness || !session.provider_session_id)
+                refuse("verification_physical_owner_required");
+            return session;
+        };
+        const verifier = readActiveDescriptorStageCoordinator(reader, scope, bundle);
+        const authors = sources.map(source => readAcceptedDescriptorStageSettlement(reader, { ...scope, stage: source.stage }, bundle, source.keys));
+        const verifierSession = physical(verifier.session_id), authorSessions = authors.map(author => physical(author.binding.sessionId));
+        assertDiagnosticSessionIndependence([verifierSession], authorSessions);
+        return { verifier, authors, verifierSession, authorSessions };
+    };
+    const original = observe(context);
+    return (writer) => {
+        if (hybridDigest(observe(writer)) !== hybridDigest(original))
+            refuse("verification_physical_owner_changed");
+    };
+}
+/** Downstream acceptance reuses the original accepted execution proof, not
+ * today's declarations, invented hashes or a new run of publication checks. */
+export function prepareDeliveryHistoricalChecks(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const selected = readDeliveryStageScope(context, input), { scope, bundle } = selected;
+    if (input.sourceStage !== (selected.flowId === "deploy" && input.stage === "deploy" ? "prepare" : "verify"))
+        refuse("accepted_verification_stage_required");
+    const keys = entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, input.sourceStage, input.projectRoot));
+    const read = (reader) => {
+        const accepted = readAcceptedStageData(reader, { ...scope, stage: input.sourceStage });
+        const data = JSON.parse(accepted.bytes.toString("utf8"));
+        const rows = reader.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.sourceStage]);
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 1024 * 1024)
+            refuse("accepted_verification_required");
+        const value = JSON.parse(rows[0].payload_json), receipt = value.receipt;
+        if (data.schema_id !== "dd-flow/delivery-stage-result@1" || data.flow_id !== selected.flowId || data.run_id !== input.runId || data.stage !== input.sourceStage
+            || !receipt || value.sha256 !== hybridDigest(receipt) || value.sha256 !== data.details?.verification_sha256
+            || receipt.schema_id !== "dd-flow/delivery-checks@1" || receipt.run_id !== input.runId || receipt.stage !== input.sourceStage
+            || receipt.bundle_sha256 !== bundle.sha256 || receipt.input_sha256 !== data.input_sha256
+            || receipt.operation_scope_sha256 !== input.operationScopeSha256 || data.details.delivery_scope_sha256 !== input.operationScopeSha256
+            || !Array.isArray(receipt.checks) || !receipt.checks.length)
+            refuse("accepted_verification_changed");
+        return { accepted, value, owner: readAcceptedDescriptorStageSettlement(reader, { ...scope, stage: input.sourceStage }, bundle, keys) };
+    };
+    const original = read(context);
+    const proof = PreparedRetainedCheckEvidence.prepare(context, { ...scope, references: original.value.receipt.checks });
+    return { sha256: original.value.sha256, receipt: structuredClone(original.value.receipt),
+        revalidate() { proof.revalidate(context); },
+        assertCustody(writer) {
+            selected.assertCustody(writer);
+            proof.assertCustody(writer);
+            if (hybridDigest(read(writer)) !== hybridDigest(original))
+                refuse("accepted_verification_changed");
+        }
+    };
+}
+/** Immediately before an external effect, historical success is insufficient:
+ * the existing check owner must still match today's workspace and policy.
+ * This also catches an edited publish/deploy script with unchanged argv. */
+export function prepareDeliveryCurrentAcceptedChecks(context, input) {
+    const historical = prepareDeliveryHistoricalChecks(context, input), selected = readDeliveryStageScope(context, input);
+    if (!selected.run.run_root)
+        refuse("run_root_required");
+    const workspace = selected.bundle.execution.snapshot().scope.workspace;
+    const checks = [...projectPolicyCheckDeclarations(workspace, "code"), ...projectPolicyCheckDeclarations(workspace, "readiness")];
+    const environment = memoryCheckEnvironment(context, selected.scope.projectId, input.runId);
+    const proof = PreparedCheckEvidence.prepare(context, { projectId: selected.scope.projectId, runId: input.runId,
+        runHome: selected.run.run_root, workspaceRoot: workspace, scope: "aggregate", checks,
+        expectedProfileHash: historical.receipt.profile_sha256, evidenceContext: historical.receipt.evidence_context,
+        ...(environment ? { checkEnvironment: environment } : {}) });
+    if (!proof.qualityPassed() || hybridDigest(proof.retainedReferences(context)) !== hybridDigest(historical.receipt.checks))
+        refuse("accepted_verification_changed");
+    return {
+        revalidate() {
+            if (hybridDigest(memoryCheckEnvironment(context, selected.scope.projectId, input.runId) ?? null) !== hybridDigest(environment ?? null))
+                refuse("managed_check_home_changed");
+            historical.revalidate();
+            proof.revalidate(context);
+        },
+        assertCustody(writer) { historical.assertCustody(writer); proof.assertCustody(writer); }
+    };
+}
+/** The existing aggregate runner/check receipts, not model-reported tests.
+ * Declarations come from project policy, never the result being accepted.
+ * Semantic adequacy and independent verification remain Stage responsibilities. */
+export function prepareDeliveryChecks(context, input) {
+    if (context.db.isOwnedWriteTransaction?.() || !["prepare", "verify"].includes(input.stage))
+        refuse("verification_stage_required");
+    if (!input.artifact || typeof input.artifact !== "object" || Array.isArray(input.artifact))
+        refuse("accepted_artifact_selection_required");
+    const selected = readDeliveryStageScope(context, input), { scope, bundle } = selected;
+    const independent = input.stage === "verify" ? prepareDeliveryVerifierIndependence(context, input) : undefined;
+    const packet = readDescriptorStageInput(context, scope, bundle);
+    if (!packet.input.predecessor || !selected.run.run_root)
+        refuse("accepted_predecessor_required");
+    const previousStage = packet.input.predecessor.stage;
+    const previous = readAcceptedStageData(context, { ...scope, stage: previousStage });
+    const prior = JSON.parse(previous.bytes.toString("utf8"));
+    const decision = prior.details.decision;
+    if (!decision || input.stage !== "prepare" && hybridDigest(prior.details.artifact) !== hybridDigest(input.artifact))
+        refuse("accepted_artifact_selection_required");
+    const workspace = bundle.execution.snapshot().scope.workspace;
+    const policy = prepareDeliveryProjectBinding(workspace, decision.policy, decision.binding.selector);
+    if (hybridDigest(policy.binding) !== hybridDigest(decision.binding))
+        refuse("accepted_policy_changed");
+    const artifact = PreparedDeliveryArtifact.prepare(workspace, input.artifact.path, { subject_ref: input.artifact.subject_ref, version: input.artifact.version, sha256: input.artifact.sha256 });
+    if (input.artifact.version !== decision.version)
+        refuse("accepted_version_required");
+    const operation = deliveryApprovalScope(scope, bundle, { operationId: decision.operation_id, binding: policy.binding,
+        artifact: { subject_ref: input.artifact.subject_ref, version: input.artifact.version, sha256: input.artifact.sha256 } });
+    const checks = [...projectPolicyCheckDeclarations(workspace, "code"), ...projectPolicyCheckDeclarations(workspace, "readiness")];
+    if (!checks.length)
+        refuse("project_verification_checks_required");
+    const owner = readActiveDescriptorStageCoordinator(context, scope, bundle), profile = codeCheckProfileHash(workspace, checks);
+    const environment = memoryCheckEnvironment(context, scope.projectId, input.runId);
+    const evidenceContext = `delivery:${hybridDigest({ operation, stage: input.stage, input: packet.inputSha256, users: selected.userInputsSha256 })}`;
+    const command = { projectId: scope.projectId, runId: scope.runId, runHome: selected.run.run_root, workspaceRoot: workspace,
+        scope: "aggregate", checks, expectedProfileHash: profile, evidenceContext,
+        ...(environment ? { checkEnvironment: environment } : {}) };
+    const assertCustody = (writer) => {
+        selected.assertCustody(writer);
+        independent?.(writer);
+        if (hybridDigest(readDescriptorStageInput(writer, scope, bundle)) !== hybridDigest(packet)
+            || hybridDigest(readAcceptedStageData(writer, { ...scope, stage: previousStage })) !== hybridDigest(previous)
+            || hybridDigest(readActiveDescriptorStageCoordinator(writer, scope, bundle)) !== hybridDigest(owner))
+            refuse("verification_owner_or_inputs_changed");
+    };
+    const revalidate = () => {
+        assertCustody(context);
+        policy.assertCurrent();
+        artifact.assertCurrent();
+        if (hybridDigest(memoryCheckEnvironment(context, scope.projectId, input.runId) ?? null) !== hybridDigest(environment ?? null))
+            refuse("managed_check_home_changed");
+        if (codeCheckProfileHash(workspace, checks) !== profile)
+            refuse("verification_policy_changed");
+    };
+    revalidate();
+    return { operation: structuredClone(operation), artifact: structuredClone(input.artifact), assertCustody, revalidate,
+        async run() { revalidate(); const result = await runCodeChecks(context, command); revalidate(); return result; },
+        evidence() {
+            revalidate();
+            const proof = PreparedCheckEvidence.prepare(context, command);
+            if (!proof.qualityPassed())
+                refuse("verification_checks_failed");
+            return { proof, receipt: { schema_id: "dd-flow/delivery-checks@1", run_id: scope.runId, stage: input.stage,
+                    bundle_sha256: bundle.sha256, input_sha256: packet.inputSha256, operation_scope_sha256: hybridDigest(operation),
+                    evidence_context: evidenceContext, profile_sha256: profile, checks: proof.retainedReferences(context) } };
+        }
+    };
+}

package/dist/services/delivery-execution.js

@@ -0,0 +1,181 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { types } from "node:util";
+import { AppError } from "../shared/errors.js";
+import { prepareDeliveryProcedure } from "./delivery-procedures.js";
+import { managedLeaseMonitor } from "./managed-lease-monitor.js";
+import { physicalStartup } from "./physical-startup.js";
+import { registerManagedProcess, confirmManagedProcess, renewManagedProcess, finishManagedProcess, assertManagedProcessLease, processTreeIsAlive } from "./managed-processes.js";
+import { stopProcessGroup } from "../harness-runtime/lib/managed-daemon.mjs";
+const id = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
+/** One step of an already retained delivery intent, not a public launcher or
+ * approval/retry policy. Reuse the ordinary process registry/lease/stop owners.
+ * No raw command output, environment values or argv enter logs or the registry. */
+export async function executeDeliveryStep(context, input) {
+    const procedure = prepareDeliveryProcedure(input.procedure, "execute"), step = procedure.procedure_steps.find(item => item.id === input.stepId);
+    if (context.db.isOwnedWriteTransaction?.() || !step || ![input.projectId, input.runId, input.operationId, input.stepId].every(id)
+        || typeof input.workspace !== "string" || !path.isAbsolute(input.workspace) || typeof input.assertCurrent !== "function" || typeof input.admit !== "function"
+        || typeof input.consumeOutput !== "function")
+        throw new AppError("delivery_execution_invalid", "Delivery execution requires its retained operation and owner fence", 2, { effect: "no_effect" });
+    if (input.deadlineAt !== undefined && (!Number.isSafeInteger(input.deadlineAt) || input.deadlineAt <= Date.now())) {
+        throw new AppError("delivery_execution_invalid", "The original procedure deadline has expired", 2, { effect: "no_effect" });
+    }
+    const assertCurrent = () => {
+        const value = input.assertCurrent();
+        if (types.isPromise(value)) {
+            void value.catch(() => { });
+            throw new AppError("delivery_execution_invalid", "Delivery owner fences must complete synchronously", 2, { effect: "no_effect" });
+        }
+    };
+    try {
+        assertCurrent();
+    }
+    catch {
+        throw new AppError("delivery_execution_invalid", "Delivery owner fence refused before process allocation", 2, { effect: "no_effect" });
+    }
+    let record = registerManagedProcess(context, { kind: "delivery", ownerId: input.operationId, projectId: input.projectId,
+        runId: input.runId, operationId: `${input.operationId}:${input.stepId}`, ownerPid: process.pid, uniqueActiveOperation: true });
+    const lease = managedLeaseMonitor(attemptMs => renewManagedProcess({ ...context, databaseDeadlineAt: Date.now() + attemptMs }, { id: record.id, leaseToken: record.lease_token }), record.lease_expires_at);
+    let admitted = false, completed = false, settled = false, frame, outputSize = 0, publicBytes = 0, publicText = "";
+    const chunks = [];
+    const internalFailures = new WeakSet();
+    let interrupt;
+    const interrupted = new Promise((_resolve, reject) => { interrupt = reject; });
+    void interrupted.catch(() => { });
+    const failure = (reason) => {
+        const error = new AppError("delivery_execution_failed", "Delivery command requires original-operation reconciliation", 1, { reason, process_id: record.id, operation_id: input.operationId, step_id: input.stepId,
+            effect: admitted && procedure.side_effect === "mutation" && !(settled && frame?.started === false && frame.error === "spawn_failed") ? "unknown" : "no_effect" });
+        internalFailures.add(error);
+        return error;
+    };
+    let ready;
+    const readiness = new Promise(resolve => { ready = resolve; });
+    const child = spawn(process.execPath, [fileURLToPath(new URL("../harness-runtime/lib/delivery-command.mjs", import.meta.url))], { cwd: input.workspace, env: {}, detached: process.platform !== "win32", windowsHide: true, stdio: ["pipe", "pipe", "pipe", "pipe", "pipe"] });
+    child.once("error", () => interrupt(failure("wrapper_spawn_failed")));
+    const closed = new Promise(resolve => child.once("close", () => { if (!completed)
+        interrupt(failure("wrapper_closed_before_result")); resolve(); }));
+    for (const stream of child.stdio)
+        stream?.on("error", () => interrupt(failure("transport_unavailable")));
+    child.stderr.resume();
+    child.stdout.on("data", bytes => {
+        publicBytes += bytes.length;
+        if (publicBytes > 8192) {
+            interrupt(failure("unbounded_transport_frame"));
+            return;
+        }
+        publicText += bytes.toString("utf8");
+        while (publicText.includes("\n")) {
+            const end = publicText.indexOf("\n"), line = publicText.slice(0, end);
+            publicText = publicText.slice(end + 1);
+            try {
+                const value = JSON.parse(line);
+                if (value.operation_id !== input.operationId || value.step_id !== input.stepId)
+                    throw new Error();
+                if (value.schema_id === "dd-flow/delivery-command-ready@1" && !admitted && !completed)
+                    ready();
+                else if (value.schema_id === "dd-flow/delivery-command-result@1" && !completed) {
+                    frame = value;
+                    completed = true;
+                }
+                else
+                    throw new Error();
+            }
+            catch {
+                interrupt(failure("invalid_transport_frame"));
+            }
+        }
+    });
+    child.stdio[4].on("data", (bytes) => {
+        outputSize += bytes.length;
+        if (outputSize > 1024 * 1024) {
+            interrupt(failure("unbounded_private_output"));
+            return;
+        }
+        chunks.push(Buffer.from(bytes));
+    });
+    const deadline = Math.min(Date.now() + procedure.timeout_ms, input.deadlineAt ?? Infinity);
+    const timeout = setTimeout(() => interrupt(failure("timeout")), Math.max(1, deadline - Date.now()));
+    const heartbeat = setInterval(() => lease.background(assertCurrent, () => interrupt(failure("owner_unconfirmed"))), 5000);
+    let terminalError;
+    try {
+        child.stdio[3].end(JSON.stringify({ schema_id: "dd-flow/delivery-command@1", operation_id: input.operationId,
+            step_id: input.stepId, argv: step.argv, permitted_environment_variables: procedure.permitted_environment_variables,
+            environment: Object.fromEntries(procedure.permitted_environment_variables.filter(name => context.env[name] !== undefined).map(name => [name, context.env[name]])) }));
+        await Promise.race([readiness, interrupted]);
+        record = await physicalStartup(Math.min(deadline, context.databaseDeadlineAt ?? deadline)).observe(() => confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid: child.pid,
+            ...(process.platform === "win32" ? {} : { processGroupId: child.pid }), ownerPid: process.pid }), () => { assertCurrent(); if (child.exitCode !== null || child.signalCode !== null)
+            throw failure("wrapper_closed_before_result"); }, record.lease_expires_at);
+        await Promise.race([lease.ensureConfirmed(assertCurrent), interrupted]);
+        assertCurrent();
+        assertManagedProcessLease(context, { id: record.id, leaseToken: record.lease_token, pid: child.pid });
+        const admission = input.admit(record);
+        if (types.isPromise(admission)) {
+            void admission.catch(() => { });
+            throw failure("asynchronous_admission_refused");
+        }
+        lease.assertNoRenewal();
+        assertCurrent();
+        if (Date.now() >= deadline)
+            throw failure("timeout");
+        admitted = true;
+        child.stdin.end("admitted\n");
+        await Promise.race([closed, interrupted]);
+        if (frame?.admitted === true && frame.started === false && frame.error === "spawn_failed")
+            throw failure("command_spawn_failed");
+        if (!frame || frame.admitted !== true || frame.started !== true || frame.error !== null || frame.exit_code !== 0
+            || frame.signal !== null || frame.output_available !== true || frame.stdout_truncated !== false)
+            throw failure("command_unsuccessful");
+    }
+    catch (error) {
+        terminalError = error;
+    }
+    finally {
+        clearTimeout(timeout);
+        clearInterval(heartbeat);
+        lease.close();
+        try {
+            await stopProcessGroup(child, 1000, { detached: process.platform !== "win32" });
+            if (processTreeIsAlive(record))
+                terminalError = failure("process_tree_unsettled");
+            else if (!finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: "stopped",
+                reason: terminalError ? "delivery_command_failed" : "delivery_command_exited" }))
+                terminalError = failure("process_owner_changed");
+            else
+                settled = true;
+        }
+        catch {
+            terminalError = failure("process_tree_unsettled");
+        }
+    }
+    if (terminalError) {
+        chunks.length = 0;
+        throw failure(terminalError instanceof AppError && internalFailures.has(terminalError)
+            ? String(terminalError.details.reason) : "owner_or_execution_failed");
+    }
+    try {
+        assertCurrent();
+    }
+    catch {
+        chunks.length = 0;
+        throw failure("owner_or_execution_failed");
+    }
+    const bytes = Buffer.concat(chunks);
+    chunks.length = 0;
+    try {
+        const projection = input.consumeOutput(bytes);
+        if (types.isPromise(projection)) {
+            void projection.catch(() => { });
+            throw failure("output_projection_failed");
+        }
+    }
+    catch {
+        throw failure("output_projection_failed");
+    }
+    finally {
+        bytes.fill(0);
+    }
+    return { process_id: record.id, operation_id: input.operationId, step_id: input.stepId, outcome: "command_succeeded",
+        // Exit zero is not publication/deployment readback or permission to repeat.
+        effect: procedure.side_effect === "mutation" ? "unknown" : "no_effect" };
+}

package/dist/services/delivery-intents.js

@@ -0,0 +1,212 @@
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareDeliveryApproval } from "./delivery-approval.js";
+import { resolveDeliveryBinding } from "./delivery-policy.js";
+import { PreparedDeliveryAccess } from "./delivery-access.js";
+import { PreparedDeliveryArtifact } from "./delivery-artifact.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { assertRunMutationAllowed, assertStageSettlementAllowed } from "./run-recovery-guard.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readActiveDescriptorStageCoordinator } from "./descriptor-stage-settlement.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { assertManagedProcessLease, managedProcessBinding, managedProcessStatus, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+const intentEvent = "delivery.operation_intent", progressEvent = "delivery.operation_event", anchor = '$.variables."delivery.operation"';
+function refuse(reason) {
+    throw new AppError("delivery_intent_invalid", "Delivery needs its original approved operation and active Stage owner", 2, { reason, effect: "no_effect" });
+}
+function pending(reason) {
+    throw new AppError("delivery_operation_pending", "Observe or reconcile the original delivery before another dispatch", 2, { reason, effect: "unknown", next_action: "reconcile_original_delivery" });
+}
+/** Original SQL operation custody; never infer 'not dispatched' from a lost
+ * log, editable file, new request ID, expired observer or terminal process. */
+export function readDeliveryIntent(context, scope) {
+    const run = context.db.get("SELECT json_extract(index_json,?) value FROM runs WHERE project_id=? AND id=?", [anchor, scope.projectId, scope.runId]);
+    if (!run)
+        refuse("bound_run_required");
+    const plans = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.plan.approval.scope.run_id')=? LIMIT 2", [scope.projectId, intentEvent, scope.runId]);
+    const events = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id LIMIT 34", [scope.projectId, progressEvent, scope.runId]);
+    if (plans.length > 1 || events.length > 33 || plans.some(row => Buffer.byteLength(row.payload_json) > 262144)
+        || events.some(row => Buffer.byteLength(row.payload_json) > 131072) || Boolean(plans.length) !== Boolean(run.value) || !plans.length && events.length)
+        pending("operation_custody_lost");
+    if (!plans.length)
+        return null;
+    let value, log, saved;
+    try {
+        value = JSON.parse(plans[0].payload_json);
+        log = events.map(row => JSON.parse(row.payload_json));
+        saved = JSON.parse(run.value);
+    }
+    catch {
+        return pending("operation_custody_invalid");
+    }
+    const plan = value.plan;
+    if (plan?.schema_id !== "dd-flow/delivery-intent@1" || plan.approval?.scope?.project_id !== scope.projectId
+        || plan.approval.scope.run_id !== scope.runId || value.identity !== hybridDigest(plan) || saved.identity !== value.identity
+        || !Array.isArray(plan.steps) || !plan.steps.length || plan.steps.length > 16
+        || plan.steps.some(step => typeof step !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(step)) || new Set(plan.steps).size !== plan.steps.length
+        || saved.count !== log.length)
+        pending("operation_custody_changed");
+    let head = value.identity, next = 0, failed = false, open = null;
+    for (const entry of log) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry) || failed || entry.run_id !== scope.runId
+            || entry.identity !== value.identity || entry.previous !== head || entry.step_id !== plan.steps[next])
+            pending("operation_event_changed");
+        if (entry.kind === "admitted" && !open && entry.process && typeof entry.process.resource_home === "string"
+            && typeof entry.process.process_id === "string" && /^[a-f0-9]{64}$/.test(entry.process.registration_sha256)
+            && entry.access?.schema_id === "dd-flow/delivery-access@1" && entry.access.operation_id === plan.approval.scope.operation_id
+            && entry.access.binding_id === plan.approval.scope.binding_id)
+            open = entry;
+        else if (entry.kind === "command_result" && open && entry.result && entry.result.process_id === open.process.process_id
+            && entry.result.operation_id === plan.approval.scope.operation_id && entry.result.step_id === entry.step_id
+            && ["command_succeeded", "failed"].includes(entry.result.outcome) && ["no_effect", "unknown"].includes(entry.result.effect)) {
+            // A failed or uncertain command is never permission to run a later step.
+            if (entry.result.outcome === "command_succeeded") {
+                next++;
+                open = null;
+            }
+            else
+                failed = true;
+        }
+        else
+            pending("operation_event_order_invalid");
+        head = hybridDigest(entry);
+    }
+    if (head !== saved.head)
+        pending("operation_anchor_changed");
+    return { ...value, events: log, head, next, open, failed };
+}
+/** Original intent/admission owner, not an executor. The Stage independently
+ * verifies manifest references and project procedure safety. No public route yet. */
+export function prepareDeliveryIntent(context, scope, bundle, raw, proposal) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const binding = resolveDeliveryBinding({ schema_id: "dd-flow/delivery-policy@1", bindings: [raw.binding] }, raw.binding.selector);
+    if (binding.procedures.execute.side_effect !== "mutation")
+        refuse("protected_mutation_required");
+    const selection = { ...raw, binding }, approval = prepareDeliveryApproval(context, scope, bundle, selection, proposal), grant = approval.value();
+    const artifact = PreparedDeliveryArtifact.prepare(bundle.execution.snapshot().scope.workspace, raw.artifactPath, selection.artifact);
+    const stage = grant.scope.flow_id === "deploy" ? "deploy" : "publish", previous = stage === "deploy" ? "prepare" : "verify";
+    const predecessor = readAcceptedStageData(context, { ...scope, stage: previous });
+    let data;
+    try {
+        data = JSON.parse(predecessor.bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("accepted_selection_required");
+    }
+    if (data.details?.delivery_scope_sha256 !== grant.scope_sha256)
+        refuse("accepted_selection_required");
+    const generation = assertRunMutationAllowed(context, scope.projectId, scope.runId);
+    const authority = (writer) => {
+        assertRunMutationAllowed(writer, scope.projectId, scope.runId, generation);
+        const run = assertPreparedRunBundleSqlAuthority(writer, scope, bundle), index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== stage
+            || !index.stage_runs?.some((item) => item.stage === stage && item.status === "running"))
+            refuse("active_delivery_stage_required");
+        const packet = readDescriptorStageInput(writer, { ...scope, stage }, bundle), actor = readActiveDescriptorStageCoordinator(writer, { ...scope, stage }, bundle);
+        if (packet.input.predecessor?.stage !== previous || hybridDigest(packet.input.predecessor.result) !== hybridDigest(predecessor.result))
+            refuse("accepted_predecessor_changed");
+        if (writer.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, actor.work_id]))
+            refuse("active_child_work");
+        return { packet, actor };
+    };
+    const owner = authority(context), original = readDeliveryIntent(context, scope);
+    const proposed = { schema_id: "dd-flow/delivery-intent@1", approval: grant, artifact: artifact.value(), predecessor: { stage: previous, result: predecessor.result },
+        steps: binding.procedures.execute.procedure_steps.map(step => step.id) };
+    // Retain the first human-readable interpretation rather than requiring a
+    // future observer to reproduce its wording. Scope, basis, inputs and expiry
+    // remain exact; neither commentary nor a fresh timestamp renews permission.
+    const semantic = (plan) => ({ ...plan, approval: { ...plan.approval, approved_at: null, interpretation: null } });
+    if (original && hybridDigest(semantic(original.plan)) !== hybridDigest(semantic(proposed)))
+        pending("original_operation_scope_changed");
+    const plan = original?.plan ?? proposed, identity = hybridDigest(plan), accessScope = {
+        projectId: scope.projectId, runId: scope.runId, operationId: selection.operationId, workspace: bundle.execution.snapshot().scope.workspace, binding
+    };
+    const assertCustody = (writer) => {
+        approval.assertCustody(writer);
+        if (hybridDigest(authority(writer)) !== hybridDigest(owner))
+            refuse("delivery_owner_changed");
+        const current = readDeliveryIntent(writer, scope);
+        if (current && current.identity !== identity)
+            pending("original_operation_changed");
+        return current;
+    };
+    const settlementCustody = (writer) => {
+        // Expiry/revocation forbids new effects, not recording what an already
+        // admitted command actually did. Ordinary Stage/control fences still own
+        // the allowed generation and cooperative settlement window.
+        assertStageSettlementAllowed(writer, scope.projectId, scope.runId, stage, generation);
+        assertPreparedRunBundleSqlAuthority(writer, scope, bundle);
+        const current = readDeliveryIntent(writer, scope);
+        if (!current || current.identity !== identity)
+            pending("original_operation_changed");
+        return current;
+    };
+    const assertArtifact = (writer) => {
+        if (writer.db.isOwnedWriteTransaction?.())
+            refuse("artifact_observation_outside_writer_required");
+        artifact.assertCurrent();
+    };
+    const retain = (writer) => {
+        assertArtifact(writer);
+        return writer.db.writeTransaction(() => {
+            const current = assertCustody(writer);
+            if (current)
+                return current;
+            appendAudit(writer, { projectId: scope.projectId, eventType: intentEvent, payload: { identity, plan } });
+            writer.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchor, JSON.stringify({ identity, count: 0, head: identity }), scope.projectId, scope.runId]);
+            return readDeliveryIntent(writer, scope);
+        });
+    };
+    return { value: () => structuredClone(plan), assertCustody, retain,
+        admitStep(writer, stepId, process, access) {
+            if (!(access instanceof PreparedDeliveryAccess))
+                refuse("owned_access_observation_required");
+            assertArtifact(writer);
+            return writer.db.writeTransaction(() => {
+                const current = assertCustody(writer);
+                if (!current)
+                    refuse("retained_intent_required");
+                if (current.open || current.plan.steps[current.next] !== stepId)
+                    pending("original_step_already_admitted_or_out_of_order");
+                if (process.kind !== "delivery" || process.project_id !== scope.projectId || process.run_id !== scope.runId
+                    || process.owner_id !== selection.operationId || process.operation_id !== `${selection.operationId}:${stepId}` || !process.pid)
+                    refuse("selected_process_required");
+                assertManagedProcessLease(writer, { id: process.id, leaseToken: process.lease_token, pid: process.pid });
+                access.consume(writer, accessScope);
+                const entry = { run_id: scope.runId, identity, previous: current.head, kind: "admitted", step_id: stepId,
+                    process: managedProcessBinding(process, resourceHome(writer)), access: access.value() };
+                appendAudit(writer, { projectId: scope.projectId, eventType: progressEvent, payload: entry });
+                writer.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchor,
+                    JSON.stringify({ identity, count: current.events.length + 1, head: hybridDigest(entry) }), scope.projectId, scope.runId]);
+            });
+        },
+        recordCommand(writer, result) {
+            if (writer.db.isOwnedWriteTransaction?.())
+                refuse("physical_observation_outside_writer_required");
+            const before = settlementCustody(writer), admitted = before.open;
+            if (before.failed || !admitted || result.step_id !== admitted.step_id || result.process_id !== admitted.process.process_id
+                || result.operation_id !== selection.operationId || !["command_succeeded", "failed"].includes(result.outcome)
+                || !["no_effect", "unknown"].includes(result.effect))
+                pending("original_command_result_required");
+            if (admitted.process.resource_home !== resourceHome(writer))
+                pending("original_resource_home_required");
+            const process = managedProcessStatus(writer).find(item => item.id === result.process_id);
+            if (!process || managedProcessBinding(process, resourceHome(writer)).registration_sha256 !== admitted.process.registration_sha256
+                || process.state !== "stopped" || processTreeIsAlive(process))
+                pending("original_process_not_settled");
+            return writer.db.writeTransaction(() => {
+                const current = settlementCustody(writer);
+                if (!current || current.head !== before.head)
+                    pending("operation_changed_before_result");
+                const entry = { run_id: scope.runId, identity, previous: current.head, kind: "command_result", step_id: result.step_id,
+                    result: { process_id: result.process_id, operation_id: result.operation_id, step_id: result.step_id, outcome: result.outcome, effect: result.effect } };
+                appendAudit(writer, { projectId: scope.projectId, eventType: progressEvent, payload: entry });
+                writer.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchor,
+                    JSON.stringify({ identity, count: current.events.length + 1, head: hybridDigest(entry) }), scope.projectId, scope.runId]);
+                return readDeliveryIntent(writer, scope);
+            });
+        }
+    };
+}