@hawkeyexl/manni 1.1.0 → 2.0.0

package/dist/index.d.ts

@@ -16,6 +16,23 @@ declare class ToolError extends Error {
     constructor(message: string);
 }
 
+/**
+ * The one severity scale every manni tool speaks. Least to most severe.
+ *
+ * Three values, chosen to match the sinks every tool writes to and the
+ * linters that sit beside it. GitHub annotations are `error`, `warning` and
+ * `notice`; so are ESLint's and Vale's levels, and pa11y's. A flag or config
+ * key that two domains both have carries the same name and the same values,
+ * and this is where the values for `severity` are defined once.
+ *
+ * A domain whose source speaks another scale maps onto this one and keeps
+ * the source's value in a field of its own, so nothing is lost for lookup.
+ * a11y is the first case: axe reports four impacts, the analyzer folds them
+ * onto these three, and each finding still carries axe's word as `impact`.
+ */
+declare const SEVERITIES: readonly ["notice", "warning", "error"];
+type Severity = (typeof SEVERITIES)[number];
+
 /**
  * Shared types for docmeta.
  *
@@ -185,7 +202,33 @@ interface FieldError {
      * and its SARIF location, and this names where the *value* was written.
      */
     file?: string;
+    /**
+     * How much the finding weighs, on the family scale (`src/shared/severity.ts`).
+     *
+     * The invariant, stated here and nowhere else: a result's `ok` is true iff
+     * no entry of its `errors` has severity `error`, and an **absent** severity
+     * means `error`. So every producer that never sets this field is unchanged,
+     * and a `warning` or `notice` is a finding that is reported, baselined and
+     * fingerprinted like any other but never fails a file, and so never moves
+     * the exit code. Nothing in meta's own validation sets one today; a sibling
+     * tool's findings ride these types and reporters, and some of theirs are
+     * advisory.
+     *
+     * Deliberately not part of the fingerprint: a rule that is downgraded from
+     * error to warning is the same finding, and a baseline that forgot it on
+     * the way down would re-open every instance.
+     *
+     * `isErrorSeverity` is the one reading of this field; derive `ok` through
+     * it rather than restating the absent-means-error rule.
+     */
+    severity?: Severity;
 }
