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

package/dist/services/interactive-user-inputs.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+const eventType = "interactive.user_input";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_user_input_invalid", "Interactive input requires its exact RUN and ordered delivered user bytes", 1, { reason, effect: "no_effect" });
+}
+function validDelivery(value) {
+    if (value === null)
+        return true;
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).sort().join() !== "controller_id,pause_id,request_id")
+        return false;
+    return Object.values(value).every(item => typeof item === "string" && item.length > 0 && item.length <= 256 && !/[\0\r\n]/.test(item));
+}
+function state(runId, bundle, initial, turns) {
+    const value = { schema_id: "dd-flow/interactive-user-turns@1", run_id: runId, bundle_sha256: bundle.sha256,
+        initial_request: initial, turns, finish_requested: turns.at(-1)?.kind === "finish" };
+    return { ...value, sha256: hybridDigest(value) };
+}
+/** Custody only: a delivered turn does not certify applicability, approve an
+ * agent's scope expansion or authorize Git/delivery. No files or RUNs allocated.
+ * Stage owners must fence this full revision before accepting their results. */
+function readInteractiveUserTurns(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        if (bundle.manifest.flow_id !== "interactive")
+            refuse("foreign_flow");
+        const bytes = bundle.blob("runtime/source-request.md"), reference = bundle.manifest.inventory.find(item => item.path === "runtime/source-request.md");
+        if (!bytes.length || bytes.length > 64 * 1024 || !reference || hash(bytes) !== reference.sha256)
+            refuse("original_request_missing");
+        const initial = { sha256: reference.sha256, base64: bytes.toString("base64") }, turns = [];
+        const rows = context.db.all("SELECT id,payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id LIMIT 129", [scope.projectId, eventType, scope.runId]);
+        if (rows.length > 128)
+            refuse("too_many_turns");
+        let total = bytes.length;
+        const requests = new Set();
+        for (const row of rows) {
+            if (Buffer.byteLength(row.payload_json) > 2 * 1024 * 1024)
+                refuse("unbounded_turn");
+            let payload;
+            try {
+                payload = JSON.parse(row.payload_json);
+            }
+            catch {
+                return refuse("invalid_turn_custody");
+            }
+            const turn = payload?.turn;
+            if (!payload || !["bundle_sha256,previous_sha256,run_id,turn", "bundle_sha256,delivery,previous_sha256,run_id,turn"].includes(Object.keys(payload).sort().join())
+                || Object.hasOwn(payload, "delivery") && !validDelivery(payload.delivery)
+                || payload.run_id !== scope.runId || payload.bundle_sha256 !== bundle.sha256
+                || payload.previous_sha256 !== state(scope.runId, bundle, initial, turns).sha256
+                || !turn || Object.keys(turn).sort().join() !== "base64,inputs_sha256,kind,request_id,sequence,sha256"
+                || turn.sequence !== turns.length + 1 || !validRequest(turn.request_id) || requests.has(turn.request_id)
+                || typeof turn.inputs_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(turn.inputs_sha256)
+                || !["turn", "finish"].includes(turn.kind) || typeof turn.base64 !== "string" || turns.at(-1)?.kind === "finish")
+                refuse("invalid_turn_custody");
+            const content = Buffer.from(turn.base64, "base64");
+            total += content.length;
+            if (!content.length || content.length > 1024 * 1024 || total > 16 * 1024 * 1024
+                || content.toString("base64") !== turn.base64 || hash(content) !== turn.sha256)
+                refuse("turn_bytes_changed");
+            requests.add(turn.request_id);
+            turns.push(turn);
+        }
+        return { ...state(scope.runId, bundle, initial, turns), event_ids: rows.map(row => row.id) };
+    });
+}
+/** Free turns and actual HITL answers share one SQL snapshot/revision. Later
+ * answers cannot disappear behind a previously frozen free-turn digest. */
+export function readInteractiveUserInputs(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const turns = readInteractiveUserTurns(context, scope, bundle);
+        const answers = readPreparedMemoryFlowUserInputs(context, scope, "interactive", bundle);
+        const messages = [...answers.sources.filter(source => source.role !== "request"),
+            ...turns.turns.map((turn, index) => ({ role: turn.kind, event_id: turns.event_ids[index],
+                request_id: turn.request_id, sequence: turn.sequence, sha256: turn.sha256, base64: turn.base64 }))]
+            .sort((a, b) => a.event_id - b.event_id);
+        const value = { schema_id: "dd-flow/interactive-user-inputs@1", run_id: scope.runId,
+            bundle_sha256: bundle.sha256, initial_request: turns.initial_request,
+            initial_request_basis: { role: "request", event_id: 0, sha256: turns.initial_request.sha256 }, turns: turns.turns,
+            turns_sha256: turns.sha256, messages, finish_requested: turns.finish_requested };
+        return { ...value, sha256: hybridDigest(value) };
+    });
+}
+/** Historical routing metadata, not another message or fresh pause selection. */
+export function readInteractiveInputDelivery(context, scope, bundle, requestId) {
+    return context.db.readSnapshot(() => {
+        const inputs = readInteractiveUserInputs(context, scope, bundle);
+        if (!inputs.turns.some(turn => turn.request_id === requestId))
+            refuse("original_turn_required");
+        const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.turn.request_id')=?", [scope.projectId, eventType, scope.runId, requestId]);
+        return structuredClone(JSON.parse(row.payload_json).delivery ?? null);
+    });
+}
+function validRequest(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
+}
+/** Internal ingress for a future bound CLI turn/finish command, not an agent
+ * result field. Explicit kind=finish closes intake; text is never interpreted
+ * as a finish trigger. Exact-request replay remains possible after Stage move. */
+export function retainInteractiveUserInput(context, scope, bundle, input) {
+    if (!validRequest(input.requestId) || !["turn", "finish"].includes(input.kind)
+        || !/^[a-f0-9]{64}$/.test(input.expectedInputsSha256) || !(input.bytes instanceof Uint8Array)
+        || !input.bytes.length || input.bytes.length > 1024 * 1024 || Object.hasOwn(input, "delivery") && !validDelivery(input.delivery))
+        refuse("invalid_delivery");
+    const bytes = Buffer.from(input.bytes), checksum = hash(bytes);
+    return context.db.writeTransaction(() => {
+        const current = readInteractiveUserInputs(context, scope, bundle);
+        const prior = current.turns.find(turn => turn.request_id === input.requestId);
+        if (prior) {
+            if (prior.kind !== input.kind || prior.sha256 !== checksum || prior.base64 !== bytes.toString("base64")
+                || prior.inputs_sha256 !== input.expectedInputsSha256
+                || Object.hasOwn(input, "delivery") && hybridDigest(input.delivery) !== hybridDigest(readInteractiveInputDelivery(context, scope, bundle, input.requestId)))
+                refuse("request_conflict");
+            return { changed: false, turn: prior, inputs: current };
+        }
+        assertRunMutationAllowed(context, scope.projectId, scope.runId);
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+        if (current.sha256 !== input.expectedInputsSha256)
+            refuse("inputs_changed");
+        if (current.finish_requested)
+            refuse("finish_already_requested");
+        const active = index.stage_runs?.findLast((stage) => stage.stage === "interactive");
+        const hitlPaused = run.status === "paused" && active?.status === "paused" && active.pause?.reason === "waiting_for_user"
+            && typeof active.pause.id === "string" && active.pause.id.length > 0 && typeof active.pause.work_id === "string" && active.pause.work_id.length > 0;
+        if (run.status !== "running" && run.status !== "waiting_for_user" && !hitlPaused || index.current_stage !== "interactive"
+            || !index.stage_runs?.some((stage) => stage.stage === "interactive" && ["running", "waiting_for_user", "paused"].includes(stage.status)))
+            refuse("interactive_stage_required");
+        const turn = { sequence: current.turns.length + 1, request_id: input.requestId, kind: input.kind,
+            inputs_sha256: current.sha256, sha256: checksum, base64: bytes.toString("base64") };
+        appendAudit(context, { projectId: scope.projectId, eventType, payload: { run_id: scope.runId,
+                bundle_sha256: bundle.sha256, previous_sha256: current.turns_sha256, turn,
+                ...(Object.hasOwn(input, "delivery") ? { delivery: input.delivery } : {}) } });
+        // Re-reading within the same writer validates bounds/custody before commit.
+        return { changed: true, turn, inputs: readInteractiveUserInputs(context, scope, bundle) };
+    }, "interactive.retainUserInput");
+}

