@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/descriptor-coordinator-session.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { readDescriptorStageInput, readDescriptorStageInputForRecovery } from "./descriptor-stage-coordinator.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** SQL-only physical coordinator proof, independent of allocation/prompt
+ * custody. It creates no Session, hook claim or provider operation.
+ */
+export function readDescriptorCoordinatorSession(context, input, refuse = reason => {
+    throw new AppError("descriptor_coordinator_session_invalid", "Coordinator has no matching physical Session custody", 1, { reason, effect: "no_effect" });
+}) {
+    const { scope, bundle, workId } = input;
+    const rows = context.db.all("SELECT ws.id,ws.session_id,ws.hook_event_id,ws.prompt_path,ws.result_path,s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.session_id=ws.session_id AND s.project_id=? WHERE ws.work_id=? AND ws.status='running' AND s.run_id=? AND s.current_stage=? AND s.status='active' LIMIT 2", [scope.projectId, workId, scope.runId, scope.stage]);
+    if (rows.length !== 1)
+        refuse("active_coordinator_session_required");
+    const session = rows[0], route = bundle.execution.stage(scope.stage);
+    const selected = input.recoveryRead ? readDescriptorStageInputForRecovery(context, scope, bundle, input.recoveryRead) : readDescriptorStageInput(context, scope, bundle), directory = bundle.descriptor.stage(scope.stage).directory;
+    if (session.prompt_path !== path.join(selected.runRoot, directory, "coordinator-prompt.md")
+        || session.result_path !== path.join(selected.runRoot, directory, "result-input.json"))
+        refuse("coordinator_packet_link_changed");
+    if (session.harness !== runtimeHarness(route.profile)
+        || !context.db.get("SELECT 1 FROM hook_events WHERE project_id=? AND event_key=? AND session_id=? AND harness=? AND provider_session_id=? AND status='claimed' AND event_name='PreToolUse'", [scope.projectId, session.hook_event_id, session.session_id, session.harness, session.provider_session_id]))
+        refuse("coordinator_start_custody_missing");
+    const bindings = 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')=? LIMIT 33", [scope.projectId, scope.runId, scope.stage, session.id]);
+    if (!bindings.length || bindings.length > 32 || bindings.some(row => Buffer.byteLength(row.payload_json) > 32768))
+        refuse("physical_binding_missing");
+    const binding = JSON.parse(bindings[0].payload_json);
+    if (bindings.some(row => hybridDigest(JSON.parse(row.payload_json)) !== hybridDigest(binding))
+        || binding.work_id !== workId || binding.session_id !== session.session_id || binding.harness !== session.harness || binding.provider_session_id !== session.provider_session_id
+        || binding.execution_sha256 !== bundle.execution.sha256 || binding.profile_id !== route.profile.id || binding.profile_sha256 !== hybridDigest(route.profile)
+        || binding.session_mode !== route.session_mode || hybridDigest(binding.scope) !== hybridDigest({ ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: scope.stage }))
+        refuse("physical_binding_changed");
+    return hybridDigest({ session, binding });
+}

package/dist/services/descriptor-root-work.js

@@ -0,0 +1,53 @@
+import { AppError } from "../shared/errors.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { nextWorkId } from "./ids.js";
+import { appendAudit } from "./audit.js";
+const event = "flow_run.descriptor_root_work";
+function refuse(reason) {
+    throw new AppError("descriptor_root_work_invalid", "RUN root Work lacks independent allocation custody", 1, { reason, effect: "no_effect" });
+}
+const binding = (scope, bundle) => ({ projectId: scope.projectId, runId: scope.runId, bundle_sha256: bundle.sha256 });
+/** SQL-only read. Root identity is retained independently, never discovered
+ * from an arbitrary root row or reconstructed after receipt loss.
+ */
+export function readDescriptorRootWork(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const receipts = 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 (receipts.length !== 1 || Buffer.byteLength(receipts[0].payload_json) > 16 * 1024)
+            refuse("root_work_receipt_missing");
+        const receipt = JSON.parse(receipts[0].payload_json);
+        const expected = binding(scope, bundle);
+        if (typeof receipt.work_id !== "string" || hybridDigest(receipt) !== hybridDigest({ run_id: scope.runId, work_id: receipt.work_id, binding: expected }))
+            refuse("root_work_changed");
+        const roots = context.db.all("SELECT work_id,task,payload_json,status,launch_policy,result_schema,depends_on_json FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL LIMIT 2", [scope.projectId, scope.runId]);
+        if (roots.length !== 1)
+            refuse("ambiguous_root_work");
+        const root = roots[0];
+        if (root.work_id !== receipt.work_id || root.task !== `Coordinate ${bundle.descriptor.descriptor.id}`
+            || root.payload_json !== JSON.stringify({ descriptor_run_coordinator: expected })
+            || root.launch_policy !== "reuse_allowed" || root.result_schema !== null || root.depends_on_json !== "[]")
+            refuse("root_work_custody_missing");
+        if (JSON.parse(run.index_json).root_work_id !== root.work_id)
+            refuse("root_work_anchor_missing");
+        return { workId: root.work_id, status: root.status };
+    });
+}
+/** Called only in the same writer as fresh descriptor RUN allocation. Stage
+ * handlers consume this identity; they never allocate a second RUN root.
+ */
+export function allocateDescriptorRootWork(context, scope, bundle) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id IS NULL", [scope.projectId, scope.runId])
+        || context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=?", [scope.projectId, event, scope.runId]))
+        refuse("root_work_already_allocated");
+    const workId = nextWorkId(context, scope.projectId, bundle.descriptor.descriptor.id), now = context.now();
+    const expected = binding(scope, bundle);
+    context.db.run("INSERT INTO works (work_id,project_id,run_id,parent_work_id,task,launch_policy,depends_on_json,status,payload_json,created_at,updated_at) VALUES (?,?,?,NULL,?,'reuse_allowed','[]','created',?,?,?)", [workId, scope.projectId, scope.runId, `Coordinate ${bundle.descriptor.descriptor.id}`, JSON.stringify({ descriptor_run_coordinator: expected }), now, now]);
+    context.db.run("UPDATE runs SET index_json=json_set(index_json,'$.root_work_id',?) WHERE project_id=? AND id=?", [workId, scope.projectId, scope.runId]);
+    appendAudit(context, { projectId: scope.projectId, eventType: event, payload: { run_id: scope.runId, work_id: workId, binding: expected } });
+    if (readDescriptorRootWork(context, scope, bundle).workId !== workId)
+        refuse("root_work_not_retained");
+    return workId;
+}

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

@@ -0,0 +1,105 @@
+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 git = snapshot.owner.prior?.git ?? gitFacts(bundle.execution.snapshot().scope.workspace);
+        return new PreparedDescriptorRunSettlement(scope, bundle, snapshot.owner, git, snapshot.generation, matchKeys);
+    }
+    apply(context, assertHandlerCustody) {
+        if (typeof assertHandlerCustody !== "function")
+            refuse("handler_fence_required");
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: this.#bundle.execution.snapshot().scope.projectRoot, 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(this.#bundle.execution.snapshot().scope.workspace)) !== 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" };
+    }
+}