dsh-doublecheck 0.5.0

package/lib/domain/evidence.js

@@ -0,0 +1,180 @@
+/**
+ * Test-run evidence classification for the red/green gates.
+ *
+ * The durable session log is the only source of truth: a shell tool call
+ * (`bash` / `pwsh`, including Code Mode sub-dispatches) whose command matches
+ * the configured test patterns is a test run, and its rendered result text
+ * carries the exit facts (`[exit code: N]`, timeout, signal, sandbox-denial
+ * markers). A failing run is red evidence; a passing run is green evidence.
+ *
+ * @module dsh-doublecheck/domain/evidence
+ */
+/** Shared defaults: shell tools that can run tests. */
+export const DEFAULT_TEST_TOOL_NAMES = ['bash', 'pwsh'];
+/** Shared defaults: commands that count as test runs. */
+export const DEFAULT_TEST_COMMAND_PATTERNS = [
+    '(?:^|[;&|]\\s*)(?:(?:pnpm|npm|npx|yarn|bun)(?:\\s+run)?\\s+(?:test|vitest|jest|mocha)(?:\\s|$))',
+    '(?:^|[;&|]\\s*)(?:(?:pytest|go\\s+test|cargo\\s+test|make\\s+test|ctest)(?:\\s|$))',
+    '(?:^|[;&|]\\s*)(?:node\\s+--test(?:\\s|$))',
+];
+/** Shared defaults: mutation tools and test-file path patterns. */
+export const DEFAULT_MUTATION_TOOLS = ['edit', 'write'];
+/** Shared defaults: paths that identify test files. */
+export const DEFAULT_TEST_FILE_PATTERNS = [
+    '(^|[\\\\/])(tests?|__tests__|specs?)([\\\\/]|$)',
+    '\\.(test|spec)\\.[A-Za-z0-9]+$',
+];
+/** Background bash/pwsh acknowledgements are not test outcomes. */
+const BACKGROUND_ACK = /^started background job \S+/;
+/** The command never ran: a sandbox denial is not a failing test. */
+const SANDBOX_DENIAL = /\[sandbox: [^\]]*denied under [^\]]* mode\]/;
+const TIMED_OUT = /\[timed out after \d+ms\]/;
+const KILLED_BY_SIGNAL = /\[killed by signal: [^\]]+\]/;
+const EXIT_CODE = /\[exit code: (\d+)\]/m;
+/**
+ * Compile the detection knobs, rejecting invalid regexes at load time.
+ * @param config - the raw string knobs from the guard config.
+ * @returns the compiled detection record.
+ */
+export function compileDetection(config) {
+    assertNonEmptyNames('testToolNames', config.testToolNames);
+    assertNonEmptyNames('guardTools', config.guardTools);
+    return {
+        testToolNames: [...config.testToolNames],
+        testCommandPatterns: config.testCommandPatterns.map(compilePattern),
+        mutationTools: [...config.guardTools],
+        testFilePatterns: config.testFilePatterns.map(compilePattern),
+    };
+}
+/** The detection record with every list empty: test-run evidence is ignored. */
+export function emptyDetection() {
+    return {
+        testToolNames: [],
+        testCommandPatterns: [],
+        mutationTools: [],
+        testFilePatterns: [],
+    };
+}
+/**
+ * Parse a raw tool-call `arguments` value (a JSON string from the model, or an
+ * already-normalized object from a Code Mode sub-dispatch) into a plain record.
+ * @param raw - the raw arguments value from the durable event.
+ * @returns the parsed record, or `undefined` when the string is not valid JSON.
+ */
+export function parseRawArguments(raw) {
+    if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
+        return raw;
+    }
+    if (typeof raw !== 'string')
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        // Malformed model JSON carries no usable command or path; it is not evidence.
+        return undefined;
+    }
+}
+/**
+ * The shell command a tool call would execute, when the tool is a configured
+ * test runner.
+ * @param name - the called tool name.
+ * @param args - the parsed arguments record.
+ * @param detection - the compiled detection knobs.
+ * @returns the command text, or `undefined` when this call is not a shell run.
+ */
+export function shellCommand(name, args, detection) {
+    if (!detection.testToolNames.includes(name))
+        return undefined;
+    const command = args?.['command'];
+    return typeof command === 'string' && command.length > 0 ? command : undefined;
+}
+/**
+ * Whether a shell command is a test run under the configured patterns.
+ * @param command - the command text.
+ * @param detection - the compiled detection knobs.
+ * @returns true when at least one pattern matches.
+ */
+export function isTestCommand(command, detection) {
+    return detection.testCommandPatterns.some(pattern => pattern.test(command));
+}
+/**
+ * The mutation target path of a tool call, when the tool is a configured
+ * mutation tool and its arguments name a file.
+ * @param name - the called tool name.
+ * @param args - the parsed arguments record.
+ * @param detection - the compiled detection knobs.
+ * @returns the target path, or `undefined` when the call does not name one.
+ */
+export function mutationTargetPath(name, args, detection) {
+    if (!detection.mutationTools.includes(name))
+        return undefined;
+    const path = args?.['file_path'];
+    return typeof path === 'string' && path.length > 0 ? path : undefined;
+}
+/**
+ * Whether a mutation target is itself a test file (writing the failing test
+ * is the red step, so test files stay editable).
+ * @param path - the mutation target path.
+ * @param detection - the compiled detection knobs.
+ * @returns true when the path matches a test-file pattern.
+ */
+export function isTestFilePath(path, detection) {
+    return detection.testFilePatterns.some(pattern => pattern.test(path));
+}
+/**
+ * Classify the durable result of one test run from its model-facing text.
+ * @param text - the joined text blocks of the rendered result.
+ * @param isError - whether the tool call failed at the infrastructure level.
+ * @returns red/green evidence, or `undefined` when the run proves nothing.
+ */
+export function testOutcome(text, isError) {
+    if (isError)
+        return undefined;
+    if (BACKGROUND_ACK.test(text))
+        return undefined;
+    if (SANDBOX_DENIAL.test(text))
+        return undefined;
+    if (TIMED_OUT.test(text) || KILLED_BY_SIGNAL.test(text))
+        return 'fail';
+    const exit = EXIT_CODE.exec(text);
+    if (exit !== null)
+        return exit[1] === '0' ? 'pass' : 'fail';
+    // A finished shell run with no failure markers settled with exit code 0.
+    return 'pass';
+}
+/** Join the text blocks of a rendered result into one searchable string. */
+export function joinTextBlocks(content) {
+    const parts = [];
+    for (const block of content) {
+        if (block.type === 'text' && typeof block.text === 'string') {
+            parts.push(block.text);
+        }
+        else if (block.type === 'tool-result' && Array.isArray(block.content)) {
+            // A durable ToolResultMessage wraps its text blocks in one tool-result block.
+            parts.push(joinTextBlocks(block.content));
+        }
+    }
+    return parts.join('\n');
+}
+function compilePattern(source) {
+    try {
+        return new RegExp(source);
+    }
+    catch {
+        throw new Error(`dsh-doublecheck: invalid regex pattern "${source}" in the red/green gate configuration`);
+    }
+}
+function assertNonEmptyNames(field, names) {
+    if (names.length === 0)
+        throw new Error(`dsh-doublecheck: ${field} must not be empty`);
+    for (const name of names) {
+        if (name.length === 0)
+            throw new Error(`dsh-doublecheck: ${field} must not contain empty tool names`);
+    }
+    if (new Set(names).size !== names.length)
+        throw new Error(`dsh-doublecheck: ${field} must not contain duplicates`);
+}

