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

package/dist/services/interactive-stage-handlers.js

@@ -0,0 +1,289 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { readInteractiveStageScope, startInteractiveStage } from "./interactive-stage-entry.js";
+import { interactiveStages } from "../domain/interactive-flow.js";
+import { PreparedInteractiveStageObservation } from "./interactive-stage-observation.js";
+import { PreparedInteractiveChecks } from "./interactive-checks.js";
+import { PreparedDescriptorStageSettlement, 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 { readCompletedInteractiveWork } from "./interactive-work-completion.js";
+import { PreparedRetainedCheckEvidence } from "./code-checks.js";
+import { prepareInteractiveStageResult, assertInteractiveStageContinuation } from "./interactive-stage-results.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readInteractiveWorkHistory } from "./interactive-work-history.js";
+import { registerInteractiveStageGraph, readRegisteredInteractiveWork } from "./interactive-work-registration.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { PreparedInteractiveWorkCollection } from "./interactive-work-collection.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { prepareInteractiveFinishIntegration, prepareInteractiveIntegrationCustody } from "./interactive-git-dispatch.js";
+const event = "interactive.stage_acceptance";
+export const interactiveStageHandlers = Object.freeze(interactiveStages.map(stage => Object.freeze({ flowId: "interactive", stage,
+    entryId: "interactive-stage-entry", finishId: "interactive-stage-finish", entry: startInteractiveStage, finish: finishInteractiveStage })));
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_stage_invalid", "Interactive completion requires actual reviewed work and owned checks", 2, { reason, effect: "no_effect" });
+}
+function receipt(context, scope) {
+    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')=? LIMIT 2", [scope.projectId, event, scope.runId, scope.stage]);
+    if (rows.length > 1 || rows.some(row => Buffer.byteLength(row.payload_json) > 2 * 1024 * 1024))
+        refuse("ambiguous_stage_acceptance");
+    return rows[0] ? JSON.parse(rows[0].payload_json) : null;
+}
+function assertRetainedPlan(context, scope, proof) {
+    if (!proof.check_plan_sha256)
+        return;
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='interactive.check_plan' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.sha256')=? LIMIT 2", [scope.projectId, scope.runId, proof.check_plan_sha256]);
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 1024 * 1024)
+        refuse("accepted_check_plan_required");
+    const value = JSON.parse(rows[0].payload_json), plan = value?.plan, binding = proof.binding;
+    if (value.sha256 !== proof.check_plan_sha256 || hybridDigest(plan) !== value.sha256 || plan.run_id !== scope.runId || plan.stage !== scope.stage
+        || plan.bundle_sha256 !== proof.bundle_sha256 || plan.input_sha256 !== binding.inputSha256
+        || plan.user_inputs_sha256 !== binding.userInputsSha256 || plan.scope_revision !== binding.scopeRevision
+        || plan.file_changes_sha256 !== binding.fileChangesSha256 || plan.no_checks_reason !== proof.no_checks_reason
+        || !Array.isArray(plan.checks) || Boolean(plan.checks.length) !== Boolean(proof.checks.length))
+        refuse("accepted_check_plan_changed");
+}
+/** Historical replay uses accepted SQL/result/check custody, never today's
+ * workspace or today's scope to manufacture a replacement successful result. */
+function acceptedStage(context, input, selected) {
+    const { scope, bundle } = selected, accepted = readAcceptedStageData(context, scope), proof = receipt(context, scope);
+    const value = JSON.parse(accepted.bytes.toString("utf8"));
+    if (!proof || proof.schema_id !== "dd-flow/interactive-stage-acceptance@1" || proof.run_id !== input.runId || proof.stage !== input.stage
+        || proof.bundle_sha256 !== bundle.sha256 || proof.result_sha256 !== accepted.result.sha256 || accepted.data_schema_id !== "dd-flow/interactive-stage-result@1"
+        || proof.binding.runId !== input.runId || proof.binding.stage !== input.stage || proof.binding.inputSha256 !== accepted.input_sha256
+        || value.details.review?.verdict === "revise" || !Array.isArray(proof.checks)
+        || (["hardening", "review"].includes(input.stage)
+            ? !/^[a-f0-9]{64}$/.test(proof.check_plan_sha256 ?? "") || !proof.checks.length && !proof.no_checks_reason?.trim()
+            : proof.check_plan_sha256 !== null || proof.checks.length !== 0 || proof.no_checks_reason !== null))
+        refuse("accepted_stage_proof_required");
+    const prepared = prepareInteractiveStageResult(accepted.bytes, bundle.descriptor.stageBlob(input.stage, "result_schema"), proof.binding);
+    if (!prepared.bytes.equals(accepted.bytes))
+        refuse("accepted_stage_result_changed");
+    const checks = proof.checks.length ? PreparedRetainedCheckEvidence.prepare(context, { projectId: scope.projectId, runId: input.runId, references: proof.checks }) : null;
+    const integration = input.stage === "integration" ? prepareInteractiveIntegrationCustody(context, input) : null;
+    if (integration ? !proof.integration?.binding || hybridDigest(proof.integration.binding) !== hybridDigest(integration.binding)
+        || proof.integration.observation?.schema_id !== "dd-flow/interactive-finish-integration@1"
+        || proof.integration.observation.operation_sha256 !== integration.binding.operation_sha256
+        || proof.integration.observation.no_op !== integration.reviewed.empty
+        || Boolean(proof.integration.observation.git) === integration.reviewed.empty
+        : proof.integration !== undefined)
+        refuse("accepted_integration_proof_required");
+    const assertProof = (writer) => {
+        if (hybridDigest(receipt(writer, scope)) !== hybridDigest(proof)
+            || hybridDigest(readAcceptedStageData(writer, scope)) !== hybridDigest(accepted))
+            refuse("accepted_stage_proof_changed");
+        assertRetainedPlan(writer, scope, proof);
+        checks?.assertCustody(writer);
+        integration?.assertCustody(writer);
+        const collection = proof.collection;
+        if (collection) {
+            if (hybridDigest(collection) !== proof.binding.workCollectionSha256 || collection.run_id !== input.runId || collection.stage !== input.stage
+                || collection.bundle_sha256 !== bundle.sha256 || collection.input_sha256 !== accepted.input_sha256)
+                refuse("accepted_work_collection_changed");
+            const work = readCompletedInteractiveWork(writer, { ...scope, workId: collection.work_id }, bundle);
+            if (hybridDigest(work.receipt) !== collection.settlement_sha256 || work.receipt.result_sha256 !== collection.result_sha256
+                || hybridDigest(work.start.assignment.receipt) !== collection.registration_sha256
+                || hybridDigest(work.start.receipt.actor) !== hybridDigest(collection.actor))
+                refuse("accepted_work_collection_changed");
+        }
+        else if (proof.binding.workCollectionSha256 !== null)
+            refuse("accepted_work_collection_changed");
+    };
+    context.db.readSnapshot(() => assertProof(context));
+    return { accepted, proof, result: prepared.result, assertCustody: assertProof };
+}
+/** Historical semantic and physical Stage custody for terminal integration.
+ * Reading an accepted proposal alone is not proof of coordinator settlement.
+ * Lifecycle keys are prepared outside the SQL writer; no current source capture
+ * or new Stage/Work allocation occurs here. */
+export function readAcceptedInteractiveStage(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("physical_preparation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, input, true);
+    if (!selected.replay)
+        refuse("accepted_stage_required");
+    const retained = acceptedStage(context, input, selected);
+    const matchKeys = entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, input.stage, input.projectRoot));
+    const settlement = readAcceptedDescriptorStageSettlement(context, selected.scope, selected.bundle, matchKeys);
+    const assertCustody = (writer) => {
+        retained.assertCustody(writer);
+        if (hybridDigest(readAcceptedDescriptorStageSettlement(writer, selected.scope, selected.bundle, matchKeys)) !== hybridDigest(settlement))
+            refuse("accepted_stage_settlement_changed");
+    };
+    context.db.readSnapshot(() => assertCustody(context));
+    return { result: structuredClone(retained.result), proof: structuredClone(retained.proof),
+        bytes: Buffer.from(retained.accepted.bytes), reference: structuredClone(retained.accepted.result), assertCustody };
+}
+function prepareReplay(context, input, selected) {
+    const retained = acceptedStage(context, input, selected);
+    const prepared = prepareInteractiveStageResult(input.bytes, selected.bundle.descriptor.stageBlob(input.stage, "result_schema"), retained.proof.binding);
+    if (!prepared.bytes.equals(retained.accepted.bytes))
+        refuse("accepted_stage_result_changed");
+    return { settlement: PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes: prepared.bytes }),
+        resultSha256: retained.proof.result_sha256, assertCustody: retained.assertCustody };
+}
+function retainAcceptance(context, scope, proof) {
+    if (Buffer.byteLength(JSON.stringify(proof)) > 2 * 1024 * 1024)
+        refuse("unbounded_stage_acceptance");
+    const prior = receipt(context, scope);
+    if (prior) {
+        if (hybridDigest(prior) !== hybridDigest(proof))
+            refuse("accepted_stage_proof_changed");
+    }
+    else
+        appendAudit(context, { projectId: scope.projectId, eventType: event, payload: proof });
+}
+function pendingAcceptedIntegration(context, input, resultSha256, cause) {
+    let committed = false;
+    try {
+        const selected = readInteractiveStageScope(context, input, true);
+        committed = selected.replay && receipt(context, selected.scope)?.result_sha256 === resultSha256
+            && readAcceptedStageData(context, selected.scope).result.sha256 === resultSha256;
+    }
+    catch { /* No independently retained terminal acceptance. */ }
+    if (!committed)
+        throw cause;
+    throw new AppError("interactive_finish_pending", "Accepted integration requires projection or RUN settlement reconciliation", 1, { effect: "committed", recoverable: true, run_id: input.runId, next_action: "reconcile_accepted_integration",
+        cause: cause instanceof AppError ? cause.code : "finish_settlement_failed" });
+}
+/** Git effects are issued separately by the scoped operation owner. This
+ * handler consumes observed integration, never an agent's commit claim. A
+ * committed Stage can be followed by an interrupted RUN closure; replay seals
+ * that original result without revisiting today's mutable workspace. */
+function finishIntegration(context, input) {
+    const selected = readInteractiveStageScope(context, input, true), { scope, bundle } = selected;
+    if (selected.replay) {
+        const replay = prepareReplay(context, input, selected);
+        try {
+            const stage = replay.settlement.apply(context, replay.assertCustody), accepted = readAcceptedInteractiveStage(context, input);
+            return { ...stage, ...PreparedDescriptorRunSettlement.prepare(context, input).apply(context, accepted.assertCustody) };
+        }
+        catch (error) {
+            return pendingAcceptedIntegration(context, input, replay.resultSha256, error);
+        }
+    }
+    if (receipt(context, scope))
+        refuse("orphan_stage_acceptance");
+    const review = readAcceptedInteractiveStage(context, { ...input, stage: "review" });
+    const git = prepareInteractiveFinishIntegration(context, input);
+    const packet = readDescriptorStageInput(context, scope, bundle);
+    if (packet.input.predecessor?.stage !== "review" || hybridDigest(packet.input.predecessor.result) !== hybridDigest(review.reference))
+        refuse("accepted_review_predecessor_required");
+    const original = git.reviewed;
+    const binding = { runId: input.runId, stage: "integration", inputSha256: packet.inputSha256,
+        baselineSha256: original.baseline_sha256, userInputsSha256: original.user_inputs_sha256, scopeRevision: original.scope_revision,
+        fileChangesSha256: original.file_changes_sha256, finishRequested: true, workCollectionSha256: null, review: review.result.details.review,
+        retainedLimitations: review.result.details.limitations,
+        predecessors: [{ stage: "review", ...review.reference }] };
+    const prepared = prepareInteractiveStageResult(input.bytes, bundle.descriptor.stageBlob("integration", "result_schema"), binding);
+    assertInteractiveStageContinuation(prepared.result, review.result);
+    const proof = { schema_id: "dd-flow/interactive-stage-acceptance@1", run_id: input.runId, stage: "integration", bundle_sha256: bundle.sha256,
+        result_sha256: hash(prepared.bytes), binding, collection: null, check_plan_sha256: null, checks: [], no_checks_reason: null,
+        integration: { binding: git.binding, observation: git.value() } };
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes: prepared.bytes });
+    review.assertCustody(context);
+    git.revalidate();
+    try {
+        const stage = settlement.apply(context, writer => {
+            review.assertCustody(writer);
+            git.assertCustody(writer);
+            retainAcceptance(writer, scope, proof);
+        });
+        const accepted = readAcceptedInteractiveStage(context, input);
+        return { ...stage, ...PreparedDescriptorRunSettlement.prepare(context, input).apply(context, accepted.assertCustody) };
+    }
+    catch (error) {
+        return pendingAcceptedIntegration(context, input, proof.result_sha256, error);
+    }
+}
+/** Internal handlers. Public admission still requires registered descriptors,
+ * controller/command wiring and installed family qualification. */
+export function finishInteractiveStage(context, input) {
+    if (input.stage === "integration")
+        return finishIntegration(context, input);
+    const selected = readInteractiveStageScope(context, input, true), { scope, bundle } = selected;
+    if (selected.replay) {
+        const replay = prepareReplay(context, input, selected);
+        return replay.settlement.apply(context, replay.assertCustody);
+    }
+    if (receipt(context, scope))
+        refuse("orphan_stage_acceptance");
+    const observation = PreparedInteractiveStageObservation.prepare(context, input), proposal = observation.prepareResult(input.bytes);
+    if (proposal.result.details.review?.verdict === "revise")
+        throw new AppError("interactive_review_corrections_required", "Independent review has unresolved work; the Stage remains open", 2, { phase: "prepare", effect: "no_effect", recoverable: true, projection: { outcome: "needs_repair", review: proposal.result.details.review,
+                review_work_id: observation.collectionProof()?.work_id, work_collection_sha256: proposal.result.work_collection_sha256 }, continuation: { kind: "correction_required" } });
+    const checked = ["hardening", "review"].includes(input.stage) ? observation.prepareCheckedResult(context, input.bytes, PreparedInteractiveChecks.restore(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage })) : null;
+    const prepared = checked ?? proposal;
+    const proof = { schema_id: "dd-flow/interactive-stage-acceptance@1", run_id: input.runId, stage: input.stage,
+        bundle_sha256: bundle.sha256, result_sha256: hash(prepared.bytes), binding: observation.binding(), collection: observation.collectionProof(),
+        check_plan_sha256: checked?.check_plan_sha256 ?? null, checks: checked?.checks ?? [], no_checks_reason: checked?.no_checks_reason ?? null };
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes: prepared.bytes });
+    observation.revalidate(context);
+    checked?.revalidate(context);
+    return settlement.apply(context, writer => {
+        observation.assertCustody(writer);
+        checked?.assertCustody(writer);
+        retainAcceptance(writer, scope, proof);
+    });
+}
+/** A negative review permits a separate scoped author, not reviewer writes or
+ * Stage rewind. Replaying allocation returns its original Work even if active. */
+export function registerInteractiveReviewCorrection(context, input) {
+    if (typeof input.reviewWorkId !== "string" || !input.reviewWorkId || input.reviewWorkId.length > 256 || /[\0\r\n]/.test(input.reviewWorkId))
+        refuse("review_work_id_required");
+    const stage = "review", selected = readInteractiveStageScope(context, { ...input, stage }), { scope, bundle } = selected;
+    const packet = readDescriptorStageInput(context, scope, bundle), review = readCompletedInteractiveWork(context, { ...scope, workId: input.reviewWorkId }, bundle);
+    if (review.start.assignment.packet.stage !== "review" || review.start.assignment.packet.owner_stage !== "review"
+        || review.start.assignment.receipt.attempt !== packet.attempt || review.result.verdict === "ready")
+        refuse("negative_review_required_for_correction");
+    const requestId = `correction-${hybridDigest({ work_id: input.reviewWorkId, result_sha256: review.receipt.result_sha256, input_sha256: packet.inputSha256 }).slice(0, 40)}`;
+    const args = { projectRoot: input.projectRoot, runId: input.runId, stage, role: "hardening",
+        requestId, gitExecutable: readInteractiveWorkGit(bundle).git_executable };
+    const prior = context.db.get("SELECT 1 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')='review' AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.request_id')=? LIMIT 1", [scope.projectId, input.runId, packet.attempt, requestId]);
+    if (prior)
+        return registerInteractiveStageGraph(context, args);
+    const history = readInteractiveWorkHistory(context, scope, bundle);
+    if (history.works.at(-1)?.work_id !== input.reviewWorkId)
+        refuse("latest_negative_review_required");
+    return registerInteractiveStageGraph(context, args, writer => {
+        if (hybridDigest(readInteractiveWorkHistory(writer, scope, bundle)) !== hybridDigest(history))
+            refuse("correction_history_changed");
+    });
+}
+/** Hand off a settled correction and its current check evidence to a fresh
+ * read-only critic. An author result never becomes accepted review itself. */
+export function registerInteractiveCorrectionReview(context, input) {
+    if (typeof input.correctionWorkId !== "string" || !input.correctionWorkId || input.correctionWorkId.length > 256 || /[\0\r\n]/.test(input.correctionWorkId))
+        refuse("correction_work_id_required");
+    const stage = "review", { scope, bundle } = readInteractiveStageScope(context, { ...input, stage });
+    const packet = readDescriptorStageInput(context, scope, bundle), author = readCompletedInteractiveWork(context, { ...scope, workId: input.correctionWorkId }, bundle);
+    if (author.start.assignment.packet.owner_stage !== "review" || author.start.assignment.packet.stage !== "hardening"
+        || author.start.assignment.receipt.attempt !== packet.attempt || author.result.verdict !== "ready")
+        refuse("ready_correction_author_required");
+    const requestId = `recheck-${hybridDigest({ work_id: input.correctionWorkId, result_sha256: author.receipt.result_sha256, input_sha256: packet.inputSha256 }).slice(0, 40)}`;
+    const args = { projectRoot: input.projectRoot, runId: input.runId, stage, requestId, gitExecutable: readInteractiveWorkGit(bundle).git_executable };
+    const prior = context.db.get("SELECT 1 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')='review' AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.request_id')=? LIMIT 1", [scope.projectId, input.runId, packet.attempt, requestId]);
+    if (prior) {
+        const registered = registerInteractiveStageGraph(context, args);
+        const retained = readRegisteredInteractiveWork(context, scope, bundle, registered.work_ids.review).retained.body;
+        const originalAuthor = retained.work_history.works.at(-1);
+        if (!retained.stage_checks || originalAuthor?.work_id !== input.correctionWorkId
+            || originalAuthor.result_sha256 !== author.receipt.result_sha256)
+            refuse("recheck_registration_changed");
+        return registered;
+    }
+    const collection = PreparedInteractiveWorkCollection.prepareCorrectionAuthor(context, input);
+    if (collection.snapshot().work_id !== input.correctionWorkId)
+        refuse("latest_correction_author_required");
+    const checks = PreparedInteractiveChecks.restore(context, { ...input, stage }), evidence = checks.evidence(context);
+    collection.revalidate(context);
+    return registerInteractiveStageGraph(context, { ...args, checks }, writer => {
+        collection.assertCustody(writer);
+        checks.assertCustody(writer);
+        evidence?.assertCustody(writer);
+    });
+}

