@petepetrash/circuit 0.1.0

package/dist/app/history/memory-preview.js

@@ -0,0 +1,103 @@
+import { HISTORY_AUTHORITY_NOTICE, HistoryMemoryInputPreviewV1, MemoryInputV0, } from '../../schemas/index.js';
+import { sha256Hex } from '../../shared/connector-relay.js';
+function fileStem(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
+    const trimmed = normalized.replace(/^[^a-z0-9]+/, '').slice(0, 96);
+    return trimmed.length === 0 ? 'memory' : trimmed;
+}
+function appliesTo(hit) {
+    const facets = new Set(hit.doc.facets);
+    if (facets.has('failure'))
+        return 'prior_failure';
+    if (facets.has('verification'))
+        return 'verification';
+    if (facets.has('operator-note'))
+        return 'operator_note';
+    return 'context';
+}
+function hintText(hit) {
+    const caution = hit.doc.facets.includes('checkpoint') || hit.doc.facets.includes('verification')
+        ? ' This is prior-run context only; rerun current checks before relying on it.'
+        : '';
+    const snippet = hit.snippet.trim();
+    const summary = hit.doc.summary.trim();
+    // On a prior-failure hit, lead with the failure summary (what went wrong and
+    // how it was resolved) rather than the lexical snippet that matched the
+    // query. The snippet is whatever fragment scored the match — often
+    // low-signal — so it buries the reason recall exists to surface.
+    const base = appliesTo(hit) === 'prior_failure'
+        ? summary.length > 0
+            ? summary
+            : snippet
+        : snippet.length > 0
+            ? snippet
+            : summary;
+    return `${base}\nSource: ${hit.doc.run_id} ${hit.doc.source_path}.${caution}`.trim();
+}
+export function historyMemoryInputPreview(input) {
+    const memoryInputs = [];
+    const matches = [];
+    for (const hit of input.hits) {
+        if (!hit.doc.memory_safe)
+            continue;
+        const hash = sha256Hex(hit.doc.doc_id).slice(0, 12);
+        const runPrefix = fileStem(hit.doc.run_id).slice(0, 32);
+        const memoryId = `prior-run-${runPrefix}-${hash}`.slice(0, 128);
+        const source = hit.doc.source_ref.sha256 !== undefined &&
+            hit.doc.source_sha256 !== undefined &&
+            hit.doc.source_ref.sha256 === hit.doc.source_sha256
+            ? {
+                ref: hit.doc.source_ref,
+                captured_at: hit.doc.recorded_at ?? input.capturedAt ?? new Date().toISOString(),
+                ...(hit.doc.source_mtime_ms === undefined
+                    ? {}
+                    : { source_updated_at: new Date(hit.doc.source_mtime_ms).toISOString() }),
+                sha256: hit.doc.source_sha256,
+            }
+            : {
+                ref: hit.doc.source_ref,
+                captured_at: hit.doc.recorded_at ?? input.capturedAt ?? new Date().toISOString(),
+                ...(hit.doc.source_mtime_ms === undefined
+                    ? {}
+                    : { source_updated_at: new Date(hit.doc.source_mtime_ms).toISOString() }),
+            };
+        const memory = MemoryInputV0.parse({
+            schema_version: 1,
+            memory_id: memoryId,
+            kind: 'prior_run',
+            source,
+            summary: hit.doc.summary,
+            hints: [
+                {
+                    id: `hint-${hash}`,
+                    text: hintText(hit),
+                    applies_to: appliesTo(hit),
+                },
+            ],
+            staleness: hit.staleness,
+            authority: 'hint_only',
+        });
+        memoryInputs.push(memory);
+        matches.push({
+            memory_id: memoryId,
+            rank: hit.rank,
+            score: hit.score,
+            source_doc_id: hit.doc.doc_id,
+            source_ref: hit.doc.source_ref,
+            snippet: hit.snippet,
+        });
+    }
+    return HistoryMemoryInputPreviewV1.parse({
+        api_version: 'history-memory-input-preview-v1',
+        schema_version: 1,
+        query: input.query,
+        format: 'memory-input',
+        index_state: input.indexState,
+        rebuilt: input.rebuilt,
+        authority_notice: HISTORY_AUTHORITY_NOTICE,
+        warnings: input.warnings,
+        memory_inputs: memoryInputs,
+        matches,
+    });
+}
+//# sourceMappingURL=memory-preview.js.map

