@hawkeyexl/manni 2.1.0 → 2.3.0

package/dist/index.d.ts

@@ -128,14 +128,6 @@ interface MetadataExtractor {
     name: string;
     /** Lowercase file extensions this extractor handles, incl. dot (e.g. ".md"). */
     extensions: string[];
-    /**
-     * Whether this extractor can *read* — false for a format that is registered
-     * but not yet wired up. Every registered extractor sets it true today; it is
-     * kept because it is a distinct capability from writability, which is the
-     * presence of `apply`. A format can read without writing, and one being
-     * added could be declared before it can do either.
-     */
-    implemented: boolean;
     /**
      * Extract metadata from raw file content.
      *
@@ -358,6 +350,16 @@ declare function selectCollections(collections: readonly CollectionConfig[], nam
  */
 declare function isMember(collection: CollectionConfig, relPath: string): boolean;
 
+/** Vale's settings under `tools.vale`. */
+interface ValeToolConfig {
+    /** Vale's config file, as written, relative to `manni.config.yaml`. */
+    config?: string;
+}
+/** The document's top-level `tools:`, one namespace per outside tool. */
+interface ToolsConfig {
+    vale?: ValeToolConfig;
+}
+
 interface ConfigFile {
     /** Absolute path to the file. */
     path: string;
@@ -387,6 +389,12 @@ interface ConfigFile {
      * document *is* the tool's section, so it carries no family-wide keys.
      */
     collections: CollectionConfig[];
+    /**
+     * The document's top-level `tools:` (proposal 0052), an outside tool's
+     * settings, parsed once here for the same reason as `collections`. `{}` when
+     * the key is absent, and always `{}` for a `legacy` file.
+     */
+    tools: ToolsConfig;
     /**
      * The document's top-level `encryptionKey:` (proposal 0045), validated
      * here. Absent when the key is, and always absent for a `legacy` file, for
@@ -703,6 +711,14 @@ interface DerivedField {
      * reports it, when one does. `derive` writes there, never into the page.
      */
     manifest?: string;
+    /**
+     * Proposal 0047: the manifest a field other than `provenance` is written
+     * into, as the run reports it, when a manifest of the page's collections
+     * owns the key. Absent when the value goes to the page.
+     */
+    destination?: string;
+    /** The 1-based line of the key in `destination` after the write. Absent under `dryRun` and `check`. */
+    destinationLine?: number;
 }
 /**
  * The `schema` ref a stale-field finding carries, and so its baseline and
@@ -728,9 +744,14 @@ declare function compareDerived(field: DerivableField, asserted: unknown, derive
  * 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.
+ * line the asserted key sits on; an unset field has no line. `locate` answers
+ * for a value a manifest supplied (proposal 0047): the finding then names the
+ * manifest and its line, as every other manifest finding does.
  */
-declare function staleFindings(fields: readonly DerivedField[], lineFor: (pointer: string) => number | undefined): FieldError[];
+declare function staleFindings(fields: readonly DerivedField[], lineFor: (pointer: string) => number | undefined, locate?: (pointer: string) => {
+    file: string;
+    line?: number;
+} | undefined): FieldError[];
 
 interface SchemaOverride {
     /**
@@ -1367,183 +1388,205 @@ declare function runGet(opts: GetOptions): Promise<GetFileResult[]>;
 /** Ask a yes/no question; `true` only for a yes. */
 type Confirm = (question: string) => Promise<boolean>;
 
-interface QueryOptions {
-    /**
-     * One SQL statement. The table is `docs`; see the system columns below.
-     * May be empty when `db` is set — export without querying.
-     */
-    sql: string;
-    /**
-     * `--db`: also write the built database to this file, for any SQLite
-     * front-end (sqlite3, Datasette, duckdb) to open afterwards. The file is a
-     * regenerated artifact: an existing SQLite file at the path is overwritten,
-     * anything else is refused.
-     */
-    db?: string;
-    inputs: string[];
-    as?: string;
-    exclude?: string[];
-    exts?: string[];
-    configPath?: string;
-    /** `--no-config`: skip config discovery and use the built-in defaults. */
-    noConfig?: boolean;
-    /**
-     * `--collection <name>`, repeatable: run over the named configured
-     * collections instead of every declared one (proposal 0041). Cannot be
-     * combined with positional paths; `-` is allowed beside it.
-     */
-    collections?: string[];
-    cwd?: string;
-    /** Content for the `-` (stdin) input, injected by the CLI/tests. */
-    stdinContent?: string;
-    /** Permit an input set that resolves to zero files (see `assertNonEmpty`). */
-    allowEmpty?: boolean;
+/**
+ * The `schema` ref a collision finding carries, and so its baseline and rule
+ * identity: `external:owned/external`. Shaped like `check:<name>` 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 `check` is.
+ */
+declare const EXTERNAL_OWNED_SCHEMA = "external:owned";
+/**
+ * The `schema` ref of a duplicate-join finding (0039): two documents carry
+ * the same value of a join field, so one manifest entry matched both.
+ */
+declare const EXTERNAL_DUPLICATE_SCHEMA = "external:duplicate";
+/**
+ * The `keyword` every external-metadata finding carries: no Ajv keyword
+ * produced it.
+ */
+declare const EXTERNAL_KEYWORD = "external";
+/** The join that names documents by path, and the default. */
+declare const PATH_JOIN = "path";
+/** One value a manifest supplied, and where it was written. */
+interface ExternalMetadataValue {
+    value: unknown;
+    /** The collection whose manifest supplied it (proposal 0041). */
+    collection: string;
+    /** Manifest path as the run reports it: relative to the run's base, posix — or the URL. */
+    file: string;
+    /** 1-based line of the key in the manifest, when known. */
+    line?: number;
     /**
-     * `--no-gitignore` (false). Absent leaves config `respectGitignore:` in
-     * charge, which itself defaults to on.
+     * 1-based manifest line of every node inside `value`, keyed by the JSON
+     * Pointer relative to `value` (`/2/source/file`). A mapping member sits on
+     * its key's line, and a list item on the line its node starts. Present only
+     * when `value` is a mapping or a list with members; `line` answers for the
+     * value itself.
      */
-    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;
+    lines?: ReadonlyMap<string, number>;
+}
+/** One manifest entry, for the orphan checks. */
+interface ExternalMetadataEntry {
+    /** The collection whose manifest declared it (proposal 0041). */
+    collection: string;
+    /** `path`, or the frontmatter field this entry is keyed by. */
+    join: string;
+    /** Absolute document path, for a path entry. */
+    abs?: string;
+    /** The key exactly as written in the manifest. */
+    spelled: string;
+    /** Manifest path as the run reports it. */
+    file: string;
+    /** 1-based line of the entry in the manifest, when known. */
+    line?: number;
+}
+/** Every manifest of a run, loaded once and consulted per document. */
+interface ExternalMetadataIndex {
     /**
-     * `--offline`, accepted for surface parity with the other commands. DDL
-     * statements do resolve the corpus's schema set (0024), but only from disk
-     * and the bundled built-ins — a URL ref refuses with "vendor it first"
-     * before anything could fetch — so there is still no network dependency to
-     * suppress.
+     * Owned key -> every collection that owns it, with the manifest that does.
+     *
+     * A list rather than one entry, because two collections may legitimately
+     * each own the same key (0041 rule 5): `guides` and `blog` can both supply
+     * `owner`. Ambiguity only exists for a file that is a member of both, which
+     * is decided per file in `mergeExternalMetadata`.
      */
+    owners: ReadonlyMap<string, readonly {
+        collection: string;
+        file: string;
+    }[]>;
+    /** Path-joined manifests: absolute document path -> owned key -> value. */
+    byPath: ReadonlyMap<string, ReadonlyMap<string, ExternalMetadataValue>>;
+    /** Field-joined manifests: field -> value -> owned key -> value. */
+    byField: ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, ExternalMetadataValue>>>;
+    /** Every manifest entry, in manifest order. */
+    entries: readonly ExternalMetadataEntry[];
+}
+interface LoadExternalMetadataOptions {
+    /** Directory `externalMetadata[].file` and every manifest key resolve from. */
+    configDir: string;
+    /** Directory the run's file labels are relative to; manifests are reported the same way. */
+    base: string;
+    /** `--offline` / `offline:`: a URL manifest is refused rather than fetched (0038). */
     offline?: boolean;
+    /** Network timeout for a URL manifest; the schema fetch's default otherwise. */
+    timeoutMs?: number;
+    /** For tests: the environment `tokenEnv` is read from. */
+    env?: Record<string, string | undefined>;
+}
+/** A place a merged value lives, for a finding that must name it. */
+interface SourceLocation {
+    file: string;
+    line?: number;
+    col?: number;
+}
+/** A key the document carries that a manifest owns. */
+interface ExternalMetadataCollision {
+    key: string;
+    /** The owning manifest, as the run reports it. */
+    file: string;
+    /** The collection that manifest belongs to (proposal 0041). */
+    collection: string;
+}
+/** A field-joined entry a document matched (0039). */
+interface ExternalMetadataJoin {
+    field: string;
+    /** The value matched: the field's plaintext, decrypted first when the page holds it encrypted. */
+    value: string;
     /**
-     * `--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,
-     * matching `fill`'s convention (proposal 0025; 0022 recorded the original
-     * preview-by-default surface this revises).
-     */
-    dryRun?: boolean;
-    /**
-     * Values for the statement's named parameters (`$name`, `:name`, `@name`),
-     * keyed by bare name (a `$`/`:`/`@` prefix on a key is tolerated). Each
-     * value passes through the same `bindValue` the projection loader uses —
-     * booleans become 1/0, arrays and objects JSON text — so a bound parameter
-     * compares against a stored cell under exactly the encoding the cell got
-     * (proposal 0029). A parameter the SQL references with no entry here
-     * refuses: unbound would silently bind NULL and match nothing.
-     */
-    params?: Record<string, unknown>;
-    /**
-     * `-s/--schema`, repeatable: the schema set the run's DDL evolves — CLI
-     * precedence for the DDL planner *only* (proposal 0030). The per-file
-     * resolution walk is skipped and the deduped refs are the set; every guard
-     * inside the set (single local file for ADD, sole declarer for
-     * DROP/RENAME, builtin fork, URL refusal, the trust boundary) runs
-     * unchanged. Collection views keep following the config's resolution. A
-     * run whose statement produces no DDL effect refuses before anything is
-     * applied — a flag that would silently mean nothing must refuse.
+     * The field as the page holds it, when that differs from `value`: the
+     * ciphertext of an encrypted join field (proposal 0045). A finding about
+     * the join names this, never the plaintext.
      */
-    schemas?: string[];
+    pageValue?: string;
+    /** The manifest, as the run reports it. */
+    file: string;
+    /** The collection that manifest belongs to (proposal 0041). */
+    collection: string;
+}
+/** What `mergeExternalMetadata` hands back. */
+interface MergedMetadata {
+    /** The document's metadata with every owned key the manifest supplied. */
+    extracted: ExtractedMetadata;
     /**
-     * How to ask for a new encryption key when an `UPDATE` or `INSERT` writes
-     * a column its schema marks `x-manni-encrypt` and no key is available
-     * (proposal 0045). The CLI passes `terminalConfirm()`, which is
-     * `undefined` off a terminal; absent, such a write refuses (exit 2). A dry
-     * run never asks: it writes nothing.
+     * Owned keys the document itself also carried, in document order, each
+     * with the manifest that owns it — so the finding names it without a
+     * second lookup, and without a fallback for an index that is not there.
      */
-    confirm?: Confirm;
+    collisions: ExternalMetadataCollision[];
+    /** Field-joined entries this document matched, one per manifest at most. */
+    joins: ExternalMetadataJoin[];
     /**
-     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
-     * `process.env`; tests pass their own.
+     * Where a merged pointer's value lives. Answers only for a value the
+     * manifest supplied — a bare key or its `/key` pointer, and anything
+     * beneath it — and `undefined` for everything the document owns, which is
+     * what `lineFor` is for.
+     *
+     * The line is the deepest manifest node the pointer reaches, so
+     * `/citations/2` is the third item's line and `/citations/2/source/file`
+     * that member's. A pointer past what the manifest holds falls back to the
+     * nearest ancestor that exists, and at worst to the owned key's line.
      */
-    env?: NodeJS.ProcessEnv;
-    /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
-    now?: () => Date;
+    locate: (pointer: string) => SourceLocation | undefined;
 }
+/** The join an external-metadata config asks for: `path` unless it names a field. */
+declare function externalMetadataJoin(manifest: Pick<ExternalMetadataConfig, "join">): string;
 /**
- * One thing a statement changed, in file-space terms. Cell-level kinds carry
- * a `key` (a set, a deletion via `SET k = NULL` / `ALTER DROP COLUMN`, or a
- * key rename); file-level kinds carry the whole event (`cleared` — the block
- * stripped by DELETE; `created` — a file INSERT made; `renamed` — a `_path`
- * move). Exactly one kind per object.
+ * Load every manifest of every collection the run covers. Resolves to `null`
+ * when none of them declares one, which is every setup that existed before
+ * this feature.
+ *
+ * Every refusal is a `DocmetaError`: the manifest is a config-supplied input,
+ * and one that is missing or misshapen is the run's problem, not a
+ * document's (0014).
  */
-type QueryChange = {
-    file: string;
-    written: boolean;
-} & ({
-    key: string;
-    from: unknown;
-    to: unknown;
-} | {
-    key: string;
-    from: unknown;
-    deleted: true;
-} | {
-    key: string;
-    renamedFrom: string;
-    to: unknown;
-} | {
-    cleared: true;
-    from: Record<string, unknown>;
-} | {
-    created: true;
-    to: Record<string, unknown>;
-} | {
-    renamed: string;
-} | {
-    /** A DDL statement edited the schema itself (0024): `file` is the
-     * schema written — an in-place edit, or the fork of a builtin. */
-    schema: true;
-    op: "add" | "drop" | "rename";
-    key: string;
-    renamedTo?: string;
-    type?: string;
-    /** 0028: a declared type equal to a format name carries the format. */
-    format?: string;
-    /** 0028: a `CHECK (k IN (…))` on the added column carries the enum. */
-    enum?: (string | number)[];
-    required?: boolean;
-    forkedFrom?: string;
-} | {
-    /** A DDL side effect on the governing config file: a fork repoints the
-     * `schemas:` entry (`key: "schemas"`), an in-place edit of a pinned
-     * schema refreshes its pin (`key: "integrity"`). Disclosed as a change
-     * because the preview must name every file `--write` will touch. */
-    config: true;
-    key: string;
-    from: unknown;
-    to: unknown;
-});
-interface QueryRun {
-    /** Result column names, in SELECT order — present even for zero rows. */
-    columns: string[];
-    rows: Record<string, unknown>[];
-    /** Set when `db` was written: where, and how big the table is. */
-    db?: {
-        path: string;
-        files: number;
-        columns: number;
-    };
-    /**
-     * Present when the statement was a metadata edit: every cell it changed
-     * (empty when a mutating statement matched nothing). Absent on reads.
-     */
-    changes?: QueryChange[];
-    /**
-     * Where the run stood, in the same shape `ValidateRun.frame` carries — the
-     * path-normalization frame SARIF and JUnit need before they can name a file
-     * the way the repository does (proposal 0026). Constructed from the run's
-     * `cwd`, its config directory, and the directory file labels resolve
-     * against; absent only when a caller built a `QueryRun` by hand.
-     */
-    frame?: FingerprintContext;
-}
-declare function runQuery(opts: QueryOptions): Promise<QueryRun>;
+declare function loadExternalMetadata(collections: readonly CollectionConfig[], opts: LoadExternalMetadataOptions): Promise<ExternalMetadataIndex | null>;
+/**
+ * Merge the external metadata for one document into its extracted metadata.
+ *
+ * `label` is the document as the run spells it, relative to `base`; a path
+ * entry matches on the resolved absolute path, never on the spelling, so a
+ * positional run from a subdirectory finds the same entry a config-corpus
+ * run does. A field entry matches on the document's own value of the join
+ * field, wherever the document lives. Stdin never matches a path entry:
+ * there is no file behind it.
+ *
+ * `memberOf` names the collections this document belongs to, and only their
+ * manifests are consulted (0041 rule 4). It is the caller's `memberOf(...)`
+ * result, computed once per file.
+ *
+ * `present`, `format` and the document's own positions are untouched. A
+ * manifest key is not in the document, so `lineFor` keeps answering
+ * `undefined` for it, and `locate` answers instead.
+ *
+ * A join field the page holds encrypted (proposal 0045) is decrypted with
+ * `options.encryptionKey` before it is matched. With no key, and a manifest
+ * of this document's collections joining on that field, the run cannot match
+ * and refuses. A ciphertext that does not decrypt matches nothing.
+ */
+declare function mergeExternalMetadata(label: string, extracted: ExtractedMetadata, index: ExternalMetadataIndex | null, memberOf: readonly string[], base: string, options?: {
+    encryptionKey?: () => string | undefined;
+}): MergedMetadata;
+/** The `/key` pointer for an external-metadata finding, RFC 6901 escaped. */
+declare function externalMetadataPointer(key: string): string;
+/**
+ * Path entries naming no loaded document.
+ *
+ * `loaded` are the run's file labels, relative to `base`. Checked only when
+ * the run is the config corpus (the same invariant corpus checks use): a
+ * positional path means the operator chose to look at part of the corpus,
+ * and an entry for the rest is expected, not orphaned.
+ */
+declare function orphanEntries(index: ExternalMetadataIndex | null, loaded: readonly string[], base: string, collections?: readonly string[]): ExternalMetadataEntry[];
+/**
+ * Field entries no loaded document matched (0039). `matched` is field -> the
+ * values documents in the run carried, which the caller collects from each
+ * document's `joins` — so this runs after the per-file loop, under the same
+ * corpus invariant as `orphanEntries`.
+ */
+declare function orphanJoins(index: ExternalMetadataIndex | null, matched: ReadonlyMap<string, ReadonlySet<string>>, collections?: readonly string[]): ExternalMetadataEntry[];
+/** The operational error an orphan check raises, naming the first entry. */
+declare function orphanError(orphans: readonly ExternalMetadataEntry[]): DocmetaError;
 
 interface BuiltinInfo {
     id: string;
@@ -1673,199 +1716,213 @@ declare function schemaLoadOptions(args: {
 /** Load and return the JSON Schema object for a reference. */
 declare function loadSchema(ref: string, options?: LoadSchemaOptions): Promise<Record<string, unknown>>;
 
-interface SchemasInfo {
-    builtins: BuiltinInfo[];
-    formats: {
-        name: string;
-        extensions: string[];
-        implemented: boolean;
-        /** Whether `manni meta fill` can write metadata back to this format. */
-        writable: boolean;
-    }[];
-}
-declare function getSchemasInfo(): SchemasInfo;
-/**
- * Where a vendored schema lands by default.
- *
- * **Not** `.docmeta/`, which is gitignored wholesale and holds the schema and
- * proposal caches. A vendored schema is the opposite kind of artifact: it has
- * to be committed, because being in the consuming repository's own history is
- * the entire point of vendoring.
- */
-declare const DEFAULT_VENDOR_DIR = "./schema";
-interface VendorOptions {
-    /** The `http(s)` URL to download. */
-    url: string;
-    /** Directory for the vendored copy, relative to `cwd`. Default `./schema`. */
-    dir?: string;
-    /** `-c/--config`. Absent discovers a config, or creates one in `cwd`. */
-    configPath?: string;
-    cwd?: string;
-    /** Diagnostics for the user; the CLI writes these to stderr. */
-    onNotice?: (message: string) => void;
-    /** Fetch timeout, in ms. Defaults to the registry's. */
-    timeoutMs?: number;
-    /** Response size cap, in bytes. Defaults to the registry's. */
-    maxBytes?: number;
-}
-interface VendorResult {
-    /** The URL that was downloaded. */
-    url: string;
-    /** The vendored file, relative to `cwd`, posix-style. */
-    file: string;
-    /** The pin recorded for it. */
-    integrity: string;
-    /** Size of the vendored copy, in bytes. */
-    bytes: number;
-    /** The config that was written, relative to `cwd`, posix-style. */
-    config: string;
-    /** Whether that config had to be created. */
-    configCreated: boolean;
-    /** Whether an existing `schemas:` entry was replaced rather than appended. */
-    replaced: boolean;
-    /** Whether the downloaded bytes were identical to the copy already on disk. */
-    unchanged: boolean;
-}
 /**
- * The filename for a vendored schema, derived from the URL's last path segment.
+ * `x-manni-location` (proposal 0047): where a schema would like a top-level
+ * key's value stored, on the page or in external metadata.
  *
- * Sanitized rather than trusted: the segment reaches the filesystem, so
- * anything that is not an ordinary filename character is replaced, and a
- * leading dot is prefixed away so the copy cannot land as a hidden file that
- * directory walks skip.
- */
-declare function vendorFileName(url: string): string;
-/**
- * Download a remote schema into the repository and pin it.
+ * The keyword is registered on every Ajv meta builds (validator.ts), next to
+ * `x-manni-encrypt`, and like it records where it was evaluated. Ajv's own
+ * resolution is the walker, so a mark counts through `$ref`, `allOf` and a
+ * referenced built-in, and inside the `anyOf`, `oneOf` and `if`/`then`
+ * branches Ajv takes. Only top-level properties carry a preference; a nested
+ * mark is accepted and ignored. `Validator.locationPreferences` is the one
+ * question commands ask of it.
  *
- * The order of operations is the contract: everything that can refuse does so
- * *before* the network call or the write, so a refused run leaves the working
- * tree exactly as it found it.
- */
-declare function runVendorSchema(opts: VendorOptions): Promise<VendorResult>;
-
-/** Shared shapes for the `fill` command, split out to keep imports acyclic. */
+ * One schema marking one key both ways is judged twice. Through `properties`,
+ * `allOf` and local `$ref` alone, it is refused when the schema compiles.
+ * Across conditional branches it is not an error: Ajv evaluates failing
+ * branches too, so that schema gives the key no preference.
+ */
+/** The schema keyword. */
+declare const LOCATION_KEYWORD = "x-manni-location";
+/** Where a top-level key prefers to live. */
+type FieldLocation = "page" | "external";
+/** A key's preferred location, and the schema ref whose mark decided it. */
+interface LocationPreference {
+    location: FieldLocation;
+    /** The ref, as given to `locationPreferences`, whose mark won. */
+    schema: string;
+}
 
-/** Why a proposed value was not written. */
-type SkipReason = 
-/** Self-reported confidence was below the threshold. */
-"low-confidence"
-/** Writing it would leave the document failing its own schema. */
- | "schema-mismatch"
-/** The model declined to propose a value. */
- | "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;
-    required: boolean;
-    confidence: number;
-    reasoning: string;
+declare class Validator {
+    private readonly schemaOptions;
     /**
-     * Absent when the field was skipped. `(encrypted)` when the field's schema
-     * marks it `x-manni-encrypt`: the page holds the ciphertext, and no report
-     * prints either that or the plaintext (proposal 0045).
+     * How this validator's schemas are loaded: the disk cache location, its TTL,
+     * and `--offline`. Held per instance rather than read from module state, so
+     * two differently-configured validations in one process each get their own
+     * settings.
+     *
+     * That is not full isolation, and the difference matters to a library
+     * caller: `schema-registry` keeps a process-wide memo of fetched schemas, so
+     * one validator's successful fetch is visible to another. `offline` is
+     * excluded from that sharing on purpose — an offline validator will not be
+     * served something this process pulled over the network — but the memo is
+     * still shared, so a URL fetched once is not re-fetched per instance.
      */
-    value?: unknown;
-    written: boolean;
-    skipReason?: SkipReason;
+    constructor(schemaOptions?: LoadSchemaOptions);
+    private ajvByDialect;
     /**
-     * The value was written encrypted, because the field's schema marks it
-     * `x-manni-encrypt`. Absent otherwise.
+     * Keyed on the in-flight *promise*, not the resolved validator. Caching the
+     * result made this a check-then-act race: `fill` walks files through a worker
+     * pool, so every worker missed the cache while the first `loadSchema` was
+     * still pending and they all then compiled the same schema into the one
+     * shared per-dialect Ajv. Ajv registers a schema's `$id` on the first compile
+     * and rejects the second with "schema with key or id ... already exists",
+     * which took down any multi-file run against an $id-bearing schema. Storing
+     * the promise before the first await lets the losers await the one compile.
      */
-    encrypted?: boolean;
-}
-/**
- * One `meta-provenance` entry as `fill` writes it (proposal 0046): the model,
- * the JSON Pointers of the fields it proposed, escaped per RFC 6901, and the
- * confidence each was written at. Keys are the page's own spelling, so the
- * JSON report shows exactly what landed in the document. An entry `fill`
- * merged into keeps whatever else it held.
- */
-interface MetaProvenanceEntry {
-    "generated-by": string;
-    fields: string[];
-    confidence: Record<string, number>;
-    [other: string]: unknown;
-}
-/**
- * What became of this file's `meta-provenance` entry. It is never a failure:
- * neither outcome changes the summary or the exit code.
- */
-type MetaProvenanceReport = {
-    written: true;
-    entry: MetaProvenanceEntry;
-}
-/** The page's schemas, checked with the entry in place, reject it. */
- | {
-    written: false;
-    skipReason: "schema-mismatch";
-}
-/** A manifest in one of the page's collections owns the key. */
- | {
-    written: false;
-    skipReason: "manifest-owned";
-    manifest: string;
-}
-/**
- * The format's writer cannot hold a list of entries (an HTML or XML
- * attribute holds one line), so the fields were written without it.
- */
- | {
-    written: false;
-    skipReason: "unwritable";
-};
-interface FillFileResult {
-    file: string;
-    format: string;
-    schemas: string[];
-    fields: FilledField[];
-    /** Whether the file's content changed (false under --dry-run too). */
-    changed: boolean;
-    /** Parse failure, read-only format, or provider error. */
-    error?: string;
-    /** The filled document. Populated only when the caller asks for it. */
-    content?: string;
+    private cache;
+    private ajvFor;
     /**
-     * The `meta-provenance` entry recording the fields this run wrote
-     * (proposal 0046). Absent when no field was written; reported, not written,
-     * under `--dry-run`.
+     * Synchronous by design: the `cache.set` has to happen in the same tick as
+     * the miss, or a second caller can slip in before the entry exists.
      */
-    metaProvenance?: MetaProvenanceReport;
+    private compile;
+    private compileUncached;
+    /**
+     * The instance pointers of `data` that carry `x-manni-encrypt: true` under
+     * any schema in `refs`, in the order the validator evaluated them.
+     *
+     * A first pass with the recording keyword, so a mark counts exactly where
+     * validation would evaluate it. Only present values are marked: Ajv applies
+     * a property's subschema to a property that exists. A branch Ajv does not
+     * take (`then` behind a failing `if`, an `anyOf` branch after a passing
+     * one) contributes nothing; a branch it takes contributes its marks
+     * whether or not the branch passes, because a ciphertext routinely fails
+     * the rest of its own subschema until it is decrypted.
+     */
+    markedPointers(data: Record<string, unknown>, refs: string[]): Promise<Set<string>>;
+    /**
+     * The location each top-level key of `data` prefers under `refs`: `page` or
+     * `external`, and the ref whose `x-manni-location` mark decided it. A key no
+     * schema marks has no entry.
+     *
+     * A first pass with the recording keyword, as `markedPointers` runs, so a
+     * mark counts exactly where validation would evaluate it, and a nested mark
+     * is ignored. Only present values are marked: Ajv applies a property's
+     * subschema to a property that exists. A caller asking where a key it is
+     * about to write belongs passes `data` that already holds the candidate
+     * value. `$schema` is stripped first, as validation does.
+     *
+     * Refs are evaluated in order and a later ref's mark wins. A ref that says
+     * both values for one key unconditionally is refused when it compiles; one
+     * whose evaluated branches say both gives that key no preference.
+     */
+    locationPreferences(data: Record<string, unknown>, refs: string[]): Promise<Map<string, LocationPreference>>;
+    /**
+     * Validate `data` against every schema in `refs`. Returns all violations,
+     * each tagged with the schema that produced it and a source line via
+     * `lineFor`.
+     *
+     * `colFor` is optional and additive: this signature is public, so a fourth
+     * *required* parameter — or a widened third one — would be a consumer break.
+     * Callers with an extractor that supplies no column pass nothing and get the
+     * previous behavior exactly.
+     */
+    validate(data: Record<string, unknown>, refs: string[], lineFor: (pointer: string) => number | undefined, colFor?: (pointer: string) => number | undefined, 
+    /**
+     * Where a merged value lives when it is not in the document (proposal
+     * 0037): a manifest's file and line. Consulted before `lineFor`,
+     * and additive in the way `colFor` was.
+     */
+    locate?: (pointer: string) => SourceLocation | undefined): Promise<FieldError[]>;
 }
-interface FillSummary {
+
+/** Why a value was moved: its schema's mark, or a manifest that already owns the key. */
+type RelocateMoveReason = "preferred" | "owned";
+/** Why a value stayed on the side it is on. */
+type RelocateStayReason = "no-home" | "read-only-format" | "no-join-value" | "values-differ" | "url-manifest" | "unreadable";
+/** One value that moved, or would under `dryRun`. */
+type RelocateMove = {
+    key: string;
+    to: "page";
+    from: string;
+    reason: RelocateMoveReason;
+} | {
+    key: string;
+    to: "manifest";
+    manifest: string;
+    /** 1-based line of the key in the manifest afterwards. Absent under `dryRun`. */
+    line?: number;
+    reason: RelocateMoveReason;
+};
+/** One value that stayed on the wrong side. */
+interface RelocateStay {
+    key: string;
+    reason: RelocateStayReason;
+    /** The sentence the pretty reporter prints after `stays: `. Not part of the JSON shape. */
+    detail?: string;
+}
+interface RelocateFileResult {
+    /** The page, as the run labels it. */
+    file: string;
+    moved: RelocateMove[];
+    stayed: RelocateStay[];
+    /** A member page outside the paths the run named, reached through a `keys:` or `paths:` change. */
+    beyond: boolean;
+}
+interface RelocateManifestResult {
+    /** The manifest as the run reports it: relative to the run's base, or the URL. */
+    file: string;
+    collection: string;
+    /** Its index in the collection's `externalMetadata:` before the run. */
+    index: number;
+    created: boolean;
+    keysAdded: string[];
+    keysRemoved: string[];
+    /** The keys it owns afterwards. */
+    keys: string[];
+    /** Whether its last key went, so the config no longer declares it (R3). */
+    undeclared: boolean;
+    /** Pages beyond the named paths whose values a `keys:` change moves, or leaves. */
+    beyond: number;
+}
+interface RelocateConfigResult {
+    /** The config file relative to the working directory, or null when there is none and none was needed. */
+    file: string | null;
+    created: boolean;
+    collectionsCreated: {
+        name: string;
+        paths: string[];
+    }[];
+    pathsAdded: {
+        collection: string;
+        path: string;
+    }[];
+}
+interface RelocateSummary {
+    /** Pages with a value moved or stayed. */
     files: number;
-    changed: number;
-    written: number;
-    skipped: number;
-    /** Skipped fields that the schema lists as required — drives exit code 1. */
-    requiredSkipped: number;
-    errors: number;
-    costUsd: number;
-    cached: number;
+    moved: number;
+    stayed: number;
+    manifestsCreated: number;
 }
-interface FillRun {
-    results: FillFileResult[];
-    summary: FillSummary;
-    /** Echoed so JSON consumers and CI can assert which gate actually ran. */
-    threshold: number;
+interface RelocateResult {
     dryRun: boolean;
-    provider: string;
-    model: string;
-    /** True when the call cap stopped the run before every file was seen. */
-    turnsSpent: boolean;
+    config: RelocateConfigResult;
+    /** Every manifest the run creates, changes the keys of, or moves a value into or out of. */
+    manifests: RelocateManifestResult[];
+    files: RelocateFileResult[];
+    summary: RelocateSummary;
 }
-interface FillOptions {
+
+interface QueryOptions {
+    /**
+     * One SQL statement. The table is `docs`; see the system columns below.
+     * May be empty when `db` is set — export without querying.
+     */
+    sql: string;
+    /**
+     * `--db`: also write the built database to this file, for any SQLite
+     * front-end (sqlite3, Datasette, duckdb) to open afterwards. The file is a
+     * regenerated artifact: an existing SQLite file at the path is overwritten,
+     * anything else is refused.
+     */
+    db?: string;
     inputs: string[];
-    cliSchemas?: string[];
-    exts?: string[];
-    exclude?: string[];
-    /** `--as` format override (extractor name). */
     as?: string;
+    exclude?: string[];
+    exts?: string[];
     configPath?: string;
     /** `--no-config`: skip config discovery and use the built-in defaults. */
     noConfig?: boolean;
@@ -1890,429 +1947,590 @@ interface FillOptions {
     /** Called once when a config governs the run, so the CLI can report it. */
     onConfigLoaded?: (info: ConfigNotice) => void;
     /**
-     * `--offline`: never fetch a remote **schema**. Absent leaves config
-     * `offline:` in charge.
-     *
-     * Scoped to schema loading only. It says nothing about the inference
-     * provider, which is a separate network dependency with its own controls
-     * (`--provider mock`, `--dry-run`).
+     * `--offline`, accepted for surface parity with the other commands. DDL
+     * statements do resolve the corpus's schema set (0024), but only from disk
+     * and the bundled built-ins — a URL ref refuses with "vendor it first"
+     * before anything could fetch — so there is still no network dependency to
+     * suppress.
      */
     offline?: boolean;
-    /** Restrict proposals to these top-level fields. */
-    fields?: string[];
-    /** Minimum self-reported confidence to write (0-1). Default 0.7. */
-    confidence?: number;
-    /** Report proposals without writing them. */
-    dryRun?: boolean;
-    provider?: string;
-    model?: string;
-    /** Use the on-disk proposal cache. Default true. */
-    cache?: boolean;
-    /** Refuse a hosted provider: inference must run on this machine. */
-    local?: boolean;
-    /** Stop after this many inference calls. Counts calls, not files. */
-    maxTurns?: number;
-    /** Characters of document per call. Default 12000. */
-    chunkChars?: number;
-    /** Files inferred in parallel. Default 4. */
-    concurrency?: number;
-    /** Include the filled document on each result (used for stdin and tests). */
-    includeContent?: boolean;
-    /** Test seam: bypasses `makeProvider`, so no API key is needed. */
-    inferenceProvider?: InferenceProvider;
     /**
-     * How to ask for a new encryption key when a field its schema marks
-     * `x-manni-encrypt` is about to be written and no key is available
-     * (proposal 0045). The CLI passes `terminalConfirm()`, which is `undefined`
-     * off a terminal; absent, the run refuses (exit 2) before the first model
-     * request.
+     * `--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.
      */
-    confirm?: Confirm;
+    cache?: boolean;
     /**
-     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
-     * `process.env`; tests pass their own.
+     * `--dry-run`: preview the statement's per-file changes — the diff it
+     * would make, files untouched. Without it a mutating statement applies,
+     * matching `fill`'s convention (proposal 0025; 0022 recorded the original
+     * preview-by-default surface this revises).
      */
-    env?: NodeJS.ProcessEnv;
-}
-
-declare function runFill(opts: FillOptions): Promise<FillRun>;
-
-interface DeriveOptions {
-    inputs: string[];
+    dryRun?: boolean;
     /**
-     * `--collection <name>`, repeatable: stamp only the named configured
-     * collections instead of every declared one (proposal 0041). Cannot be
-     * combined with paths.
+     * Values for the statement's named parameters (`$name`, `:name`, `@name`),
+     * keyed by bare name (a `$`/`:`/`@` prefix on a key is tolerated). Each
+     * value passes through the same `bindValue` the projection loader uses —
+     * booleans become 1/0, arrays and objects JSON text — so a bound parameter
+     * compares against a stored cell under exactly the encoding the cell got
+     * (proposal 0029). A parameter the SQL references with no entry here
+     * refuses: unbound would silently bind NULL and match nothing.
      */
-    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;
+    params?: Record<string, unknown>;
     /**
-     * `--no-gitignore` (false). Absent leaves config `respectGitignore:` in
-     * charge, which itself defaults to on.
+     * `-s/--schema`, repeatable: the schema set the run's DDL evolves — CLI
+     * precedence for the DDL planner *only* (proposal 0030). The per-file
+     * resolution walk is skipped and the deduped refs are the set; every guard
+     * inside the set (single local file for ADD, sole declarer for
+     * DROP/RENAME, builtin fork, URL refusal, the trust boundary) runs
+     * unchanged. Collection views keep following the config's resolution. A
+     * run whose statement produces no DDL effect refuses before anything is
+     * applied — a flag that would silently mean nothing must refuse.
      */
-    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;
+    schemas?: string[];
     /**
-     * How to ask for a new encryption key when a field its schema marks
-     * `x-manni-encrypt` is about to be stamped and no key is available
-     * (proposal 0045). The CLI passes `terminalConfirm()`, which is `undefined`
-     * off a terminal; absent, such a stamp refuses (exit 2). A dry run never
-     * asks: it writes nothing.
+     * How to ask for a new encryption key when an `UPDATE` or `INSERT` writes
+     * a column its schema marks `x-manni-encrypt` and no key is available
+     * (proposal 0045). The CLI passes `terminalConfirm()`, which is
+     * `undefined` off a terminal; absent, such a write refuses (exit 2). A dry
+     * run never asks: it writes nothing.
      */
     confirm?: Confirm;
+    /**
+     * Called with relocate's result when a write's P1 offer was accepted and
+     * the values moved (proposal 0047), so the CLI can print relocate's report.
+     */
+    onRelocated?: (result: RelocateResult) => void;
     /**
      * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
      * `process.env`; tests pass their own.
      */
     env?: NodeJS.ProcessEnv;
-    /**
-     * `--generated-by <name>` (proposal 0046): the machine uncommitted body
-     * lines go to, or the lines a `<path>:L1-L2` positional names. Absent reads
-     * `MANNI_GENERATED_BY` from `env`; an empty value is unset either way.
-     */
-    generatedBy?: string;
+    /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
+    now?: () => Date;
 }
-interface DeriveFileResult {
+/**
+ * One thing a statement changed, in file-space terms. Cell-level kinds carry
+ * a `key` (a set, a deletion via `SET k = NULL` / `ALTER DROP COLUMN`, or a
+ * key rename); file-level kinds carry the whole event (`cleared` — the block
+ * stripped by DELETE; `created` — a file INSERT made; `renamed` — a `_path`
+ * move). Exactly one kind per object.
+ *
+ * `manifest` (proposal 0047) names the external-metadata manifest the change
+ * lands in, as the run reports it, when it lands in one: an owned key's set,
+ * removal or rename, a created file's owned keys, a stripped document's
+ * entry, or a moved document's entry.
+ */
+type QueryChange = {
     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[];
+    written: boolean;
+    manifest?: string;
+} & ({
+    key: string;
+    from: unknown;
+    to: unknown;
+} | {
+    key: string;
+    from: unknown;
+    deleted: true;
+} | {
+    key: string;
+    renamedFrom: string;
+    to: unknown;
+} | {
+    cleared: true;
+    from: Record<string, unknown>;
+} | {
+    created: true;
+    to: Record<string, unknown>;
+} | {
+    renamed: string;
+} | {
+    /** A DDL statement edited the schema itself (0024): `file` is the
+     * schema written — an in-place edit, or the fork of a builtin. */
+    schema: true;
+    op: "add" | "drop" | "rename";
+    key: string;
+    renamedTo?: string;
+    type?: string;
+    /** 0028: a declared type equal to a format name carries the format. */
+    format?: string;
+    /** 0028: a `CHECK (k IN (…))` on the added column carries the enum. */
+    enum?: (string | number)[];
+    required?: boolean;
+    forkedFrom?: string;
+} | {
+    /** A DDL side effect on the governing config file: a fork repoints the
+     * `schemas:` entry (`key: "schemas"`), an in-place edit of a pinned
+     * schema refreshes its pin (`key: "integrity"`). Disclosed as a change
+     * because the preview must name every file `--write` will touch. */
+    config: true;
+    key: string;
+    from: unknown;
+    to: unknown;
+});
+interface QueryRun {
+    /** Result column names, in SELECT order — present even for zero rows. */
+    columns: string[];
+    rows: Record<string, unknown>[];
+    /** Set when `db` was written: where, and how big the table is. */
+    db?: {
+        path: string;
+        files: number;
+        columns: number;
+    };
     /**
-     * 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.
+     * Present when the statement was a metadata edit: every cell it changed
+     * (empty when a mutating statement matched nothing). Absent on reads.
      */
-    changed: boolean;
-    /** Why the file could not be derived or written; the run goes on without it. */
-    error?: string;
+    changes?: QueryChange[];
     /**
-     * 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.
+     * Where the run stood, in the same shape `ValidateRun.frame` carries — the
+     * path-normalization frame SARIF and JUnit need before they can name a file
+     * the way the repository does (proposal 0026). Constructed from the run's
+     * `cwd`, its config directory, and the directory file labels resolve
+     * against; absent only when a caller built a `QueryRun` by hand.
      */
-    findings?: FieldError[];
+    frame?: FingerprintContext;
 }
-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;
-    /**
-     * `provenance` ranges whose write reached the disk (proposal 0046): always
-     * 0 under `dryRun` and `check`. Present only when the run derives
-     * `provenance`.
-     */
-    ranges?: number;
-    stale: number;
-    unset: number;
-    unknown: number;
-    errors: number;
+declare function runQuery(opts: QueryOptions): Promise<QueryRun>;
+
+interface SchemasInfo {
+    builtins: BuiltinInfo[];
+    formats: {
+        name: string;
+        extensions: string[];
+        /** Whether `manni meta fill` can write metadata back to this format. */
+        writable: boolean;
+    }[];
 }
-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$1>>;
-    /** Where the run stood, for the SARIF reporter under `check`. See `ValidateRun.frame`. */
-    frame: FingerprintContext;
+declare function getSchemasInfo(): SchemasInfo;
+/**
+ * Where a vendored schema lands by default.
+ *
+ * **Not** `.docmeta/`, which is gitignored wholesale and holds the schema and
+ * proposal caches. A vendored schema is the opposite kind of artifact: it has
+ * to be committed, because being in the consuming repository's own history is
+ * the entire point of vendoring.
+ */
+declare const DEFAULT_VENDOR_DIR = "./schema";
+interface VendorOptions {
+    /** The `http(s)` URL to download. */
+    url: string;
+    /** Directory for the vendored copy, relative to `cwd`. Default `./schema`. */
+    dir?: string;
+    /** `-c/--config`. Absent discovers a config, or creates one in `cwd`. */
+    configPath?: string;
+    cwd?: string;
+    /** Diagnostics for the user; the CLI writes these to stderr. */
+    onNotice?: (message: string) => void;
+    /** Fetch timeout, in ms. Defaults to the registry's. */
+    timeoutMs?: number;
+    /** Response size cap, in bytes. Defaults to the registry's. */
+    maxBytes?: number;
+}
+interface VendorResult {
+    /** The URL that was downloaded. */
+    url: string;
+    /** The vendored file, relative to `cwd`, posix-style. */
+    file: string;
+    /** The pin recorded for it. */
+    integrity: string;
+    /** Size of the vendored copy, in bytes. */
+    bytes: number;
+    /** The config that was written, relative to `cwd`, posix-style. */
+    config: string;
+    /** Whether that config had to be created. */
+    configCreated: boolean;
+    /** Whether an existing `schemas:` entry was replaced rather than appended. */
+    replaced: boolean;
+    /** Whether the downloaded bytes were identical to the copy already on disk. */
+    unchanged: boolean;
 }
-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
- * `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 `check` is.
+ * The filename for a vendored schema, derived from the URL's last path segment.
+ *
+ * Sanitized rather than trusted: the segment reaches the filesystem, so
+ * anything that is not an ordinary filename character is replaced, and a
+ * leading dot is prefixed away so the copy cannot land as a hidden file that
+ * directory walks skip.
  */
-declare const EXTERNAL_OWNED_SCHEMA = "external:owned";
+declare function vendorFileName(url: string): string;
 /**
- * The `schema` ref of a duplicate-join finding (0039): two documents carry
- * the same value of a join field, so one manifest entry matched both.
+ * Download a remote schema into the repository and pin it.
+ *
+ * The order of operations is the contract: everything that can refuse does so
+ * *before* the network call or the write, so a refused run leaves the working
+ * tree exactly as it found it.
  */
-declare const EXTERNAL_DUPLICATE_SCHEMA = "external:duplicate";
+declare function runVendorSchema(opts: VendorOptions): Promise<VendorResult>;
+
+/** Shared shapes for the `fill` command, split out to keep imports acyclic. */
+
+/** Why a proposed value was not written. */
+type SkipReason = 
+/** Self-reported confidence was below the threshold. */
+"low-confidence"
+/** Writing it would leave the document failing its own schema. */
+ | "schema-mismatch"
+/** The model declined to propose a value. */
+ | "no-proposal"
 /**
- * The `keyword` every external-metadata finding carries: no Ajv keyword
- * produced it.
+ * The field is managed by `derive` (`derive.fields` in the config), so it
+ * was never sent for inference: only `manni meta derive` writes it.
  */
-declare const EXTERNAL_KEYWORD = "external";
-/** The join that names documents by path, and the default. */
-declare const PATH_JOIN = "path";
-/** One value a manifest supplied, and where it was written. */
-interface ExternalMetadataValue {
-    value: unknown;
-    /** The collection whose manifest supplied it (proposal 0041). */
-    collection: string;
-    /** Manifest path as the run reports it: relative to the run's base, posix — or the URL. */
-    file: string;
-    /** 1-based line of the key in the manifest, when known. */
-    line?: number;
+ | "managed";
+interface FilledField {
+    /** JSON Pointer, e.g. "/title" — the same form `validate` reports. */
+    field: string;
+    required: boolean;
+    confidence: number;
+    reasoning: string;
     /**
-     * 1-based manifest line of every node inside `value`, keyed by the JSON
-     * Pointer relative to `value` (`/2/source/file`). A mapping member sits on
-     * its key's line, and a list item on the line its node starts. Present only
-     * when `value` is a mapping or a list with members; `line` answers for the
-     * value itself.
+     * Absent when the field was skipped. `(encrypted)` when the field's schema
+     * marks it `x-manni-encrypt`: the page holds the ciphertext, and no report
+     * prints either that or the plaintext (proposal 0045).
      */
-    lines?: ReadonlyMap<string, number>;
-}
-/** One manifest entry, for the orphan checks. */
-interface ExternalMetadataEntry {
-    /** The collection whose manifest declared it (proposal 0041). */
-    collection: string;
-    /** `path`, or the frontmatter field this entry is keyed by. */
-    join: string;
-    /** Absolute document path, for a path entry. */
-    abs?: string;
-    /** The key exactly as written in the manifest. */
-    spelled: string;
-    /** Manifest path as the run reports it. */
-    file: string;
-    /** 1-based line of the entry in the manifest, when known. */
-    line?: number;
-}
-/** Every manifest of a run, loaded once and consulted per document. */
-interface ExternalMetadataIndex {
+    value?: unknown;
+    written: boolean;
+    skipReason?: SkipReason;
     /**
-     * Owned key -> every collection that owns it, with the manifest that does.
-     *
-     * A list rather than one entry, because two collections may legitimately
-     * each own the same key (0041 rule 5): `guides` and `blog` can both supply
-     * `owner`. Ambiguity only exists for a file that is a member of both, which
-     * is decided per file in `mergeExternalMetadata`.
+     * The value was written encrypted, because the field's schema marks it
+     * `x-manni-encrypt`. Absent otherwise.
      */
-    owners: ReadonlyMap<string, readonly {
-        collection: string;
-        file: string;
-    }[]>;
-    /** Path-joined manifests: absolute document path -> owned key -> value. */
-    byPath: ReadonlyMap<string, ReadonlyMap<string, ExternalMetadataValue>>;
-    /** Field-joined manifests: field -> value -> owned key -> value. */
-    byField: ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, ExternalMetadataValue>>>;
-    /** Every manifest entry, in manifest order. */
-    entries: readonly ExternalMetadataEntry[];
+    encrypted?: boolean;
+    /**
+     * Proposal 0047: the manifest the value was written into, as the run
+     * reports it, when a manifest of the page's collections owns the key.
+     * Absent when the value went to the page.
+     */
+    destination?: string;
 }
-interface LoadExternalMetadataOptions {
-    /** Directory `externalMetadata[].file` and every manifest key resolve from. */
-    configDir: string;
-    /** Directory the run's file labels are relative to; manifests are reported the same way. */
-    base: string;
-    /** `--offline` / `offline:`: a URL manifest is refused rather than fetched (0038). */
-    offline?: boolean;
-    /** Network timeout for a URL manifest; the schema fetch's default otherwise. */
-    timeoutMs?: number;
-    /** For tests: the environment `tokenEnv` is read from. */
-    env?: Record<string, string | undefined>;
+/**
+ * One `meta-provenance` entry as `fill` writes it (proposal 0046): the model,
+ * the JSON Pointers of the fields it proposed, escaped per RFC 6901, and the
+ * confidence each was written at. Keys are the page's own spelling, so the
+ * JSON report shows exactly what landed in the document. An entry `fill`
+ * merged into keeps whatever else it held.
+ */
+interface MetaProvenanceEntry {
+    "generated-by": string;
+    fields: string[];
+    confidence: Record<string, number>;
+    [other: string]: unknown;
 }
-/** A place a merged value lives, for a finding that must name it. */
-interface SourceLocation {
-    file: string;
-    line?: number;
-    col?: number;
+/**
+ * What became of this file's `meta-provenance` entry. It is never a failure:
+ * neither outcome changes the summary or the exit code.
+ */
+type MetaProvenanceReport = {
+    written: true;
+    entry: MetaProvenanceEntry;
+    /** The manifest the entry was written into, when one owns `meta-provenance` (0047). */
+    destination?: string;
 }
-/** A key the document carries that a manifest owns. */
-interface ExternalMetadataCollision {
-    key: string;
-    /** The owning manifest, as the run reports it. */
-    file: string;
-    /** The collection that manifest belongs to (proposal 0041). */
-    collection: string;
+/** The page's schemas, checked with the entry in place, reject it. */
+ | {
+    written: false;
+    skipReason: "schema-mismatch";
 }
-/** A field-joined entry a document matched (0039). */
-interface ExternalMetadataJoin {
-    field: string;
-    /** The value matched: the field's plaintext, decrypted first when the page holds it encrypted. */
-    value: string;
+/** A URL manifest in one of the page's collections owns the key, and cannot be written (0047). */
+ | {
+    written: false;
+    skipReason: "manifest-owned";
+    manifest: string;
+}
+/**
+ * The format's writer cannot hold a list of entries (an HTML or XML
+ * attribute holds one line), so the fields were written without it.
+ */
+ | {
+    written: false;
+    skipReason: "unwritable";
+};
+interface FillFileResult {
+    file: string;
+    format: string;
+    schemas: string[];
+    fields: FilledField[];
+    /** Whether the file's content changed (false under --dry-run too). */
+    changed: boolean;
+    /** Parse failure, read-only format, or provider error. */
+    error?: string;
+    /** The filled document. Populated only when the caller asks for it. */
+    content?: string;
     /**
-     * The field as the page holds it, when that differs from `value`: the
-     * ciphertext of an encrypted join field (proposal 0045). A finding about
-     * the join names this, never the plaintext.
+     * The `meta-provenance` entry recording the fields this run wrote
+     * (proposal 0046). Absent when no field was written; reported, not written,
+     * under `--dry-run`.
      */
-    pageValue?: string;
-    /** The manifest, as the run reports it. */
-    file: string;
-    /** The collection that manifest belongs to (proposal 0041). */
-    collection: string;
+    metaProvenance?: MetaProvenanceReport;
 }
-/** What `mergeExternalMetadata` hands back. */
-interface MergedMetadata {
-    /** The document's metadata with every owned key the manifest supplied. */
-    extracted: ExtractedMetadata;
+interface FillSummary {
+    files: number;
+    changed: number;
+    written: number;
+    skipped: number;
+    /** Skipped fields that the schema lists as required — drives exit code 1. */
+    requiredSkipped: number;
+    errors: number;
+    costUsd: number;
+    cached: number;
+}
+interface FillRun {
+    results: FillFileResult[];
+    summary: FillSummary;
+    /** Echoed so JSON consumers and CI can assert which gate actually ran. */
+    threshold: number;
+    dryRun: boolean;
+    provider: string;
+    model: string;
+    /** True when the call cap stopped the run before every file was seen. */
+    turnsSpent: boolean;
+}
+interface FillOptions {
+    inputs: string[];
+    cliSchemas?: string[];
+    exts?: string[];
+    exclude?: string[];
+    /** `--as` format override (extractor name). */
+    as?: string;
+    configPath?: string;
+    /** `--no-config`: skip config discovery and use the built-in defaults. */
+    noConfig?: boolean;
+    /**
+     * `--collection <name>`, repeatable: run over the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with positional paths; `-` is allowed beside it.
+     */
+    collections?: string[];
+    cwd?: string;
+    /** Content for the `-` (stdin) input, injected by the CLI/tests. */
+    stdinContent?: 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;
+    /**
+     * `--offline`: never fetch a remote **schema**. Absent leaves config
+     * `offline:` in charge.
+     *
+     * Scoped to schema loading only. It says nothing about the inference
+     * provider, which is a separate network dependency with its own controls
+     * (`--provider mock`, `--dry-run`).
+     */
+    offline?: boolean;
+    /** Restrict proposals to these top-level fields. */
+    fields?: string[];
+    /** Minimum self-reported confidence to write (0-1). Default 0.7. */
+    confidence?: number;
+    /** Report proposals without writing them. */
+    dryRun?: boolean;
+    provider?: string;
+    model?: string;
+    /** Use the on-disk proposal cache. Default true. */
+    cache?: boolean;
+    /** Refuse a hosted provider: inference must run on this machine. */
+    local?: boolean;
+    /** Stop after this many inference calls. Counts calls, not files. */
+    maxTurns?: number;
+    /** Characters of document per call. Default 12000. */
+    chunkChars?: number;
+    /** Files inferred in parallel. Default 4. */
+    concurrency?: number;
+    /** Include the filled document on each result (used for stdin and tests). */
+    includeContent?: boolean;
+    /** Test seam: bypasses `makeProvider`, so no API key is needed. */
+    inferenceProvider?: InferenceProvider;
+    /**
+     * How to ask for a new encryption key when a field its schema marks
+     * `x-manni-encrypt` is about to be written and no key is available
+     * (proposal 0045). The CLI passes `terminalConfirm()`, which is `undefined`
+     * off a terminal; absent, the run refuses (exit 2) before the first model
+     * request.
+     */
+    confirm?: Confirm;
     /**
-     * Owned keys the document itself also carried, in document order, each
-     * with the manifest that owns it — so the finding names it without a
-     * second lookup, and without a fallback for an index that is not there.
+     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
+     * `process.env`; tests pass their own.
      */
-    collisions: ExternalMetadataCollision[];
-    /** Field-joined entries this document matched, one per manifest at most. */
-    joins: ExternalMetadataJoin[];
+    env?: NodeJS.ProcessEnv;
     /**
-     * Where a merged pointer's value lives. Answers only for a value the
-     * manifest supplied — a bare key or its `/key` pointer, and anything
-     * beneath it — and `undefined` for everything the document owns, which is
-     * what `lineFor` is for.
-     *
-     * The line is the deepest manifest node the pointer reaches, so
-     * `/citations/2` is the third item's line and `/citations/2/source/file`
-     * that member's. A pointer past what the manifest holds falls back to the
-     * nearest ancestor that exists, and at worst to the owned key's line.
+     * Called with relocate's result after the user accepts a P1 offer
+     * (proposal 0047), so the CLI can print what moved before the report.
      */
-    locate: (pointer: string) => SourceLocation | undefined;
+    onRelocated?: (result: RelocateResult) => void;
 }
-/** The join an external-metadata config asks for: `path` unless it names a field. */
-declare function externalMetadataJoin(manifest: Pick<ExternalMetadataConfig, "join">): string;
-/**
- * Load every manifest of every collection the run covers. Resolves to `null`
- * when none of them declares one, which is every setup that existed before
- * this feature.
- *
- * Every refusal is a `DocmetaError`: the manifest is a config-supplied input,
- * and one that is missing or misshapen is the run's problem, not a
- * document's (0014).
- */
-declare function loadExternalMetadata(collections: readonly CollectionConfig[], opts: LoadExternalMetadataOptions): Promise<ExternalMetadataIndex | null>;
-/**
- * Merge the external metadata for one document into its extracted metadata.
- *
- * `label` is the document as the run spells it, relative to `base`; a path
- * entry matches on the resolved absolute path, never on the spelling, so a
- * positional run from a subdirectory finds the same entry a config-corpus
- * run does. A field entry matches on the document's own value of the join
- * field, wherever the document lives. Stdin never matches a path entry:
- * there is no file behind it.
- *
- * `memberOf` names the collections this document belongs to, and only their
- * manifests are consulted (0041 rule 4). It is the caller's `memberOf(...)`
- * result, computed once per file.
- *
- * `present`, `format` and the document's own positions are untouched. A
- * manifest key is not in the document, so `lineFor` keeps answering
- * `undefined` for it, and `locate` answers instead.
- *
- * A join field the page holds encrypted (proposal 0045) is decrypted with
- * `options.encryptionKey` before it is matched. With no key, and a manifest
- * of this document's collections joining on that field, the run cannot match
- * and refuses. A ciphertext that does not decrypt matches nothing.
- */
-declare function mergeExternalMetadata(label: string, extracted: ExtractedMetadata, index: ExternalMetadataIndex | null, memberOf: readonly string[], base: string, options?: {
-    encryptionKey?: () => string | undefined;
-}): MergedMetadata;
-/** The `/key` pointer for an external-metadata finding, RFC 6901 escaped. */
-declare function externalMetadataPointer(key: string): string;
-/**
- * Path entries naming no loaded document.
- *
- * `loaded` are the run's file labels, relative to `base`. Checked only when
- * the run is the config corpus (the same invariant corpus checks use): a
- * positional path means the operator chose to look at part of the corpus,
- * and an entry for the rest is expected, not orphaned.
- */
-declare function orphanEntries(index: ExternalMetadataIndex | null, loaded: readonly string[], base: string, collections?: readonly string[]): ExternalMetadataEntry[];
-/**
- * Field entries no loaded document matched (0039). `matched` is field -> the
- * values documents in the run carried, which the caller collects from each
- * document's `joins` — so this runs after the per-file loop, under the same
- * corpus invariant as `orphanEntries`.
- */
-declare function orphanJoins(index: ExternalMetadataIndex | null, matched: ReadonlyMap<string, ReadonlySet<string>>, collections?: readonly string[]): ExternalMetadataEntry[];
-/** The operational error an orphan check raises, naming the first entry. */
-declare function orphanError(orphans: readonly ExternalMetadataEntry[]): DocmetaError;
 
-declare class Validator {
-    private readonly schemaOptions;
+declare function runFill(opts: FillOptions): Promise<FillRun>;
+
+interface DeriveOptions {
+    inputs: string[];
     /**
-     * How this validator's schemas are loaded: the disk cache location, its TTL,
-     * and `--offline`. Held per instance rather than read from module state, so
-     * two differently-configured validations in one process each get their own
-     * settings.
-     *
-     * That is not full isolation, and the difference matters to a library
-     * caller: `schema-registry` keeps a process-wide memo of fetched schemas, so
-     * one validator's successful fetch is visible to another. `offline` is
-     * excluded from that sharing on purpose — an offline validator will not be
-     * served something this process pulled over the network — but the memo is
-     * still shared, so a URL fetched once is not re-fetched per instance.
+     * `--collection <name>`, repeatable: stamp only the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with paths.
      */
-    constructor(schemaOptions?: LoadSchemaOptions);
-    private ajvByDialect;
+    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;
     /**
-     * Keyed on the in-flight *promise*, not the resolved validator. Caching the
-     * result made this a check-then-act race: `fill` walks files through a worker
-     * pool, so every worker missed the cache while the first `loadSchema` was
-     * still pending and they all then compiled the same schema into the one
-     * shared per-dialect Ajv. Ajv registers a schema's `$id` on the first compile
-     * and rejects the second with "schema with key or id ... already exists",
-     * which took down any multi-file run against an $id-bearing schema. Storing
-     * the promise before the first await lets the losers await the one compile.
+     * `--no-gitignore` (false). Absent leaves config `respectGitignore:` in
+     * charge, which itself defaults to on.
      */
-    private cache;
-    private ajvFor;
+    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;
     /**
-     * Synchronous by design: the `cache.set` has to happen in the same tick as
-     * the miss, or a second caller can slip in before the entry exists.
+     * How to ask for a new encryption key when a field its schema marks
+     * `x-manni-encrypt` is about to be stamped and no key is available
+     * (proposal 0045). The CLI passes `terminalConfirm()`, which is `undefined`
+     * off a terminal; absent, such a stamp refuses (exit 2). A dry run never
+     * asks: it writes nothing.
      */
-    private compile;
-    private compileUncached;
+    confirm?: Confirm;
     /**
-     * The instance pointers of `data` that carry `x-manni-encrypt: true` under
-     * any schema in `refs`, in the order the validator evaluated them.
-     *
-     * A first pass with the recording keyword, so a mark counts exactly where
-     * validation would evaluate it. Only present values are marked: Ajv applies
-     * a property's subschema to a property that exists. A branch Ajv does not
-     * take (`then` behind a failing `if`, an `anyOf` branch after a passing
-     * one) contributes nothing; a branch it takes contributes its marks
-     * whether or not the branch passes, because a ciphertext routinely fails
-     * the rest of its own subschema until it is decrypted.
+     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
+     * `process.env`; tests pass their own.
      */
-    markedPointers(data: Record<string, unknown>, refs: string[]): Promise<Set<string>>;
+    env?: NodeJS.ProcessEnv;
     /**
-     * Validate `data` against every schema in `refs`. Returns all violations,
-     * each tagged with the schema that produced it and a source line via
-     * `lineFor`.
-     *
-     * `colFor` is optional and additive: this signature is public, so a fourth
-     * *required* parameter — or a widened third one — would be a consumer break.
-     * Callers with an extractor that supplies no column pass nothing and get the
-     * previous behavior exactly.
+     * `--generated-by <name>` (proposal 0046): the machine uncommitted body
+     * lines go to, or the lines a `<path>:L1-L2` positional names. Absent reads
+     * `MANNI_GENERATED_BY` from `env`; an empty value is unset either way.
      */
-    validate(data: Record<string, unknown>, refs: string[], lineFor: (pointer: string) => number | undefined, colFor?: (pointer: string) => number | undefined, 
+    generatedBy?: string;
     /**
-     * Where a merged value lives when it is not in the document (proposal
-     * 0037): a manifest's file and line. Consulted before `lineFor`,
-     * and additive in the way `colFor` was.
+     * Called with relocate's result after the user accepts a P1 offer
+     * (proposal 0047), so the CLI can print what moved before the report.
      */
-    locate?: (pointer: string) => SourceLocation | undefined): Promise<FieldError[]>;
+    onRelocated?: (result: RelocateResult) => void;
+}
+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;
+    /**
+     * `provenance` ranges whose write reached the disk (proposal 0046): always
+     * 0 under `dryRun` and `check`. Present only when the run derives
+     * `provenance`.
+     */
+    ranges?: 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$1>>;
+    /** Where the run stood, for the SARIF reporter under `check`. See `ValidateRun.frame`. */
+    frame: FingerprintContext;
+}
+declare function runDerive(opts: DeriveOptions): Promise<DeriveRun>;
+
+/**
+ * `relocate` (proposal 0047): move every value to where its schema's
+ * `x-manni-location` mark and the config's manifests say it belongs.
+ *
+ * Out of the page and into a manifest go the values a schema prefers in
+ * external metadata and the values a manifest already owns. Out of a manifest
+ * and into the page go the values a schema prefers on the page. The
+ * collection, manifest file and config entry a value needs are created on the
+ * way, and a change to a manifest's `keys:` covers every member page of its
+ * collection. The planning and writing live in `core/relocation.ts`, which the
+ * writers' and validate's offers share; this is the command around it.
+ *
+ * Two refusals come before the config is read, because each rules out the
+ * whole run: stdin, which is not a document a manifest can name, and
+ * `--no-config`, which leaves nowhere to declare a manifest.
+ */
+
+interface RelocateOptions {
+    /** Files, directories and globs. Empty falls back to the configured collections. `-` is refused. */
+    inputs: string[];
+    /** `--fields`: only these keys. Each must carry a mark, or be manifest-owned, for some file. */
+    fields?: string[];
+    /** `--collection <name>`, repeatable: run over these configured collections. */
+    collections?: string[];
+    /** `-s/--schema`, repeatable: the schema set every page is judged by. */
+    cliSchemas?: string[];
+    /** `--dry-run`: report what would move and be created; write nothing. */
+    dryRun?: boolean;
+    /** `--as`: force an extractor. */
+    as?: string;
+    exts?: string[];
+    exclude?: string[];
+    configPath?: string;
+    /** `--no-config`: refused, since relocate writes the config. */
+    noConfig?: boolean;
+    cwd?: string;
+    allowEmpty?: boolean;
+    /** `--no-gitignore` (false). Absent leaves config `respectGitignore:` in charge. */
+    respectGitignore?: boolean;
+    onNotice?: (message: string) => void;
+    onConfigLoaded?: (info: ConfigNotice) => void;
+    /** Where `MANNI_ENCRYPTION_KEY` is read, for an encrypted join field. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
 }
+declare function runRelocate(opts: RelocateOptions): Promise<RelocateResult>;
 
 /** One value re-encrypted: where, and the ciphertext before and after. */
 interface ReencryptedValue {
@@ -3211,15 +3429,13 @@ contents: string | Uint8Array): Promise<void>;
 
 /**
  * Extractor registry. Maps file extensions to extractors and resolves an
- * extractor by name (for the `--as` override). Every registered extractor is
- * implemented today; the `implemented` filters below are what would keep a
- * declared-but-unwired format out of directory walks, so an unfinished format
- * can be registered without becoming "supported".
+ * extractor by name (for the `--as` override). A registered extractor reads
+ * its format, so registration is what makes an extension supported.
  */
 
-/** Resolve an implemented extractor for a file extension (incl. dot). */
+/** Resolve the extractor for a file extension (incl. dot). */
 declare function extractorForExtension(ext: string): MetadataExtractor | undefined;
-/** Extensions handled by implemented extractors (used for directory walks). */
+/** Extensions handled by registered extractors (used for directory walks). */
 declare function supportedExtensions(): string[];
 
 type KeySource = "env" | "config" | "none";
@@ -3271,7 +3487,7 @@ interface CitationSource {
     /** The git commit hash the pin was taken at: 7 to 64 lowercase hex. */
     "commit-sha"?: string;
 }
-/** One entry of `citations`, as the schema (`manni:citations:1.0.0-proposal.3`) spells it. */
+/** One entry of `citations`, as the schema (`manni:citations:1.0.0-proposal.4`) spells it. */
 interface Citation {
     id?: string;
     claim?: CitationClaim;
@@ -3907,12 +4123,9 @@ declare function readSource(root: string, index: SourceIndex, range: SourceRange
  * `indexOf` for the delimiters, never a regex over the whole page, and is
  * handed the body only, so a `cite` inside frontmatter is never matched.
  *
- * It does not read code. An opener inside a fenced block (``` or ~~~ in
- * markdown and mdx, indented or not; `----` in asciidoc; an unclosed fence
- * runs to the end, as a renderer reads it) or inside a backtick span (a run of
- * backticks closed by a run of the same length on the same line) is skipped,
- * so a page that documents the syntax carries no statements. html and xml
- * have neither; a `<pre>` is not code to this scanner.
+ * It does not read code. An opener inside a fenced block or a backtick span,
+ * as `src/shared/code-regions.ts` finds them, is skipped, so a page that
+ * documents the syntax carries no statements.
  *
  * Every form parses in both markdown and mdx. The first form is what
  * `formatStatement` writes: the html comment for markdown, the jsx comment
@@ -4993,4 +5206,4 @@ declare namespace index {
   export { type index_EncryptionContext as EncryptionContext, index_KeyError as KeyError, type index_KeyRotateOptions as KeyRotateOptions, type index_KeyRotateResult as KeyRotateResult, type index_KeySetOptions as KeySetOptions, type index_KeySetResult as KeySetResult, type index_KeySource as KeySource, type index_ResolvedKey as ResolvedKey, type index_RotateManifest as RotateManifest, type index_RotateOutcome as RotateOutcome, type index_RotatePage as RotatePage, type index_RotatedCitation as RotatedCitation, type index_RotatedManifestValue as RotatedManifestValue, type index_RotatedMetadata as RotatedMetadata, type index_RotatedValue as RotatedValue, type index_SkippedCitation as SkippedCitation, type index_SkippedManifestValue as SkippedManifestValue, type index_SkippedMetadata as SkippedMetadata, type index_SkippedValue as SkippedValue, index_decryptValue as decryptValue, index_encryptValue as encryptValue, index_isEncryptedValue as isEncryptedValue, index_resolveEncryptionKey as resolveEncryptionKey, index_runKeyRotate as runKeyRotate, index_runKeySet as runKeySet };
 }
 
-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 ReencryptMetadataResult, type ReencryptedValue, 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$1 as SourceStatus, type SpawnOptions, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, argvFor, assertSourcesAvailable, cachedClient, index$1 as cite, classifyRef, collectSchemaPins, compareDerived, consultedSources, createResolvedView, createReviewClient, deriveFromCommands, deriveFromReviews, deriveMetadata, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, identityFromOrigin, integrityOf, isBuiltinField, isCommonFormat, isDeriveFormat, isDeriveSource, isErrorSeverity, isFillFormat, isIntegrity, isMember, isPerFile, isQueryFormat, isReportFormat, index as key, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mentionsResolved, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, parseOriginUrl, rebaseConfigSchemaRefs, reencryptMetadata, 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 };
+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 FieldLocation, 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, LOCATION_KEYWORD, type LoadExternalMetadataOptions, type LoadSchemaOptions, type LoadedConfig, type LocationPreference, 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 ReencryptMetadataResult, type ReencryptedValue, type RelocateOptions, type RelocateResult, 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$1 as SourceStatus, type SpawnOptions, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, argvFor, assertSourcesAvailable, cachedClient, index$1 as cite, classifyRef, collectSchemaPins, compareDerived, consultedSources, createResolvedView, createReviewClient, deriveFromCommands, deriveFromReviews, deriveMetadata, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, identityFromOrigin, integrityOf, isBuiltinField, isCommonFormat, isDeriveFormat, isDeriveSource, isErrorSeverity, isFillFormat, isIntegrity, isMember, isPerFile, isQueryFormat, isReportFormat, index as key, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mentionsResolved, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, parseOriginUrl, rebaseConfigSchemaRefs, reencryptMetadata, render, renderDerive, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, resolvedColumns, run, runDerive, runFill, runGet, runQuery, runRelocate, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, selectCollections, sourcesFor, staleFindings, stringifyValue, supportedExtensions, valueOf, vendorFileName, writeFileAtomic };