@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/security/policy/approval.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @boombot/security — persisted HITL approval state machine.
+ *
+ * The single source of truth for the lifecycle of a human-in-the-loop
+ * approval request:
+ *
+ *     pending → approved | denied | expired
+ *
+ * `pending` is the only non-terminal state. A human answers with
+ * `resolveApproval(id, 'approved' | 'denied')`; the deadline passing moves
+ * the row to `expired` (via `sweepExpired`, called by the live approval
+ * timer and by the boot scan). Every transition out of `pending` is guarded
+ * by `WHERE status = 'pending'`, so a decision applies exactly once — a
+ * retried `turn.approve` or a racing timer can never double-resolve a
+ * request.
+ *
+ * Persistence: `node:sqlite` (built-in, zero dependencies — same as
+ * `SqliteSessionStore`), table `approval_requests` in the store's own
+ * database file. The gateway opens `<dataDir>/approvals.sqlite`, so the
+ * session store's schema (`sessions.sqlite`, incl. its legacy
+ * `turn_approvals` checkpoint table) is never migrated by this module and
+ * no other worker's migrations can collide with it.
+ *
+ * Restart semantics (P1-2): rows still `pending` at boot died with the
+ * previous process — their in-memory waiters are gone. `resumePendingOnBoot`
+ * first sweeps past-deadline rows to `expired`, then returns the survivors
+ * so the gateway can re-announce them (`turn.approval_required`) instead of
+ * failing them silently. The turn that requested them cannot resume (its
+ * loop state died with the old process); answering records the human's
+ * decision and the client is told the turn is gone.
+ *
+ * This module is new code written for BoomBot. It implements the
+ * approval-as-persisted-state-machine pattern (cf. the research notes);
+ * it does not copy any third-party implementation.
+ */
+/** Lifecycle states of one approval request. `pending` is the only live state. */
+export type ApprovalRequestStatus = 'pending' | 'approved' | 'denied' | 'expired';
+/** The two decisions a human (or the `turn.approve` command) can record. */
+export type ApprovalHumanDecision = 'approved' | 'denied';
+/** Everything needed to open a new approval request. */
+export interface ApprovalRequestInput {
+    /** Stable id for the request (the turn service uses the approval runId). */
+    readonly id: string;
+    /** Owning turn — used to correlate the re-announced SSE event after a restart. */
+    readonly turnId: string;
+    readonly sessionId: string;
+    /** Proposed tool, e.g. 'shell.exec'. */
+    readonly toolName: string;
+    /** JSON-serialized tool arguments, shown to the approver. */
+    readonly argsJson: string;
+    /** Why the policy asked instead of deciding itself. */
+    readonly reason: string;
+    /** Absolute deadline (ms since epoch). Past it the request is `expired`. */
+    readonly expiresAtMs: number;
+    /** Who asked (principal id). Optional; null when unknown. */
+    readonly requestedBy?: string;
+}
+/** A persisted approval request: input plus its lifecycle state. */
+export interface ApprovalRequestRecord extends ApprovalRequestInput {
+    readonly status: ApprovalRequestStatus;
+    readonly requestedAtMs: number;
+    readonly resolvedAtMs: number | null;
+    /** Who resolved it; 'system:expiry…' for timeouts, null when unknown. */
+    readonly resolvedBy: string | null;
+}
+export interface ApprovalStoreOptions {
+    /** Clock override (tests). Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Persisted HITL approval state machine over `node:sqlite`.
+ * One instance per gateway process, backed by `<dataDir>/approvals.sqlite`.
+ */
+export declare class ApprovalStore {
+    private readonly db;
+    private readonly now;
+    private constructor();
+    static open(path: string, options?: ApprovalStoreOptions): ApprovalStore;
+    static openMemory(options?: ApprovalStoreOptions): ApprovalStore;
+    close(): void;
+    /**
+     * Open a new request as `pending`. Throws on invalid input or a duplicate
+     * id (ids are runIds — a duplicate means the caller re-requested instead
+     * of answering).
+     */
+    requestApproval(input: ApprovalRequestInput): ApprovalRequestRecord;
+    /** Fetch one request by id, if it exists. */
+    getApproval(id: string): ApprovalRequestRecord | undefined;
+    /**
+     * Record a human decision. Idempotent: only a `pending` row transitions;
+     * returns the updated record, or `undefined` when there was nothing
+     * pending to resolve (unknown id, already decided, or expired).
+     */
+    resolveApproval(id: string, decision: ApprovalHumanDecision, resolvedBy?: string): ApprovalRequestRecord | undefined;
+    /**
+     * Mark one `pending` request `expired` (gateway shutdown: the waiter is
+     * about to be dropped, so the request can never be answered for its
+     * turn). Returns the updated record, or `undefined` when not pending.
+     */
+    expireApproval(id: string): ApprovalRequestRecord | undefined;
+    /** Every still-`pending` request, oldest first. */
+    listPendingApprovals(): ApprovalRequestRecord[];
+    /**
+     * Move every `pending` request past its deadline to `expired`.
+     * Idempotent; returns the swept requests (with their new state).
+     */
+    sweepExpired(nowMs?: number): ApprovalRequestRecord[];
+    /**
+     * Boot scan. Past-deadline `pending` rows become `expired`; the survivors
+     * are returned for re-announcement (`turn.approval_required`) so a
+     * reconnecting client sees them instead of a silent timeout.
+     */
+    resumePendingOnBoot(nowMs?: number): {
+        resumed: ApprovalRequestRecord[];
+        expired: ApprovalRequestRecord[];
+    };
+}

package/dist/node_modules/@boombot/security/policy/approval.js

@@ -0,0 +1,223 @@
+/**
+ * @boombot/security — persisted HITL approval state machine.
+ *
+ * The single source of truth for the lifecycle of a human-in-the-loop
+ * approval request:
+ *
+ *     pending → approved | denied | expired
+ *
+ * `pending` is the only non-terminal state. A human answers with
+ * `resolveApproval(id, 'approved' | 'denied')`; the deadline passing moves
+ * the row to `expired` (via `sweepExpired`, called by the live approval
+ * timer and by the boot scan). Every transition out of `pending` is guarded
+ * by `WHERE status = 'pending'`, so a decision applies exactly once — a
+ * retried `turn.approve` or a racing timer can never double-resolve a
+ * request.
+ *
+ * Persistence: `node:sqlite` (built-in, zero dependencies — same as
+ * `SqliteSessionStore`), table `approval_requests` in the store's own
+ * database file. The gateway opens `<dataDir>/approvals.sqlite`, so the
+ * session store's schema (`sessions.sqlite`, incl. its legacy
+ * `turn_approvals` checkpoint table) is never migrated by this module and
+ * no other worker's migrations can collide with it.
+ *
+ * Restart semantics (P1-2): rows still `pending` at boot died with the
+ * previous process — their in-memory waiters are gone. `resumePendingOnBoot`
+ * first sweeps past-deadline rows to `expired`, then returns the survivors
+ * so the gateway can re-announce them (`turn.approval_required`) instead of
+ * failing them silently. The turn that requested them cannot resume (its
+ * loop state died with the old process); answering records the human's
+ * decision and the client is told the turn is gone.
+ *
+ * This module is new code written for BoomBot. It implements the
+ * approval-as-persisted-state-machine pattern (cf. the research notes);
+ * it does not copy any third-party implementation.
+ */
+import { DatabaseSync } from 'node:sqlite';
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS approval_requests (
+  id TEXT PRIMARY KEY,
+  turn_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  tool_name TEXT NOT NULL,
+  args_json TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  requested_by TEXT,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'denied', 'expired')),
+  requested_at_ms INTEGER NOT NULL,
+  expires_at_ms INTEGER NOT NULL,
+  resolved_at_ms INTEGER,
+  resolved_by TEXT
+);
+CREATE INDEX IF NOT EXISTS approval_requests_pending_idx
+  ON approval_requests (status, expires_at_ms);
+`;
+const STATUSES = new Set(['pending', 'approved', 'denied', 'expired']);
+function recordFromRow(row) {
+    // The CHECK constraint guarantees the status, but a foreign tool could
+    // have written the file: degrade to `expired` (fail-closed — never
+    // re-announce or resolve a row we don't understand).
+    const status = STATUSES.has(row.status) ? row.status : 'expired';
+    return {
+        id: row.id,
+        turnId: row.turn_id,
+        sessionId: row.session_id,
+        toolName: row.tool_name,
+        argsJson: row.args_json,
+        reason: row.reason,
+        ...(row.requested_by == null ? {} : { requestedBy: row.requested_by }),
+        status,
+        requestedAtMs: row.requested_at_ms,
+        expiresAtMs: row.expires_at_ms,
+        resolvedAtMs: row.resolved_at_ms,
+        resolvedBy: row.resolved_by,
+    };
+}
+function assertValidInput(input) {
+    for (const [field, value] of [
+        ['id', input.id],
+        ['turnId', input.turnId],
+        ['sessionId', input.sessionId],
+        ['toolName', input.toolName],
+    ]) {
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(`ApprovalStore.requestApproval: '${field}' must be a non-empty string`);
+        }
+    }
+    if (typeof input.argsJson !== 'string') {
+        throw new Error(`ApprovalStore.requestApproval: 'argsJson' must be a string`);
+    }
+    if (typeof input.reason !== 'string') {
+        throw new Error(`ApprovalStore.requestApproval: 'reason' must be a string`);
+    }
+    if (!Number.isFinite(input.expiresAtMs)) {
+        throw new Error(`ApprovalStore.requestApproval: 'expiresAtMs' must be a finite number`);
+    }
+}
+/**
+ * Persisted HITL approval state machine over `node:sqlite`.
+ * One instance per gateway process, backed by `<dataDir>/approvals.sqlite`.
+ */
+export class ApprovalStore {
+    db;
+    now;
+    constructor(db, now) {
+        this.db = db;
+        this.now = now;
+    }
+    static open(path, options = {}) {
+        const db = new DatabaseSync(path);
+        db.exec('PRAGMA journal_mode = WAL;');
+        db.exec(SCHEMA_SQL);
+        return new ApprovalStore(db, options.now ?? Date.now);
+    }
+    static openMemory(options = {}) {
+        return ApprovalStore.open(':memory:', options);
+    }
+    close() {
+        this.db.close();
+    }
+    /**
+     * Open a new request as `pending`. Throws on invalid input or a duplicate
+     * id (ids are runIds — a duplicate means the caller re-requested instead
+     * of answering).
+     */
+    requestApproval(input) {
+        assertValidInput(input);
+        const requestedAtMs = this.now();
+        this.db
+            .prepare(`INSERT INTO approval_requests
+           (id, turn_id, session_id, tool_name, args_json, reason, requested_by,
+            status, requested_at_ms, expires_at_ms)
+         VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)`)
+            .run(input.id, input.turnId, input.sessionId, input.toolName, input.argsJson, input.reason, input.requestedBy ?? null, requestedAtMs, input.expiresAtMs);
+        const record = this.getApproval(input.id);
+        if (record === undefined) {
+            // Unreachable unless the database misbehaves; fail loud, not silent.
+            throw new Error(`ApprovalStore.requestApproval: lost row for id '${input.id}'`);
+        }
+        return record;
+    }
+    /** Fetch one request by id, if it exists. */
+    getApproval(id) {
+        const row = this.db
+            .prepare('SELECT * FROM approval_requests WHERE id = ?')
+            .get(id);
+        return row === undefined ? undefined : recordFromRow(row);
+    }
+    /**
+     * Record a human decision. Idempotent: only a `pending` row transitions;
+     * returns the updated record, or `undefined` when there was nothing
+     * pending to resolve (unknown id, already decided, or expired).
+     */
+    resolveApproval(id, decision, resolvedBy) {
+        if (decision !== 'approved' && decision !== 'denied') {
+            throw new Error(`ApprovalStore.resolveApproval: invalid decision '${String(decision)}'`);
+        }
+        const result = this.db
+            .prepare(`UPDATE approval_requests
+         SET status = ?, resolved_at_ms = ?, resolved_by = ?
+         WHERE id = ? AND status = 'pending'`)
+            .run(decision, this.now(), resolvedBy ?? null, id);
+        if (Number(result.changes) !== 1)
+            return undefined;
+        return this.getApproval(id);
+    }
+    /**
+     * Mark one `pending` request `expired` (gateway shutdown: the waiter is
+     * about to be dropped, so the request can never be answered for its
+     * turn). Returns the updated record, or `undefined` when not pending.
+     */
+    expireApproval(id) {
+        const result = this.db
+            .prepare(`UPDATE approval_requests
+         SET status = 'expired', resolved_at_ms = ?, resolved_by = 'system:expiry'
+         WHERE id = ? AND status = 'pending'`)
+            .run(this.now(), id);
+        if (Number(result.changes) !== 1)
+            return undefined;
+        return this.getApproval(id);
+    }
+    /** Every still-`pending` request, oldest first. */
+    listPendingApprovals() {
+        const rows = this.db
+            .prepare(`SELECT * FROM approval_requests
+         WHERE status = 'pending'
+         ORDER BY requested_at_ms ASC, rowid ASC`)
+            .all();
+        return rows.map(recordFromRow);
+    }
+    /**
+     * Move every `pending` request past its deadline to `expired`.
+     * Idempotent; returns the swept requests (with their new state).
+     */
+    sweepExpired(nowMs = this.now()) {
+        const stale = this.db
+            .prepare(`SELECT * FROM approval_requests
+         WHERE status = 'pending' AND expires_at_ms <= ?
+         ORDER BY requested_at_ms ASC, rowid ASC`)
+            .all(nowMs);
+        if (stale.length === 0)
+            return [];
+        this.db
+            .prepare(`UPDATE approval_requests
+         SET status = 'expired', resolved_at_ms = ?, resolved_by = 'system:expiry-sweep'
+         WHERE status = 'pending' AND expires_at_ms <= ?`)
+            .run(nowMs, nowMs);
+        return stale.map((row) => ({
+            ...recordFromRow(row),
+            status: 'expired',
+            resolvedAtMs: nowMs,
+            resolvedBy: 'system:expiry-sweep',
+        }));
+    }
+    /**
+     * Boot scan. Past-deadline `pending` rows become `expired`; the survivors
+     * are returned for re-announcement (`turn.approval_required`) so a
+     * reconnecting client sees them instead of a silent timeout.
+     */
+    resumePendingOnBoot(nowMs = this.now()) {
+        const expired = this.sweepExpired(nowMs);
+        return { resumed: this.listPendingApprovals(), expired };
+    }
+}

package/dist/node_modules/@boombot/security/reasoning-guard/claim-extractor.d.ts

@@ -0,0 +1,10 @@
+import type { Claim } from './types.js';
+/**
+ * Split text into sentences and classify each one.
+ *
+ * - `id` is `claim-1`, `claim-2`, … in document order.
+ * - `text` is the sentence with surrounding whitespace and trailing sentence
+ *   punctuation stripped.
+ * - `span` is the `[start, end)` offset of `text` in the original string.
+ */
+export declare function extractClaims(text: string): Claim[];

package/dist/node_modules/@boombot/security/reasoning-guard/claim-extractor.js

@@ -0,0 +1,124 @@
+/**
+ * Deterministic sentence splitter.
+ *
+ * Splits on sentence-terminating punctuation or newlines, but never on a `.`
+ * that directly follows a digit (protects decimals like "3.14", versions like
+ * "2.0"). Rule-based and fully deterministic: same input always yields the
+ * same claims, spans, and ids.
+ */
+// Boundary = newline run, or punctuation NOT preceded by a digit (lookbehind).
+const SENTENCE_BOUNDARY = /(\r?\n+|(?<!\d)[.!?…]+)/g;
+const TRAILING_PUNCT = /[.!?…]+$/u;
+/**
+ * `\b` is ASCII-only: it never matches after letters like à, ó, ẽ. These
+ * Unicode-aware boundaries treat every letter/digit as a word character,
+ * so patterns containing Vietnamese words (là, có, đô, giờ, …) work.
+ */
+const UWB_BEFORE = '(?<![\\p{L}\\p{N}_])';
+const UWB_AFTER = '(?![\\p{L}\\p{N}_])';
+const GREETING_RE = new RegExp(`^(chào|xin chào|hello|hi|hey|cảm ơn|thanks)${UWB_AFTER}`, 'iu');
+const QUESTION_START_RE = new RegExp(`^(ai|cái gì|tại sao|làm sao|bao giờ|bao nhiêu|what|why|how|when|which|who|where)${UWB_AFTER}`, 'iu');
+const OPINION_RE = /(tôi nghĩ|theo tôi|mình nghĩ|có lẽ|i think|in my opinion|maybe|probably)/iu;
+const INSTRUCTION_RE = /(hãy|đừng|vui lòng|please|bạn nên|you should)/iu;
+const QUOTE_RE = /[""][^""]+[""]|«[^»]+»/u;
+const NUMBER_UNIT_RE = new RegExp(`\\d+(?:\\.\\d+)?\\s*(?:%|percent|USD|VND|đồng|đô|ngày|giờ|phút|giây|tuần|tháng|năm|km|ms|GB|MB|°[cf]|rpm|tokens?|files?|dòng)${UWB_AFTER}`, 'iu');
+const DATE_RE = /\d{1,2}[/-]\d{1,2}[/-]\d{2,4}|\d{4}-\d{2}-\d{2}/;
+const TIME_RE = /\d{1,2}:\d{2}/;
+const CURRENCY_RE = /[$€£¥]/;
+const STATUS_RE = /(hoàn thành|đã xong|thành công|thất bại|đã deploy|đang chạy|đã dừng|đã lưu|đã tạo|đã xóa|completed|done|success|failed|deployed|running|created|deleted)\b/iu;
+const ASSERT_VERB_RE = new RegExp(`${UWB_BEFORE}(là|có|được|sẽ|is|are|was|were|has|have)${UWB_AFTER}`, 'iu');
+const UPPER_RE = /\p{Lu}/u;
+/** A capitalized token that is not the first token of the sentence. */
+function hasMidSentenceCapital(text) {
+    const tokens = text.split(/\s+/u).filter((t) => t.length > 0);
+    for (let i = 1; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token !== undefined && UPPER_RE.test(token)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Classify one sentence. Rules are evaluated in priority order and the first
+ * match wins, so classification is stable and explainable.
+ */
+function classify(body, terminator) {
+    // 1. Non-falsifiable: questions, greetings, opinions, instructions.
+    if (terminator.includes('?') || QUESTION_START_RE.test(body)) {
+        return 'non-falsifiable';
+    }
+    if (GREETING_RE.test(body)) {
+        return 'non-falsifiable';
+    }
+    if (OPINION_RE.test(body)) {
+        return 'non-falsifiable';
+    }
+    if (INSTRUCTION_RE.test(body)) {
+        return 'non-falsifiable';
+    }
+    // 2. Quoted speech.
+    if (QUOTE_RE.test(body)) {
+        return 'quote';
+    }
+    // 3. Numbers, dates, times, money.
+    if (NUMBER_UNIT_RE.test(body) ||
+        DATE_RE.test(body) ||
+        TIME_RE.test(body) ||
+        CURRENCY_RE.test(body)) {
+        return 'factual-number';
+    }
+    // 4. Status assertions.
+    if (STATUS_RE.test(body)) {
+        return 'factual-status';
+    }
+    // 5. Entity assertions: assertive verb + a capitalized token past position 0.
+    if (ASSERT_VERB_RE.test(body) && hasMidSentenceCapital(body)) {
+        return 'factual-entity';
+    }
+    // 6. Everything else is not checkable.
+    return 'non-falsifiable';
+}
+function terminatorOf(boundary) {
+    return boundary.includes('?') ? '?' : boundary;
+}
+/**
+ * Split text into sentences and classify each one.
+ *
+ * - `id` is `claim-1`, `claim-2`, … in document order.
+ * - `text` is the sentence with surrounding whitespace and trailing sentence
+ *   punctuation stripped.
+ * - `span` is the `[start, end)` offset of `text` in the original string.
+ */
+export function extractClaims(text) {
+    const claims = [];
+    let counter = 0;
+    const push = (start, end, terminator) => {
+        const raw = text.slice(start, end);
+        const trimmed = raw.trim();
+        if (trimmed.length === 0) {
+            return;
+        }
+        const body = trimmed.replace(TRAILING_PUNCT, '');
+        if (body.length === 0) {
+            return;
+        }
+        const spanStart = start + (raw.length - raw.trimStart().length);
+        counter += 1;
+        claims.push({
+            id: `claim-${counter}`,
+            text: body,
+            kind: classify(body, terminator),
+            span: { start: spanStart, end: spanStart + body.length },
+        });
+    };
+    SENTENCE_BOUNDARY.lastIndex = 0;
+    let segStart = 0;
+    let m;
+    while ((m = SENTENCE_BOUNDARY.exec(text)) !== null) {
+        push(segStart, m.index, terminatorOf(m[0]));
+        segStart = m.index + m[0].length;
+    }
+    push(segStart, text.length, '');
+    return claims;
+}

package/dist/node_modules/@boombot/security/reasoning-guard/evidence-ledger.d.ts

@@ -0,0 +1,25 @@
+import type { Evidence } from './types.js';
+/** Input accepted by {@link EvidenceLedger.record}. */
+export interface RecordInput {
+    readonly tool: string;
+    readonly args: unknown;
+    readonly output: string;
+    readonly error?: boolean;
+}
+/**
+ * Append-only ledger of tool outputs.
+ *
+ * Every tool execution records an {@link Evidence}: the tool name, a stable
+ * hash of its arguments, a bounded excerpt of its output, and a timestamp.
+ * The grounding check can only cite evidence that was recorded here, which is
+ * what makes "no evidence → ungrounded" enforceable.
+ */
+export declare class EvidenceLedger {
+    private readonly maxExcerptChars;
+    private readonly entries;
+    private counter;
+    constructor(maxExcerptChars?: number);
+    record(input: RecordInput): Evidence;
+    all(): readonly Evidence[];
+    clear(): void;
+}

package/dist/node_modules/@boombot/security/reasoning-guard/evidence-ledger.js

@@ -0,0 +1,70 @@
+/**
+ * Deterministic, key-sorted JSON serialization used for `argsHash`.
+ * Key order never affects the hash: `{a:1,b:2}` and `{b:2,a:1}` hash alike.
+ */
+function stableStringify(value) {
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        const keys = Object.keys(record).sort();
+        const parts = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+        return `{${parts.join(',')}}`;
+    }
+    return String(value);
+}
+/** FNV-1a 32-bit, hex-encoded. Pure JS so the ledger stays portable. */
+function fnv1a32Hex(input) {
+    let hash = 0x81_1c_9d_c5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01_00_01_93);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * Append-only ledger of tool outputs.
+ *
+ * Every tool execution records an {@link Evidence}: the tool name, a stable
+ * hash of its arguments, a bounded excerpt of its output, and a timestamp.
+ * The grounding check can only cite evidence that was recorded here, which is
+ * what makes "no evidence → ungrounded" enforceable.
+ */
+export class EvidenceLedger {
+    maxExcerptChars;
+    entries = [];
+    counter = 0;
+    constructor(maxExcerptChars = 500) {
+        this.maxExcerptChars = maxExcerptChars;
+    }
+    record(input) {
+        this.counter += 1;
+        const evidence = {
+            id: `e${this.counter}`,
+            tool: input.tool,
+            argsHash: fnv1a32Hex(stableStringify(input.args)),
+            excerpt: input.output.slice(0, this.maxExcerptChars),
+            ts: Date.now(),
+        };
+        this.entries.push(evidence);
+        return evidence;
+    }
+    all() {
+        return this.entries;
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+}

package/dist/node_modules/@boombot/security/reasoning-guard/gate.d.ts

@@ -0,0 +1,38 @@
+import type { EvidenceLedger } from './evidence-ledger.js';
+import type { Claim, GuardConfig, VerificationReport } from './types.js';
+/** Result of verifying one agent turn. */
+export interface TurnResult {
+    readonly text: string;
+    readonly report: VerificationReport;
+}
+/**
+ * Result of verifying one agent turn with the extracted claims attached.
+ *
+ * Callers that annotate the report (e.g. the gateway streaming
+ * `turn.verification` with the claim text per verdict) need the claims
+ * alongside the report; re-extracting them outside the gate would
+ * duplicate the draft-truncation logic.
+ */
+export interface TurnVerification {
+    readonly text: string;
+    readonly claims: readonly Claim[];
+    readonly report: VerificationReport;
+}
+/**
+ * Verify a draft response against the tool-output evidence ledger,
+ * returning the claims as well as the verified text and the report.
+ *
+ * Pipeline: bound the draft (`maxClaimChars`) → extract claims →
+ * check grounding → apply the mode policy → build the report.
+ *
+ * `mode: 'off'` short-circuits: the draft passes through untouched with an
+ * empty report and no claims.
+ */
+export declare function verifyTurnWithClaims(draft: string, ledger: EvidenceLedger, config: GuardConfig): TurnVerification;
+/**
+ * Verify a draft response against the tool-output evidence ledger.
+ *
+ * Same pipeline as {@link verifyTurnWithClaims}; this convenience form
+ * drops the claims when the caller only needs the text and the report.
+ */
+export declare function verifyTurn(draft: string, ledger: EvidenceLedger, config: GuardConfig): TurnResult;

package/dist/node_modules/@boombot/security/reasoning-guard/gate.js

@@ -0,0 +1,61 @@
+import { extractClaims } from './claim-extractor.js';
+import { checkGrounding } from './grounding-check.js';
+import { applyPolicy } from './policy.js';
+import { DEFAULT_GUARD_CONFIG } from './types.js';
+/**
+ * Verify a draft response against the tool-output evidence ledger,
+ * returning the claims as well as the verified text and the report.
+ *
+ * Pipeline: bound the draft (`maxClaimChars`) → extract claims →
+ * check grounding → apply the mode policy → build the report.
+ *
+ * `mode: 'off'` short-circuits: the draft passes through untouched with an
+ * empty report and no claims.
+ */
+export function verifyTurnWithClaims(draft, ledger, config) {
+    const resolved = { ...DEFAULT_GUARD_CONFIG, ...config };
+    if (resolved.mode === 'off') {
+        return {
+            text: draft,
+            claims: [],
+            report: {
+                verdicts: [],
+                ungroundedCount: 0,
+                mode: 'off',
+                msElapsed: 0,
+                truncated: false,
+            },
+        };
+    }
+    const startedAt = Date.now();
+    const truncated = draft.length > resolved.maxClaimChars;
+    const bounded = truncated ? draft.slice(0, resolved.maxClaimChars) : draft;
+    const claims = extractClaims(bounded);
+    const verdicts = checkGrounding(claims, ledger.all(), {
+        minEntityOverlap: resolved.minEntityOverlap,
+    });
+    const applied = applyPolicy(bounded, claims, verdicts, resolved.mode);
+    const text = truncated ? applied + draft.slice(resolved.maxClaimChars) : applied;
+    const ungroundedCount = verdicts.filter((verdict) => verdict.verdict === 'ungrounded').length;
+    return {
+        text,
+        claims,
+        report: {
+            verdicts,
+            ungroundedCount,
+            mode: resolved.mode,
+            msElapsed: Date.now() - startedAt,
+            truncated,
+        },
+    };
+}
+/**
+ * Verify a draft response against the tool-output evidence ledger.
+ *
+ * Same pipeline as {@link verifyTurnWithClaims}; this convenience form
+ * drops the claims when the caller only needs the text and the report.
+ */
+export function verifyTurn(draft, ledger, config) {
+    const { text, report } = verifyTurnWithClaims(draft, ledger, config);
+    return { text, report };
+}

package/dist/node_modules/@boombot/security/reasoning-guard/grounding-check.d.ts

@@ -0,0 +1,12 @@
+import type { Claim, ClaimVerdict, Evidence } from './types.js';
+/** Options for {@link checkGrounding}. */
+export interface GroundingOptions {
+    readonly minEntityOverlap: number;
+}
+/**
+ * Verify every claim against the evidence ledger.
+ *
+ * Conservative by design: when in doubt the claim is `ungrounded`, never
+ * silently passed. `non-falsifiable` claims always pass without evidence.
+ */
+export declare function checkGrounding(claims: readonly Claim[], evidences: readonly Evidence[], opts: GroundingOptions): ClaimVerdict[];