package/dist/services/interactive-work-batch.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+export const interactiveWorkResultSchema = "dd-flow/interactive-work-result@1";
+function refuse(reason) {
+    throw new AppError("interactive_work_batch_invalid", "Interactive Work requires selected task data, scope and worker instruction", 2, { reason, effect: "no_effect" });
+}
+export function interactiveWorkPathAllowed(name) {
+    return typeof name === "string" && !!name && name.length <= 4096 && !path.posix.isAbsolute(name) && !path.win32.isAbsolute(name)
+        && !name.includes("\\") && !name.includes("\0") && name.split("/").every(part => !!part && ![".", "..", ".git", ".dd-flow", "node_modules"].includes(part.toLowerCase()) && localEnvironmentAllowed(part));
+}
+const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+/** Deterministic batch data only. Registration, actor custody, workspace
+ * observation, source delivery and dispatch remain with existing runtime owners.
+ * One writer avoids overlapping shared-workspace hardening writes. */
+export function interactiveWorkBatch(input) {
+    if (!input || Object.keys(input).filter(key => key !== "owner_stage").sort().join() !== "baseline_sha256,context,file_changes_sha256,input_sha256,instruction,read_inputs,run_id,scope_revision,stage,user_inputs_sha256,write_paths"
+        || !/^RUN-[0-9]+-[a-z0-9-]+$/.test(input.run_id) || !["hardening", "review"].includes(input.stage)
+        || ![input.input_sha256, input.baseline_sha256, input.user_inputs_sha256, input.scope_revision, input.file_changes_sha256].every(digest)
+        || typeof input.instruction !== "string" || !input.instruction.trim() || Buffer.byteLength(input.instruction) > 1024 * 1024
+        || !input.context || input.context.root !== "run" || !interactiveWorkPathAllowed(input.context.path) || !digest(input.context.sha256)
+        || !Array.isArray(input.read_inputs) || !input.read_inputs.length || input.read_inputs.length > 20_000
+        || input.read_inputs.some(ref => !ref || !["run", "workspace"].includes(ref.root) || !interactiveWorkPathAllowed(ref.path) || !digest(ref.sha256))
+        || new Set(input.read_inputs.map(ref => `${ref.root}:${ref.path}`)).size !== input.read_inputs.length
+        || !input.read_inputs.some(ref => hybridDigest(ref) === hybridDigest(input.context))
+        || !Array.isArray(input.write_paths) || input.write_paths.length > 20_000 || input.write_paths.some(name => !interactiveWorkPathAllowed(name))
+        || new Set(input.write_paths).size !== input.write_paths.length || hybridDigest(input.write_paths) !== hybridDigest([...input.write_paths].sort()))
+        refuse("invalid_selected_input");
+    if (input.stage === "review" && input.write_paths.length)
+        refuse("review_write_scope_forbidden");
+    if (input.owner_stage !== undefined && !["hardening", "review"].includes(input.owner_stage))
+        refuse("invalid_work_owner_role");
+    const ownerStage = input.owner_stage ?? input.stage;
+    if (!["hardening", "review"].includes(ownerStage) || ownerStage === "hardening" && input.stage !== "hardening")
+        refuse("invalid_work_owner_role");
+    const packet = { schema_id: "dd-flow/interactive-work-input@1", flow_id: "interactive",
+        ...structuredClone(input), owner_stage: ownerStage, key: input.stage, result_schema: interactiveWorkResultSchema };
+    return { works: [{ key: input.stage, depends_on: [], launch_policy: "fresh_agent_required",
+                result_schema: interactiveWorkResultSchema, task: input.instruction,
+                payload: { kind: `interactive-${input.stage}`, read_only: input.stage === "review",
+                    interactive: { ...packet, packet_sha256: hybridDigest(packet) } } }] };
+}

