@deksden-com/dd-flow-cli 0.9.0-beta.152 → 0.9.0-beta.156

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

package/dist/services/delivery-operation.js

@@ -0,0 +1,81 @@
+import { AppError } from "../shared/errors.js";
+import { readDeliveryStageScope } from "./delivery-stage-entry.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { readActiveDescriptorStageCoordinator } from "./descriptor-stage-settlement.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { prepareDeliveryProjectBinding } from "./delivery-policy.js";
+import { prepareDeliveryIntent, readDeliveryIntent } from "./delivery-intents.js";
+import { PreparedDeliveryAccess } from "./delivery-access.js";
+import { executeDeliveryStep } from "./delivery-execution.js";
+import { observeDeliveryResult } from "./delivery-result.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareDeliveryCurrentAcceptedChecks } from "./delivery-checks.js";
+function pending(reason) {
+    throw new AppError("delivery_operation_pending", "Reconcile the original delivery before another dispatch", 2, { reason, effect: "unknown", next_action: "reconcile_original_delivery" });
+}
+/** Internal protected operation composition. No Stage/RUN completion, login,
+ * provider SDK, ambient shell, fallback account or automatic mutation retry.
+ * Startup is not approval: the proposal cites an exact delivered user input. */
+export async function executeDeliveryOperation(context, input) {
+    const selected = readDeliveryStageScope(context, input), { scope, bundle, flowId } = selected;
+    const mutation = flowId === "deploy" ? "deploy" : "publish";
+    if (input.stage !== mutation || context.db.isOwnedWriteTransaction?.())
+        throw new AppError("delivery_stage_invalid", "Protected execution requires its active delivery Stage", 2, { effect: "no_effect" });
+    const prior = readAcceptedStageData(context, { ...scope, stage: flowId === "deploy" ? "prepare" : "verify" });
+    const details = JSON.parse(prior.bytes.toString("utf8")).details;
+    const { decision, artifact } = details;
+    if (!decision || !artifact)
+        throw new AppError("delivery_stage_invalid", "Accepted delivery selection is required", 2, { effect: "no_effect" });
+    const workspace = bundle.execution.snapshot().scope.workspace;
+    const policy = prepareDeliveryProjectBinding(workspace, decision.policy, decision.binding.selector);
+    if (hybridDigest(policy.binding) !== hybridDigest(decision.binding))
+        throw new AppError("delivery_stage_invalid", "Accepted delivery policy changed", 2, { effect: "no_effect" });
+    const operation = { operationId: decision.operation_id, binding: policy.binding, artifactPath: artifact.path,
+        artifact: { subject_ref: artifact.subject_ref, version: artifact.version, sha256: artifact.sha256 } };
+    const intent = prepareDeliveryIntent(context, scope, bundle, operation, input.approval);
+    const checks = prepareDeliveryCurrentAcceptedChecks(context, { ...input, sourceStage: flowId === "deploy" ? "prepare" : "verify",
+        operationScopeSha256: hybridDigest(intent.value().approval.scope) });
+    checks.revalidate();
+    intent.retain(context);
+    const owner = readActiveDescriptorStageCoordinator(context, scope, bundle);
+    const assertOwner = () => {
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        if (hybridDigest(readActiveDescriptorStageCoordinator(context, scope, bundle)) !== hybridDigest(owner))
+            pending("delivery_owner_changed");
+        policy.assertCurrent();
+    };
+    const assertCurrent = () => { assertOwner(); selected.assertCustody(context); intent.assertCustody(context); checks.assertCustody(context); };
+    const retained = readDeliveryIntent(context, scope);
+    if (retained.open || retained.failed)
+        pending("original_step_requires_reconciliation");
+    const procedure = policy.binding.procedures.execute, deadline = Date.now() + procedure.timeout_ms;
+    for (const step of procedure.procedure_steps.slice(retained.next)) {
+        assertCurrent();
+        checks.revalidate();
+        const access = await PreparedDeliveryAccess.observe(context, { ...scope, operationId: operation.operationId, workspace,
+            binding: policy.binding, assertCurrent });
+        checks.revalidate();
+        let result;
+        try {
+            result = await executeDeliveryStep(context, { ...scope, operationId: operation.operationId, workspace, stepId: step.id,
+                procedure, deadlineAt: deadline, assertCurrent,
+                admit(process) { checks.revalidate(); selected.assertCustody(context); checks.assertCustody(context); intent.admitStep(context, step.id, process, access); }, consumeOutput() { } });
+        }
+        catch (error) {
+            // Record only the executor's original admitted and physically settled
+            // process. An admission refusal must not invent a failed effect event.
+            const current = readDeliveryIntent(context, scope);
+            if (current?.open && error instanceof AppError && current.open.process.process_id === error.details.process_id) {
+                intent.recordCommand(context, { process_id: current.open.process.process_id, operation_id: operation.operationId,
+                    step_id: step.id, outcome: "failed", effect: error.details.effect === "no_effect" ? "no_effect" : "unknown" });
+            }
+            throw error;
+        }
+        intent.recordCommand(context, result);
+    }
+    // Expiry or later revocation forbids new mutation, not honest observation of
+    // an already admitted effect. Preserve Stage ownership and original policy.
+    const readback = await observeDeliveryResult(context, { ...scope, binding: policy.binding, assertCurrent: assertOwner });
+    return { operation_id: operation.operationId, intent_sha256: hybridDigest(intent.value()),
+        readback_sha256: hybridDigest(readback), status: readback.observation.status, rollback: readback.observation.rollback ?? null };
+}

