npm - @agentproto/corpus - Versions diffs - 0.1.0-alpha.1 - Mend

@agentproto/corpus 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/LICENSE +21 -0
package/README.md +30 -0
package/dist/chunk-KYX2DTEH.mjs +14 -0
package/dist/chunk-KYX2DTEH.mjs.map +1 -0
package/dist/chunk-UPX26MYH.mjs +104 -0
package/dist/chunk-UPX26MYH.mjs.map +1 -0
package/dist/index.d.ts +2893 -0
package/dist/index.mjs +3380 -0
package/dist/index.mjs.map +1 -0
package/dist/ports/index.d.ts +205 -0
package/dist/ports/index.mjs +3 -0
package/dist/ports/index.mjs.map +1 -0
package/dist/sidecar-TTWQD5R3.mjs +3 -0
package/dist/sidecar-TTWQD5R3.mjs.map +1 -0
package/package.json +80 -0

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,2893 @@
+import { FsPort, ClockPort, IdentityPort, FetcherPort, FsStat, FsLockHandle, EvalRubricPort, EvalContextPort, EvaluatorPort } from './ports/index.js';
+export { CallerIdentity, EvalInputPort, EvalResultPort, FetchedSource, FetchedSourceKind, systemClock } from './ports/index.js';
+import { z } from 'zod';
+import { Registry } from '@agentproto/registry';
+/**
+ * AIP-10 slug helpers — the single source of truth for turning arbitrary
+ * text or paths into schema-valid slugs. Replaces the three drifted
+ * `makeSlug` copies (web / local-files / distill importers) and the two
+ * `uniqueSlug` copies, so a rule change lands once instead of in four
+ * places.
+ *
+ * Two AIP-10 slug shapes:
+ *   - **source** id `^[a-z0-9][a-z0-9-]*$` — a leading digit is allowed.
+ *   - **entry / role / tag** id `^[a-z][a-z0-9-]*[a-z0-9]$` — must start
+ *     with a letter and end alphanumeric. Pass `leadingLetter: true`.
+ */
+interface SlugifyOptions {
+    /** Max length before the trailing-dash trim. Default 96. */
+    readonly maxLen?: number;
+    /** Returned when the slugified result is empty / degenerate. Default "item". */
+    readonly fallback?: string;
+    /**
+     * Guarantee the AIP-10 *entry* shape: a leading letter (prefix `e-` when
+     * the slug would otherwise start with a digit) and length ≥ 2.
+     */
+    readonly leadingLetter?: boolean;
+    /** Strip a leading `http(s)://` first — for slugging a URL fallback. */
+    readonly stripScheme?: boolean;
+}
+/** Slugify arbitrary text into an AIP-10-valid id. */
+declare function slugify(input: string, opts?: SlugifyOptions): string;
+/**
+ * Disambiguate a slug against a set of already-used ones by appending
+ * `-2`, `-3`, … The suffix is numeric, so an entry-shaped base stays
+ * entry-valid (ends alphanumeric).
+ */
+declare function uniqueSlug(base: string, seen: Set<string>, maxLen?: number): string;
+/** True when `s` is a valid AIP-10 source id (leading digit allowed). */
+declare function isSourceSlug(s: string): boolean;
+/** True when `s` is a valid AIP-10 entry/role/tag id (leading letter). */
+declare function isEntrySlug(s: string): boolean;
+/**
+ * Language-tag normalization — the single source of truth for coercing a
+ * raw language value into the AIP-10 source shape `^[a-z]{2}(-[A-Z]{2})?$`.
+ *
+ * Two upstreams feed it, which is why this used to be two drifted copies:
+ *   - **STT** (Whisper verbose_json) emits a full English NAME ("english",
+ *     "french").
+ *   - **readability / browser** fetchers read `<html lang>` VERBATIM, in any
+ *     case and separator ("en-us", "EN", "pt_BR", "zh-Hant-TW").
+ *
+ * One function handles both: map a known name → code, else parse a BCP-47
+ * tag — lowercase the 2-letter primary, uppercase a genuine 2-letter region,
+ * and discard scripts / extensions / 3-letter primaries (which the AIP-10
+ * source schema doesn't allow) rather than emit something that fails
+ * validation. Returns `undefined` for anything unparseable so the field is
+ * omitted, never written invalid.
+ */
+declare function normalizeLanguageTag(raw: string | undefined): string | undefined;
+/**
+ * @agentproto/corpus — public types.
+ *
+ * Frontmatter shapes here are deliberately loose (`Record<string,
+ * unknown>`). Strict validation lives in `validate/validator.ts` —
+ * keeping the reader weakly-typed lets it surface drift through the
+ * validator's structured errors rather than failing on parse.
+ */
+type FileKind = "knowledge-workspace" | "knowledge-source" | "knowledge-entry" | "collection-schema" | "collection-item" | "playbook" | "operator" | "workflow" | "routine" | "unknown";
+interface ParsedFile {
+    /** Workspace-relative path (e.g. "entries/principles/2026/foo.md"). */
+    readonly path: string;
+    /** Classification by location. */
+    readonly kind: FileKind;
+    /** Parsed YAML frontmatter. Empty object if frontmatter is missing. */
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    /** Markdown body (everything after the closing `---`). */
+    readonly body: string;
+    /** SHA-256 of the entire file contents — used as optimistic-concurrency versionToken. */
+    readonly versionToken: string;
+}
+interface CorpusWorkspaceSnapshot {
+    /** Root path passed to the reader (relative or absolute, host's choice). */
+    readonly root: string;
+    /** The KNOWLEDGE.md file, if found. */
+    readonly workspace: ParsedFile | null;
+    readonly sources: readonly ParsedFile[];
+    readonly entries: readonly ParsedFile[];
+    readonly collections: readonly ParsedFile[];
+    readonly collectionItems: readonly ParsedFile[];
+    readonly playbooks: readonly ParsedFile[];
+    readonly operators: readonly ParsedFile[];
+    readonly workflows: readonly ParsedFile[];
+    readonly routines: readonly ParsedFile[];
+    /** .md files we found but couldn't classify. */
+    readonly unknown: readonly ParsedFile[];
+}
+/** Validator result per file, returned by `validate/validator.ts`. */
+interface ValidationIssue {
+    readonly path: string;
+    readonly instancePath: string;
+    readonly message: string;
+    readonly severity: "error" | "warn" | "info";
+}
+interface ValidationResult {
+    readonly issues: readonly ValidationIssue[];
+    readonly valid: boolean;
+}
+/** Lint result, returned by `validate/linter.ts`. */
+interface LintIssue {
+    readonly lintId: string;
+    readonly path: string;
+    readonly message: string;
+    readonly severity: "error" | "warn" | "info";
+}
+interface LintReport {
+    readonly issues: readonly LintIssue[];
+    readonly errorCount: number;
+    readonly warnCount: number;
+    readonly infoCount: number;
+}
+/** Event taxonomy emitted by the corpus to `_log.md`. */
+type CorpusEventKind = "corpus.candidate.discovered" | "corpus.candidate.analyzed" | "corpus.candidate.approved" | "corpus.candidate.rejected" | "corpus.candidate.needs_work" | "corpus.entry.promoted" | "corpus.entry.deprecated" | "corpus.entry.archived" | "corpus.gap.opened" | "corpus.gap.resolved" | "playbook.shadow.registered" | "playbook.activated" | "playbook.archived";
+interface CorpusEvent {
+    readonly kind: CorpusEventKind;
+    readonly at: string;
+    readonly actor: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+/**
+ * Per-state-transition attestation stored under
+ * `metadata.corpus.attestations[]` on entries, candidates, and
+ * playbooks. The audit chain that `_log.md` rolls up.
+ *
+ * `model` + `promptHash` are recorded when an AI agent produced the
+ * transition (analyzed by analyst-bot, scored by reviewer-bot, …).
+ * Human-driven transitions omit them. `signature` is reserved for
+ * AIP-23 signing once the identity infra is wired — until then it
+ * stays optional and the chain relies on principal + at + hash.
+ */
+type AttestationKind = "created" | "analyzed" | "reviewed" | "promoted" | "deprecated" | "archived" | "activated" | "evaluated" | "imported" | "tombstoned";
+interface Attestation {
+    readonly kind: AttestationKind;
+    /** AIP-23-style identity ref. e.g. "ws://operators/corpus-curator". */
+    readonly identity: string;
+    readonly at: string;
+    /** Optional model id for AI-produced transitions. */
+    readonly model?: string;
+    /** Optional sha256 of the prompt + system prompt used. */
+    readonly promptHash?: string;
+    /** Optional signature (AIP-23). Reserved until identity infra lands. */
+    readonly signature?: string;
+    /** Free-form note — appears in curator UI tooltips. */
+    readonly note?: string;
+}
+/**
+ * A reusable corpus starter — pure TS data, no filesystem dependency.
+ *
+ * Follows the @agentproto/role-catalog pattern: a preset is a
+ * declarative bundle of file paths → file contents that a host writes
+ * to a target workspace via the FsPort. The kit defines the
+ * interface; individual packages under `@agentproto/corpus-presets/*`
+ * ship per-vertical content.
+ *
+ * `files` keys are workspace-relative paths (no leading slash). The
+ * host (e.g. corpus-cli's `init` command, or any embedding runtime)
+ * is responsible for iterating + writing via FsPort.
+ */
+interface CorpusPreset {
+    readonly slug: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly files: Readonly<Record<string, string>>;
+    /**
+     * Optional bootstrap hook. Hosts that need to do more than write
+     * files (e.g. seed _candidates.yaml sidecar, register a KB row)
+     * implement this. The default `init` flow just writes `files`.
+     */
+    readonly bootstrap?: (ctx: CorpusPresetBootstrapContext) => Promise<void>;
+}
+interface CorpusPresetBootstrapContext {
+    /** Workspace root within whatever fs the host has handed us. */
+    readonly workspacePath: string;
+    /**
+     * Write a single file relative to workspacePath. Implementations
+     * typically just call FsPort.writeFile. Exposed as a callback so
+     * the preset doesn't need to import FsPort directly (keeps presets
+     * minimally typed).
+     */
+    readonly write: (relativePath: string, content: string) => Promise<void>;
+}
+/**
+ * Attestation helpers — append + read the per-transition audit chain
+ * stored under `metadata.corpus.attestations[]`.
+ *
+ * Pure. The lifecycle workflows (promote, playbook activate/archive,
+ * playbook evaluator) call `appendAttestation` immediately before
+ * writing the file. Tooling that displays the chain (curator UI,
+ * `corpus events:trace <slug>`) calls `readAttestations`.
+ */
+/**
+ * Append an attestation to a frontmatter object's
+ * `metadata.corpus.attestations[]`. Returns a NEW frontmatter
+ * object — mutation-free so callers can chain transformations.
+ *
+ * If `metadata.corpus.attestations` doesn't exist, it's created. If
+ * the new attestation is byte-identical to the last entry (same kind
+ * + identity + at), it's a no-op (idempotent against
+ * lifecycle workflow retries).
+ */
+declare function appendAttestation(frontmatter: Readonly<Record<string, unknown>>, attestation: Attestation): Record<string, unknown>;
+/**
+ * Read the attestation chain off a frontmatter object. Returns `[]`
+ * if the entry has none (e.g. legacy entries written before the
+ * attestation chain shipped).
+ */
+declare function readAttestations(frontmatter: Readonly<Record<string, unknown>>): readonly Attestation[];
+/**
+ * Convenience: build an attestation from current clock + identity.
+ * Lifecycle code typically calls this then immediately
+ * `appendAttestation`.
+ */
+declare function makeAttestation(input: {
+    readonly kind: Attestation["kind"];
+    readonly identity: string;
+    readonly at: string;
+    readonly model?: string;
+    readonly promptHash?: string;
+    readonly note?: string;
+}): Attestation;
+/**
+ * Access policy — pure logic that decides whether a caller can see a
+ * piece of corpus content based on its `metadata.corpus.access` spec.
+ *
+ * Inputs:
+ *   spec    — what the entry/source declares (classification + allowed refs)
+ *   caller  — identityTree (resolved by IdentityPort)
+ *
+ * Output:
+ *   permitted: boolean
+ *   reason: human-readable
+ *   redact: bytes-redaction hint for getSource() (some classifications
+ *           let the caller see metadata but not body bytes)
+ *
+ * Default policy by classification:
+ *
+ *   public      — anyone can see (and read bytes)
+ *   internal    — same-guild only (default for unmarked entries)
+ *   restricted  — explicit allowedRoles / allowedOperators / allowedUsers
+ *                 ONLY; classification fallback is deny
+ *   secret      — same as restricted PLUS bytes are redacted for
+ *                 callers below the bar (they see frontmatter, not body)
+ *
+ * Engines/UIs filter silently — no "you have N results but can't see
+ * them" leakage to the caller below.
+ */
+type AccessClassification = "public" | "internal" | "restricted" | "secret";
+interface CorpusAccessSpec {
+    readonly classification?: AccessClassification;
+    readonly allowedRoles?: readonly string[];
+    readonly allowedOperators?: readonly string[];
+    readonly allowedUsers?: readonly string[];
+    readonly allowedGuilds?: readonly string[];
+    readonly allowedOrgs?: readonly string[];
+    /** Free-form host extension. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface AccessCaller {
+    /** identityTree most-specific → least-specific. */
+    readonly identityTree: readonly string[];
+}
+/**
+ * Per-evaluation context the adapter passes alongside the caller.
+ * Distinct from the spec (entry-side) and the caller (subject-side);
+ * this carries the *workspace-side* facts that classification rules
+ * need but that the entry doesn't repeat per-row.
+ */
+interface AccessContext {
+    /**
+     * Guild slug that owns the workspace this entry lives in (e.g.
+     * "acme-marketing"). When set, the `internal` classification
+     * requires the caller's identityTree to include
+     * `ws://guilds/<homeGuild>` — i.e. an entry tagged internal is
+     * visible only to that guild, not to anyone-in-any-guild.
+     *
+     * When omitted, `internal` falls back to "fail-closed" rather than
+     * the old "any-guild" semantics, on the principle that an
+     * unidentifiable workspace shouldn't leak its content.
+     */
+    readonly homeGuild?: string;
+}
+interface AccessDecision {
+    readonly permitted: boolean;
+    readonly reason: string;
+    /** For getSource — true means body bytes MUST be redacted. */
+    readonly redactBytes: boolean;
+}
+/**
+ * Evaluate access for a caller against an access spec. Returns a
+ * decision the caller (engine adapter, tool) uses to filter / redact.
+ *
+ * Missing `access` block in frontmatter = treat as `classification:
+ * internal`, no explicit allow lists. Same-guild matches via the
+ * identityTree.
+ */
+declare function evaluateAccess(spec: CorpusAccessSpec | undefined, caller: AccessCaller, context?: AccessContext): AccessDecision;
+/**
+ * Extract the access spec from a frontmatter object's
+ * `metadata.corpus.access`. Returns undefined when the entry has
+ * none — caller treats it as `internal` (the default).
+ */
+declare function readAccessSpec(frontmatter: Readonly<Record<string, unknown>>): CorpusAccessSpec | undefined;
+/**
+ * Capability — uniform tool-boundary enforcement.
+ *
+ * Every corpus tool declares a required `Capability`. The host
+ * (Guilde corpus.bundle / corpus-cli) calls `evaluateCapability` at
+ * dispatch time. Capabilities are configured per-workspace under
+ * `KNOWLEDGE.md.metadata.corpus.accessModes`.
+ *
+ * Pure logic. Audit + actual rejection happen in the host.
+ */
+type Capability = "read" | "cite" | "flag-learning" | "curate" | "promote" | "activate-playbook" | "admin-reindex" | "bypass-default-filters";
+interface CapabilityRule {
+    readonly allowedRoles: readonly string[];
+    /** Optional rate-limit hint — enforcement lives in the host. */
+    readonly rateLimit?: {
+        readonly perOperator?: number;
+        readonly window?: string;
+    };
+    /** Requires curator approval before the action commits. */
+    readonly requireApproval?: boolean;
+    /** Audit-log the call (default false). */
+    readonly audit?: boolean;
+}
+type AccessModesMap = Readonly<Partial<Record<Capability, CapabilityRule>>>;
+interface CapabilityCaller {
+    /** identityTree most-specific → least-specific. */
+    readonly identityTree: readonly string[];
+}
+interface CapabilityDecision {
+    readonly permitted: boolean;
+    readonly reason: string;
+    /** Rate-limit hint to enforce, if defined. */
+    readonly rateLimit?: CapabilityRule["rateLimit"];
+    /** True if the tool MUST collect approval before committing. */
+    readonly requireApproval: boolean;
+    /** True if the host should write an audit entry on completion. */
+    readonly audit: boolean;
+}
+declare function evaluateCapability(capability: Capability, accessModes: AccessModesMap | undefined, caller: CapabilityCaller): CapabilityDecision;
+/**
+ * Read accessModes from a parsed KNOWLEDGE.md workspace
+ * frontmatter. Returns undefined if not declared — caller uses
+ * DEFAULT_RULES.
+ */
+declare function readAccessModes(workspaceFrontmatter: Readonly<Record<string, unknown>>): AccessModesMap | undefined;
+/**
+ * Language filtering — pure helpers for BCP-47 locale matching.
+ *
+ * Where language lives:
+ *   - AIP-10 source: native top-level `language` field (already in spec).
+ *   - AIP-10 entry: under `metadata.corpus.language` until the AIP-10
+ *     spec hoists `language` to first-class on entries.
+ *   - Workspace default: `KNOWLEDGE.md.metadata.corpus.languages.default`.
+ *   - Operator locale: `OPERATOR.md.metadata.corpus.locale`.
+ *
+ * Default filter: an entry surfaces to an operator if its language
+ * matches the operator's locale OR matches the workspace default
+ * (typically en-US so generic principles aren't locale-gated). Empty
+ * `language` on the entry = treat as the workspace default (it's
+ * almost always the corpus's home language).
+ *
+ * Locale matching is loose (`en` matches `en-US` / `en-GB`) so we
+ * don't drown the user in misses on regional variants.
+ */
+interface ResolveLanguageFilterInput {
+    /** BCP-47 locale the caller is operating in. */
+    readonly callerLocale?: string;
+    /**
+     * Default language declared in `KNOWLEDGE.md.metadata.corpus.languages.default`.
+     * Used as the implicit language for entries that don't declare one.
+     */
+    readonly workspaceDefaultLanguage?: string;
+}
+interface LanguageFilter {
+    /**
+     * The set of language codes that surface. Used by middleware to
+     * filter hits silently. Empty set = no language filter (everyone
+     * sees everything; happens when neither caller nor workspace
+     * declares a language).
+     */
+    readonly allowedLanguages: ReadonlySet<string>;
+    /**
+     * Whether entries with no declared language should pass through.
+     * True when the workspace declares a default — those entries
+     * inherit it.
+     */
+    readonly allowUnspecified: boolean;
+}
+declare function resolveLanguageFilter(input: ResolveLanguageFilterInput): LanguageFilter;
+declare function matchesLanguageFilter(entryLanguage: string | undefined, filter: LanguageFilter): boolean;
+/**
+ * Convenience: read the operator's locale from frontmatter.
+ * Falls back to undefined when not declared.
+ */
+declare function readOperatorLocale(operatorFrontmatter: Readonly<Record<string, unknown>>): string | undefined;
+/**
+ * Read the workspace's default language from KNOWLEDGE.md.
+ */
+declare function readWorkspaceDefaultLanguage(workspaceFrontmatter: Readonly<Record<string, unknown>>): string | undefined;
+/**
+ * Read an entry / source's language. Sources expose it at top level
+ * (AIP-10 spec); entries put it under `metadata.corpus.language`
+ * until the corresponding AIP-10 amendment lands.
+ */
+declare function readEntryLanguage(frontmatter: Readonly<Record<string, unknown>>): string | undefined;
+/**
+ * CandidatesSidecar — accessor for `collections/<name>/_candidates.yaml`.
+ *
+ * The plan calls out lazy materialization (so-so #6): the
+ * "discovered" state has high volume and short lifespan; AIP-18 ITEM
+ * files only materialize when a candidate transitions to `analyzed`.
+ * Until then, candidates live in a YAML sidecar keyed by id.
+ *
+ * Sidecar shape:
+ *   candidates:
+ *     - id: <slug>
+ *       status: discovered   # may also be transitioning (rare)
+ *       sourceUrl: ...       # collection-specific fields are free-form
+ *       contentHash: ...
+ *       discoveredAt: ISO
+ *       discoveredBy: ws://operators/<slug>
+ *
+ * The accessor enforces:
+ *   - id uniqueness within the file
+ *   - atomic full-file writes (no partial sidecar)
+ *   - status transition discipline (a row stays here only while
+ *     `status === "discovered"`; transitions out remove the row and
+ *     return the data so the caller can materialize ITEM.md)
+ */
+interface CandidateRow {
+    readonly id: string;
+    readonly status: "discovered" | string;
+    /** Open-ended — collection schema's `fields` defines what's allowed. */
+    readonly [key: string]: unknown;
+}
+interface CandidatesSidecarOptions {
+    readonly fs: FsPort;
+    /** Workspace-relative path of the sidecar file. */
+    readonly path: string;
+}
+declare class CandidatesSidecar {
+    private readonly opts;
+    constructor(opts: CandidatesSidecarOptions);
+    /**
+     * Load every row from disk. Returns an empty list if the file
+     * doesn't exist (a fresh corpus has no candidates yet).
+     */
+    load(): Promise<readonly CandidateRow[]>;
+    /**
+     * Append a new candidate. Refuses if `id` already exists — sidecar
+     * keys are unique. Returns the full updated list.
+     */
+    append(row: CandidateRow): Promise<readonly CandidateRow[]>;
+    /**
+     * Mutate one row in-place. Throws if not found.
+     */
+    update(id: string, patch: Readonly<Record<string, unknown>>): Promise<CandidateRow>;
+    /**
+     * Remove a row by id. Returns the removed row so the caller can
+     * materialize an ITEM.md from its fields. Throws if not found.
+     *
+     * Use this when a candidate transitions out of `discovered`: pull
+     * it from the sidecar, write the ITEM.md, append an event.
+     */
+    take(id: string): Promise<CandidateRow>;
+    /**
+     * Whole-file replace. Used in tests and by the indexer for
+     * bulk migrations. Prefer append/update/take for normal flow.
+     */
+    write(candidates: readonly CandidateRow[]): Promise<void>;
+}
+declare class SidecarDuplicateError extends Error {
+    readonly path: string;
+    readonly id: string;
+    constructor(path: string, id: string);
+}
+declare class SidecarNotFoundError extends Error {
+    readonly path: string;
+    readonly id: string;
+    constructor(path: string, id: string);
+}
+/**
+ * CorpusImporter — pluggable bootstrap contract.
+ *
+ * Real corpora are rarely born from blank fixtures — they come from
+ * Notion workspaces, Drive folders, web crawls, PDFs, internal docs,
+ * existing knowledge bases. Importers are how a corpus gets seeded
+ * from reality without hand-authoring every file.
+ *
+ * The pattern is symmetric with IKnowledgeProvider / IEvaluator:
+ *   1. Kit (this package) ships the contract + a reference impl
+ *      (`LocalFilesImporter`).
+ *   2. Adapter packages (Notion, Drive, web-crawl, …) implement the
+ *      contract via their own SDKs/HTTP layer.
+ *   3. The host (Guilde corpus-host) wires a registry + dispatch.
+ *
+ * Importers write to two places, atomically per source:
+ *   - `sources/<importer-id>/<batch>/<slug>.md`  — archived AIP-10 source
+ *   - `_candidates.yaml`                          — discovered candidate row
+ *
+ * Both writes go through CorpusWorkspaceWriter so versionToken /
+ * transaction-lock semantics hold the same way as the rest of the
+ * corpus lifecycle.
+ */
+interface ImporterTarget {
+    /**
+     * Stable importer instance id. Allows the same importer adapter to
+     * run multiple times against different sources (e.g. two distinct
+     * Notion workspaces). Reflected in the archive path:
+     * `sources/<importerId>/<batch>/`.
+     */
+    readonly importerId: string;
+    /** Optional batch id — defaults to ISO timestamp on first archive. */
+    readonly batchId?: string;
+    /** Importer-specific configuration (auth tokens, source spec, filters). */
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/**
+ * One source unit the importer produces. The host writes this to
+ * `sources/<importerId>/<batchId>/<slug>.md` as AIP-10 frontmatter +
+ * body, and appends a row to `_candidates.yaml`.
+ */
+interface ImportedSource {
+    /** Stable kebab-case slug for the source. */
+    readonly slug: string;
+    /** Human-readable title. */
+    readonly title: string;
+    /** sha256-prefixed content hash (importer responsibility — dedup gate). */
+    readonly contentHash: string;
+    /** Source body (markdown). */
+    readonly body: string;
+    /** Optional original URL. */
+    readonly originalUrl?: string;
+    /** AIP-10 authority class. */
+    readonly authority?: "primary" | "secondary" | "rumour";
+    /** BCP-47 language code — drives the locale-matching retrieval filter. */
+    readonly language?: string;
+    readonly tags?: readonly string[];
+    /** Vendor extension fields go under metadata.corpus.* on the source frontmatter. */
+    readonly corpusMetadata?: Readonly<Record<string, unknown>>;
+}
+interface BatchReport {
+    /** Importer that produced the batch. */
+    readonly importerId: string;
+    readonly batchId: string;
+    /** Sources archived this run. */
+    readonly archivedSlugs: readonly string[];
+    /** Sources skipped because contentHash already exists. */
+    readonly duplicateSlugs: readonly string[];
+    /** Candidate ids written to _candidates.yaml. */
+    readonly candidateIds: readonly string[];
+    /** Diagnostic messages (non-fatal warnings, dedup reasons, etc.). */
+    readonly warnings: readonly string[];
+}
+/**
+ * The contract concrete importers implement. Two methods:
+ *   - `enumerate(target)` — yields ImportedSource objects.
+ *     Caller iterates + decides what to do with each (run dedup,
+ *     archive, append).
+ *
+ * The kit ships the "what to do with each" logic in
+ * `ImporterRunner` — concrete importers focus ONLY on producing
+ * `ImportedSource` from their data source.
+ */
+interface CorpusImporter {
+    /** Stable id, e.g. "local-files", "notion", "drive", "web-crawl". */
+    readonly id: string;
+    /** Brief human-readable label (UI metadata). */
+    readonly label: string;
+    /**
+     * Yield sources for the configured target. Async iterator so the
+     * host can stream + back-pressure on large imports. Each source
+     * carries everything the runner needs to archive + materialize a
+     * candidate.
+     */
+    enumerate(target: ImporterTarget): AsyncIterable<ImportedSource>;
+}
+interface ImporterRunnerOptions {
+    /**
+     * Build the candidate row from an ImportedSource. Lets callers
+     * customize the corpusKind heuristic + add app-specific fields.
+     * Default: maps to `corpusKind: "example"`.
+     */
+    readonly toCandidate?: (s: ImportedSource, sourceId: string) => CandidateRow;
+}
+/**
+ * ImporterRunner — drives a CorpusImporter to actually land files
+ * + candidate rows in the workspace.
+ *
+ * Importers themselves are pure source-of-data — they yield
+ * `ImportedSource`. The runner is where I/O lives: archives sources
+ * to `sources/<importerId>/<batchId>/`, appends `_candidates.yaml`
+ * rows, dedups against existing sources by `content_hash`, emits a
+ * `corpus.candidate.discovered` event per imported source.
+ *
+ * Same fs+writer+emitter pattern as the rest of the corpus lifecycle.
+ */
+declare class ImporterRunner {
+    private readonly opts;
+    constructor(opts: {
+        readonly fs: FsPort;
+        readonly clock: ClockPort;
+        readonly identity: IdentityPort;
+        readonly workspacePath: string;
+        readonly runner?: ImporterRunnerOptions;
+    });
+    /**
+     * Run a single importer batch end-to-end.
+     *
+     *   1. Pre-load existing source content_hashes for dedup.
+     *   2. For each source the importer yields:
+     *      a. Skip if hash already exists in the workspace.
+     *      b. Otherwise write AIP-10 source frontmatter + body to
+     *         `sources/<importerId>/<batchId>/<slug>.md`.
+     *      c. Append candidate row to `_candidates.yaml`.
+     *   3. Emit `corpus.candidate.discovered` per archived source.
+     *
+     * Atomic per-source (each source archived + candidate written
+     * inside one writer.transaction).
+     */
+    run(importer: CorpusImporter, target: ImporterTarget): Promise<BatchReport>;
+}
+/**
+ * LocalFilesImporter — reads .md files from a configured FsPort path
+ * and yields them as ImportedSource. Reference implementation that
+ * proves the importer surface end-to-end without external SDKs.
+ *
+ * Config (target.config):
+ *   - rootPath: string             — workspace-relative path to scan
+ *   - extensions?: string[]        — defaults to [".md"]
+ *   - maxFiles?: number            — defaults to 1000
+ *   - tags?: string[]              — applied to every imported source
+ *   - language?: string            — applied to every source (BCP-47)
+ *
+ * Pure kit code — consumes FsPort, no node:fs / no network.
+ *
+ * Slug derivation: filename without extension, lowercased + slug-safed.
+ * Content hash: sha256 of UTF-8 body bytes.
+ */
+interface LocalFilesImporterOptions {
+    readonly fs: FsPort;
+}
+declare class LocalFilesImporter implements CorpusImporter {
+    private readonly opts;
+    readonly id = "local-files";
+    readonly label = "Local Files";
+    constructor(opts: LocalFilesImporterOptions);
+    enumerate(target: ImporterTarget): AsyncIterable<ImportedSource>;
+}
+/**
+ * KbMigrationImporter — turn an existing knowledge base into a
+ * stream of `ImportedSource` for the runner.
+ *
+ * Use case: a guild already has a populated qdrant/gbrain KB row
+ * with N documents. Day-1 corpus onboarding shouldn't be "abandon
+ * your knowledge and start over" — this importer reads the source
+ * KB via its IKnowledgeProvider, materializes each source as an
+ * importable, and the runner archives them into `sources/` +
+ * appends candidates. The source KB stays intact (read-only).
+ *
+ * The minimal IKnowledgeProvider-like shape we consume — keeps the
+ * kit decoupled from @agstudio/integration-knowledge.
+ *
+ * Each migrated source carries `provenanceKind: imported-from-kb`
+ * and `sourceKbId` in `metadata.corpus` so curators can trace which
+ * KB row each item came from.
+ */
+/**
+ * Structural shape — any IKnowledgeProvider satisfies it. We don't
+ * import IKnowledgeProvider directly to keep the kit dep-free.
+ */
+interface KbListLike {
+    listSources(): Promise<readonly KbSourceLike[]>;
+}
+interface KbSourceLike {
+    readonly id: string;
+    readonly kind: string;
+    readonly uri: string;
+    readonly title?: string;
+    readonly bytes: number;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+interface KbMigrationConfig {
+    /** Stable id of the source KB (used in provenance + archive path). */
+    readonly sourceKbId: string;
+    /** Live provider instance from the source KB. */
+    readonly provider: KbListLike;
+    /**
+     * Optional fetcher for the body of each source. The migration
+     * importer enumerates source METADATA from listSources(); to
+     * archive the actual content, the host must supply a way to fetch
+     * the body. If omitted, sources are imported with an empty body +
+     * a note pointing back to the source KB.
+     */
+    readonly fetchBody?: (sourceId: string) => Promise<string>;
+    /** Optional max sources to import this batch. */
+    readonly maxSources?: number;
+}
+declare class KbMigrationImporter implements CorpusImporter {
+    readonly id = "kb-migration";
+    readonly label = "Migrate from existing KB";
+    enumerate(target: ImporterTarget): AsyncIterable<ImportedSource>;
+}
+/**
+ * WebImporter — turns a list of URLs into corpus sources by reducing
+ * each to text through an injected FetcherPort. The importer is pure:
+ * it slugs, hashes, and shapes ImportedSource; the FetcherPort supplies
+ * the environment-bound "URL → { title, text }" capability (YouTube
+ * captions, article readability, or — at a fatter tier — transcription).
+ *
+ * Config (target.config):
+ *   - urls: string[]          — required. The source URLs to import.
+ *   - maxUrls?: number        — defaults to 1000.
+ *   - tags?: string[]         — applied to every imported source.
+ *   - language?: string       — fallback BCP-47 when the fetcher omits one.
+ *
+ * A URL the fetcher returns `null` for (e.g. a caption-less video on a
+ * non-transcribing tier) is skipped — the runner records it as a
+ * warning rather than aborting the batch.
+ *
+ * Pure kit code — consumes FetcherPort, no node:fs / no network of its
+ * own. Slug: derived from title, else the URL. Hash: sha256 of the text.
+ */
+interface WebImporterOptions {
+    readonly fetcher: FetcherPort;
+}
+declare class WebImporter implements CorpusImporter {
+    private readonly opts;
+    readonly id = "web";
+    readonly label = "Web (URLs)";
+    constructor(opts: WebImporterOptions);
+    enumerate(target: ImporterTarget): AsyncIterable<ImportedSource>;
+}
+/**
+ * ConversationSourcePort — the "conversation ref → turns" boundary the
+ * ConversationImporter consumes. Symmetric with FetcherPort (URL → text):
+ * it keeps the importer PURE and chat-store-agnostic. The importer decides
+ * *what* to import (windowing, transcript shape, dedup hash); the port supplies
+ * the one capability that is environment-bound — resolving a conversation
+ * reference to its turns, wherever they live.
+ *
+ * Structural interface, NOT nominal — any object of this shape satisfies it.
+ * Concrete implementations live where the messages live:
+ *
+ *   - a companion app over its Mastra thread store (per-user threads),
+ *   - a guild runtime over its conversation log,
+ *   - a fake (tests): canned turns per ref.
+ *
+ * Returning `null` lets the importer skip-with-warning rather than abort the
+ * batch; throwing is reserved for hard failures (auth, store unreachable).
+ */
+/** One turn in a conversation. */
+interface ConversationTurn {
+    /** Free-form speaker role — "user" | "assistant" | "system" | a name. */
+    readonly role: string;
+    /** The turn's text, already flattened to plain text by the port. */
+    readonly text: string;
+    /** ISO-8601 timestamp, when known — for provenance + window ordering. */
+    readonly at?: string;
+}
+/**
+ * One resolved slice of conversation — the raw material a ConversationImporter
+ * turns into a `knowledge.source`.
+ */
+interface ConversationDoc {
+    /**
+     * Stable id for THIS slice — becomes the source slug base and the `sources:`
+     * provenance ref. Chat is append-only, so for incremental distill the host
+     * encodes the window here (e.g. `thread-123-2026-06-06`): a growing
+     * conversation then yields a distinct source per window instead of colliding
+     * on one immutable slug.
+     */
+    readonly id: string;
+    /** Human-readable title, when the store has one. */
+    readonly title?: string;
+    /** The turns in chronological order. */
+    readonly turns: readonly ConversationTurn[];
+    /** BCP-47 language hint, when the store knows it. */
+    readonly language?: string;
+}
+interface ConversationSourcePort {
+    /** Resolve a conversation reference to its turns, or null to skip it. */
+    fetchConversation(ref: string): Promise<ConversationDoc | null>;
+}
+/**
+ * ConversationImporter — turns conversations into corpus sources by rendering
+ * each to a transcript through an injected ConversationSourcePort. The importer
+ * is pure: it slugs, hashes, and shapes ImportedSource; the port supplies the
+ * environment-bound "ref → turns" capability (a Mastra thread store, a chat DB).
+ *
+ * This is the seam for conversation→knowledge distill — the resulting sources
+ * feed DistillRunner exactly like web sources do (the pipeline is provenance-
+ * agnostic). Chat is append-only, so a single immutable slug per conversation
+ * would collide once new turns arrive; the host handles this by WINDOWING —
+ * giving each ConversationDoc a window-unique id (e.g. `<thread>-<date>`), so
+ * each window distills once and a daily run only sees fresh windows.
+ *
+ * Config (target.config):
+ *   - refs: string[]                              — required. Refs to resolve.
+ *   - tags?: string[]                             — applied to every source.
+ *   - language?: string                           — fallback BCP-47.
+ *   - authority?: "primary"|"secondary"|"rumour"  — default "secondary".
+ *   - maxRefs?: number                            — defaults to 1000.
+ *
+ * Pure kit code — consumes ConversationSourcePort, no chat-store dependency.
+ * Slug: derived from the doc id. Hash: sha256 of the rendered transcript, so
+ * an unchanged window re-import dedups in ImporterRunner.
+ */
+interface ConversationImporterOptions {
+    readonly source: ConversationSourcePort;
+}
+declare class ConversationImporter implements CorpusImporter {
+    private readonly opts;
+    readonly id = "conversation";
+    readonly label = "Conversation";
+    constructor(opts: ConversationImporterOptions);
+    enumerate(target: ImporterTarget): AsyncIterable<ImportedSource>;
+}
+/**
+ * Distill — raw source → refined knowledge entries (the KNOWLEDGE layer).
+ *
+ * The "simple mode": no graph engine. A refined entry is just an AIP-10
+ * `knowledge.entry/v1` markdown file whose `sources: [<id>]` frontmatter
+ * IS the `derivedFrom` provenance edge. The filesystem refs ARE the graph;
+ * a graph engine (mind-graph / gbrain) is an optional index added later.
+ *
+ * The kit owns the contract + the runner (what to write, where, with what
+ * provenance). The LLM that actually extracts insights is an injected
+ * `DistillPort` — host-supplied (Claude/OpenAI), so the kit stays pure.
+ */
+/** Generic AIP-10 refined kinds — NOT domain-specific. */
+declare const REFINED_KIND_SCHEMA: z.ZodEnum<{
+    example: "example";
+    summary: "summary";
+    principle: "principle";
+    pattern: "pattern";
+    critique: "critique";
+}>;
+type RefinedKind = z.infer<typeof REFINED_KIND_SCHEMA>;
+/** Runtime guard — narrows an untyped value to RefinedKind without a cast. */
+declare function isRefinedKind(value: unknown): value is RefinedKind;
+interface DistilledItem {
+    readonly kind: RefinedKind;
+    readonly title: string;
+    /** The refined insight, markdown. Self-contained, not a quote dump. */
+    readonly body: string;
+    /** 0–1 model confidence. */
+    readonly confidence?: number;
+    readonly tags?: readonly string[];
+}
+interface DistillInput {
+    readonly title: string;
+    readonly body: string;
+    readonly tags?: readonly string[];
+    /** Hint for the kinds worth extracting (e.g. only principles). */
+    readonly kinds?: readonly RefinedKind[];
+}
+/**
+ * The LLM boundary. Given a raw source, return refined items. Injected by
+ * the host (corpus-cli `AnthropicDistiller`, a Guilde operator, …) so the
+ * kit takes no model dependency.
+ */
+interface DistillPort {
+    distill(input: DistillInput): Promise<readonly DistilledItem[]>;
+}
+/**
+ * DistillRunner — turn one raw source into refined AIP-10 entries.
+ *
+ * Reads nothing itself beyond what it's handed; writes each distilled item
+ * as `entries/<kind-plural>/<year>/<slug>.md` (layout: "dated", default) or
+ * `entries/<kind-plural>/<slug>.md` (layout: "flat") with `sources: [<sourceId>]`
+ * (the provenance edge) and inherited `access`. Pure: consumes FsPort +
+ * ClockPort + an injected DistillPort. The filesystem refs are the graph.
+ */
+interface DistillSource {
+    /** The raw source's AIP-10 id (becomes the `sources:` provenance ref). */
+    readonly id: string;
+    readonly title: string;
+    readonly body: string;
+    readonly tags?: readonly string[];
+    /** Access scope inherited by every entry distilled from this source. */
+    readonly access?: string;
+    readonly domain?: string;
+}
+interface DistillRunReport {
+    readonly sourceId: string;
+    readonly entryPaths: readonly string[];
+    readonly skipped: readonly string[];
+}
+/** Where distilled entries land under `entries/<kind>/`. */
+type EntryLayout = "dated" | "flat";
+interface DistillRunnerOptions {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly distiller: DistillPort;
+    /**
+     * Entry path layout. "dated" (default) → `entries/<kind>/<year>/<slug>.md`
+     * (scales to large corpora over time); "flat" → `entries/<kind>/<slug>.md`.
+     */
+    readonly layout?: EntryLayout;
+}
+declare class DistillRunner {
+    private readonly opts;
+    constructor(opts: DistillRunnerOptions);
+    run(source: DistillSource): Promise<DistillRunReport>;
+}
+/**
+ * Shared distill prompt + parse — the model-agnostic core of distillation.
+ *
+ * Every DistillPort backend (an HTTP Messages-API distiller, a CLI-agent
+ * distiller, an in-app model adapter) asks the same thing and reads the same
+ * shape back, so the prompt and the tolerant JSON parse live here once. A
+ * backend owns only the transport (HTTP vs. child process vs. SDK) and how it
+ * extracts the model's text.
+ */
+/** Build the distillation prompt for one source, capped at `maxItems`. */
+declare function buildDistillPrompt(input: DistillInput, maxItems: number): string;
+/** Tolerant parse: grab the first `[...]` block (allows ```json fences / prose). */
+declare function parseItems(text: string): DistilledItem[];
+/**
+ * scanDistilledSourceIds — which raw source ids already have ≥1 refined entry
+ * derived from them, found by reading the `sources:` provenance backlink on
+ * every `entries/**/*.md`. Lets an incremental distill skip sources already
+ * done, so a daily re-run is idempotent (no duplicate entries, no wasted spend).
+ *
+ * Tolerant of both `walk` conventions a host's FsPort may use — paths relative
+ * to the walked dir (MemFs) or anchored at the workspace root (a workspace
+ * adapter) — by normalizing each back under `entries/` before reading.
+ */
+declare function scanDistilledSourceIds(fs: FsPort): Promise<Set<string>>;
+/**
+ * Distill registry — the catalog of distill kinds.
+ *
+ * Distill is four swappable slots: SOURCE (raw material) → IMPORTER (how to
+ * render it) → DISTILLER (the LLM) → TARGET (where entries land). A
+ * `DistillDescriptor` binds all four for one kind ("conversation", "web", …);
+ * the registry holds them by id so the cron/worker can dispatch polymorphically
+ * — adding a kind is registering a descriptor, with zero pipeline changes.
+ *
+ * Lightweight on purpose (mirrors the AIP-35 filesystem-provider registry):
+ * descriptors are code-registered, so there is no `resolveConfig` / secrets /
+ * UI-fields surface the way user-connected engine descriptors carry. Vendor-
+ * neutral — the kit owns the contract + the generic runner; the per-kind
+ * bindings live in each app's core package.
+ */
+/**
+ * Who a distill runs for. `id` is the durable handle carried on the queued job
+ * (`resolveScope` rehydrates it in the worker); `userId` feeds the job's owner.
+ * Kinds extend this with their own scope fields (a guild id, a workspace id, …).
+ */
+interface DistillScope {
+    readonly id: string;
+    readonly userId: string;
+    readonly [key: string]: unknown;
+}
+/** Where distilled entries land — the corpus filesystem for a scope. */
+interface DistillTarget {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    /** Optional corpus root within the fs (defaults to the fs root, ""). */
+    readonly root?: string;
+}
+/**
+ * SOURCE + IMPORTER bound to one scope. Co-constructed so both share a single
+ * (cache-bearing) source instance where relevant (e.g. a windowed conversation
+ * source loads each thread once). The binding owns the importer-native config
+ * AND the provenance mapping, so `runDistill` stays importer-agnostic — a
+ * conversation kind keys on `{refs}`/`conversationId`, a web kind on
+ * `{urls}`/`originalUrl`, with no per-kind code in the runner.
+ */
+interface DistillBinding {
+    /** The kit importer for this kind (ConversationImporter, WebImporter, …). */
+    readonly importer: CorpusImporter;
+    /**
+     * Build the importer's NATIVE config for the fresh (not-yet-distilled)
+     * material, or `null` when nothing new is left to import. The config is
+     * passed straight to `importer.enumerate({ config })`, so its shape is the
+     * importer's own (`{refs}`, `{urls}`, …). Filter against `distilled` (the set
+     * of provenance ids already backing ≥1 entry) so a re-run only sees fresh work.
+     */
+    prepare(distilled: ReadonlySet<string>): Promise<Readonly<Record<string, unknown>> | null>;
+    /**
+     * Stable provenance id for an imported source — becomes the entry's
+     * `sources:` backlink and the dedup key matched against `distilled`. MUST
+     * agree with the ids `prepare` filters on (e.g. the window slug, the URL).
+     */
+    provenanceId(imported: ImportedSource): string;
+}
+/**
+ * One catalog entry: a distill kind, with its four slots bound to a scope.
+ * Generic over the scope shape so each kind keeps its own typed scope while the
+ * registry stores them uniformly.
+ */
+interface DistillDescriptor<S extends DistillScope = DistillScope> {
+    /** Stable kind id — "conversation" | "web" | … */
+    readonly id: string;
+    /** Queue type the cron submits and the worker handles, e.g. "distill:conversation". */
+    readonly jobType: string;
+    /** Human-readable label (diagnostics / surfaces). */
+    readonly label: string;
+    /** Tags applied to every source distilled by this kind (e.g. ["personal"]). */
+    readonly tags?: readonly string[];
+    /**
+     * SOURCE + IMPORTER slots, bound to the scope. Receives the resolved TARGET
+     * so an importer that reads the corpus filesystem (e.g. refine-its-own-sources)
+     * can bind against it without resolving the target a second time.
+     */
+    bind(scope: S, target: DistillTarget): DistillBinding;
+    /** DISTILLER slot: the LLM boundary for this scope. */
+    distiller(scope: S): DistillPort;
+    /** TARGET slot: where entries land for this scope. */
+    target(scope: S): Promise<DistillTarget>;
+    /**
+     * Consent gate. Checked at fan-out (bulk filter) AND re-checked in the worker
+     * (authoritative — it can flip between enqueue and execution). Absent ⇒ no gate.
+     */
+    consent?(scope: S): Promise<boolean>;
+    /** Who to run for. Implementations should stream/paginate at scale. */
+    scopes(): Promise<readonly S[]>;
+    /** Rehydrate a scope from its `id` — the worker holds only the id post-enqueue. */
+    resolveScope(scopeId: string): Promise<S>;
+}
+interface DistillRegistry {
+    /** Register a kind. Throws on duplicate id. */
+    register<S extends DistillScope>(descriptor: DistillDescriptor<S>): void;
+    has(id: string): boolean;
+    /** Resolve by id. Throws when the id was never registered. */
+    resolve(id: string): DistillDescriptor;
+    /** All registered descriptors (for the cron fan-out + worker handler map). */
+    list(): DistillDescriptor[];
+}
+declare function createDistillRegistry(): DistillRegistry;
+/**
+ * runDistill — the generic distill pass for one (descriptor × scope).
+ *
+ * The kind-agnostic generalization of the conversation pipeline: resolve the
+ * scope's TARGET, scan which provenance ids are already distilled, ask the
+ * binding (SOURCE + IMPORTER) for the fresh refs, import each, and run the
+ * DISTILLER over it — writing refined AIP-10 entries via `DistillRunner`.
+ * No per-kind branches: every variation rides on the descriptor's slots.
+ *
+ * Idempotent: a unit whose provenance id already backs an entry is skipped by
+ * the binding's `prepare`, and `DistillRunner` additionally skips any entry
+ * slug that already exists — so a daily re-run only adds fresh material.
+ */
+interface DistillReport {
+    readonly descriptorId: string;
+    readonly scopeId: string;
+    /** Sources the importer yielded this run. */
+    unitsConsidered: number;
+    /** Units that produced ≥1 new entry. */
+    unitsDistilled: number;
+    entriesWritten: number;
+    /** Entry slugs skipped because an identical title already existed. */
+    skipped: number;
+}
+declare function runDistill<S extends DistillScope>(descriptor: DistillDescriptor<S>, scope: S): Promise<DistillReport>;
+/**
+ * ClaudeDistiller — a `DistillPort` backed by Claude over the Messages API.
+ * Reuses the kit's shared prompt + tolerant parse (`buildDistillPrompt` /
+ * `parseItems`), owning only the HTTP transport. SDK-free (raw fetch) so the
+ * job takes no client-lib dependency.
+ *
+ * Vendor-neutral: the only host coupling is an injected `apiKey` / `model` /
+ * `baseUrl` — no app names, no env-name assumptions. Distillation is bulk +
+ * background, so a mid-tier model is the sensible default; the caller gates
+ * the spend (consent + incremental windows).
+ */
+interface ClaudeDistillerOptions {
+    readonly apiKey: string;
+    /** Defaults to a mid-tier model — distillation is bulk + background. */
+    readonly model?: string;
+    readonly baseUrl?: string;
+    /** Max refined items to extract per source. */
+    readonly maxItems?: number;
+}
+declare class ClaudeDistiller implements DistillPort {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly maxItems;
+    constructor(opts: ClaudeDistillerOptions);
+    distill(input: DistillInput): Promise<readonly DistilledItem[]>;
+}
+/**
+ * Conversation windowing — pure helpers + the windowed-source contract.
+ *
+ * Chat is append-only, so a single immutable slug per conversation would
+ * collide once new turns arrive. The fix is WINDOWING: each (thread,
+ * completed-UTC-day) slice is the unit that distils exactly once (a closed day
+ * is immutable). These helpers compose / parse the window ref the importer
+ * resolves and the provenance slug the distilled-scan dedups on.
+ *
+ * No transport, no chat-store, no model dependency — just string algebra over
+ * `(threadId, day)` plus a structural source contract. A fake satisfying
+ * `ConversationWindowSource` is all a test needs.
+ */
+/** Compose the importer ref for one (thread, day) window. */
+declare function windowRef(threadId: string, day: string): string;
+/** Parse a window ref back to its parts, or null when malformed. */
+declare function parseWindowRef(ref: string): {
+    threadId: string;
+    day: string;
+} | null;
+/** Slug base a window resolves to — also the `sources:` provenance id, so the
+ *  distilled-scan can dedup windows across runs with no slug drift. */
+declare function windowSlug(threadId: string, day: string): string;
+/** A thread the source owns — minimal shape the enumeration needs. */
+interface ConversationThreadRef {
+    readonly id: string;
+    readonly threadId?: string;
+}
+/**
+ * The windowed source the distill pipeline drives: a `ConversationSourcePort`
+ * that can also enumerate its threads and each thread's completed-day windows.
+ * A fake satisfying this is all a test needs (no DB, no chat store).
+ */
+interface ConversationWindowSource extends ConversationSourcePort {
+    listThreads(): Promise<ConversationThreadRef[]>;
+    listWindows(threadId: string): Promise<string[]>;
+}
+/**
+ * Enumerate the window refs worth distilling for a windowed source: every
+ * (thread, completed-day) window whose provenance slug isn't already distilled.
+ * Generic over any `ConversationWindowSource`, so a binding never re-implements
+ * the thread→window→skip loop.
+ */
+declare function enumerateWindowRefs(source: ConversationWindowSource, distilled: ReadonlySet<string>): Promise<string[]>;
+/**
+ * resolveKnowledge — the `knowledge:` binding resolver (KNOWLEDGE→SKILL link).
+ *
+ * Filesystem-first: a skill's binding (`{ tags, kinds }`) is resolved against
+ * the refined `entries/**/*.md` on disk — no graph engine. Returns the
+ * matching refined entries (with their `sources:` provenance), filtered by the
+ * caller's access scope so an operator never sees knowledge above its clearance.
+ *
+ * A graph engine (mind-graph / gbrain) can later replace this scan with
+ * traversal/activation behind the SAME signature — the binding contract is stable.
+ */
+interface CorpusEntryQuery {
+    /** Match entries sharing ANY of these tags. Empty/absent = no tag filter. */
+    readonly tags?: readonly string[];
+    /** Restrict to these refined kinds. Empty/absent = all kinds. */
+    readonly kinds?: readonly RefinedKind[];
+    /** Cap results (highest-confidence first). */
+    readonly maxResults?: number;
+}
+/** A resolved origin an entry was distilled from (id + where to find it). */
+interface SourceRef {
+    readonly id: string;
+    readonly url?: string;
+    readonly title?: string;
+    readonly authority?: string;
+    readonly language?: string;
+}
+interface ResolvedEntry {
+    readonly slug: string;
+    readonly kind: string;
+    readonly title: string;
+    readonly body: string;
+    /** Provenance — the raw source ids this entry was derived from. */
+    readonly sources: readonly string[];
+    /** Resolved provenance — id + url + title for each source, when available. */
+    readonly sourceRefs?: readonly SourceRef[];
+    readonly confidence: number;
+    readonly tags: readonly string[];
+    readonly access?: string;
+    readonly path: string;
+}
+interface ResolveKnowledgeOptions {
+    readonly fs: FsPort;
+    readonly query: CorpusEntryQuery;
+    /**
+     * Access scopes the caller (operator) is cleared for. An entry passes if it
+     * has no access (public) or its access ∈ this set. Omit = no access filter.
+     */
+    readonly allowedAccess?: ReadonlySet<string>;
+}
+declare function resolveKnowledge(opts: ResolveKnowledgeOptions): Promise<readonly ResolvedEntry[]>;
+/**
+ * OverlayFs — stacks FsPorts so a writable layer shadows read-only ones.
+ *
+ * This is the customization engine for the SKILL→KNOWLEDGE→SOURCES spine:
+ * a guild's editable corpus (its system workspace) sits ON TOP of one or
+ * more read-only knowledge packs (shared, shipped). Layers are ordered
+ * highest-precedence first.
+ *
+ *   overlay = new OverlayFs([guildFs, packFs])   // guild wins
+ *
+ * Resolution is by RELATIVE PATH:
+ *   - reads (readFile/stat/exists) return the first layer that has the path
+ *   - walk/readdir UNION across layers, deduped — so an entry the guild
+ *     re-authors at the same path appears ONCE, with the guild's content
+ *   - a path only in the pack passes through unchanged (the floor)
+ *   - a path only in the guild is additive (extend)
+ *   - writes/appends/locks always target the top (writable) layer; the
+ *     packs stay pristine for every other guild
+ *
+ * This keeps `resolveKnowledge` untouched: it walks `entries/**` over the
+ * overlay and never sees a pack entry that the guild has shadowed.
+ */
+/**
+ * Sibling-path marker that removes (whiteouts) a lower layer's entry. To
+ * drop `entries/foo.md`, a higher layer authors `entries/foo.md.whiteout`.
+ * A marker file (not a frontmatter flag) keeps overlay resolution a pure
+ * path operation — listing a directory never reads entry bodies.
+ */
+declare const WHITEOUT_SUFFIX = ".whiteout";
+interface OverlayFsOptions {
+    /**
+     * Honor `.whiteout` markers so a higher layer can REMOVE (not just
+     * shadow) a lower entry. OFF by default: with whiteout disabled the
+     * overlay is pure union + shadow, byte-for-byte the original behavior.
+     */
+    readonly whiteout?: boolean;
+    /**
+     * Index of the writable layer (writes / appends / locks target it).
+     * Defaults to 0. Set this when a read-only CONSTRAINT floor is pinned
+     * ABOVE the writable layer: read precedence (layer order) and the write
+     * target are then independent — the floor wins reads, the guild layer
+     * still takes writes.
+     */
+    readonly writableLayer?: number;
+}
+declare class OverlayFs implements FsPort {
+    /** Layers ordered highest-precedence first. */
+    private readonly layers;
+    private readonly whiteout;
+    private readonly writableIndex;
+    constructor(layers: readonly FsPort[], options?: OverlayFsOptions);
+    /**
+     * Top-down resolution for a single path: the first layer that declares
+     * either the real entry OR its whiteout marker decides. Within one
+     * layer a real entry wins over a stale marker. Returns null when no
+     * layer declares the path, and `{ removed: true }` when the winning
+     * layer tombstones it.
+     */
+    private resolvePath;
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    stat(path: string): Promise<FsStat | null>;
+    readdir(path: string): Promise<readonly string[]>;
+    walk(path: string): Promise<readonly string[]>;
+    /**
+     * Union the entries each layer reports for a path (basenames for
+     * readdir, relative paths for walk), resolving whiteouts top-down: the
+     * first layer (highest precedence) that declares an entry or its marker
+     * wins. Real entries win over markers within the same layer; marker
+     * files are stripped from the result.
+     */
+    private unionWhiteoutAware;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    lock(path: string): Promise<FsLockHandle>;
+}
+/**
+ * ReadOnlyFs — wraps an FsPort and rejects every mutation. Use to seal a
+ * knowledge pack so a misconfigured host can never write into the shared,
+ * shipped corpus (the guild's edits belong in its own overlay layer).
+ */
+declare class ReadOnlyFs implements FsPort {
+    private readonly inner;
+    constructor(inner: FsPort);
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    stat(path: string): Promise<FsStat | null>;
+    readdir(path: string): Promise<readonly string[]>;
+    walk(path: string): Promise<readonly string[]>;
+    writeFile(path: string, _content: string): Promise<void>;
+    appendFile(path: string, _content: string): Promise<void>;
+    lock(path: string): Promise<FsLockHandle>;
+}
+/**
+ * MemFs — an in-memory FsPort over a flat `path → content` map.
+ *
+ * Paths are workspace-relative (no leading slash), exactly like the disk
+ * adapters; `walk(dir)` returns paths relative to the walked directory, so it
+ * composes with `resolveKnowledge` (which re-prefixes) and with `OverlayFs`
+ * unchanged.
+ *
+ * Primary use: a knowledge PACK whose entries are inlined into the JS bundle
+ * at build time (see `@guilde/knowledge-packs`). Reading from an in-memory map
+ * means packs ride inside `dist` — no runtime `fs`, no path resolution, no
+ * loose data files for the deploy to drop. Wrap in `ReadOnlyFs` for packs.
+ */
+declare class MemFs implements FsPort {
+    private readonly files;
+    constructor(files: Record<string, string>);
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    readdir(path: string): Promise<readonly string[]>;
+    walk(path: string): Promise<readonly string[]>;
+    stat(path: string): Promise<FsStat | null>;
+    lock(): Promise<FsLockHandle>;
+}
+/**
+ * Knowledge-stack layer model (AIP-10 §Composition).
+ *
+ * A knowledge stack is the ordered set of layers an operator's recall is
+ * resolved against: its own packs, its role's packs, an org house-style
+ * view, a regional compliance floor, and so on. Each layer is produced by
+ * a registered `LayerProvider` — adding a dimension (region, compliance,
+ * tier, …) is registering one provider, never editing the resolver.
+ *
+ * The model has two knobs:
+ *   - `band`  — precedence among LENS layers (lower = higher precedence).
+ *   - `mode`  — `lens` (overridable) vs `constraint` (a non-shadowable,
+ *               non-tombstoneable floor; see AIP-10).
+ *
+ * Vendor-neutral: a provider reads a generic `ResolutionContext` and emits
+ * `LayerRef`s the host knows how to mount. The context carries dimension
+ * values plus an opaque, host-typed `subject` (an operator row, a role
+ * handle, …) so per-app providers stay type-safe without leaking app
+ * types into the kit.
+ */
+/** How a layer composes against the others. */
+type LayerMode = "lens" | "constraint";
+/** A pointer to a mountable knowledge source — a pack id or a view ref. */
+interface LayerRef {
+    /** Pack id (`screen-cv`) or KNOWLEDGE.md view ref (`region/fr`). */
+    readonly ref: string;
+    /** How the host should resolve `ref`. Defaults to `pack`. */
+    readonly kind?: "pack" | "view";
+}
+/**
+ * What the resolver is given. `subject` is opaque to the kit; providers
+ * narrow it. `dimensions` is the open facet bag (`region`, `compliance`,
+ * `org`, `tier`, `locale`, …).
+ */
+interface ResolutionContext<TSubject = unknown> {
+    /** Stable bucketing token for shadow rollout (e.g. conversation id). */
+    readonly conversationId?: string;
+    /** Dimension values keyed by dimension name. Missing/undefined = absent.
+     * List-valued dimensions (e.g. `capability`) carry every value at once —
+     * providers that expect a scalar must guard. */
+    readonly dimensions?: Readonly<Record<string, string | readonly string[] | undefined>>;
+    /** Host payload providers read to compute their refs. */
+    readonly subject?: TSubject;
+}
+/** Optional shadow-rollout config for a layer. */
+interface LayerShadow {
+    /** Fraction of conversations the layer fires on (0..1). */
+    readonly pct?: number;
+}
+/**
+ * A pluggable layer. Behavior lives on the descriptor — the resolver never
+ * branches on `id` or `dimension`. Register via
+ * `createRegistry<LayerProvider>({ family, keyBy: p => p.id })`.
+ */
+interface LayerProvider<TSubject = unknown> {
+    /** Registry key. */
+    readonly id: string;
+    /** Precedence among lenses; lower wins. Constraints are hoisted regardless. */
+    readonly band: number;
+    /** `lens` (overridable) or `constraint` (floor). */
+    readonly mode: LayerMode;
+    /** Dimension this layer adapts (`operator`, `role`, `region`, …) for audit. */
+    readonly dimension?: string;
+    /** When set, the layer is a shadow arm sampled deterministically. */
+    readonly shadow?: LayerShadow;
+    /** Compute the layer's refs for a context. Empty → the layer is inert. */
+    resolve(ctx: ResolutionContext<TSubject>): readonly LayerRef[] | Promise<readonly LayerRef[]>;
+}
+/** One resolved layer in the stack, carrying audit attribution. */
+interface StackEntry {
+    readonly providerId: string;
+    readonly band: number;
+    readonly mode: LayerMode;
+    readonly dimension?: string;
+    readonly refs: readonly LayerRef[];
+    /** True iff this layer was a shadow arm that sampled in for this context. */
+    readonly shadowSampled: boolean;
+}
+/** The resolved stack + the audit trail of layers that did NOT contribute. */
+interface StackResolution {
+    /** Contributing layers, band-ordered (constraints keep their band here; the
+     *  mount step hoists them). */
+    readonly entries: readonly StackEntry[];
+    /** Providers that resolved to nothing or sampled out, for "why not" audits. */
+    readonly skipped: readonly StackSkip[];
+}
+interface StackSkip {
+    readonly providerId: string;
+    readonly dimension?: string;
+    readonly reason: "empty" | "shadow-not-sampled";
+}
+/**
+ * StackResolver — given a `ResolutionContext` and a registry of
+ * `LayerProvider`s, produce the band-ordered list of layers an operator's
+ * recall is resolved against.
+ *
+ * The generalization of `OperatorOverlayResolver` (playbooks): same
+ * ctx → registry → priority-sort → ordered-list shape, same deterministic
+ * shadow sampling for % rollout. Pure — no I/O. The host turns the emitted
+ * refs into mounted FsPorts (see `buildOverlayFromStack`).
+ */
+declare class StackResolver<TSubject = unknown> {
+    private readonly registry;
+    constructor(registry: Registry<LayerProvider<TSubject>>);
+    resolve(ctx: ResolutionContext<TSubject>): Promise<StackResolution>;
+}
+/**
+ * Turn a resolved knowledge stack into a mounted `OverlayFs`, and the
+ * helpers that flatten it.
+ *
+ * Mount order encodes the AIP-10 plane-precedence invariant:
+ *
+ *   [ ...constraint layers (read-only floor, band-ordered) ]   ← top
+ *   [ guild writable layer ]                                   ← writes here
+ *   [ ...lens layers (band-ordered) ]                          ← floor packs
+ *
+ * Constraints are hoisted ABOVE the guild layer so neither a guild edit
+ * nor a `.whiteout` can shadow or remove them (they sit higher, and
+ * top-down resolution + whiteout-only-suppresses-lower make them a true
+ * floor). Writes still target the guild layer via `writableLayer`, so the
+ * read floor and the write target stay independent.
+ */
+interface BuildOverlayOptions {
+    /** The guild's own editable corpus — the single writable layer. */
+    readonly guildFs: FsPort;
+    /** The resolved stack (band-ordered entries). */
+    readonly stack: StackResolution;
+    /** Resolve a layer ref to an FsPort, or null if it has no mountable source. */
+    readonly loadFs: (ref: LayerRef) => FsPort | null;
+}
+/**
+ * Build the mounted overlay for a resolved stack. Returns `guildFs`
+ * unchanged when no layer resolves to a mountable source (so the
+ * single-layer fast path is preserved).
+ */
+declare function buildOverlayFromStack(opts: BuildOverlayOptions): FsPort;
+/**
+ * Flatten a resolved stack to a de-duplicated, band-ordered list of pack
+ * refs (kind `pack` or unspecified). This reproduces the legacy
+ * `resolveOperatorPacks` output shape (operator packs before role packs,
+ * each id once) so the pack-id contract stays stable.
+ */
+declare function flattenPackRefs(stack: StackResolution): string[];
+/** Pack refs split by composition mode, each list deduped + band-ordered. */
+interface StackRefPartition {
+    /** Lens packs — mount UNDER the writable layer (the guild shadows them). */
+    readonly lens: readonly string[];
+    /** Constraint packs — mount ABOVE the writable layer (a non-shadowable floor). */
+    readonly constraint: readonly string[];
+}
+/**
+ * Partition a resolved stack's pack refs by mode. The host mounts `lens`
+ * below the guild layer and `constraint` above it (read-only), so a
+ * compliance/legal floor cannot be shadowed or tombstoned. With no
+ * constraint layers resolved, `lens` equals `flattenPackRefs` — the legacy
+ * pack-id contract.
+ */
+declare function partitionStackRefs(stack: StackResolution): StackRefPartition;
+/**
+ * Sink — the agnostic outbound boundary: push refined corpus entries to an
+ * external store. The kit knows NOTHING about any host (Guilde, etc.) — it
+ * just hands `SinkItem`s to a `SinkPort`. Concrete sinks (a config-driven MCP
+ * caller, an HTTP endpoint, a local mirror) live in host/adapter packages and
+ * are selected by a sink manifest, not by code in the kit.
+ *
+ * This is how a vendor-neutral corpus links to a specific host: via a
+ * declarative sink config + MCP, never a host-named command.
+ */
+interface SinkItem {
+    readonly slug: string;
+    readonly kind: string;
+    readonly title: string;
+    readonly body: string;
+    /** Provenance — raw source ids this entry derived from. */
+    readonly sources: readonly string[];
+    readonly tags: readonly string[];
+    readonly confidence: number;
+    readonly access?: string;
+    /** Stable address for idempotent upsert, e.g. `corpus://<slug>`. */
+    readonly uri: string;
+}
+interface SinkPushResult {
+    readonly uri: string;
+    readonly ok: boolean;
+    readonly skipped?: boolean;
+    readonly error?: string;
+}
+interface SinkPort {
+    /** Push one item. Idempotent on `uri` is the sink's responsibility. */
+    push(item: SinkItem): Promise<SinkPushResult>;
+}
+/**
+ * SyncRunner — push refined corpus entries to a SinkPort. Agnostic: it scans
+ * `entries/` (via resolveKnowledge), shapes each as a SinkItem, and pushes
+ * through the injected sink. The sink (and its host binding) is config, not
+ * code here. Sources stay local (raw archive); only refined knowledge syncs.
+ */
+interface SyncRunnerOptions {
+    readonly fs: FsPort;
+    readonly sink: SinkPort;
+    /** Which entries to sync (tags/kinds). Empty = all refined entries. */
+    readonly select?: CorpusEntryQuery;
+    /** URI scheme for the item address. Default `corpus`. */
+    readonly uriScheme?: string;
+    /** Pace between pushes (ms). Default 0. */
+    readonly throttleMs?: number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+interface SyncReport {
+    readonly pushed: number;
+    readonly skipped: number;
+    readonly failed: number;
+    readonly results: readonly SinkPushResult[];
+}
+declare class SyncRunner {
+    private readonly opts;
+    constructor(opts: SyncRunnerOptions);
+    run(): Promise<SyncReport>;
+}
+/**
+ * Multi-reviewer score aggregation.
+ *
+ * High-stakes corpus entries (those flagged by curator policy as
+ * needing N-reviewer review) get scored by multiple reviewers — the
+ * single-reviewer path is fine for the bulk of the queue, but the
+ * top quality tier deserves redundancy.
+ *
+ * Aggregation policy:
+ *   - **Median** is the default — robust to a single outlier reviewer.
+ *   - **Weighted-median** uses reviewer track-record weights so a
+ *     well-calibrated reviewer's score counts for more than a fresh /
+ *     under-calibrated one.
+ *
+ * Disagreement detection: when the spread between the highest and
+ * lowest review exceeds a threshold, the aggregate carries a
+ * `disagreement: true` flag — the curator's queue can route those
+ * entries to human adjudication rather than auto-trust the median.
+ *
+ * Pure — no I/O. Inputs come from the lifecycle workflow; outputs
+ * feed the gate evaluator.
+ */
+interface ReviewerScore {
+    /** AIP-23-style identity. */
+    readonly reviewerIdentity: string;
+    /** 0..5 (matches metadata.corpus.qualityScore convention). */
+    readonly score: number;
+    /**
+     * Optional confidence weight from the reviewer's track record
+     * (correlation with downstream utility/lift). Defaults to 1.0
+     * for unknown reviewers. See `correlation.ts`.
+     */
+    readonly weight?: number;
+    readonly at: string;
+    readonly note?: string;
+}
+interface AggregateOptions {
+    /** Spread threshold above which `disagreement` is flagged. Default: 1.5. */
+    readonly disagreementThreshold?: number;
+    /** When true, use weighted-median; else plain median. */
+    readonly weighted?: boolean;
+}
+interface AggregateResult {
+    /** Aggregate qualityScore (0..5). */
+    readonly aggregate: number;
+    /** Highest vs lowest review difference. */
+    readonly spread: number;
+    /** True when spread > disagreementThreshold. */
+    readonly disagreement: boolean;
+    /** Number of reviewers that contributed. */
+    readonly sampleSize: number;
+    /** Per-reviewer breakdown for the curator UI. */
+    readonly breakdown: readonly {
+        readonly reviewerIdentity: string;
+        readonly score: number;
+        readonly weight: number;
+    }[];
+}
+/**
+ * Aggregate N reviewer scores into one final score + a disagreement
+ * flag. Empty input → aggregate=0, disagreement=false (caller decides
+ * whether that's an error).
+ */
+declare function aggregateReviewerScores(reviews: readonly ReviewerScore[], opts?: AggregateOptions): AggregateResult;
+/**
+ * Reviewer track record — per-reviewer history of (score → observed
+ * outcome) used to compute calibration weights.
+ *
+ * Stored at `corpus/_calibration/reviewer-track-record.yaml`:
+ *
+ *   reviewers:
+ *     "ws://operators/quality-reviewer":
+ *       - { entrySlug, qualityScore, observedUtility?, observedLift?, at }
+ *     "ws://operators/junior-reviewer":
+ *       - ...
+ *
+ * Append-only — every review pass adds rows. The calibration routine
+ * reads the configured window (typically 90 days), correlates the
+ * reviewer's scores against observed retrieval-quality outcomes, and
+ * derives a weight in [0, 1] that feeds the multi-reviewer aggregator
+ * (see `aggregate.ts`).
+ */
+interface TrackRecordEntry {
+    readonly entrySlug: string;
+    /** Reviewer-assigned 0..5 quality score at review time. */
+    readonly qualityScore: number;
+    /** Retrieval utility (0..1 — fraction of hits actually cited). */
+    readonly observedUtility?: number;
+    /** Retrieval lift (>1 = boost vs baseline, <1 = drag). */
+    readonly observedLift?: number;
+    readonly at: string;
+}
+interface ReviewerTrackRecordOptions {
+    readonly fs: FsPort;
+    /** Workspace-relative path. Defaults to `_calibration/reviewer-track-record.yaml`. */
+    readonly path?: string;
+}
+declare class ReviewerTrackRecord {
+    private readonly opts;
+    private readonly path;
+    constructor(opts: ReviewerTrackRecordOptions);
+    /** Load the full record. Empty when the file doesn't exist yet. */
+    load(): Promise<Readonly<Record<string, readonly TrackRecordEntry[]>>>;
+    /** Append one entry under a reviewer's identity. */
+    append(reviewerIdentity: string, entry: TrackRecordEntry): Promise<void>;
+    /**
+     * Read all entries for a reviewer in the last N days. Used by the
+     * calibration routine to compute correlation on a rolling window.
+     */
+    window(reviewerIdentity: string, days: number, now: Date): Promise<readonly TrackRecordEntry[]>;
+    /** Reviewer identities present in the record. */
+    listReviewers(): Promise<readonly string[]>;
+}
+/**
+ * Calibration — correlate a reviewer's qualityScore against the
+ * downstream retrieval-quality outcomes (utility + lift). Reviewers
+ * whose scores don't predict outcomes are miscalibrated; their
+ * weight drops in the multi-reviewer aggregator until they re-train.
+ *
+ * Math: Pearson correlation coefficient on two parallel arrays.
+ * Returns NaN-safe r in [-1, 1]. Threshold for "calibrated" is host
+ * policy; the helper just reports.
+ *
+ * Pure — no I/O. Inputs come from `ReviewerTrackRecord.window`,
+ * outputs feed the calibration routine + multi-reviewer aggregator.
+ */
+interface ReviewerCalibration {
+    readonly reviewerIdentity: string;
+    readonly sampleSize: number;
+    /**
+     * Pearson r in [-1, 1]. Higher = reviewer's qualityScore predicts
+     * downstream outcomes better. Negative = reviewer is inversely
+     * correlated (worse than random). NaN when sampleSize < 2 or all
+     * scores are identical (no variance).
+     */
+    readonly correlationUtility: number;
+    readonly correlationLift: number;
+    /** Whether this reviewer meets the calibrated threshold. */
+    readonly isCalibrated: boolean;
+    /** Suggested weight for the multi-reviewer aggregator (0..1). */
+    readonly suggestedWeight: number;
+    /** Reason flag — useful for curator UI tooltips. */
+    readonly status: "calibrated" | "miscalibrated" | "insufficient-sample" | "no-variance";
+}
+interface CalibrationOptions {
+    /** Minimum sample size to compute calibration. Defaults to 10. */
+    readonly minSampleSize?: number;
+    /** Pearson r threshold above which a reviewer is "calibrated". Defaults to 0.4. */
+    readonly calibratedThreshold?: number;
+}
+/**
+ * Pearson correlation coefficient on two parallel numeric arrays.
+ *
+ *   r = cov(X, Y) / (σ_X · σ_Y)
+ *
+ * Returns NaN when:
+ *   - either array is < 2 elements
+ *   - either array has zero variance (all values identical)
+ *
+ * NaN is the explicit "I can't compute this" signal — callers
+ * decide whether NaN means "default to neutral weight" or "flag for
+ * human review".
+ */
+declare function pearsonCorrelation(xs: readonly number[], ys: readonly number[]): number;
+/**
+ * Compute a single reviewer's calibration from their track-record
+ * window. Returns a ReviewerCalibration summary.
+ *
+ * Strategy: average the utility-correlation and lift-correlation
+ * (when both are available). If only one outcome was recorded
+ * across the window (rare), use that one alone.
+ */
+declare function computeReviewerCalibration(reviewerIdentity: string, entries: readonly TrackRecordEntry[], opts?: CalibrationOptions): ReviewerCalibration;
+/**
+ * CorpusWorkspaceReader — scan + parse a corpus workspace via FsPort.
+ *
+ * Pure path-discipline + YAML parsing — no schema validation here. The
+ * reader's job is to surface every .md file in the workspace and
+ * classify it by location. Schema validation happens in
+ * `validate/validator.ts` so callers can run both in parallel and get
+ * crisp error categorization.
+ *
+ * Pure: no `node:fs`, no `node:path`. All paths are joined manually
+ * with "/" so the kit runs on Node, Bun, Deno, and browser-side
+ * editors (e.g. curator UI lint preview).
+ */
+interface CorpusWorkspaceReaderOptions {
+    readonly fs: FsPort;
+}
+declare class CorpusWorkspaceReader {
+    private readonly opts;
+    constructor(opts: CorpusWorkspaceReaderOptions);
+    /**
+     * Scan the workspace rooted at `root` and return a typed snapshot.
+     * `root` is workspace-relative (the host resolves to a backing
+     * storage); commonly "" for the workspace root itself.
+     */
+    read(root: string): Promise<CorpusWorkspaceSnapshot>;
+}
+/**
+ * CorpusWorkspaceWriter — atomic file writes with versionToken
+ * optimistic-concurrency guard.
+ *
+ * Every write goes through `writeFile(path, content, expected?)`:
+ *   - If `expected` is provided, the writer reads the current file's
+ *     content hash and refuses to write if it doesn't match → throws
+ *     CorpusVersionConflictError. Caller retries with the fresh
+ *     versionToken.
+ *   - If `expected` is null, the writer requires the file to NOT
+ *     exist (create-only).
+ *   - If `expected` is undefined, the writer overwrites unconditionally
+ *     (use sparingly — bypasses the concurrency-correctness story).
+ *
+ * Multi-file transactions (e.g. promote entry + update _index.md +
+ * append _log.md) use FsPort.lock on a sentinel path so concurrent
+ * promoters serialize cleanly.
+ *
+ * The writer is the ONLY component allowed to call FsPort.writeFile
+ * for workspace content. The reader/validator/linter never write.
+ * The event emitter writes only _log.md via append.
+ */
+declare class CorpusVersionConflictError extends Error {
+    readonly path: string;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(path: string, expected: string, actual: string);
+}
+interface CorpusWorkspaceWriterOptions {
+    readonly fs: FsPort;
+}
+/**
+ * Frontmatter + body source pair, used by helpers like `writeEntry`
+ * that need to serialize the .md back from structured data.
+ */
+interface MarkdownDoc {
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    readonly body: string;
+}
+declare class CorpusWorkspaceWriter {
+    private readonly opts;
+    constructor(opts: CorpusWorkspaceWriterOptions);
+    /**
+     * Compute the versionToken for raw file content. Exposed so the
+     * caller can stage a write and pass the same hash function used
+     * inside the writer.
+     */
+    static versionTokenOf(content: string): string;
+    /**
+     * Atomic write with optimistic concurrency check.
+     *
+     *   - expected === undefined → unconditional overwrite (use sparingly)
+     *   - expected === null      → create-only (refuses if exists)
+     *   - expected === string    → CAS check (refuses if current hash differs)
+     *
+     * Returns the new versionToken on success.
+     */
+    writeFile(path: string, content: string, expected?: string | null): Promise<string>;
+    /**
+     * Serialize a markdown doc (frontmatter + body) and write atomically.
+     * Frontmatter keys are stringified in a stable order so version
+     * tokens are deterministic across emitter rebuilds.
+     */
+    writeMarkdown(path: string, doc: MarkdownDoc, expected?: string | null): Promise<string>;
+    /**
+     * Run `fn` while holding a workspace-scoped lock. Used for
+     * multi-file transactions (promote entry + update _index.md + log
+     * append). The lock path is host-specific; we default to
+     * `_log.md` because it's the file every transaction touches.
+     *
+     * `lockPath` is workspace-relative.
+     */
+    transaction<T>(lockPath: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * CorpusValidator — validate a workspace snapshot against the AIP JSON
+ * Schemas (the spec source-of-truth at
+ * projects/agentproto/agentproto/specs/resources/aip-XX/draft/).
+ *
+ * The validator is constructed once with an AJV instance pre-loaded
+ * with every referenced schema, then run against a `ParsedFile` or a
+ * whole `CorpusWorkspaceSnapshot`. Schema loading is delegated to a
+ * factory function so the kit doesn't carry the spec JSON inside — the
+ * host (cloud adapter or local CLI) supplies the schemas at boot.
+ *
+ * Why AJV not zod: the AgentProto zod schemas at @agentproto/(aip)/schema
+ * are partially generated stubs today (z.any() oneOf branches in
+ * knowledge/collection/playbook). AJV against the canonical JSON
+ * Schemas is the authoritative path until the zod stubs are
+ * regenerated from the JSON Schemas. The corpus kit is the place that
+ * exercises both, so this discipline matters.
+ */
+/**
+ * Map from FileKind → JSON Schema key. The schema bundle the host
+ * supplies must include these keys.
+ */
+type AipSchemaKey = "knowledge" | "collection" | "playbook" | "operator" | "workflow" | "routine";
+interface AipSchemaBundle {
+    /** Schemas keyed by AIP doctype. Values are JSON Schema documents. */
+    readonly schemas: Readonly<Record<AipSchemaKey, unknown>>;
+    /**
+     * External schemas to register with AJV before compilation (so
+     * `$ref` cross-document references resolve). The known cross-refs
+     * today are AIP-16 IO and AIP-17 RUNNER.
+     */
+    readonly externals?: ReadonlyArray<unknown>;
+}
+interface CorpusValidatorOptions {
+    readonly bundle: AipSchemaBundle;
+}
+declare class CorpusValidator {
+    private readonly validators;
+    constructor(opts: CorpusValidatorOptions);
+    /**
+     * Validate a single parsed file. Returns issues + a valid flag.
+     * Unknown FileKind ("unknown" bucket) is reported as a single info
+     * issue — the file exists but doesn't fit AIP conventions.
+     */
+    validateFile(file: ParsedFile): ValidationResult;
+    /**
+     * Validate every file in a workspace snapshot. Returns a flat list
+     * of issues across all files plus a `valid` flag that's true only
+     * if zero error-severity issues exist.
+     */
+    validateWorkspace(snapshot: CorpusWorkspaceSnapshot): ValidationResult;
+}
+/**
+ * CorpusLinter — implements the AIP-10 lint kinds declared in
+ * KNOWLEDGE.md.lints[]. Five canonical kinds + `custom` delegation
+ * hook for hosts that ship their own checks.
+ *
+ * Lint kinds (per AIP-10 spec):
+ *   - require-source — entries of kinds X MUST have ≥1 source ref
+ *   - min-confidence — entries of kinds X SHOULD have confidence ≥ N
+ *   - max-age        — entries of kinds X with updated_at older than N days
+ *   - broken-ref     — sources/links/supersedes references that don't resolve
+ *   - orphan         — entries that no other entry references (incoming = 0)
+ *   - custom         — delegated to host-supplied callbacks keyed by lint id
+ *
+ * The linter assumes the workspace has already passed schema validation.
+ * Running lint on invalid workspace yields garbage. Callers should run
+ * the validator first; the writer pipeline enforces this.
+ */
+interface LintDeclaration {
+    readonly id: string;
+    readonly kind: "require-source" | "min-confidence" | "max-age" | "broken-ref" | "orphan" | "custom";
+    readonly appliesTo: string;
+    readonly severity: "error" | "warn" | "info";
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+type CustomLintRunner = (decl: LintDeclaration, snapshot: CorpusWorkspaceSnapshot) => readonly LintIssue[];
+interface CorpusLinterOptions {
+    readonly clock: ClockPort;
+    /** Per-id implementations for `kind: custom` lints. */
+    readonly customRunners?: Readonly<Record<string, CustomLintRunner>>;
+}
+declare class CorpusLinter {
+    private readonly opts;
+    constructor(opts: CorpusLinterOptions);
+    lint(snapshot: CorpusWorkspaceSnapshot): LintReport;
+    private lintRequireSource;
+    private lintMinConfidence;
+    private lintMaxAge;
+    private lintBrokenRef;
+    private lintOrphan;
+}
+/**
+ * CorpusEventEmitter — append-only writer for `_log.md`.
+ *
+ * The corpus' audit trail. Every state transition (candidate
+ * discovered/analyzed/approved/rejected, entry promoted/deprecated,
+ * playbook activated/archived, gap opened/resolved) appends one line
+ * here.
+ *
+ * Line format (NDJSON-ish, but inside a markdown file for AIP-10
+ * conformance — _log.md is the canonical AIP-10 log doctype):
+ *
+ *   - {ISO}  {kind}  by {actor}  payload={JSON}
+ *
+ * Concrete:
+ *
+ *   - 2026-05-22T14:30:00.000Z  corpus.entry.promoted  by ws://operators/corpus-curator  payload={"slug":"contrarian-short-form-hooks","kind":"pattern"}
+ *
+ * Why line-per-event (not blocks): every host needs to grep / tail /
+ * stream the log without a markdown parser. Inside an .md file =
+ * AIP-10 conformant; line-format = ops-friendly.
+ *
+ * Atomicity: relies on FsPort.appendFile being atomic against
+ * concurrent appends. Hosts MUST honor that — cloud topology uses
+ * append APIs (S3 Express, GCS), local topology uses POSIX append
+ * (atomic up to PIPE_BUF).
+ */
+interface CorpusEventEmitterOptions {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly identity: IdentityPort;
+    /**
+     * Workspace root the emitter targets — `_log.md` is written
+     * relative to this. Hosts that mount multiple corpora pass one
+     * emitter per workspace root.
+     */
+    readonly workspaceRoot: string;
+}
+declare class CorpusEventEmitter {
+    private readonly opts;
+    constructor(opts: CorpusEventEmitterOptions);
+    /**
+     * Emit one event. Returns the event as written (including the
+     * ISO timestamp and actor resolved at emit time). The .md log file
+     * is created on first append if missing.
+     */
+    emit(kind: CorpusEventKind, payload: Readonly<Record<string, unknown>>): Promise<CorpusEvent>;
+}
+/**
+ * Candidate state machine.
+ *
+ * AIP-18 collection COLLECTION.md declares the `statuses[]` array
+ * with explicit `transitionsTo`. This module enforces those
+ * transitions at the corpus-kit boundary so callers can never
+ * silently land an item in an illegal state.
+ *
+ * The corpus' canonical candidate collection (per the plan) has:
+ *
+ *   discovered → analyzed | rejected
+ *   analyzed   → approved | rejected | needs-work
+ *   needs-work → analyzed | rejected
+ *   approved   = terminal
+ *   rejected   = terminal
+ *
+ * This module is pure (no I/O). The lifecycle workflow caller pairs
+ * it with the writer + emitter to durably enact each transition.
+ */
+type CandidateStatus = "discovered" | "analyzed" | "needs-work" | "approved" | "rejected";
+/**
+ * Default transition graph mirroring the corpus-candidate AIP-18
+ * collection shape shipped in the marketing preset. Hosts that load a
+ * custom collection schema may override via
+ * `transitionGraphFromCollection()`.
+ */
+declare const DEFAULT_TRANSITIONS: Readonly<Record<CandidateStatus, readonly CandidateStatus[]>>;
+interface TransitionCheck {
+    readonly allowed: boolean;
+    readonly reason?: string;
+}
+/**
+ * Check whether a candidate can transition from `from` to `to`.
+ */
+declare function canTransition(from: CandidateStatus, to: CandidateStatus, graph?: Readonly<Record<CandidateStatus, readonly CandidateStatus[]>>): TransitionCheck;
+/**
+ * Build a transition graph from a parsed COLLECTION.md frontmatter.
+ * Hosts call this once at boot to align the candidate state machine
+ * with whatever collection schema the workspace ships.
+ *
+ * Falls back to DEFAULT_TRANSITIONS if the frontmatter doesn't carry
+ * a recognizable `statuses[]` array — the caller is encouraged to
+ * pass the parsed frontmatter directly rather than re-flattening.
+ */
+declare function transitionGraphFromCollection(fm: Readonly<Record<string, unknown>>): Readonly<Record<string, readonly string[]>>;
+declare class IllegalTransitionError extends Error {
+    readonly from: CandidateStatus;
+    readonly to: CandidateStatus;
+    readonly reason: string;
+    constructor(from: CandidateStatus, to: CandidateStatus, reason: string);
+}
+/**
+ * Validate a transition and throw if disallowed. Convenience wrapper
+ * around canTransition for callers that want fail-fast semantics.
+ */
+declare function assertTransition(from: CandidateStatus, to: CandidateStatus, graph?: Readonly<Record<CandidateStatus, readonly CandidateStatus[]>>): void;
+/**
+ * Auto-promote gate — evaluates a candidate against
+ * `KNOWLEDGE.md.metadata.corpus.autoPromote.requires`.
+ *
+ * The plan's auto-promote requirements (from the workspace manifest
+ * example) typically include:
+ *
+ *   qualityScore: { min: 4.2 }
+ *   riskScore:    { max: 1.5 }
+ *   hasArchiveHash: true
+ *   requiredFields: [why_it_works, transferable_pattern, use_when, avoid_when]
+ *   notRestricted: true
+ *
+ * This gate returns a structured GateResult with pass/fail + the
+ * specific rules that failed, so the caller can either auto-promote
+ * (all pass) or route to human review (corpus-review collection)
+ * with the failure reasons attached.
+ *
+ * Pure — no I/O.
+ */
+interface AutoPromoteRequirements {
+    readonly qualityScore?: {
+        min?: number;
+        max?: number;
+    };
+    readonly riskScore?: {
+        min?: number;
+        max?: number;
+    };
+    readonly hasArchiveHash?: boolean;
+    readonly requiredFields?: readonly string[];
+    readonly notRestricted?: boolean;
+}
+interface AutoPromoteConfig {
+    readonly enabled: boolean;
+    readonly requires?: AutoPromoteRequirements;
+}
+interface CandidateForGate {
+    /** Parsed candidate frontmatter (analyzed state) + body. */
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    readonly body: string;
+    /** Optional analysis output — fields the analyst produced. */
+    readonly analysis?: Readonly<Record<string, unknown>>;
+}
+interface GateFailure {
+    readonly rule: string;
+    readonly message: string;
+}
+interface GateResult {
+    readonly passed: boolean;
+    readonly failures: readonly GateFailure[];
+    /** True when the workspace itself has auto-promote disabled. */
+    readonly disabled: boolean;
+}
+/**
+ * Read the auto-promote config from a workspace snapshot. Returns
+ * a "disabled" config if the workspace doesn't declare one — the
+ * gate will short-circuit to "always require human review".
+ */
+declare function extractAutoPromoteConfig(snapshot: CorpusWorkspaceSnapshot): AutoPromoteConfig;
+/**
+ * Evaluate a candidate against the workspace's auto-promote config.
+ * Returns `passed: true` only when every declared requirement holds.
+ */
+declare function evaluateGate(candidate: CandidateForGate, config: AutoPromoteConfig): GateResult;
+/**
+ * Chunking strategy for corpus entries.
+ *
+ * Split an entry body into chunks that fit the backing engine's
+ * `maxChunkBytes` capability. Naive but predictable — overlap window
+ * keeps semantic continuity across boundaries; smarter sentence /
+ * semantic chunking can land later behind the same call.
+ *
+ * Matches the qdrant adapter's CHUNK_TARGET_CHARS / CHUNK_OVERLAP_CHARS
+ * numerology so corpus + qdrant agree on chunk shape end-to-end.
+ */
+interface ChunkerOptions {
+    /** Soft target per chunk (characters). Default 1500 ≈ 375 tokens. */
+    readonly targetChars?: number;
+    /** Overlap window between adjacent chunks. Default 150. */
+    readonly overlapChars?: number;
+    /** Hard ceiling — backing engine's maxChunkBytes (Buffer-byte). */
+    readonly maxBytes?: number;
+}
+declare function chunkText(text: string, opts?: ChunkerOptions): string[];
+/**
+ * WriterPort — the corpus kit's path into a backing knowledge engine.
+ *
+ * The kit never imports IKnowledgeProvider — that's an agstudio type.
+ * Instead it consumes this minimal port; the host (agstudio
+ * CorpusInternalWriter in cloud, future local-CLI bridge) supplies
+ * the implementation.
+ *
+ * Matches the shape of `CorpusInternalWriter` in
+ * `packages/integration/knowledge/src/providers/corpus/internal-writer.ts`
+ * so the cloud-topology adapter is a one-to-one satisfying type.
+ */
+interface WriterChunk {
+    readonly text: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface PushChunksInput {
+    readonly entrySlug: string;
+    readonly entryPath: string;
+    readonly title?: string;
+    readonly uri?: string;
+    readonly chunks: readonly WriterChunk[];
+    readonly entryMetadata?: Readonly<Record<string, unknown>>;
+}
+interface WriterPort {
+    pushChunks(input: PushChunksInput): Promise<readonly string[]>;
+    removeEntry(entrySlug: string): Promise<{
+        removed: number;
+    }>;
+}
+/**
+ * CorpusIndexer — coordinator that ships active entries into the
+ * backing engine via WriterPort.
+ *
+ * The kit doesn't know about IKnowledgeProvider — agstudio's
+ * CorpusInternalWriter satisfies WriterPort and bridges to the
+ * actual engine (qdrant / gbrain). Local topology supplies its own
+ * WriterPort (e.g. dockered qdrant).
+ *
+ * Three public methods:
+ *   - reindex(snapshot)     full sync: pushes every active entry
+ *   - syncEntry(snapshot, slug)  delta: re-push a single entry
+ *   - removeEntry(slug)     delta: drop a deprecated/archived entry
+ *
+ * Policy: only entries with `metadata.corpus.status === "active"`
+ * (or unset, treated as active) are shipped. Deprecated/archived
+ * entries are removed from the backing engine.
+ */
+interface CorpusIndexerOptions {
+    readonly writer: WriterPort;
+    /** Optional chunker tuning. Defaults match the backing engine's caps. */
+    readonly chunker?: ChunkerOptions;
+}
+interface IndexReport {
+    readonly pushed: number;
+    readonly removed: number;
+    readonly skipped: number;
+    readonly chunkCount: number;
+}
+declare class CorpusIndexer {
+    private readonly opts;
+    constructor(opts: CorpusIndexerOptions);
+    /**
+     * Re-sync every active entry. Used at boot (cold-install) and by
+     * the admin `corpus reindex` command for drift recovery.
+     */
+    reindex(snapshot: CorpusWorkspaceSnapshot): Promise<IndexReport>;
+    /**
+     * Re-sync a single entry by slug. The lifecycle's `promote`
+     * workflow calls this immediately after writing the entry file.
+     */
+    syncEntry(snapshot: CorpusWorkspaceSnapshot, slug: string): Promise<{
+        chunkCount: number;
+    }>;
+    /** Drop one entry from the backing engine (deprecation, GDPR erase). */
+    removeEntry(slug: string): Promise<void>;
+    private pushEntry;
+}
+/**
+ * Promote workflow — turn an analyzed candidate into a published
+ * AIP-10 entry. The fan-out the plan describes:
+ *
+ *   1. Validate the promotion request (gate check, slug uniqueness)
+ *   2. Acquire workspace lock (atomicity across the multi-file write)
+ *   3. Write the entry file (AIP-10 conformant frontmatter + body)
+ *   4. Update _index.md (faceted catalog regen)
+ *   5. Sync to backing engine via CorpusIndexer
+ *   6. Append corpus.entry.promoted event to _log.md
+ *   7. Take the candidate row out of the sidecar (or update the
+ *      AIP-18 ITEM.md if it was materialized already)
+ *
+ * Idempotent on candidate.id — re-running promote for the same id
+ * reuses the existing entry path rather than duplicating. The
+ * workspace lock guards against concurrent promoters.
+ *
+ * Pure-ish: the workflow itself is logic + orchestration; every I/O
+ * effect goes through the injected reader/writer/emitter/indexer.
+ */
+interface PromoteOptions {
+    /** Workspace root inside FsPort (typically ""). */
+    readonly workspacePath: string;
+    /** Slug of the entry to create (or update, if it already exists). */
+    readonly entrySlug: string;
+    /** AIP-10 entry kind (principle | pattern | …). */
+    readonly entryKind: string;
+    /** Path of the entry within the workspace, e.g. entries/patterns/2026/foo.md */
+    readonly entryPath: string;
+    /** AIP-10 entry frontmatter to publish. */
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    /** Entry body (markdown after frontmatter). */
+    readonly body: string;
+    /**
+     * Optional candidate id to consume from a sidecar. When provided,
+     * the workflow removes the row from `collections/<name>/_candidates.yaml`
+     * on success (caller specifies the collection via `candidateSidecar`).
+     */
+    readonly candidateId?: string;
+    readonly candidateSidecarPath?: string;
+    /**
+     * Bypass the auto-promote gate. Used when a curator manually
+     * approves a candidate that failed the gate (corpus-review path).
+     * The emitted event still records the bypass.
+     */
+    readonly bypassGate?: boolean;
+}
+interface PromoteResult {
+    readonly entryPath: string;
+    readonly entryVersionToken: string;
+    readonly chunkCount: number;
+    readonly gatePassed: boolean;
+    readonly bypassed: boolean;
+}
+interface PromoteContext {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly identity: IdentityPort;
+    readonly indexer: CorpusIndexer;
+}
+declare class PromoteRejectedError extends Error {
+    readonly entrySlug: string;
+    readonly failures: ReadonlyArray<{
+        rule: string;
+        message: string;
+    }>;
+    constructor(entrySlug: string, failures: ReadonlyArray<{
+        rule: string;
+        message: string;
+    }>);
+}
+/**
+ * Workspace-scoped promoter. Construct once per workspace + per
+ * actor (identity is captured by the injected IdentityPort).
+ */
+declare class CorpusPromoter {
+    private readonly ctx;
+    constructor(ctx: PromoteContext);
+    promote(opts: PromoteOptions): Promise<PromoteResult>;
+}
+/**
+ * Attachment-binding axes — the dimensions a selector can target.
+ *
+ * An axis is a named dimension of the consuming subject (an operator,
+ * usually): its identity slug, the AIP-47 role it fulfils, the
+ * host-assigned position label, the capabilities it carries. Assets
+ * (playbook overlays, knowledge packs, skills) declare a `Selector`
+ * over these axes; the host supplies `Dimensions` for the subject and
+ * one matcher evaluates `selector ⊨ dimensions`.
+ *
+ * This package ships only the AIP-concept axes. Hosts register extra
+ * axes (org units, regions, compliance regimes, …) on their own
+ * registry — nothing here knows about any host's org model.
+ */
+interface AxisDefinition {
+    /** Axis id — the key used in `selector:` frontmatter and in Dimensions. */
+    readonly id: string;
+    /** AIP that owns the axis's value vocabulary, when one does. */
+    readonly aip?: number;
+    /** Doc line for catalog/UI surfaces. */
+    readonly description?: string;
+    /**
+     * Authoring-time ref check. Returns an error message, or null when
+     * the ref is acceptable. Hosts inject catalog-aware validators here
+     * (e.g. "role ref must be a known catalog slug").
+     */
+    readonly validateRef?: (ref: string) => string | null;
+    /**
+     * Canonicalize a ref before matching — absorbs the AIP-12 ref shapes
+     * (`operator/<slug>`, `ws://operators/<slug>`, globs → `"*"`).
+     */
+    readonly normalizeRef?: (ref: string) => string;
+}
+/** Matches any present value on the axis. */
+declare const ANY_REF = "*";
+/**
+ * Ref-shape normalizer for an axis addressed as `<singular>/<slug>` or
+ * `ws://<plural>/<slug>` — the shapes AIP-12 targets historically used.
+ * Globs (`<singular>/*`, `ws://<plural>/*`) collapse to `ANY_REF`.
+ */
+declare function prefixedRefNormalizer(singular: string, plural: string): (ref: string) => string;
+/** The operator's own slug — AIP-9 identity. */
+declare const identityAxis: AxisDefinition;
+/** The AIP-47 catalog role (job) the operator fulfils. */
+declare const roleAxis: AxisDefinition;
+/** The host-assigned, user-settable seat label (slugified). */
+declare const positionAxis: AxisDefinition;
+/** A capability slug the subject carries. */
+declare const capabilityAxis: AxisDefinition;
+declare const WELL_KNOWN_AXES: readonly AxisDefinition[];
+type AxisRegistry = Registry<AxisDefinition>;
+/**
+ * Axis registry seeded with the well-known AIP axes. Hosts pass their
+ * extra axes; ids must not collide with the well-known set.
+ */
+declare function createAxisRegistry(extra?: readonly AxisDefinition[]): AxisRegistry;
+/**
+ * Selector ⊨ Dimensions — the one matcher every attachment kind uses.
+ *
+ * A `Selector` is a small boolean expression over axis terms; the host
+ * supplies the subject's `Dimensions` (axis → value(s)) and the matcher
+ * decides whether the asset attaches. Scope (org / guild / workspace
+ * reach) is NOT expressed here — reach is decided by which corpus
+ * workspaces the host aggregates before matching ever runs.
+ */
+interface SelectorTerm {
+    readonly axis: string;
+    /** Refs the term accepts — OR within the list. `"*"` = any present value. */
+    readonly anyOf: readonly string[];
+}
+interface Selector {
+    /** Every term must match (AND). */
+    readonly allOf?: readonly SelectorTerm[];
+    /** At least one term must match (OR). */
+    readonly anyOf?: readonly SelectorTerm[];
+}
+/**
+ * The subject's axis values. A missing key means the subject has no
+ * value on that axis — terms against it fail (never match-all).
+ */
+type Dimensions = Readonly<Record<string, string | readonly string[] | undefined>>;
+interface MatchOptions {
+    /** Axis registry supplying per-axis `normalizeRef`. Optional — without it refs match verbatim. */
+    readonly axes?: AxisRegistry;
+}
+declare const EMPTY_SELECTOR: Selector;
+/** True when the selector has no terms at all. */
+declare function isEmptySelector(selector: Selector): boolean;
+/**
+ * Evaluate `selector ⊨ dimensions`.
+ *
+ * - An EMPTY selector matches NOTHING — an asset that wants everyone
+ *   in scope says so with an explicit `{ axis, anyOf: ["*"] }` term.
+ *   (Parity with the legacy empty-`targets` behavior.)
+ * - A term fails when the dimension is absent.
+ * - A term matches when its normalized refs intersect the dimension's
+ *   values, or when it carries `"*"` and the dimension is present.
+ */
+declare function matchesSelector(selector: Selector, dimensions: Dimensions, options?: MatchOptions): boolean;
+/**
+ * `selector:` frontmatter → Selector.
+ *
+ * Authoring shape (AIP-12 §selector):
+ *
+ *   selector:
+ *     role: sales-rep              # one ref
+ *     capability: [demo, forecast] # OR within the list
+ *
+ * Keys are axis ids; multiple keys AND together. The advanced
+ * `allOf:`/`anyOf:` long form is accepted verbatim for selectors that
+ * need OR across axes.
+ *
+ * Parsing never throws — malformed input returns null and the caller
+ * falls back to the legacy `targets` compile. A selector that silently
+ * dropped a malformed term could attach an overlay to the wrong
+ * operators; null keeps the file on its legacy binding instead.
+ */
+declare function parseSelectorFrontmatter(raw: unknown): Selector | null;
+/**
+ * Legacy `targets[]` / `binds_operator` → Selector compile.
+ *
+ * Permanent, not transitional: PLAYBOOK.md files authored before
+ * `selector:` live in real corpus workspaces and keep working forever.
+ *
+ * The legacy format is axis-AMBIGUOUS: a `kind: "operator"` ref (and
+ * `binds_operator`) historically held either an operator slug OR a
+ * role slug — the old matcher tried both. The compile preserves that
+ * exactly by putting each such ref in BOTH the identity and the role
+ * bucket of an `anyOf` selector. `kind: "role" | "skill" | "runtime"`
+ * refs compile to their own axes (a host that supplies no `skill`
+ * dimension keeps today's no-match behavior for skill targets).
+ */
+interface LegacyTarget {
+    readonly kind: string;
+    readonly ref: string;
+}
+declare function compileLegacyPlaybookBinding(targets: readonly LegacyTarget[], bindsOperator?: string): Selector;
+/**
+ * Attachment declarations — "this asset attaches to subjects matching
+ * this selector", evaluated by the one matcher.
+ *
+ * A host keeps a flat list of declarations (a knowledge pack attaches to
+ * a set of roles, a skill attaches to one position, …) and asks which
+ * ones a given subject's `Dimensions` satisfy. This replaces the older
+ * shape where bindings were grafted onto the subject (e.g. mutating a
+ * role handle at boot): the declaration is data, matching is a pure
+ * function, nothing is mutated.
+ *
+ * Asset-kind-agnostic and vendor-neutral — the `kind` is the host's
+ * (`"pack" | "skill" | …`); the selector axes are AIP concepts. `band` /
+ * `mode` are optional layering hints a host's mount step may honor; the
+ * matcher itself ignores them.
+ */
+/** What a declaration attaches — an opaque, host-typed ref under a kind. */
+interface AttachmentAsset<Kind extends string = string> {
+    readonly kind: Kind;
+    readonly ref: string;
+}
+/** An asset + the selector deciding which subjects it attaches to. */
+interface AttachmentDeclaration<Kind extends string = string> {
+    readonly asset: AttachmentAsset<Kind>;
+    /** Subjects whose `Dimensions` satisfy this attach the asset. */
+    readonly selector: Selector;
+    /** Optional precedence hint for the host's mount step (see AIP-10 bands). */
+    readonly band?: number;
+    /** Optional composition hint — `lens` vs `constraint`. */
+    readonly mode?: LayerMode;
+}
+interface MatchAttachmentsOptions {
+    /** Axis registry supplying per-axis `normalizeRef` for the matcher. */
+    readonly axes?: AxisRegistry;
+}
+/**
+ * The subset of `declarations` whose selector matches `dimensions`. Order
+ * is preserved; de-duplication of resulting refs is the caller's call
+ * (the same asset may attach via several declarations).
+ */
+declare function matchAttachments<Kind extends string>(declarations: readonly AttachmentDeclaration<Kind>[], dimensions: Dimensions, options?: MatchAttachmentsOptions): AttachmentDeclaration<Kind>[];
+/**
+ * Matched asset refs for one kind, de-duplicated, first-seen order — the
+ * flat shape most mount steps want.
+ */
+declare function matchAttachmentRefs<Kind extends string>(declarations: readonly AttachmentDeclaration<Kind>[], kind: Kind, dimensions: Dimensions, options?: MatchAttachmentsOptions): string[];
+/**
+ * Playbook surface types — shared by registry, resolver, lifecycle.
+ *
+ * AIP-12 PLAYBOOK frontmatter is rich (targets, kind, lock_check,
+ * evidence, status, supersedes, history, …). The registry parses
+ * the full shape; the public types here cover the fields the
+ * resolver and the lifecycle need.
+ *
+ * Corpus-specific extension fields (shadowTrafficPct, autoPromote,
+ * shadowMetrics, archiveReason, execution) live under
+ * `metadata.corpus.*` until the AIP-12 spec hoists them to first-class
+ * fields; we surface them as a typed namespace on the parsed playbook
+ * so callers don't dig into untyped frontmatter.
+ */
+type PlaybookStatus = "shadow" | "active" | "archived";
+type PlaybookKind = "overlay" | "block-replacement";
+type PlaybookTargetKind = "operator" | "role" | "skill" | "runtime";
+interface PlaybookTarget {
+    readonly kind: PlaybookTargetKind;
+    readonly ref: string;
+}
+interface PlaybookCorpusMeta {
+    /** 0..1 — fraction of traffic this shadow plays on. */
+    readonly shadowTrafficPct?: number;
+    /** Records the win-rate vs baseline + sample size. */
+    readonly shadowMetrics?: {
+        readonly sampleSize?: number;
+        readonly winRateVsBaseline?: number | null;
+        readonly lastEvaluatedAt?: string | null;
+    };
+    readonly autoPromote?: {
+        readonly enabled: boolean;
+        readonly metric: string;
+        readonly threshold: {
+            gte?: number;
+            lte?: number;
+        };
+        readonly minSampleSize: number;
+        readonly cooldown?: string;
+    };
+    readonly archiveReason?: string | null;
+    readonly execution?: "sandboxed" | "inProcess";
+    readonly authoredBy?: string;
+    readonly derivedFromGap?: string;
+    /** Free-form forward-compat. */
+    readonly [key: string]: unknown;
+}
+interface Playbook {
+    /** Workspace-relative path of the .md file. */
+    readonly path: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly status: PlaybookStatus;
+    readonly kind: PlaybookKind;
+    /** Priority for overlay ordering — higher first. Default 100. */
+    readonly priority: number;
+    readonly targets: readonly PlaybookTarget[];
+    /** Optional convenience — narrower than targets[]. */
+    readonly bindsOperator?: string;
+    /**
+     * The binding, always populated: parsed from `selector:` frontmatter
+     * when present, otherwise compiled from the legacy `targets[]` /
+     * `binds_operator` fields (see binding/legacy.ts). Matching goes
+     * through this — never through `targets` directly.
+     */
+    readonly selector: Selector;
+    /** Where `selector` came from — explicit frontmatter or legacy compile. */
+    readonly selectorSource: "selector" | "legacy";
+    readonly supersedes: readonly string[];
+    /** Markdown body — the overlay text. */
+    readonly body: string;
+    /** Corpus-namespaced extension fields (metadata.corpus.*). */
+    readonly corpus: PlaybookCorpusMeta;
+    /** Hash of file content for optimistic-concurrency CAS writes. */
+    readonly versionToken: string;
+    /** The raw parsed file — exposed for the lifecycle CAS path. */
+    readonly file: ParsedFile;
+}
+/** Selector for `listBy` queries. */
+interface PlaybookQuery {
+    readonly status?: PlaybookStatus | readonly PlaybookStatus[];
+    readonly operatorRef?: string;
+    /** Match on `kind` (overlay | block-replacement). */
+    readonly kind?: PlaybookKind;
+    /**
+     * Match playbooks bound to this slug (binds_operator OR targets[]).
+     * Accepts several slugs so a caller can match an operator by more than
+     * one handle it answers to — e.g. its identity slug AND the role slug it
+     * fulfils. A playbook matches if it binds/targets ANY of them.
+     *
+     * Sugar over `dimensions: { identity: slugs, role: slugs }` — prefer
+     * `dimensions` when the caller knows which axis each value belongs to.
+     */
+    readonly forOperatorSlug?: string | readonly string[];
+    /**
+     * Typed subject dimensions (axis → value(s)) evaluated against each
+     * playbook's `selector`. Wins over `forOperatorSlug` when both are set.
+     */
+    readonly dimensions?: Dimensions;
+}
+/**
+ * PlaybookRegistry — load + index every AIP-12 PLAYBOOK.md in the
+ * workspace's `playbooks/` directory.
+ *
+ * The registry is a thin read layer over a `CorpusWorkspaceSnapshot`:
+ *   - parses raw frontmatter into the typed `Playbook` shape,
+ *   - exposes O(1) lookups by slug,
+ *   - filters by status / kind / target operator on listBy().
+ *
+ * No FsPort dependency — the snapshot already carries the parsed
+ * files. The lifecycle layer is the one that writes; this registry
+ * is pure read.
+ */
+interface PlaybookRegistryOptions {
+    readonly snapshot: CorpusWorkspaceSnapshot;
+}
+declare class PlaybookRegistry {
+    private readonly bySlug;
+    private readonly all;
+    constructor(opts: PlaybookRegistryOptions);
+    list(): readonly Playbook[];
+    bySlugOrNull(slug: string): Playbook | null;
+    listBy(query?: PlaybookQuery): readonly Playbook[];
+}
+/**
+ * OperatorOverlayResolver — given an operator + conversation context,
+ * returns the playbook overlays to splice into the operator's prompt.
+ *
+ * Decision rules:
+ *   1. `active` playbooks targeting the operator are ALWAYS included.
+ *   2. `shadow` playbooks fire on a deterministic-hash subset of
+ *      conversations (`shadowTrafficPct`, default 0.10) — same
+ *      conversation always lands the same arm so an eval batch is
+ *      reproducible.
+ *   3. `archived` playbooks are never included (per the AIP-12
+ *      lifecycle terminal state).
+ *   4. Multiple active playbooks for the same operator stack by
+ *      `priority` (higher first). `kind: block-replacement` overrides
+ *      the operator's default block for the named trait;
+ *      `kind: overlay` appends to the prompt.
+ *
+ * Pure — no I/O. Consumes a `PlaybookRegistry` (read-only) + the
+ * resolution context. Lifecycle writes go through the lifecycle
+ * module.
+ */
+interface ResolveContext {
+    /**
+     * Slug of the operator the overlays apply to. Matches against
+     * `binds_operator` AND `targets[].ref` (with operator/* glob).
+     */
+    readonly operatorSlug: string;
+    /**
+     * The role (job) slug the operator fulfils, when distinct from its
+     * identity slug. Overlays bind by role — "the recruiting SOP for any
+     * recruiter" — so a playbook targeting this role matches every operator
+     * fulfilling it, not just one. Matched in addition to `operatorSlug`.
+     *
+     * @deprecated Supply `dimensions` instead — it carries role, position,
+     * capability, and any host-registered axis in one typed map.
+     */
+    readonly roleSlug?: string;
+    /**
+     * Typed subject dimensions (axis → value(s)) evaluated against each
+     * playbook's selector. When present, wins over the
+     * `operatorSlug`/`roleSlug` slug-pair matching.
+     */
+    readonly dimensions?: Dimensions;
+    /**
+     * Conversation id (or another stable bucketing token). Used to
+     * deterministically place a conversation into shadow-traffic
+     * buckets, so the same conversation consistently sees (or doesn't
+     * see) a given shadow overlay.
+     */
+    readonly conversationId?: string;
+}
+interface ResolvedOverlay {
+    readonly playbookSlug: string;
+    readonly status: PlaybookStatus;
+    readonly kind: Playbook["kind"];
+    readonly priority: number;
+    /** The overlay body. */
+    readonly body: string;
+    /** Audit attribution. */
+    readonly playbookPath: string;
+    /** True iff this overlay came from a shadow playbook + was sampled in. */
+    readonly shadowSampled: boolean;
+}
+interface ResolveResult {
+    readonly operatorSlug: string;
+    readonly overlays: readonly ResolvedOverlay[];
+}
+declare class OperatorOverlayResolver {
+    private readonly registry;
+    constructor(registry: PlaybookRegistry);
+    resolve(ctx: ResolveContext): ResolveResult;
+}
+/**
+ * Render-ready combination of overlays for a prompt. Returns the
+ * concatenated overlay bodies (priority-ordered, separated by
+ * `\n\n---\n\n`). `block-replacement` overlays are listed in the
+ * `replacements` field separately — the host's prompt assembler
+ * decides how to merge those into the operator's named blocks.
+ */
+interface RenderedOverlays {
+    readonly appendBlock: string;
+    readonly replacements: ReadonlyArray<{
+        readonly playbookSlug: string;
+        readonly body: string;
+    }>;
+}
+declare function renderOverlays(result: ResolveResult): RenderedOverlays;
+/**
+ * PlaybookLifecycle — activate / archive / supersede AIP-12
+ * playbooks, atomically.
+ *
+ * State machine (per the AIP-12 spec):
+ *   shadow   → active | archived
+ *   active   → archived
+ *   archived = terminal
+ *
+ * activate(slug):
+ *   1. Read current playbook (CAS via versionToken).
+ *   2. For each slug in playbook.supersedes that's currently active:
+ *      transition that slug to `archived` first.
+ *   3. Update the target playbook's status → "active", clear
+ *      shadowMetrics.lastEvaluatedAt to mark the activation moment.
+ *   4. Atomic file write (CAS).
+ *   5. Emit `playbook.activated` event.
+ *
+ * archive(slug, reason):
+ *   1. CAS read.
+ *   2. Set status → "archived", metadata.corpus.archiveReason = reason.
+ *   3. Atomic write.
+ *   4. Emit `playbook.archived`.
+ *
+ * Multi-file transaction guarded by FsPort.lock so a concurrent
+ * activate can't half-supersede.
+ */
+declare class PlaybookNotFoundError extends Error {
+    readonly slug: string;
+    constructor(slug: string);
+}
+declare class IllegalPlaybookTransitionError extends Error {
+    readonly slug: string;
+    readonly from: PlaybookStatus;
+    readonly to: PlaybookStatus;
+    constructor(slug: string, from: PlaybookStatus, to: PlaybookStatus);
+}
+interface PlaybookLifecycleOptions {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly identity: IdentityPort;
+    readonly workspacePath: string;
+}
+interface ActivateResult {
+    readonly slug: string;
+    readonly previousStatus: PlaybookStatus;
+    readonly versionToken: string;
+    readonly supersededSlugs: readonly string[];
+}
+interface ArchiveResult {
+    readonly slug: string;
+    readonly previousStatus: PlaybookStatus;
+    readonly versionToken: string;
+}
+declare class PlaybookLifecycle {
+    private readonly opts;
+    constructor(opts: PlaybookLifecycleOptions);
+    /**
+     * Transition `slug` from shadow → active. Cascades through
+     * `supersedes[]`: any currently-active playbook listed there is
+     * archived (with `archiveReason: superseded-by-<slug>`) in the
+     * same lock-guarded transaction.
+     */
+    activate(slug: string): Promise<ActivateResult>;
+    /**
+     * Transition `slug` → archived. Skip-no-op if already archived.
+     */
+    archive(slug: string, reason: string): Promise<ArchiveResult>;
+    private loadOne;
+    private loadRegistry;
+    private writeWith;
+    /** Build a transition attestation from current clock + given identity. */
+    private attestation;
+    private emitter;
+}
+/**
+ * PlaybookEvaluator — runs shadow vs baseline eval batches on AIP-12
+ * playbooks, records winRateVsBaseline + sample size, decides
+ * promotion readiness against `metadata.corpus.autoPromote`.
+ *
+ * Inputs (per eval-case the host hands us):
+ *   - prompt: the test prompt
+ *   - shadow.response: agent output WITH the playbook overlay applied
+ *   - baseline.response: agent output WITHOUT the overlay
+ *   - rubric: how to score both arms
+ *
+ * Output:
+ *   - winRateVsBaseline = fraction of cases where shadow.score >= baseline.score
+ *   - sampleSize = n
+ *   - readyForActivation = winRate >= threshold && n >= minSampleSize
+ *
+ * The evaluator does NOT itself activate the playbook — it writes
+ * shadowMetrics back to the PLAYBOOK.md (via the writer) and lets
+ * the curator's `activate` workflow decide. That keeps the
+ * audit chain clean: evaluator measures, curator decides.
+ *
+ * Pure logic. Backing IEvaluator + writer/emitter come in as ports.
+ */
+interface EvalCase {
+    /** Optional stable id — used in event payloads + per-case audit. */
+    readonly id?: string;
+    readonly prompt: string;
+    /** Agent output WITH the playbook overlay applied. */
+    readonly shadowResponse: string;
+    /** Agent output WITHOUT the overlay (baseline). */
+    readonly baselineResponse: string;
+}
+interface PlaybookBatchOptions {
+    readonly rubric: EvalRubricPort;
+    readonly cases: readonly EvalCase[];
+    /** Forwarded to evaluator + recorded in event payloads. */
+    readonly contextOverrides?: Partial<EvalContextPort>;
+}
+interface PlaybookBatchResult {
+    readonly playbookSlug: string;
+    readonly sampleSize: number;
+    readonly winRateVsBaseline: number;
+    readonly shadowAvgScore: number;
+    readonly baselineAvgScore: number;
+    readonly readyForActivation: boolean;
+    /** Per-case details — useful for the curator UI. */
+    readonly perCase: readonly {
+        readonly id?: string;
+        readonly shadowScore: number;
+        readonly baselineScore: number;
+        readonly winnerArm: "shadow" | "baseline" | "tie";
+    }[];
+}
+interface PlaybookEvaluatorOptions {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly identity: IdentityPort;
+    readonly workspacePath: string;
+    readonly evaluator: EvaluatorPort;
+}
+declare class PlaybookEvaluator {
+    private readonly opts;
+    constructor(opts: PlaybookEvaluatorOptions);
+    /**
+     * Run an eval batch against a single playbook. For each case:
+     *   1. Score shadow.response against rubric → shadowScore
+     *   2. Score baseline.response against rubric → baselineScore
+     *   3. shadow "wins" if shadowScore >= baselineScore
+     * Aggregate: winRateVsBaseline = wins / n.
+     *
+     * On completion: writes shadowMetrics back to the PLAYBOOK.md (CAS),
+     * emits a `corpus.playbook.evaluated` event (held outside the formal
+     * AIP-41 taxonomy until the spec adopts it).
+     */
+    runBatch(playbookSlug: string, batch: PlaybookBatchOptions): Promise<PlaybookBatchResult>;
+    private loadPlaybook;
+    private persistMetrics;
+    private appendCustomEvent;
+}
+/**
+ * @agentproto/corpus — composition of AIP-10/12/18/9/15/41.
+ *
+ * Spec: https://agentproto.sh/docs/corpus
+ */
+declare const SPEC_NAME: "agentcorpus/v1";
+declare const SPEC_VERSION: "0.1.0-alpha";
+export { ANY_REF, type AccessCaller, type AccessClassification, type AccessContext, type AccessDecision, type AccessModesMap, type ActivateResult, type AggregateOptions, type AggregateResult, type AipSchemaBundle, type AipSchemaKey, type ArchiveResult, type AttachmentAsset, type AttachmentDeclaration, type Attestation, type AttestationKind, type AutoPromoteConfig, type AutoPromoteRequirements, type AxisDefinition, type AxisRegistry, type BatchReport, type BuildOverlayOptions, type CalibrationOptions, type CandidateForGate, type CandidateRow, type CandidateStatus, CandidatesSidecar, type CandidatesSidecarOptions, type Capability, type CapabilityCaller, type CapabilityDecision, type CapabilityRule, type ChunkerOptions, ClaudeDistiller, type ClaudeDistillerOptions, ClockPort, type ConversationDoc, ConversationImporter, type ConversationImporterOptions, type ConversationSourcePort, type ConversationThreadRef, type ConversationTurn, type ConversationWindowSource, type CorpusAccessSpec, type CorpusEntryQuery, type CorpusEvent, CorpusEventEmitter, type CorpusEventEmitterOptions, type CorpusEventKind, type CorpusImporter, CorpusIndexer, type CorpusIndexerOptions, CorpusLinter, type CorpusLinterOptions, type CorpusPreset, type CorpusPresetBootstrapContext, CorpusPromoter, CorpusValidator, type CorpusValidatorOptions, CorpusVersionConflictError, CorpusWorkspaceReader, type CorpusWorkspaceReaderOptions, type CorpusWorkspaceSnapshot, CorpusWorkspaceWriter, type CorpusWorkspaceWriterOptions, type CustomLintRunner, DEFAULT_TRANSITIONS, type Dimensions, type DistillBinding, type DistillDescriptor, type DistillInput, type DistillPort, type DistillRegistry, type DistillReport, type DistillRunReport, DistillRunner, type DistillRunnerOptions, type DistillScope, type DistillSource, type DistillTarget, type DistilledItem, EMPTY_SELECTOR, type EntryLayout, type EvalCase, EvalContextPort, EvalRubricPort, EvaluatorPort, FetcherPort, type FileKind, FsLockHandle, FsPort, FsStat, type GateFailure, type GateResult, IdentityPort, IllegalPlaybookTransitionError, IllegalTransitionError, type ImportedSource, ImporterRunner, type ImporterRunnerOptions, type ImporterTarget, type IndexReport, type KbListLike, type KbMigrationConfig, KbMigrationImporter, type KbSourceLike, type LanguageFilter, type LayerMode, type LayerProvider, type LayerRef, type LayerShadow, type LintIssue, type LintReport, LocalFilesImporter, type LocalFilesImporterOptions, type MarkdownDoc, type MatchAttachmentsOptions, type MatchOptions, MemFs, OperatorOverlayResolver, OverlayFs, type OverlayFsOptions, type ParsedFile, type Playbook, type PlaybookBatchOptions, type PlaybookBatchResult, type PlaybookCorpusMeta, PlaybookEvaluator, type PlaybookEvaluatorOptions, type PlaybookKind, PlaybookLifecycle, type PlaybookLifecycleOptions, PlaybookNotFoundError, type PlaybookQuery, PlaybookRegistry, type PlaybookRegistryOptions, type PlaybookStatus, type PlaybookTarget, type PlaybookTargetKind, type PromoteContext, type PromoteOptions, PromoteRejectedError, type PromoteResult, type PushChunksInput, REFINED_KIND_SCHEMA, ReadOnlyFs, type RefinedKind, type RenderedOverlays, type ResolutionContext, type ResolveContext, type ResolveKnowledgeOptions, type ResolveLanguageFilterInput, type ResolveResult, type ResolvedEntry, type ResolvedOverlay, type ReviewerCalibration, type ReviewerScore, ReviewerTrackRecord, type ReviewerTrackRecordOptions, SPEC_NAME, SPEC_VERSION, type Selector, type SelectorTerm, SidecarDuplicateError, SidecarNotFoundError, type SinkItem, type SinkPort, type SinkPushResult, type SlugifyOptions, type SourceRef, type StackEntry, type StackRefPartition, type StackResolution, StackResolver, type StackSkip, type SyncReport, SyncRunner, type SyncRunnerOptions, type TrackRecordEntry, type TransitionCheck, type ValidationIssue, type ValidationResult, WELL_KNOWN_AXES, WHITEOUT_SUFFIX, WebImporter, type WebImporterOptions, type WriterChunk, type WriterPort, aggregateReviewerScores, appendAttestation, assertTransition, buildDistillPrompt, buildOverlayFromStack, canTransition, capabilityAxis, chunkText, compileLegacyPlaybookBinding, computeReviewerCalibration, createAxisRegistry, createDistillRegistry, enumerateWindowRefs, evaluateAccess, evaluateCapability, evaluateGate, extractAutoPromoteConfig, flattenPackRefs, identityAxis, isEmptySelector, isEntrySlug, isRefinedKind, isSourceSlug, makeAttestation, matchAttachmentRefs, matchAttachments, matchesLanguageFilter, matchesSelector, normalizeLanguageTag, parseItems, parseSelectorFrontmatter, parseWindowRef, partitionStackRefs, pearsonCorrelation, positionAxis, prefixedRefNormalizer, readAccessModes, readAccessSpec, readAttestations, readEntryLanguage, readOperatorLocale, readWorkspaceDefaultLanguage, renderOverlays, resolveKnowledge, resolveLanguageFilter, roleAxis, runDistill, scanDistilledSourceIds, slugify, transitionGraphFromCollection, uniqueSlug, windowRef, windowSlug };