@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/services/run-recovery.js

@@ -4,11 +4,16 @@ export { recoveryGuard, assertRunMutationAllowed, assertRunRecoveryAllowed } fro
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { parseLifecycleCommand } from "../harness-runtime/lib/lifecycle-command.mjs";
 import { AppError } from "../shared/errors.js";
 import { entityReferenceVariants } from "../shared/entity-references.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { appendFlowRunTimelineEvent, setFlowRunRecoveryPaused } from "./runs.js";
+import { appendFlowRunTimelineEvent, setFlowRunRecoveryPaused, readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readDescriptorCoordinatorSession } from "./descriptor-coordinator-session.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
 import { verifyRecoverySnapshot } from "./eval-snapshots.js";
 import { findRecentMatchingHookEvent, hookSessionIdentity, recoveryAcceptMatchKey } from "./hooks.js";
 import { flowCommand } from "./stage-pause.js";
@@ -19,6 +24,93 @@ export function recoveryPacketReceipt(binding) {
         throw new AppError("recovery_packet_missing", "Recovery requires its original verified Work packet", 1);
     return { packet_json: binding.packet_json, packet_sha256: binding.packet_sha256, packet: JSON.parse(binding.packet_json) };
 }
+/** Read-only custody permission for one prepared recovery ACK, not lifecycle admission. */
+export class PreparedRecoveryCoordinatorRead {
+    #scope;
+    #recoveryId;
+    #eventKey;
+    #generation;
+    #signature;
+    constructor(scope, recoveryId, eventKey, generation, signature) {
+        this.#scope = Object.freeze(scope);
+        this.#recoveryId = recoveryId;
+        this.#eventKey = eventKey;
+        this.#generation = generation;
+        this.#signature = signature;
+        Object.freeze(this);
+    }
+    get scope() { return this.#scope; }
+    static prepare(context, scope, recoveryId, eventKey) {
+        const proof = recoveryCoordinatorReadProof(context, scope, recoveryId, eventKey);
+        return new PreparedRecoveryCoordinatorRead({ ...scope }, recoveryId, eventKey, proof.generation, proof.signature);
+    }
+    assertRead(context, scope) {
+        const proof = recoveryCoordinatorReadProof(context, scope, this.#recoveryId, this.#eventKey);
+        if (hybridDigest(scope) !== hybridDigest(this.#scope) || proof.generation !== this.#generation || proof.signature !== this.#signature)
+            throw new AppError("recovery_owner_changed", "Recovery read custody changed", 1);
+    }
+}
+function recoveryCoordinatorReadProof(context, scope, recoveryId, eventKey) {
+    const guard = recoveryGuard(context, scope.projectId, scope.runId);
+    const binding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ?", [recoveryId]);
+    const identity = hookSessionIdentity(context, scope.projectId, eventKey);
+    const hook = context.db.get("SELECT status,event_name,match_key FROM hook_events WHERE id = ?", [identity.hookEventId]);
+    const run = context.db.get("SELECT r.index_json,p.root AS project_root FROM runs r JOIN projects p ON p.id=r.project_id WHERE r.project_id=? AND r.id=?", [scope.projectId, scope.runId]);
+    const packet = binding ? recoveryPacketReceipt(binding).packet : null;
+    const delivery = packet?.lifecycle_delivery;
+    const prior = binding && context.db.get("SELECT ws.id,ws.status AS session_status,w.status AS work_status FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE ws.id=? AND ws.work_id=? AND ws.session_id=? AND ws.status='running' AND w.project_id=? AND w.run_id=? AND w.status IN ('running','paused')", [binding.prior_work_session_id, binding.work_id, binding.session_id, scope.projectId, scope.runId]);
+    if (!guard || guard.recovery_id !== recoveryId || guard.status !== "resuming" || !guard.capture_path || !binding || binding.status !== "prepared" || !run || !prior
+        || binding.session_id !== identity.sessionId || binding.harness !== identity.harness || binding.provider_session_id !== identity.providerSessionId || binding.daemon_id !== identity.daemonId || identity.parentSessionId
+        || hook?.status !== "observed" || hook.event_name !== "PreToolUse" || !entityReferenceVariants(scope.runId).some(reference => hook.match_key === recoveryAcceptMatchKey(reference, recoveryId, run.project_root))
+        || packet?.schema_id !== "dd-flow/root-recovery-packet@1" || packet.recovery_id !== recoveryId || packet.mode !== "same-session" || packet.continuation !== "unfinished_work" || packet.run_id !== scope.runId || packet.work_id !== binding.work_id
+        || packet.retained_session_status !== prior.session_status || packet.retained_work_status !== prior.work_status
+        || packet.capture_path !== guard.capture_path
+        || packet.generation !== guard.generation || packet.stage !== scope.stage || typeof delivery?.text !== "string"
+        || crypto.createHash("sha256").update(delivery.text).digest("hex") !== delivery.sha256
+        || JSON.parse(run.index_json).current_stage !== scope.stage)
+        throw new AppError("recovery_binding_mismatch", "Read requires exact prepared recovery acknowledgement custody", 1);
+    return { generation: guard.generation, signature: hybridDigest({ scope, guard, binding, identity, hook, run, prior }) };
+}
+export function recoveredCoordinatorBinding(original, input) {
+    const scope = original.scope;
+    if (original.run_id !== input.runId || scope?.project_id !== input.projectId || scope.run_id !== input.runId || scope.stage !== input.stage
+        || original.work_id !== input.workId || original.work_session_id !== input.priorWorkSessionId || original.session_id !== input.sessionId
+        || original.harness !== input.harness || original.provider_session_id !== input.providerSessionId || input.model !== input.frozenModel
+        || original.execution_sha256 !== input.executionSha256 || original.profile_id !== input.profileId || original.profile_sha256 !== input.profileSha256 || original.session_mode !== input.sessionMode
+        || !Number.isInteger(input.generation) || input.generation < 1 || !/^[a-f0-9]{64}$/.test(input.packetSha256)
+        || !input.daemonId || !input.hookEventKey)
+        throw new AppError("recovery_binding_mismatch", "Recovered coordinator differs from original frozen physical custody", 1);
+    return { ...original, work_session_id: input.workSessionId, recovery: {
+            recovery_id: input.recoveryId, generation: input.generation, original_work_session_id: input.priorWorkSessionId,
+            original_binding_sha256: hybridDigest(original), packet_sha256: input.packetSha256,
+            acknowledgement_hook: input.hookEventKey, daemon_id: input.daemonId
+        } };
+}
+/** Read issued delivery authority from the verified capture, never a mutable prompt. */
+export function capturedStageDelivery(capture, scope, originalPrompt) {
+    const db = new DatabaseSync(path.join(capture, "runtime", "db.sqlite"), { readOnly: true });
+    try {
+        const rows = db.prepare("SELECT command, outcome_json FROM lifecycle_invocations WHERE status = 'settled' AND json_extract(scope_json, '$.projectRoot') = ? AND json_extract(scope_json, '$.runId') = ? AND json_extract(scope_json, '$.rootSessionId') = ? AND json_extract(scope_json, '$.generation') < ? ORDER BY rowid DESC").all(scope.projectRoot, scope.runId, scope.sessionId, scope.generation);
+        for (const row of rows) {
+            const result = row.outcome_json ? JSON.parse(row.outcome_json).result : null;
+            const parsed = parseLifecycleCommand(row.command);
+            if (parsed.kind === "none" || !parsed.supported || parsed.invocation.operation !== "stage_start" || parsed.invocation.args.options.get("stage")?.[0] !== scope.stage
+                || result?.stage !== scope.stage || result.attempt !== scope.attempt || result.work_id !== scope.workId || typeof result.worker_prompt_markdown !== "string")
+                continue;
+            const text = result.worker_prompt_markdown;
+            if (!text.startsWith(originalPrompt))
+                throw new AppError("recovery_packet_mismatch", "Captured Stage delivery differs from its original semantic prompt", 1);
+            const sha256 = crypto.createHash("sha256").update(text).digest("hex");
+            if (!db.prepare("SELECT 1 FROM lifecycle_packet_assignments WHERE packet_sha256 = ? LIMIT 1").get(sha256))
+                throw new AppError("recovery_packet_missing", "Captured Stage delivery has no committed lifecycle assignment", 1);
+            return { text, sha256 };
+        }
+        return null;
+    }
+    finally {
+        db.close();
+    }
+}
 function rootRecoveryPacket(context, run, guard, owner) {
     const work = context.db.get("SELECT task, status, result, result_schema, payload_json, depends_on_json FROM works WHERE work_id = ?", [owner.work_id]);
     const session = context.db.get("SELECT prompt_path, status FROM work_sessions WHERE id = ?", [owner.id]);
@@ -34,9 +126,18 @@ function rootRecoveryPacket(context, run, guard, owner) {
     }
     const prompt = fs.readFileSync(promptPath, "utf8");
     const currentPrompt = currentStagePrompt(context, session.prompt_path, run.run_root, prompt);
+    const index = JSON.parse(run.index_json);
+    const stage = index.current_stage ?? null;
+    const attempt = index.stage_runs?.find((item) => item.stage === stage)?.attempt;
+    const provider = context.db.get("SELECT s.provider_session_id FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id JOIN sessions s ON s.session_id = ws.session_id AND s.project_id = w.project_id WHERE ws.id = ?", [owner.id]);
+    const delivery = !boundary && stage && attempt ? capturedStageDelivery(guard.capture_path, { projectRoot: run.project_root, runId: run.id, sessionId: provider.provider_session_id, stage, workId: owner.work_id, generation: guard.generation, attempt }, prompt) : null;
+    if (!boundary && ["mb-init", "mb-upgrade"].includes(run.flow_kind) && !delivery)
+        throw new AppError("recovery_packet_missing", "Unfinished Memory Stage requires its captured published lifecycle delivery", 1);
     const dependencies = JSON.parse(work.depends_on_json);
     return JSON.stringify({
         schema_id: "dd-flow/root-recovery-packet@1", recovery_id: guard.recovery_id, generation: guard.generation, run_id: run.id, work_id: owner.work_id,
+        stage,
+        ...(delivery ? { lifecycle_delivery: delivery } : {}),
         mode: "same-session", continuation: boundary ? "stage_boundary" : "unfinished_work", retained_work_status: work.status, retained_session_status: session.status, retained_result: work.result,
         original_task: work.task, original_task_sha256: crypto.createHash("sha256").update(work.task).digest("hex"),
         original_prompt: { path: promptPath, text: prompt, sha256: crypto.createHash("sha256").update(prompt).digest("hex") },
@@ -53,7 +154,7 @@ export function acceptanceCommand(context, runId, recoveryId, projectRoot) {
     return managedLifecycleCommand(context, `${flowCommand(context)} run recovery accept ${JSON.stringify(runId)} --recovery-id ${JSON.stringify(recoveryId)} --project-root ${JSON.stringify(projectRoot)} --json`);
 }
 export function requireRecoveryRun(context, projectId, runId) {
-    const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, r.index_json, r.flow_kind, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]);
     if (!run?.run_root)
         throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId });
     return run;
@@ -251,6 +352,7 @@ export function resumeRunRecovery(context, input, prepared = prepareRunRecoveryR
         return { signature, owner, packet, running, evidence };
     });
     const { owner, packet, running } = publication;
+    verifyRecoverySnapshot(guard.capture_path, { runId: run.id, recoveryId: guard.recovery_id, projectRoot: run.project_root, workspaceRoot: run.workspace_root });
     context.db.writeTransaction(() => {
         if (authority() !== publication.signature)
             throw new AppError("recovery_state_changed", "Recovery inputs changed while its packet was prepared", 1, { recovery_id: guard.recovery_id });
@@ -278,6 +380,16 @@ export function acceptRunRecovery(context, input) {
     const eventKey = input.hookEventId ?? findRecentMatchingHookEvent(context, { projectId: project.id, matchKey, errorCode: "trusted_recovery_acceptance_required", operation: "run recovery accept" }).eventKey;
     const identity = hookSessionIdentity(context, project.id, eventKey);
     const now = context.now();
+    const preparedBinding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ?", [input.recoveryId]);
+    const preparedPacket = preparedBinding ? recoveryPacketReceipt(preparedBinding).packet : null;
+    const bundle = preparedBinding?.status === "prepared" && preparedPacket?.continuation === "unfinished_work" && preparedPacket.lifecycle_delivery
+        ? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id }) : null;
+    const coordinatorScope = bundle && preparedPacket?.stage ? { projectId: project.id, runId: run.id, stage: preparedPacket.stage } : null;
+    if (preparedBinding?.status === "prepared" && preparedPacket?.continuation === "unfinished_work"
+        && ["mb-init", "mb-upgrade"].includes(run.flow_kind) && (!preparedPacket.lifecycle_delivery || !coordinatorScope))
+        throw new AppError("recovery_packet_missing", "Memory recovery lacks retained Stage delivery and frozen coordinator scope", 1);
+    const recoveryRead = coordinatorScope ? PreparedRecoveryCoordinatorRead.prepare(context, coordinatorScope, input.recoveryId, eventKey) : undefined;
+    const preparedCustody = coordinatorScope && bundle ? readDescriptorCoordinatorSession(context, { scope: coordinatorScope, bundle, workId: preparedBinding.work_id, recoveryRead: recoveryRead }) : null;
     const result = context.db.writeTransaction(() => {
         assertRecoveryRunCanResume(context, project.id, run.id);
         const guard = recoveryGuard(context, project.id, run.id);
@@ -287,11 +399,14 @@ export function acceptRunRecovery(context, input) {
             throw new AppError("recovery_binding_mismatch", "Recovery acknowledgement does not belong to the authorized physical Session and generation", 1);
         const packetReceipt = recoveryPacketReceipt(binding);
         const retained = packetReceipt.packet;
-        if (binding.harness === "zcode-acp" || (binding.harness === "codex-desktop" && hasLifecyclePacketAssignments(context, retained.original_prompt.text))) {
+        const authorityPrompt = retained.lifecycle_delivery?.text ?? retained.original_prompt.text;
+        if (retained.lifecycle_delivery && crypto.createHash("sha256").update(authorityPrompt).digest("hex") !== retained.lifecycle_delivery.sha256)
+            throw new AppError("recovery_packet_mismatch", "Retained lifecycle delivery checksum differs", 1);
+        if (binding.harness === "zcode-acp" || (binding.harness === "codex-desktop" && hasLifecyclePacketAssignments(context, authorityPrompt))) {
             const scope = { projectRoot: run.project_root, daemonId: binding.daemon_id, rootSessionId: binding.provider_session_id, runId: run.id, generation: guard.generation };
             const assignments = new Set();
             packetReceipt.lifecycle_recovery = {
-                commands: retained.continuation === "stage_boundary" ? [] : recoverLifecycleCommands({ ...context, captureLifecycleAssignment: id => { assignments.add(id); } }, retained.original_prompt.text, scope),
+                commands: retained.continuation === "stage_boundary" ? [] : recoverLifecycleCommands({ ...context, captureLifecycleAssignment: id => { assignments.add(id); } }, authorityPrompt, scope),
                 instruction: "original_prompt is immutable historical evidence. Do not execute its old command authority. Use only replacement commands below; reconcile unknown outcomes before continuing. At a completed stage boundary return control to the runner.",
                 work_list_command: `${flowCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: JSON.stringify(scope) } })} work ls --run ${run.id} --ready --project-root ${JSON.stringify(run.project_root)} --json`
             };
@@ -308,10 +423,35 @@ export function acceptRunRecovery(context, input) {
         const prior = context.db.get("SELECT ws.prompt_path, ws.result_path FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE ws.id = ? AND ws.work_id = ? AND ws.session_id = ? AND ws.status = ? AND w.status = ?", [binding.prior_work_session_id, binding.work_id, binding.session_id, packet.retained_session_status ?? "running", packet.retained_work_status ?? (JSON.parse(binding.packet_json).paused ? "paused" : "running")]);
         if (!prior)
             throw new AppError("recovery_owner_changed", "Retained root WorkSession changed before recovery acceptance", 1);
+        let physicalBinding = null;
+        if (!boundary && coordinatorScope && bundle) {
+            const currentRun = assertPreparedRunBundleSqlAuthority(context, coordinatorScope, bundle);
+            if (preparedBinding?.packet_sha256 !== binding.packet_sha256 || preparedBinding.prior_work_session_id !== binding.prior_work_session_id
+                || preparedPacket?.stage !== JSON.parse(currentRun.index_json).current_stage
+                || readDescriptorCoordinatorSession(context, { scope: coordinatorScope, bundle, workId: binding.work_id, recoveryRead: recoveryRead }) !== preparedCustody)
+                throw new AppError("recovery_owner_changed", "Original coordinator custody changed before recovery acknowledgement", 1);
+            const route = bundle.execution.stage(coordinatorScope.stage);
+            if (identity.model !== route.profile.model)
+                throw new AppError("recovery_binding_mismatch", "Recovery acknowledgement model differs from the frozen coordinator", 1);
+            const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'stage.coordinator_binding' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.scope.stage') = ? AND json_extract(payload_json, '$.work_session_id') = ?", [project.id, run.id, coordinatorScope.stage, binding.prior_work_session_id]);
+            physicalBinding = JSON.parse(rows[0].payload_json);
+        }
         context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [now, identity.hookEventId]);
         if (!boundary) {
+            const recoveredWorkSessionId = `WS-${crypto.randomUUID()}`;
             context.db.run("UPDATE work_sessions SET status = 'interrupted', completed_at = ?, updated_at = ? WHERE id = ?", [now, now, binding.prior_work_session_id]);
-            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?)", [`WS-${crypto.randomUUID()}`, binding.work_id, binding.session_id, eventKey, prior.prompt_path, prior.result_path, now, now]);
+            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?)", [recoveredWorkSessionId, binding.work_id, binding.session_id, eventKey, prior.prompt_path, prior.result_path, now, now]);
+            if (physicalBinding)
+                appendAudit(context, { projectId: project.id, eventType: "stage.coordinator_binding", payload: recoveredCoordinatorBinding(physicalBinding, {
+                        projectId: project.id, runId: run.id, stage: coordinatorScope.stage, workId: binding.work_id,
+                        priorWorkSessionId: binding.prior_work_session_id, workSessionId: recoveredWorkSessionId,
+                        sessionId: identity.sessionId, harness: identity.harness, providerSessionId: identity.providerSessionId,
+                        model: identity.model, frozenModel: bundle.execution.stage(coordinatorScope.stage).profile.model,
+                        executionSha256: bundle.execution.sha256, profileId: bundle.execution.stage(coordinatorScope.stage).profile.id,
+                        profileSha256: hybridDigest(bundle.execution.stage(coordinatorScope.stage).profile), sessionMode: bundle.execution.stage(coordinatorScope.stage).session_mode,
+                        recoveryId: guard.recovery_id, generation: guard.generation, packetSha256: binding.packet_sha256,
+                        hookEventKey: eventKey, daemonId: identity.daemonId
+                    }) });
         }
         context.db.run("UPDATE run_recovery_bindings SET status = 'accepted', hook_event_key = ?, accepted_at = ? WHERE recovery_id = ?", [eventKey, now, binding.recovery_id]);
         context.db.run("UPDATE run_recovery_guards SET status = 'recovered', resumed_at = ?, updated_at = ? WHERE recovery_id = ?", [now, now, guard.recovery_id]);

package/dist/services/run-start-custody.js

@@ -0,0 +1,177 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+export const runStartPayloadLimit = 64 * 1024 * 1024;
+export function runStartBytesSha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+export function refuseRunStart(reason) {
+    throw new AppError("run_start_custody_invalid", "RUN creation requires its exact retained request", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+export function hasRunStartTable(context) {
+    return Boolean(context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_start_requests'"));
+}
+function object(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join("\0") === keys.sort().join("\0");
+}
+function digest(value) { return typeof value === "string" && /^[a-f0-9]{64}$/.test(value); }
+function canonicalBase64(value) {
+    return typeof value === "string" && Buffer.from(value, "base64").toString("base64") === value;
+}
+/** Retained data can drive filesystem writes only after a closed shape check. */
+export function validateRunStartPayload(value) {
+    if (!object(value) || !exactKeys(value, ["schema_id", "request_id", "project_id", "project_root", "workspace_root", "home_root",
+        "run_id", "request_sha256", "bundle_sha256", "subject_type", "subject_id", "slug", "run_root", "initial_index",
+        "bundle_manifest_base64", "blobs", "artifacts", "owners", "git"]))
+        refuseRunStart("invalid_allocation_shape");
+    for (const key of ["request_id", "project_id", "run_id", "slug", "subject_type", "subject_id"])
+        if (typeof value[key] !== "string" || !value[key].trim() || value[key].length > 1024)
+            refuseRunStart("invalid_allocation_shape");
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value.project_id)
+        || !/^RUN-\d+-[a-z0-9][a-z0-9-]*$/.test(value.run_id))
+        refuseRunStart("invalid_allocation_shape");
+    for (const key of ["project_root", "workspace_root", "home_root", "run_root"])
+        if (typeof value[key] !== "string" || !path.isAbsolute(value[key]) || path.resolve(value[key]) !== value[key])
+            refuseRunStart("invalid_allocation_scope");
+    if (value.run_root !== path.join(value.home_root, "projects", value.project_id, "runs", value.run_id)
+        || !digest(value.request_sha256) || !digest(value.bundle_sha256) || !canonicalBase64(value.bundle_manifest_base64)
+        || runStartBytesSha256(Buffer.from(value.bundle_manifest_base64, "base64")) !== value.bundle_sha256
+        || !object(value.initial_index) || !object(value.owners) || !exactKeys(value.owners, ["home", "project", "workspace"]))
+        refuseRunStart("invalid_allocation_shape");
+    for (const key of ["home", "project", "workspace"]) {
+        const owner = value.owners[key];
+        if (!object(owner) || !exactKeys(owner, ["dev", "ino"]) || ![owner.dev, owner.ino].every(number => Number.isSafeInteger(number) && Number(number) >= 0))
+            refuseRunStart("invalid_allocation_owner");
+    }
+    if (!object(value.git) || !exactKeys(value.git, ["branch", "head", "status_sha256"]) || typeof value.git.branch !== "string" || !value.git.branch
+        || value.git.head !== null && (typeof value.git.head !== "string" || !/^[a-f0-9]{40,64}$/.test(value.git.head))
+        || !digest(value.git.status_sha256))
+        refuseRunStart("invalid_allocation_git");
+    for (const key of ["blobs", "artifacts"]) {
+        const entries = value[key];
+        if (!Array.isArray(entries) || entries.length > 4096)
+            refuseRunStart("invalid_allocation_assets");
+        const seen = new Set();
+        for (const entry of entries) {
+            if (!object(entry) || !exactKeys(entry, ["path", "base64"]) || typeof entry.path !== "string"
+                || !entry.path || entry.path.includes("\\") || entry.path.includes("\0") || entry.path.split("/").some(part => !part || part === "." || part === "..")
+                || seen.has(entry.path) || !canonicalBase64(entry.base64))
+                refuseRunStart("invalid_allocation_assets");
+            if (key === "artifacts" && (!["engine-binding.json", "operational-policy.source.md", "operational-contract.json"].includes(entry.path)
+                || Buffer.from(entry.base64, "base64").length > 1024 * 1024))
+                refuseRunStart("invalid_allocation_artifact");
+            seen.add(entry.path);
+        }
+        if (key === "artifacts" && (!seen.has("engine-binding.json") || seen.has("operational-policy.source.md") && !seen.has("operational-contract.json")))
+            refuseRunStart("invalid_allocation_artifact");
+    }
+}
+/** Metadata and copied SQL bytes only. No engine/filesystem/provider admission. */
+export function readRunStartRequest(context, projectId, requestId) {
+    return context.db.readSnapshot(() => readRunStartRequestSnapshot(context, projectId, requestId));
+}
+function readRunStartRequestSnapshot(context, projectId, requestId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuseRunStart("invalid_request_id");
+    const row = hasRunStartTable(context) ? context.db.get("SELECT run_id, payload_json, payload_sha256 FROM run_start_requests WHERE project_id = ? AND request_id = ?", [projectId, requestId]) : undefined;
+    const starts = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.start_request' AND json_extract(payload_json, '$.request_id') = ? LIMIT 2", [projectId, requestId]);
+    if (!row) {
+        const marker = context.db.get("SELECT 1 FROM runs WHERE project_id = ? AND json_extract(index_json, '$.start_request.request_id') = ? LIMIT 1", [projectId, requestId]);
+        const bound = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'")
+            && context.db.get("SELECT 1 FROM run_bundle_authorities WHERE project_id = ? AND json_extract(admission_json, '$.executionScope.requestId') = ? LIMIT 1", [projectId, requestId]);
+        if (starts.length || marker || bound)
+            refuseRunStart("request_receipt_missing");
+        return null;
+    }
+    if (starts.length !== 1 || Buffer.byteLength(row.payload_json) > runStartPayloadLimit
+        || runStartBytesSha256(row.payload_json) !== row.payload_sha256)
+        refuseRunStart("allocation_changed");
+    let payload, receipt;
+    try {
+        payload = JSON.parse(row.payload_json);
+        receipt = JSON.parse(starts[0].payload_json);
+    }
+    catch {
+        return refuseRunStart("invalid_allocation_json");
+    }
+    validateRunStartPayload(payload);
+    if (!object(receipt))
+        refuseRunStart("invalid_allocation_receipt");
+    const run = context.db.get("SELECT project_root, workspace_root, run_root, flow_kind, subject_type, subject_id, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, row.run_id]);
+    let index;
+    try {
+        if (!run)
+            refuseRunStart("allocated_run_missing");
+        index = JSON.parse(run.index_json);
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuseRunStart("allocated_run_changed");
+    }
+    if (!object(index))
+        refuseRunStart("allocated_run_changed");
+    const marker = index.start_request, initial = payload.initial_index;
+    if (!payload || payload.schema_id !== "dd-flow/run-start-allocation@1" || payload.project_id !== projectId
+        || payload.request_id !== requestId || payload.run_id !== row.run_id || !Array.isArray(payload.blobs) || !Array.isArray(payload.artifacts)
+        || !initial || initial.run_id !== row.run_id || initial.project?.id !== projectId || initial.start_request !== undefined
+        || initial.execution_bundle?.manifest_sha256 !== payload.bundle_sha256 || !/^[a-f0-9]{64}$/.test(payload.request_sha256)
+        || !marker || marker.schema_id !== "dd-flow/run-start-request@1" || marker.request_id !== requestId
+        || marker.request_sha256 !== payload.request_sha256 || marker.allocation_sha256 !== row.payload_sha256
+        || receipt.run_id !== row.run_id || receipt.request_id !== requestId || receipt.request_sha256 !== payload.request_sha256 || receipt.allocation_sha256 !== row.payload_sha256
+        || run.project_root !== payload.project_root || run.workspace_root !== payload.workspace_root || run.run_root !== payload.run_root
+        || run.flow_kind !== initial.flow_kind || run.subject_id !== payload.subject_id || run.subject_type !== payload.subject_type
+        || !object(index.execution_bundle) || hybridDigest(index.execution_bundle) !== hybridDigest(initial.execution_bundle))
+        refuseRunStart("allocated_run_changed");
+    const publications = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.start_published' AND json_extract(payload_json, '$.run_id') = ? LIMIT 2", [projectId, row.run_id]);
+    if (publications.length > 1 || Boolean(marker.publication_sha256) !== (publications.length === 1))
+        refuseRunStart("publication_receipt_missing");
+    if (publications.length) {
+        let publication;
+        try {
+            publication = JSON.parse(publications[0].payload_json);
+        }
+        catch {
+            return refuseRunStart("invalid_publication_receipt");
+        }
+        if (!object(publication) || publication.schema_id !== "dd-flow/run-start-publication@1" || hybridDigest(publication) !== marker.publication_sha256 || publication.request_id !== requestId
+            || publication.run_id !== row.run_id || publication.allocation_sha256 !== row.payload_sha256 || publication.bundle_sha256 !== payload.bundle_sha256)
+            refuseRunStart("publication_receipt_changed");
+        const owners = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.start_root_owned' AND json_extract(payload_json, '$.run_id') = ? LIMIT 2", [projectId, row.run_id]);
+        if (owners.length !== 1)
+            refuseRunStart("root_ownership_receipt_missing");
+        let owner;
+        try {
+            owner = JSON.parse(owners[0].payload_json);
+        }
+        catch {
+            return refuseRunStart("root_ownership_receipt_changed");
+        }
+        if (!object(owner) || owner.schema_id !== "dd-flow/run-start-owner@1" || owner.run_id !== row.run_id || owner.request_id !== requestId
+            || owner.allocation_sha256 !== row.payload_sha256 || hybridDigest(owner) !== publication.root_owner_sha256)
+            refuseRunStart("root_ownership_receipt_changed");
+    }
+    return { payload, payloadJson: row.payload_json, sha256: row.payload_sha256, published: Boolean(marker.publication_sha256) };
+}
+/** Lost markers/receipts cannot silently become legacy mutable execution. */
+export function assertRunStartupSettled(context, projectId, runId) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    let marker;
+    try {
+        marker = run ? JSON.parse(run.index_json).start_request : undefined;
+    }
+    catch {
+        return refuseRunStart("allocated_run_changed");
+    }
+    const row = hasRunStartTable(context) ? context.db.get("SELECT request_id FROM run_start_requests WHERE project_id = ? AND run_id = ?", [projectId, runId]) : undefined;
+    const audit = context.db.get("SELECT json_extract(payload_json, '$.request_id') AS request_id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.start_request' AND json_extract(payload_json, '$.run_id') = ? LIMIT 1", [projectId, runId]);
+    if (!marker && !row && !audit)
+        return;
+    if (!marker || !row || !audit || row.request_id !== marker.request_id || audit.request_id !== marker.request_id)
+        refuseRunStart("request_receipt_missing");
+    const retained = readRunStartRequest(context, projectId, marker.request_id);
+    if (!retained?.published)
+        throw new AppError("run_start_publication_pending", "Finish the original RUN creation request before lifecycle writes", 1, { effect: "no_effect", run_id: runId, request_id: marker.request_id, next_action: "reconcile_exact_request" });
+}