package/dist/services/delivery-policy.js

@@ -0,0 +1,91 @@
+import { AppError } from "../shared/errors.js";
+import { prepareDeliveryProcedure } from "./delivery-procedures.js";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { PreparedDeliveryArtifact } from "./delivery-artifact.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+const selectorKeys = ["operation", "profile_id", "subject_ref", "provider", "host", "target", "stage"];
+const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && value.trim().length > 0 && value.length <= 4096 && !value.includes("\0");
+const keys = (value, allowed) => Object.keys(value).length === allowed.length && allowed.every(key => Object.hasOwn(value, key));
+function refuse(reason) {
+    throw new AppError("delivery_policy_invalid", "Delivery requires one exact project-owned operation binding", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason });
+}
+function selector(value) {
+    if (!record(value) || !keys(value, selectorKeys) || !selectorKeys.every(key => text(value[key]))
+        || !["release", "deploy", "publish"].includes(value.operation))
+        refuse("invalid_selector");
+    return Object.fromEntries(selectorKeys.map(key => [key, value[key]]));
+}
+function publicId(value) {
+    if (!record(value) || !keys(value, ["kind", "id"]) || !text(value.kind) || !text(value.id))
+        refuse("invalid_public_identifier");
+    return { kind: value.kind, id: value.id };
+}
+function access(value) {
+    if (!record(value))
+        refuse("invalid_access_policy");
+    if (value.applicability === "not_required") {
+        if (!keys(value, ["applicability", "reason"]) || !text(value.reason))
+            refuse("not_required_needs_policy_reason");
+        return { applicability: "not_required", reason: value.reason };
+    }
+    if (value.applicability !== "required" || !keys(value, ["applicability", "identity", "authority", "target"]))
+        refuse("invalid_access_policy");
+    return { applicability: "required", identity: publicId(value.identity),
+        authority: value.authority === "not_required" ? "not_required" : publicId(value.authority), target: publicId(value.target) };
+}
+function binding(value) {
+    if (!record(value) || !keys(value, ["id", "selector", "access", "procedures"])
+        || typeof value.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(value.id)
+        || !record(value.procedures) || !keys(value.procedures, ["access_readback", "execute", "result_readback"]))
+        refuse("invalid_binding");
+    const selectedAccess = access(value.access), procedures = value.procedures;
+    if (selectedAccess.applicability === "not_required" && procedures.access_readback !== null
+        || selectedAccess.applicability === "required" && procedures.access_readback === null)
+        refuse("access_readback_mismatch");
+    return { id: value.id, selector: selector(value.selector), access: selectedAccess, procedures: {
+            access_readback: procedures.access_readback === null ? null : prepareDeliveryProcedure(procedures.access_readback, "readback"),
+            execute: prepareDeliveryProcedure(procedures.execute, "execute"),
+            result_readback: prepareDeliveryProcedure(procedures.result_readback, "readback")
+        } };
+}
+/** Exact data resolution, not operation permission. The owning flow must bind
+ * these project-policy bytes to its frozen decision, independently run safe
+ * access readback and check separate current approval for the exact artifact,
+ * version, RUN/request and target. Never infer account access from this match. */
+export function resolveDeliveryBinding(policy, selected) {
+    const requested = selector(selected);
+    if (!record(policy) || !keys(policy, ["schema_id", "bindings"]) || policy.schema_id !== "dd-flow/delivery-policy@1"
+        || !Array.isArray(policy.bindings) || policy.bindings.length > 256)
+        refuse("invalid_policy");
+    const bindings = policy.bindings.map(binding);
+    if (new Set(bindings.map(item => item.id)).size !== bindings.length)
+        refuse("duplicate_binding_id");
+    const matches = bindings.filter(item => selectorKeys.every(key => item.selector[key] === requested[key]));
+    if (!matches.length)
+        refuse("no_exact_binding");
+    if (matches.length !== 1)
+        refuse("ambiguous_binding");
+    return matches[0];
+}
+/** Observe a selected project file, not a binding invented in an agent result.
+ * Revalidation stays outside SQL writers; no provider command runs here. */
+export function prepareDeliveryProjectBinding(workspace, reference, selected) {
+    if (!reference || typeof reference.path !== "string" || path.isAbsolute(reference.path))
+        refuse("project_policy_relative_path_required");
+    const file = PreparedDeliveryArtifact.prepare(workspace, reference.path, { subject_ref: "delivery-policy", version: "1", sha256: reference.sha256 });
+    const bytes = readBoundedReleaseFile(path.join(workspace, reference.path), 1024 * 1024);
+    if (createHash("sha256").update(bytes).digest("hex") !== reference.sha256)
+        refuse("project_policy_changed");
+    let policy;
+    try {
+        policy = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_project_policy");
+    }
+    const binding = resolveDeliveryBinding(policy, selected);
+    file.assertCurrent();
+    return { binding, assertCurrent: () => file.assertCurrent() };
+}

