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

package/dist/services/descriptor-run-settlement.js

@@ -0,0 +1,107 @@
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { appendFlowRunTimelineEvent, assertPreparedRunBundleSqlAuthority, completeDescriptorRunState, gitFacts, publishRunProjections, readFlowRunExecutionBundle, withStageSettlement } from "./runs.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const event = "flow_run.descriptor_run_settlement";
+function refuse(reason) {
+    throw new AppError("descriptor_run_settlement_invalid", "Terminal descriptor RUN lacks exact settlement custody", 1, { reason, effect: "no_effect" });
+}
+function selected(context, scope, bundle, matchKeys) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const root = readDescriptorRootWork(context, scope, bundle);
+    const run = context.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+    const index = JSON.parse(run.index_json);
+    const terminal = index.stage_runs.at(-1);
+    if (!bundle.descriptor.descriptor.terminal_stages.includes(scope.stage)
+        || terminal?.stage !== scope.stage || terminal.status !== "done")
+        refuse("terminal_stage_not_accepted");
+    const data = readAcceptedStageData(context, scope);
+    const stageReceipt = readAcceptedDescriptorStageSettlement(context, scope, bundle, matchKeys);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id<>? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, root.workId])
+        || context.db.get("SELECT 1 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' LIMIT 1", [scope.projectId, scope.runId]))
+        refuse("work_still_active");
+    const prior = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+    if (prior.length > 1 || prior.some(row => Buffer.byteLength(row.payload_json) > 32 * 1024))
+        refuse("ambiguous_receipt");
+    if (root.status !== (prior.length ? "completed" : "running") || run.status !== (prior.length ? "done" : "running"))
+        refuse("terminal_state_changed");
+    return { rootId: root.workId, result: data.bytes.toString("utf8"), binding: { ...scope, work_id: root.workId, bundle_sha256: bundle.sha256, result_sha256: data.result.sha256, input_sha256: data.input_sha256, stage_receipt_sha256: hybridDigest(stageReceipt) }, prior: prior[0] ? JSON.parse(prior[0].payload_json) : null };
+}
+/** Runtime closure only. A terminal handler must first verify semantic/check/
+ * review/Git acceptance, revalidate physical proof, and supply its SQL fence.
+ * Transcript usage collection is deliberately outside this atomic writer.
+ */
+export class PreparedDescriptorRunSettlement {
+    #scope;
+    #bundle;
+    #owner;
+    #git;
+    #generation;
+    #matchKeys;
+    constructor(scope, bundle, owner, git, generation, matchKeys) {
+        this.#scope = scope;
+        this.#bundle = bundle;
+        this.#owner = owner;
+        this.#git = git;
+        this.#generation = generation;
+        this.#matchKeys = matchKeys;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), bundle = readFlowRunExecutionBundle(context, input);
+        if (!bundle)
+            refuse("bundle_required");
+        const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+        const matchKeys = entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, input.stage, input.projectRoot));
+        const snapshot = context.db.readSnapshot(() => ({ owner: selected(context, scope, bundle, matchKeys), generation: assertRunMutationAllowed(context, scope.projectId, scope.runId) }));
+        const operational = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const git = snapshot.owner.prior?.git ?? gitFacts(operational.workspace_root ?? operational.project_root);
+        return new PreparedDescriptorRunSettlement(scope, bundle, snapshot.owner, git, snapshot.generation, matchKeys);
+    }
+    apply(context, assertHandlerCustody) {
+        if (typeof assertHandlerCustody !== "function")
+            refuse("handler_fence_required");
+        const operational = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: operational.project_root, runId: this.#scope.runId });
+        if (!bundle || bundle.sha256 !== this.#bundle.sha256)
+            refuse("bundle_changed");
+        const observed = context.db.readSnapshot(() => selected(context, this.#scope, this.#bundle, this.#matchKeys));
+        if (!observed.prior && hybridDigest(gitFacts(operational.workspace_root ?? operational.project_root)) !== hybridDigest(this.#git))
+            refuse("git_observation_changed");
+        const receipt = { run_id: this.#scope.runId, work_id: this.#owner.rootId, binding: this.#owner.binding, git: this.#git };
+        const changed = withStageSettlement(context, () => {
+            assertRunMutationAllowed(context, this.#scope.projectId, this.#scope.runId, this.#generation);
+            assertHandlerCustody(context);
+            const current = selected(context, this.#scope, this.#bundle, this.#matchKeys);
+            if (hybridDigest(current.binding) !== hybridDigest(this.#owner.binding) || current.result !== this.#owner.result)
+                refuse("terminal_custody_changed");
+            if (current.prior) {
+                if (hybridDigest(current.prior) !== hybridDigest(receipt)
+                    || context.db.get("SELECT result FROM works WHERE work_id=?", [current.rootId])?.result !== current.result)
+                    refuse("settlement_changed");
+                return false;
+            }
+            if (this.#owner.prior)
+                refuse("settlement_receipt_missing");
+            const now = context.now();
+            if (context.db.run("UPDATE works SET status='completed',result=?,completed_at=?,updated_at=? WHERE work_id=? AND project_id=? AND run_id=? AND status='running'", [current.result, now, now, current.rootId, this.#scope.projectId, this.#scope.runId]).changes !== 1)
+                refuse("root_changed");
+            appendFlowRunTimelineEvent(context, this.#scope.projectId, this.#scope.runId, { at: now, type: "work_completed", work_id: current.rootId, descriptor_terminal: true });
+            completeDescriptorRunState(context, this.#scope, this.#bundle, this.#git);
+            appendAudit(context, { projectId: this.#scope.projectId, eventType: event, payload: receipt });
+            return true;
+        });
+        // A committed terminal receipt can outlive an interrupted file publisher.
+        // Replay restores projections from current SQL, without settling again.
+        publishRunProjections(context, this.#scope.projectId, this.#scope.runId);
+        return { changed, run_id: this.#scope.runId, work_id: this.#owner.rootId, status: "done" };
+    }
+}

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

@@ -0,0 +1,495 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { parseFullEntityId } from "../domain/entity-ids.js";
+import { projectRunHome, resolveProjectRoot } from "../storage/paths.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { admitBundledFlow, bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { PreparedMemoryInitRuntimeStorage } from "./memory-init-storage.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+import { prepareFlowRunStart, publishRunProjections, readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority, runBundleAuthorityMetadata } from "./runs.js";
+import { readRunStartRequest, refuseRunStart, runStartBytesSha256, runStartPayloadLimit } from "./run-start-custody.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { allocateDescriptorRootWork, readDescriptorRootWork } from "./descriptor-root-work.js";
+import { nextRunId } from "./ids.js";
+import { readMemoryInitRunAllocation } from "./memory-init-run-allocation.js";
+import { readMemoryUpgradeEvidence, readMemoryUpgradeTargetEvidence, upgradeEvidenceFilePath, upgradeEvidenceIndexPath, upgradeTargetIndexPath } from "./memory-upgrade-evidence.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { assertMemoryFixRequestBundle } from "./memory-fix-request.js";
+import { assertInteractiveRequestBundle, revalidateInteractiveEntryWorkspace } from "./interactive-request.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+import { assertDeliveryRequestBundle } from "./delivery-request.js";
+const encode = (value) => Buffer.from(JSON.stringify(value));
+const owner = (directory) => {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory())
+        refuseRunStart("linked_or_missing_directory");
+    return { dev: stat.dev, ino: stat.ino };
+};
+export function observeDescriptorWorkspace(context, projectRoot, workspaceRoot, gitExecutable = "git") {
+    const env = Object.fromEntries(Object.entries({ ...process.env, ...context.env }).filter(([key]) => !key.startsWith("GIT_")));
+    const read = (root, args, optional = false) => {
+        const result = spawnSync(gitExecutable, ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false", "-C", root, ...args], { env: { ...env, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || !optional && result.status !== 0)
+            refuseRunStart("git_observation_failed");
+        return result.status === 0 ? result.stdout : null;
+    };
+    const common = (root) => {
+        if (read(root, ["rev-parse", "--is-bare-repository"])?.trim() !== "false"
+            || resolveProjectRoot(read(root, ["rev-parse", "--show-toplevel"]).trim()) !== root)
+            refuseRunStart("not_repository_root");
+        return fs.realpathSync(path.resolve(root, read(root, ["rev-parse", "--git-common-dir"]).trim()));
+    };
+    if (common(projectRoot) !== common(workspaceRoot))
+        refuseRunStart("foreign_workspace");
+    const branch = read(workspaceRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"], true)?.trim();
+    if (!branch)
+        refuseRunStart("workspace_branch_unavailable");
+    return { branch, head: read(workspaceRoot, ["rev-parse", "--verify", "HEAD"], true)?.trim() ?? null,
+        status_sha256: runStartBytesSha256(read(workspaceRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"])) };
+}
+function project(context, projectRoot) {
+    const selected = context.db.get("SELECT id, root, status FROM projects WHERE root = ?", [projectRoot]);
+    if (!selected || selected.status !== "active" || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(selected.id))
+        refuseRunStart("project_not_registered_or_active");
+    return selected;
+}
+/** Select before building the bundle; an existing request keeps its original ID. */
+export function nextDescriptorRunId(context, input) {
+    const root = resolveProjectRoot(input.projectRoot), selected = project(context, root), prior = readRunStartRequest(context, selected.id, input.requestId);
+    if (prior)
+        return prior.payload.run_id;
+    return nextRunId(context, selected.id, input.slug);
+}
+/** SQL-only: mb-init consumes its independently retained reservation, never
+ * a caller-provided id or whichever sequence happens to be available now. */
+function assertRunIdentity(context, projectId, bundle, fresh) {
+    if (bundle.manifest.flow_id === "mb-init") {
+        const scope = bundle.execution.snapshot().scope;
+        const allocation = readMemoryInitRunAllocation(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+        if (!allocation || allocation.project_id !== projectId || allocation.run_id !== bundle.manifest.run_id)
+            refuseRunStart("memory_run_reservation_changed");
+        memoryBootstrap(context, projectId, bundle);
+    }
+    else if (fresh && nextRunId(context, projectId, parseFullEntityId(bundle.manifest.run_id).slug) !== bundle.manifest.run_id)
+        refuseRunStart("run_id_changed");
+    if (fresh && (["mb-fix", "interactive"].includes(bundle.manifest.flow_id) || isDeliveryFlow(bundle.manifest.flow_id)))
+        memoryBootstrap(context, projectId, bundle);
+}
+function compatibleSdlcProfile(bundle, profile, home) {
+    if (!profile?.settings.execution || !profile.agent_profiles || profile.settings.stage_session_mode !== bundle.execution.settings.stage_session_mode)
+        refuseRunStart("sdlc_policy_not_frozen");
+    for (const stage of bundle.descriptor.descriptor.stages) {
+        const route = resolveExecutionPolicy({ ddFlowHome: home, policy: profile.settings.execution, profiles: profile.agent_profiles, stage: stage.id });
+        if (hybridDigest(route.coordinator) !== hybridDigest(bundle.execution.stage(stage.id).profile)
+            || route.delegation.mode !== bundle.execution.settings.delegation.mode
+            || route.delegation.mode === "external" && route.delegation.max_parallel !== bundle.execution.settings.delegation.max_parallel
+            || !bundle.execution.snapshot().profiles.some(value => hybridDigest(value.profile) === hybridDigest(route.worker)))
+            refuseRunStart("sdlc_frozen_route_mismatch");
+    }
+}
+function memoryBootstrap(context, projectId, bundle) {
+    if (bundle.descriptor.descriptor.id === "sdlc")
+        return;
+    if (bundle.manifest.flow_id === "mb-fix") {
+        assertMemoryFixRequestBundle(context, projectId, bundle);
+        return;
+    }
+    if (bundle.manifest.flow_id === "interactive") {
+        assertInteractiveRequestBundle(context, projectId, bundle);
+        return;
+    }
+    if (isDeliveryFlow(bundle.manifest.flow_id)) {
+        assertDeliveryRequestBundle(context, projectId, bundle);
+        return;
+    }
+    const scope = bundle.execution.snapshot().scope;
+    if (isSourceSnapshotFlow(bundle.manifest.flow_id)) {
+        const snapshot = readDiagnosticSnapshotCustody(context, { projectId, projectRoot: scope.projectRoot,
+            sourceRoot: scope.projectRoot, requestId: scope.requestId, flowId: bundle.manifest.flow_id });
+        if (!snapshot || snapshot.root !== scope.workspace || bundle.manifest.bootstrap_receipts.length !== 0)
+            refuseRunStart("diagnostic_snapshot_authority_changed");
+        return;
+    }
+    if (bundle.descriptor.descriptor.id === "mb-init") {
+        const retained = readMemoryInitBootstrapReadiness(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+        const reference = bundle.manifest.bootstrap_receipts[0];
+        if (!retained || retained.projectId !== projectId || bundle.manifest.bootstrap_receipts.length !== 1 || !reference
+            || retained.authority.binding.execution_sha256 !== bundle.execution.sha256
+            || !bundle.blob(bundle.manifest.engine_manifest.path).equals(Buffer.from(retained.authority.binding.engine_manifest_base64, "base64"))
+            || retained.authority.bootstrap_sha256 !== reference.sha256
+            || !bundle.blob(reference.path).equals(encode(retained.authority.receipt)))
+            refuseRunStart("memory_bootstrap_authority_changed");
+        return;
+    }
+    if (bundle.descriptor.descriptor.id !== "mb-upgrade")
+        refuseRunStart("unsupported_memory_bootstrap");
+    const retained = readMemoryUpgradeBootstrapReadiness(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+    const reference = bundle.manifest.bootstrap_receipts[0];
+    if (!retained || !retained.hasPreservationBaseline || !retained.hasLintCapability || !retained.hasGitPolicy || !retained.hasFlowCapability || retained.projectId !== projectId || bundle.manifest.bootstrap_receipts.length !== 1 || !reference
+        || retained.authority.binding.execution_sha256 !== bundle.execution.sha256
+        || !bundle.blob(bundle.manifest.engine_manifest.path).equals(Buffer.from(retained.authority.binding.engine_manifest_base64, "base64"))
+        || retained.authority.bootstrap_sha256 !== reference.sha256
+        || !bundle.blob(reference.path).equals(encode(retained.authority.receipt)))
+        refuseRunStart("memory_bootstrap_authority_changed");
+}
+function observeRunWorkspace(context, bundle, projectId) {
+    const scope = bundle.execution.snapshot().scope;
+    if (!isSourceSnapshotFlow(bundle.manifest.flow_id))
+        return observeDescriptorWorkspace(context, scope.projectRoot, scope.workspace);
+    const snapshot = readDiagnosticSnapshot(context, { projectId, projectRoot: scope.projectRoot,
+        sourceRoot: scope.projectRoot, requestId: scope.requestId, flowId: bundle.manifest.flow_id });
+    if (!snapshot || snapshot.root !== scope.workspace)
+        refuseRunStart("diagnostic_snapshot_authority_changed");
+    return observeDescriptorWorkspace(context, snapshot.root, snapshot.root);
+}
+/** RUN allocation and SQL bundle authority are one request-owned transaction.
+ * Physical publication is separate, replayable and gates lifecycle writes.
+ * This does not register missing handlers or qualify a provider/storage route.
+ */
+export class PreparedDescriptorRunStart {
+    requestSha256;
+    #payload;
+    #payloadJson;
+    #sha256;
+    #bundle;
+    #storage;
+    constructor(payload, payloadJson, bundle, storage) {
+        this.#payload = structuredClone(payload);
+        this.#payloadJson = payloadJson;
+        this.#sha256 = runStartBytesSha256(payloadJson);
+        this.#bundle = bundle;
+        this.#storage = storage;
+        this.requestSha256 = payload.request_sha256;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle))
+            refuseRunStart("unprepared_bundle");
+        const bundle = input.bundle, scope = bundle.execution.snapshot().scope;
+        const blobs = new Map(bundle.manifest.inventory.map(value => [value.path, bundle.blob(value.path)]));
+        admitBundledFlow(bundle.blob(bundle.manifest.descriptor.path), bundle.manifest.descriptor.sha256, blobs);
+        bundle.engine();
+        if (resolveProjectRoot(scope.projectRoot) !== scope.projectRoot || resolveProjectRoot(scope.workspace) !== scope.workspace)
+            refuseRunStart("noncanonical_scope");
+        const selected = project(context, scope.projectRoot), parsedId = parseFullEntityId(bundle.manifest.run_id);
+        if (parsedId.type !== "RUN")
+            refuseRunStart("invalid_run_id");
+        const subjectId = input.subjectId ?? scope.requestId, subjectType = input.subjectType ?? "flow_request";
+        if (![subjectId, subjectType].every(value => typeof value === "string" && Boolean(value.trim()) && value.length <= 1024))
+            refuseRunStart("invalid_subject");
+        const requestSha256 = hybridDigest({ scope, bundle_sha256: bundle.sha256, subject_id: subjectId, subject_type: subjectType });
+        const prior = readRunStartRequest(context, selected.id, scope.requestId), storage = PreparedMemoryInitRuntimeStorage.prepare(context);
+        assertRunIdentity(context, selected.id, bundle, !prior);
+        if (prior) {
+            if (prior.payload.request_sha256 !== requestSha256 || prior.payload.run_id !== bundle.manifest.run_id)
+                refuseRunStart("request_changed");
+            const prepared = new PreparedDescriptorRunStart(prior.payload, prior.payloadJson, bundle, storage);
+            if (!prior.published)
+                prepared.revalidatePhysical(context);
+            return prepared;
+        }
+        if (bundle.manifest.flow_id !== "mb-init")
+            memoryBootstrap(context, selected.id, bundle);
+        const home = fs.realpathSync(context.ddFlowHome), runRoot = projectRunHome(home, selected.id, bundle.manifest.run_id);
+        if (fs.existsSync(runRoot))
+            refuseRunStart("foreign_run_root");
+        const facts = observeRunWorkspace(context, bundle, selected.id), now = context.now(), artifacts = [
+            { path: "engine-binding.json", base64: bundle.blob(bundle.manifest.engine_binding.path).toString("base64") }
+        ];
+        const isSdlc = bundle.descriptor.descriptor.id === "sdlc", flowKind = isSdlc ? "vnext_specify" : bundle.descriptor.descriptor.id;
+        if (!["vnext_specify", "mb-init", "mb-upgrade", "mb-fix", "interactive"].includes(flowKind) && !isSourceSnapshotFlow(flowKind) && !isDeliveryFlow(flowKind))
+            refuseRunStart("unsupported_flow_kind");
+        if (flowKind === "mb-upgrade") {
+            const upgradeScope = { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace };
+            artifacts.push(...readMemoryUpgradeEvidence(context, upgradeScope).artifacts, ...readMemoryUpgradeTargetEvidence(context, upgradeScope).artifacts);
+        }
+        const legacy = isSdlc ? prepareFlowRunStart(context, { projectRoot: scope.projectRoot, workspaceRoot: scope.workspace,
+            flowKind, subjectId, subjectType, slug: parsedId.slug }) : undefined;
+        const profile = legacy?.executionProfile;
+        if (isSdlc)
+            compatibleSdlcProfile(bundle, profile, home);
+        if (profile) {
+            const decision = profile.operational_decision;
+            const policy = decision ? readBoundedReleaseFile(path.resolve(scope.projectRoot, decision.policy.path), 1024 * 1024) : undefined;
+            if (policy && runStartBytesSha256(policy) !== decision.policy.sha256)
+                refuseRunStart("operational_policy_changed");
+            const policySource = policy ? { path: "operational-policy.source.md", sha256: runStartBytesSha256(policy) } : undefined;
+            const binding = { project_id: selected.id, run_id: bundle.manifest.run_id, project_root: scope.projectRoot,
+                ...(decision?.scope.eval_id ? { eval_id: decision.scope.eval_id } : {}),
+                ...(decision?.scope.execution_id ? { execution_id: decision.scope.execution_id } : {}) };
+            const contract = encode({ schema_id: "dd-flow/run-operational-contract@1", binding,
+                settings: { merge_delivery: profile.settings.merge_delivery, merge_cleanup: profile.settings.merge_cleanup },
+                ...(decision ? { decision } : {}), ...(policySource ? { policy_source: policySource } : {}) });
+            profile.operational_contract = { path: "operational-contract.json", sha256: runStartBytesSha256(contract), ...(policySource ? { policy_source: policySource } : {}), binding };
+            if (policy && policySource)
+                artifacts.push({ path: policySource.path, base64: policy.toString("base64") });
+            artifacts.push({ path: "operational-contract.json", base64: contract.toString("base64") });
+        }
+        const initial = { schema_id: "dd-flow/flow-run@3", run_id: bundle.manifest.run_id, short_id: parsedId.shortId,
+            flow_kind: flowKind, subject: { id: subjectId, title: subjectId }, project: { id: selected.id, title: path.basename(selected.root) },
+            workspace: { project_root: scope.projectRoot, workspace_path: scope.workspace, branch: facts.branch, base: facts.head ?? "unborn" },
+            run_home: { storage: "dd_flow_home", path: runRoot, relative_path: path.posix.join("runs", bundle.manifest.run_id) },
+            execution: { project_root: scope.projectRoot, workspace_root: scope.workspace, git: { branch: facts.branch, head: facts.head, status: facts.status_sha256 === runStartBytesSha256("") ? "clean" : "dirty" } },
+            stage_runs: [], sessions: [], status: "running", verdict: "pending", next_action: null,
+            created_at: now, updated_at: now, started_at: now, timing_status: "measured", runtime_revision: 1,
+            execution_bundle: runBundleAuthorityMetadata(bundle).anchor,
+            ...(legacy ? { flow_flags: legacy.flowFlags, snapshot_revision: legacy.flowFlags.snapshot_revision, snapshot_checksum: legacy.flowFlags.snapshot_checksum,
+                reconciliation_status: "reconciled", execution_profile: profile,
+                verification_matrix_contract: "dd-flow/verification-matrix@1", final_check_coverage_contract: "dd-flow/final-check-coverage@1",
+                settings: { plan_review: { mode: profile.settings.plan_review_mode, source: "default", reason: "Frozen SDLC policy", updated_at: now },
+                    code_review: { mode: profile.settings.code_review_mode, source: "default", reason: "Frozen SDLC policy", updated_at: now } } } : {}) };
+        const payload = { schema_id: "dd-flow/run-start-allocation@1", request_id: scope.requestId, project_id: selected.id,
+            project_root: scope.projectRoot, workspace_root: scope.workspace, home_root: home, run_id: bundle.manifest.run_id, run_root: runRoot,
+            subject_id: subjectId, subject_type: subjectType, slug: parsedId.slug, request_sha256: requestSha256, bundle_sha256: bundle.sha256, initial_index: initial,
+            bundle_manifest_base64: bundle.manifestBytes().toString("base64"), blobs: [...blobs].map(([logical, bytes]) => ({ path: logical, base64: bytes.toString("base64") })), artifacts,
+            owners: { home: owner(home), project: owner(scope.projectRoot), workspace: owner(scope.workspace) }, git: facts };
+        const payloadJson = JSON.stringify(payload);
+        if (Buffer.byteLength(payloadJson) > runStartPayloadLimit)
+            refuseRunStart("allocation_exceeds_bound");
+        return new PreparedDescriptorRunStart(payload, payloadJson, bundle, storage);
+    }
+    static restore(context, input) {
+        const selected = project(context, resolveProjectRoot(input.projectRoot)), retained = readRunStartRequest(context, selected.id, input.requestId);
+        if (!retained)
+            refuseRunStart("request_receipt_missing");
+        const payload = retained.payload, row = context.db.get("SELECT admission_json FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [selected.id, payload.run_id]);
+        if (!row)
+            refuseRunStart("bundle_authority_missing");
+        let admission;
+        try {
+            admission = JSON.parse(row.admission_json);
+        }
+        catch {
+            return refuseRunStart("bundle_authority_invalid");
+        }
+        if (!admission || Buffer.byteLength(row.admission_json) > 1024 * 1024 || !Array.isArray(admission.receipts)
+            || hybridDigest(admission) !== payload.initial_index.execution_bundle?.admission_sha256
+            || admission.receipts.some(value => !Array.isArray(value) || value.length !== 2 || typeof value[0] !== "string")
+            || new Set(admission.receipts.map(value => value[0])).size !== admission.receipts.length)
+            refuseRunStart("bundle_authority_invalid");
+        const bundle = RetainedExecutionBundle.admit(Buffer.from(payload.bundle_manifest_base64, "base64"), payload.bundle_sha256, new Map(payload.blobs.map(value => [value.path, Buffer.from(value.base64, "base64")])), { ...admission, receipts: new Map(admission.receipts), descriptorContext: bundledHandlerContext(new Map()) });
+        return PreparedDescriptorRunStart.prepare(context, { bundle, subjectId: payload.subject_id, subjectType: payload.subject_type });
+    }
+    revalidateDirectoryOwners(context) {
+        const p = this.#payload;
+        if (fs.realpathSync(context.ddFlowHome) !== p.home_root || hybridDigest(owner(p.home_root)) !== hybridDigest(p.owners.home)
+            || hybridDigest(owner(p.project_root)) !== hybridDigest(p.owners.project) || hybridDigest(owner(p.workspace_root)) !== hybridDigest(p.owners.workspace))
+            refuseRunStart("physical_scope_changed");
+    }
+    revalidatePhysical(context) {
+        this.revalidateDirectoryOwners(context);
+        if (this.#bundle.manifest.flow_id === "interactive")
+            revalidateInteractiveEntryWorkspace(context, this.#bundle);
+        const p = this.#payload;
+        if (hybridDigest(observeRunWorkspace(context, this.#bundle, p.project_id)) !== hybridDigest(p.git))
+            refuseRunStart("physical_scope_changed");
+        this.#bundle.engine();
+    }
+    apply(context, checkpoint) {
+        const p = this.#payload, prior = readRunStartRequest(context, p.project_id, p.request_id);
+        if (prior && prior.sha256 !== this.#sha256)
+            refuseRunStart("request_changed");
+        assertRunIdentity(context, p.project_id, this.#bundle, !prior);
+        if (prior?.published) {
+            this.#storage.assertCompatibility(context);
+            this.revalidateDirectoryOwners(context);
+            if (project(context, p.project_root).id !== p.project_id)
+                refuseRunStart("physical_scope_changed");
+            const owned = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.start_root_owned' AND json_extract(payload_json, '$.run_id') = ?", [p.project_id, p.run_id]);
+            const rootOwner = JSON.parse(owned.payload_json);
+            let ancestor = p.home_root;
+            for (const part of path.relative(p.home_root, p.run_root).split(path.sep)) {
+                ancestor = path.join(ancestor, part);
+                owner(ancestor);
+            }
+            const ownerFile = path.join(p.run_root, "run-start-owner.json");
+            if (hybridDigest(owner(p.run_root)) !== hybridDigest(rootOwner.owner) || fs.lstatSync(ownerFile).nlink !== 1
+                || !readBoundedReleaseFile(ownerFile, 1024 * 1024).equals(encode(rootOwner)))
+                refuseRunStart("run_root_owner_changed");
+            assertPreparedRunBundleSqlAuthority(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+            readDescriptorRootWork(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+            if (readFlowRunExecutionBundle(context, { projectRoot: p.project_root, runId: p.run_id })?.sha256 !== p.bundle_sha256)
+                refuseRunStart("bundle_changed");
+            publishRunProjections(context, p.project_id, p.run_id);
+            return { runId: p.run_id, bundleSha256: p.bundle_sha256, changed: false };
+        }
+        this.revalidatePhysical(context);
+        const metadata = runBundleAuthorityMetadata(this.#bundle);
+        let allocated = Boolean(prior);
+        try {
+            context.db.writeTransaction(() => {
+                this.#storage.assertCompatibility(context);
+                const replay = readRunStartRequest(context, p.project_id, p.request_id);
+                assertRunIdentity(context, p.project_id, this.#bundle, !replay);
+                if (replay) {
+                    if (replay.sha256 !== this.#sha256)
+                        refuseRunStart("request_changed");
+                    assertPreparedRunBundleSqlAuthority(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+                    readDescriptorRootWork(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+                    return;
+                }
+                if (project(context, p.project_root).id !== p.project_id)
+                    refuseRunStart("run_id_changed");
+                const index = { ...p.initial_index, start_request: { schema_id: "dd-flow/run-start-request@1", request_id: p.request_id, request_sha256: p.request_sha256, allocation_sha256: this.#sha256 } };
+                context.db.run(`INSERT INTO runs (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
+          status, verdict, next_action, runtime_path, run_dir, run_index_path, run_home_path, run_root, layout_version, artifact_root_kind, index_json, created_at, updated_at, completed_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', 'pending', NULL, ?, ?, ?, ?, ?, 'home_run_v2', 'dd_flow_home', ?, ?, ?, NULL)`, [p.run_id, p.initial_index.short_id, p.slug, p.project_id, p.project_root, p.workspace_root, p.initial_index.flow_kind, p.subject_type, p.subject_id,
+                    path.join(p.run_root, "run.json"), p.run_root, path.join(p.run_root, "run.json"), p.run_root, p.run_root, JSON.stringify(index), p.initial_index.created_at, p.initial_index.updated_at]);
+                context.db.execSchema(`CREATE TABLE IF NOT EXISTS run_bundle_authorities (project_id TEXT NOT NULL, run_id TEXT NOT NULL, manifest_sha256 TEXT NOT NULL,
+          admission_json TEXT NOT NULL, PRIMARY KEY(project_id, run_id), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id));
+          CREATE TABLE IF NOT EXISTS run_start_requests (project_id TEXT NOT NULL, request_id TEXT NOT NULL, run_id TEXT NOT NULL, payload_json TEXT NOT NULL,
+          payload_sha256 TEXT NOT NULL, PRIMARY KEY(project_id, request_id), UNIQUE(project_id, run_id), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id))`);
+                context.db.run("INSERT INTO run_bundle_authorities (project_id, run_id, manifest_sha256, admission_json) VALUES (?, ?, ?, ?)", [p.project_id, p.run_id, p.bundle_sha256, metadata.admissionJson]);
+                context.db.run("INSERT INTO run_start_requests (project_id, request_id, run_id, payload_json, payload_sha256) VALUES (?, ?, ?, ?, ?)", [p.project_id, p.request_id, p.run_id, this.#payloadJson, this.#sha256]);
+                appendAudit(context, { projectId: p.project_id, eventType: "flow_run.start_request", payload: { run_id: p.run_id, request_id: p.request_id, request_sha256: p.request_sha256, allocation_sha256: this.#sha256 } });
+                appendAudit(context, { projectId: p.project_id, eventType: "flow_run.started", payload: { run_id: p.run_id, flow_kind: p.initial_index.flow_kind, subject: p.initial_index.subject, workspace_root: p.workspace_root, run_home: p.run_root } });
+                assertPreparedRunBundleSqlAuthority(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+                allocateDescriptorRootWork(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+            }, "runs.allocateDescriptorStart");
+            allocated = true;
+            checkpoint?.("allocated");
+            const lock = acquireInstallationLock(path.join(p.home_root, `.run-start-${hybridDigest({ project_id: p.project_id, request_id: p.request_id })}.lock`), this.#sha256);
+            let failed = false, failure;
+            try {
+                this.publish(context, checkpoint);
+            }
+            catch (error) {
+                failed = true;
+                failure = error;
+            }
+            try {
+                lock.release();
+            }
+            catch (error) {
+                if (!failed)
+                    throw error;
+                if (failure instanceof AppError)
+                    failure.details.lock_cleanup_failed = true;
+                else
+                    failure = new AppError("run_start_publication_failed", "Original publication failure retained; lock cleanup also failed", 1, { reason: "publication_failed", lock_cleanup_failed: true });
+            }
+            if (failed)
+                throw failure;
+            return { runId: p.run_id, bundleSha256: p.bundle_sha256, changed: true };
+        }
+        catch (error) {
+            throw new AppError("run_start_incomplete", "RUN creation requires exact-request reconciliation", 1, { reason: error instanceof AppError ? error.details.reason ?? error.code : "publication_failed", effect: allocated ? "partial" : "no_effect", run_id: p.run_id, request_id: p.request_id,
+                ...(error instanceof AppError && error.details.lock_cleanup_failed ? { lock_cleanup_failed: true } : {}), next_action: "reconcile_exact_request" });
+        }
+    }
+    publish(context, checkpoint) {
+        const p = this.#payload;
+        this.revalidatePhysical(context);
+        let current = p.home_root;
+        for (const part of path.relative(p.home_root, path.dirname(p.run_root)).split(path.sep)) {
+            current = path.join(current, part);
+            if (!fs.existsSync(current))
+                fs.mkdirSync(current, { mode: 0o700 });
+            owner(current);
+        }
+        const owned = 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", [p.project_id, p.run_id]);
+        let rootOwner;
+        if (fs.existsSync(p.run_root)) {
+            if (owned.length !== 1)
+                refuseRunStart("root_ownership_receipt_missing");
+            rootOwner = JSON.parse(owned[0].payload_json);
+            if (!rootOwner || rootOwner.schema_id !== "dd-flow/run-start-owner@1" || rootOwner.run_id !== p.run_id || rootOwner.allocation_sha256 !== this.#sha256 || rootOwner.request_id !== p.request_id
+                || hybridDigest(rootOwner.owner) !== hybridDigest(owner(p.run_root)))
+                refuseRunStart("run_root_owner_changed");
+            if (fs.lstatSync(path.join(p.run_root, "run-start-owner.json")).nlink !== 1 || !readBoundedReleaseFile(path.join(p.run_root, "run-start-owner.json"), 1024 * 1024).equals(encode(rootOwner)))
+                refuseRunStart("run_root_owner_changed");
+        }
+        else {
+            if (owned.length)
+                refuseRunStart("owned_run_root_missing");
+            fs.mkdirSync(p.run_root, { mode: 0o700 });
+            rootOwner = { schema_id: "dd-flow/run-start-owner@1", run_id: p.run_id, request_id: p.request_id, allocation_sha256: this.#sha256, owner: owner(p.run_root) };
+            fs.writeFileSync(path.join(p.run_root, "run-start-owner.json"), encode(rootOwner), { flag: "wx", mode: 0o600 });
+            context.db.writeTransaction(() => {
+                this.#storage.assertCompatibility(context);
+                if (readRunStartRequest(context, p.project_id, p.request_id)?.sha256 !== this.#sha256)
+                    refuseRunStart("allocation_changed");
+                appendAudit(context, { projectId: p.project_id, eventType: "flow_run.start_root_owned", payload: rootOwner });
+            }, "runs.retainStartRootOwner");
+        }
+        checkpoint?.("root_owned");
+        const assertPhysicalOwner = () => {
+            // Every write needs path custody, not another whole-workspace Git probe.
+            // Git/engine are fenced around the batch and before SQL acceptance.
+            this.revalidateDirectoryOwners(context);
+            let ancestor = p.home_root;
+            for (const part of path.relative(p.home_root, p.run_root).split(path.sep)) {
+                ancestor = path.join(ancestor, part);
+                owner(ancestor);
+            }
+            if (hybridDigest(owner(p.run_root)) !== hybridDigest(rootOwner.owner))
+                refuseRunStart("run_root_owner_changed");
+            const file = path.join(p.run_root, "run-start-owner.json");
+            if (fs.lstatSync(file).nlink !== 1 || !readBoundedReleaseFile(file, 1024 * 1024).equals(encode(rootOwner)))
+                refuseRunStart("run_root_owner_changed");
+        };
+        for (const artifact of p.artifacts) {
+            assertPhysicalOwner();
+            const file = path.join(p.run_root, artifact.path), bytes = Buffer.from(artifact.base64, "base64");
+            if (fs.existsSync(file)) {
+                const limit = [upgradeEvidenceIndexPath, upgradeTargetIndexPath, upgradeEvidenceFilePath(runStartBytesSha256(bytes))].includes(artifact.path) ? 16 * 1024 * 1024 : 1024 * 1024;
+                if (fs.lstatSync(file).nlink !== 1 || !readBoundedReleaseFile(file, limit).equals(bytes))
+                    refuseRunStart("start_artifact_changed");
+            }
+            else
+                fs.writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
+        }
+        assertPhysicalOwner();
+        this.revalidatePhysical(context);
+        this.#bundle.materialize(p.run_root);
+        checkpoint?.("bundle_published");
+        const physical = readFlowRunExecutionBundle(context, { projectRoot: p.project_root, runId: p.run_id });
+        if (physical?.sha256 !== p.bundle_sha256)
+            refuseRunStart("bundle_changed");
+        assertPhysicalOwner();
+        this.revalidatePhysical(context);
+        context.db.writeTransaction(() => {
+            this.#storage.assertCompatibility(context);
+            const retained = readRunStartRequest(context, p.project_id, p.request_id);
+            if (!retained || retained.sha256 !== this.#sha256)
+                refuseRunStart("allocation_changed");
+            if (project(context, p.project_root).id !== p.project_id)
+                refuseRunStart("project_not_registered_or_active");
+            assertPreparedRunBundleSqlAuthority(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+            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", [p.project_id, p.run_id]);
+            if (owners.length !== 1 || owners[0].payload_json !== JSON.stringify(rootOwner))
+                refuseRunStart("root_ownership_receipt_changed");
+            if (retained.published)
+                return;
+            const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [p.project_id, p.run_id]);
+            const index = JSON.parse(run.index_json);
+            const root = readDescriptorRootWork(context, { projectId: p.project_id, runId: p.run_id }, this.#bundle);
+            if (root.status !== "created" || index.stage_runs.length || index.sessions.length
+                || context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND work_id <> ? LIMIT 1", [p.project_id, p.run_id, root.workId])
+                || context.db.get("SELECT 1 FROM work_sessions WHERE work_id=? LIMIT 1", [root.workId])
+                || context.db.get("SELECT 1 FROM sessions WHERE project_id = ? AND run_id = ? LIMIT 1", [p.project_id, p.run_id])
+                || context.db.get("SELECT 1 FROM run_recovery_guards WHERE project_id = ? AND run_id = ? LIMIT 1", [p.project_id, p.run_id])
+                || context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_controllers'")
+                    && context.db.get("SELECT 1 FROM run_controllers WHERE project_id = ? AND run_id = ? LIMIT 1", [p.project_id, p.run_id]))
+                refuseRunStart("run_started_before_publication");
+            const receipt = { schema_id: "dd-flow/run-start-publication@1", request_id: p.request_id, run_id: p.run_id, allocation_sha256: this.#sha256,
+                bundle_sha256: p.bundle_sha256, root_owner_sha256: hybridDigest(rootOwner) };
+            appendAudit(context, { projectId: p.project_id, eventType: "flow_run.start_published", payload: receipt });
+            index.start_request.publication_sha256 = hybridDigest(receipt);
+            index.runtime_revision = (index.runtime_revision ?? 0) + 1;
+            context.db.run("UPDATE runs SET index_json = ? WHERE project_id = ? AND id = ? AND index_json = ?", [JSON.stringify(index), p.project_id, p.run_id, run.index_json]);
+            if (!readRunStartRequest(context, p.project_id, p.request_id)?.published)
+                refuseRunStart("publication_not_committed");
+            context.db.afterCommit(() => publishRunProjections(context, p.project_id, p.run_id));
+        }, "runs.acceptStartPublication");
+        checkpoint?.("published");
+    }
+}