+/**
+ * Whether a finding counts against `ok`: true for `error` and for an absent
+ * severity, false for `warning` and `notice`. See `FieldError.severity` for
+ * the invariant.
+ */
+declare function isErrorSeverity(e: Pick<FieldError, "severity">): boolean;
 /** Validation outcome for a single file. */
 interface ValidationResult {
     /** Absolute or cwd-relative path of the file. */
@@ -229,8 +272,22 @@ interface RunSummary {
     files: number;
     passed: number;
     failed: number;
-    /** Violations reported. Baselined ones are excluded — see `baseline`. */
+    /**
+     * Error-severity findings reported. Baselined ones are excluded — see
+     * `baseline` — and so are warnings, which have their own count.
+     */
     errors: number;
+    /**
+     * Warning-severity findings reported. Omitted when there are none, which is
+     * every run of meta's own validation today, so the JSON summary is unchanged
+     * for them. A warning never fails a file or the run.
+     */
+    warnings?: number;
+    /**
+     * Notice-severity findings reported. Omitted when there are none, as
+     * `warnings` is. A notice never fails a file or the run.
+     */
+    notices?: number;
     /**
      * Candidate documents `.gitignore` removed from the walk. Omitted when it
      * removed none. Reported because silent removal is what makes the filter
@@ -301,6 +358,50 @@ declare function selectCollections(collections: readonly CollectionConfig[], nam
  */
 declare function isMember(collection: CollectionConfig, relPath: string): boolean;
 
+interface ConfigFile {
+    /** Absolute path to the file. */
+    path: string;
+    /** Directory holding it; relative paths in the config resolve from here. */
+    dir: string;
+    /**
+     * The file as the user would name it: relative to `cwd`, posix separators,
+     * or the spelling they typed for an explicit path. For error messages.
+     */
+    source: string;
+    /** The file's text, for a tool that rewrites the file in place. */
+    text: string;
+    /**
+     * The tool's slice: the value under `section:` when `wrapped`, otherwise
+     * the whole document. `null` for an empty file or an empty section; the
+     * tool decides what empty means.
+     */
+    value: unknown;
+    /** Whether `value` came from under `section:`. */
+    wrapped: boolean;
+    /** How the file was found. Explicit paths are never warned about. */
+    kind: "manni" | "moose" | "legacy" | "explicit";
+    /**
+     * The document's top-level `collections:` (proposal 0041), parsed once here
+     * because every tool reads the same declaration. `[]` when the key is
+     * absent, and always `[]` for a `legacy` file: a per-tool file's whole
+     * document *is* the tool's section, so it carries no family-wide keys.
+     */
+    collections: CollectionConfig[];
+    /**
+     * The document's top-level `encryptionKey:` (proposal 0045), validated
+     * here. Absent when the key is, and always absent for a `legacy` file, for
+     * the same reason as `collections`. `MANNI_ENCRYPTION_KEY` wins over it;
+     * read it through `resolveEncryptionKey`, not directly.
+     */
+    encryptionKey?: string;
+    /**
+     * The document's top-level `encryptionKeyPrevious:`, validated here as
+     * `encryptionKey` is. Present only while a rotation is unfinished, and read
+     * only by `manni key rotate`, which finishes it.
+     */
+    encryptionKeyPrevious?: string;
+}
+
 /**
  * The derived metadata channel: values computed from git history, CODEOWNERS
  * and the review record on GitHub or GitLab rather than written by hand.
@@ -355,7 +456,7 @@ interface DerivedRecord {
     fields: Record<DerivableField, DerivedValue | null>;
 }
 /** Whether a source can answer at all; `reason` names the fix when not. */
-interface SourceStatus {
+interface SourceStatus$1 {
     available: boolean;
     reason?: string;
 }
@@ -389,7 +490,7 @@ interface MergedChange {
 interface ReviewClient {
     detect(): Promise<RemoteIdentity | null>;
     /** Binary on PATH and authenticated for the host; `reason` names the fix. */
-    status(): Promise<SourceStatus>;
+    status(): Promise<SourceStatus$1>;
     /** The merged PR/MR that contains the commit, or null (open, none, or unknown). */
     mergedChangeFor(sha: string): Promise<MergedChange | null>;
 }
@@ -716,6 +817,18 @@ interface LoadedConfig {
      * order. `[]` for a legacy per-tool file, which carries no family-wide keys.
      */
     collections: CollectionConfig[];
+    /**
+     * The family file's top-level `encryptionKey:` (proposal 0045), when it has
+     * one. `MANNI_ENCRYPTION_KEY` wins over it: read the run's key through
+     * `resolveEncryptionKey`, never from here directly.
+     */
+    encryptionKey?: string;
+    /**
+     * The file itself, as family discovery found it. What a write that needs a
+     * key hands `ensureEncryptionKey`, so the key lands in the file that
+     * governs the run.
+     */
+    configFile?: ConfigFile;
 }
 
 /**
@@ -857,6 +970,12 @@ interface RunConfig {
      * operator chose part of the corpus.
      */
     fromCollections: boolean;
+    /**
+     * The governing config file, when one governs the run: what the run's
+     * encryption key resolves from (proposal 0045), with `MANNI_ENCRYPTION_KEY`
+     * winning over it, and where a write that needs a key writes one.
+     */
+    configFile?: ConfigFile;
 }
 /**
  * Settle the three things every command core needs from config before it can
@@ -924,6 +1043,12 @@ interface ValidateOptions {
      * set is the config-resolved corpus (proposal 0026).
      */
     checks?: boolean;
+    /**
+     * The environment `MANNI_ENCRYPTION_KEY` is read from (proposal 0045).
+     * Defaults to `process.env`; tests pass their own so a developer's key is
+     * never read.
+     */
+    env?: NodeJS.ProcessEnv;
     /**
      * `--no-derive` (false): skip comparing each managed field (`derive.fields`
      * in the config, proposal 0040) with what the evidence says. Absent leaves
@@ -1059,6 +1184,9 @@ interface GetFileResult {
 }
 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.
@@ -1141,6 +1269,19 @@ interface QueryOptions {
      * applied — a flag that would silently mean nothing must refuse.
      */
     schemas?: string[];
+    /**
+     * 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;
+    /**
+     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
+     * `process.env`; tests pass their own.
+     */
+    env?: NodeJS.ProcessEnv;
     /** The clock an uncommitted body change is dated by. Test seam; default `new Date()`. */
     now?: () => Date;
 }
@@ -1444,10 +1585,19 @@ interface FilledField {
     required: boolean;
     confidence: number;
     reasoning: string;
-    /** Absent when the field was skipped. */
+    /**
+     * 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).
+     */
     value?: unknown;
     written: boolean;
     skipReason?: SkipReason;
+    /**
+     * The value was written encrypted, because the field's schema marks it
+     * `x-manni-encrypt`. Absent otherwise.
+     */
+    encrypted?: boolean;
 }
 interface FillFileResult {
     file: string;
@@ -1544,6 +1694,19 @@ interface FillOptions {
     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;
+    /**
+     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
+     * `process.env`; tests pass their own.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 
 declare function runFill(opts: FillOptions): Promise<FillRun>;
@@ -1589,6 +1752,19 @@ interface DeriveOptions {
     now?: () => Date;
     /** The review client, for every repository in the run. Test seam; default `gh` / `glab`. */
     reviews?: ReviewClient;
+    /**
+     * 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.
+     */
+    confirm?: Confirm;
+    /**
+     * The environment `MANNI_ENCRYPTION_KEY` is read from. Defaults to
+     * `process.env`; tests pass their own.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 interface DeriveFileResult {
     file: string;
@@ -1627,7 +1803,7 @@ interface DeriveRun {
     dryRun: boolean;
     check: boolean;
     /** One status per source the run consulted; a source nobody asked for is absent. */
-    sources: Partial<Record<DeriveSource, SourceStatus>>;
+    sources: Partial<Record<DeriveSource, SourceStatus$1>>;
     /** Where the run stood, for the SARIF reporter under `check`. See `ValidateRun.frame`. */
     frame: FingerprintContext;
 }
@@ -1662,6 +1838,14 @@ interface ExternalMetadataValue {
     file: string;
     /** 1-based line of the key in the manifest, when known. */
     line?: number;
+    /**
+     * 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.
+     */
+    lines?: ReadonlyMap<string, number>;
 }
 /** One manifest entry, for the orphan checks. */
 interface ExternalMetadataEntry {
@@ -1728,7 +1912,14 @@ interface ExternalMetadataCollision {
 /** 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;
+    /**
+     * 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.
+     */
+    pageValue?: string;
     /** The manifest, as the run reports it. */
     file: string;
     /** The collection that manifest belongs to (proposal 0041). */
@@ -1751,6 +1942,11 @@ interface MergedMetadata {
      * 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.
      */
     locate: (pointer: string) => SourceLocation | undefined;
 }
@@ -1783,8 +1979,15 @@ declare function loadExternalMetadata(collections: readonly CollectionConfig[],
  * `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): MergedMetadata;
+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;
 /**
@@ -1841,6 +2044,19 @@ declare class Validator {
      */
     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>>;
     /**
      * Validate `data` against every schema in `refs`. Returns all violations,
      * each tagged with the schema that produced it and a source line via
@@ -1860,6 +2076,45 @@ declare class Validator {
     locate?: (pointer: string) => SourceLocation | undefined): Promise<FieldError[]>;
 }
 
+/** One value re-encrypted: where, and the ciphertext before and after. */
+interface ReencryptedValue {
+    pointer: string;
+    from: string;
+    to: string;
+}
+interface ReencryptMetadataResult {
+    /** The page with every rewritten value; the input itself when nothing was. */
+    content: string;
+    rewritten: ReencryptedValue[];
+    /** Values that could not be re-encrypted, and why. */
+    skipped: {
+        pointer: string;
+        message: string;
+    }[];
+}
+/**
+ * Re-encrypt every encrypted value in one page's metadata from `fromKey` to
+ * `toKey`.
+ *
+ * - A value that decrypts under `fromKey` is rewritten under `toKey`.
+ * - One that already decrypts under `toKey` is done: an interrupted rotation
+ *   can be run again. It is neither rewritten nor skipped.
+ * - One that decrypts under neither is skipped.
+ *
+ * The format is `page.format` (an extractor name) when given, else the
+ * file's extension. A nested value rewrites its top-level key; everything
+ * else in the page is kept. A format that cannot be written lists every value
+ * it would have rewritten as skipped, and returns the content unchanged.
+ */
+declare function reencryptMetadata(page: {
+    file: string;
+    content: string;
+    format?: string;
+}, opts: {
+    fromKey: string;
+    toKey: string;
+}): ReencryptMetadataResult;
+
 /**
  * Applied when nothing else resolves. Seven-Action is safe to include here
  * because it constrains `action` — a key documents don't otherwise carry — and
@@ -2041,7 +2296,7 @@ interface DeriveResult {
      * 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>>;
+    sources: Partial<Record<DeriveSource, SourceStatus$1>>;
 }
 /**
  * Which sources can state a field, in precedence order: the built-in table
@@ -2055,7 +2310,7 @@ declare function consultedSources(fields: readonly DerivableField[], sources: re
  * 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 assertSourcesAvailable(sources: Partial<Record<DeriveSource, SourceStatus$1>>, 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. */
@@ -2109,7 +2364,7 @@ interface CommandSourceOptions {
     spawn?: Partial<SpawnOptions>;
 }
 interface CommandSourceResult {
-    status: SourceStatus;
+    status: SourceStatus$1;
     /** By label; every input present when available, keyed by field within. */
     records: Map<string, Record<string, DerivedValue | null>>;
 }
@@ -2167,7 +2422,7 @@ declare abstract class CliClient implements ReviewClient {
     protected abstract readonly tool: "gh" | "glab";
     constructor(identity: RemoteIdentity | null, spawnOpts: SpawnOptions);
     detect(): Promise<RemoteIdentity | null>;
-    status(): Promise<SourceStatus>;
+    status(): Promise<SourceStatus$1>;
     mergedChangeFor(sha: string): Promise<MergedChange | null>;
     protected abstract lookup(identity: RemoteIdentity, sha: string): Promise<MergedChange | null>;
     protected get bin(): string;
@@ -2242,7 +2497,7 @@ interface ReviewFacts {
     "last-reviewed": DerivedValue | null;
 }
 interface ReviewSourceResult {
-    status: SourceStatus;
+    status: SourceStatus$1;
     /** By label. Empty when the source is unavailable. */
     records: Map<string, ReviewFacts>;
 }
@@ -2449,6 +2704,11 @@ declare function renderSarif(results: ValidationResult[], opts?: SarifOptions):
  * Violation-as-testcase would make the test count rise and fall with document
  * quality, which reads as a suite someone broke.
  *
+ * **A warning is not a `<failure>`.** JUnit has no level below failure, and a
+ * `<failure>` that did not fail the run would make the tab disagree with the
+ * exit code. A warning-only file is a passing testcase; the warning is still
+ * in the JSON and SARIF output, which have somewhere to put it.
+ *
  * Escaping is the one thing a hand-rolled writer gets wrong. Messages carry
  * schema-authored text — a `pattern` regex may hold `<`, `&`, and quotes — and
  * paths can hold `&`. Every attribute value goes through `xmlEscape`; nothing
@@ -2718,4 +2978,1830 @@ declare function extractorForExtension(ext: string): MetadataExtractor | undefin
 /** Extensions handled by implemented extractors (used for directory walks). */
 declare function supportedExtensions(): string[];
 
-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 };
+type KeySource = "env" | "config" | "none";
+interface ResolvedKey {
+    key: string | undefined;
+    source: KeySource;
+}
+type ToError = (message: string) => Error;
+/**
+ * The key a run uses: the environment's, else the config file's, else none.
+ *
+ * An empty `MANNI_ENCRYPTION_KEY` counts as unset, because that is what an
+ * absent CI secret expands to (a fork's pull request, say), and refusing the
+ * run there would fail every such build for a key it was never going to get.
+ * A non-empty value of the wrong shape is refused, and never echoed.
+ */
+declare function resolveEncryptionKey(opts: {
+    env?: NodeJS.ProcessEnv;
+    file: ConfigFile | null;
+    toError: ToError;
+}): ResolvedKey;
+
+/** A parsed `<src>` or `source`: a path or `~` ciphertext, and an optional line range. */
+interface SourceRange {
+    /** Repo-root-relative posix path, or the `~` ciphertext when `encrypted`. */
+    path: string;
+    /** `true` when `path` is an encrypted source (`~` and 82+ base64url characters) rather than a path. */
+    encrypted: boolean;
+    /** 1-based, inclusive. Both absent for a whole-file citation. */
+    start?: number;
+    end?: number;
+}
+/** Lines as an entry writes them: an integer for one line, `"L1-L2"` for several. */
+type LineSpec = number | string;
+/** The page text a citation supports. */
+interface CitationClaim {
+    /** Body lines: counted from the first line after the frontmatter. Absent when a marker anchors the entry. */
+    lines?: LineSpec;
+    /** `sha256-<64 hex>` over the claimed lines, always plain. */
+    integrity: string;
+}
+/** The lines a claim rests on. */
+interface CitationSource {
+    /** Root-relative posix path, or `~` and the path encrypted with the family key. */
+    file: string;
+    /** File lines. Absent pins the whole file. */
+    lines?: LineSpec;
+    /** `sha256-<64 hex>`, or `hmac-sha256-<64 hex>` exactly when `file` is encrypted. */
+    integrity: string;
+    /** 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. */
+interface Citation {
+    id?: string;
+    claim?: CitationClaim;
+    source: CitationSource;
+    quote?: boolean;
+}
+/** Where an entry is kept: the page's frontmatter, or a manifest a collection declares. */
+type OriginKind = "frontmatter" | "manifest";
+/** Where an entry sits. */
+interface CitationOrigin {
+    kind: OriginKind;
+    /** The file the entry sits in: the page for frontmatter, the manifest otherwise. */
+    file: string;
+    /** Line of the entry in that file. */
+    line?: number;
+    /** Index in the page's `citations` list. */
+    index: number;
+}
+/**
+ * One entry handed to `checkCitations` from outside the page, already merged
+ * from a manifest. `entry` is the raw value and is validated as a frontmatter
+ * entry is; its index is its position in the list.
+ */
+interface CitationInput {
+    entry: unknown;
+    origin: {
+        kind: OriginKind;
+        file: string;
+        line?: number;
+    };
+}
+/** How a citation's claim is anchored: by its lines, by a body marker, or not at all. */
+type CitationAnchor = "claim" | "marker" | null;
+type SourceStatus = "current" | "moved" | "moved-ambiguous" | "changed" | "missing" | "never-true" | "skipped";
+type ClaimStatus = "current" | "moved" | "moved-ambiguous" | "changed" | "skipped";
+/**
+ * Why a source could not be read: not a tracked file under the root, an
+ * encrypted source with no key to decrypt it, one that does not decrypt under
+ * the key there is, or a tracked file that could not be read.
+ */
+type MissingReason = "untracked" | "no-key" | "undecryptable" | "unreadable";
+/**
+ * Every rule a finding can carry, stated once. The union and the default
+ * severity table are derived from this array so the three cannot disagree.
+ */
+declare const CITE_RULES: readonly ["source-moved", "source-moved-ambiguous", "source-changed", "source-never-true", "source-missing", "claim-moved", "claim-moved-ambiguous", "claim-changed", "marker-orphan", "marker-invalid", "marker-repeated", "anchor-invalid", "entry-invalid", "quote-drift"];
+type CiteRule = (typeof CITE_RULES)[number];
+/**
+ * A rule's level: the family scale (`src/shared/severity.ts`) plus `off`,
+ * which drops the rule's findings altogether.
+ */
+type CiteSeverity = Severity | "off";
+/** The claim end of a classified citation. Line specs are `"L"` or `"L1-L2"`. */
+interface ClaimEnd {
+    /** The entry's body lines. Absent when a marker anchors the claim. */
+    lines?: string;
+    /** Where the claim is judged, in file lines: the recorded lines, or what the marker anchors. */
+    fileLines?: string;
+    status: ClaimStatus;
+    /** For `moved`: the new body lines. */
+    newLines?: string;
+    /** For `moved-ambiguous`: every candidate, in body lines. */
+    candidates?: string[];
+    /** For `moved`: the new file lines. Pretty-only. */
+    newFileLines?: string;
+    /** For `moved-ambiguous`: every candidate, in file lines. Pretty-only. */
+    candidateFileLines?: string[];
+    /** For `changed`: the page lines at the claim now, for `--show-diff`. Pretty-only. */
+    text?: string[];
+}
+/** The source end of a classified citation. */
+interface SourceEnd {
+    /** `file` and `lines` as the entry spells them: `path`, `path:L`, `path:L1-L2`, the ciphertext for `path`. */
+    src: string;
+    status: SourceStatus;
+    /**
+     * The path an encrypted source decrypted to. Never printed except by the
+     * pretty reporter under `--reveal`; never serialized to a machine format.
+     */
+    resolvedPath?: string;
+    /** For `missing`: why the source could not be read. Composes the message, which never names a path. */
+    missingReason?: MissingReason;
+    /** For `moved`: the new file lines. */
+    newLines?: string;
+    /** For `moved`: the new `src`, spelled as the entry spells sources. */
+    newSrc?: string;
+    /** For `moved-ambiguous`: every candidate `src`. */
+    candidates?: string[];
+    /** The commit the pin was taken at. */
+    commitSha?: string;
+    /** For `changed` with a commit: whether git could show that commit. */
+    historyAvailable?: boolean;
+    /** Subjects of commits touching the path since the commit. Pretty-only. */
+    commitsSince?: string[];
+    /** Unified diff of the path since the commit. Pretty-only, `--show-diff`. */
+    diff?: string;
+    /** The move search hit its byte budget before covering the file. */
+    truncatedSearch?: boolean;
+}
+/** One classified citation: both ends, and how it is anchored. */
+interface CitationResult {
+    citation: Citation;
+    origin: CitationOrigin;
+    anchor: CitationAnchor;
+    /** File line of the marker that names the entry, when one does. */
+    markerLine?: number;
+    /**
+     * File line the citation anchors to now: the claim's first line, or the
+     * first line of the text a marker anchors. Where its findings sit.
+     */
+    anchorLine?: number;
+    /** `null` for an entry with no `claim`: a bare pin, or a marker with no drift check. */
+    claim: ClaimEnd | null;
+    source: SourceEnd;
+}
+interface CitationFinding {
+    rule: CiteRule;
+    /** `manni:cite/<rule>`. */
+    ruleId: string;
+    /** On the family scale: an `error` fails the file; a `warning` or a `notice` is reported and never does. */
+    severity: Severity;
+    message: string;
+    /** Line the finding anchors to: in the page, or in `file` when that is set. */
+    line?: number;
+    /** The manifest, when the finding sits there rather than on the page. */
+    file?: string;
+    id?: string;
+    /** The source, spelled as the entry spells it. */
+    src?: string;
+    newSrc?: string;
+    /** Index in the page's `citations` for a finding about one entry. */
+    index?: number;
+}
+interface PageCitationReport {
+    file: string;
+    format: string;
+    citations: CitationResult[];
+    findings: CitationFinding[];
+    /** Run-level advice, said once per run by the caller: shallow clone, root fallback. */
+    notices: string[];
+}
+/** What `showFile` answers: the bytes, or why it could not. */
+type ShownFile = {
+    text: string;
+} | {
+    missing: "commit" | "path";
+};
+/**
+ * A thin git client over `execFile("git", …)`, memoized per call shape so a
+ * page with a thousand citations against one path runs one `git show`.
+ */
+interface GitClient {
+    available(): Promise<boolean>;
+    head(): Promise<string | null>;
+    /** Tracked files, posix, relative to the root. */
+    lsFiles(): Promise<string[]>;
+    showFile(commit: string, path: string): Promise<ShownFile>;
+    subjectsSince(commit: string, path: string): Promise<string[]>;
+    diffSince(commit: string, path: string): Promise<string>;
+}
+/**
+ * The files a source may resolve to. Built from `git ls-files` when git is
+ * available, else from a walk that follows no symlinks. Every entry is
+ * realpath-contained in the root.
+ */
+interface SourceIndex {
+    files(): readonly string[];
+    /** Whether `path` is a tracked file under the root. An encrypted source is decrypted first, then asked here. */
+    has(path: string): boolean;
+}
+interface CheckPageOptions {
+    /** Absolute directory source paths resolve from. */
+    root: string;
+    /** Default true. False: page-side rules only; every source status is `skipped`. Claim ends are still judged. */
+    checkSources?: boolean;
+    /**
+     * The encryption key: decrypts encrypted sources and keys their pins.
+     * Absent, an encrypted citation is `missing` (no key to decrypt it).
+     */
+    key?: string;
+    severity?: Partial<Record<CiteRule, CiteSeverity>>;
+    /**
+     * The git client the source index and history are read through. Defaults
+     * to one over the root, which is used whenever git is on PATH and the root
+     * is inside a work tree. A caller that wants no git at all passes `noGit()`.
+     */
+    gitClient?: GitClient;
+    sourceIndex?: SourceIndex;
+    /**
+     * The page's citations as merged from a manifest, each with where it sits.
+     * Given, the page's own frontmatter `citations` is not read. Without it, a
+     * grader calling `checkCitations` on a sidecar page would find no citations.
+     */
+    citations?: readonly CitationInput[];
+    /**
+     * The manifest that owns this page's `citations`, when one does. A page
+     * that carries its own anyway is `entry-invalid`, in meta's `external:owned`
+     * words.
+     */
+    owned?: {
+        file: string;
+        collection: string;
+    };
+}
+interface MintOptions {
+    root: string;
+    /** `path`, `path:L`, `path:L1-L2`, or an encrypted `~file` with the same line forms. */
+    src: string;
+    id?: string;
+    /** The claim pin, already taken over the page lines. */
+    claim?: CitationClaim;
+    quote?: boolean;
+    /** A commit to record; `false` records none; absent records HEAD when git has one. */
+    commitSha?: string | false;
+    /**
+     * Write `file` encrypted and pin the lines with the keyed pin; needs `key`.
+     * A source that is already encrypted stays encrypted either way.
+     */
+    encrypt?: boolean;
+    /** The encryption key: encrypts, decrypts an encrypted source, and keys its pin. */
+    key?: string;
+    gitClient?: GitClient;
+    sourceIndex?: SourceIndex;
+}
+/** One marker found in a page body: `cite <id>` in the format's comment syntax. */
+interface InlineStatement {
+    /** File line of the marker. */
+    line: number;
+    /** File line of the anchored text: the rest of the marker's line, else the paragraph or block that follows. */
+    anchorLine?: number;
+    payload: {
+        kind: "ref";
+        id: string;
+    } | {
+        kind: "bad";
+        reason: string;
+        json?: boolean;
+    };
+    /** The marker text between the delimiters, trimmed. */
+    raw: string;
+    /** Character offsets of the whole marker in the file, for rewriting. */
+    start: number;
+    end: number;
+}
+/** A validated citation with where it sits and the marker that names it, before classification. */
+interface PageCitation {
+    citation: Citation;
+    origin: CitationOrigin;
+    /** The first marker naming the entry's id. */
+    marker?: InlineStatement;
+}
+/** What `readPage` returns: the entries, the markers, and page-side findings. */
+interface PageCitations {
+    file: string;
+    format: string;
+    content: string;
+    /** Offset where the body starts (just past the closing fence, or 0). */
+    bodyOffset: number;
+    /** File line of body line 1: the first line after the frontmatter, or 1. */
+    bodyLine: number;
+    citations: PageCitation[];
+    statements: InlineStatement[];
+    findings: CitationFinding[];
+}
+interface CheckOptions {
+    /** Positional inputs; empty means the configured collections' `paths:` (0041). */
+    inputs: string[];
+    /**
+     * `--collection <name>`, repeatable: the collections this run covers. Empty
+     * or absent means every declared one; see `selectCollections`.
+     */
+    collection?: string[];
+    exts?: string[];
+    /** `--exclude`, appended to the selected collections' `exclude:` when the run reads from them. */
+    exclude?: string[];
+    as?: string;
+    configPath?: string;
+    noConfig?: boolean;
+    cwd?: string;
+    stdinContent?: string;
+    allowEmpty?: boolean;
+    respectGitignore?: boolean;
+    onNotice?: (message: string) => void;
+    onConfigLoaded?: (info: {
+        path: string;
+        dir: string;
+    }) => void;
+    baseline?: string | boolean;
+    writeBaseline?: string | boolean;
+    /** `--no-check-sources` (false): page-side rules only. Absent leaves `checkSources:` in charge. */
+    checkSources?: boolean;
+    /**
+     * `--show-diff`: the report will want diffs and commit subjects. The check
+     * is the same either way; the run only says, once, when git is not there
+     * to give them.
+     */
+    showDiff?: boolean;
+    root?: string;
+    /**
+     * The git client every page is checked through. Defaults to one over the
+     * root, used whenever git is on PATH and the root is inside a work tree; a
+     * test hands in a fake.
+     */
+    gitClient?: GitClient;
+    /** Defaults to `process.env`; read for `MANNI_ENCRYPTION_KEY`. A test hands in its own. */
+    env?: NodeJS.ProcessEnv;
+}
+interface CheckRun {
+    results: ValidationResult[];
+    summary: RunSummary;
+    frame: FingerprintContext;
+    pages: PageCitationReport[];
+    warnings: number;
+    notices: number;
+}
+/** Page lines as an editor numbers them, 1-based and inclusive. */
+interface PageLines {
+    start: number;
+    end: number;
+}
+interface AddOptions {
+    page: string;
+    /** The claim's lines as an editor numbers them (`page:L`, `page:L1-L2`). Absent: a bare pin. */
+    pageLines?: PageLines;
+    src: string;
+    id?: string;
+    /** Write a marker above the page lines instead of claim lines, and pin the text it anchors. Needs `pageLines` and `id`. */
+    marker?: boolean;
+    /** The page lines are a fenced block that reproduces the source. Needs `pageLines`. */
+    quote?: boolean;
+    /**
+     * `--encrypt`: write `file` encrypted, with a keyed pin, even when no key is
+     * available yet, in which case `confirm` is asked whether to generate one.
+     * An available key encrypts every add without it, so `false` and absent
+     * are the same.
+     */
+    encrypt?: boolean;
+    /** `false` records no `commit-sha`. */
+    commitSha?: boolean;
+    dryRun?: boolean;
+    as?: string;
+    configPath?: string;
+    noConfig?: boolean;
+    cwd?: string;
+    stdinContent?: string;
+    root?: string;
+    /**
+     * The git client HEAD and the source index are read through. Defaults to
+     * one over the root; a test hands in a fake.
+     */
+    gitClient?: GitClient;
+    /** Defaults to `process.env`; read for `MANNI_ENCRYPTION_KEY`. A test hands in its own. */
+    env?: NodeJS.ProcessEnv;
+    onNotice?: (message: string) => void;
+    onConfigLoaded?: (info: {
+        path: string;
+        dir: string;
+    }) => void;
+    /**
+     * Asked when `encrypt` needs a key and there is none; the CLI passes
+     * `terminalConfirm()`. Absent, the add refuses instead of asking.
+     */
+    confirm?: Confirm;
+}
+/** The manifest half of a write: what it says now, and whether it was saved. */
+interface ManifestWrite {
+    /** The manifest as the run reports it. */
+    file: string;
+    /** 1-based line the written entry now sits on. */
+    line: number;
+    /** The whole manifest, rewritten. */
+    content: string;
+    diff: string;
+    written: boolean;
+}
+interface AddResult {
+    file: string;
+    citation: Citation;
+    /**
+     * Where the entry was written: the page's frontmatter, or the manifest the
+     * page's collection declares. The config decides, not a flag.
+     */
+    placed: "frontmatter" | "manifest";
+    /** The manifest the entry went to, under `placed: "manifest"`. */
+    manifest?: ManifestWrite;
+    /** File lines of the claim after the write: the claim lines, or the text the marker anchors. */
+    claimLines?: PageLines;
+    /** File line of the marker written above the claim, under `marker`. */
+    markerLine?: number;
+    /** The rewritten page. */
+    content: string;
+    diff: string;
+    written: boolean;
+}
+interface UpdateOptions extends Omit<CheckOptions, "baseline" | "writeBaseline"> {
+    accept?: boolean;
+    only?: string[];
+    dryRun?: boolean;
+}
+/** One end `update` rewrote. */
+interface UpdateRewrite {
+    id?: string;
+    /** Index in the page's `citations`. */
+    index: number;
+    /** File line of the entry. */
+    line?: number;
+    end: "claim" | "source";
+    reason: "moved" | "accepted";
+    /** The status that was repaired. */
+    status: "moved" | "changed" | "never-true";
+    /**
+     * Before and after. A moved claim: its file lines. A moved source: its
+     * `src`. An accepted end: its pin.
+     */
+    from: string;
+    to: string;
+    /** An accepted claim: its first file line. */
+    at?: number;
+    /** An accepted claim: the text now pinned, whitespace collapsed. */
+    text?: string;
+    /** An accepted source: its `src`. */
+    src?: string;
+    /** An accepted source: the commit recorded in the entry, when it records one. */
+    commitSha?: string;
+}
+interface UpdatePage {
+    file: string;
+    rewritten: UpdateRewrite[];
+    skipped: CitationFinding[];
+    diff: string;
+    written: boolean;
+    /** The rewritten page, for the stdin input only: it has no file to be written to. */
+    content?: string;
+}
+/** One manifest a run rewrote: what changed in it, and whether it was saved. */
+interface ManifestChange {
+    /** The manifest as the run reports it. */
+    file: string;
+    diff: string;
+    written: boolean;
+}
+interface UpdateRun {
+    pages: UpdatePage[];
+    rewritten: number;
+    skipped: number;
+    /** The manifests this run rewrote, each written once however many pages it holds. */
+    manifests?: ManifestChange[];
+    exitCode: 0 | 1;
+}
+/** One citation `reencryptCitations` rewrote: where it sits, and its source before and after. */
+interface ReencryptedCitation {
+    id?: string;
+    /** Index in `citations`. */
+    index?: number;
+    /** File line of the entry. */
+    line?: number;
+    /** `file` and its line suffix, under the old key and under the new. */
+    from: string;
+    to: string;
+}
+/** What `reencryptCitations` did to one page. */
+interface ReencryptCitationsResult {
+    /** The page with every re-encrypted citation rewritten; the input itself when none was. */
+    content: string;
+    rewritten: ReencryptedCitation[];
+    /** Citations that could not be re-encrypted, and why. A message never names a path. */
+    skipped: {
+        id?: string;
+        index?: number;
+        line?: number;
+        message: string;
+    }[];
+}
+/**
+ * Config under `cite:` in manni.config.yaml, camelCase as `meta:` is. The
+ * document set is not here: proposal 0041 moved `paths` and `exclude` to the
+ * family-level `collections:` list, which every tool reads. Neither is the
+ * encryption key, the top-level `encryptionKey:` every tool reads (0045).
+ */
+interface CiteConfig {
+    allowEmpty?: boolean;
+    respectGitignore?: boolean;
+    root?: string;
+    baseline?: string;
+    checkSources?: boolean;
+    severity?: Partial<Record<CiteRule, CiteSeverity>>;
+}
+interface LoadedCiteConfig {
+    config: CiteConfig;
+    path: string;
+    dir: string;
+    /** The file as the user would name it, for messages. */
+    source: string;
+    /** The family file's top-level `collections:`, parsed by the shared layer (0041). */
+    collections: CollectionConfig[];
+}
+/** What every command core resolves before touching a file. */
+interface CiteRun {
+    config: CiteConfig | null;
+    /** The positional inputs, or the selected collections' `paths:` in declaration order. */
+    inputs: string[];
+    /** Directory the inputs resolve from: cwd for positional inputs, the config directory for collections. */
+    base: string;
+    /**
+     * The collections this run covers: every declared one, or the ones
+     * `--collection` named. `[]` when no config governs the run.
+     */
+    collections: CollectionConfig[];
+    /** Whether `inputs` came from the collections rather than the command line. */
+    fromCollections: boolean;
+    configDir?: string;
+    configPath?: string;
+    /** The config file as the user would name it, for messages. */
+    configSource?: string;
+    /** Absolute root source paths resolve from. */
+    root: string;
+    /**
+     * The family encryption key (proposal 0045): `MANNI_ENCRYPTION_KEY`, else
+     * the config's top-level `encryptionKey:`. Absent when neither is set.
+     */
+    key?: string;
+    /** Where `key` came from. The environment wins over the config. */
+    keySource: KeySource;
+    /**
+     * The config file that governs the run, as discovery found it. A write
+     * that needs a key (`add --encrypt` with none) puts one there.
+     */
+    configFile?: ConfigFile;
+}
+
+/** An operational or usage error in the citation tool: exit 2. */
+declare class CiteError extends ToolError {
+    constructor(message: string);
+}
+
+/**
+ * Which rules fail a run, which only warn, and which are notices.
+ *
+ * Warnings and notices never affect the exit code (docevals' rule).
+ * `source-moved` is a warning because `cite update` fixes it mechanically,
+ * and a PR job that failed on it would make the ratchet noisy. `claim-moved`
+ * is a notice: the text is found verbatim, so nothing drifted.
+ * `claim-changed` is a warning, since it fires on any edit to a pinned
+ * paragraph, a typo fix beside the cited sentence included. A repository that
+ * wants either hard sets `severity: { claim-changed: error }`.
+ */
+
+declare const DEFAULT_SEVERITY: Readonly<Record<CiteRule, CiteSeverity>>;
+declare const RULE_ID_PREFIX = "manni:cite";
+/** `manni:cite/<rule>`: the SARIF rule id and the JUnit failure type. */
+declare function ruleId(rule: CiteRule): string;
+declare function isCiteRule(value: string): value is CiteRule;
+/** The effective severity table: defaults with the config's overrides. */
+declare function resolveSeverity(overrides?: Partial<Record<CiteRule, CiteSeverity>>): Record<CiteRule, CiteSeverity>;
+
+/** The schema's `$defs.fileRef.pattern`, as a RegExp. */
+declare const FILE_PATTERN: RegExp;
+/** A source on the command line: a `file`, then an optional `:L` or `:L1-L2`. */
+declare const SRC_PATTERN: RegExp;
+/**
+ * Parse a command-line source. Throws `CiteError` on bad grammar or an end
+ * line before the start. A one-line `path:L` comes back with `end` equal to
+ * `start`, so a range's width is always `end - start + 1`.
+ */
+declare function parseSrc(src: string): SourceRange;
+/** The canonical spelling: `path:L` for one line, `path:L1-L2` otherwise. */
+declare function formatSrc(range: SourceRange): string;
+/**
+ * The lines an entry's `lines` names. Undefined for a value that is neither
+ * a positive integer nor `"L1-L2"` with `L1 <= L2`: the schema refuses the
+ * first, and `readPage` reports the second.
+ */
+declare function parseLines(spec: LineSpec): PageLines | undefined;
+/** Lines as an entry writes them: the integer for one line, `"L1-L2"` otherwise. */
+declare function lineSpec(lines: PageLines): LineSpec;
+/** Lines as a report spells them: `"9"` or `"9-12"`. */
+declare function spellLines(lines: PageLines): string;
+/** An entry's source as a range. Its lines must already be valid (see `parseLines`). */
+declare function sourceRange(source: CitationSource): SourceRange;
+/** An entry's source spelled as one string, `path:L1-L2`, the way the command line takes it. */
+declare function spellSource(source: CitationSource): string;
+/** A range's lines as an entry writes them; undefined for a whole file. */
+declare function rangeLines(range: SourceRange): LineSpec | undefined;
+
+/** BOM stripped, CRLF folded to LF. */
+declare function normalizeText(text: string): string;
+/** The normalized lines, without the empty element a trailing LF leaves. */
+declare function splitLines(text: string): string[];
+/**
+ * The cited lines joined by LF. Throws `CiteError` when the range runs past
+ * the end of the text (`<path> has N lines; line M is out of range`).
+ */
+declare function sliceLines(lines: readonly string[], range?: {
+    start?: number;
+    end?: number;
+}, label?: string): string;
+/** The pin of the cited lines: plain, or the keyed pin under `key` when one is given. */
+declare function hashRange(text: string, range?: {
+    start?: number;
+    end?: number;
+}, key?: string): string;
+/**
+ * The pin of already-joined lines: `sha256-<hex>`, or with `key` the
+ * `hmac-sha256-<hex>` keyed pin an encrypted source carries. A plain pin
+ * passes `undefined`.
+ */
+declare function hashLines(joined: string, key?: string): string;
+/** Whether a pin is keyed (`hmac-sha256-`), the form an encrypted source carries. */
+declare function isKeyedPin(pin: string): boolean;
+
+/**
+ * How a citation reads on a terminal. A pin is sixty-four hex digits and a
+ * ciphertext is longer still, so both are abbreviated for a person, and every
+ * report and every `add` line abbreviates them the same way.
+ */
+/** `sha256-78af1d33…`, `hmac-sha256-5e0c1a2b…`: the prefix and eight hex digits. */
+declare function shortPin(integrity: string): string;
+/** The seven characters a person reads a commit by. */
+declare function shortCommit(commit: string): string;
+/**
+ * `~AQx7…:2`: an encrypted source, abbreviated, with its line suffix kept. A
+ * plain path is spelled in full, because that is what a reader has to find.
+ */
+declare function shortSrc(src: string): string;
+
+interface BuildIndexOptions {
+    /** `git ls-files` when this client reports git available; a walk when it does not, or with no client. */
+    gitClient?: GitClient;
+}
+declare function buildSourceIndex(root: string, opts?: BuildIndexOptions): Promise<SourceIndex>;
+type ReadSourceResult = {
+    kind: "ok";
+    resolvedPath: string;
+    text: string;
+} | {
+    kind: "missing";
+    reason: MissingReason;
+};
+/**
+ * Read the file a range names. An encrypted source is decrypted under `key`
+ * first: with no key it is `no-key`, under another key `undecryptable`. Never
+ * reads a path the index does not hold.
+ */
+declare function readSource(root: string, index: SourceIndex, range: SourceRange, key?: string): Promise<ReadSourceResult>;
+
+/**
+ * Markers: `cite <id>` inside the format's comment syntax.
+ *
+ * | Format        | Forms                                                        |
+ * |---------------|--------------------------------------------------------------|
+ * | markdown, mdx | `<!-- cite … -->`, `{/* cite … *\/}`, `[comment]: # (cite …)` |
+ * | html, xml     | `<!-- cite … -->`                                            |
+ * | asciidoc      | `// (cite …)`                                                |
+ * | rst           | `.. (cite …)`                                                |
+ *
+ * A marker carries an id and nothing else (`cite true` names id `true`). A
+ * payload starting with `{` was the inline entry of proposal 0044's first
+ * draft; it is `marker-invalid` now, because an entry lives in frontmatter or
+ * a manifest and a source is never written into the body. The scanner uses
+ * `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.
+ *
+ * Every form parses in both markdown and mdx. The first form is what
+ * `formatStatement` writes: the html comment for markdown, the jsx comment
+ * for mdx, which rejects an html comment.
+ */
+
+interface StatementForm {
+    open: string;
+    close: string;
+}
+/** The forms per extractor name. Unknown formats have none. */
+declare function statementForms(format: string): readonly StatementForm[];
+/** Scan a body for statements. `from` maps body offsets/lines to file offsets/lines. */
+declare function parseStatements(body: string, format: string, from?: {
+    offset: number;
+    line: number;
+}): InlineStatement[];
+/** `"\r\n"` when the text's first line break is CRLF, else `"\n"`. */
+declare function detectEol(text: string): "\n" | "\r\n";
+/**
+ * The paragraph starting at or after `offset` (skipping blank lines), as
+ * `{ start, end, line }` file offsets and the file line it starts on. A fence
+ * opener ends the search with no paragraph.
+ */
+declare function paragraphAfter(content: string, offset: number): {
+    start: number;
+    end: number;
+    line: number;
+} | undefined;
+/**
+ * The fenced code block starting at or after `offset` (``` or ~~~; asciidoc
+ * `----`), as file offsets of its content lines and the file line of the
+ * opening fence. `undefined` for formats with no locator (html, xml, rst).
+ */
+declare function fencedBlockAfter(content: string, offset: number, format: string): {
+    start: number;
+    end: number;
+    line: number;
+    text: string;
+} | undefined;
+/**
+ * The fenced block at `offset` in any fence family, for callers that have no
+ * format at hand (the claim search). Undefined when the line at `offset` is
+ * not an opener.
+ */
+declare function fencedBlockAt(content: string, offset: number): {
+    start: number;
+    end: number;
+    line: number;
+    text: string;
+} | undefined;
+/** Every fenced block in the body, for `--quote` without `--claim`. */
+declare function fencedBlocks(content: string, bodyOffset: number, format: string): {
+    start: number;
+    end: number;
+    line: number;
+    text: string;
+}[];
+/** Render a marker in the format's first form, e.g. `<!-- cite fetch-timeout -->`. */
+declare function formatStatement(format: string, payload: {
+    kind: "ref";
+    id: string;
+}): string;
+/**
+ * The fenced block opening on `line`, as the lines it spans, fences included.
+ * Undefined when that line is not an opener the format knows, or the block is
+ * never closed.
+ */
+declare function fenceSpanAt(text: string, line: number, format: string): {
+    start: number;
+    end: number;
+} | undefined;
+/** Whether `line` sits inside a fenced block rather than opening one. */
+declare function insideFence(text: string, bodyOffset: number, line: number, format: string): boolean;
+/**
+ * The lines a marker anchors, as 1-based lines of `text`: the rest of its own
+ * line when that carries text, else the paragraph or fenced block that
+ * follows. With `quote`, the next fenced block after it, wherever that is.
+ * Undefined when nothing follows to anchor.
+ */
+declare function anchoredLines(text: string, after: number, format: string, quote?: boolean): {
+    start: number;
+    end: number;
+} | undefined;
+/** 1-based file line of a file offset, counting CRLF once. */
+declare function lineAt(content: string, offset: number): number;
+/** File offset of the first character of a 1-based line (the length when past the end). */
+declare function offsetOfLine(content: string, line: number): number;
+
+/**
+ * The claim end: the page text a citation supports, classified by the same
+ * machinery as the source end and against the page as it is now.
+ *
+ * The claim's lines are body-relative, so editing the frontmatter never moves
+ * them; every line a person reads is a file line, translated here. The pin
+ * holds at the recorded lines: `current`. The same text is found verbatim
+ * elsewhere in the body: `moved`, once, or `moved-ambiguous`. Nowhere:
+ * `changed`, the sentence was edited. A marker-anchored claim pins what the
+ * marker anchors, so it never moves; it is `current` or `changed`.
+ */
+
+declare function normalizeWhitespace(text: string): string;
+/** `true` when the block's normalized text equals the cited lines under the hashing rule. */
+declare function blockMatches(blockText: string, citedJoined: string): boolean;
+/** Body lines as file lines: body line 1 is the first line after the frontmatter. */
+declare function toFileLines(lines: PageLines, bodyLine: number): PageLines;
+/** File lines as body lines. */
+declare function toBodyLines(lines: PageLines, bodyLine: number): PageLines;
+/** The pin of a page range, under the claim rule: always plain. */
+declare function pinOfLines(lines: readonly string[], range: PageLines): string | undefined;
+/** The first file line of a classified claim: where its findings sit. */
+declare function claimLine(claim: ClaimEnd): number | undefined;
+/**
+ * Classify one entry's claim end against the page. `lines` is the page under
+ * the hashing rule (`splitLines`). `null` for an entry with no `claim`: a
+ * bare pin, or a marker with no drift check on its sentence.
+ */
+declare function claimEnd(page: PageCitations, entry: PageCitation, lines: readonly string[]): ClaimEnd | null;
+/** What `update --accept` re-pins over: the paragraph or fenced block at a line. */
+interface ClaimUnit {
+    lines: PageLines;
+    kind: "paragraph" | "block";
+    text: string[];
+}
+/**
+ * The paragraph or fenced block at a file line. Undefined when the line is
+ * blank, outside the body, or inside a fenced block rather than opening one:
+ * those are the claims `update --accept` skips.
+ *
+ * A paragraph runs from this line to its end, not from the paragraph's own
+ * first line. The line asked about is the claim's first line, and re-pinning
+ * has to leave that where it is, so a claim that started mid-paragraph keeps
+ * starting there.
+ */
+declare function unitAt(page: PageCitations, line: number, lines: readonly string[]): ClaimUnit | undefined;
+/** The lines a marker anchors now, for `update --accept` on a marker-anchored claim. */
+declare function markerUnit(page: PageCitations, entry: PageCitation, lines: readonly string[]): ClaimUnit | undefined;
+
+/** `git` at `root`, as a client; see the module comment for the call shapes. */
+declare function gitClient(root: string): GitClient;
+/**
+ * What a run says, once, when git is not there and the run wanted it: a
+ * citation carries a commit, or `--show-diff` asked for diffs, so history
+ * would have been read. Said through `onNotice`; never a finding.
+ */
+declare const GIT_UNAVAILABLE_HISTORY = "git is not available here, so citations are checked without history: no never-true, no diffs, no commit subjects.";
+/** What `add` and `update --accept` say, once, when a commit would have been recorded and git is not there. */
+declare const GIT_UNAVAILABLE_COMMIT = "git is not available here, so the citation records no commit.";
+/**
+ * A client that answers "no git": `available()` false, everything else empty.
+ * What a caller passes as `gitClient` to run without git where git is there.
+ */
+declare function noGit(): GitClient;
+
+/**
+ * Source-side classification of one citation.
+ *
+ * current: the range hashes to the pin. moved / moved-ambiguous: a window of
+ * the same length hashes equal elsewhere (once / more than once); whole-file
+ * citations never move. changed: none equal; with a commit and history,
+ * the diff and commit subjects are attached (pretty-only). never-true: no
+ * window of the range's length anywhere in the file at the commit hashes to
+ * the pin, or the path is absent there. The recorded lines are tried first;
+ * the rest of the file is searched because `update` rewrites `src` for a move
+ * without touching `commit`, so the lines a pin was minted from may sit
+ * elsewhere in the file as it was then. A window that matches there is the
+ * original for the move search below. missing: the source cannot be read.
+ *
+ * Move search: with the original text (git could show the commit), candidate
+ * offsets are where the first line matches, compared lexically, hashed only on
+ * a full match. Without it, a ±2000-line window around the original position
+ * first, then the rest of the file under a 64 MiB hashing budget; past the
+ * budget the result is `changed` with `truncatedSearch`.
+ *
+ * Order, as the ladder has it: the move search runs whenever the pin does not
+ * hold, and history decides only what a non-match is called. So a pin that
+ * never held at its commit but whose bytes sit elsewhere in the file is
+ * `moved`, not `never-true`; the search sees the file as it is.
+ */
+
+declare const MOVE_WINDOW_LINES = 2000;
+declare const MOVE_BUDGET_BYTES: number;
+declare const MAX_RANGE_LINES = 5000;
+interface ClassifyOptions {
+    root: string;
+    index: SourceIndex;
+    /** History is read through it when it reports git available, and never otherwise. */
+    git: GitClient;
+    /** The encryption key: decrypts an encrypted source and keys its pin. */
+    key?: string;
+    /** Hashing budget for the blind move search, in bytes. Default `MOVE_BUDGET_BYTES`. */
+    budget?: number;
+}
+interface FindWindowsOptions {
+    /** The 1-based start line the range was pinned at: the blind search begins around it. */
+    around?: number;
+    /** The cited lines at the commit, when git could show them: enables the first-line filter. */
+    original?: readonly string[];
+    /** Hashing budget for the blind search, in bytes. Default `MOVE_BUDGET_BYTES`. */
+    budget?: number;
+}
+/**
+ * Pure move search over normalized lines: the 1-based start lines where a
+ * window of `length` lines hashes to `pin`. `original` (the cited lines at the
+ * commit, when known) enables the first-line filter. `key` keys the hash for
+ * an encrypted source's pin and is `undefined` for a plain one.
+ */
+declare function findWindows(lines: readonly string[], length: number, pin: string, key: string | undefined, opts?: FindWindowsOptions): {
+    starts: number[];
+    truncated: boolean;
+};
+/**
+ * What git could say about the pin at the recorded commit. `unknown` is a
+ * file at the commit too large to search under the budget with the pin found
+ * nowhere in the part that was: neither true nor never true. `original`
+ * carries the cited lines as they were then, which `reencryptCitations` re-keys
+ * from when the pin no longer holds today.
+ */
+type History = {
+    kind: "none";
+} | {
+    kind: "unavailable";
+} | {
+    kind: "never-true";
+} | {
+    kind: "unknown";
+} | {
+    kind: "original";
+    lines: string[];
+};
+declare function historyOf(git: GitClient, commit: string, path: string, range: SourceRange, pin: string, key: string | undefined, budget: number | undefined): Promise<History>;
+declare function classifyCitation(entry: PageCitation, opts: ClassifyOptions): Promise<SourceEnd>;
+
+declare const MAX_MARKERS_PER_PAGE = 500;
+/** What a marker with a JSON payload is told, since an entry never lives in the body. */
+declare const MARKER_JSON = "A marker names an entry by id. Write the entry in frontmatter or the sidecar.";
+interface ReadPageOptions {
+    /** Extractor name; derived from the file's extension when absent. */
+    format?: string;
+    /**
+     * The page's citations as a manifest owns them, already merged. Given, the
+     * page's own frontmatter `citations` is not read.
+     */
+    citations?: readonly CitationInput[];
+    /**
+     * The manifest that owns this page's `citations`, when one does. A page
+     * that also carries its own is `entry-invalid`: neither channel wins, and
+     * the discarded value would be exactly the one nobody checked.
+     */
+    owned?: {
+        file: string;
+        collection: string;
+    };
+}
+/** Meta's `external:owned` sentence, said by `cite check` under `entry-invalid`. */
+declare function ownedMessage(owner: {
+    file: string;
+    collection: string;
+}): string;
+/** Ajv validation of one entry object against `$defs.citationEntry`; the first error text, or undefined. */
+declare function validateEntry(entry: unknown): string | undefined;
+declare function pickExtractor(file: string, format: string | undefined): MetadataExtractor;
+/** File line of body line 1: the first line after the frontmatter, or 1. */
+declare function bodyLineOf(content: string, bodyOffset: number): number;
+declare function readPage(file: string, content: string, opts?: ReadPageOptions): PageCitations;
+
+/** The one key cite keeps in a manifest. */
+declare const CITATIONS_KEY = "citations";
+/** A manifest that owns `citations` for one collection. */
+interface CitationManifest {
+    /** The collection that declares it. */
+    collection: string;
+    /** Absolute path of the manifest file. */
+    path: string;
+    /** The manifest as the run reports it. */
+    file: string;
+    /** `path`, or the page field the manifest joins on. */
+    join: string;
+}
+/** Where one page's citations are kept, and what the manifest already holds. */
+interface PageSidecar {
+    /** The manifest that owns this page's citations, when one does. */
+    owner?: CitationManifest;
+    /**
+     * The key under which this page is written in the manifest: its path
+     * relative to the config directory, or its value of the join field.
+     * Undefined when the manifest joins on a field the page does not carry, so
+     * a writer refuses rather than inventing a key.
+     */
+    entry?: string;
+    /** The manifest's entries for this page, when it supplies any. */
+    citations?: CitationInput[];
+    /** Field-joined entries this page matched, for the duplicate-join check. */
+    joins: readonly ExternalMetadataJoin[];
+}
+interface CitationSidecars {
+    /** The manifests that own `citations`, by collection. */
+    manifests: readonly CitationManifest[];
+    /** Directory manifest paths and manifest keys resolve from. */
+    configDir: string;
+    /** Directory the run's file labels are relative to. */
+    base: string;
+    forPage(label: string, content: string, format?: string): PageSidecar;
+    /**
+     * Manifest entries naming a page this run did not load, under meta's own
+     * corpus invariant. `covered` names the collections a `--collection` run
+     * narrowed to, or `undefined` for a whole-corpus run.
+     */
+    orphans(loaded: readonly string[], covered?: readonly string[]): ExternalMetadataEntry[];
+    /** Field entries no loaded page matched, same invariant. */
+    orphanJoins(matched: ReadonlyMap<string, ReadonlySet<string>>, covered?: readonly string[]): ExternalMetadataEntry[];
+}
+interface LoadSidecarOptions {
+    /** Every collection the config declares, not only the ones the run selected. */
+    collections: readonly CollectionConfig[];
+    /** The config file's directory. */
+    configDir: string;
+    /** Directory the run's file labels are relative to. */
+    base: string;
+    /** The config file as the user would name it, for the URL refusal. */
+    configSource: string;
+    /** The family encryption key, for a join field a page holds encrypted. */
+    key?: string;
+    /** The tool's error class; `CiteError` unless a sibling command says otherwise. */
+    toError?: (message: string) => Error;
+}
+/** `collection <name>: citations cannot come from a URL manifest, because cite writes them.` */
+declare function urlManifestRefusal(source: string, collection: string): string;
+/** `<page> is in collections a and b, and both keep citations in a manifest.` */
+declare function twoManifestsRefusal(label: string, a: string, b: string): string;
+/**
+ * Load every manifest that owns `citations`, or `null` when none does — which
+ * is every setup that keeps its citations in frontmatter, and costs nothing.
+ *
+ * Only the citations-owning manifests are loaded. A sibling manifest of the
+ * same collection, supplying meta's own keys from a URL, is none of cite's
+ * business and is never fetched here.
+ */
+declare function loadCitationSidecars(opts: LoadSidecarOptions): Promise<CitationSidecars | null>;
+/** The refusal a whole-corpus run raises for a manifest entry naming nothing. */
+declare function orphanRefusal(orphans: readonly ExternalMetadataEntry[], toError?: (message: string) => Error): Error;
+/**
+ * Two pages carrying one `join:` value: the manifest cannot tell them apart,
+ * and cite would write one page's entry over the other's. Meta files this as
+ * a finding on each document; here it is the run's problem, because the run
+ * writes.
+ */
+declare function duplicateJoinRefusal(field: string, value: string, file: string, labels: readonly string[]): string;
+/**
+ * Load the sidecars a resolved run governs; `null` with no config, or no
+ * citations manifest. `base` overrides the run's when a command labels its
+ * pages from somewhere else — `add` takes one page from the command line and
+ * labels it from the working directory, whatever the collections would.
+ */
+declare function sidecarsFor(run: CiteRun, over?: {
+    base?: string;
+    toError?: (message: string) => Error;
+}): Promise<CitationSidecars | null>;
+
+interface SpliceManifestOptions {
+    /**
+     * The document entry: its path relative to the config's directory, or its
+     * value of the join field when `join` names one. A path entry matches
+     * however the manifest spells it (`./docs/a.md` is `docs/a.md`); a join
+     * value matches exactly.
+     */
+    entry: string;
+    /** The owned key to write. */
+    key: string;
+    /** The value to write. Mappings and lists are written in block style. */
+    value: unknown;
+    /** `path` (the default) or the frontmatter field the manifest joins on. */
+    join?: string;
+    /** The manifest as the run reports it, for error messages. */
+    file?: string;
+}
+interface SplicedManifest {
+    /** The whole manifest, with the one value rewritten. */
+    text: string;
+    /** 1-based line where the written value now starts. */
+    line: number;
+}
+/**
+ * Rewrite `options.key` of `options.entry` in the manifest `text` to
+ * `options.value`, and return the new text and the line the value starts on.
+ *
+ * Throws `DocmetaError`, and never returns a partial result, when:
+ *  - the text is not valid YAML, or its top level is not a mapping;
+ *  - the entry is named twice, or is not a mapping;
+ *  - the key is set twice in the entry, or is `$schema`;
+ *  - the value is `undefined`;
+ *  - the key or entry is absent and would go into a flow mapping that has
+ *    members (`{ jira: A }`), which this writer does not add to;
+ *  - the key is written as an explicit `? key`;
+ *  - the result does not read back as written.
+ */
+declare function spliceManifestValue(text: string, options: SpliceManifestOptions): SplicedManifest;
+
+/** One manifest held for the length of a run: its text before, and now. */
+interface HeldManifest {
+    /** Absolute path, the write target. */
+    path: string;
+    /** The manifest as the run reports it. */
+    file: string;
+    /** The bytes as they were read. */
+    before: string;
+    /** The bytes as the run has rewritten them. */
+    text: string;
+}
+/** Every manifest one run writes, read once and spliced in memory. */
+declare class ManifestSet {
+    private readonly held;
+    /** Read a manifest, or hand back the copy this run has already rewritten. */
+    hold(manifest: CitationManifest): Promise<HeldManifest>;
+    /**
+     * Write one page's whole `citations` list into its entry, and answer where
+     * the entry at `index` now sits. The manifest is not saved: `changed()`
+     * lists what the run would write.
+     */
+    write(manifest: CitationManifest, entry: string, citations: readonly unknown[], index: number): Promise<{
+        file: string;
+        line: number;
+    }>;
+    /** The manifests this run rewrote, with the diff of each. */
+    changed(): {
+        path: string;
+        file: string;
+        before: string;
+        text: string;
+        diff: string;
+    }[];
+}
+/** `spliceManifestValue`, with meta's refusal reported as this tool's. */
+declare function splice(text: string, options: Parameters<typeof spliceManifestValue>[1]): {
+    text: string;
+    line: number;
+};
+/**
+ * The 1-based line of one item of an entry's `citations`, in a manifest that
+ * may not have been written yet. The loader answers this for a manifest on
+ * disk; a freshly spliced one has to be read where it stands, so `add` can
+ * say where the entry it just wrote went.
+ */
+declare function itemLine(text: string, entry: string, index: number, join: string): number | undefined;
+
+/**
+ * `checkCitations`: the programmatic core a docevals `tool:cite` grader calls
+ * for one page. Reads the entries and markers, classifies both ends of each
+ * citation, applies the severity table, and returns findings whose messages
+ * spell sources exactly as the entry spelled them.
+ *
+ * The claim end is page-side, so it is judged even under `--no-check-sources`,
+ * which a public docs checkout runs. The source end needs the files.
+ *
+ * `quote: true` is settled here. The claim must still be a fenced block
+ * (`anchor-invalid`), and the block is faithful when it reproduces the cited
+ * lines as pinned (which survives a move and a missing source) or as they are
+ * now (a block someone refreshed ahead of a re-mint). Neither: `quote-drift`.
+ */
+
+declare function checkCitations(page: {
+    file: string;
+    content: string;
+    format?: string;
+}, opts: CheckPageOptions): Promise<PageCitationReport>;
+
+/** The one place a source end's message is composed, per status. */
+declare function messageFor(source: SourceEnd): string;
+/** The one place a claim end's message is composed, per status. */
+declare function claimMessageFor(result: CitationResult): string;
+/** Findings for classified citations under a severity table; `off` rules produce none. */
+declare function findingsFor(results: readonly CitationResult[], severity: Readonly<Record<CiteRule, CiteSeverity>>): CitationFinding[];
+/**
+ * Where a finding is located once it becomes a `FieldError`: the page, or
+ * the manifest the entry sits in.
+ *
+ * A manifest outside the repository has no location any reporter can use —
+ * SARIF drops a uri that rebases to `../…`, and a GitHub annotation on one
+ * lands nowhere — so the finding falls back to the page, and its line goes
+ * with the file it belonged to. Inside the tree, both travel, and `file`
+ * is what every reporter reads to annotate the manifest instead.
+ */
+declare function errorSite(finding: CitationFinding): Pick<CitationFinding, "line" | "file">;
+declare function toValidationResult(report: PageCitationReport): ValidationResult;
+
+/** Append one entry to `citations` (creating the key), via the format's extractor. */
+declare function appendFrontmatterCitation(content: string, format: string, citation: Citation, filePath?: string): string;
+/**
+ * The entry as a plain object, in the order a reader scans it, with every
+ * absent optional left out rather than written as `null`.
+ */
+declare function entryObject(citation: Citation): Record<string, unknown>;
+/** One scalar of an entry a repair may rewrite: a file, an end's lines, its pin, or the commit. */
+type EntryPath = readonly [
+    end: "claim" | "source",
+    field: "file" | "lines" | "integrity" | "commit-sha"
+];
+/** Replace the scalar on one line of entry N, e.g. `source.lines` after a move. */
+declare function spliceEntryField(content: string, format: string, index: number, path: EntryPath, value: LineSpec): string;
+/** Insert a statement line before the line containing `offset`, with the page's EOL. */
+declare function insertStatementBefore(content: string, offset: number, statement: string): string;
+/**
+ * A unified diff of two texts, `---`/`+++` headers with the same label. Lines
+ * are the hashing rule's (`splitLines`): a BOM is never part of a line, so a
+ * page that carries one diffs the same as one that does not.
+ */
+declare function unifiedDiff(label: string, before: string, after: string): string;
+
+declare function mintCitation(opts: MintOptions): Promise<Citation>;
+
+declare const CITE_SECTION = "cite";
+declare const DEFAULT_CITE_BASELINE_PATH = ".manni-cite-baseline.json";
+/**
+ * Validate the `cite:` slice of a family file. `raw` is what the loader cut
+ * out: `null` for an empty section, which is the same as no keys at all.
+ * `source` is the file as the user would name it, for the messages.
+ */
+declare function parseCiteConfig(raw: unknown, source: string): CiteConfig;
+/**
+ * The family file itself, found as `loadCiteConfig` finds it but before its
+ * `cite:` slice is parsed: the text, the section shape and the family keys
+ * (`collections:`, `encryptionKey:`), for a caller that needs more than the
+ * values, such as a write that puts a key there. `null` when discovery finds
+ * nothing.
+ */
+declare function readCiteConfigFile(explicitPath: string | undefined, cwd: string): Promise<ConfigFile | null>;
+/**
+ * Load the config from an explicit path (an error if missing) or by
+ * discovery: cwd and each ancestor up to the nearest `.git` boundary, reading
+ * `manni.config.yaml` at its `cite:` key. A family file with neither `cite:`
+ * nor `collections:` belongs to a sibling tool and discovery keeps looking;
+ * one with `collections:` alone is this tool's config with no options of its
+ * own (0041). See src/shared/config-file.ts for the rules. `null` when
+ * discovery finds nothing.
+ */
+declare function loadCiteConfig(explicitPath?: string, cwd?: string): Promise<LoadedCiteConfig | null>;
+interface CiteRunOptions {
+    cwd: string;
+    /** `-c/--config`. */
+    configPath?: string;
+    /** `--no-config`: skip discovery and run on the built-in defaults. */
+    noConfig?: boolean;
+    /** Positional inputs; empty means fall back to the selected collections' `paths:`. */
+    inputs: string[];
+    /**
+     * `--collection <name>`, repeatable: the collections this run covers. Empty
+     * or absent means every declared one, the same thing, because commander's
+     * collector hands `[]` over when the flag was never typed.
+     */
+    collection?: string[];
+    /** `--root`, cwd-relative. */
+    root?: string;
+    onConfigLoaded?: (info: {
+        path: string;
+        dir: string;
+    }) => void;
+    /** Told once when the root fell back to cwd. */
+    onNotice?: (message: string) => void;
+    /** Defaults to `process.env`; a test hands in its own. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Settle what every command core needs before it touches a file: which
+ * config governs the run, what to resolve and from where, the root `src:`
+ * paths resolve against, and the encryption key.
+ */
+declare function resolveCiteRun(opts: CiteRunOptions): Promise<CiteRun>;
+
+declare function runCheck(opts: CheckOptions): Promise<CheckRun>;
+
+declare function runAdd(opts: AddOptions): Promise<AddResult>;
+
+declare function runUpdate(opts: UpdateOptions): Promise<UpdateRun>;
+
+/**
+ * `reencryptCitations`: re-encrypt one page's encrypted citations under a new
+ * key, for `manni key rotate` (proposal 0045). It reads sources and never
+ * writes: the caller gets the rewritten page back, and writes it only once
+ * every page in the run could be re-encrypted.
+ *
+ * A citation counts as done only when its `source.file` decrypts under the
+ * new key *and* its pin holds under the new key. Either alone is a half
+ * rotation, and a rerun has to finish it rather than declare it done. Meta's
+ * walker cannot leave one today, because it skips the whole `citations` key
+ * and cite encrypts in its own `cite-src` context; an interrupted run, a hand
+ * edit, or a second writer of the same manifest can.
+ *
+ * The path must be tracked, and the pin must hold under the old key, over the
+ * lines as they are today or, with git, as they were at the entry's
+ * `commit-sha` (the classifier's history search). Then `file` becomes the
+ * path's ciphertext under the new key, its lines kept, and `integrity` the
+ * keyed pin under it, so a `changed` citation stays exactly as changed. A pin
+ * that holds nowhere is skipped, with `update --accept` named as the repair.
+ * No message names a path.
+ */
+
+/** Options every re-encryption takes, whichever channel the entry lives in. */
+interface ReencryptOptions {
+    root: string;
+    fromKey: string;
+    toKey: string;
+    /** History and the source index are read through it; defaults to one over the root. */
+    gitClient?: GitClient;
+    sourceIndex?: SourceIndex;
+}
+declare function reencryptCitations(page: {
+    file: string;
+    content: string;
+    format?: string;
+}, opts: ReencryptOptions): Promise<ReencryptCitationsResult>;
+/** What `reencryptCitationEntries` did to one page's manifest entries. */
+interface ReencryptEntriesResult {
+    /** The entries as they should now be written, a copy of what came in. */
+    entries: unknown[];
+    /** Whether any of them changed. */
+    changed: boolean;
+    rewritten: ReencryptedCitation[];
+    skipped: {
+        id?: string;
+        index?: number;
+        line?: number;
+        message: string;
+    }[];
+}
+/**
+ * The same rotation, for a page whose citations live in a manifest.
+ *
+ * The entries come from meta's merge, so they are plain values; each one is
+ * validated as `readPage` validates a frontmatter entry, and an encrypted
+ * source's `file` and `integrity` are rewritten in place. The caller writes
+ * the whole list back with one splice, once every page of the run could be
+ * re-encrypted.
+ */
+declare function reencryptCitationEntries(page: {
+    file: string;
+    content: string;
+    format?: string;
+    citations: readonly CitationInput[];
+}, opts: ReencryptOptions): Promise<ReencryptEntriesResult>;
+
+/**
+ * Pretty output for `check` and `update`.
+ *
+ * A citation is one row: its name, its claim end, its source end, and, when a
+ * manifest owns the entry, where that is. Both ends read in file lines, the
+ * only lines a person sees. Marks: ✓ current, ✗ error, ↕ warning, ℹ notice,
+ * · skipped or baselined; a file line is ✓, ✗ (an error), ⚠ (a warning, no
+ * error) or ℹ (notices only). Diffs, commit subjects and a changed claim's
+ * current lines print only under `showDiff`; a decrypted path only under
+ * `reveal`. Colour via `shouldColor`; never under `--no-color`/`NO_COLOR`.
+ */
+
+interface PrettyOptions {
+    color: boolean;
+    quiet?: boolean;
+    showDiff?: boolean;
+    reveal?: boolean;
+}
+declare function renderCheckPretty(run: CheckRun, opts: PrettyOptions): string;
+/** What one rewritten end says it did. */
+declare function rewriteLine(rewrite: UpdateRewrite): string;
+declare function renderUpdatePretty(run: UpdateRun, opts: PrettyOptions): string;
+
+/**
+ * JSON output. `{ summary, pages }` for check; the `UpdateRun` for update.
+ *
+ * A citation prints its two ends and how they are anchored. `resolvedPath`,
+ * `diff`, `commitsSince` and a changed claim's current lines are left out of
+ * every citation: output never says more than the page did. It is an
+ * allowlist rather than a strip, so a field added to the result stays private
+ * until someone decides here that it is safe to print.
+ */
+
+declare function renderCheckJson(run: CheckRun): string;
+declare function renderUpdateJson(run: UpdateRun): string;
+
+declare function renderCheckGithub(run: CheckRun): string;
+
+/**
+ * The citation tool's programmatic API, exported from the package as the
+ * `cite` namespace: `import { cite } from "@hawkeyexl/manni"`.
+ */
+
+type index$1_AddOptions = AddOptions;
+type index$1_AddResult = AddResult;
+type index$1_BuildIndexOptions = BuildIndexOptions;
+declare const index$1_CITATIONS_KEY: typeof CITATIONS_KEY;
+declare const index$1_CITE_RULES: typeof CITE_RULES;
+declare const index$1_CITE_SECTION: typeof CITE_SECTION;
+type index$1_CheckOptions = CheckOptions;
+type index$1_CheckPageOptions = CheckPageOptions;
+type index$1_CheckRun = CheckRun;
+type index$1_Citation = Citation;
+type index$1_CitationAnchor = CitationAnchor;
+type index$1_CitationClaim = CitationClaim;
+type index$1_CitationFinding = CitationFinding;
+type index$1_CitationInput = CitationInput;
+type index$1_CitationManifest = CitationManifest;
+type index$1_CitationOrigin = CitationOrigin;
+type index$1_CitationResult = CitationResult;
+type index$1_CitationSidecars = CitationSidecars;
+type index$1_CitationSource = CitationSource;
+type index$1_CiteConfig = CiteConfig;
+type index$1_CiteError = CiteError;
+declare const index$1_CiteError: typeof CiteError;
+type index$1_CiteRule = CiteRule;
+type index$1_CiteRun = CiteRun;
+type index$1_CiteRunOptions = CiteRunOptions;
+type index$1_CiteSeverity = CiteSeverity;
+type index$1_ClaimEnd = ClaimEnd;
+type index$1_ClaimStatus = ClaimStatus;
+type index$1_ClaimUnit = ClaimUnit;
+type index$1_ClassifyOptions = ClassifyOptions;
+declare const index$1_DEFAULT_CITE_BASELINE_PATH: typeof DEFAULT_CITE_BASELINE_PATH;
+declare const index$1_DEFAULT_SEVERITY: typeof DEFAULT_SEVERITY;
+type index$1_EntryPath = EntryPath;
+declare const index$1_FILE_PATTERN: typeof FILE_PATTERN;
+type index$1_FindWindowsOptions = FindWindowsOptions;
+declare const index$1_GIT_UNAVAILABLE_COMMIT: typeof GIT_UNAVAILABLE_COMMIT;
+declare const index$1_GIT_UNAVAILABLE_HISTORY: typeof GIT_UNAVAILABLE_HISTORY;
+type index$1_GitClient = GitClient;
+type index$1_HeldManifest = HeldManifest;
+type index$1_History = History;
+type index$1_InlineStatement = InlineStatement;
+type index$1_LineSpec = LineSpec;
+type index$1_LoadSidecarOptions = LoadSidecarOptions;
+type index$1_LoadedCiteConfig = LoadedCiteConfig;
+declare const index$1_MARKER_JSON: typeof MARKER_JSON;
+declare const index$1_MAX_MARKERS_PER_PAGE: typeof MAX_MARKERS_PER_PAGE;
+declare const index$1_MAX_RANGE_LINES: typeof MAX_RANGE_LINES;
+declare const index$1_MOVE_BUDGET_BYTES: typeof MOVE_BUDGET_BYTES;
+declare const index$1_MOVE_WINDOW_LINES: typeof MOVE_WINDOW_LINES;
+type index$1_ManifestChange = ManifestChange;
+type index$1_ManifestSet = ManifestSet;
+declare const index$1_ManifestSet: typeof ManifestSet;
+type index$1_ManifestWrite = ManifestWrite;
+type index$1_MintOptions = MintOptions;
+type index$1_MissingReason = MissingReason;
+type index$1_OriginKind = OriginKind;
+type index$1_PageCitation = PageCitation;
+type index$1_PageCitationReport = PageCitationReport;
+type index$1_PageCitations = PageCitations;
+type index$1_PageLines = PageLines;
+type index$1_PageSidecar = PageSidecar;
+type index$1_PrettyOptions = PrettyOptions;
+declare const index$1_RULE_ID_PREFIX: typeof RULE_ID_PREFIX;
+type index$1_ReadPageOptions = ReadPageOptions;
+type index$1_ReadSourceResult = ReadSourceResult;
+type index$1_ReencryptCitationsResult = ReencryptCitationsResult;
+type index$1_ReencryptEntriesResult = ReencryptEntriesResult;
+type index$1_ReencryptOptions = ReencryptOptions;
+type index$1_ReencryptedCitation = ReencryptedCitation;
+declare const index$1_SRC_PATTERN: typeof SRC_PATTERN;
+type index$1_ShownFile = ShownFile;
+type index$1_SourceEnd = SourceEnd;
+type index$1_SourceIndex = SourceIndex;
+type index$1_SourceRange = SourceRange;
+type index$1_SourceStatus = SourceStatus;
+type index$1_StatementForm = StatementForm;
+type index$1_UpdateOptions = UpdateOptions;
+type index$1_UpdatePage = UpdatePage;
+type index$1_UpdateRewrite = UpdateRewrite;
+type index$1_UpdateRun = UpdateRun;
+declare const index$1_anchoredLines: typeof anchoredLines;
+declare const index$1_appendFrontmatterCitation: typeof appendFrontmatterCitation;
+declare const index$1_blockMatches: typeof blockMatches;
+declare const index$1_bodyLineOf: typeof bodyLineOf;
+declare const index$1_buildSourceIndex: typeof buildSourceIndex;
+declare const index$1_checkCitations: typeof checkCitations;
+declare const index$1_claimEnd: typeof claimEnd;
+declare const index$1_claimLine: typeof claimLine;
+declare const index$1_claimMessageFor: typeof claimMessageFor;
+declare const index$1_classifyCitation: typeof classifyCitation;
+declare const index$1_detectEol: typeof detectEol;
+declare const index$1_duplicateJoinRefusal: typeof duplicateJoinRefusal;
+declare const index$1_entryObject: typeof entryObject;
+declare const index$1_errorSite: typeof errorSite;
+declare const index$1_fenceSpanAt: typeof fenceSpanAt;
+declare const index$1_fencedBlockAfter: typeof fencedBlockAfter;
+declare const index$1_fencedBlockAt: typeof fencedBlockAt;
+declare const index$1_fencedBlocks: typeof fencedBlocks;
+declare const index$1_findWindows: typeof findWindows;
+declare const index$1_findingsFor: typeof findingsFor;
+declare const index$1_formatSrc: typeof formatSrc;
+declare const index$1_formatStatement: typeof formatStatement;
+declare const index$1_gitClient: typeof gitClient;
+declare const index$1_hashLines: typeof hashLines;
+declare const index$1_hashRange: typeof hashRange;
+declare const index$1_historyOf: typeof historyOf;
+declare const index$1_insertStatementBefore: typeof insertStatementBefore;
+declare const index$1_insideFence: typeof insideFence;
+declare const index$1_isCiteRule: typeof isCiteRule;
+declare const index$1_isKeyedPin: typeof isKeyedPin;
+declare const index$1_itemLine: typeof itemLine;
+declare const index$1_lineAt: typeof lineAt;
+declare const index$1_lineSpec: typeof lineSpec;
+declare const index$1_loadCitationSidecars: typeof loadCitationSidecars;
+declare const index$1_loadCiteConfig: typeof loadCiteConfig;
+declare const index$1_markerUnit: typeof markerUnit;
+declare const index$1_messageFor: typeof messageFor;
+declare const index$1_mintCitation: typeof mintCitation;
+declare const index$1_noGit: typeof noGit;
+declare const index$1_normalizeText: typeof normalizeText;
+declare const index$1_normalizeWhitespace: typeof normalizeWhitespace;
+declare const index$1_offsetOfLine: typeof offsetOfLine;
+declare const index$1_orphanRefusal: typeof orphanRefusal;
+declare const index$1_ownedMessage: typeof ownedMessage;
+declare const index$1_paragraphAfter: typeof paragraphAfter;
+declare const index$1_parseCiteConfig: typeof parseCiteConfig;
+declare const index$1_parseLines: typeof parseLines;
+declare const index$1_parseSrc: typeof parseSrc;
+declare const index$1_parseStatements: typeof parseStatements;
+declare const index$1_pickExtractor: typeof pickExtractor;
+declare const index$1_pinOfLines: typeof pinOfLines;
+declare const index$1_rangeLines: typeof rangeLines;
+declare const index$1_readCiteConfigFile: typeof readCiteConfigFile;
+declare const index$1_readPage: typeof readPage;
+declare const index$1_readSource: typeof readSource;
+declare const index$1_reencryptCitationEntries: typeof reencryptCitationEntries;
+declare const index$1_reencryptCitations: typeof reencryptCitations;
+declare const index$1_renderCheckGithub: typeof renderCheckGithub;
+declare const index$1_renderCheckJson: typeof renderCheckJson;
+declare const index$1_renderCheckPretty: typeof renderCheckPretty;
+declare const index$1_renderUpdateJson: typeof renderUpdateJson;
+declare const index$1_renderUpdatePretty: typeof renderUpdatePretty;
+declare const index$1_resolveCiteRun: typeof resolveCiteRun;
+declare const index$1_resolveSeverity: typeof resolveSeverity;
+declare const index$1_rewriteLine: typeof rewriteLine;
+declare const index$1_ruleId: typeof ruleId;
+declare const index$1_runAdd: typeof runAdd;
+declare const index$1_runCheck: typeof runCheck;
+declare const index$1_runUpdate: typeof runUpdate;
+declare const index$1_shortCommit: typeof shortCommit;
+declare const index$1_shortPin: typeof shortPin;
+declare const index$1_shortSrc: typeof shortSrc;
+declare const index$1_sidecarsFor: typeof sidecarsFor;
+declare const index$1_sliceLines: typeof sliceLines;
+declare const index$1_sourceRange: typeof sourceRange;
+declare const index$1_spellLines: typeof spellLines;
+declare const index$1_spellSource: typeof spellSource;
+declare const index$1_splice: typeof splice;
+declare const index$1_spliceEntryField: typeof spliceEntryField;
+declare const index$1_splitLines: typeof splitLines;
+declare const index$1_statementForms: typeof statementForms;
+declare const index$1_toBodyLines: typeof toBodyLines;
+declare const index$1_toFileLines: typeof toFileLines;
+declare const index$1_toValidationResult: typeof toValidationResult;
+declare const index$1_twoManifestsRefusal: typeof twoManifestsRefusal;
+declare const index$1_unifiedDiff: typeof unifiedDiff;
+declare const index$1_unitAt: typeof unitAt;
+declare const index$1_urlManifestRefusal: typeof urlManifestRefusal;
+declare const index$1_validateEntry: typeof validateEntry;
+declare namespace index$1 {
+  export { type index$1_AddOptions as AddOptions, type index$1_AddResult as AddResult, type index$1_BuildIndexOptions as BuildIndexOptions, index$1_CITATIONS_KEY as CITATIONS_KEY, index$1_CITE_RULES as CITE_RULES, index$1_CITE_SECTION as CITE_SECTION, type index$1_CheckOptions as CheckOptions, type index$1_CheckPageOptions as CheckPageOptions, type index$1_CheckRun as CheckRun, type index$1_Citation as Citation, type index$1_CitationAnchor as CitationAnchor, type index$1_CitationClaim as CitationClaim, type index$1_CitationFinding as CitationFinding, type index$1_CitationInput as CitationInput, type index$1_CitationManifest as CitationManifest, type index$1_CitationOrigin as CitationOrigin, type index$1_CitationResult as CitationResult, type index$1_CitationSidecars as CitationSidecars, type index$1_CitationSource as CitationSource, type index$1_CiteConfig as CiteConfig, index$1_CiteError as CiteError, type index$1_CiteRule as CiteRule, type index$1_CiteRun as CiteRun, type index$1_CiteRunOptions as CiteRunOptions, type index$1_CiteSeverity as CiteSeverity, type index$1_ClaimEnd as ClaimEnd, type index$1_ClaimStatus as ClaimStatus, type index$1_ClaimUnit as ClaimUnit, type index$1_ClassifyOptions as ClassifyOptions, index$1_DEFAULT_CITE_BASELINE_PATH as DEFAULT_CITE_BASELINE_PATH, index$1_DEFAULT_SEVERITY as DEFAULT_SEVERITY, type index$1_EntryPath as EntryPath, index$1_FILE_PATTERN as FILE_PATTERN, type index$1_FindWindowsOptions as FindWindowsOptions, index$1_GIT_UNAVAILABLE_COMMIT as GIT_UNAVAILABLE_COMMIT, index$1_GIT_UNAVAILABLE_HISTORY as GIT_UNAVAILABLE_HISTORY, type index$1_GitClient as GitClient, type index$1_HeldManifest as HeldManifest, type index$1_History as History, type index$1_InlineStatement as InlineStatement, type index$1_LineSpec as LineSpec, type index$1_LoadSidecarOptions as LoadSidecarOptions, type index$1_LoadedCiteConfig as LoadedCiteConfig, index$1_MARKER_JSON as MARKER_JSON, index$1_MAX_MARKERS_PER_PAGE as MAX_MARKERS_PER_PAGE, index$1_MAX_RANGE_LINES as MAX_RANGE_LINES, index$1_MOVE_BUDGET_BYTES as MOVE_BUDGET_BYTES, index$1_MOVE_WINDOW_LINES as MOVE_WINDOW_LINES, type index$1_ManifestChange as ManifestChange, index$1_ManifestSet as ManifestSet, type index$1_ManifestWrite as ManifestWrite, type index$1_MintOptions as MintOptions, type index$1_MissingReason as MissingReason, type index$1_OriginKind as OriginKind, type index$1_PageCitation as PageCitation, type index$1_PageCitationReport as PageCitationReport, type index$1_PageCitations as PageCitations, type index$1_PageLines as PageLines, type index$1_PageSidecar as PageSidecar, type index$1_PrettyOptions as PrettyOptions, index$1_RULE_ID_PREFIX as RULE_ID_PREFIX, type index$1_ReadPageOptions as ReadPageOptions, type index$1_ReadSourceResult as ReadSourceResult, type index$1_ReencryptCitationsResult as ReencryptCitationsResult, type index$1_ReencryptEntriesResult as ReencryptEntriesResult, type index$1_ReencryptOptions as ReencryptOptions, type index$1_ReencryptedCitation as ReencryptedCitation, index$1_SRC_PATTERN as SRC_PATTERN, type index$1_ShownFile as ShownFile, type index$1_SourceEnd as SourceEnd, type index$1_SourceIndex as SourceIndex, type index$1_SourceRange as SourceRange, type index$1_SourceStatus as SourceStatus, type index$1_StatementForm as StatementForm, type index$1_UpdateOptions as UpdateOptions, type index$1_UpdatePage as UpdatePage, type index$1_UpdateRewrite as UpdateRewrite, type index$1_UpdateRun as UpdateRun, index$1_anchoredLines as anchoredLines, index$1_appendFrontmatterCitation as appendFrontmatterCitation, index$1_blockMatches as blockMatches, index$1_bodyLineOf as bodyLineOf, index$1_buildSourceIndex as buildSourceIndex, index$1_checkCitations as checkCitations, index$1_claimEnd as claimEnd, index$1_claimLine as claimLine, index$1_claimMessageFor as claimMessageFor, index$1_classifyCitation as classifyCitation, index$1_detectEol as detectEol, index$1_duplicateJoinRefusal as duplicateJoinRefusal, index$1_entryObject as entryObject, index$1_errorSite as errorSite, index$1_fenceSpanAt as fenceSpanAt, index$1_fencedBlockAfter as fencedBlockAfter, index$1_fencedBlockAt as fencedBlockAt, index$1_fencedBlocks as fencedBlocks, index$1_findWindows as findWindows, index$1_findingsFor as findingsFor, index$1_formatSrc as formatSrc, index$1_formatStatement as formatStatement, index$1_gitClient as gitClient, index$1_hashLines as hashLines, index$1_hashRange as hashRange, index$1_historyOf as historyOf, index$1_insertStatementBefore as insertStatementBefore, index$1_insideFence as insideFence, index$1_isCiteRule as isCiteRule, index$1_isKeyedPin as isKeyedPin, index$1_itemLine as itemLine, index$1_lineAt as lineAt, index$1_lineSpec as lineSpec, index$1_loadCitationSidecars as loadCitationSidecars, index$1_loadCiteConfig as loadCiteConfig, index$1_markerUnit as markerUnit, index$1_messageFor as messageFor, index$1_mintCitation as mintCitation, index$1_noGit as noGit, index$1_normalizeText as normalizeText, index$1_normalizeWhitespace as normalizeWhitespace, index$1_offsetOfLine as offsetOfLine, index$1_orphanRefusal as orphanRefusal, index$1_ownedMessage as ownedMessage, index$1_paragraphAfter as paragraphAfter, index$1_parseCiteConfig as parseCiteConfig, index$1_parseLines as parseLines, index$1_parseSrc as parseSrc, index$1_parseStatements as parseStatements, index$1_pickExtractor as pickExtractor, index$1_pinOfLines as pinOfLines, index$1_rangeLines as rangeLines, index$1_readCiteConfigFile as readCiteConfigFile, index$1_readPage as readPage, index$1_readSource as readSource, index$1_reencryptCitationEntries as reencryptCitationEntries, index$1_reencryptCitations as reencryptCitations, index$1_renderCheckGithub as renderCheckGithub, index$1_renderCheckJson as renderCheckJson, index$1_renderCheckPretty as renderCheckPretty, index$1_renderUpdateJson as renderUpdateJson, index$1_renderUpdatePretty as renderUpdatePretty, index$1_resolveCiteRun as resolveCiteRun, index$1_resolveSeverity as resolveSeverity, index$1_rewriteLine as rewriteLine, index$1_ruleId as ruleId, index$1_runAdd as runAdd, index$1_runCheck as runCheck, index$1_runUpdate as runUpdate, index$1_shortCommit as shortCommit, index$1_shortPin as shortPin, index$1_shortSrc as shortSrc, index$1_sidecarsFor as sidecarsFor, index$1_sliceLines as sliceLines, index$1_sourceRange as sourceRange, index$1_spellLines as spellLines, index$1_spellSource as spellSource, index$1_splice as splice, index$1_spliceEntryField as spliceEntryField, index$1_splitLines as splitLines, index$1_statementForms as statementForms, index$1_toBodyLines as toBodyLines, index$1_toFileLines as toFileLines, index$1_toValidationResult as toValidationResult, index$1_twoManifestsRefusal as twoManifestsRefusal, index$1_unifiedDiff as unifiedDiff, index$1_unitAt as unitAt, index$1_urlManifestRefusal as urlManifestRefusal, index$1_validateEntry as validateEntry };
+}
+
+/**
+ * The key domain's option and result types (proposal 0045). `key` manages a
+ * family resource, the encryption key, rather than documents of its own: `set`
+ * writes it, and `rotate` re-encrypts every value the family's tools wrote
+ * under it before writing a new one.
+ */
+
+interface KeySetOptions {
+    /** `[value]`: the key to write. Omitted: 64 random hex characters (256 bits). */
+    value?: string;
+    /**
+     * `-c, --config <path>`, relative to `cwd`: the config file to write, which
+     * must exist. Omitted: the nearest `manni.config.yaml` whatever it carries,
+     * else a new one at the git root (else `cwd`).
+     */
+    configPath?: string;
+    /** `--dry-run`: name the target and write nothing. */
+    dryRun?: boolean;
+    cwd?: string;
+    /** Read for `MANNI_ENCRYPTION_KEY`. Defaults to `process.env`; tests pass their own. */
+    env?: NodeJS.ProcessEnv;
+    /** A stderr diagnostic (the git warning); the CLI adds the `manni: ` prefix. */
+    onNotice?: (message: string) => void;
+}
+/** What `set` wrote, or would have. Never the key. */
+interface KeySetResult {
+    /** Absolute path of the config file. */
+    path: string;
+    /** The file as the user would name it, for the report. */
+    source: string;
+    /** Whether the write creates the file. */
+    created: boolean;
+    /** Whether the key was generated rather than given. */
+    generated: boolean;
+    dryRun: boolean;
+}
+interface KeyRotateOptions {
+    /** `[paths...]`: files, directories or globs. Empty: every collection. Any makes the run narrowed. */
+    inputs: string[];
+    /** `--collection <name>`, repeatable. Empty or absent: every collection. Any makes the run narrowed. */
+    collection?: string[];
+    /**
+     * `--to <value>`: the new key. Omitted on a whole run with a key from the
+     * config: 64 random hex characters. Required for a narrowed run and for a
+     * key from `MANNI_ENCRYPTION_KEY`.
+     */
+    to?: string;
+    /** `--ext <list>`, already split: extensions for directory walks. */
+    exts?: string[];
+    /** `--exclude <glob>`, repeatable; added to the selected collections' `exclude:` on a collection run. */
+    exclude?: string[];
+    /** `--as <format>`: force an extractor for every input. */
+    as?: string;
+    /** `-c, --config <path>`: the config the current key is read from and the new one written to. */
+    configPath?: string;
+    /** `--allow-empty`: zero matched files is success. */
+    allowEmpty?: boolean;
+    /** `--no-gitignore` (false). Absent: `.gitignore` is respected. */
+    respectGitignore?: boolean;
+    /** `--root <dir>`, cwd-relative: where cited sources resolve from. Else `cite.root`, else the git root, else `cwd`. */
+    root?: string;
+    /** `--dry-run`: re-encrypt in memory, write nothing. */
+    dryRun?: boolean;
+    cwd?: string;
+    /** Read for `MANNI_ENCRYPTION_KEY`. Defaults to `process.env`; tests pass their own. */
+    env?: NodeJS.ProcessEnv;
+    /** Stderr diagnostics; the CLI adds the `manni: ` prefix. */
+    onNotice?: (message: string) => void;
+    /**
+     * The git client sources and history are read through. Defaults to one
+     * over the root, used whenever git is on PATH and the root is inside a
+     * work tree; a test hands in a fake.
+     */
+    gitClient?: GitClient;
+    /**
+     * How a page or a manifest is written. Defaults to an atomic write; tests
+     * inject a failure.
+     */
+    writePage?: (path: string, content: string) => Promise<void>;
+}
+/** A metadata value re-encrypted: its JSON pointer, and the ciphertext before and after. */
+interface RotatedMetadata {
+    kind: "metadata";
+    pointer: string;
+    from: string;
+    to: string;
+}
+/** A citation re-encrypted: where it sits, and its `src` (line suffix kept) before and after. */
+interface RotatedCitation {
+    kind: "citation";
+    id?: string;
+    /** Index in `citations` for a frontmatter entry. */
+    index?: number;
+    line?: number;
+    from: string;
+    to: string;
+}
+type RotatedValue = RotatedMetadata | RotatedCitation;
+interface SkippedMetadata {
+    kind: "metadata";
+    pointer: string;
+    message: string;
+}
+interface SkippedCitation {
+    kind: "citation";
+    id?: string;
+    index?: number;
+    line?: number;
+    message: string;
+}
+/** A value that could not be re-encrypted, and why. A message never names a path or a value. */
+type SkippedValue = SkippedMetadata | SkippedCitation;
+/** One page with something encrypted on it. */
+interface RotatePage {
+    file: string;
+    rewritten: RotatedValue[];
+    skipped: SkippedValue[];
+    /** Whether this run wrote the page. */
+    written: boolean;
+}
+/**
+ * A value re-encrypted in an external-metadata manifest (proposals 0037 and
+ * 0041): which document entry supplied it, and where it sits in that entry.
+ */
+interface RotatedManifestValue {
+    /** The document entry, exactly as the manifest spells it. */
+    entry: string;
+    /** JSON pointer into the entry's owned keys: `/owner`, `/contacts/0/email`. */
+    pointer: string;
+    from: string;
+    to: string;
+}
+/** A manifest value that could not be re-encrypted, and why. */
+interface SkippedManifestValue {
+    entry: string;
+    pointer: string;
+    message: string;
+}
+/**
+ * One local external-metadata manifest with something encrypted in it. A URL
+ * manifest is read-only (0038) and is never planned, so it never appears.
+ */
+interface RotateManifest {
+    /** The manifest as the run reports it, relative to the run's base. */
+    file: string;
+    /** The collection whose `externalMetadata:` declared it. */
+    collection: string;
+    rewritten: RotatedManifestValue[];
+    skipped: SkippedManifestValue[];
+    /** Whether this run wrote the manifest. */
+    written: boolean;
+}
+/**
+ * How a run ended, which decides its last line:
+ *
+ * - `written`: a whole run wrote the pages, then the new key to the config.
+ * - `finished`: a whole run finished a rotation an interruption left behind.
+ * - `narrowed`: paths or `--collection`; pages written, key not.
+ * - `env`: the key comes from `MANNI_ENCRYPTION_KEY`; pages written, key not.
+ * - `skipped`: a value could not be re-encrypted; nothing written (exit 1).
+ * - `dry-run`: nothing written.
+ */
+type RotateOutcome = "written" | "finished" | "narrowed" | "env" | "skipped" | "dry-run";
+interface KeyRotateResult {
+    /** Pages that had something to re-encrypt or skip, in the order they were read. */
+    pages: RotatePage[];
+    /**
+     * Local external-metadata manifests that had something to re-encrypt or
+     * skip, in the order the selected collections declare them.
+     */
+    manifests: RotateManifest[];
+    /** Values re-encrypted, in memory under `--dry-run` and a skip. */
+    reencrypted: number;
+    skipped: number;
+    /** Whether the config now holds the new key because of this run. */
+    keyWritten: boolean;
+    outcome: RotateOutcome;
+    /** The config file the key comes from, as the user would name it; absent for an environment key. */
+    configSource?: string;
+    /** A citation baseline exists and this run wrote pages, so its pins are stale. */
+    baselineStale: boolean;
+    /** `0` everything re-encrypted, `1` something skipped. Operational errors throw. */
+    exitCode: 0 | 1;
+}
+
+/** An operational or usage error in the key domain: exit 2. */
+declare class KeyError extends ToolError {
+    constructor(message: string);
+}
+
+declare function runKeySet(opts: KeySetOptions): Promise<KeySetResult>;
+
+declare function runKeyRotate(opts: KeyRotateOptions): Promise<KeyRotateResult>;
+
+/** Which kind of value a token holds. Bound as associated data. */
+type EncryptionContext = "meta" | "cite-src";
+/** Whether `value` is shaped like a token. Says nothing about which key. */
+declare function isEncryptedValue(value: unknown): value is string;
+/**
+ * Encrypt any JSON value. Throws for a value that is not JSON (`undefined`, a
+ * function) and for a key that is not key-shaped: both are programming
+ * errors, since keys arrive through `resolveEncryptionKey`.
+ */
+declare function encryptValue(value: unknown, key: string, context: EncryptionContext): string;
+/**
+ * Decrypt a token. `{ ok: false }` for anything that is not a canonical token
+ * under this key and context; never throws.
+ */
+declare function decryptValue(token: string, key: string, context: EncryptionContext): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+
+/**
+ * The key domain's programmatic API, exported from the package as the `key`
+ * namespace: `import { key } from "@hawkeyexl/manni"`. The command cores, and
+ * the family's encryption primitives a caller needs beside them.
+ */
+
+type index_EncryptionContext = EncryptionContext;
+type index_KeyError = KeyError;
+declare const index_KeyError: typeof KeyError;
+type index_KeyRotateOptions = KeyRotateOptions;
+type index_KeyRotateResult = KeyRotateResult;
+type index_KeySetOptions = KeySetOptions;
+type index_KeySetResult = KeySetResult;
+type index_KeySource = KeySource;
+type index_ResolvedKey = ResolvedKey;
+type index_RotateManifest = RotateManifest;
+type index_RotateOutcome = RotateOutcome;
+type index_RotatePage = RotatePage;
+type index_RotatedCitation = RotatedCitation;
+type index_RotatedManifestValue = RotatedManifestValue;
+type index_RotatedMetadata = RotatedMetadata;
+type index_RotatedValue = RotatedValue;
+type index_SkippedCitation = SkippedCitation;
+type index_SkippedManifestValue = SkippedManifestValue;
+type index_SkippedMetadata = SkippedMetadata;
+type index_SkippedValue = SkippedValue;
+declare const index_decryptValue: typeof decryptValue;
+declare const index_encryptValue: typeof encryptValue;
+declare const index_isEncryptedValue: typeof isEncryptedValue;
+declare const index_resolveEncryptionKey: typeof resolveEncryptionKey;
+declare const index_runKeyRotate: typeof runKeyRotate;
+declare const index_runKeySet: typeof runKeySet;
+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 };