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

package/dist/services/controller-fanout.js

@@ -13,6 +13,7 @@ import { stageAttempt, stageWorkIds } from "./stage-work-graph.js";
 import { runtimeCommand } from "./runtime-command.js";
 import { promptDeliveryInstruction } from "./prompt-delivery.js";
 import { currentStageFinishCommand } from "./lifecycle-invocations.js";
+import { acceptedChildWork } from "./controller-result-authority.js";
 function semanticCompletionPrompt(stage, completed, command) {
     const task = stage === "plan-review"
         ? "Classify the reviewer findings, apply every accepted correction in the current PLAN-REVIEW Work, and write the authoritative review decision."
@@ -74,8 +75,11 @@ export async function nextControllerFanout(context, input) {
         const issues = reconciled.issues.filter(issue => !["child_check_in_progress", "child_capacity_pending"].includes(issue.code));
         if (issues.length)
             throw new AppError("fanout_reconciliation_required", "Native child outcome requires reconciliation, not replay", 1, { issues });
-        if (children.some(child => child.status === "running" || child.status === "unknown"))
-            return { kind: "wait", reason: "native_children_unsettled" };
+        const unsettled = children.filter(child => child.status === "running" || child.status === "unknown");
+        if (unsettled.length) {
+            const project = requireProjectByRoot(context, input.projectRoot);
+            return { kind: "wait", reason: unsettled.every(child => acceptedChildWork(context, { project_id: project.id, run_id: input.runId }, input.harness, input.sessionId, child.session_id)) ? "accepted_work_native_cleanup" : "native_children_unsettled" };
+        }
         fanout = getVnextFanoutStatus(context, input).orchestration;
     }
     if (input.dispatchFence && !fanout.works.failed)
@@ -155,7 +159,8 @@ export async function nextControllerFanout(context, input) {
             const work = choice.work;
             const row = context.db.get("SELECT payload_json,result_schema FROM works WHERE work_id=?", [work.work_id]);
             const payload = JSON.parse(row?.payload_json ?? "null");
-            if (payload?.kind === "memory-review" && row?.result_schema === "dd-flow/memory-review-work-result@1") {
+            if (payload?.kind === "memory-review" && row?.result_schema === "dd-flow/memory-review-work-result@1"
+                || payload?.kind === "interactive-review" && row?.result_schema === "dd-flow/interactive-work-result@1") {
                 const copy = prepareMemoryNativeReviewCopy(context, work.work_id, true);
                 return { ...work, start_command: `cd '${copy.root.replaceAll("'", "'\\''")}' && ${workStartCommand(context, assertWorkLaunchReady(context, work.work_id))}` };
             }
@@ -171,7 +176,7 @@ export async function nextControllerFanout(context, input) {
             if (!work.work_id || !work.start_command)
                 throw new AppError("fanout_contract_invalid", "Ready Work omits its trusted start command", 1);
         const totalWorks = fanout.works.created + fanout.works.running + fanout.works.completed + fanout.works.failed + fanout.works.cancelled;
-        return prompt("dispatch_work", renderDelegationInstructions({ harness: input.harness, stage: input.stage, capacity, works: wave, totalWorks, remainingWorks: fanout.works.created - wave.length }));
+        return { ...prompt("dispatch_work", renderDelegationInstructions({ harness: input.harness, stage: input.stage, capacity, works: wave, totalWorks, remainingWorks: fanout.works.created - wave.length })), work_ids: wave.map(work => work.work_id) };
     }
     if (fanout.works.running)
         return { kind: "wait", reason: "work_receipts_pending" };

package/dist/services/controller-memory-worker.js

@@ -6,7 +6,8 @@ import { launchExternalWork } from "./external-work-launch.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertControllerLeaseAllowed } from "./run-controller-process.js";
 import { assertManagedProcessLease } from "./managed-processes.js";
-import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
 if (!parentPort)
     throw new AppError("controller_memory_task_invalid", "Memory worker requires its controller thread", 1);
 const port = parentPort, cancellation = new AbortController();
@@ -18,9 +19,10 @@ let reply;
 try {
     context = createContext(env, "prepared_existing");
     const project = requireProjectByRoot(context, task.input.projectRoot);
-    const run = context.db.get("SELECT flow_kind FROM runs WHERE project_id=? AND id=?", [project.id, task.input.runId]);
-    if (!run || !["mb-init", "mb-upgrade"].includes(run.flow_kind) && !isDiagnosticFlow(run.flow_kind))
-        throw new AppError("controller_memory_task_invalid", "Worker requires the selected memory or diagnostic RUN", 1, { effect: "no_effect" });
+    const run = context.db.get("SELECT flow_kind,index_json FROM runs WHERE project_id=? AND id=?", [project.id, task.input.runId]);
+    const delivery = run && isDeliveryFlow(run.flow_kind) && JSON.parse(run.index_json).execution_bundle?.flow_id === run.flow_kind;
+    if (!run || !["mb-init", "mb-upgrade", "mb-fix", "interactive"].includes(run.flow_kind) && !isSourceSnapshotFlow(run.flow_kind) && !delivery)
+        throw new AppError("controller_memory_task_invalid", "Worker requires the selected memory, interactive, source-snapshot or bound delivery RUN", 1, { effect: "no_effect" });
     if (task.operation === "external") {
         const work = context.db.get("SELECT project_id,run_id FROM works WHERE work_id=?", [task.input.workId]);
         if (!work || work.project_id !== project.id || work.run_id !== task.input.runId)

package/dist/services/controller-result-authority.js

@@ -0,0 +1,122 @@
+import { nextAttempt } from "./runs.js";
+import { stageAttempt, stageCycle, stageWorkIds } from "./stage-work-graph.js";
+import { storageSessionId } from "./session-identity.js";
+import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+import { terminalProviderRecovery } from "../harness-runtime/lib/provider-overload-policy.mjs";
+import { getVnextFanoutStatus } from "./vnext-fanout.js";
+import { normalizeNativeChildren, nativeTreeReadiness } from "../harness-runtime/lib/native-children.mjs";
+/** Disappearance from a truncated child list is not retirement evidence. */
+export function acceptedChildrenRetired(expected, receipt, sessionId, operationId) {
+    const children = normalizeNativeChildren(receipt, sessionId);
+    const settledTree = nativeTreeReadiness(receipt, { sessionId, operationId }) === "ready"
+        && Array.isArray(receipt.tree_session_ids) ? receipt.tree_session_ids : [];
+    return expected.every(id => {
+        const child = children.find(item => item.session_id === id);
+        return Boolean(child && ["completed", "failed", "cancelled"].includes(child.status)) || settledTree.includes(id);
+    });
+}
+/** Typed transport/provider failures only; integrity/ownership errors never become notes. */
+export function lateNativeFailure(error, sessionId) {
+    const value = error;
+    return isObservationLoss(error) || isObservationLoss(value?.details?.cause)
+        || value?.code === "settlement_recovery_required" || terminalProviderRecovery(error, sessionId);
+}
+/** A technical pause is an engine-recorded boundary, never an operator label. */
+export function technicalDependencyControl(context, projectId, runId, controlId) {
+    if (!context.db.get("SELECT 1 FROM sqlite_schema WHERE name='run_controller_events'"))
+        return false;
+    return Boolean(context.db.get(`SELECT 1 FROM run_controller_events e JOIN run_controllers c ON c.controller_id=e.controller_id JOIN run_controls rc ON rc.project_id=c.project_id AND rc.run_id=c.run_id WHERE c.project_id=? AND c.run_id=? AND rc.control_id=? AND rc.action='pause' AND e.event_type='technical_dependency_paused' AND json_extract(e.data_json,'$.control_id')=rc.control_id AND json_extract(e.data_json,'$.schema_id')='dd-flow/controller-dependency@1'`, [projectId, runId, controlId]));
+}
+/** A technical pause may be resumed automatically only for its own accepted Work.
+ * This is a read-only predicate and is rechecked under the resume transaction. */
+export function acceptedTechnicalWorkControl(context, row, controlId) {
+    try {
+        const control = context.db.get("SELECT request_id,recovery_id,status,action FROM run_controls WHERE project_id=? AND run_id=? AND control_id=?", [row.project_id, row.run_id, controlId]);
+        if (!control || control.action !== "pause" || control.status !== "settled")
+            return false;
+        const guard = context.db.get("SELECT recovery_id,generation,status,capture_path FROM run_recovery_guards WHERE project_id=? AND run_id=? ORDER BY generation DESC LIMIT 1", [row.project_id, row.run_id]);
+        if (!guard || guard.recovery_id !== control.recovery_id || guard.status !== "sealed" || !guard.capture_path || guard.generation <= row.generation)
+            return false;
+        const events = context.db.all("SELECT data_json FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=?", [row.controller_id, controlId]);
+        if (events.length !== 1)
+            return false;
+        const event = JSON.parse(events[0].data_json);
+        if (event.schema_id !== "dd-flow/controller-dependency@1" || event.request_id !== control.request_id || event.generation !== row.generation || typeof event.source_operation_id !== "string")
+            return false;
+        const state = JSON.parse(row.state_json), session = state.current_session === null ? null : state.sessions?.[state.current_session];
+        if (!session?.id || !session.owner?.owner_id || event.state_dir !== session.state_dir)
+            return false;
+        const op = context.db.get("SELECT generation,status,input_json FROM run_controller_operations WHERE controller_id=? AND operation_id=?", [row.controller_id, event.source_operation_id]);
+        if (!op || op.generation !== row.generation || !["outcome_unknown", "completed"].includes(op.status))
+            return false;
+        const input = JSON.parse(op.input_json), expected = input.obligation;
+        if (input.owner !== session.owner.owner_id || input.state_dir !== session.state_dir || !Array.isArray(input.args) || input.args[0] !== "session" || input.args[1] !== "prompt" || input.args.indexOf("--session-id") < 0 || input.args[input.args.indexOf("--session-id") + 1] !== session.id || !expected || expected.action !== "work" || expected.stage !== state.stage || expected.generation !== row.generation || !Array.isArray(expected.work_ids) || !expected.work_ids.length || !Array.isArray(expected.work_session_ids))
+            return false;
+        const run = context.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+        const stage = run && JSON.parse(run.index_json).stage_runs.find(item => item.stage === expected.stage && (item.attempt ?? "try-001") === expected.attempt);
+        if (!run || !["running", "paused"].includes(run.status) || stage?.status !== "running" || !controllerObligationAccepted(context, row, expected))
+            return false;
+        const stageWorks = stageWorkIds(context, row.project_id, row.run_id, expected.stage);
+        return expected.work_ids.every(id => stageWorks.has(id) && Boolean(context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? AND status='completed'", [id])))
+            && expected.work_session_ids.every(id => Boolean(context.db.get(`SELECT 1 FROM work_sessions WHERE id=? AND status='completed' AND work_id IN (${expected.work_ids.map(() => "?").join(",")})`, [id, ...expected.work_ids])));
+    }
+    catch {
+        return false;
+    }
+}
+/** Persist this snapshot with the exact dispatch, never infer success from one arbitrary Work. */
+export function controllerObligation(context, row, stage, action, assignedWorkIds) {
+    const ids = [...stageWorkIds(context, row.project_id, row.run_id, stage)];
+    const works = ids.length ? context.db.all("SELECT work_id,status,parent_work_id FROM works WHERE project_id=? AND run_id=?", [row.project_id, row.run_id]).filter(work => ids.includes(work.work_id)) : [];
+    const targets = action === "work" ? works.filter(work => work.parent_work_id && ["created", "running"].includes(work.status) && (!assignedWorkIds || assignedWorkIds.includes(work.work_id))).map(work => work.work_id) : [];
+    const sessions = targets.length ? context.db.all("SELECT ws.id,ws.work_id FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND ws.status='running'", [row.project_id, row.run_id]).filter(session => targets.includes(session.work_id)).map(session => session.id) : [];
+    const run = context.db.get("SELECT index_json,project_root FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+    const previous = run ? JSON.parse(run.index_json).stage_runs.find(item => item.stage === stage) : undefined;
+    return { stage, attempt: action === "entry" ? nextAttempt(previous) : stageAttempt(context, row.project_id, row.run_id, stage), cycle: stageCycle(context, row.project_id, row.run_id, stage), action, work_ids: targets, work_session_ids: sessions, generation: row.generation, ...(action === "resume" && previous?.pause ? { pause_id: previous.pause.id } : {}), ...(action === "graph" ? { graph_before: ids.sort() } : {}) };
+}
+export function controllerObligationAccepted(context, row, expected) {
+    if (expected.generation !== row.generation)
+        return false;
+    const run = context.db.get("SELECT index_json,project_root FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+    if (!run)
+        return false;
+    const stages = JSON.parse(run.index_json).stage_runs;
+    const stage = [...stages].reverse().find(item => item.stage === expected.stage && (item.attempt ?? "try-001") === expected.attempt);
+    if (!stage || stageCycle(context, row.project_id, row.run_id, expected.stage) !== expected.cycle)
+        return false;
+    if (["done", "skipped"].includes(stage.status))
+        return true;
+    if (expected.action === "resume")
+        return Boolean(expected.pause_id && context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_resumed' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.pause_id')=?", [row.project_id, row.run_id, expected.stage, expected.pause_id]));
+    if (expected.action === "entry") {
+        // Entry-only is a boundary for fanout stages. A non-fanout entry Turn
+        // also owes semantic work: merely starting SPECIFY is not its result.
+        if (stage.status === "paused" && stage.pause)
+            return Boolean(context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id=? AND status='paused'", [row.project_id, row.run_id, stage.pause.work_id]));
+        if (stage.status !== "running")
+            return false;
+        try {
+            return Boolean(getVnextFanoutStatus(context, { projectRoot: run.project_root, runId: row.run_id, stage: expected.stage }).orchestration);
+        }
+        catch {
+            return false;
+        }
+    }
+    if (expected.action === "graph") {
+        const current = [...stageWorkIds(context, row.project_id, row.run_id, expected.stage)];
+        return Array.isArray(expected.graph_before) && current.length > expected.graph_before.length && expected.graph_before.every(id => current.includes(id));
+    }
+    if (expected.action !== "work" || !expected.work_ids.length)
+        return false;
+    return expected.work_ids.every(id => context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, id])?.status === "completed")
+        && expected.work_session_ids.every(id => context.db.get("SELECT status FROM work_sessions WHERE id=?", [id])?.status === "completed");
+}
+/** A native failure cannot revoke an accepted result; unknown association is not success. */
+export function acceptedChildWork(context, row, harness, parent, child) {
+    const links = context.db.all(`SELECT ws.work_id,ws.status,w.status AS work_status FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id WHERE w.project_id=? AND w.run_id=? AND ws.session_id=? AND s.parent_session_id=? ORDER BY ws.created_at DESC,ws.rowid DESC`, [row.project_id, row.run_id, storageSessionId({ harness_id: harness, session_id: child }), storageSessionId({ harness_id: harness, session_id: parent })]);
+    const current = new Map();
+    for (const link of links)
+        if (!current.has(link.work_id))
+            current.set(link.work_id, link);
+    return current.size > 0 && [...current.values()].every(link => link.status === "completed" && link.work_status === "completed");
+}

package/dist/services/dashboard.js

@@ -216,10 +216,11 @@ export function autoRefreshDashboards(context, input) {
     if (projectRecoveryGuarded(context, project.id))
         return { ok: true, skipped: true, reason: "run_recovery_guarded" };
     const configured = readProjectConfig(context, project.id);
-    // Automatic observation must not change a memory or diagnostic source baseline.
+    // Automatic observation must not change a memory/diagnostic baseline or
+    // invalidate accepted delivery checks by rewriting workspace projections.
     // Keep projections in Home; do not hide runtime-created paths in Git or
     // weaken source preservation by excluding user-owned .tasks directories.
-    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND flow_kind IN ('mb-init','mb-upgrade','mb-audit','project-review') AND (id=? OR status IN ('created','running','paused','waiting_for_user','blocked')) LIMIT 1", [project.id, input.runId ?? null]);
+    const initializing = context.db.get("SELECT 1 FROM runs WHERE project_id=? AND (flow_kind IN ('mb-init','mb-upgrade','mb-fix','mb-audit','project-review','review-fix','interactive') OR flow_kind='mb-distill' AND json_extract(index_json,'$.execution_bundle.flow_id')='mb-distill' OR flow_kind IN ('release','deploy','publish') AND json_extract(index_json,'$.execution_bundle.flow_id')=flow_kind) AND (id=? OR status IN ('created','running','paused','waiting_for_user','blocked')) LIMIT 1", [project.id, input.runId ?? null]);
     const config = initializing ? { ...configured, dashboard: { ...configured.dashboard,
             markdown_path: path.join(projectDashboardDir(context.ddFlowHome, project.id), "project-dashboard.md") } } : configured;
     if (!config.dashboard.auto_refresh) {
@@ -1307,6 +1308,7 @@ function normalizeFlowKind(flowKind) {
         "mb-upgrade",
         "mb-audit",
         "mb-fix",
+        "review-fix",
         "mb-distill",
         "mb-upgrade-review",
         "mb-sdlc-review",

package/dist/services/delivery-access.js

@@ -0,0 +1,123 @@
+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";
+const dimensions = ["identity", "authority", "target"];
+const freshnessMs = 30000;
+const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function refuse(reason) {
+    throw new AppError("delivery_access_required", "Delivery access is not established for the selected operation; do not login or change context automatically", 2, { reason, effect: "no_effect" });
+}
+function identity(context, input) {
+    return hybridDigest({ home: context.ddFlowHome, project_id: input.projectId, run_id: input.runId,
+        operation_id: input.operationId, workspace: input.workspace, binding: input.binding });
+}
+/** Private same-process observation, not serialized publication authority.
+ * The owning Stage still establishes project-policy/readback safety and checks
+ * separate scoped approval, artifact custody and retained operation intent. */
+export class PreparedDeliveryAccess {
+    #scope;
+    #pid = process.pid;
+    #expires;
+    #consumed = false;
+    #report;
+    constructor(context, input, observed, report) {
+        this.#scope = identity(context, input);
+        this.#expires = observed + freshnessMs;
+        this.#report = structuredClone(report);
+    }
+    static async observe(context, raw) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("observation_outside_writer_required");
+        const binding = resolveDeliveryBinding({ schema_id: "dd-flow/delivery-policy@1", bindings: [raw.binding] }, raw.binding.selector);
+        const input = { ...raw, binding }, times = new Map(), processes = [];
+        const assertCurrent = () => {
+            const result = raw.assertCurrent();
+            if (types.isPromise(result)) {
+                void result.catch(() => { });
+                refuse("synchronous_owner_fence_required");
+            }
+        };
+        assertCurrent();
+        if (binding.access.applicability === "required") {
+            const access = binding.access, procedure = binding.procedures.access_readback, deadline = Date.now() + procedure.timeout_ms;
+            // The project-owned procedure is the structured extractor. Each step
+            // emits only this public-context envelope (possibly partial/empty).
+            for (const step of procedure.procedure_steps) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    refuse("readback_failed");
+                let malformed = false;
+                try {
+                    const result = await executeDeliveryStep(context, { projectId: input.projectId, runId: input.runId,
+                        operationId: `access-${randomUUID()}`, stepId: step.id, workspace: input.workspace, procedure, deadlineAt: deadline,
+                        assertCurrent, admit() { }, consumeOutput(bytes) {
+                            let value;
+                            try {
+                                value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+                            }
+                            catch {
+                                malformed = true;
+                                return;
+                            }
+                            if (!record(value) || value.schema_id !== "dd-flow/delivery-access-observation@1"
+                                || Object.keys(value).some(key => !["schema_id", ...dimensions].includes(key))) {
+                                malformed = true;
+                                return;
+                            }
+                            for (const dimension of dimensions) {
+                                if (!Object.hasOwn(value, dimension))
+                                    continue;
+                                const expected = access[dimension], observed = value[dimension];
+                                if (expected === "not_required") {
+                                    if (observed !== "not_required") {
+                                        malformed = true;
+                                        return;
+                                    }
+                                }
+                                else if (!record(observed) || Object.keys(observed).sort().join() !== "id,kind"
+                                    || observed.kind !== expected.kind || observed.id !== expected.id) {
+                                    malformed = true;
+                                    return;
+                                }
+                                times.set(dimension, Date.parse(context.now()));
+                            }
+                        } });
+                    processes.push(result.process_id);
+                    if (Date.now() >= deadline)
+                        refuse("readback_failed");
+                }
+                catch {
+                    refuse("readback_failed");
+                }
+                if (malformed)
+                    refuse("context_mismatch_or_unsafe_output");
+            }
+            if (!times.has("identity") || !times.has("target") || access.authority !== "not_required" && !times.has("authority"))
+                refuse("required_context_not_observable");
+        }
+        assertCurrent();
+        const now = Date.parse(context.now());
+        if (!Number.isFinite(now) || [...times.values()].some(time => !Number.isFinite(time) || time > now))
+            refuse("observation_clock_invalid");
+        const observed = times.size ? Math.min(...times.values()) : now;
+        const prepared = new PreparedDeliveryAccess(context, input, observed, { schema_id: "dd-flow/delivery-access@1",
+            operation_id: input.operationId, binding_id: binding.id, observed_at: new Date(observed).toISOString(),
+            applicability: binding.access.applicability === "required" ? "verified" : "not_required",
+            identity: binding.access.applicability === "required" ? "verified" : "not_required",
+            authority: binding.access.applicability === "required" && binding.access.authority !== "not_required" ? "verified" : "not_required",
+            target: binding.access.applicability === "required" ? "verified" : "not_required", expected: binding.access, processes });
+        prepared.assertFresh(context, input);
+        return prepared;
+    }
+    value() { return structuredClone(this.#report); }
+    assertFresh(context, input) {
+        const now = Date.parse(context.now());
+        if (this.#pid !== process.pid || this.#consumed || identity(context, input) !== this.#scope
+            || !Number.isFinite(now) || now < Date.parse(this.#report.observed_at) || now >= this.#expires)
+            refuse("fresh_same_process_readback_required");
+    }
+    consume(context, input) { this.assertFresh(context, input); this.#consumed = true; }
+}

package/dist/services/delivery-approval.js

@@ -0,0 +1,68 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { resolveDeliveryBinding } from "./delivery-policy.js";
+const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const keys = (value, names) => Object.keys(value).sort().join() === [...names].sort().join();
+const text = (value) => typeof value === "string" && Boolean(value.trim()) && value.length <= 4096 && !value.includes("\0");
+function refuse(reason) {
+    throw new AppError("delivery_approval_invalid", "Delivery needs current user approval for the exact selected operation", 2, { reason, effect: "no_effect" });
+}
+/** Public decision scope, not observed artifact bytes, account access or grant.
+ * The Stage owner supplies its retained artifact/target selection and freezes
+ * the same scope in the operation intent before execution. */
+export function deliveryApprovalScope(scope, bundle, selection) {
+    const flow = bundle.manifest.flow_id;
+    if (flow !== "release" && flow !== "deploy" && flow !== "publish")
+        refuse("delivery_bundle_required");
+    const binding = resolveDeliveryBinding({ schema_id: "dd-flow/delivery-policy@1", bindings: [selection.binding] }, selection.binding.selector);
+    if (binding.selector.operation !== flow || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(selection.operationId)
+        || !record(selection.artifact) || !keys(selection.artifact, ["subject_ref", "version", "sha256"])
+        || selection.artifact.subject_ref !== binding.selector.subject_ref || !text(selection.artifact.version) || !digest(selection.artifact.sha256))
+        refuse("exact_operation_scope_required");
+    const request = bundle.execution.snapshot().scope.requestId;
+    if (!text(request) || !digest(bundle.sha256))
+        refuse("original_request_required");
+    return { schema_id: "dd-flow/delivery-approval-scope@1", project_id: scope.projectId, run_id: scope.runId,
+        request_id: request, bundle_sha256: bundle.sha256, operation_id: selection.operationId, flow_id: flow,
+        binding_id: binding.id, binding_sha256: hybridDigest(binding), selector: binding.selector, artifact: structuredClone(selection.artifact) };
+}
+/** Custody and exact scope only: interpreting whether the cited user really
+ * approves this operation remains the owning agent/review's responsibility.
+ * Flow startup, a question or successful login never becomes approval here.
+ * This prepared value is not a publication token or dispatch authority. */
+export function prepareDeliveryApproval(context, scope, bundle, selection, proposal) {
+    if (!record(proposal) || !keys(proposal, ["scope_sha256", "user_inputs_sha256", "basis", "expires_at", "reason"])
+        || !digest(proposal.scope_sha256) || !digest(proposal.user_inputs_sha256) || !text(proposal.reason)
+        || !text(proposal.expires_at) || !record(proposal.basis) || !keys(proposal.basis, ["role", "event_id", "sha256"])
+        || !["request", "answer"].includes(proposal.basis.role) || !Number.isSafeInteger(proposal.basis.event_id)
+        || proposal.basis.event_id < 0 || !digest(proposal.basis.sha256))
+        refuse("invalid_approval_proposal");
+    const selected = deliveryApprovalScope(scope, bundle, selection), flow = selected.flow_id;
+    const users = readPreparedMemoryFlowUserInputs(context, scope, flow, bundle), inputsHash = hybridDigest(users);
+    if (proposal.scope_sha256 !== hybridDigest(selected))
+        refuse("approval_scope_mismatch");
+    if (proposal.user_inputs_sha256 !== inputsHash)
+        refuse("current_user_input_required");
+    const source = users.sources.find(item => item.role === proposal.basis.role && item.event_id === proposal.basis.event_id && item.sha256 === proposal.basis.sha256);
+    if (!source || proposal.basis.role === "request" && proposal.basis.event_id !== 0)
+        refuse("delivered_approval_basis_required");
+    const expiry = Date.parse(proposal.expires_at), approvedAt = context.now();
+    if (!Number.isFinite(expiry) || !Number.isFinite(Date.parse(approvedAt)) || expiry <= Date.parse(approvedAt))
+        refuse("approval_expired");
+    const value = { schema_id: "dd-flow/delivery-approval@1", scope: selected, scope_sha256: hybridDigest(selected),
+        user_inputs_sha256: inputsHash, approver: "delivered_user", basis: structuredClone(proposal.basis),
+        approved_at: approvedAt, expires_at: new Date(expiry).toISOString(), interpretation: proposal.reason };
+    return {
+        value: () => structuredClone(value),
+        /** SQL/data-only fence. A later answer (including revocation) invalidates
+         * the interpretation until the owning Stage reassesses the full input set. */
+        assertCustody(writer) {
+            if (hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, flow, bundle)) !== inputsHash)
+                refuse("approval_inputs_changed");
+            if (!Number.isFinite(Date.parse(writer.now())) || Date.parse(writer.now()) >= expiry)
+                refuse("approval_expired");
+        }
+    };
+}

package/dist/services/delivery-artifact.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+function refuse(reason) {
+    throw new AppError("delivery_artifact_invalid", "Delivery requires the exact accepted artifact bytes", 2, { reason, phase: "prepare", effect: "no_effect", recoverable: true });
+}
+function observe(workspace, logicalPath) {
+    if (!path.isAbsolute(workspace) || typeof logicalPath !== "string" || !logicalPath || logicalPath.length > 4096
+        || logicalPath.includes("\\") || logicalPath.includes("\0") || path.isAbsolute(logicalPath)
+        || logicalPath.split("/").some(part => !part || part === "." || part === ".." || part === ".git"))
+        refuse("contained_artifact_required");
+    try {
+        if (fs.realpathSync(workspace) !== workspace || !fs.lstatSync(workspace).isDirectory())
+            refuse("canonical_workspace_required");
+        let file = workspace;
+        for (const part of logicalPath.split("/").slice(0, -1)) {
+            file = path.join(file, part);
+            if (!fs.lstatSync(file).isDirectory())
+                refuse("contained_artifact_required");
+        }
+        file = path.join(workspace, logicalPath);
+        if (!fs.lstatSync(file).isFile())
+            refuse("regular_artifact_required");
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+        try {
+            const before = fs.fstatSync(fd, { bigint: true }), digest = createHash("sha256"), buffer = Buffer.allocUnsafe(256 * 1024);
+            if (!before.isFile())
+                refuse("regular_artifact_required");
+            let length = 0n;
+            for (;;) {
+                const count = fs.readSync(fd, buffer, 0, buffer.length, null);
+                if (!count)
+                    break;
+                digest.update(buffer.subarray(0, count));
+                length += BigInt(count);
+            }
+            const after = fs.fstatSync(fd, { bigint: true }), named = fs.lstatSync(file, { bigint: true });
+            if (length !== before.size || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs
+                || !named.isFile() || named.dev !== before.dev || named.ino !== before.ino || fs.realpathSync(file) !== file)
+                refuse("artifact_changed_during_observation");
+            return { sha256: digest.digest("hex"), bytes: length.toString() };
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("artifact_unavailable");
+    }
+}
+/** Exact file/archive bytes, or a project-owned manifest selecting immutable
+ * remote artifacts. A manifest digest alone does not prove its remote objects:
+ * the owning verify Stage must establish those references before approval.
+ * Observation is synchronous and outside SQL writers, immediately before the
+ * managed admission fence; it is not an OS lock against a hostile local writer. */
+export class PreparedDeliveryArtifact {
+    #workspace;
+    #path;
+    #artifact;
+    #bytes;
+    constructor(workspace, logicalPath, artifact, bytes) {
+        this.#workspace = workspace;
+        this.#path = logicalPath;
+        this.#artifact = structuredClone(artifact);
+        this.#bytes = bytes;
+    }
+    static prepare(workspace, logicalPath, artifact) {
+        if (!artifact || Object.keys(artifact).sort().join() !== "sha256,subject_ref,version"
+            || typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(artifact.sha256)
+            || [artifact.subject_ref, artifact.version].some(value => typeof value !== "string" || !value.trim() || value.length > 4096 || value.includes("\0")))
+            refuse("accepted_artifact_required");
+        const actual = observe(workspace, logicalPath);
+        if (actual.sha256 !== artifact.sha256)
+            refuse("accepted_artifact_changed");
+        return new PreparedDeliveryArtifact(workspace, logicalPath, artifact, actual.bytes);
+    }
+    value() { return { schema_id: "dd-flow/delivery-artifact@1", workspace: this.#workspace, path: this.#path, artifact: structuredClone(this.#artifact), bytes: this.#bytes }; }
+    assertCurrent() {
+        const actual = observe(this.#workspace, this.#path);
+        if (actual.sha256 !== this.#artifact.sha256 || actual.bytes !== this.#bytes)
+            refuse("accepted_artifact_changed");
+    }
+}