@hawkeyexl/manni 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { InferenceProvider } from '@hawkeyexl/inference';
+import { DatabaseSync } from 'node:sqlite';
 
 /**
  * The error every tool under the umbrella throws for an operational failure.
@@ -300,6 +301,175 @@ declare function selectCollections(collections: readonly CollectionConfig[], nam
  */
 declare function isMember(collection: CollectionConfig, relPath: string): boolean;
 
+/**
+ * The derived metadata channel: values computed from git history, CODEOWNERS
+ * and the review record on GitHub or GitLab rather than written by hand.
+ *
+ * A derived value never merges into what the schema sees. `manni meta derive`
+ * stamps the managed fields (`derive.fields` in the config) into the
+ * document, and `validate` reports a managed field whose asserted value
+ * differs from the derived one as a finding. This module holds the shared
+ * vocabulary — which fields can be derived, from which sources — and the two
+ * pure steps every source feeds: comparing an asserted value with a derived
+ * one, and turning the stale comparisons into findings.
+ */
+
+/** The six built-in fields, in the order messages list them. */
+declare const DERIVABLE_FIELDS: readonly ["created", "last-updated", "authors", "owner", "reviewed-by", "last-reviewed"];
+type BuiltinDerivableField = (typeof DERIVABLE_FIELDS)[number];
+/**
+ * A managed field name: one of the six built-ins, or a key with an entry in
+ * `derive.commands`. The config parser guarantees one or the other.
+ */
+type DerivableField = string;
+declare function isBuiltinField(x: string): x is BuiltinDerivableField;
+/** Every source `derive.sources` may name; absent means all five. */
+declare const DERIVE_SOURCES: readonly ["git", "codeowners", "github", "gitlab", "command"];
+type DeriveSource = (typeof DERIVE_SOURCES)[number];
+/**
+ * One configured command, as `derive.commands` reads after parsing: the argv
+ * to run, the program first, and how long to wait for it.
+ */
+interface DeriveCommand {
+    run: readonly string[];
+    timeoutMs: number;
+}
+declare function isDeriveSource(x: string): x is DeriveSource;
+/**
+ * One fact a source produced, with where it came from. `evidence` is the
+ * short human-readable trail a finding quotes — a commit, a CODEOWNERS line,
+ * a pull request — so the reader can check the claim without re-running.
+ */
+interface DerivedValue {
+    value: unknown;
+    source: DeriveSource;
+    evidence: string;
+}
+/**
+ * Everything derived for one document. A `null` field means a source was
+ * consulted and had no fact to offer (a file with no commits yet, a path no
+ * CODEOWNERS rule matches); an absent field means no source answered for it.
+ */
+interface DerivedRecord {
+    file: string;
+    fields: Record<DerivableField, DerivedValue | null>;
+}
+/** Whether a source can answer at all; `reason` names the fix when not. */
+interface SourceStatus {
+    available: boolean;
+    reason?: string;
+}
+/** Which host the origin remote points at, and what to call the project there. */
+interface RemoteIdentity {
+    kind: "github" | "gitlab";
+    host: string;
+    /** `owner/repo` on GitHub; the full namespace path on GitLab. */
+    project: string;
+}
+/** One `APPROVED` review, the latest per reviewer. */
+interface Approval {
+    login: string;
+    /** ISO-8601. */
+    submittedAt: string;
+}
+/** The merged PR/MR that carried a commit. Immutable once merged, so cacheable. */
+interface MergedChange {
+    /** The PR number or MR iid. */
+    id: number;
+    /** ISO-8601. */
+    mergedAt: string;
+    /** Approvals only, deduplicated by login; the built-in clients order them oldest first. */
+    approvals: Approval[];
+}
+/**
+ * The review half of the derive context: the merged change behind a commit and
+ * who approved it. Reached through `gh` / `glab`, never an HTTP client — see
+ * `reviews.ts`.
+ */
+interface ReviewClient {
+    detect(): Promise<RemoteIdentity | null>;
+    /** Binary on PATH and authenticated for the host; `reason` names the fix. */
+    status(): Promise<SourceStatus>;
+    /** The merged PR/MR that contains the commit, or null (open, none, or unknown). */
+    mergedChangeFor(sha: string): Promise<MergedChange | null>;
+}
+/** One document as the sources see it. */
+interface DeriveInput {
+    label: string;
+    absPath: string;
+    content: string;
+    extracted: ExtractedMetadata;
+}
+/** What a derive run holds constant across every document it visits. */
+interface DeriveContext {
+    /** The run's working directory, the fallback when no config directory applies. */
+    cwd: string;
+    /** Directory the input labels are relative to, as `resolveRunConfig` settled it. */
+    base: string;
+    configDir?: string;
+    sources: readonly DeriveSource[];
+    fields: readonly DerivableField[];
+    /** CODEOWNERS path, when the config names one; resolved from `configDir`. */
+    codeowners?: string;
+    /** The `command` source's table, by the field each command derives; absent means none configured. */
+    commands?: Readonly<Record<string, DeriveCommand>>;
+    cache: boolean;
+    now: () => Date;
+    /** The review client for every repository in the run; the built-in `gh` / `glab` clients when absent. */
+    reviews?: ReviewClient;
+}
+/**
+ * How an asserted value stands against the derived one.
+ *
+ * - `current` — they agree.
+ * - `stale` — the document says one thing and a source says another.
+ * - `unset` — the document says nothing and a source has a value.
+ * - `unknown` — no source could answer, so nothing is claimed either way.
+ */
+type DerivedStatus = "current" | "stale" | "unset" | "unknown";
+interface DerivedField {
+    field: DerivableField;
+    /** What the document carries; absent when it carries nothing. */
+    asserted?: unknown;
+    /**
+     * What the sources say. `null` when they could not answer, which is exactly
+     * when `status` is `unknown`.
+     */
+    derived: unknown;
+    source?: DeriveSource;
+    evidence?: string;
+    status: DerivedStatus;
+    /** Whether `derive` wrote the value into the document. */
+    written: boolean;
+}
+/**
+ * The `schema` ref a stale-field finding carries, and so its baseline and
+ * rule identity: `derived:stale/derived`. Shaped like `check:<name>` and
+ * `external:owned` so `classifyRef` passes it through as a built-in id rather
+ * than resolving it as a cwd-relative file path, and reserved in the registry
+ * for the same reason those are.
+ */
+declare const DERIVED_STALE_SCHEMA = "derived:stale";
+/** The `keyword` every derived finding carries: no Ajv keyword produced it. */
+declare const DERIVED_KEYWORD = "derived";
+/**
+ * Compare what a document asserts with what a source derived.
+ *
+ * Pure. Lists compare as sets — order-insensitive, members deep-equal — so a
+ * reordered `authors:` is not a stale one. A missing or `null` derived value
+ * means the sources could not answer, which is `unknown` rather than a
+ * verdict either way. `written` is always false here; only `derive` writes.
+ */
+declare function compareDerived(field: DerivableField, asserted: unknown, derived: DerivedValue | null | undefined): DerivedField;
+/**
+ * The findings `validate` files for a document's managed fields: one per
+ * field that is `stale` or `unset`. Current and unknown fields file nothing.
+ *
+ * `lineFor` is the document's own pointer lookup, so a finding lands on the
+ * line the asserted key sits on; an unset field has no line.
+ */
+declare function staleFindings(fields: readonly DerivedField[], lineFor: (pointer: string) => number | undefined): FieldError[];
+
 interface SchemaOverride {
     /**
      * The glob, or globs, this override governs. A file matches when **any** of
@@ -403,6 +573,41 @@ interface CheckConfig {
     /** One SQL statement whose rows follow the finding column convention. */
     query: string;
 }
