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

package/dist/services/review-fix-stage-handlers.js

@@ -0,0 +1,176 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { reviewFixStages } from "../domain/review-fix-flow.js";
+import { readReviewFixStageScope, startReviewFixStage } from "./review-fix-stage-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement, readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { readAcceptedStageData, prepareStagePacket, acceptStagePacket, prepareStageReport, acceptStageReport, publishStagePacket, publishStageReport, resolveStagePublicationPath } from "./stage-report-renderer.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { assertReviewFixStageScope, validateReviewFixStageResult, reviewFixHandoffDisposition } from "./review-fix-stage-results.js";
+import { prepareReviewFixHandoff } from "./review-fix-handoff.js";
+import { assertDiagnosticSessionIndependence } from "./diagnostic-work-collection.js";
+import { readDiagnosticSnapshot } from "./diagnostic-snapshot.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("review_fix_stage_invalid", "Review-fix requires original scope, independent review and a raw handoff", 2, { reason, effect: "no_effect" });
+}
+export const reviewFixStageHandlers = Object.freeze(reviewFixStages.map(stage => Object.freeze({ flowId: "review-fix", stage,
+    entryId: "review-fix-stage-entry", finishId: "review-fix-stage-finish", entry: startReviewFixStage, finish: finishReviewFixStage })));
+/** Read retained raw bytes for terminal replay, never recapture newer messages. */
+function readHandoff(context, scope, attempt, file) {
+    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')='handoff' AND json_extract(payload_json,'$.attempt')=? LIMIT 33", [scope.projectId, scope.runId, attempt]);
+    if (rows.length > 32)
+        refuse("handoff_custody_invalid");
+    const packets = rows.map(row => {
+        if (Buffer.byteLength(row.payload_json) > 6 * 1024 * 1024)
+            refuse("handoff_exceeds_bound");
+        return JSON.parse(row.payload_json);
+    }).filter(packet => typeof packet.file === "string" && resolveStagePublicationPath(context, scope.projectId, scope.runId, packet.file) === file);
+    if (!packets.length)
+        return null;
+    if (packets.length !== 1 || typeof packets[0].base64 !== "string")
+        refuse("accepted_handoff_missing");
+    const bytes = Buffer.from(packets[0].base64, "base64");
+    if (!bytes.length || bytes.length > 4 * 1024 * 1024 || bytes.toString("base64") !== packets[0].base64 || hash(bytes) !== packets[0].sha256)
+        refuse("accepted_handoff_changed");
+    return { bytes, sha256: hash(bytes) };
+}
+/** Generic Stage/RUN settlement remains the sole lifecycle owner. This handler
+ * writes only retained runtime packets/reports, never project files or SDLC. */
+export function finishReviewFixStage(context, input) {
+    if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    const selected = readReviewFixStageScope(context, input, true), { bundle, source, scope, replay, snapshot } = selected;
+    const packet = readDescriptorStageInput(context, scope, bundle, true, true);
+    const stage = input.stage;
+    const previousStage = stage === "scope-review" ? "intake" : stage === "handoff" ? "scope-review" : null;
+    const previous = previousStage ? readAcceptedStageData(context, { ...scope, stage: previousStage }) : null;
+    const prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+    if (previous && (packet.input.predecessor?.stage !== previousStage || hybridDigest(packet.input.predecessor.result) !== hybridDigest(previous.result)))
+        refuse("predecessor_changed");
+    const bytes = Buffer.from(input.bytes);
+    let result;
+    const users = !replay ? readPreparedMemoryFlowUserInputs(context, scope, "review-fix", bundle) : null;
+    if (replay) {
+        const accepted = readAcceptedStageData(context, scope);
+        if (!accepted.bytes.equals(bytes))
+            refuse("accepted_result_changed");
+        result = JSON.parse(accepted.bytes.toString("utf8"));
+    }
+    else {
+        result = validateReviewFixStageResult(bytes, bundle.descriptor.stageBlob(stage, "result_schema"), {
+            runId: input.runId, stage, inputSha256: packet.inputSha256, intakeSha256: source.sha256,
+            snapshotSha256: snapshot.source_sha256, userInputsSha256: hybridDigest(users),
+            findingIds: source.intake.selected_findings.map(finding => finding.id), predecessors: previous ? [{ stage: previousStage, ...previous.result }] : [],
+            userSources: users.sources.map(item => {
+                if (!["request", "question", "answer"].includes(item.role))
+                    return refuse("invalid_user_input_role");
+                return { root: item.root, path: item.path, sha256: item.sha256, role: item.role };
+            })
+        });
+        if (source.intake.limitations.some(item => !result.details.limitations.includes(item)))
+            refuse("source_limitations_missing");
+        if (prior)
+            assertReviewFixStageScope(result, prior);
+    }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, input);
+    const keys = (name) => entityReferenceVariants(input.runId).map(ref => stageLifecycleMatchKey("stage_finish", ref, name, input.projectRoot));
+    const intakeKeys = stage !== "intake" ? keys("intake") : [];
+    const reviewKeys = stage === "handoff" ? keys("scope-review") : [];
+    const readOwners = (reader) => {
+        const physical = (id) => {
+            const session = reader.db.get("SELECT harness,provider_session_id FROM sessions WHERE project_id=? AND run_id=? AND session_id=?", [scope.projectId, scope.runId, id]);
+            if (!session?.harness || !session.provider_session_id)
+                refuse("physical_owner_missing");
+            return session;
+        };
+        const intake = stage !== "intake" ? readAcceptedDescriptorStageSettlement(reader, { ...scope, stage: "intake" }, bundle, intakeKeys) : null;
+        const review = stage === "handoff" ? readAcceptedDescriptorStageSettlement(reader, { ...scope, stage: "scope-review" }, bundle, reviewKeys) : null;
+        if (intake)
+            assertDiagnosticSessionIndependence([physical(review ? review.binding.sessionId : settlement.coordinatorSessionId())], [physical(intake.binding.sessionId)]);
+        return { intake, review };
+    };
+    const owners = context.db.readSnapshot(() => readOwners(context));
+    const handoff = stage === "handoff" && !replay ? prepareReviewFixHandoff(context, input) : null;
+    const reportRoot = path.join(packet.runRoot, bundle.descriptor.stage(stage).directory), handoffFile = path.join(reportRoot, "raw-intake.json");
+    const retained = stage === "handoff" && replay ? readHandoff(context, scope, packet.attempt, handoffFile) : null;
+    if (stage === "handoff" && replay && !retained)
+        refuse("accepted_handoff_missing");
+    const raw = handoff ?? retained;
+    const rawPacket = handoff ? prepareStagePacket(handoffFile, handoff.bytes) : null;
+    const report = stage === "handoff" && raw ? prepareStageReport({ run_id: input.runId, stage, verdict: "completed", summary: result.summary,
+        review_fix: { disposition: reviewFixHandoffDisposition(result), formalization_authorized: false,
+            source: source.intake.source, source_intake: source.reference, unselected_ids: source.intake.unselected_ids,
+            scope: result.details, raw_intake: { root: "run", path: `${bundle.descriptor.stage(stage).directory}/raw-intake.json`, sha256: raw.sha256 } },
+        semantic: { next_action: "No repair or SDLC was started. Ready scope requires a separate explicit user formalization through vnext/start.md; deferred/declined/needs_scope remain honest outcomes." }
+    }) : null;
+    if (report && Buffer.byteLength(JSON.stringify(report.bytes)) > 7 * 1024 * 1024)
+        refuse("terminal_report_exceeds_bound");
+    if (!replay && hybridDigest(readDiagnosticSnapshot(context, selected.snapshotSelection, input.runId)) !== hybridDigest(snapshot))
+        refuse("snapshot_changed");
+    const fence = (writer) => {
+        selected.assertCustody(writer);
+        if (previous && hybridDigest(readAcceptedStageData(writer, { ...scope, stage: previousStage })) !== hybridDigest(previous))
+            refuse("predecessor_changed");
+        if (hybridDigest(readOwners(writer)) !== hybridDigest(owners))
+            refuse("review_owner_changed");
+        if (users && hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, "review-fix", bundle)) !== hybridDigest(users))
+            refuse("delivered_inputs_changed");
+        handoff?.assertCustody(writer);
+        if (rawPacket && !replay) {
+            const existing = readHandoff(writer, scope, packet.attempt, handoffFile);
+            if (existing && !existing.bytes.equals(rawPacket.bytes))
+                refuse("accepted_handoff_changed");
+            if (!existing)
+                acceptStagePacket(writer, { ...scope, prepared: rawPacket });
+        }
+        if (retained && hybridDigest(readHandoff(writer, scope, packet.attempt, handoffFile)) !== hybridDigest(retained))
+            refuse("accepted_handoff_changed");
+        if (report) {
+            const rows = writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_report' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='handoff' AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, scope.runId, packet.attempt]);
+            if (rows.length > 1 || rows.some(row => Buffer.byteLength(row.payload_json) > 8 * 1024 * 1024))
+                refuse("terminal_report_custody_invalid");
+            if (rows.length) {
+                const stored = JSON.parse(rows[0].payload_json);
+                if (stored.sha256 !== report.sha256 || hybridDigest(stored.bytes) !== hybridDigest(report.bytes)
+                    || resolveStagePublicationPath(writer, scope.projectId, scope.runId, stored.root) !== reportRoot)
+                    refuse("terminal_report_changed");
+            }
+            else {
+                if (replay)
+                    refuse("accepted_terminal_report_missing");
+                acceptStageReport(writer, { ...scope, root: reportRoot, prepared: report });
+            }
+        }
+    };
+    let acceptedStage = false;
+    try {
+        const accepted = settlement.apply(context, fence);
+        acceptedStage = true;
+        if (stage !== "handoff")
+            return accepted;
+        const complete = PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence);
+        publishStagePacket(context, scope.projectId, scope.runId, stage, handoffFile);
+        publishStageReport(context, scope.projectId, scope.runId, stage, reportRoot);
+        return { ...accepted, ...complete, disposition: reviewFixHandoffDisposition(result), formalization_authorized: false,
+            handoff: handoffFile, reports: ["json", "md", "html"].map(extension => path.join(reportRoot, `stage-report.${extension}`)) };
+    }
+    catch (error) {
+        if (stage !== "handoff")
+            throw error;
+        if (!acceptedStage) {
+            try {
+                acceptedStage = readAcceptedStageData(context, scope).bytes.equals(bytes);
+            }
+            catch { /* Not committed. */ }
+        }
+        if (!acceptedStage)
+            throw error;
+        throw new AppError("review_fix_handoff_pending", "Accepted handoff needs projection or RUN settlement reconciliation", 1, { effect: "committed", run_id: input.runId, next_action: "reconcile_accepted_handoff", cause: error instanceof AppError ? error.code : "handoff_settlement_failed" });
+    }
+}