package/lib/domain/projection.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The `doublecheck` session projection: the discipline facts a client renders
+ * (Web UI status row), folded from the durable session log alone.
+ *
+ * The state is plain JSON (the persisted-cache precondition of the projection
+ * registry) and mirrors the guard's own fold: a successful `doublecheck_spec`
+ * pair commits the spec goal, test runs move the color, implementation edits
+ * bump the edit count, and a `doublecheck-review` source record marks the
+ * delivery reviewed. Resumed and forked sessions fold to the same view.
+ *
+ * @module dsh-doublecheck/domain/projection
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type TestRunDetection } from './evidence.ts';
+import { type DisciplineStage, type TestColor } from './stages.ts';
+import type { DoublecheckView } from '../types.ts';
+/** The projection unit's plain-JSON fold state. */
+export interface DoublecheckProjectionState {
+    /** The last discipline stage a successful call or test run reached. */
+    stage: DisciplineStage;
+    /** The latest test-run evidence: red = failing since the last pass. */
+    color: TestColor;
+    /** Whether a successful `doublecheck_spec` call exists in the log. */
+    hasSpec: boolean;
+    /** The goal of the latest committed spec, or '' before any spec. */
+    specGoal: string;
+    /** Whether an adversary review record exists in the log. */
+    reviewed: boolean;
+    /** Total implementation edits folded so far. */
+    editCount: number;
+    /** Spec-tool call ids (with their goals) whose results have not been folded yet. */
+    pendingSpecCalls: Record<string, string>;
+    /** Test-run call ids (with their commands) whose results have not been folded yet. */
+    pendingTestCalls: Record<string, string>;
+}
+/** State for the empty log. */
+export declare function emptyDoublecheckState(): DoublecheckProjectionState;
+/**
+ * One-event transition of the `doublecheck` projection unit. Uninterested
+ * events return the same state reference (the registry's change gate).
+ * @param state - the folded state before `event`.
+ * @param event - one committed session event.
+ * @param detection - the compiled red/green evidence knobs.
+ * @returns the next state; the same reference when the event is not a
+ *   discipline fact.
+ */
+export declare function applyDoublecheckEvent(state: DoublecheckProjectionState, event: SessionEvent, detection: TestRunDetection): DoublecheckProjectionState;
+/**
+ * Fold a session log from scratch to the projection state.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled red/green evidence knobs.
+ * @returns the complete folded state.
+ */
+export declare function foldDoublecheckState(events: readonly SessionEvent[], detection: TestRunDetection): DoublecheckProjectionState;
+/**
+ * Project the folded state to the wire payload.
+ * @param state - the folded state.
+ * @returns the whole current value for the `doublecheck` projection key.
+ */
+export declare function viewDoublecheck(state: DoublecheckProjectionState): DoublecheckView;