package/dist/app/history/memory-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-preview.js","sourceRoot":"","sources":["../../../src/app/history/memory-preview.ts"],"names":[],"mappings":"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"}

package/dist/app/history/pull-log.d.ts

@@ -0,0 +1,13 @@
+import { type HistoryPullLogV1 as HistoryPullLog, type HistoryWarningV1, type PullLogEntryV1 } from '../../schemas/index.js';
+export declare const HISTORY_PULL_LOG_RELATIVE_PATH = "reports/history/pull-log.json";
+export interface AppendPullLogEntryInput {
+    readonly entry: PullLogEntryV1;
+    readonly runId?: string;
+}
+export interface AppendPullLogEntryResult {
+    readonly path?: string;
+    readonly warnings: readonly HistoryWarningV1[];
+}
+export declare function readPullLog(runFolder: string): HistoryPullLog | undefined;
+export declare function appendPullLogEntry(runFolder: string, input: AppendPullLogEntryInput): AppendPullLogEntryResult;
+//# sourceMappingURL=pull-log.d.ts.map

package/dist/app/history/pull-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-log.d.ts","sourceRoot":"","sources":["../../../src/app/history/pull-log.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,gBAAgB,IAAI,cAAc,EAEvC,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,8BAA8B,kCAAkC,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAG/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IAEvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAeD,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQzE;AAYD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,uBAAuB,GAC7B,wBAAwB,CAgD1B"}