+/**
+ * One `derive.commands` entry: a program to run for a field's value, as the
+ * config spells it. `run` is the argv, the program first; `timeout` is in
+ * seconds. The derive context carries the parsed form, `DeriveCommand`.
+ */
+interface DeriveCommandConfig {
+    run: string[];
+    timeout?: number;
+}
+/**
+ * The derived channel: managed fields `manni meta derive` stamps from git
+ * history, CODEOWNERS, the review record on GitHub or GitLab, or a configured
+ * command, and `validate` checks for drift.
+ */
+interface DeriveConfig {
+    /**
+     * The managed fields. Each is one of `DERIVABLE_FIELDS` or a key of
+     * `commands`, never `$schema`, and never a key a manifest owns: a value
+     * with two authorities has none.
+     */
+    fields: DerivableField[];
+    /** Which sources to consult; absent means all of `DERIVE_SOURCES`. */
+    sources?: DeriveSource[];
+    /**
+     * CODEOWNERS path, relative to the config file's directory, when it is not
+     * in one of the places the codeowners source looks by itself. Checked for
+     * existence at run time, not here.
+     */
+    codeowners?: string;
+    /**
+     * The `command` source's table, by the field each command derives. A key
+     * is never a built-in field, `$schema`, or a key a manifest owns.
+     */
+    commands?: Record<string, DeriveCommandConfig>;
+}
 /** Defaults for the `fill` command; every key is overridable by a CLI flag. */
 interface FillConfig {
     provider?: string;
@@ -435,6 +640,11 @@ interface DocmetaConfig {
      * run's file set is the config-resolved corpus. See `CheckConfig`.
      */
     checks?: CheckConfig[];
+    /**
+     * The managed fields `derive` stamps and `validate` checks for drift. See
+     * `DeriveConfig`.
+     */
+    derive?: DeriveConfig;
     /**
      * Element paths to lift in addition to each format's convention. See
      * `parseElementPath` for the syntax.
@@ -702,12 +912,27 @@ interface ValidateOptions {
      * in charge, which itself defaults to off.
      */
     offline?: boolean;
+    /**
+     * `--no-cache` (false): ask GitHub or GitLab again rather than reading the
+     * review cache. It reaches the comparison and any check reading the
+     * `derived` table; absent leaves the cache on.
+     */
+    cache?: boolean;
     /**
      * `--no-checks` (false): skip the config's named corpus checks for this
      * run. Absent leaves them on — they still only run when the resolved file
      * set is the config-resolved corpus (proposal 0026).
      */
     checks?: boolean;
+    /**
+     * `--no-derive` (false): skip comparing each managed field (`derive.fields`
+     * in the config, proposal 0040) with what the evidence says. Absent leaves
+     * the comparison on whenever `derive:` is configured — on scoped runs too,
+     * since it is per file rather than a corpus rule.
+     */
+    derive?: boolean;
+    /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
+    now?: () => Date;
 }
 interface ValidateRun {
     results: ValidationResult[];
@@ -767,11 +992,60 @@ interface GetOptions {
      * `--offline` uniformly without knowing which subcommand needs it.
      */
     offline?: boolean;
+    /**
+     * `--no-cache` (false): ask GitHub or GitLab again rather than reading the
+     * review cache. Only `--derived` consults it, and only for `reviewed-by`
+     * and `last-reviewed`; absent leaves the cache on.
+     */
+    cache?: boolean;
+    /**
+     * Whether to resolve each requested field against the evidence — git
+     * history, CODEOWNERS, the review record, a configured command (proposals
+     * 0040, 0042). **On unless explicitly `false`** (proposal 0043): a read
+     * says what the value is and where it came from, and `--no-derived` is the
+     * way back to what the document alone stores.
+     *
+     * Only the requested fields a source can state are derived, so a field no
+     * source claims consults nothing and spawns nothing. Stdin is included in
+     * the run and simply derives nothing: a piped document has no path, so no
+     * source can speak for it, and that is an answer rather than an error.
+     */
+    derived?: boolean;
+    /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
+    now?: () => Date;
 }
 interface GetFileResult {
     file: string;
     present: boolean;
     values: Record<string, unknown>;
+    /**
+     * The evidence per requested field. A derivable field is always a key
+     * here: a `DerivedValue` when a source answered, `null` when every
+     * consulted source had nothing to say (a file with no commits, a path no
+     * CODEOWNERS rule matches). A requested field that is **not** derivable is
+     * absent from the record. Absent altogether under `--no-derived`, when no
+     * requested field is derivable, and on a file that did not parse.
+     */
+    derived?: Record<string, DerivedValue | null>;
+    /**
+     * The effective value per requested field (proposal 0043): the document's
+     * when it **carries the key**, the derived one otherwise, and absent when
+     * neither side has it. Presence is `Object.hasOwn`, not truthiness, so a
+     * document writing `owner: null` has asserted a value and no derived one
+     * replaces it — the same rule the `resolved` SQL view implements.
+     *
+     * Shaped exactly like `values`: one entry per requested field, `undefined`
+     * where nothing resolved, which JSON drops. Absent under `--no-derived`,
+     * and on a file that did not parse.
+     */
+    resolved?: Record<string, unknown>;
+    /**
+     * Which side answered, for the fields that resolved to something. A field
+     * neither the document nor any source has is absent, which is how a reader
+     * tells "unset" from "unset, but derivable". Absent under `--no-derived`,
+     * and on a file that did not parse.
+     */
+    origin?: Record<string, "asserted" | "derived">;
     /**
      * Why this file yielded no values, when it yielded none for a reason.
      *
@@ -833,6 +1107,12 @@ interface QueryOptions {
      * suppress.
      */
     offline?: boolean;
+    /**
+     * `--no-cache` (false): ask GitHub or GitLab again rather than reading the
+     * review cache. Only a statement naming the `derived` table consults it,
+     * and only for `reviewed-by` and `last-reviewed`; absent leaves it on.
+     */
+    cache?: boolean;
     /**
      * `--dry-run`: preview the statement's per-file changes — the diff it
      * would make, files untouched. Without it a mutating statement applies,
@@ -861,6 +1141,8 @@ interface QueryOptions {
      * applied — a flag that would silently mean nothing must refuse.
      */
     schemas?: string[];
+    /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
+    now?: () => Date;
 }
 /**
  * One thing a statement changed, in file-space terms. Cell-level kinds carry
@@ -1150,7 +1432,12 @@ type SkipReason =
 /** Writing it would leave the document failing its own schema. */
  | "schema-mismatch"
 /** The model declined to propose a value. */
- | "no-proposal";
+ | "no-proposal"
+/**
+ * The field is managed by `derive` (`derive.fields` in the config), so it
+ * was never sent for inference: only `manni meta derive` writes it.
+ */
+ | "managed";
 interface FilledField {
     /** JSON Pointer, e.g. "/title" — the same form `validate` reports. */
     field: string;
@@ -1261,6 +1548,91 @@ interface FillOptions {
 
 declare function runFill(opts: FillOptions): Promise<FillRun>;
 
+interface DeriveOptions {
+    inputs: string[];
+    /**
+     * `--collection <name>`, repeatable: stamp only the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with paths.
+     */
+    collections?: string[];
+    /** `--fields`: the managed fields to stamp this run; config `derive.fields` otherwise. */
+    fields?: string[];
+    /** `--sources`: the sources to consult; config `derive.sources`, else all four. */
+    sources?: string[];
+    /** `--dry-run`: report what would change and write nothing. */
+    dryRun?: boolean;
+    /** `--check`: implies `dryRun`; stale and unset fields are findings. */
+    check?: boolean;
+    /** Use the on-disk GitHub or GitLab review cache. Default true. */
+    cache?: boolean;
+    /** `--as` format override (extractor name). */
+    as?: string;
+    exts?: string[];
+    exclude?: string[];
+    configPath?: string;
+    /** `--no-config`: skip config discovery and use the built-in defaults. */
+    noConfig?: boolean;
+    cwd?: string;
+    /** Permit an input set that resolves to zero files (see `assertNonEmpty`). */
+    allowEmpty?: boolean;
+    /**
+     * `--no-gitignore` (false). Absent leaves config `respectGitignore:` in
+     * charge, which itself defaults to on.
+     */
+    respectGitignore?: boolean;
+    /** Diagnostics for the user; the CLI writes these to stderr. */
+    onNotice?: (message: string) => void;
+    /** Called once when a config governs the run, so the CLI can report it. */
+    onConfigLoaded?: (info: ConfigNotice) => void;
+    /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
+    now?: () => Date;
+    /** The review client, for every repository in the run. Test seam; default `gh` / `glab`. */
+    reviews?: ReviewClient;
+}
+interface DeriveFileResult {
+    file: string;
+    /** Extractor/format used; `unknown` when none matched the file. */
+    format: string;
+    /** One entry per requested field, in the requested order. Empty on `error`. */
+    fields: DerivedField[];
+    /**
+     * Whether writing the stale and unset fields changed the document, or
+     * would have but for `dryRun`. Computed from the writer's output, so a
+     * patch the format serializes to the same bytes is not a change.
+     */
+    changed: boolean;
+    /** Why the file could not be derived or written; the run goes on without it. */
+    error?: string;
+    /**
+     * Under `check`, the findings for this file: one per stale or unset field,
+     * at the field's line, plus one for an `error`. Absent otherwise.
+     */
+    findings?: FieldError[];
+}
+interface DeriveSummary {
+    files: number;
+    /** Files whose document changed, or would have under `dryRun`. */
+    changed: number;
+    /** Fields whose write reached the disk: always 0 under `dryRun` and `check`. */
+    written: number;
+    stale: number;
+    unset: number;
+    unknown: number;
+    errors: number;
+}
+interface DeriveRun {
+    results: DeriveFileResult[];
+    summary: DeriveSummary;
+    dryRun: boolean;
+    check: boolean;
+    /** One status per source the run consulted; a source nobody asked for is absent. */
+    sources: Partial<Record<DeriveSource, SourceStatus>>;
+    /** Where the run stood, for the SARIF reporter under `check`. See `ValidateRun.frame`. */
+    frame: FingerprintContext;
+}
+declare function runDerive(opts: DeriveOptions): Promise<DeriveRun>;
+
 /**
  * The `schema` ref a collision finding carries, and so its baseline and rule
  * identity: `external:owned/external`. Shaped like `check:<name>` so
@@ -1659,6 +2031,330 @@ interface ExternalMetadataFetchOptions {
 /** Fetch one remote manifest. Resolves to its text; throws `DocmetaError`. */
 declare function fetchExternalMetadata(url: string, opts?: ExternalMetadataFetchOptions): Promise<string>;
 
+/** Which sources can state each built-in field, in precedence order. */
+declare const FIELD_SOURCES: Readonly<Record<BuiltinDerivableField, readonly DeriveSource[]>>;
+interface DeriveResult {
+    /** Keyed by `DeriveInput.label`; every input has a record. */
+    records: Map<string, DerivedRecord>;
+    /**
+     * One status per source the run consulted. A source nobody asked for is
+     * absent, and so is whichever of `github` and `gitlab` the origin remote does
+     * not point at. Absent means not applicable here, never unavailable.
+     */
+    sources: Partial<Record<DeriveSource, SourceStatus>>;
+}
+/**
+ * Which sources can state a field, in precedence order: the built-in table
+ * for one of the six, `command` for a key of `commands`, nothing otherwise.
+ * A built-in never reaches the command arm, whatever the table says.
+ */
+declare function sourcesFor(field: DerivableField, commands?: Readonly<Record<string, DeriveCommand>>): readonly DeriveSource[];
+/** The sources a run consults: requested, and able to state a requested field. */
+declare function consultedSources(fields: readonly DerivableField[], sources: readonly DeriveSource[], commands?: Readonly<Record<string, DeriveCommand>>): DeriveSource[];
+/**
+ * Throw the exit-2 error for the first consulted source that could not
+ * answer. `hint` is the command's own way out, appended after a semicolon.
+ */
+declare function assertSourcesAvailable(sources: Partial<Record<DeriveSource, SourceStatus>>, hint?: string): void;
+declare function deriveMetadata(inputs: readonly DeriveInput[], ctx: DeriveContext): Promise<DeriveResult>;
+
+/** How a client reaches the binary; tests point `bin` at node and a fake script. */
+interface SpawnOptions {
+    /** Defaults to `gh` / `glab`, resolved on PATH. */
+    bin?: string;
+    /** Arguments placed before the command's own, such as a script for `node`. */
+    prefixArgs?: string[];
+    cwd: string;
+    /** Kill the child after this long. Default 30 s. */
+    timeoutMs?: number;
+}
+interface Run {
+    /** Exit code; `null` when a signal ended the child. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** A stream passed `MAX_OUTPUT_BYTES` and the child was killed. */
+    tooLarge: boolean;
+}
+/** The binary could not be started at all: nothing on PATH by that name. */
+declare class BinMissing extends Error {
+}
+/** One child, stdout collected, stderr drained and kept for the message. */
+declare function run(bin: string, args: string[], opts: SpawnOptions): Promise<Run>;
+
+/**
+ * The `command` source: a field derived by running whatever `derive.commands`
+ * names for it. The value is the program's stdout — JSON when it parses as
+ * JSON, the trimmed text otherwise, `null` when there is none.
+ *
+ * A command is spawned once per run, and its value copied into every
+ * document's record, unless its argv carries `{path}`, in which case it is
+ * spawned once per document with the document's label in place. The argv is
+ * never handed to a shell: what the config lists is what runs.
+ *
+ * The first failure ends the source for the whole run, with nothing further
+ * spawned: a program that is not on PATH, a timeout, a non-zero exit. A
+ * half-derived field would read as "the command said nothing" for the
+ * documents it never reached, which is the false green the whole channel
+ * refuses. Availability is reported, never thrown, as the other sources do.
+ */
+
+/** The argv token a per-file command carries where the document's label goes. */
+declare const PATH_PLACEHOLDER = "{path}";
+interface CommandSourceOptions {
+    /** Where the commands run: the config directory, else the run cwd. */
+    cwd: string;
+    /** Test seam: `bin` and `prefixArgs` replace the configured program. */
+    spawn?: Partial<SpawnOptions>;
+}
+interface CommandSourceResult {
+    status: SourceStatus;
+    /** By label; every input present when available, keyed by field within. */
+    records: Map<string, Record<string, DerivedValue | null>>;
+}
+/** Whether any argv element carries `{path}`, so the command runs once per document. */
+declare function isPerFile(command: DeriveCommand): boolean;
+/** The argv with every `{path}` replaced by the label, forward slashes as the run spells it. */
+declare function argvFor(command: DeriveCommand, label: string): string[];
+/**
+ * What a command's stdout means: nothing when blank, the parsed value when it
+ * is *structured* JSON, the trimmed text otherwise. A date or a version string
+ * stays a string; a list or an object arrives as one.
+ *
+ * Only `{`, `[` and `"` open a parse, and that boundary is the whole point.
+ * A bare scalar is text a person wrote, and reading it as JSON silently
+ * rewrites it: `1.10` becomes the number `1.1`, so a command reporting
+ * version 1.10 stamps 1.1 into the document. A field wants the characters
+ * the command printed. The structured forms are the reason a parse exists at
+ * all — `verified-against` takes an object, and a list of anchors is a list —
+ * and neither of those can be confused with prose.
+ */
+declare function valueOf(stdout: string): unknown;
+declare function deriveFromCommands(inputs: readonly DeriveInput[], commands: Readonly<Record<string, DeriveCommand>>, opts: CommandSourceOptions): Promise<CommandSourceResult>;
+
+/**
+ * The host and project an origin URL names, for the three spellings git
+ * writes: `git@host:owner/repo.git`, `https://[user@]host/owner/repo[.git]`,
+ * `ssh://git@host[:port]/owner/repo`. The project keeps every path segment,
+ * because a GitLab namespace can nest (`group/sub/repo`). Anything else —
+ * a local path, a bare host — is `null`. A local path is recognised before
+ * the scp form is tried, because git reads `C:/mirrors/repo.git` as a
+ * directory on drive C and the scp regex would read it as host `C`.
+ */
+declare function parseOriginUrl(url: string): {
+    host: string;
+    project: string;
+} | null;
+/**
+ * Which platform a host is, and so which CLI reaches it. A host whose name
+ * says `github` (github.com, github.example.com) is GitHub; one that says
+ * `gitlab` is GitLab. A host that says neither, such as `git.example.com`,
+ * is decided by the config: when exactly one of the `github` and `gitlab`
+ * sources is requested, that is the platform the operator named. Otherwise
+ * the answer is null, and the caller reports it as a source that cannot
+ * answer. Nothing is ever assumed: the `github` source applies to GitHub
+ * and the `gitlab` source to GitLab, and neither stands in for the other.
+ */
+declare function identityFromOrigin(host: string, project: string, requested?: readonly RemoteIdentity["kind"][]): RemoteIdentity | null;
+/**
+ * The base for both CLIs: the same spawn, the same failure ladder, the same
+ * status vocabulary. Subclasses supply the binary name and the lookups.
+ */
+declare abstract class CliClient implements ReviewClient {
+    protected readonly identity: RemoteIdentity | null;
+    protected readonly spawnOpts: SpawnOptions;
+    protected abstract readonly tool: "gh" | "glab";
+    constructor(identity: RemoteIdentity | null, spawnOpts: SpawnOptions);
+    detect(): Promise<RemoteIdentity | null>;
+    status(): Promise<SourceStatus>;
+    mergedChangeFor(sha: string): Promise<MergedChange | null>;
+    protected abstract lookup(identity: RemoteIdentity, sha: string): Promise<MergedChange | null>;
+    protected get bin(): string;
+    protected run(args: string[]): Promise<Run>;
+    private timeout;
+    /**
+     * Run a call whose stdout is JSON. A not-found answer is `null`; any other
+     * failure throws, naming the command the user can re-run by hand. The
+     * message quotes the tool's own name rather than `bin`, which under test
+     * is `node`.
+     */
+    protected json(args: string[]): Promise<unknown>;
+}
+/**
+ * GitHub through `gh`. Every call carries `--hostname` (or `-R host/project`)
+ * so a GHES origin is reached even when `gh`'s default host is github.com.
+ *
+ * - `gh api --hostname <host> repos/<project>/commits/<sha>/pulls`
+ * - if empty: `gh pr list --search <sha> --state merged --json number,mergedAt -R <host>/<project>`
+ *   (a squash-merged commit's original sha is only findable through search,
+ *   and a commit that came in through another repository is `[]` here, which
+ *   is a legitimate non-error)
+ * - `gh api --hostname <host> repos/<project>/pulls/<n>` only when the list
+ *   item does not say whether it merged
+ * - `gh api --hostname <host> repos/<project>/pulls/<n>/reviews?per_page=100`
+ */
+declare class GitHubClient extends CliClient {
+    protected readonly tool = "gh";
+    protected lookup(identity: RemoteIdentity, sha: string): Promise<MergedChange | null>;
+}
+/**
+ * GitLab through `glab`. `:fullpath` is substituted by glab from the current
+ * repository, which is why the client runs from the checkout.
+ *
+ * - `glab api --hostname <host> projects/:fullpath/repository/commits/<sha>/merge_requests`
+ * - `glab api --hostname <host> projects/:fullpath/merge_requests/<iid>/approvals`
+ *
+ * GitLab records who approved but not when, so every approval is stamped
+ * with the MR's `merged_at`; `deriveFromReviews` says so in the evidence.
+ */
+declare class GitLabClient extends CliClient {
+    protected readonly tool = "glab";
+    protected lookup(identity: RemoteIdentity, sha: string): Promise<MergedChange | null>;
+}
+/**
+ * The client for the repository at `root`: origin read with
+ * `git remote get-url origin`, the CLI chosen by `identityFromOrigin`, the
+ * result wrapped in the on-disk cache. No origin (or no git) yields a client
+ * whose `status()` says so; nothing throws here, because "no host" is a
+ * source being unavailable, and that is reported where sources are reported.
+ *
+ * The CLI is spawned in `root`, not in the caller's `cwd`: `glab` fills in
+ * `:fullpath` from the repository it runs in, and `gh` detects the
+ * repository the same way, so the child must run from the checkout this
+ * client answers for. `spawn.cwd` is the test seam that overrides that.
+ */
+declare function createReviewClient(root: string, opts: {
+    cwd: string;
+    cache: boolean;
+    cacheDir: string;
+    spawn?: Partial<SpawnOptions>;
+    /** The review sources the run requested; decides a host that names neither platform. */
+    requested?: readonly RemoteIdentity["kind"][];
+}): Promise<ReviewClient>;
+interface ReviewSourceInput {
+    label: string;
+    /** The newest body-changing commit; `null` for a working-tree document. */
+    sha: string | null;
+}
+interface ReviewFacts {
+    "reviewed-by": DerivedValue | null;
+    "last-reviewed": DerivedValue | null;
+}
+interface ReviewSourceResult {
+    status: SourceStatus;
+    /** By label. Empty when the source is unavailable. */
+    records: Map<string, ReviewFacts>;
+}
+/**
+ * `reviewed-by` is every approver of the merged change, in approval order,
+ * and every fact names the source of the host it came from, `github` or `gitlab`;
+ * `last-reviewed` is the UTC date of the latest approval. A document with no
+ * commit, no merged change, or a change nobody approved derives `null` for
+ * both. One host lookup per distinct sha, however many documents share it.
+ *
+ * An unavailable client is reported and never called: `status.reason` names
+ * the fix, and the caller decides whether that fails the run.
+ */
+declare function deriveFromReviews(inputs: readonly ReviewSourceInput[], client: ReviewClient): Promise<ReviewSourceResult>;
+
+/**
+ * The `derived` table (proposal 0040): what the evidence says each derivable
+ * field should be, one row per file, as a read-only SQL view beside `docs`.
+ *
+ * `query` builds it when a statement names it, and a corpus check that names
+ * it gets the same view — this module is what keeps the two from drifting.
+ * It is a view over a backing table rather than a table, so that SQLite's own
+ * `cannot modify derived because it is a view` refuses a write before any
+ * effect gate has to: the value it holds is not stored anywhere, and the only
+ * way to change it is to change the evidence. Both objects are transient: a
+ * `--db` export drops them before the handle closes, so a frozen derived
+ * value never outlives the run that computed it.
+ *
+ * The columns are the run's: the six built-in fields, then one per key of
+ * `derive.commands` (proposal 0042), so a command-derived field is read
+ * exactly as a built-in one is.
+ */
+
+/** The third table: the effective value per field, over `docs` and the rows. */
+declare const RESOLVED_VIEW = "resolved";
+/**
+ * Every column `resolved` carries, in order: `_path`, the `docs` data columns,
+ * then any derivable field `docs` does not already have, then `_origin` and
+ * `_sources`. A docs column that is also a derivable field appears once, in
+ * the position `docs` gives it, so the field list only ever adds.
+ *
+ * The system columns are skipped: `_path` is already first, and `_format`,
+ * `_present` and `_data` are facts about the document rather than values a
+ * source could state. A frontmatter key spelled `_origin` or `_sources` is
+ * skipped for the same reason a reserved one is — the column is taken.
+ */
+declare function resolvedColumns(docsColumns: readonly string[], commands?: Readonly<Record<string, DeriveCommand>>): string[];
+/**
+ * Does the statement name the `resolved` table? The twin of `mentionsDerived`,
+ * with the same shape and the same reason: `resolved` where a table goes, so
+ * that a column alias or the word inside `unresolved` does not build a view —
+ * and, more to the point, does not spawn git behind it.
+ */
+declare function mentionsResolved(sql: string): boolean;
+/**
+ * Create the `resolved` view: one row per `docs` row, holding the effective
+ * value of every field — what the document asserts when it carries the key,
+ * what the evidence derived otherwise — plus `_origin` saying which of the two
+ * answered, and the derived row's `_sources` unchanged. Call after
+ * `createDocsTable` and `createDerivedView`.
+ *
+ * **Presence is decided by `_data`, never by NULL.** A docs column is NULL
+ * both when the key is absent and when the document writes `key: null`, and
+ * those are opposite answers: an explicit null is an assertion, and the
+ * derived value must not overwrite it. So each field asks
+ * `json_type(_data, '$."field"') IS NOT NULL`, which is true for a JSON null
+ * and false for an absent key.
+ *
+ * `_origin` is `json_patch('{}', json_object(…))` over a CASE per field that
+ * yields `'asserted'`, `'derived'`, or NULL. `json_object` alone would keep
+ * the NULL members — a field neither side has would read as present with a
+ * null origin — and RFC 7396 merge-patch, which `json_patch` implements, is
+ * exactly the "a null member deletes the key" rule that drops them. One patch
+ * call does the whole object, so the shape stays flat however many fields the
+ * run carries.
+ *
+ * The join is a LEFT JOIN, so a file the derive run has no row for keeps its
+ * asserted values with an all-`asserted` `_origin` and a NULL `_sources`.
+ *
+ * Read-only by construction: SQLite refuses a write to a view with no
+ * INSTEAD OF trigger, and there is none. The effective value is not stored
+ * anywhere, so the only way to change it is to change the document or the
+ * evidence.
+ *
+ * Call it after `createDocsTable` and `createDerivedView`. SQLite accepts a
+ * view over a table that does not exist yet and fails only at the first read,
+ * as `no such table: main._derived_rows`, far from the call that got the
+ * order wrong.
+ */
+declare function createResolvedView(db: DatabaseSync, docsColumns: readonly string[], commands?: Readonly<Record<string, DeriveCommand>>): void;
+
+/** Where the GitHub or GitLab review cache lives, relative to the project root. `.manni/` is gitignored. */
+declare const REVIEW_CACHE_DIR = ".manni/meta/review-cache";
+/** The only entry format this version understands. */
+declare const REVIEW_CACHE_VERSION = 1;
+/** The GitHub or GitLab review cache: one immutable merged change per `host/project/sha`. */
+declare class ReviewCache {
+    private readonly dir;
+    private readonly enabled;
+    constructor(dir: string, enabled: boolean);
+    entryPath(key: string): string;
+    /** The cached change, or `undefined` for a miss. Never `null`: nulls are not stored. */
+    get(key: string): MergedChange | undefined;
+    set(key: string, value: MergedChange): void;
+}
+/**
+ * `client` with `mergedChangeFor` read through the cache. Only a merged
+ * answer is stored. With no identity there is no key, and every call goes
+ * straight through — which, for a client with no origin, is a `null`.
+ */
+declare function cachedClient(client: ReviewClient, cache: ReviewCache, identity: RemoteIdentity | null): ReviewClient;
+
 /**
  * Where the cache lives, relative to the project root.
  *
@@ -1873,6 +2569,17 @@ interface FillReportOptions {
 declare function renderFillGithub(run: FillRun): string;
 declare function renderFill(format: FillReportFormat, run: FillRun, opts?: FillReportOptions): string;
 
+/**
+ * Every value `derive -f` accepts: the same five as `validate`, because a
+ * `--check` run renders through validate's reporters. Stated as its own list
+ * so the two can grow apart without either edit reaching the other.
+ */
+declare const DERIVE_FORMATS: readonly ["pretty", "json", "github", "sarif", "junit"];
+type DeriveReportFormat = (typeof DERIVE_FORMATS)[number];
+declare function isDeriveFormat(value: string): value is DeriveReportFormat;
+type DeriveReportOptions = ReportOptions;
+declare function renderDerive(run: DeriveRun, format: DeriveReportFormat, opts?: DeriveReportOptions): string;
+
 /**
  * Reporter for `get`.
  *
@@ -1896,12 +2603,17 @@ interface GetReportOptions {
 /** `(unset)` for a missing field; JSON for anything that is not a string. */
 declare function stringifyValue(value: unknown): string;
 /**
- * One `<file>: <field>=<value>` line per requested field per file.
+ * One `<file>: <field>=<value>` line per requested field per file. The value
+ * is the **resolved** one where the run derived (proposal 0043), followed by
+ * the annotation saying which side answered; under `--no-derived` it is what
+ * the document stores, with no annotation at all.
  *
- * `quiet` hides a file only when **every** requested field is unset. A file
- * where one field resolved and another did not is still printed, `(unset)`
- * included: the flag hides files, never values, so `--quiet` can never be the
- * reason a value the user asked for went missing.
+ * `quiet` hides a file only when **every** requested field is unset, judged
+ * after resolving — so a page whose only `owner` comes from CODEOWNERS is
+ * shown, where before the flag hid it. A file where one field resolved and
+ * another did not is still printed, `(unset)` included: the flag hides files,
+ * never values, so `--quiet` can never be the reason a value the user asked
+ * for went missing.
  */
 declare function renderGet(results: GetFileResult[], fields: string[], opts?: GetReportOptions): string;
 
@@ -2006,4 +2718,4 @@ declare function extractorForExtension(ext: string): MetadataExtractor | undefin
 /** Extensions handled by implemented extractors (used for directory walks). */
 declare function supportedExtensions(): string[];
 
-export { type ApplyOptions, type BaselineSummary, COMMON_FORMATS, type CheckConfig, type CollectionConfig, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, type DocmetaConfig, DocmetaError, type DocumentRefTrust, EXTERNAL_DUPLICATE_SCHEMA, EXTERNAL_KEYWORD, EXTERNAL_METADATA_FETCH_MAX_BYTES, EXTERNAL_METADATA_FETCH_TIMEOUT_MS, EXTERNAL_OWNED_SCHEMA, type ExternalMetadataCollision, type ExternalMetadataConfig, type ExternalMetadataEntry, type ExternalMetadataFetchOptions, type ExternalMetadataIndex, type ExternalMetadataJoin, type ExternalMetadataValue, type ExtractOptions, type ExtractedMetadata, FILL_FORMATS, type FetchedSchema, type FieldError, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, INTEGRITY_SHAPE, type JunitOptions, type LoadExternalMetadataOptions, type LoadSchemaOptions, type LoadedConfig, type MergedMetadata, type MetadataExtractor, type MetadataPatch, PATH_JOIN, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, type ReadOptions, type ReportFormat, type ReportOptions, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SkipReason, type SourceLocation, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, classifyRef, collectSchemaPins, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, integrityOf, isCommonFormat, isFillFormat, isIntegrity, isMember, isQueryFormat, isReportFormat, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, rebaseConfigSchemaRefs, render, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, runFill, runGet, runQuery, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, selectCollections, stringifyValue, supportedExtensions, vendorFileName, writeFileAtomic };
+export { type ApplyOptions, type Approval, type BaselineSummary, BinMissing, type BuiltinDerivableField, COMMON_FORMATS, type CheckConfig, type CollectionConfig, type CommandSourceOptions, type CommandSourceResult, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, DERIVABLE_FIELDS, DERIVED_KEYWORD, DERIVED_STALE_SCHEMA, DERIVE_FORMATS, DERIVE_SOURCES, type DerivableField, type DeriveCommand, type DeriveCommandConfig, type DeriveConfig, type DeriveContext, type DeriveFileResult, type DeriveInput, type DeriveOptions, type DeriveReportFormat, type DeriveReportOptions, type DeriveResult, type DeriveRun, type DeriveSource, type DeriveSummary, type DerivedField, type DerivedRecord, type DerivedStatus, type DerivedValue, type DocmetaConfig, DocmetaError, type DocumentRefTrust, EXTERNAL_DUPLICATE_SCHEMA, EXTERNAL_KEYWORD, EXTERNAL_METADATA_FETCH_MAX_BYTES, EXTERNAL_METADATA_FETCH_TIMEOUT_MS, EXTERNAL_OWNED_SCHEMA, type ExternalMetadataCollision, type ExternalMetadataConfig, type ExternalMetadataEntry, type ExternalMetadataFetchOptions, type ExternalMetadataIndex, type ExternalMetadataJoin, type ExternalMetadataValue, type ExtractOptions, type ExtractedMetadata, FIELD_SOURCES, FILL_FORMATS, type FetchedSchema, type FieldError, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, GitHubClient, GitLabClient, INTEGRITY_SHAPE, type JunitOptions, type LoadExternalMetadataOptions, type LoadSchemaOptions, type LoadedConfig, type MergedChange, type MergedMetadata, type MetadataExtractor, type MetadataPatch, PATH_JOIN, PATH_PLACEHOLDER, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, RESOLVED_VIEW, REVIEW_CACHE_DIR, REVIEW_CACHE_VERSION, type ReadOptions, type RemoteIdentity, type ReportFormat, type ReportOptions, ReviewCache, type ReviewClient, type ReviewFacts, type ReviewSourceInput, type ReviewSourceResult, type Run, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SkipReason, type SourceLocation, type SourceStatus, type SpawnOptions, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, argvFor, assertSourcesAvailable, cachedClient, classifyRef, collectSchemaPins, compareDerived, consultedSources, createResolvedView, createReviewClient, deriveFromCommands, deriveFromReviews, deriveMetadata, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, identityFromOrigin, integrityOf, isBuiltinField, isCommonFormat, isDeriveFormat, isDeriveSource, isFillFormat, isIntegrity, isMember, isPerFile, isQueryFormat, isReportFormat, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mentionsResolved, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, parseOriginUrl, rebaseConfigSchemaRefs, render, renderDerive, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, resolvedColumns, run, runDerive, runFill, runGet, runQuery, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, selectCollections, sourcesFor, staleFindings, stringifyValue, supportedExtensions, valueOf, vendorFileName, writeFileAtomic };