package/dist/services/interactive-stage-observation.js

@@ -0,0 +1,136 @@
+import { AppError } from "../shared/errors.js";
+import { interactiveStages } from "../domain/interactive-flow.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readInteractiveStageScope } from "./interactive-stage-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { PreparedInteractiveWorkspaceChanges } from "./interactive-mutation-scope.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { PreparedInteractiveWorkCollection } from "./interactive-work-collection.js";
+import { readInteractiveWorkHistory } from "./interactive-work-history.js";
+import { pendingInteractiveIssues } from "./interactive-work-results.js";
+import { prepareInteractiveStageResult, assertInteractiveStageContinuation } from "./interactive-stage-results.js";
+import { PreparedInteractiveChecks } from "./interactive-checks.js";
+function refuse(reason) {
+    throw new AppError("interactive_stage_observation_invalid", "Interactive result requires the current task, actual patch and independently settled Work", 2, { reason, effect: "no_effect" });
+}
+/** Actual task/patch/Work observation for Stage handlers. This grants neither
+ * successful command checks nor Git integration or Stage/RUN acceptance. */
+export class PreparedInteractiveStageObservation {
+    #selected;
+    #packet;
+    #previous;
+    #prior;
+    #changes;
+    #history;
+    #collection;
+    #binding;
+    constructor(selected, packet, previous, changes, history, collection, binding) {
+        this.#selected = selected;
+        this.#packet = packet;
+        this.#previous = previous;
+        this.#prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+        this.#changes = changes;
+        this.#history = history;
+        this.#collection = collection;
+        this.#binding = binding;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        // Integration must observe accepted reviewed bytes through the Git owner,
+        // not reuse a pre-commit workspace observation as integration evidence.
+        if (input.stage === "integration")
+            refuse("integration_observation_required");
+        const selected = readInteractiveStageScope(context, input), { scope, bundle, run } = selected, stage = input.stage;
+        const packet = readDescriptorStageInput(context, scope, bundle), index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== stage
+            || !index.stage_runs?.some((item) => item.stage === stage && item.attempt === packet.attempt && item.status === "running")
+            || selected.selected.needs_scope_refresh)
+            refuse("active_current_scope_required");
+        const previousStage = interactiveStages[interactiveStages.indexOf(stage) - 1];
+        const previous = previousStage ? readAcceptedStageData(context, { ...scope, stage: previousStage }) : null;
+        if (previous && previous.data_schema_id !== "dd-flow/interactive-stage-result@1")
+            refuse("accepted_predecessor_required");
+        if (previous ? packet.input.predecessor?.stage !== previousStage || hybridDigest(packet.input.predecessor.result) !== hybridDigest(previous.result)
+            : packet.input.predecessor != null)
+            refuse("accepted_predecessor_required");
+        const 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 });
+        const patch = changes.snapshot(), workStage = stage === "hardening" || stage === "review";
+        const history = workStage ? readInteractiveWorkHistory(context, scope, bundle) : null;
+        const registered = history?.works.some(work => work.owner_stage === stage && work.attempt === packet.attempt);
+        const collection = workStage && (stage === "review" || patch.delta.changes.length || registered)
+            ? PreparedInteractiveWorkCollection.prepare(context, { ...input, stage }) : null;
+        const work = collection?.results()[0]?.result;
+        const pending = history ? pendingInteractiveIssues(history, { file_changes_sha256: hybridDigest(patch.delta.changes),
+            user_inputs_sha256: selected.selected.inputs.sha256, scope_revision: selected.selected.revision }) : [];
+        const review = stage === "review" && work ? { verdict: work.verdict === "ready" && !pending.some(issue => issue.severity !== "minor")
+                ? "accept" : "revise", summary: work.summary } : null;
+        const binding = { runId: input.runId, stage, inputSha256: packet.inputSha256,
+            baselineSha256: selected.selected.baseline.sha256, userInputsSha256: selected.selected.inputs.sha256,
+            scopeRevision: selected.selected.revision, fileChangesSha256: hybridDigest(patch.delta.changes),
+            finishRequested: selected.selected.inputs.finish_requested, workCollectionSha256: collection?.sha256 ?? null, review,
+            retainedLimitations: work?.limitations ?? [],
+            predecessors: previous && previousStage ? [{ stage: previousStage, ...previous.result }] : [] };
+        const prepared = new PreparedInteractiveStageObservation(selected, packet, previous, changes, history, collection, binding);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    binding() { return structuredClone(this.#binding); }
+    collectionProof() { return this.#collection?.snapshot() ?? null; }
+    prepareResult(bytes) {
+        const verdict = this.#collection?.results()[0]?.result.verdict;
+        if (this.#binding.stage === "hardening" && verdict !== undefined && verdict !== "ready")
+            refuse("hardening_work_not_ready");
+        const prepared = prepareInteractiveStageResult(bytes, this.#selected.bundle.descriptor.stageBlob(this.#binding.stage, "result_schema"), this.#binding);
+        // Projection retains the latest Work's limitations; original history stays
+        // separate so a later independent Work can reassess earlier limitations.
+        if (this.#prior)
+            assertInteractiveStageContinuation(prepared.result, this.#prior);
+        return prepared;
+    }
+    /** A handler must consume this joint fence with ordinary Stage settlement.
+     * No-check decisions remain explicit, never a fabricated passed receipt. */
+    prepareCheckedResult(context, bytes, checks) {
+        if (!(checks instanceof PreparedInteractiveChecks) || !["hardening", "review"].includes(this.#binding.stage))
+            refuse("owned_stage_checks_required");
+        const plan = checks.value(), binding = this.#binding;
+        if (plan.run_id !== binding.runId || plan.stage !== binding.stage || plan.bundle_sha256 !== this.#selected.bundle.sha256
+            || plan.input_sha256 !== binding.inputSha256 || plan.user_inputs_sha256 !== binding.userInputsSha256
+            || plan.scope_revision !== binding.scopeRevision || plan.file_changes_sha256 !== binding.fileChangesSha256)
+            refuse("foreign_stage_checks");
+        this.revalidate(context);
+        const evidence = checks.evidence(context), prepared = this.prepareResult(bytes);
+        return { ...prepared, check_plan_sha256: checks.sha256, checks: evidence?.retainedReferences(context) ?? [], no_checks_reason: plan.no_checks_reason,
+            assertCustody: (writer) => { this.assertCustody(writer); checks.assertCustody(writer); evidence?.assertCustody(writer); },
+            revalidate: (reader) => { this.revalidate(reader); checks.revalidate(reader); evidence?.revalidate(reader); } };
+    }
+    revalidate(context) {
+        readInteractiveWorkGit(this.#selected.bundle);
+        this.#changes.revalidate();
+        this.#collection?.revalidate(context);
+        context.db.readSnapshot(() => this.assertSelection(context));
+    }
+    assertCustody(context) {
+        this.#changes.assertCustody(context);
+        this.assertSelection(context);
+    }
+    assertSelection(context) {
+        this.#selected.assertCustody(context);
+        this.#collection?.assertCustody(context);
+        const { scope, bundle } = this.#selected, packet = readDescriptorStageInput(context, scope, bundle);
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== scope.stage || !index.stage_runs?.some((item) => item.stage === scope.stage && item.attempt === packet.attempt && item.status === "running"))
+            refuse("active_current_scope_required");
+        if (hybridDigest(packet) !== hybridDigest(this.#packet))
+            refuse("stage_input_changed");
+        if (this.#previous && hybridDigest(readAcceptedStageData(context, { ...scope, stage: this.#binding.predecessors[0].stage })) !== hybridDigest(this.#previous))
+            refuse("predecessor_changed");
+        if (this.#history && hybridDigest(readInteractiveWorkHistory(context, scope, bundle)) !== hybridDigest(this.#history))
+            refuse("work_history_changed");
+    }
+}

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

@@ -0,0 +1,111 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { interactiveStages } from "../domain/interactive-flow.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    throw new AppError("interactive_stage_result_invalid", "Interactive Stage requires its actual inputs, scoped changes and independent review", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+}
+/** Pure proposal validation. A valid JSON result does not prove semantic
+ * correctness, physical reviewer independence, successful checks or Git effects.
+ * Those bindings come from ordinary Stage/Work/operation owners at settlement. */
+export function validateInteractiveStageResult(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 !== "dd-flow/interactive-stage-result@1")
+                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 !== "dd-flow/interactive-stage-result@1" || result.flow_id !== "interactive"
+        || !result.summary.trim() || !result.details.change_summary.trim() || result.details.limitations.some(item => !item.trim())
+        || result.details.review && !result.details.review.summary.trim())
+        refuse("invalid_schema");
+    if (result.run_id !== binding.runId || result.stage !== binding.stage || result.input_sha256 !== binding.inputSha256
+        || result.baseline_sha256 !== binding.baselineSha256 || result.user_inputs_sha256 !== binding.userInputsSha256
+        || result.scope_revision !== binding.scopeRevision || result.file_changes_sha256 !== binding.fileChangesSha256
+        || hybridDigest(result.predecessors) !== hybridDigest(binding.predecessors))
+        refuse("foreign_stage_binding");
+    if (result.work_collection_sha256 !== binding.workCollectionSha256 || hybridDigest(result.details.review) !== hybridDigest(binding.review))
+        refuse("unowned_work_or_review");
+    const preflight = binding.stage === "preflight", empty = binding.fileChangesSha256 === hybridDigest([]);
+    if (preflight ? result.predecessors.length !== 0 : result.predecessors.length !== 1
+        || result.predecessors[0]?.stage !== interactiveStages[interactiveStages.indexOf(binding.stage) - 1])
+        refuse("foreign_stage_predecessor");
+    if (preflight && (!empty || binding.finishRequested))
+        refuse("preflight_changed_or_already_finished");
+    if (!preflight && !binding.finishRequested)
+        refuse("explicit_finish_required");
+    if (binding.stage === "review" || binding.stage === "hardening" && !empty) {
+        if (!binding.workCollectionSha256)
+            refuse("completed_work_collection_required");
+    }
+    if (["review", "integration"].includes(binding.stage) ? binding.review === null : binding.review !== null)
+        refuse("review_stage_required");
+    if (binding.stage === "integration" && binding.review?.verdict !== "accept")
+        refuse("accepted_review_required");
+    return result;
+}
+/** Agents supply semantic summary/details, not manually calculated custody
+ * hashes. Binding must come from CLI-issued context/Work selection and be
+ * fenced against current SQL at settlement, never inferred from this proposal
+ * or silently refreshed to newer ambient inputs. Conflicting supplied claims
+ * refuse rather than being overwritten with valid-looking current metadata. */
+export function prepareInteractiveStageResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    let proposal;
+    try {
+        proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_schema");
+    }
+    if (!proposal || typeof proposal !== "object" || Array.isArray(proposal)
+        || !proposal.details || typeof proposal.details !== "object" || Array.isArray(proposal.details))
+        refuse("invalid_schema");
+    const owned = { schema_id: "dd-flow/interactive-stage-result@1", flow_id: "interactive", run_id: binding.runId, stage: binding.stage,
+        input_sha256: binding.inputSha256, baseline_sha256: binding.baselineSha256, user_inputs_sha256: binding.userInputsSha256,
+        scope_revision: binding.scopeRevision, file_changes_sha256: binding.fileChangesSha256, work_collection_sha256: binding.workCollectionSha256,
+        predecessors: binding.predecessors };
+    for (const [key, value] of Object.entries(owned))
+        if (Object.hasOwn(proposal, key) && hybridDigest(proposal[key]) !== hybridDigest(value))
+            refuse("foreign_stage_binding");
+    const details = proposal.details;
+    if (Object.hasOwn(details, "review") && hybridDigest(details.review) !== hybridDigest(binding.review))
+        refuse("unowned_work_or_review");
+    const supplied = details.limitations;
+    const limitations = Array.isArray(supplied)
+        ? [...supplied, ...(binding.retainedLimitations ?? []).filter(item => !supplied.includes(item))] : supplied;
+    const encoded = Buffer.from(JSON.stringify({ ...proposal, ...owned, details: { ...details, review: binding.review, limitations } }));
+    return { result: validateInteractiveStageResult(encoded, schemaBytes, binding), bytes: encoded };
+}
+/** Later HITL answers/hardening may legitimately revise an earlier scope. Once
+ * review is accepted, integration cannot change that reviewed task or patch. */
+export function assertInteractiveStageContinuation(result, prior) {
+    if (result.run_id !== prior.run_id || result.baseline_sha256 !== prior.baseline_sha256
+        || interactiveStages.indexOf(result.stage) !== interactiveStages.indexOf(prior.stage) + 1)
+        refuse("foreign_stage_predecessor");
+    if (result.stage === "integration" && (prior.details.review?.verdict !== "accept"
+        || result.user_inputs_sha256 !== prior.user_inputs_sha256 || result.scope_revision !== prior.scope_revision
+        || result.file_changes_sha256 !== prior.file_changes_sha256
+        || result.details.change_summary !== prior.details.change_summary || hybridDigest(result.details.review) !== hybridDigest(prior.details.review)
+        || prior.details.limitations.some(item => !result.details.limitations.includes(item))))
+        refuse("accepted_review_changed");
+}
+/** A real revise verdict must never be projected as successful completion. */
+export function interactiveStageDisposition(result) {
+    return result.details.review?.verdict === "revise" ? "needs_work" : "ready";
+}