package/dist/services/review-fix-stage-results.js

@@ -0,0 +1,86 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    throw new AppError("review_fix_stage_result_invalid", "Review-fix requires its selected findings and original delivered user scope", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+}
+/** Proposal validation, not semantic approval or physical reviewer independence.
+ * Registered handlers must assess actual agreement and independent ownership.
+ * There is intentionally no writable scope, specification or SDLC launch field. */
+export function validateReviewFixStageResult(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/review-fix-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/review-fix-stage-result@1" || result.flow_id !== "review-fix"
+        || !result.summary.trim())
+        refuse("invalid_schema");
+    if (result.run_id !== binding.runId || result.stage !== binding.stage || result.input_sha256 !== binding.inputSha256
+        || result.intake_sha256 !== binding.intakeSha256 || result.snapshot_sha256 !== binding.snapshotSha256
+        || result.user_inputs_sha256 !== binding.userInputsSha256
+        || hybridDigest(result.predecessors) !== hybridDigest(binding.predecessors))
+        refuse("foreign_stage_binding");
+    const ids = binding.findingIds;
+    const complete = (items, expected) => {
+        if (new Set(expected).size !== expected.length || items.length !== expected.length
+            || hybridDigest(items.map(item => item.finding_id)) !== hybridDigest(expected))
+            refuse("incomplete_finding_decisions");
+    };
+    if (!ids.length || ids.length > 4096)
+        refuse("selected_findings_required");
+    complete(result.details.decisions, ids);
+    complete(result.details.review, binding.stage === "intake" ? [] : ids);
+    for (const decision of result.details.decisions) {
+        if (!decision.reason.trim())
+            refuse("invalid_schema");
+        if (decision.disposition === "approved") {
+            if (!decision.approval_source || !binding.userSources.some(source => source.role !== "question"
+                && hybridDigest({ root: source.root, path: source.path, sha256: source.sha256 }) === hybridDigest(decision.approval_source)))
+                refuse("approval_not_delivered_by_user");
+        }
+        else if (decision.approval_source !== null)
+            refuse("nonapproved_scope_claim");
+    }
+    if (result.details.review.some(item => !item.reason.trim()))
+        refuse("invalid_schema");
+    return result;
+}
+export function assertReviewFixStageScope(result, prior) {
+    // A real answer delivered during scope-review may revise the intake proposal.
+    // The handler must bind the newly read full input set; handoff cannot revise
+    // an already reviewed decision or silently consume later user messages.
+    const revisedByUser = prior.stage === "intake" && result.stage === "scope-review"
+        && result.user_inputs_sha256 !== prior.user_inputs_sha256;
+    if (result.intake_sha256 !== prior.intake_sha256 || result.snapshot_sha256 !== prior.snapshot_sha256
+        || !revisedByUser && (result.user_inputs_sha256 !== prior.user_inputs_sha256
+            || hybridDigest(result.details.decisions) !== hybridDigest(prior.details.decisions))
+        || prior.details.limitations.some(value => !result.details.limitations.includes(value))
+        || prior.stage === "scope-review" && hybridDigest(result.details.review) !== hybridDigest(prior.details.review))
+        refuse("accepted_scope_changed");
+}
+/** Honest handoff disposition only; even ready still needs explicit formalization. */
+export function reviewFixHandoffDisposition(result) {
+    if (result.stage !== "handoff")
+        refuse("handoff_required");
+    if (result.details.review.some(item => item.verdict === "revise"))
+        return "needs_scope";
+    if (result.details.decisions.some(item => item.disposition === "approved"))
+        return "ready";
+    return result.details.decisions.some(item => item.disposition === "deferred") ? "deferred" : "declined";
+}