package/dist/services/delivery-procedures.js

@@ -0,0 +1,43 @@
+import { AppError } from "../shared/errors.js";
+const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && value.length > 0 && value.length <= 16384 && !value.includes("\0");
+const identifier = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(value);
+function refuse(reason) {
+    throw new AppError("delivery_procedure_invalid", "Delivery requires an exact project-owned noninteractive procedure", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason });
+}
+function step(value, effect) {
+    if (!record(value) || Object.keys(value).some(key => !["id", "argv", "side_effect", "noninteractive"].includes(key))
+        || !identifier(value.id) || value.side_effect !== effect || value.noninteractive !== true
+        || !Array.isArray(value.argv) || !value.argv.length || value.argv.length > 128 || !value.argv.every(text))
+        refuse("invalid_step");
+    return { id: value.id, argv: [...value.argv], side_effect: effect, noninteractive: true };
+}
+/** Prepare policy data only: no process, environment lookup, permission or
+ * provider-safety proof. Callers must bind reviewed project policy and separate
+ * operation approval before execution. Pass each argv directly with shell:false;
+ * never concatenate steps into shell text or persist authenticated raw output. */
+export function prepareDeliveryProcedure(value, purpose) {
+    if (!record(value) || Object.keys(value).some(key => !["id", "argv", "procedure_steps", "side_effect", "noninteractive", "timeout_ms", "permitted_environment_variables"].includes(key))
+        || !identifier(value.id) || value.side_effect !== "read_only" && value.side_effect !== "mutation" || value.noninteractive !== true
+        || !Number.isSafeInteger(value.timeout_ms) || value.timeout_ms < 1 || value.timeout_ms > 1800000
+        || !Array.isArray(value.permitted_environment_variables) || value.permitted_environment_variables.length > 128
+        || !value.permitted_environment_variables.every(name => typeof name === "string" && /^[A-Z_][A-Z0-9_]*$/.test(name))
+        || new Set(value.permitted_environment_variables).size !== value.permitted_environment_variables.length
+        || Object.hasOwn(value, "argv") === Object.hasOwn(value, "procedure_steps"))
+        refuse("invalid_procedure");
+    if (purpose !== "readback" && purpose !== "execute")
+        refuse("invalid_purpose");
+    const effect = value.side_effect;
+    if (purpose === "readback" && effect !== "read_only")
+        refuse("readback_must_be_read_only");
+    const steps = Object.hasOwn(value, "argv")
+        ? [step({ id: value.id, argv: value.argv, side_effect: effect, noninteractive: true }, effect)]
+        : value.procedure_steps;
+    if (!Array.isArray(steps) || !steps.length || steps.length > 16)
+        refuse("invalid_steps");
+    const prepared = steps.map(item => step(item, effect));
+    if (new Set(prepared.map(item => item.id)).size !== prepared.length)
+        refuse("duplicate_step");
+    return { id: value.id, side_effect: effect, noninteractive: true, timeout_ms: value.timeout_ms,
+        permitted_environment_variables: [...value.permitted_environment_variables], procedure_steps: prepared };
+}