package/dist/services/interactive-work-collection.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readInteractiveStageScope } from "./interactive-stage-entry.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readCompletedInteractiveWork } from "./interactive-work-completion.js";
+import { PreparedInteractiveWorkspaceChanges, readInteractiveMutationScope } from "./interactive-mutation-scope.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { assertDiagnosticSessionIndependence } from "./diagnostic-work-collection.js";
+function refuse(reason) {
+    throw new AppError("interactive_work_collection_invalid", "Interactive Stage requires its latest settled graph and unchanged actual output", 2, { reason, effect: "no_effect" });
+}
+function collectSql(context, scope, bundle, role) {
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    const graph = stageGraphScope(context, scope.projectId, scope.runId, scope.stage), root = readDescriptorRootWork(context, scope, bundle);
+    const input = readDescriptorStageInput(context, scope, bundle), selected = readInteractiveMutationScope(context, scope, bundle);
+    if (run.status !== "running" || root.status !== "running" || index.current_stage !== scope.stage || selected.needs_scope_refresh
+        || !selected.inputs.finish_requested || input.attempt !== graph.attempt
+        || !index.stage_runs?.some((item) => item.stage === scope.stage && item.status === "running" && item.attempt === graph.attempt))
+        refuse("active_stage_required");
+    if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, root.workId]))
+        refuse("active_child_work");
+    // A lost newest family receipt must not silently select an older successful
+    // round. Generic allocation custody is independently retained by the registry.
+    if (context.db.get("SELECT 1 FROM audit_events b WHERE b.project_id=? AND b.event_type='work.batch_registration' AND json_extract(b.payload_json,'$.scope.run_id')=? AND json_extract(b.payload_json,'$.scope.stage')=? AND json_extract(b.payload_json,'$.scope.attempt')=? AND json_extract(b.payload_json,'$.scope.parent_work_id')=? AND json_extract(b.payload_json,'$.scope.request_key') LIKE 'interactive-%' AND NOT EXISTS (SELECT 1 FROM audit_events f WHERE f.project_id=b.project_id AND f.event_type='interactive.work_registration' AND json_extract(f.payload_json,'$.run_id')=? AND json_extract(f.payload_json,'$.stage')=? AND json_extract(f.payload_json,'$.attempt')=? AND json_extract(f.payload_json,'$.request_id')=substr(json_extract(b.payload_json,'$.scope.request_key'),13)) LIMIT 1", [scope.projectId, scope.runId, scope.stage, graph.attempt, root.workId, scope.runId, scope.stage, graph.attempt]))
+        refuse("round_registration_lost");
+    if (context.db.get("SELECT 1 FROM works w JOIN stage_work_memberships m ON m.project_id=w.project_id AND m.run_id=w.run_id AND m.work_id=w.work_id WHERE w.project_id=? AND w.run_id=? AND w.parent_work_id=? AND m.stage=? AND m.attempt=? AND m.cycle=? AND NOT EXISTS (SELECT 1 FROM audit_events f WHERE f.project_id=w.project_id AND f.event_type='interactive.work_registration' AND json_extract(f.payload_json,'$.run_id')=w.run_id AND json_extract(f.payload_json,'$.stage')=? AND json_extract(f.payload_json,'$.attempt')=? AND json_extract(f.payload_json,'$.work_ids.'||json_extract(w.payload_json,'$._dd_flow_batch_request.item_key'))=w.work_id) LIMIT 1", [scope.projectId, scope.runId, root.workId, scope.stage, graph.attempt, graph.cycle, scope.stage, graph.attempt]))
+        refuse("work_registration_lost");
+    const latest = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='interactive.work_registration' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? ORDER BY id DESC LIMIT 1", [scope.projectId, scope.runId, scope.stage, graph.attempt]);
+    if (!latest || Buffer.byteLength(latest.payload_json) > 16384)
+        refuse("registered_graph_required");
+    const ids = Object.values(JSON.parse(latest.payload_json)?.work_ids ?? {});
+    const workId = ids[0];
+    if (ids.length !== 1 || typeof workId !== "string")
+        refuse("registered_graph_required");
+    const work = readCompletedInteractiveWork(context, { ...scope, workId }, bundle), packet = work.start.assignment.packet;
+    if (hybridDigest(JSON.parse(latest.payload_json)) !== hybridDigest(work.start.assignment.receipt))
+        refuse("latest_round_replaced");
+    if (packet.owner_stage !== scope.stage || work.start.assignment.custody.scope.attempt !== graph.attempt
+        || work.start.assignment.custody.scope.cycle !== graph.cycle || packet.input_sha256 !== input.inputSha256
+        || packet.user_inputs_sha256 !== selected.inputs.sha256 || packet.scope_revision !== selected.revision
+        || packet.baseline_sha256 !== selected.baseline.sha256)
+        refuse("issued_stage_input_changed");
+    if (packet.stage !== role)
+        refuse(role === "review" ? "final_review_work_required" : "correction_author_work_required");
+    const storedActors = context.db.all("SELECT DISTINCT COALESCE(h.harness,s.harness) AS harness,COALESCE(h.provider_session_id,s.provider_session_id) AS provider_session_id FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id LEFT JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id LEFT JOIN hook_events h ON h.project_id=w.project_id AND h.event_key=ws.hook_event_id WHERE w.project_id=? AND w.run_id=? AND ws.id<>? ORDER BY 1,2", [scope.projectId, scope.runId, work.completed.session.id]);
+    const actors = [...storedActors, ...work.start.assignment.retained.body.work_history.works.flatMap(prior => prior.actor ? [prior.actor] : [])];
+    const excluded = [...new Map(actors.map(actor => [`${actor.harness}\0${actor.provider_session_id}`, actor])).entries()]
+        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, actor]) => actor);
+    if (excluded.some(actor => !actor.harness || !actor.provider_session_id))
+        refuse("prior_physical_owner_unknown");
+    // Includes every prior writer round, failed/cancelled attempts and root
+    // coordinators, not just the latest hardening author selected by a caller.
+    try {
+        assertDiagnosticSessionIndependence([work.completed.session], excluded);
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "diagnostic_work_collection_invalid")
+            refuse("physical_session_reused");
+        throw error;
+    }
+    const binding = { schema_id: "dd-flow/interactive-work-collection@1", run_id: scope.runId, stage: scope.stage, attempt: graph.attempt,
+        bundle_sha256: bundle.sha256, input_sha256: input.inputSha256, baseline_sha256: selected.baseline.sha256,
+        user_inputs_sha256: selected.inputs.sha256, scope_revision: selected.revision, work_id: workId,
+        registration_sha256: hybridDigest(work.start.assignment.receipt), settlement_sha256: hybridDigest(work.receipt),
+        result_sha256: work.receipt.result_sha256, actor: work.start.receipt.actor, excluded_actors: excluded };
+    return { binding, work };
+}
+/** Latest actual round selection, not a semantic review verdict or check gate.
+ * Stage handlers still own issue dispositions, corrections and verification. */
+export class PreparedInteractiveWorkCollection {
+    sha256;
+    #scope;
+    #bundle;
+    #sql;
+    #changes;
+    #role;
+    constructor(scope, bundle, sql, changes, role) {
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#sql = sql;
+        this.#changes = changes;
+        this.#role = role;
+        this.sha256 = hybridDigest(sql.binding);
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        return this.prepareRole(context, input, input.stage);
+    }
+    /** Handoff only. A correction author is never final review acceptance. */
+    static prepareCorrectionAuthor(context, input) {
+        return this.prepareRole(context, { ...input, stage: "review" }, "hardening");
+    }
+    static prepareRole(context, input, role) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_preparation_outside_writer_required");
+        if (!["hardening", "review"].includes(input.stage))
+            refuse("work_stage_required");
+        const selected = readInteractiveStageScope(context, input), scope = { ...selected.scope, stage: input.stage }, bundle = selected.bundle;
+        const sql = context.db.readSnapshot(() => collectSql(context, scope, bundle, role)), frozen = bundle.execution.snapshot().scope, git = readInteractiveWorkGit(bundle);
+        const changes = PreparedInteractiveWorkspaceChanges.prepare(context, scope, bundle, { projectRoot: frozen.projectRoot, workspace: frozen.workspace,
+            gitExecutable: git.git_executable, env: context.env }, sql.work.start.baseline.snapshot().entries.map(item => item.path));
+        if (createHash("sha256").update(JSON.stringify(changes.currentSnapshot())).digest("hex") !== sql.work.receipt.observed_snapshot_sha256)
+            refuse("settled_output_changed");
+        const prepared = new PreparedInteractiveWorkCollection(scope, bundle, sql, changes, role);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    snapshot() { return structuredClone(this.#sql.binding); }
+    results() { return [{ workId: this.#sql.work.completed.workId, result: structuredClone(this.#sql.work.result) }]; }
+    revalidate(context) { readInteractiveWorkGit(this.#bundle); this.#changes.revalidate(); this.assertCustody(context); }
+    assertCustody(context) {
+        if (hybridDigest(context.db.readSnapshot(() => collectSql(context, this.#scope, this.#bundle, this.#role)).binding) !== this.sha256)
+            refuse("collection_changed");
+    }
+}

package/dist/services/interactive-work-completion.js

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readInteractiveWorkGit, readInteractiveWorkStart } from "./interactive-work-start.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { PreparedInteractiveWorkspaceChanges, readInteractiveMutationScope } from "./interactive-mutation-scope.js";
+import { validateInteractiveWorkResult, pendingInteractiveIssues } from "./interactive-work-results.js";
+import { interactiveWorkPathAllowed } from "./interactive-work-batch.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { readCompletedResearchWork } from "./diagnostic-work-collection.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_work_completion_invalid", "Interactive completion requires its original start and actual bounded changes", 2, { reason, effect: "no_effect" });
+}
+function workChanges(delta) {
+    return delta.changes.map(item => {
+        if (item.before && item.before.kind !== "file" || item.after && item.after.kind !== "file")
+            refuse("regular_file_delta_required");
+        return { path: item.path, before_sha256: item.before?.sha256 ?? null, after_sha256: item.after?.sha256 ?? null,
+            before_mode: item.before?.mode ?? null, after_mode: item.after?.mode ?? null };
+    });
+}
+/** SQL-only completed output custody, independent of mutable workspace/results
+ * projections. Semantic verdicts are returned intact, not turned into PASS. */
+export function readCompletedInteractiveWork(context, scope, bundle) {
+    return context.db.readSnapshot(() => readCompletedInteractiveWorkSql(context, scope, bundle));
+}
+function readCompletedInteractiveWorkSql(context, scope, bundle) {
+    const completed = readCompletedResearchWork(context, scope, scope.workId);
+    const start = readInteractiveWorkStart(context, scope, bundle, completed.session.id);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='interactive.work_settlement' AND json_extract(payload_json,'$.work_session_id')=? LIMIT 2", [scope.projectId, completed.session.id]);
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 8 * 1024 * 1024)
+        refuse("settlement_custody_missing");
+    const receipt = JSON.parse(rows[0].payload_json);
+    if (!receipt || Object.keys(receipt).sort().join() !== "bundle_sha256,changes,observed_snapshot_sha256,packet_sha256,result_sha256,run_id,schema_id,start_snapshot_sha256,work_id,work_session_id"
+        || receipt.schema_id !== "dd-flow/interactive-work-settlement@1" || receipt.run_id !== scope.runId || receipt.work_id !== scope.workId
+        || receipt.work_session_id !== completed.session.id || receipt.bundle_sha256 !== bundle.sha256
+        || receipt.packet_sha256 !== start.assignment.packet.packet_sha256 || receipt.start_snapshot_sha256 !== start.baseline.sha256
+        || receipt.result_sha256 !== hash(Buffer.from(completed.result)) || !/^[a-f0-9]{64}$/.test(receipt.observed_snapshot_sha256)
+        || !Array.isArray(receipt.changes))
+        refuse("settlement_binding_changed");
+    const link = context.db.get("SELECT result_receipt_json FROM work_sessions WHERE id=?", [completed.session.id]);
+    if (!link?.result_receipt_json || Buffer.byteLength(link.result_receipt_json) > 16384)
+        refuse("common_result_custody_missing");
+    const shared = JSON.parse(link.result_receipt_json);
+    if (shared.work_id !== scope.workId || shared.work_session_id !== completed.session.id || shared.status !== "completed"
+        || shared.result_sha256 !== receipt.result_sha256)
+        refuse("common_result_binding_changed");
+    const entries = new Map(start.baseline.snapshot().entries.map(item => [item.path, item]));
+    for (const change of receipt.changes) {
+        const before = entries.get(change?.path);
+        if (!change || change.before_sha256 !== (before?.kind === "file" ? before.sha256 : null)
+            || change.before_mode !== (before?.kind === "file" ? before.mode : null))
+            refuse("settled_before_version_changed");
+    }
+    const result = validateInteractiveWorkResult(Buffer.from(completed.result), bundle.blob("schemas/interactive-work-result.schema.json"), {
+        workId: scope.workId, packet: start.assignment.packet, actualChanges: receipt.changes, checks: [], checksSatisfied: true,
+        priorIssues: pendingInteractiveIssues(start.assignment.retained.body.work_history, start.assignment.packet),
+        observedSources: receipt.changes.filter(item => item.after_sha256 !== null).map(item => ({ root: "workspace", path: item.path, sha256: item.after_sha256 }))
+    });
+    return { completed, start, receipt, result };
+}
+/** Physical result preparation for common Work settlement, not Stage acceptance.
+ * No caller-provided packet, observation, actor or check receipt is authoritative. */
+export class PreparedInteractiveWorkCompletion {
+    workId;
+    sha256;
+    #scope;
+    #bundle;
+    #start;
+    #changes;
+    #delta;
+    #bytes;
+    constructor(scope, bundle, start, changes, bytes) {
+        this.#scope = { ...scope };
+        this.workId = scope.workId;
+        this.#bundle = bundle;
+        this.#start = start;
+        this.#changes = changes;
+        const currentBytes = Buffer.from(JSON.stringify(changes.currentSnapshot()));
+        const current = PreparedInteractiveGitBaseline.restore(currentBytes, hash(currentBytes));
+        this.#delta = start.baseline.changes(current);
+        if (this.#delta.head_changed || this.#delta.index_changed)
+            refuse("work_git_movement");
+        const actualChanges = workChanges(this.#delta);
+        let proposal;
+        try {
+            proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            refuse("invalid_proposal");
+        }
+        // Existing content-change proposals may omit mode metadata. Never turn an
+        // unchanged-hash placeholder into a later, unreported permission change.
+        if (proposal && typeof proposal === "object" && !Array.isArray(proposal) && Array.isArray(proposal.changes)) {
+            const value = proposal;
+            const observations = new Map(actualChanges.map(item => [item.path, item]));
+            value.changes = value.changes.map(item => {
+                const observed = observations.get(item?.path ?? "");
+                return item && observed && item.before_sha256 !== item.after_sha256 && !Object.hasOwn(item, "before_mode") && !Object.hasOwn(item, "after_mode")
+                    ? { ...item, before_mode: observed.before_mode, after_mode: observed.after_mode } : item;
+            });
+        }
+        const schema = bundle.blob("schemas/interactive-work-result.schema.json");
+        if (!schema.equals(bundle.engine().schema("interactive-work-result")))
+            refuse("selected_schema_changed");
+        const result = validateInteractiveWorkResult(Buffer.from(JSON.stringify(proposal)), schema, { workId: scope.workId, packet: start.assignment.packet,
+            actualChanges, observedSources: current.snapshot().entries.filter(item => item.kind === "file" && interactiveWorkPathAllowed(item.path))
+                .map(item => ({ root: "workspace", path: item.path, sha256: item.sha256 })),
+            // This Work contract assigns no command checks. Stage hardening owns the
+            // flow's required verification; [] does not assert those gates passed.
+            checks: [], checksSatisfied: true, priorIssues: pendingInteractiveIssues(start.assignment.retained.body.work_history, start.assignment.packet) });
+        this.#bytes = Buffer.from(JSON.stringify(result));
+        this.sha256 = hash(this.#bytes);
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+            refuse("unbounded_result");
+        const work = context.db.get("SELECT w.project_id,w.run_id,r.project_root FROM works w JOIN runs r ON r.project_id=w.project_id AND r.id=w.run_id WHERE w.work_id=?", [input.workId]);
+        const link = context.db.get("SELECT id,session_id FROM work_sessions WHERE work_id=? AND status='running'", [input.workId]);
+        if (!work || !link)
+            refuse("active_work_required");
+        const scope = { projectId: work.project_id, runId: work.run_id, workId: input.workId };
+        const bundle = readFlowRunExecutionBundle(context, { projectRoot: work.project_root, runId: work.run_id });
+        if (!bundle)
+            refuse("bundle_required");
+        const start = readInteractiveWorkStart(context, scope, bundle, link.id), frozen = bundle.execution.snapshot().scope, git = readInteractiveWorkGit(bundle);
+        const changes = PreparedInteractiveWorkspaceChanges.prepare(context, scope, bundle, { projectRoot: frozen.projectRoot, workspace: frozen.workspace,
+            gitExecutable: git.git_executable, env: context.env }, start.baseline.snapshot().entries.map(item => item.path));
+        const prepared = new PreparedInteractiveWorkCompletion(scope, bundle, start, changes, Buffer.from(input.bytes));
+        prepared.assertSettlementScope(context, link.session_id, link.id);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    bytes() { return Buffer.from(this.#bytes); }
+    revalidate(context) {
+        readInteractiveWorkGit(this.#bundle);
+        this.#changes.revalidate();
+        this.assertSettlementScope(context, this.#start.receipt.actor.session_id, this.#start.receipt.work_session_id);
+    }
+    assertSettlementScope(context, sessionId, workSessionId) {
+        const start = readInteractiveWorkStart(context, this.#scope, this.#bundle, workSessionId), packet = start.assignment.packet;
+        if (hybridDigest(start.receipt) !== hybridDigest(this.#start.receipt) || sessionId !== start.receipt.actor.session_id)
+            refuse("start_owner_changed");
+        const selected = readInteractiveMutationScope(context, this.#scope, this.#bundle), observed = this.#changes.snapshot();
+        if (selected.needs_scope_refresh || selected.revision !== packet.scope_revision || selected.inputs.sha256 !== packet.user_inputs_sha256
+            || selected.baseline.sha256 !== packet.baseline_sha256 || observed.scope_revision !== selected.revision)
+            refuse("issued_inputs_changed");
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle), index = JSON.parse(run.index_json);
+        const graph = stageGraphScope(context, this.#scope.projectId, this.#scope.runId, packet.owner_stage);
+        const stage = readDescriptorStageInput(context, { ...this.#scope, stage: packet.owner_stage }, this.#bundle);
+        if (run.status !== "running" || index.current_stage !== packet.owner_stage || graph.attempt !== start.assignment.custody.scope.attempt
+            || graph.cycle !== start.assignment.custody.scope.cycle || stage.attempt !== graph.attempt || stage.inputSha256 !== packet.input_sha256
+            || !index.stage_runs?.some((item) => item.stage === packet.owner_stage && item.status === "running" && item.attempt === graph.attempt)
+            || !context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND work_id=? AND status='running'", [this.#scope.projectId, this.#scope.runId, start.assignment.receipt.parent_work_id])
+            || !context.db.get("SELECT 1 FROM works w JOIN work_sessions ws ON ws.work_id=w.work_id JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id WHERE w.project_id=? AND w.run_id=? AND w.work_id=? AND w.status='running' AND ws.id=? AND ws.session_id=? AND ws.status='running' AND s.worker_id=w.work_id AND s.run_id=w.run_id AND s.status='active' AND s.harness=? AND s.provider_session_id=?", [this.#scope.projectId, this.#scope.runId, this.workId, workSessionId, sessionId, start.receipt.actor.harness, start.receipt.actor.provider_session_id]))
+            refuse("active_settlement_owner_required");
+    }
+    recordSettlement(context, sessionId, workSessionId) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        this.assertSettlementScope(context, sessionId, workSessionId);
+        this.#changes.assertCustody(context);
+        if (context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='interactive.work_settlement' AND json_extract(payload_json,'$.work_session_id')=?", [this.#scope.projectId, workSessionId]))
+            refuse("settlement_already_retained");
+        const receipt = { schema_id: "dd-flow/interactive-work-settlement@1", run_id: this.#scope.runId, work_id: this.workId, work_session_id: workSessionId,
+            bundle_sha256: this.#bundle.sha256, packet_sha256: this.#start.assignment.packet.packet_sha256,
+            start_snapshot_sha256: this.#start.baseline.sha256, observed_snapshot_sha256: this.#delta.current_sha256,
+            result_sha256: this.sha256, changes: workChanges(this.#delta) };
+        const json = JSON.stringify(receipt);
+        if (Buffer.byteLength(json) > 8 * 1024 * 1024)
+            refuse("unbounded_settlement");
+        context.db.run("INSERT INTO audit_events(project_id,event_type,payload_json,created_at) VALUES(?,'interactive.work_settlement',?,?)", [this.#scope.projectId, json, context.now()]);
+    }
+}