package/lib/domain/projection.js

@@ -0,0 +1,132 @@
+/**
+ * The `doublecheck` session projection: the discipline facts a client renders
+ * (Web UI status row), folded from the durable session log alone.
+ *
+ * The state is plain JSON (the persisted-cache precondition of the projection
+ * registry) and mirrors the guard's own fold: a successful `doublecheck_spec`
+ * pair commits the spec goal, test runs move the color, implementation edits
+ * bump the edit count, and a `doublecheck-review` source record marks the
+ * delivery reviewed. Resumed and forked sessions fold to the same view.
+ *
+ * @module dsh-doublecheck/domain/projection
+ */
+import { isTestCommand, isTestFilePath, joinTextBlocks, mutationTargetPath, parseRawArguments, shellCommand, testOutcome, } from "./evidence.js";
+import { SPEC_TOOL_NAME } from "./stages.js";
+/** State for the empty log. */
+export function emptyDoublecheckState() {
+    return {
+        stage: 'grill',
+        color: 'none',
+        hasSpec: false,
+        specGoal: '',
+        reviewed: false,
+        editCount: 0,
+        pendingSpecCalls: {},
+        pendingTestCalls: {},
+    };
+}
+/**
+ * One-event transition of the `doublecheck` projection unit. Uninterested
+ * events return the same state reference (the registry's change gate).
+ * @param state - the folded state before `event`.
+ * @param event - one committed session event.
+ * @param detection - the compiled red/green evidence knobs.
+ * @returns the next state; the same reference when the event is not a
+ *   discipline fact.
+ */
+export function applyDoublecheckEvent(state, event, detection) {
+    switch (event.type) {
+        case 'tool/call': {
+            const args = parseRawArguments(event.data.arguments);
+            if (event.data.name === SPEC_TOOL_NAME) {
+                const goal = typeof args?.['goal'] === 'string' ? args['goal'] : '';
+                return { ...state, pendingSpecCalls: { ...state.pendingSpecCalls, [event.data.callId]: goal } };
+            }
+            const command = shellCommand(event.data.name, args, detection);
+            if (command !== undefined && isTestCommand(command, detection)) {
+                return { ...state, pendingTestCalls: { ...state.pendingTestCalls, [event.data.callId]: command } };
+            }
+            const path = mutationTargetPath(event.data.name, args, detection);
+            if (path !== undefined && !isTestFilePath(path, detection)) {
+                return { ...state, editCount: state.editCount + 1 };
+            }
+            return state;
+        }
+        case 'tool/result': {
+            const callId = event.data.message.source.callId;
+            if (event.data.error === undefined && callId in state.pendingSpecCalls) {
+                const pendingSpecCalls = { ...state.pendingSpecCalls };
+                const goal = pendingSpecCalls[callId] ?? '';
+                delete pendingSpecCalls[callId];
+                return {
+                    ...state,
+                    pendingSpecCalls,
+                    hasSpec: true,
+                    specGoal: goal,
+                    stage: 'design',
+                };
+            }
+            if (callId in state.pendingTestCalls) {
+                const pendingTestCalls = { ...state.pendingTestCalls };
+                delete pendingTestCalls[callId];
+                const outcome = testOutcome(joinTextBlocks(event.data.message.content), event.data.error !== undefined);
+                const next = { ...state, pendingTestCalls };
+                if (outcome === 'fail')
+                    return { ...next, color: 'red', stage: 'red' };
+                if (outcome === 'pass')
+                    return { ...next, color: 'green', stage: 'green' };
+                return next;
+            }
+            return state;
+        }
+        case 'tool/code-dispatch': {
+            const args = parseRawArguments(event.data.arguments);
+            const command = shellCommand(event.data.name, args, detection);
+            if (command !== undefined && isTestCommand(command, detection)) {
+                const outcome = testOutcome(joinTextBlocks(event.data.content), event.data.isError);
+                if (outcome === 'fail')
+                    return { ...state, color: 'red', stage: 'red' };
+                if (outcome === 'pass')
+                    return { ...state, color: 'green', stage: 'green' };
+            }
+            return state;
+        }
+        case 'user/message': {
+            const source = event.data.source;
+            if (source.kind === 'doublecheck-review' && !state.reviewed) {
+                return { ...state, reviewed: true };
+            }
+            return state;
+        }
+        default:
+            return state;
+    }
+}
+/**
+ * Fold a session log from scratch to the projection state.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled red/green evidence knobs.
+ * @returns the complete folded state.
+ */
+export function foldDoublecheckState(events, detection) {
+    let state = emptyDoublecheckState();
+    for (const event of events) {
+        state = applyDoublecheckEvent(state, event, detection);
+    }
+    return state;
+}
+/**
+ * Project the folded state to the wire payload.
+ * @param state - the folded state.
+ * @returns the whole current value for the `doublecheck` projection key.
+ */
+export function viewDoublecheck(state) {
+    return {
+        stage: state.stage,
+        color: state.color,
+        hasSpec: state.hasSpec,
+        specGoal: state.specGoal,
+        reviewed: state.reviewed,
+        editCount: state.editCount,
+    };
+}