package/dist/services/run-control-receipt.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const records = (value) => Array.isArray(value) ? value.map(object) : [];
+const text = (value) => typeof value === "string" && value.length ? value : null;
+/** Pure projection of durable evidence. Never infer quiescence from an ACK,
+ * a terminal RUN label, or a settlement captured before a subsequent resume. */
+export function controlStatusReceipt(observation, request = {}) {
+    const control = object(observation.control), worker = object(observation.worker), resume = object(observation.resume_operation);
+    const present = Boolean(control.control_id), current = control.current === true;
+    const activeResume = Boolean(resume.operation_id);
+    const historical = !current || activeResume || ["resuming", "resumed"].includes(String(control.status));
+    const settlement = object(control.settlement);
+    const snapshot = historical ? {} : control.admission === "sealed" ? settlement : object(worker.snapshot);
+    const nodes = records(snapshot.nodes).map((node, index) => {
+        const identity = Object.fromEntries(["operation_id", "controller_id", "process_id", "check_id", "merge_request_id", "work_id", "work_session_id", "session_id", "harness", "state_dir", "resource_home"].filter(key => node[key] !== undefined).map(key => [key, node[key]]));
+        const settled = node.status === "completed";
+        const role = ["subject", "worker", "merge", "judge", "probe", "check", "process"].includes(String(node.role)) ? node.role : node.check_id ? "check" : node.merge_request_id ? "merge" : node.process_id ? "process" : "unknown";
+        return { id: `node:${crypto.createHash("sha256").update(JSON.stringify(Object.keys(identity).length ? identity : { index, reason: node.reason })).digest("hex")}`, role, status: settled ? "completed" : node.status === "outcome_unknown" ? "unknown" : "pending", acknowledged: settled || object(node.receipt).cancelled === true, settled, reason: settled ? null : text(node.reason) ?? "node_settlement_required", details: node };
+    });
+    const settled = present && current && !historical && control.status === "settled" && control.admission === "sealed" && Boolean(control.capture_path) && settlement.settled === true && Array.isArray(settlement.nodes) && nodes.every(node => node.settled);
+    let state;
+    if (!present)
+        state = request.action && ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "terminal_noop" : "not_requested";
+    else if (!current)
+        state = "superseded";
+    else if (resume.status === "failed" || worker.status === "failed")
+        state = "recovery_required";
+    else if (control.status === "resumed" && control.admission === "recovered" && resume.status === "completed")
+        state = "running";
+    else if (activeResume || control.status === "resuming")
+        state = "resuming";
+    else if (settled)
+        state = control.requested_mode === "pause" ? "paused" : "stopped";
+    else
+        state = control.requested_mode === "pause" ? "pause_requested" : "stop_requested";
+    const reasons = settled ? [] : [...new Set([
+            ...nodes.filter(node => !node.settled).map(node => node.reason),
+            ...(Array.isArray(snapshot.pending_reasons) ? snapshot.pending_reasons.filter((reason) => typeof reason === "string" && Boolean(reason)) : []),
+            ...(!present ? [state === "terminal_noop" ? "terminal_settlement_not_observed" : "control_not_requested"]
+                : !current ? ["control_superseded"]
+                    : state === "running" ? ["run_active"]
+                        : state === "resuming" ? ["recovery_acceptance_pending"]
+                            : state === "recovery_required" ? [text(object(resume.error).code) ?? text(object(worker.error).code) ?? "control_recovery_required"]
+                                : control.admission === "sealed" ? ["recovery_capture_required"] : ["settlement_observation_required"])
+        ])];
+    return {
+        ...observation, schema_id: "dd-flow/run-control-receipt@1", ok: true,
+        request_id: request.requestId ?? text(resume.request_id) ?? text(control.request_id), control_id: text(control.control_id),
+        generation: Number.isSafeInteger(control.generation) ? control.generation : 0,
+        requested_mode: request.action ?? (activeResume ? "resume" : text(control.requested_mode)),
+        applied_mode: settled ? control.requested_mode : state === "running" ? "resume" : null,
+        state, settled, nodes, unsettled_reasons: reasons,
+        resumability: ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "not_applicable" : settled || state === "recovery_required" ? "recovery_required" : ["running", "not_requested", "terminal_noop", "superseded"].includes(state) ? "not_applicable" : "pending",
+        recovery_id: text(control.recovery_id)
+    };
+}