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

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

package/dist/services/delivery-request.js

@@ -0,0 +1,99 @@
+import { AppError } from "../shared/errors.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readRunStartRequest, runStartPayloadLimit } from "./run-start-custody.js";
+import { PreparedDescriptorRunStart } from "./descriptor-run-start.js";
+import { prepareDeliveryRunBundle } from "./diagnostic-run-bundle.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const event = "delivery.request";
+function refuse(reason) {
+    throw new AppError("delivery_request_invalid", "Delivery requires its original request, workspace and frozen selection", 2, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+/** SQL/data only: retries never consult a newer operator selection. */
+export function readDeliveryRequest(context, scope) {
+    if (!isDeliveryFlow(scope.flowId) || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId))
+        refuse("invalid_scope");
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.scope.requestId')=? LIMIT 2", [project.id, event, scope.requestId]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > runStartPayloadLimit)
+        refuse("ambiguous_request");
+    const value = JSON.parse(rows[0].payload_json);
+    if (value.schema_id !== "dd-flow/delivery-request@1" || value.project_id !== project.id
+        || hybridDigest(value.scope) !== hybridDigest(scope) || !Number.isFinite(Date.parse(value.created_at))
+        || typeof value.objective !== "string" || !value.objective.trim() || Buffer.byteLength(value.objective) > 64 * 1024
+        || !value.execution || hybridDigest(value.execution) !== value.execution_sha256)
+        refuse("request_changed");
+    return value;
+}
+export function retainDeliveryRequest(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("prepare_outside_writer");
+    if (!(input.source instanceof PreparedInstalledFlowSource) || !(input.execution instanceof FrozenGenericExecution)
+        || !(input.engine instanceof AdmittedFrozenEngine) || !isDeliveryFlow(input.scope.flowId))
+        refuse("prepared_selection_required");
+    const frozen = input.execution.snapshot(), flow = input.source.resolveRegisteredFlow(), project = requireProjectByRoot(context, input.scope.projectRoot);
+    if (frozen.scope.projectRoot !== input.scope.projectRoot || frozen.scope.requestId !== input.scope.requestId
+        || frozen.settings.flow_id !== input.scope.flowId || flow.descriptor.id !== input.scope.flowId
+        || frozen.settings.descriptor_sha256 !== flow.sha256 || frozen.settings.stage_session_mode === "same_session"
+        || frozen.settings.attached_session_receipt || frozen.settings.delegation.native_capacity_receipt
+        || !input.objective.trim() || Buffer.byteLength(input.objective) > 64 * 1024)
+        refuse("selection_changed");
+    input.source.revalidate();
+    input.engine.admitDeliveryFlow(input.source, input.scope.flowId);
+    const manifest = input.engine.manifest(), checksum = manifest.integrity.checksum;
+    if (typeof checksum !== "string")
+        refuse("engine_identity_required");
+    const value = { schema_id: "dd-flow/delivery-request@1", project_id: project.id, scope: structuredClone(input.scope),
+        created_at: context.now(), objective: input.objective, selection: structuredClone(input.selection),
+        source: input.source.snapshot(), source_sha256: input.source.sha256, execution: frozen, execution_sha256: input.execution.sha256,
+        engine: { identity: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+                integrity_checksum: checksum, snapshot_root: manifest.snapshot_root }, manifest_sha256: input.engine.manifestSha256 } };
+    if (Buffer.byteLength(JSON.stringify(value)) > runStartPayloadLimit)
+        refuse("request_exceeds_bound");
+    return context.db.writeTransaction(() => {
+        const prior = readDeliveryRequest(context, input.scope);
+        if (prior) {
+            if (hybridDigest({ ...value, created_at: prior.created_at }) !== hybridDigest(prior))
+                refuse("request_conflict");
+            return prior;
+        }
+        if (readRunStartRequest(context, project.id, input.scope.requestId))
+            refuse("foreign_run_request");
+        appendAudit(context, { projectId: project.id, eventType: event, payload: value });
+        return value;
+    });
+}
+/** Called inside the common RUN allocation writer: retained data only. */
+export function assertDeliveryRequestBundle(context, projectId, bundle) {
+    const frozen = bundle.execution.snapshot(), flowId = bundle.manifest.flow_id;
+    if (!isDeliveryFlow(flowId))
+        refuse("delivery_bundle_required");
+    const request = readDeliveryRequest(context, { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, flowId });
+    if (!request || request.project_id !== projectId || request.execution_sha256 !== bundle.execution.sha256
+        || request.source.descriptor.sha256 !== bundle.manifest.descriptor.sha256 || bundle.manifest.bootstrap_receipts.length
+        || request.engine.manifest_sha256 !== bundle.manifest.engine_manifest.sha256
+        || !bundle.blob("runtime/source-request.md").equals(Buffer.from(request.objective)))
+        refuse("original_request_bundle_required");
+    for (const item of request.source.blobs)
+        if (!bundle.blob(item.path).equals(Buffer.from(item.base64, "base64")))
+            refuse("source_bytes_changed");
+}
+export function startDeliveryRun(context, scope) {
+    const request = readDeliveryRequest(context, scope);
+    if (!request)
+        refuse("original_request_required");
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    if (readRunStartRequest(context, project.id, scope.requestId))
+        return PreparedDescriptorRunStart.restore(context, scope).apply(context);
+    const source = PreparedInstalledFlowSource.restoreRetained(request.source, request.source_sha256);
+    const execution = FrozenGenericExecution.restore(request.execution, request.execution_sha256, source.resolveRegisteredFlow(), request.execution.scope);
+    const engine = AdmittedFrozenEngine.admitSelection(request.engine.identity, request.engine.manifest_sha256);
+    const bundle = prepareDeliveryRunBundle(context, { source, execution, engine, boundAt: request.created_at, requestText: request.objective });
+    return PreparedDescriptorRunStart.prepare(context, { bundle }).apply(context);
+}

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