/**
 * Typed `FindingSubject` — the canonical grammar every analyst kind emits.
 *
 * Background: kind actor prompts have always documented a subject grammar
 * (e.g. `system-prompt:<section>`, `agent-knowledge:wiki:<slug>`) but the
 * LLM was unconstrained — it could emit `subject: "fix the prompt"`
 * (prose) and downstream adapters routed on `startsWith(...)` would
 * silently skip it. Every per-vertical `ImprovementAdapter` had a
 * routing table that mostly caught nothing.
 *
 * This module fixes that:
 *   - `parseFindingSubject(raw)` — returns the typed `FindingSubject`
 *     when `raw` matches the grammar, else `null`. Used at the
 *     `RawAnalystFindingSchema` boundary so malformed subjects are
 *     rejected loudly instead of silently lifted into the registry.
 *   - `FindingSubjectKind` — the union of valid locus categories. Each
 *     variant carries the typed components downstream adapters resolve
 *     against the agent's surface manifest (no string parsing in the
 *     adapter).
 *   - `FINDING_SUBJECT_GRAMMAR_PROMPT` — single source of truth for the
 *     grammar string embedded in kind actor prompts. Drift between
 *     prompt and parser is impossible if every kind imports this.
 *
 * The grammar is intentionally NARROW — only loci the substrate's
 * default `ImprovementAdapter` / `KnowledgeAdapter` can act on. A
 * finding with a subject outside this set fails the parser; the kind
 * author either extends the grammar here (and adds adapter routing)
 * or rephrases the prompt to map onto an existing variant.
 *
 * `failure-mode` is the one exception — its subjects are free-form
 * cluster labels, not loci. The schema preserves them as
 * `{ kind: 'cluster', label }` and the adapters skip them (cluster
 * findings are evidence, not actionable mutations).
 */
import { z } from 'zod';
/**
 * Discriminated union of every locus the substrate can route findings to.
 *
 * Adapters narrow on `kind` and use the typed components (no string
 * parsing). Adding a variant here REQUIRES updating the parser, the
 * grammar prompt, and at least one adapter — by design.
 */
export type FindingSubject = {
    kind: 'knowledge.wiki';
    slug: string;
    heading?: string;
} | {
    kind: 'knowledge.claim';
    topic: string;
} | {
    kind: 'knowledge.raw';
    sourceId: string;
} | {
    kind: 'knowledge.stale';
    slug: string;
} | {
    kind: 'system-prompt';
    section: string;
} | {
    kind: 'tool-doc';
    tool: string;
    aspect?: string;
} | {
    kind: 'new-tool';
    name: string;
} | {
    kind: 'rag';
    corpus: string;
    docId: string;
} | {
    kind: 'memory';
    key: string;
} | {
    kind: 'scaffolding';
    concern: string;
} | {
    kind: 'output-schema';
    field: string;
} | {
    kind: 'websearch.outdated';
    topic: string;
} | {
    kind: 'prior-run-summary';
    topic: string;
} | {
    kind: 'cluster';
    label: string;
};
export type FindingSubjectKind = FindingSubject['kind'];
export declare const FINDING_SUBJECT_KINDS: ReadonlyArray<FindingSubjectKind>;
/**
 * Parse a raw subject string emitted by an analyst kind's actor.
 *
 * Returns the typed `FindingSubject` when `raw` matches the grammar,
 * else `null`. Callers use the `null` return as a signal to either
 * (a) reject the finding at parse time (kinds that emit typed loci —
 * knowledge-gap, improvement, knowledge-poisoning) or (b) lift it as
 * a cluster label (failure-mode).
 *
 * Slugs are constrained to `[a-z0-9-]+` (lowercase kebab) to keep file
 * paths sane downstream. Topics / keys / sections allow any non-empty
 * string (free-form for the LLM's voice) but get trimmed.
 *
 * Empty / whitespace-only inputs return `null`. `undefined` returns
 * `null`. Both are surfaced by the caller as a rejected subject.
 */
export declare function parseFindingSubject(raw: string | null | undefined): FindingSubject | null;
/**
 * Render the parsed subject back to its canonical string form. Inverse
 * of `parseFindingSubject`; useful when the substrate constructs new
 * findings programmatically (e.g. for tests, replays, or
 * `id_basis` carry-forward).
 */
export declare function renderFindingSubject(s: FindingSubject): string;
/**
 * The grammar text embedded into kind actor prompts. Kinds opt into
 * the subset of variants they emit (e.g. `improvement` excludes the
 * cluster variant; `failure-mode` includes ONLY the cluster variant).
 *
 * Drift between prompt and parser is impossible: every kind imports
 * this constant + the matching `expects` set, and the unit tests below
 * lock the table to the parser.
 */
export declare const FINDING_SUBJECT_GRAMMAR_PROMPT: string;
/**
 * The variants each kind is allowed to emit. Used at the kind factory
 * boundary so a knowledge-gap finding can't sneak in a `system-prompt:*`
 * subject (the improvement-analyst's job) and vice versa.
 *
 * `failure-mode` is restricted to `cluster` — the only kind that emits
 * a non-locus subject.
 */
export declare const KIND_EXPECTED_SUBJECTS: Record<string, ReadonlyArray<FindingSubjectKind>>;
/**
 * Zod schema that validates a raw subject string and returns the parsed
 * `FindingSubject`. Embedded in `RawAnalystFindingSchema` via
 * `transform`, so `subject` arrives at the kind factory either as a
 * typed locus or as a parse error attached to a single Zod issue.
 *
 * Optionality is preserved: subjects ARE optional on the wire (some
 * findings are descriptive, not actionable). When present, they MUST
 * parse — emitting a malformed subject is a contract violation, not a
 * soft signal.
 */
export declare const FindingSubjectStringSchema: z.ZodString;
//# sourceMappingURL=finding-subject.d.ts.map