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

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

@@ -0,0 +1,249 @@
+import path from "node:path";
+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 { PreparedInteractiveWorkspaceChanges } from "./interactive-mutation-scope.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { prepareStagePacket, acceptStagePacket, publishStagePacket, resolveStagePublicationPath } from "./stage-report-renderer.js";
+import { putInteractiveBundleData, readInteractiveBundleData } from "./interactive-bundle-data.js";
+import { interactiveWorkBatch, interactiveWorkPathAllowed } from "./interactive-work-batch.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { readInteractiveWorkHistory, assertInteractiveWorkHistory, assertInteractiveCorrectionHistory } from "./interactive-work-history.js";
+import { pendingInteractiveIssues } from "./interactive-work-results.js";
+import { PreparedInteractiveChecks } from "./interactive-checks.js";
+const event = "interactive.work_context", logical = "runtime/work-context.json";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_work_context_invalid", "Interactive Work requires its exact retained user data and original versions", 2, { reason, effect: "no_effect" });
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_context_json");
+    }
+}
+function record(context, scope, bundle, reference) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.reference.path')=? LIMIT 2", [scope.projectId, event, scope.runId, scope.stage, scope.attempt, reference.path]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 4 * 1024 * 1024)
+        refuse("ambiguous_or_unbounded_context");
+    const value = json(Buffer.from(rows[0].payload_json));
+    if (!value || Object.keys(value).sort().join() !== "attempt,bundle_sha256,input,logical_sha256,packet_refs,reference,run_id,schema_id,stage"
+        || value.schema_id !== "dd-flow/interactive-work-context@1" || value.run_id !== scope.runId || value.stage !== scope.stage || value.attempt !== scope.attempt
+        || value.bundle_sha256 !== bundle.sha256 || !/^[a-f0-9]{64}$/.test(value.logical_sha256)
+        || hybridDigest(value.reference) !== hybridDigest(reference) || hybridDigest(value.input?.context) !== hybridDigest(reference)
+        || value.input?.run_id !== scope.runId || value.input.owner_stage !== scope.stage
+        || !Array.isArray(value.packet_refs) || !value.packet_refs.length || value.packet_refs.length > 33)
+        refuse("context_scope_changed");
+    interactiveWorkBatch(value.input);
+    return value;
+}
+/** Selected SQL packet bytes, never mutable projections or caller-owned JSON. */
+export function readRetainedInteractiveWorkContext(context, scope, bundle, reference) {
+    const value = record(context, scope, bundle, reference);
+    if (!value)
+        refuse("context_custody_missing");
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    if (!run.run_root)
+        refuse("run_root_missing");
+    const prefix = `${bundle.descriptor.stage(scope.stage).directory}/work-contexts/${value.logical_sha256}/`;
+    const files = new Map(), inventory = [];
+    for (const ref of value.packet_refs) {
+        if (!ref || ref.root !== "run" || !ref.path.startsWith(prefix) || !/^[a-f0-9]{64}$/.test(ref.sha256))
+            refuse("foreign_context_part");
+        const name = ref.path.slice(prefix.length);
+        if (!interactiveWorkPathAllowed(name) || files.has(name))
+            refuse("invalid_context_inventory");
+        const suffix = `/${ref.path}`;
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.sha256')=? AND substr(json_extract(payload_json,'$.file'),-?)=? LIMIT 2", [scope.projectId, scope.runId, scope.stage, scope.attempt, ref.sha256, suffix.length, suffix]);
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+            refuse("context_part_custody_missing");
+        const packet = json(Buffer.from(rows[0].payload_json));
+        if (typeof packet.base64 !== "string" || resolveStagePublicationPath(context, scope.projectId, scope.runId, packet.file) !== path.join(run.run_root, ref.path))
+            refuse("context_part_scope_changed");
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (!bytes.length || bytes.length > 1024 * 1024 || bytes.toString("base64") !== packet.base64 || hash(bytes) !== ref.sha256)
+            refuse("context_part_changed");
+        files.set(name, bytes);
+        inventory.push({ path: name, sha256: ref.sha256 });
+    }
+    const selected = readInteractiveBundleData({ manifest: { ...bundle.manifest, inventory }, blob: name => files.get(name) ?? Buffer.alloc(0) }, logical);
+    if (selected.sha256 !== value.logical_sha256 || selected.reference.sha256 !== reference.sha256 || reference.path !== `${prefix}${logical}`)
+        refuse("context_identity_changed");
+    const body = json(selected.bytes);
+    if (!body || body.schema_id !== "dd-flow/interactive-work-data@1" || body.run_id !== scope.runId || body.stage !== scope.stage
+        || body.work_role !== value.input.stage
+        || body.bundle_sha256 !== bundle.sha256 || body.input_sha256 !== value.input.input_sha256
+        || body.baseline_sha256 !== value.input.baseline_sha256
+        || body.user_inputs_sha256 !== value.input.user_inputs_sha256 || body.scope_revision !== value.input.scope_revision
+        || body.file_changes_sha256 !== value.input.file_changes_sha256 || !Array.isArray(body.file_changes)
+        || hybridDigest(body.file_changes) !== value.input.file_changes_sha256 || !Array.isArray(body.current_files)
+        || body.current_files.some(item => !item || item.kind !== "file" || !interactiveWorkPathAllowed(item.path) || !/^[a-f0-9]{64}$/.test(item.sha256))
+        || body.worker_instruction?.root !== "run" || body.worker_instruction.path !== `execution-bundle/interactive/hybrid/${value.input.stage}-worker.md`
+        || hash(Buffer.from(value.input.instruction)) !== body.worker_instruction.sha256
+        || hybridDigest(value.input.read_inputs) !== hybridDigest([...value.packet_refs, body.worker_instruction, ...(body.stage_checks?.sources ?? []),
+            ...body.current_files.map(item => ({ root: "workspace", path: item.path, sha256: item.sha256 }))]))
+        refuse("context_binding_changed");
+    if (body.stage_checks) {
+        const { plan, plan_sha256, sources, receipts } = body.stage_checks;
+        if (body.work_role !== "review" || plan_sha256 !== hybridDigest(plan) || plan.run_id !== scope.runId || plan.stage !== scope.stage
+            || plan.bundle_sha256 !== bundle.sha256 || plan.input_sha256 !== body.input_sha256 || plan.user_inputs_sha256 !== body.user_inputs_sha256
+            || plan.scope_revision !== body.scope_revision || plan.file_changes_sha256 !== body.file_changes_sha256
+            || !Array.isArray(receipts) || !Array.isArray(sources) || sources.some(ref => ref.root !== "run")
+            || receipts.some(ref => !sources.some(source => source.path === ref.path && source.sha256 === ref.sha256)))
+            refuse("stage_checks_changed");
+    }
+    assertInteractiveWorkHistory(body.work_history, scope.runId, bundle.sha256);
+    if (scope.stage === "review" && value.input.stage === "hardening")
+        assertInteractiveCorrectionHistory(body.work_history, scope.attempt);
+    if (hybridDigest(body.pending_issues) !== hybridDigest(pendingInteractiveIssues(body.work_history, body)))
+        refuse("pending_issues_changed");
+    return { record: value, bytes: selected.bytes, body };
+}
+/** Source preparation only, not a Work registration/launch permission. The
+ * graph owner pairs retainPreparedSql with its existing atomic batch writer. */
+export class PreparedInteractiveWorkContext {
+    #selected;
+    #changes;
+    #scope;
+    #record;
+    #packets;
+    #history;
+    #verification;
+    constructor(selected, changes, scope, value, packets, history, verification) {
+        this.#selected = selected;
+        this.#changes = changes;
+        this.#scope = scope;
+        this.#record = structuredClone(value);
+        this.#packets = packets;
+        this.#history = structuredClone(history);
+        this.#verification = verification;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        if (!["hardening", "review"].includes(input.stage))
+            refuse("work_stage_required");
+        const role = input.role ?? input.stage;
+        if (!["hardening", "review"].includes(role) || input.stage === "hardening" && role !== "hardening")
+            refuse("invalid_work_owner_role");
+        const selected = readInteractiveStageScope(context, input), { bundle, scope, run } = selected;
+        const stage = readDescriptorStageInput(context, scope, bundle);
+        if (!run.run_root)
+            refuse("run_root_missing");
+        const history = readInteractiveWorkHistory(context, scope, bundle);
+        if (input.stage === "review" && role === "hardening") {
+            assertInteractiveCorrectionHistory(history, stage.attempt);
+            bundle.execution.work(input.stage, undefined, role);
+        }
+        const changes = PreparedInteractiveWorkspaceChanges.prepare(context, scope, bundle, { projectRoot: bundle.execution.snapshot().scope.projectRoot,
+            workspace: bundle.execution.snapshot().scope.workspace, gitExecutable: input.gitExecutable, env: context.env });
+        const workerPath = `interactive/hybrid/${role}-worker.md`, workerBytes = bundle.blob(workerPath);
+        let instruction;
+        try {
+            instruction = new TextDecoder("utf-8", { fatal: true }).decode(workerBytes);
+        }
+        catch {
+            return refuse("invalid_worker_instruction");
+        }
+        if (!bundle.blob("schemas/interactive-work-result.schema.json").equals(bundle.engine().schema("interactive-work-result")))
+            refuse("worker_schema_not_qualified");
+        const current = changes.currentSnapshot(), patch = changes.snapshot().delta.changes, entry = selected.selected.baseline.snapshot(), state = selected.selected;
+        let stageChecks = null;
+        let verificationOwner = null;
+        if (input.checks) {
+            if (!(input.checks instanceof PreparedInteractiveChecks) || role !== "review")
+                refuse("owned_review_checks_required");
+            const plan = input.checks.value(), evidence = input.checks.evidence(context), sources = new Map();
+            if (plan.run_id !== input.runId || plan.stage !== input.stage || plan.bundle_sha256 !== bundle.sha256 || plan.input_sha256 !== stage.inputSha256
+                || plan.user_inputs_sha256 !== state.inputs.sha256 || plan.scope_revision !== state.revision || plan.file_changes_sha256 !== hybridDigest(patch))
+                refuse("foreign_review_checks");
+            for (const source of evidence?.sourceReferences() ?? []) {
+                const prior = sources.get(source.path);
+                if (prior && prior.sha256 !== source.sha256)
+                    refuse("conflicting_check_sources");
+                sources.set(source.path, source);
+            }
+            stageChecks = { plan_sha256: input.checks.sha256, plan, receipts: evidence?.retainedReferences(context) ?? [], sources: [...sources.values()] };
+            verificationOwner = { context, checks: input.checks, evidence };
+        }
+        const currentFiles = current.entries.filter(item => item.kind === "file" && interactiveWorkPathAllowed(item.path));
+        const body = { schema_id: "dd-flow/interactive-work-data@1", run_id: input.runId, stage: input.stage, work_role: role, bundle_sha256: bundle.sha256,
+            input_sha256: stage.inputSha256, baseline_sha256: state.baseline.sha256, user_inputs_sha256: state.inputs.sha256, scope_revision: state.revision, file_changes_sha256: hybridDigest(patch),
+            delivered_user_inputs: { initial_request: state.inputs.initial_request, messages: state.inputs.messages, finish_requested: state.inputs.finish_requested },
+            entry_git: { head: entry.head, branch: entry.branch, index_sha256: entry.index_sha256, status_base64: entry.status_base64, visibility: entry.visibility },
+            scope: { paths: state.active_paths, decisions: state.records.map(item => ({ basis: item.basis, reason: item.reason, paths: item.paths, user_inputs_sha256: item.user_inputs_sha256 })) },
+            before_versions: state.before_versions.filter(item => state.active_paths.includes(item.path)), current_files: currentFiles, file_changes: patch,
+            work_history: history, stage_checks: stageChecks, pending_issues: pendingInteractiveIssues(history, { file_changes_sha256: hybridDigest(patch), user_inputs_sha256: state.inputs.sha256, scope_revision: state.revision }),
+            worker_instruction: { root: "run", path: `execution-bundle/${workerPath}`, sha256: hash(workerBytes) } };
+        const bytes = Buffer.from(JSON.stringify(body)), blobs = new Map(), data = putInteractiveBundleData(blobs, logical, bytes);
+        const prefix = `${bundle.descriptor.stage(input.stage).directory}/work-contexts/${data.sha256}/`;
+        const packetRefs = [...blobs].map(([name, content]) => ({ root: "run", path: `${prefix}${name}`, sha256: hash(content) }));
+        const reference = { root: "run", path: `${prefix}${logical}`, sha256: data.reference.sha256 };
+        const workInput = { run_id: input.runId, stage: role, owner_stage: input.stage, input_sha256: stage.inputSha256,
+            baseline_sha256: state.baseline.sha256, user_inputs_sha256: state.inputs.sha256, scope_revision: state.revision,
+            file_changes_sha256: hybridDigest(patch), context: reference, read_inputs: [...packetRefs, { ...body.worker_instruction, root: "run" }, ...(stageChecks?.sources ?? []),
+                ...currentFiles.map(item => ({ root: "workspace", path: item.path, sha256: item.sha256 }))],
+            write_paths: role === "hardening" ? [...state.active_paths] : [], instruction };
+        interactiveWorkBatch(workInput);
+        const ownedScope = { ...scope, stage: input.stage, attempt: stage.attempt };
+        const value = { schema_id: "dd-flow/interactive-work-context@1", run_id: input.runId, stage: input.stage,
+            attempt: stage.attempt, bundle_sha256: bundle.sha256, logical_sha256: data.sha256, reference, packet_refs: packetRefs, input: workInput };
+        if (Buffer.byteLength(JSON.stringify(value)) > 4 * 1024 * 1024)
+            refuse("unbounded_context_metadata");
+        const packets = [...blobs].map(([name, content]) => prepareStagePacket(path.join(run.run_root, prefix, name), content));
+        const prepared = new PreparedInteractiveWorkContext(selected, changes, ownedScope, value, packets, history, verificationOwner);
+        prepared.revalidate();
+        return prepared;
+    }
+    snapshot() { return structuredClone(this.#record); }
+    workInput() { return structuredClone(this.#record.input); }
+    revalidate() { this.#changes.revalidate(); if (this.#verification) {
+        this.#verification.checks.revalidate(this.#verification.context);
+        this.#verification.evidence?.revalidate(this.#verification.context);
+    } }
+    assertCustody(context) {
+        this.#selected.assertCustody(context);
+        this.#changes.assertCustody(context);
+        this.#verification?.checks.assertCustody(context);
+        this.#verification?.evidence?.assertCustody(context);
+        if (hybridDigest(readInteractiveWorkHistory(context, this.#scope, this.#selected.bundle)) !== hybridDigest(this.#history))
+            refuse("work_history_changed");
+        const current = readDescriptorStageInput(context, this.#scope, this.#selected.bundle);
+        if (current.attempt !== this.#scope.attempt || current.inputSha256 !== this.#record.input.input_sha256)
+            refuse("stage_input_changed");
+    }
+    retainPreparedSql(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const prior = record(context, this.#scope, this.#selected.bundle, this.#record.reference);
+        if (prior) {
+            if (hybridDigest(prior) !== hybridDigest(this.#record))
+                refuse("context_changed");
+            return { changed: false };
+        }
+        this.assertCustody(context);
+        assertRunMutationAllowed(context, this.#scope.projectId, this.#scope.runId);
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#selected.bundle), index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== this.#scope.stage || !index.stage_runs?.some((item) => item.stage === this.#scope.stage && item.status === "running" && item.attempt === this.#scope.attempt))
+            refuse("active_work_stage_required");
+        for (const prepared of this.#packets)
+            acceptStagePacket(context, { ...this.#scope, prepared });
+        context.db.run("INSERT INTO audit_events(project_id,event_type,payload_json,created_at) VALUES(?,?,?,?)", [this.#scope.projectId, event, JSON.stringify(this.#record), context.now()]);
+        readRetainedInteractiveWorkContext(context, this.#scope, this.#selected.bundle, this.#record.reference);
+        return { changed: true };
+    }
+    publish(context) {
+        const retained = readRetainedInteractiveWorkContext(context, this.#scope, this.#selected.bundle, this.#record.reference);
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#selected.bundle);
+        for (const ref of retained.record.packet_refs)
+            publishStagePacket(context, this.#scope.projectId, this.#scope.runId, this.#scope.stage, path.join(run.run_root, ref.path));
+    }
+}

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

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { readRegisteredInteractiveWork } from "./interactive-work-registration.js";
+import { readCompletedInteractiveWork } from "./interactive-work-completion.js";
+import { readInteractiveWorkStart } from "./interactive-work-start.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_work_history_invalid", "Interactive corrections require the original registered Work history", 2, { reason, effect: "no_effect" });
+}
+/** A reviewer remains read-only. A separate author can be registered inside
+ * that same Stage only after its independently completed negative review. */
+export function assertInteractiveCorrectionHistory(history, attempt) {
+    const prior = history.works.findLast(work => work.owner_stage === "review" && work.stage === "review" && work.attempt === attempt && work.status === "completed");
+    if (!prior || typeof prior.result === "string" || prior.result.verdict === "ready")
+        refuse("negative_review_required_for_correction");
+}
+/** Retained task data validation only; never reconstruct custody from this JSON. */
+export function assertInteractiveWorkHistory(value, runId, bundleSha256) {
+    if (!value || Object.keys(value).sort().join() !== "bundle_sha256,run_id,schema_id,works"
+        || value.schema_id !== "dd-flow/interactive-work-history@1" || value.run_id !== runId || value.bundle_sha256 !== bundleSha256
+        || !Array.isArray(value.works) || value.works.length > 20_000)
+        refuse("invalid_retained_history");
+    const ids = new Set();
+    let total = 0;
+    for (const item of value.works) {
+        if (!item || Object.keys(item).sort().join() !== "actor,attempt,owner_stage,request_id,result,result_sha256,review_binding,stage,status,work_id,work_session_id"
+            || typeof item.work_id !== "string" || !item.work_id || ids.has(item.work_id) || !["hardening", "review"].includes(item.stage)
+            || typeof item.attempt !== "string" || !item.attempt || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(item.request_id)
+            || !["hardening", "review"].includes(item.owner_stage) || item.owner_stage === "hardening" && item.stage !== "hardening"
+            || !["completed", "failed", "cancelled"].includes(item.status)
+            || (item.work_session_id === null ? item.actor !== null || item.status === "completed"
+                : typeof item.work_session_id !== "string" || !item.work_session_id || !item.actor
+                    || Object.keys(item.actor).sort().join() !== "harness,provider_session_id"
+                    || typeof item.actor.harness !== "string" || !item.actor.harness
+                    || typeof item.actor.provider_session_id !== "string" || !item.actor.provider_session_id))
+            refuse("invalid_history_entry");
+        if (item.status === "completed" && item.stage === "review" ? !item.review_binding
+            || Object.keys(item.review_binding).sort().join() !== "file_changes_sha256,scope_revision,user_inputs_sha256"
+            || Object.values(item.review_binding).some(value => typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
+            : item.review_binding !== null)
+            refuse("invalid_history_review_binding");
+        const text = typeof item.result === "string" ? item.result : JSON.stringify(item.result);
+        if (typeof text !== "string" || !text.length || Buffer.byteLength(text) > 1024 * 1024 || hash(text) !== item.result_sha256)
+            refuse("history_result_changed");
+        if (item.status === "completed" ? typeof item.result !== "object" || !item.result || item.result.schema_id !== "dd-flow/interactive-work-result@1"
+            || item.result.run_id !== runId || item.result.work_id !== item.work_id || item.result.stage !== item.stage : typeof item.result !== "string")
+            refuse("foreign_history_result");
+        ids.add(item.work_id);
+        total += Buffer.byteLength(JSON.stringify(item));
+        if (total > 32 * 1024 * 1024)
+            refuse("history_budget_exceeded");
+    }
+}
+/** Original SQL custody, in registration order, across all attempts and stages.
+ * Missing/active Works refuse; terminal failures remain data, never fake reviews. */
+export function readInteractiveWorkHistory(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        if (bundle.manifest.flow_id !== "interactive" || bundle.manifest.run_id !== scope.runId)
+            refuse("interactive_bundle_required");
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        const rows = context.db.all("SELECT j.value AS work_id FROM audit_events f,json_each(f.payload_json,'$.work_ids') j WHERE f.project_id=? AND f.event_type='interactive.work_registration' AND json_extract(f.payload_json,'$.run_id')=? ORDER BY f.id,j.key LIMIT 20001", [scope.projectId, scope.runId]);
+        const works = context.db.all("SELECT work_id,status FROM works WHERE project_id=? AND run_id=? AND result_schema='dd-flow/interactive-work-result@1' LIMIT 20001", [scope.projectId, scope.runId]);
+        const registered = new Set(rows.map(row => row.work_id));
+        if (rows.length > 20_000 || works.length !== rows.length || registered.size !== rows.length
+            || works.some(work => !registered.has(work.work_id)))
+            refuse("history_registration_missing");
+        const byId = new Map(works.map(work => [work.work_id, work])), entries = [];
+        let total = 0;
+        for (const row of rows) {
+            const work = byId.get(row.work_id);
+            if (!["completed", "failed", "cancelled"].includes(work.status))
+                refuse("prior_work_not_terminal");
+            const text = context.db.get("SELECT result FROM works WHERE project_id=? AND run_id=? AND work_id=? AND length(CAST(result AS BLOB))<=1048576", [scope.projectId, scope.runId, row.work_id])?.result;
+            if (!text)
+                refuse("unbounded_or_missing_history_result");
+            const assignment = readRegisteredInteractiveWork(context, scope, bundle, row.work_id);
+            const link = context.db.get("SELECT id,status,result_receipt_json FROM work_sessions WHERE work_id=? ORDER BY rowid DESC LIMIT 1", [row.work_id]);
+            let actor = null, result = text;
+            if (work.status === "completed") {
+                const completed = readCompletedInteractiveWork(context, { ...scope, workId: row.work_id }, bundle);
+                if (link?.id !== completed.completed.session.id)
+                    refuse("history_latest_session_changed");
+                actor = { harness: completed.completed.session.harness, provider_session_id: completed.completed.session.provider_session_id };
+                result = completed.result;
+            }
+            else if (link) {
+                const start = readInteractiveWorkStart(context, { ...scope, workId: row.work_id }, bundle, link.id);
+                if (link.status !== work.status || !link.result_receipt_json || Buffer.byteLength(link.result_receipt_json) > 16384)
+                    refuse("terminal_session_custody_missing");
+                const receipt = JSON.parse(link.result_receipt_json);
+                if (receipt.work_id !== row.work_id || receipt.work_session_id !== link.id || receipt.status !== work.status || receipt.result_sha256 !== hash(text))
+                    refuse("terminal_result_changed");
+                actor = { harness: start.receipt.actor.harness, provider_session_id: start.receipt.actor.provider_session_id };
+            }
+            const entry = { work_id: row.work_id, stage: assignment.packet.stage, owner_stage: assignment.packet.owner_stage, attempt: assignment.receipt.attempt,
+                request_id: assignment.receipt.request_id, status: work.status, work_session_id: link?.id ?? null,
+                review_binding: work.status === "completed" && assignment.packet.stage === "review" ? {
+                    file_changes_sha256: assignment.packet.file_changes_sha256, user_inputs_sha256: assignment.packet.user_inputs_sha256,
+                    scope_revision: assignment.packet.scope_revision
+                } : null,
+                actor, result_sha256: hash(text), result };
+            total += Buffer.byteLength(JSON.stringify(entry));
+            if (total > 32 * 1024 * 1024)
+                refuse("history_budget_exceeded");
+            entries.push(entry);
+        }
+        const history = { schema_id: "dd-flow/interactive-work-history@1", run_id: scope.runId, bundle_sha256: bundle.sha256, works: entries };
+        assertInteractiveWorkHistory(history, scope.runId, bundle.sha256);
+        return history;
+    });
+}

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

@@ -0,0 +1,124 @@
+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 { stageGraphScope } from "./stage-work-graph.js";
+import { PreparedInteractiveWorkContext, readRetainedInteractiveWorkContext } from "./interactive-work-context.js";
+import { interactiveWorkBatch } from "./interactive-work-batch.js";
+import { prepareWorkBatch, addWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+import { PreparedInteractiveChecks } from "./interactive-checks.js";
+const event = "interactive.work_registration";
+function refuse(reason) {
+    throw new AppError("interactive_work_registration_invalid", "Interactive Work must belong to its retained Stage context and atomic graph", 2, { reason, effect: "no_effect" });
+}
+/** SQL-only assignment custody, usable after the Stage or workspace advanced.
+ * A launch owner must separately fence current Stage/input/physical state. */
+export function readRegisteredInteractiveWork(context, scope, bundle, workId) {
+    const custody = readWorkBatchCustody(context, workId), bound = custody.scope;
+    if (bundle.manifest.flow_id !== "interactive" || bound.project_id !== scope.projectId || bound.run_id !== scope.runId
+        || !["hardening", "review"].includes(bound.stage) || !bound.request_key.startsWith("interactive-"))
+        refuse("foreign_work_assignment");
+    const stage = bound.stage, requestId = bound.request_key.slice("interactive-".length);
+    const root = readDescriptorRootWork(context, scope, bundle);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.request_id')=? LIMIT 2", [scope.projectId, event, scope.runId, stage, bound.attempt, requestId]);
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 16 * 1024)
+        refuse("registration_custody_missing");
+    const receipt = JSON.parse(rows[0].payload_json);
+    if (!receipt || Object.keys(receipt).sort().join() !== "attempt,batch_sha256,bundle_sha256,context,parent_work_id,request_id,run_id,schema_id,stage,work_ids"
+        || receipt.schema_id !== "dd-flow/interactive-work-registration@1" || receipt.run_id !== scope.runId || receipt.stage !== stage
+        || receipt.attempt !== bound.attempt || receipt.request_id !== requestId || receipt.parent_work_id !== root.workId
+        || bound.parent_work_id !== root.workId || receipt.bundle_sha256 !== bundle.sha256
+        || hybridDigest(receipt.work_ids) !== hybridDigest(custody.work_ids))
+        refuse("registration_scope_changed");
+    const retained = readRetainedInteractiveWorkContext(context, { ...scope, stage, attempt: bound.attempt }, bundle, receipt.context);
+    const batch = interactiveWorkBatch(retained.record.input);
+    if (retained.record.input.owner_stage !== stage || custody.item_key !== retained.record.input.stage
+        || receipt.work_ids[custody.item_key] !== workId || Object.keys(receipt.work_ids).join() !== custody.item_key
+        || receipt.batch_sha256 !== hybridDigest(batch.works) || receipt.batch_sha256 !== custody.batch_sha256)
+        refuse("registration_batch_changed");
+    return { receipt, retained, packet: batch.works[0].payload.interactive, custody };
+}
+/** Registration replay returns original allocation metadata, not fresh launch authority. */
+export function registerInteractiveStageGraph(context, input, assertHandlerCustody) {
+    const requestId = input.requestId ?? "initial";
+    const role = input.role ?? input.stage;
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(requestId))
+        refuse("invalid_request_id");
+    const selected = readInteractiveStageScope(context, input), { scope, bundle } = selected;
+    const graph = stageGraphScope(context, scope.projectId, scope.runId, input.stage);
+    const root = readDescriptorRootWork(context, scope, bundle);
+    const requestKey = `interactive-${requestId}`;
+    const requestScope = { ...graph, stage: input.stage, parent_work_id: root.workId, request_key: requestKey };
+    const requestSha = hybridDigest(requestScope);
+    const read = () => {
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.request_id')=? LIMIT 2", [scope.projectId, event, scope.runId, input.stage, graph.attempt, requestId]);
+        if (!rows.length) {
+            if (context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='work.batch_registration' AND json_extract(payload_json,'$.request_sha256')=?", [scope.projectId, requestSha])
+                || context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND json_extract(payload_json,'$._dd_flow_batch_request.request_sha256')=?", [scope.projectId, scope.runId, requestSha]))
+                refuse("registration_receipt_missing");
+            return null;
+        }
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 16 * 1024)
+            refuse("ambiguous_registration");
+        const receipt = JSON.parse(rows[0].payload_json);
+        if (!receipt || Object.keys(receipt).sort().join() !== "attempt,batch_sha256,bundle_sha256,context,parent_work_id,request_id,run_id,schema_id,stage,work_ids"
+            || receipt.schema_id !== "dd-flow/interactive-work-registration@1" || receipt.run_id !== scope.runId
+            || receipt.stage !== input.stage || receipt.attempt !== graph.attempt || receipt.request_id !== requestId
+            || receipt.parent_work_id !== root.workId || receipt.bundle_sha256 !== bundle.sha256)
+            refuse("registration_scope_changed");
+        const retained = readRetainedInteractiveWorkContext(context, { ...scope, stage: input.stage, attempt: graph.attempt }, bundle, receipt.context);
+        if (retained.record.input.stage !== role)
+            refuse("registration_role_changed");
+        const batch = interactiveWorkBatch(retained.record.input);
+        if (receipt.batch_sha256 !== hybridDigest(batch.works)
+            || !receipt.work_ids || Object.keys(receipt.work_ids).sort().join() !== batch.works.map(item => item.key).sort().join()
+            || new Set(Object.values(receipt.work_ids)).size !== batch.works.length)
+            refuse("registration_batch_changed");
+        for (const [key, id] of Object.entries(receipt.work_ids)) {
+            const custody = readWorkBatchCustody(context, id);
+            if (custody.item_key !== key || custody.batch_sha256 !== receipt.batch_sha256 || hybridDigest(custody.scope) !== requestSha
+                || hybridDigest(custody.work_ids) !== hybridDigest(receipt.work_ids))
+                refuse("registration_work_changed");
+        }
+        return receipt;
+    };
+    const prior = context.db.readSnapshot(read);
+    if (prior)
+        return { ...prior, replayed: true };
+    const noOverlap = () => {
+        if (context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status IN ('created','running','paused') AND json_extract(payload_json,'$.kind') IN ('interactive-hardening','interactive-review')", [scope.projectId, scope.runId, root.workId]))
+            refuse("active_previous_round");
+    };
+    noOverlap();
+    const checks = input.checks ?? (role === "review" ? PreparedInteractiveChecks.prepareReview(context, input) ?? undefined : undefined);
+    if (checks && !input.checks) {
+        checks.retain(context);
+        checks.evidence(context);
+    }
+    const frame = PreparedInteractiveWorkContext.prepare(context, { ...input, ...(checks ? { checks } : {}) }), metadata = frame.snapshot();
+    if (metadata.attempt !== graph.attempt)
+        refuse("stage_attempt_changed");
+    const batchInput = { parentWorkId: root.workId, stage: input.stage, requestKey, value: interactiveWorkBatch(frame.workInput()) };
+    const prepared = prepareWorkBatch(context, batchInput);
+    frame.revalidate();
+    return context.db.writeTransaction(() => {
+        const racing = read();
+        if (racing)
+            return { ...racing, replayed: true };
+        assertHandlerCustody?.(context);
+        frame.assertCustody(context);
+        noOverlap();
+        if (readDescriptorRootWork(context, scope, bundle).workId !== root.workId)
+            refuse("root_changed");
+        frame.retainPreparedSql(context);
+        const allocated = addWorkBatch(context, { ...batchInput, prepared });
+        const receipt = { schema_id: "dd-flow/interactive-work-registration@1", run_id: scope.runId, stage: input.stage,
+            attempt: graph.attempt, request_id: requestId, parent_work_id: root.workId, bundle_sha256: bundle.sha256,
+            context: metadata.reference, batch_sha256: hybridDigest(prepared), work_ids: allocated.work_ids };
+        context.db.run("INSERT INTO audit_events(project_id,event_type,payload_json,created_at) VALUES(?,?,?,?)", [scope.projectId, event, JSON.stringify(receipt), context.now()]);
+        const verified = read();
+        if (!verified)
+            refuse("registration_not_retained");
+        return { ...verified, replayed: false };
+    });
+}

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

@@ -0,0 +1,115 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { interactiveWorkResultSchema } from "./interactive-work-batch.js";
+const issueKey = (workId, issueId) => JSON.stringify([workId, issueId]);
+/** Only independently settled review decisions close earlier items. Author
+ * decisions are proposals. Null issue_id tracks an unfinished Work outcome,
+ * not an invented product finding. Failed/cancelled attempts remain explicit. */
+export function pendingInteractiveIssues(history, binding) {
+    const pending = new Map();
+    for (const work of history.works) {
+        if (work.status !== "completed" || typeof work.result === "string") {
+            pending.set(issueKey(work.work_id, null), { work_id: work.work_id, issue_id: null, severity: "major", summary: String(work.result) });
+            continue;
+        }
+        const result = work.result;
+        if (work.stage === "review" && work.review_binding?.file_changes_sha256 === binding.file_changes_sha256
+            && work.review_binding.user_inputs_sha256 === binding.user_inputs_sha256 && work.review_binding.scope_revision === binding.scope_revision)
+            for (const decision of result.issue_decisions ?? [])
+                if (decision.outcome !== "still_open")
+                    pending.delete(issueKey(decision.work_id, decision.issue_id));
+        for (const issue of result.issues)
+            pending.set(issueKey(work.work_id, issue.id), {
+                work_id: work.work_id, issue_id: issue.id, severity: issue.severity, summary: issue.summary
+            });
+        if (result.verdict !== "ready" && !result.issues.length && !(result.issue_decisions ?? []).some(decision => decision.outcome === "still_open"))
+            pending.set(issueKey(work.work_id, null), { work_id: work.work_id, issue_id: null, severity: "major", summary: result.summary });
+    }
+    return [...pending.values()];
+}
+function refuse(reason) {
+    throw new AppError("interactive_work_result_invalid", "Interactive Work requires its exact assignment, observed changes and checks", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+}
+/** Proposal checks only. Physical source/check/Session custody must be prepared
+ * independently and fenced again in Work completion and Stage settlement. */
+export function validateInteractiveWorkResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || !schemaBytes.length || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    let result;
+    try {
+        result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_schema");
+    }
+    const validate = (() => {
+        try {
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+            if (schema.$id !== interactiveWorkResultSchema)
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: true, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    if (!validate(result) || result.schema_id !== interactiveWorkResultSchema || !result.summary.trim()
+        || result.limitations.some(item => !item.trim()))
+        refuse("invalid_schema");
+    const packet = binding.packet;
+    if (result.run_id !== packet.run_id || result.work_id !== binding.workId || result.stage !== packet.stage
+        || result.packet_sha256 !== packet.packet_sha256)
+        refuse("foreign_work_binding");
+    if (hybridDigest(result.changes) !== hybridDigest(binding.actualChanges))
+        refuse("unobserved_change_claim");
+    const paths = result.changes.map(item => item.path);
+    if (new Set(paths).size !== paths.length || result.changes.some(item => !packet.write_paths.includes(item.path)
+        || item.before_sha256 === item.after_sha256 && item.before_mode === item.after_mode
+        || Object.hasOwn(item, "before_mode") && ((item.before_sha256 === null) !== (item.before_mode === null)
+            || (item.after_sha256 === null) !== (item.after_mode === null))))
+        refuse("change_outside_write_scope");
+    if (packet.stage === "review" && (result.changes.length || packet.write_paths.length))
+        refuse("review_changed_sources");
+    if (hybridDigest(result.checks) !== hybridDigest(binding.checks))
+        refuse("unowned_check_claim");
+    const sources = new Map(packet.read_inputs.map(ref => [`${ref.root}:${ref.path}`, ref.sha256]));
+    for (const change of result.changes)
+        sources.delete(`workspace:${change.path}`);
+    for (const ref of [...binding.observedSources, ...binding.checks]) {
+        const key = `${ref.root}:${ref.path}`;
+        // Changed workspace inputs are superseded only by independently observed
+        // post-Work sources. Agent references never extend this allowed evidence.
+        const change = ref.root === "workspace" ? result.changes.find(item => item.path === ref.path) : null;
+        if (change && change.after_sha256 !== ref.sha256)
+            refuse("stale_observed_output");
+        if (ref.root === "run" && sources.has(key) && sources.get(key) !== ref.sha256)
+            refuse("conflicting_run_evidence");
+        sources.set(key, ref.sha256);
+    }
+    const ids = new Set();
+    for (const issue of result.issues) {
+        if (!issue.id.trim() || !issue.summary.trim() || ids.has(issue.id))
+            refuse("invalid_issue");
+        ids.add(issue.id);
+        if (issue.evidence.some(ref => sources.get(`${ref.root}:${ref.path}`) !== ref.sha256))
+            refuse("foreign_issue_evidence");
+    }
+    const pending = new Map((binding.priorIssues ?? []).map(issue => [issueKey(issue.work_id, issue.issue_id), issue]));
+    const decisions = result.issue_decisions ?? [], decided = new Set();
+    if (decisions.length !== pending.size)
+        refuse("incomplete_prior_issue_decisions");
+    for (const decision of decisions) {
+        const key = issueKey(decision.work_id, decision.issue_id), prior = pending.get(key);
+        if (!prior || decided.has(key) || !decision.summary.trim())
+            refuse("foreign_or_duplicate_issue_decision");
+        if (decision.evidence.some(ref => sources.get(`${ref.root}:${ref.path}`) !== ref.sha256))
+            refuse("foreign_issue_decision_evidence");
+        if (result.verdict === "ready" && decision.outcome === "still_open" && prior.severity !== "minor")
+            refuse("unsupported_ready_claim");
+        decided.add(key);
+    }
+    if (result.verdict === "ready" && (!binding.checksSatisfied || result.issues.some(issue => issue.severity !== "minor")))
+        refuse("unsupported_ready_claim");
+    return result;
+}