scoutline 0.23.0 → 0.24.0

package/dist/commands/investigate.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Investigation orchestrator (investigate-pipeline lane, Ticket T4;
+ * docs/plans/investigate-pipeline DESIGN.md D3, PRD AC-3/AC-4/AC-9/
+ * AC-10; ADR-0013).
+ *
+ * Thin, data-returning composition of the seams `search` and `read`
+ * already export — no bespoke merge fork, no local fan-out copy, no
+ * transport of its own:
+ *
+ *   1. planSubQueries (T2, injected loadContextText — no filesystem).
+ *   2. resolveFanoutPlan over the resolved provider pin (AC-1 tiers,
+ *      the same inputs handleSearch passes).
+ *   3. Grid execution through the exported seams: fan-out mode runs
+ *      executeFanoutPlan; single mode runs the exported search() with
+ *      {merge: N > 1} over the escaped-pipe join of the sub-queries
+ *      (the exact context-mode join precedent, index.ts handleSearch).
+ *   4. Top --sources distinct sources = the first K rows of the merged
+ *      FormattedResult[] (mergeResults already collapsed near-dup
+ *      clusters to representatives — a near-dup pair IS one row).
+ *   5. Reads: bounded-concurrency pool (default 4) over the reader
+ *      capability seam via executeReaderOperation, one client per
+ *      read (descriptor.create per read), closed in `finally`.
+ *   6. extractPassages (T3) per read result.
+ *   7. EvidencePack assembly per the T1 types.
+ *
+ * `--synthesize` (T7, PRD AC-7, DESIGN D6, ADR-0013 §2) is the explicit
+ * Z.AI-only escape hatch and is ADDITIVE-ONLY BY CONSTRUCTION: the pack
+ * is fully assembled (searches, reads, extraction, coverage) BEFORE the
+ * synthesis dep is ever called, so the brief can only ever be ADDED as
+ * the LAST key — a failed synthesis is the invocation's terminal error
+ * and never degrades, shrinks, or reorders the pack. The command holds
+ * no transport: construction is handler-seam wiring, exactly like every
+ * other capability, and the dep is injected.
+ *
+ * Reader supplier selection mirrors handleRead: the FIRST descriptor
+ * in registry order whose injected `readerCapabilityFor` resolves a
+ * ReaderCapability serves every read (the same first-configured-capable
+ * order read uses; cross-provider fallback per failed read is the
+ * index.ts handler seam's business, T6). A supplier that rejects a
+ * source terminally classifies as `reader-failed:<code>`; a supplier
+ * that cannot serve the capability at all classifies as
+ * `no-reader-supplier`. Unread rows carry reason codes only
+ * (redacted, house rule); the pool continues past them;
+ * `sourcesRead` counts successes only.
+ *
+ * Consumption linearity: every billable arm and read attempt records
+ * exactly one event (N×M + K) because the shared executors emit per
+ * invoke and the orchestrator never double-reads a URL.
+ *
+ * `--isolated` is ACCEPTED, never rejected: the pid-segment cache
+ * behavior is the main() handler seam's job (T6) — the command has no
+ * cache-directory logic of its own; the injected cache IS the
+ * (possibly isolated) production cache. Journal entry/marker WRITING
+ * lives at the index.ts descriptor seam (journalingDescriptors /
+ * captureServingDescriptors): this command consumes the injected
+ * descriptor list verbatim, so capture-wrapped descriptors keep
+ * stamping servedFrom/cacheKey cells the journal hook consumes — the
+ * T4-level guarantee (asserted by the seam-passthrough test); journal
+ * wiring itself is deferred to T6 (journal.ts / index.ts untouched).
+ */
+import type { CommandContext, CommandResult } from "../command-invocation.js";
+import type { ReaderCapability } from "../capabilities/reader.js";
+import type { FusionMode } from "../lib/config-store.js";
+import { type ResponseCache } from "../lib/cache.js";
+import type { RetryPolicy } from "../lib/execution.js";
+import type { ConsumptionSink } from "../lib/consumption.js";
+import type { ProviderDescriptor, ProviderId } from "../providers/types.js";
+import { type LadderRule } from "../lib/output-budget.js";
+/**
+ * `--synthesize` escape hatch (T7). The deterministic brief prompt: the
+ * bare question, the planned sub-query grid, and the extracted passage
+ * quotes (bounded). No clock, no randomness — identical fixtures produce
+ * a byte-identical prompt.
+ */
+export interface SynthesisPrompt {
+    readonly question: string;
+    readonly subQueries: readonly string[];
+    /** Extracted passage quotes, in pack order, capped at
+     * {@link SYNTHESIS_QUOTE_CAP}. */
+    readonly quotes: readonly string[];
+}
+/**
+ * Passage-quote cap for the brief prompt. Bounded so the prompt cannot
+ * grow with the read pool: 20 quotes ≈ the first few sources' passages,
+ * well inside the Z.AI chat context even at the passage cap (5 per
+ * source). Deterministic (first N in pack order), never sampled.
+ */
+export declare const SYNTHESIS_QUOTE_CAP = 20;
+/**
+ * The synthesis dep shape. `synthesize?` is threaded from the handler
+ * seam (index.ts), which owns the transport — the command never
+ * constructs one. Production passes a Z.AI chat-completions caller;
+ * tests pass a fixture.
+ */
+export type SynthesizeBrief = (prompt: SynthesisPrompt) => Promise<string>;
+/**
+ * `investigate --help` (T6/T7). The command's rejected-flag contract is
+ * part of the surface: --depth/--arms/--budget-tokens DO NOT EXIST (PRD
+ * AC-1 — the rejection is the feature), and --context-stdin is
+ * deliberately not investigate's (search-only spelling; pipes and
+ * --context cover the sub-query sources).
+ */
+export declare const INVESTIGATE_HELP: string;
+export interface InvestigateOptions {
+    /**
+     * Raw `--provider` value (comma-list / "all" / single id), threaded
+     * to resolveFanoutPlan verbatim — the same tier grammar search uses.
+     */
+    readonly provider?: string;
+    /** `--context` file path; selects the planner's context tier. */
+    readonly contextFile?: string;
+    /**
+     * `--sources`: how many distinct post-cluster sources to read.
+     * Positive integer; default 5. 0/negative/non-integers are
+     * VALIDATION_ERROR (validation at the trust boundary).
+     */
+    readonly sources?: number;
+    /**
+     * ACCEPTED, never rejected (PRD AC-9: no ISOLATED_REJECTED path).
+     * The pid-segment cache behavior belongs to the main() handler seam
+     * (T6) — this command has no cache-directory logic of its own; the
+     * injected cache IS the (possibly isolated) production cache.
+     */
+    readonly isolated?: boolean;
+    /** `--no-cache`: threaded to every underlying search + read. */
+    readonly noCache?: boolean;
+    /**
+     * `--no-journal`: threaded through ONLY as far as the command seam
+     * allows (the underlying ops take no such option — journaling is
+     * wired at the index.ts descriptor/hook seam). T6 owns the real
+     * suppression; recorded here so the option never fails the parse.
+     */
+    readonly noJournal?: boolean;
+    /**
+     * `--max-chars` (T5, D7): whole-envelope Output Budget over the
+     * EvidencePack via INVESTIGATE_LADDER. Strict positive integer
+     * (parseBriefMaxChars class); 0/negative/fractional values are
+     * VALIDATION_ERROR at the trust boundary.
+     */
+    readonly maxChars?: number;
+    /**
+     * `--synthesize` (T7, PRD AC-7): attach an additive `brief` to the
+     * pack via the injected {@link InvestigateExecutionDependencies.
+     * synthesize} dep. Z.AI-only (the notice lives at the handler seam,
+     * where the raw provider pin is visible). Set without a dep is a
+     * wiring bug — the command throws rather than silently skipping.
+     */
+    readonly synthesize?: boolean;
+    /**
+     * investigate-verify lane (DESIGN D3, PRD AC-1): claim-corroboration
+     * mode. The positional becomes the statement; `splitClaims` owns the
+     * grid (one verbatim sub-query per sentence-claim, ≤ 8 — the R1
+     * fail-loud cap); the planner module is NOT invoked. `--context` +
+     * `--verify` is pair-rejected at the index.ts parse seam; `|` is
+     * literal text (claims split on sentences, never pipes).
+     */
+    readonly verify?: boolean;
+}
+/**
+ * INVESTIGATE_LADDER (D7 budget order; verify lane D6 extension):
+ * passages trim FIRST (quote truncate, charRange adjusts — the
+ * round-trip pin survives), then LATE sources drop whole, then —
+ * verify packs only — evidence pointers drop per claim (whole).
+ * question/subQueries/coverage and verify claim text/verdicts/cue
+ * counts are never cut — expressed by omission (no rule touches
+ * them).
+ */
+export declare const INVESTIGATE_LADDER: readonly [LadderRule<unknown>, LadderRule<unknown>, LadderRule<unknown>];
+export interface InvestigateExecutionDependencies {
+    /**
+     * Live provider registry — the same `HandlerDependencies.
+     * providerDescriptors` list handleSearch consumes (possibly the
+     * capture-wrapped journalingDescriptors list; this command never
+     * unwraps it, so journal servedFrom/cacheKey stamping survives).
+     */
+    readonly descriptors: readonly ProviderDescriptor[];
+    /** The resolved env (env + file-configured keys). Input only. */
+    readonly env: NodeJS.ProcessEnv;
+    /** Whether `fanout` is enabled in the active config. */
+    readonly configFanout: boolean;
+    /** Resolved per-capability routing table. */
+    readonly routing?: Readonly<Record<string, readonly ProviderId[]>>;
+    /** Shared response cache for search arms AND reads. */
+    readonly cache: ResponseCache;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly random: () => number;
+    readonly retryPolicy?: RetryPolicy;
+    /** Usage-ledger sink — N×M + K linearity pins on it. */
+    readonly consume?: ConsumptionSink;
+    /** Clock for consumption events. */
+    readonly now?: () => number;
+    /**
+     * Fusion ranking mode — resolved ONCE at the handler seam (env >
+     * config > "rrf"), exactly how handleSearch threads it. Omitted
+     * (direct tests) → "rrf".
+     */
+    readonly fusionMode?: FusionMode;
+    /**
+     * Wall clock for `fetchedAt` (ISO-8601 UTC-Z, D5). Injected for
+     * byte-identical determinism pins; defaults to `() => new Date()`.
+     */
+    nowWall?: () => Date;
+    /**
+     * Read-pool concurrency bound (default 4). Overridable in deps so
+     * tests can pin the pool shape without timers.
+     */
+    readConcurrency?: number;
+    /** Injected context reader (production: readContextSource-shaped). */
+    loadContextText(filePath: string): Promise<string>;
+    /**
+     * Reader supplier seam: resolve the ReaderCapability a provider
+     * descriptor serves, or `undefined` when it has none. Production
+     * mirrors handleRead's shape — `descriptor.create({ env }).reader` —
+     * so selection follows the same first-configured-capable order read
+     * uses (the registry order the descriptor list already carries).
+     */
+    readerCapabilityFor(descriptor: ProviderDescriptor): ReaderCapability | undefined;
+    /**
+     * T5: resolved secrets for the compaction artifact's redaction (the
+     * save seam's contract — the caller redacts before persisting).
+     * Omitted (direct tests, no secrets) → no-op redaction.
+     */
+    readonly secrets?: string[];
+    /**
+     * T7: the synthesis transport (handler-seam wiring — this command
+     * never constructs one). Consulted ONLY when `--synthesize` is set,
+     * and only AFTER the pack is fully assembled.
+     */
+    synthesize?: SynthesizeBrief;
+}
+export declare function investigate(question: string, options: InvestigateOptions | undefined, deps: InvestigateExecutionDependencies, context?: CommandContext): Promise<CommandResult>;
+//# sourceMappingURL=investigate.d.ts.map

package/dist/commands/investigate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"investigate.d.ts","sourceRoot":"","sources":["../../src/commands/investigate.ts"],"names":[],"mappings":"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"}