package/dist/app/history/pull-log.js

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { HISTORY_AUTHORITY_NOTICE, HistoryPullLogV1, } from '../../schemas/index.js';
+import { writeJsonAtomic } from '../../shared/atomic-io.js';
+// Stable on-disk contract path. Held as a local constant (the Slice 1 discipline)
+// so this writer targets the run-folder layout convention reports/history/*.json
+// rather than coupling to any module's current file location.
+export const HISTORY_PULL_LOG_RELATIVE_PATH = 'reports/history/pull-log.json';
+function pullLogUnavailable(runFolder, error) {
+    return {
+        code: 'pull_log_unavailable',
+        message: `pull-log unwritable: ${error instanceof Error ? error.message : String(error)}; the pull returned results but was not logged`,
+        run_folder: runFolder,
+        source_path: HISTORY_PULL_LOG_RELATIVE_PATH,
+    };
+}
+// Read <run-folder>/reports/history/pull-log.json if present and parseable.
+// Returns undefined when the file is absent or unreadable — read failures never
+// throw (the caller treats undefined as "no prior log", which is also the
+// first-pull case).
+export function readPullLog(runFolder) {
+    const path = join(runFolder, HISTORY_PULL_LOG_RELATIVE_PATH);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return HistoryPullLogV1.parse(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Append one entry to the run folder's pull-log, atomically and fail-soft. On the
+// first pull the file does not exist, so the writer synthesizes the full
+// HistoryPullLogV1 header (api_version/schema_version/authority_notice plus the
+// optional run_id and an empty file-level warnings array) and pushes the entry; on
+// later pulls it preserves the header and appends. A prior log that exists but is
+// unreadable is RESET to a fresh header carrying the new entry, with a file-level
+// pull_log_unavailable warning recording the reset. The write is tmp+rename and
+// re-parsed before the rename commits (the Slice 1 discipline). Any I/O failure is
+// swallowed into a pull_log_unavailable warning and no path: orienting the agent
+// outranks bookkeeping, so the pull is NEVER blocked by a logging failure (D2).
+export function appendPullLogEntry(runFolder, input) {
+    const outPath = join(runFolder, HISTORY_PULL_LOG_RELATIVE_PATH);
+    const warnings = [];
+    // Reading the prior log can fail two ways: the file is absent (the first-pull
+    // case — synthesize a fresh header) or it is present-but-corrupt (reset to a
+    // fresh header and warn). readPullLog already collapses both to undefined, so we
+    // distinguish them by existence to decide whether the reset warning is owed.
+    let existing;
+    try {
+        if (existsSync(outPath)) {
+            existing = HistoryPullLogV1.parse(JSON.parse(readFileSync(outPath, 'utf8')));
+        }
+    }
+    catch (error) {
+        warnings.push(pullLogUnavailable(runFolder, error));
+    }
+    let log;
+    try {
+        log =
+            existing === undefined
+                ? HistoryPullLogV1.parse({
+                    api_version: 'history-pull-log-v1',
+                    schema_version: 1,
+                    ...(input.runId === undefined ? {} : { run_id: input.runId }),
+                    authority_notice: HISTORY_AUTHORITY_NOTICE,
+                    entries: [input.entry],
+                    warnings,
+                })
+                : HistoryPullLogV1.parse({
+                    ...existing,
+                    entries: [...existing.entries, input.entry],
+                    // Carry forward any prior file-level warnings (the header is preserved).
+                    warnings: existing.warnings,
+                });
+    }
+    catch (error) {
+        // The entry or synthesized header failed validation — fail-soft, do not throw.
+        return { warnings: [pullLogUnavailable(runFolder, error)] };
+    }
+    try {
+        writeJsonAtomic(outPath, log, {
+            validate: (raw) => HistoryPullLogV1.parse(JSON.parse(raw)),
+        });
+        return { path: outPath, warnings };
+    }
+    catch (error) {
+        return { warnings: [...warnings, pullLogUnavailable(runFolder, error)] };
+    }
+}
+//# sourceMappingURL=pull-log.js.map

package/dist/app/history/pull-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-log.js","sourceRoot":"","sources":["../../../src/app/history/pull-log.ts"],"names":[],"mappings":"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"}

package/dist/app/history/pull-suppression.d.ts

@@ -0,0 +1,12 @@
+import { type HistoryMemoryEffectV1, type HistoryMemoryInputPreviewV1 as HistoryMemoryInputPreview } from '../../schemas/index.js';
+export interface SuppressMeasuredNegativeInput {
+    readonly preview: HistoryMemoryInputPreview;
+    readonly flowId: string;
+    readonly effect?: HistoryMemoryEffectV1;
+}
+export interface SuppressMeasuredNegativeResult {
+    readonly preview: HistoryMemoryInputPreview;
+    readonly suppressedCount: number;
+}
+export declare function suppressMeasuredNegative(input: SuppressMeasuredNegativeInput): SuppressMeasuredNegativeResult;
+//# sourceMappingURL=pull-suppression.d.ts.map

package/dist/app/history/pull-suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-suppression.d.ts","sourceRoot":"","sources":["../../../src/app/history/pull-suppression.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,IAAI,yBAAyB,EAE9D,MAAM,wBAAwB,CAAC;AAGhC,MAAM,WAAW,6BAA6B;IAG5C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAG5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAYD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,8BAA8B,CAwChC"}

package/dist/app/history/pull-suppression.js

@@ -0,0 +1,40 @@
+import { HistoryMemoryInputPreviewV1, } from '../../schemas/index.js';
+import { groupKeyForMemory } from './memory-identity.js';
+// The pure pull-suppression seam (Slice 4 D3), mirroring Slice 3's pure gate. It
+// drops every memory input whose (group_key, flow) verdict is correlated_negative
+// — the only measured-harm state — AND its parallel matches[] entry (same
+// memory_id), so the printed preview stays internally consistent (the preview
+// schema has no length-binding refine; this is the seam that keeps it consistent).
+// Unlike the push gate it applies NO budget or tier ordering: the agent asked an
+// explicit question at a decision point, so the pull surfaces everything that
+// matches except measured harm (D3). The key is formed exactly as Slice 3's, via
+// groupKeyForMemory, so a hint suppressed by the push path is suppressed by the
+// pull path too. No I/O; it never mutates the input preview.
+export function suppressMeasuredNegative(input) {
+    // (group_key, flow_id) -> verdict, from Slice 2's per-item effects. Cold corpus
+    // (no effect report, or no rows) leaves this empty, so nothing is suppressed.
+    const verdicts = new Map();
+    if (input.effect !== undefined) {
+        for (const item of input.effect.item_effects) {
+            verdicts.set(`${item.group_key} ${item.flow_id}`, item.comparison.effect_status);
+        }
+    }
+    const isMeasuredNegative = (memory) => verdicts.get(`${groupKeyForMemory(memory)} ${input.flowId}`) === 'correlated_negative';
+    // The ids dropped from memory_inputs; the parallel matches[] entries with the
+    // same id are dropped in lockstep so the preview stays consistent.
+    const suppressedIds = new Set(input.preview.memory_inputs.filter(isMeasuredNegative).map((memory) => memory.memory_id));
+    if (suppressedIds.size === 0) {
+        return { preview: input.preview, suppressedCount: 0 };
+    }
+    const memoryInputs = input.preview.memory_inputs.filter((memory) => !suppressedIds.has(memory.memory_id));
+    const matches = input.preview.matches.filter((match) => !suppressedIds.has(match.memory_id));
+    // Re-validate the trimmed preview so a malformed projection cannot slip through
+    // the suppression seam (the Slice 1/2/3 parse-the-result discipline).
+    const preview = HistoryMemoryInputPreviewV1.parse({
+        ...input.preview,
+        memory_inputs: memoryInputs,
+        matches,
+    });
+    return { preview, suppressedCount: suppressedIds.size };
+}
+//# sourceMappingURL=pull-suppression.js.map

package/dist/app/history/pull-suppression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-suppression.js","sourceRoot":"","sources":["../../../src/app/history/pull-suppression.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAmBzD,iFAAiF;AACjF,kFAAkF;AAClF,0EAA0E;AAC1E,8EAA8E;AAC9E,mFAAmF;AACnF,iFAAiF;AACjF,8EAA8E;AAC9E,iFAAiF;AACjF,gFAAgF;AAChF,6DAA6D;AAC7D,MAAM,UAAU,wBAAwB,CACtC,KAAoC;IAEpC,gFAAgF;IAChF,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAGrB,CAAC;IACJ,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YAC7C,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,MAAM,kBAAkB,GAAG,CACzB,MAA0D,EACjD,EAAE,CACX,QAAQ,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,qBAAqB,CAAC;IAEzF,8EAA8E;IAC9E,mEAAmE;IACnE,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CACzF,CAAC;IACF,IAAI,aAAa,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CACrD,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CACjD,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAE7F,gFAAgF;IAChF,sEAAsE;IACtE,MAAM,OAAO,GAAG,2BAA2B,CAAC,KAAK,CAAC;QAChD,GAAG,KAAK,CAAC,OAAO;QAChB,aAAa,EAAE,YAAY;QAC3B,OAAO;KACR,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/app/history/query.d.ts

@@ -0,0 +1,19 @@
+import { type HistoryDocumentKindV1, type HistoryQueryResultV1 as HistoryQueryResult } from '../../schemas/index.js';
+import { type HistoryPathOptions } from './indexer.js';
+export interface HistoryQueryOptions extends HistoryPathOptions {
+    readonly query: string;
+    readonly limit?: number;
+    readonly perRunLimit?: number;
+    readonly flow?: string;
+    readonly kind?: HistoryDocumentKindV1;
+    readonly rebuildIfStale?: boolean;
+    readonly now?: () => Date;
+}
+export declare function scoreProjectFactRelevance(input: {
+    readonly query: string;
+    readonly summary: string;
+    readonly hintTexts: readonly string[];
+    readonly appliesTo: readonly string[];
+}): number;
+export declare function queryHistory(options: HistoryQueryOptions): HistoryQueryResult;
+//# sourceMappingURL=query.d.ts.map

package/dist/app/history/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/app/history/query.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,IAAI,kBAAkB,EAIhD,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,cAAc,CAAC;AA6BtB,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AA8ID,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,MAAM,CAwBT;AAwDD,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAkH7E"}

package/dist/app/history/query.js

@@ -0,0 +1,342 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { HISTORY_AUTHORITY_NOTICE, HistoryQueryResultV1, } from '../../schemas/index.js';
+import { sha256Hex } from '../../shared/connector-relay.js';
+import { resolveRunFilePath } from '../../shared/run-file-paths.js';
+import { HistoryCommandError, historyIndexState, readHistoryIndex, rebuildHistoryIndex, resolveHistoryPaths, } from './indexer.js';
+const STOPWORDS = new Set([
+    'the',
+    'and',
+    'for',
+    'that',
+    'this',
+    'with',
+    'from',
+    'into',
+    'what',
+    'when',
+    'where',
+    'why',
+    'how',
+    'run',
+    'runs',
+    'circuit',
+    'history',
+    'query',
+    'report',
+    'reports',
+]);
+const FAILURE_TERMS = new Set(['fail', 'failed', 'failure', 'aborted', 'abort', 'error']);
+const CHECKPOINT_TERMS = new Set(['checkpoint', 'choice', 'selection', 'resume']);
+const VERIFICATION_TERMS = new Set(['verify', 'verification', 'proof', 'check', 'test']);
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((term) => term.length >= 2 && !STOPWORDS.has(term));
+}
+function termCounts(tokens) {
+    const counts = new Map();
+    for (const token of tokens)
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+    return counts;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function idf(documents) {
+    const docFreq = new Map();
+    for (const doc of documents) {
+        const terms = unique(tokenize(`${doc.title}\n${doc.summary}\n${doc.text}\n${doc.facets.join(' ')}`));
+        for (const term of terms)
+            docFreq.set(term, (docFreq.get(term) ?? 0) + 1);
+    }
+    const out = new Map();
+    for (const [term, count] of docFreq) {
+        out.set(term, Math.log((documents.length + 1) / (count + 1)) + 1);
+    }
+    return out;
+}
+function weightedTf(doc, term) {
+    const title = termCounts(tokenize(doc.title)).get(term) ?? 0;
+    const summary = termCounts(tokenize(doc.summary)).get(term) ?? 0;
+    const text = termCounts(tokenize(doc.text)).get(term) ?? 0;
+    const facets = termCounts(tokenize(doc.facets.join(' '))).get(term) ?? 0;
+    return title * 5 + summary * 4 + facets * 2 + text;
+}
+function queryBigrams(terms) {
+    const bigrams = [];
+    for (let index = 0; index < terms.length - 1; index += 1) {
+        const left = terms[index];
+        const right = terms[index + 1];
+        if (left !== undefined && right !== undefined)
+            bigrams.push(`${left} ${right}`);
+    }
+    return bigrams;
+}
+function facetBoost(queryTerms, doc) {
+    let score = 0;
+    const reasons = [];
+    const facets = new Set(doc.facets);
+    if (queryTerms.some((term) => FAILURE_TERMS.has(term)) && facets.has('failure')) {
+        score += 5;
+        reasons.push('failure facet matched');
+        if (doc.doc_kind === 'trace' || doc.doc_kind === 'run') {
+            score += 3;
+            reasons.push('failure trace/run prioritized');
+        }
+    }
+    if (queryTerms.some((term) => CHECKPOINT_TERMS.has(term)) && facets.has('checkpoint')) {
+        score += 2;
+        reasons.push('checkpoint facet matched');
+    }
+    if (queryTerms.some((term) => VERIFICATION_TERMS.has(term)) && facets.has('verification')) {
+        score += 2;
+        reasons.push('verification facet matched');
+    }
+    return { score, reasons };
+}
+function scoreDocument(input) {
+    let score = 0;
+    const reasons = [];
+    const matchedTerms = [];
+    for (const term of input.queryTerms) {
+        const tf = Math.min(weightedTf(input.doc, term), 3);
+        if (tf <= 0)
+            continue;
+        matchedTerms.push(term);
+        score += (input.queryIdf.get(term) ?? 1) * tf;
+    }
+    const haystack = `${input.doc.title}\n${input.doc.summary}\n${input.doc.text}`.toLowerCase();
+    const queryPhrase = input.query.trim().toLowerCase();
+    if (queryPhrase.length > 0 && haystack.includes(queryPhrase)) {
+        score += 2;
+        reasons.push('exact phrase matched');
+    }
+    for (const bigram of queryBigrams(input.queryTerms)) {
+        if (haystack.includes(bigram)) {
+            score += 0.5;
+            reasons.push(`bigram matched: ${bigram}`);
+        }
+    }
+    const boosted = facetBoost(input.queryTerms, input.doc);
+    score += boosted.score;
+    reasons.push(...boosted.reasons);
+    if (!input.doc.memory_safe) {
+        score -= 3;
+        reasons.push('memory-unsafe source penalized');
+    }
+    if (input.indexState === 'possibly_stale') {
+        score -= 0.5;
+        reasons.push('possibly stale index penalty');
+    }
+    if (matchedTerms.length > 0)
+        reasons.push(`matched terms: ${matchedTerms.join(', ')}`);
+    return {
+        score,
+        matchedTerms: unique(matchedTerms),
+        reasons,
+    };
+}
+// Lexical relevance of a stored project fact to the run query. Reuses the same
+// machinery prior-run recall uses (tokenize -> weighted term frequency capped at
+// 3, exact-phrase +2, adjacent-bigram +0.5) so a project fact and a prior-run
+// hit are scored on the same scale. A project fact carries no corpus, so IDF is
+// flat (every matched term contributes its capped weighted tf directly) and the
+// stale/effect signals stay out of this number; those are the gate's job, not
+// the scorer's. The caller maps a fact's fields onto these inputs: `summary` is
+// the headline (summary weight), each hint `text` is detail (text weight), and
+// each hint `applies_to` is a categorical tag (facet weight). Returns 0 when the
+// query has no scorable terms, which preserves store order under a flat tie.
+export function scoreProjectFactRelevance(input) {
+    const queryTerms = unique(tokenize(input.query));
+    if (queryTerms.length === 0)
+        return 0;
+    const summaryCounts = termCounts(tokenize(input.summary));
+    const textCounts = termCounts(tokenize(input.hintTexts.join('\n')));
+    const facetCounts = termCounts(tokenize(input.appliesTo.join(' ')));
+    let score = 0;
+    for (const term of queryTerms) {
+        // Same field weighting as weightedTf (title*5 + summary*4 + facets*2 + text),
+        // minus the title field a project fact does not have, then capped at 3.
+        const weighted = (summaryCounts.get(term) ?? 0) * 4 +
+            (facetCounts.get(term) ?? 0) * 2 +
+            (textCounts.get(term) ?? 0);
+        const tf = Math.min(weighted, 3);
+        if (tf > 0)
+            score += tf;
+    }
+    const haystack = `${input.summary}\n${input.hintTexts.join('\n')}`.toLowerCase();
+    const queryPhrase = input.query.trim().toLowerCase();
+    if (queryPhrase.length > 0 && haystack.includes(queryPhrase))
+        score += 2;
+    for (const bigram of queryBigrams(queryTerms)) {
+        if (haystack.includes(bigram))
+            score += 0.5;
+    }
+    return score;
+}
+function normalizeText(text) {
+    return tokenize(text).join(' ');
+}
+function snippet(doc, matchedTerms) {
+    const haystack = `${doc.summary}\n${doc.text}`.replace(/\s+/g, ' ').trim();
+    if (haystack.length <= 420)
+        return haystack;
+    const lower = haystack.toLowerCase();
+    const firstMatch = matchedTerms
+        .map((term) => lower.indexOf(term))
+        .filter((index) => index >= 0)
+        .sort((left, right) => left - right)[0];
+    const start = Math.max(0, (firstMatch ?? 0) - 120);
+    return haystack.slice(start, start + 420).trim();
+}
+function sourceStaleness(doc, checkedAt) {
+    if (doc.source_sha256 === undefined) {
+        return {
+            status: 'unknown',
+            reason_codes: ['memory_unverified'],
+            checked_at: checkedAt,
+        };
+    }
+    try {
+        const sourcePath = resolveRunFilePath(doc.run_folder, doc.source_path);
+        if (!existsSync(sourcePath)) {
+            return {
+                status: 'stale',
+                reason_codes: ['memory_stale'],
+                checked_at: checkedAt,
+            };
+        }
+        const currentHash = sha256Hex(readFileSync(sourcePath, 'utf8'));
+        return currentHash === doc.source_sha256
+            ? {
+                status: 'fresh',
+                reason_codes: ['source_hash_verified'],
+                checked_at: checkedAt,
+            }
+            : {
+                status: 'stale',
+                reason_codes: ['memory_stale'],
+                checked_at: checkedAt,
+            };
+    }
+    catch {
+        return {
+            status: 'unknown',
+            reason_codes: ['memory_unverified'],
+            checked_at: checkedAt,
+        };
+    }
+}
+export function queryHistory(options) {
+    const limit = options.limit ?? 8;
+    const perRunLimit = options.perRunLimit ?? 1;
+    if (limit < 1 || limit > 50 || !Number.isInteger(limit)) {
+        throw new HistoryCommandError('invalid_invocation', '--limit must be an integer from 1 to 50');
+    }
+    if (perRunLimit < 1 || perRunLimit > 5 || !Number.isInteger(perRunLimit)) {
+        throw new HistoryCommandError('invalid_invocation', '--per-run-limit must be an integer from 1 to 5');
+    }
+    const queryTerms = unique(tokenize(options.query));
+    const paths = resolveHistoryPaths(options);
+    let rebuilt = false;
+    let index;
+    try {
+        index = readHistoryIndex(options);
+    }
+    catch (error) {
+        if (error instanceof HistoryCommandError &&
+            error.code === 'index_missing' &&
+            options.rebuildIfStale === true) {
+            index = rebuildHistoryIndex(options);
+            rebuilt = true;
+        }
+        else {
+            throw error;
+        }
+    }
+    let indexState = historyIndexState(paths, index.manifest);
+    if (indexState === 'possibly_stale' && options.rebuildIfStale === true) {
+        index = rebuildHistoryIndex(options);
+        rebuilt = true;
+        indexState = historyIndexState(paths, index.manifest);
+    }
+    const warnings = [...index.manifest.warnings];
+    if (indexState === 'possibly_stale') {
+        warnings.push({
+            code: 'source_invalid',
+            message: 'history index may be stale; run circuit history rebuild --json to refresh it',
+        });
+    }
+    const candidates = index.documents.filter((doc) => {
+        if (options.flow !== undefined && doc.flow_id !== options.flow)
+            return false;
+        if (options.kind !== undefined && doc.doc_kind !== options.kind)
+            return false;
+        return true;
+    });
+    const idfMap = idf(candidates);
+    const scored = candidates
+        .map((doc) => {
+        const score = scoreDocument({
+            query: options.query,
+            queryTerms,
+            queryIdf: idfMap,
+            doc,
+            indexState,
+        });
+        return { doc, ...score };
+    })
+        .filter((candidate) => candidate.score > 0 || options.query.trim().length === 0)
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        const rightDate = Date.parse(right.doc.recorded_at ?? '1970-01-01T00:00:00.000Z');
+        const leftDate = Date.parse(left.doc.recorded_at ?? '1970-01-01T00:00:00.000Z');
+        if (rightDate !== leftDate)
+            return rightDate - leftDate;
+        return left.doc.doc_id.localeCompare(right.doc.doc_id);
+    });
+    const seenText = new Set();
+    const runCounts = new Map();
+    const selected = [];
+    for (const candidate of scored) {
+        const textHash = sha256Hex(normalizeText(candidate.doc.text));
+        if (seenText.has(textHash))
+            continue;
+        const runCount = runCounts.get(candidate.doc.run_id) ?? 0;
+        if (runCount >= perRunLimit)
+            continue;
+        seenText.add(textHash);
+        runCounts.set(candidate.doc.run_id, runCount + 1);
+        selected.push(candidate);
+        if (selected.length >= limit)
+            break;
+    }
+    const checkedAt = (options.now ?? (() => new Date()))().toISOString();
+    const hits = selected.map((candidate, index) => {
+        const staleness = sourceStaleness(candidate.doc, checkedAt);
+        const freshBoost = staleness.status === 'fresh' ? 0.25 : 0;
+        return {
+            rank: index + 1,
+            score: Number((candidate.score + freshBoost).toFixed(6)),
+            doc: candidate.doc,
+            snippet: snippet(candidate.doc, candidate.matchedTerms),
+            matched_terms: [...candidate.matchedTerms],
+            ranking_reasons: freshBoost > 0 ? [...candidate.reasons, 'source hash verified'] : [...candidate.reasons],
+            staleness,
+        };
+    });
+    return HistoryQueryResultV1.parse({
+        api_version: 'history-query-result-v1',
+        schema_version: 1,
+        query: options.query,
+        format: 'json',
+        index_state: indexState,
+        rebuilt,
+        authority_notice: HISTORY_AUTHORITY_NOTICE,
+        warnings,
+        results: hits,
+    });
+}
+//# sourceMappingURL=query.js.map