package/lib/domain/report.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The doublecheck report fold: consolidate the durable discipline evidence of
+ * one session into report facts, derive the delivery verdict, and render the
+ * model-facing report document.
+ *
+ * Everything here folds the session log alone — the spec (from the
+ * `doublecheck_spec` call arguments), the test-run timeline (red/green
+ * outcomes), the implementation edits, and the injected
+ * `doublecheck-review` source records — so a report re-derived after resume
+ * or fork reads identically.
+ *
+ * @module dsh-doublecheck/domain/report
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools';
+import type { WorkflowMeta } from '@deepseek-ai/dsh-workflow';
+import { type TestRunDetection } from './evidence.ts';
+import { type GrilledSpec, type ReportVerdict, type ReviewFinding, type ReviewVerdict, type VerifyCheck } from './vocabulary.ts';
+/** One timeline row of the report fold, in log order. */
+export interface ReportTimelineEntry {
+    /** The evidence kind this row records. */
+    kind: 'spec' | 'red' | 'green' | 'review';
+    /** Short human-readable detail (command, spec goal preview, or verdict). */
+    detail: string;
+}
+/** The folded discipline facts of one session. */
+export interface ReportFacts {
+    /** The latest committed spec, or null before any spec exists. */
+    spec: GrilledSpec | null;
+    /** Counts of failing and passing test runs on record. */
+    testRuns: {
+        failed: number;
+        passed: number;
+    };
+    /** Spec/test/review evidence in log order. */
+    timeline: ReportTimelineEntry[];
+    /** Implementation edits (non-test-file mutations) on record. */
+    edits: number;
+    /** The latest injected adversary review, or null when none ran. */
+    review: {
+        verdict: ReviewVerdict;
+        findings: ReviewFinding[];
+    } | null;
+}
+/** The full canonical report value the tool returns. */
+export interface ReportData extends ReportFacts {
+    /** The derived delivery status. */
+    verdict: ReportVerdict;
+    /**
+     * Verification checks, when the verify workflow ran. `complete` is true
+     * only when every spec dimension returned a verdict, so `proven` never
+     * rests on silently missing dimensions.
+     */
+    verification: {
+        checks: VerifyCheck[];
+        complete: boolean;
+    } | null;
+    /** Workspace markdown copy outcome. */
+    path: string | null;
+    written: boolean;
+}
+/** Empty facts: nothing evidenced yet. */
+export declare function emptyReportFacts(): ReportFacts;
+/**
+ * Fold a session log into report facts.
+ * @param events - the session's append-only event log.
+ * @param detection - the compiled test-run/mutation detection knobs.
+ * @returns the complete folded facts.
+ */
+export declare function foldReportFacts(events: readonly SessionEvent[], detection: TestRunDetection): ReportFacts;
+/**
+ * Derive the delivery verdict from the folded facts, the optional review,
+ * and the optional verification outcome.
+ * @param facts - the folded session facts.
+ * @param verification - verification outcome when the verify workflow ran, else null.
+ * @returns the report verdict.
+ */
+export declare function deriveReportVerdict(facts: ReportFacts, verification: ReportData['verification']): ReportVerdict;
+/** Render the report facts as the model-facing markdown document. */
+export declare function renderReportMarkdown(data: ReportData): string;
+/** The structured output each verification child must satisfy. */
+export declare const VERIFY_CHECK_SCHEMA: ObjectJsonSchema;
+/** How the verify workflow fans its checkers out. */
+export type VerifyMode = 'all' | 'single';
+/** The verify workflow identity block. */
+export declare const VERIFY_META: WorkflowMeta;
+/**
+ * Build the verify workflow script body.
+ * @param mode - `all` fans out one parallel checker per spec dimension;
+ * `single` runs one checker over every dimension (cheaper, one subagent).
+ * @returns the plain-JS script body for `WorkflowStartRequest.script`.
+ */
+export declare function buildVerifyScript(mode: VerifyMode): string;