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

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

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