TypeScript API reference

manni meta publishes a programmatic entry point alongside the CLI. A Node.js or TypeScript tool can call the same cores the CLI is built on. There is no process to spawn and no stdout to parse. Consume manni meta results shows the worked example; this page is the exhaustive list.

import { runValidate } from "@hawkeyexl/manni";

ESM, Node 24+

manni meta is an ES module targeting Node.js 24 or newer. Import it from ESM (or a .mts / .ts file compiled to ESM); there is no CommonJS require entry. Type-only exports are marked as such in the tables below and erase at compile time.

Command cores

One function per subcommand, each taking an options object and resolving to a structured result. The cores contain no CLI or IO plumbing: they do not read process.argv, do not write to stdout, and do not call process.exit. Turning a result into text is the reporters’ job, and mapping it to an exit code is the caller’s.

Export	Purpose
runValidate	Run the validation pipeline over the resolved inputs. Backs manni meta validate.
ValidateOptions (type)	Input to runValidate. Mirrors the CLI: inputs, cliSchemas, exts, exclude, as, configPath, stdinContent, baseline and offline settings. An optional env is the environment MANNI_ENCRYPTION_KEY is read from, which defaults to process.env.
ValidateRun (type)	What runValidate resolves to: results, summary, and the frame describing where the run stood.
runGet	Read named metadata fields from each input. Backs manni meta get. Always returns every file it saw, since --quiet filtering lives in the reporter.
GetOptions (type)	Input to runGet: the same input model plus the fields to read.
GetFileResult (type)	One runGet result. The file, whether metadata was present, the resolved values, and an optional error when the metadata block could not be read at all. When provenance was requested, provenance carries bodyLine, the file line body line 1 sits on, and current, whether the record agrees with git as validate judges it. current is absent when nothing was derived.
runQuery	Run one SQL statement over an in-memory table built from every input’s metadata. Backs manni meta query. Returns every row. The --check verdict is the CLI’s exit code, not the result’s.
QueryOptions (type)	Input to runQuery. The same input model plus the sql to run. Optional named-parameter params, with values encoded like stored cells: booleans as 1/0, arrays and objects as JSON text. Optional schemas naming the set a DDL statement evolves (the CLI’s -s). A run that produces no schema-evolving effects then refuses, export-only runs included. An optional db export path makes sql optional. An optional confirm is how a write to a column marked x-manni-encrypt asks for an encryption key when there is none; absent, that write refuses. The same confirm puts the relocation offer when a write sets a key its schema prefers in external metadata and no manifest owns it. Absent, the value is written to the page with one warning. An optional onRelocated receives relocate’s RelocateResult after an accepted offer moved values. An optional env is the environment MANNI_ENCRYPTION_KEY is read from.
QueryRun (type)	What runQuery resolves to. Result columns (present even for zero rows), rows, and a mutating statement’s changes. The frame describing where the run stood, which is what SARIF and JUnit rendering need. When db was written, its path and size.
QueryChange (type)	One thing a mutating statement changed, as a union of kinds. A cell set (key/from/to), a key deletion (deleted), or a key rename (renamedFrom). A stripped block (cleared), a created file (created), or a file move (renamed). A schema edit (schema) carries the op, the type/format/enum/required intent, 0028’s fields included, and any forkedFrom. A DDL side effect on the governing config (config), which is either a fork’s schemas: repoint or a refreshed integrity: pin, as one change object each. Every kind records whether it was written or previewed. A change that lands in an external-metadata manifest rather than the page carries manifest, the manifest’s path.
runFill	Propose and write missing metadata with an inference provider. Backs manni meta fill.
FillOptions (type)	Input to runFill: provider, model, confidence threshold, cost ceiling, concurrency, and whether to write. An optional confirm is how a run asks for an encryption key. It is used when a field marked x-manni-encrypt is to be written and there is none. Absent, the run refuses before its first model request. When a field its schema prefers in external metadata has no manifest, the same confirm puts the relocation offer before the first model request. Absent, the value is written to the page with one warning. An optional onRelocated receives relocate’s RelocateResult after an accepted offer moved values. An optional env is the environment MANNI_ENCRYPTION_KEY is read from.
FillRun (type)	What runFill resolves to: per-file results plus the run summary.
FillFileResult (type)	One file’s fill outcome: the fields considered and whether the document was rewritten. metaProvenance reports the meta-provenance entry. A written entry is {written: true, entry}, plus destination when a manifest owns the entry and it was written there. A skipped one is {written: false, skipReason} with schema-mismatch, manifest-owned (a URL manifest owns it; plus the manifest URL) or unwritable. It is absent when no field was written.
FillSummary (type)	Aggregate fill counts, including cost and the required fields left unfilled.
FilledField (type)	One proposed field: JSON Pointer, required, confidence, reasoning, the value, and whether it was written. encrypted is set when the value was written encrypted, and value then reads (encrypted). destination names the manifest the value was written into, when a manifest of the page’s collections owns the key.
SkipReason (type)	Why a proposal was not written: low-confidence, schema-mismatch, or no-proposal.
runDerive	Stamp the managed stewardship fields from git history, CODEOWNERS, GitHub and GitLab. Backs manni meta derive. Writes a stale or unset field unless dryRun or check; leaves current and unknown alone. Throws DocmetaError for stdin, a field or source it does not know, nothing to derive, and a consulted source that cannot answer.
DeriveOptions (type)	Input to runDerive: the same input model minus stdin, plus fields and sources (config derive: otherwise), dryRun, check, cache, a now clock, and a reviews client to inject. generatedBy is --generated-by, read from MANNI_GENERATED_BY in env when absent, and an input may carry a <path>:L1-L2 range. An optional confirm asks for an encryption key when a marked field is to be stamped and there is none. It also puts the relocation offer when a field its schema prefers in external metadata has no manifest. Neither is asked under dryRun or check. An optional onRelocated receives relocate’s RelocateResult after an accepted offer. onNotice receives the run’s diagnostics, the location warnings among them.
DeriveRun (type)	What runDerive resolves to: per-file results, the summary, whether it was a dryRun or a check, the sources consulted with each one’s status, and the frame SARIF needs.
DeriveFileResult (type)	One file’s outcome: its fields as DerivedFields, whether it changed, an error when it could not be derived or written, and under check its findings.
DeriveSummary (type)	The aggregate counts. They cover files, changed files, fields written, how many fields were stale, unset, or unknown, and errors. ranges, present when provenance is among the fields, counts the provenance ranges written.
runRelocate	Put each value where its schema’s x-manni-location mark and the config’s manifests say it belongs, in both directions. Backs manni meta relocate. Creates the collection, manifest file and config entry a value needs, and writes nothing under dryRun. Throws DocmetaError for stdin, noConfig, no inputs, a fields name nothing marks or owns, and a manifest path that exists undeclared.
RelocateOptions (type)	Input to runRelocate: the same input model minus stdin, plus fields, collections, cliSchemas and dryRun. noConfig is accepted so that it can be refused.
RelocateResult (type)	What runRelocate resolves to. It carries dryRun, the config changes, and each manifests entry with the keys it gained and lost. Then per-page files with the values moved and stayed (each with its reason), and the summary. A run with a stayed value is exit 1 on the CLI.
getSchemasInfo	The built-in schema registry and the supported input formats, as data. Backs manni meta schemas.
runVendorSchema	Fetch a remote schema, write it into the repository, and record its integrity pin. Backs manni meta schemas vendor.
VendorOptions (type)	Input to runVendorSchema: the URL, the destination directory, and whether to update the config.
VendorResult (type)	What was written. The file path, the integrity digest, and the config edit that was made.
vendorFileName	The file name schemas vendor derives from a schema URL.
DEFAULT_VENDOR_DIR	The default destination directory for vendored schemas (./schema).

Operational failures throw DocmetaError

The cores throw a DocmetaError for operational problems: no inputs and no config, an unknown --as format, an unreadable config, an unresolvable schema. That is the same condition the CLI maps to exit 2. A validation failure is not thrown. It comes back as a result with ok: false.

Validation engine and results

The shapes below are the ones --format json serializes, so a programmatic caller and a subprocess caller are reading the same data model.

Export	Purpose
Validator	The Ajv-backed engine. Validate already-extracted metadata against a schema set without going through the file pipeline. validate takes the data, the schema refs, a lineFor callback, an optional colFor, and an optional fifth locate callback. locate says where a merged value lives when it is not in the document (an external-metadata manifest’s file and line). markedPointers takes the data and the schema refs, and resolves to the instance pointers that carry x-manni-encrypt: true, wherever validation evaluates the mark. locationPreferences takes the same two, and resolves to a map from each top-level key to its LocationPreference. Only keys present in the data are marked, a later ref wins, and one schema saying both values for a key throws a DocmetaError.
LOCATION_KEYWORD	The schema keyword x-manni-location, whose value is page or external.
FieldLocation (type)	"page" | "external".
LocationPreference (type)	One key’s preferred location, and the schema ref whose mark decided it.
ValidationResult (type)	One file’s outcome: the file label, ok, the schemas applied, the errors, and how many findings a baseline suppressed.
FieldError (type)	One violation. The JSON Pointer, the message, the failing keyword, and the schema that produced it. An optional file names the file line and col refer to when it is not the result’s own. It is set only for a value an external-metadata manifest supplied. An optional severity, on the family scale, is set by producers whose findings are advisory.
isErrorSeverity	Whether a FieldError counts against ok: true for error and for an absent severity, false for warning and notice. The one reading of the severity invariant; derive ok through it.
RunSummary (type)	Aggregate counts for a run. Files, passed, failed, errors, plus optional warnings, gitignoreSkipped and baseline blocks.
BaselineSummary (type)	How a baseline shaped the run. Its path, whether it was written, and the recorded, suppressed, and stale counts.
FingerprintContext (type)	The frame a ValidateRun returns: the working directory, the directory canonical paths are measured from, and the directory result labels are relative to. Pass it back into render for SARIF.

Collections

A collection is a named set of documents, declared once at the top level of manni.config.yaml and read by every tool in the family. It carries the globs that select its files, the globs that exclude them, and the external metadata joined to them. See Collections in the configuration reference for the keys, and collections as inputs for what the CLI does with them.

These live in the shared layer rather than the metadata tool’s, because the document set is not one tool’s business. A caller that wants the same file sets manni meta sees parses them once and asks isMember or memberOf per file.

Export	Purpose
CollectionConfig (type)	One declared collection. It carries its name, the paths that select its files, and the exclude globs that remove them. It also carries the externalMetadata manifests joined to its members and an optional url naming where it is published. exclude and externalMetadata are always present, defaulted to [] by the parser, so a consumer never checks for undefined.
ExternalMetadataConfig (type)	One external-metadata manifest on a collection. It carries the manifest file, the top-level keys it owns, an optional tokenEnv, and an optional join. file is a path relative to the config’s directory or an https:// URL, and tokenEnv names the environment variable holding that URL’s bearer token. join is path or the top-level field the manifest’s keys are values of. The parser has already asserted the keys are non-empty, unique, disjoint across the collection’s manifests, and never $schema. It has also asserted that tokenEnv appears only on a URL, and that join is neither $schema nor an owned key.
parseCollections	Parse a family file’s top-level collections: value into CollectionConfig[], in declaration order. Errors are built with a toError callback you supply, so each tool reports a bad family file in its own error class.
selectCollections	The collections a run covers. That is every one when names is undefined, else the named ones in declaration order however they were named on the command line. Repeats collapse. An unknown name throws, because a typo that silently narrowed a run to nothing would read as a clean pass.
isMember	Whether one file belongs to one collection. relPath is posix and already relative to the config file’s directory, so this is arithmetic on a string. There is no stat, nothing that can fail, and no per-file cost. A path that climbed out of the config directory, and stdin, are members of nothing.
memberOf	The names of every collection a file belongs to, given the collections, the config directory, the run’s base, and the file’s label. This is what mergeExternalMetadata takes, computed once per file.
externalMetadataUrlProblem	Why a URL may not name a manifest, or null when it may. It refuses userinfo in the URL, plain http:// off a loopback host, and any other scheme. The config parser applies it to every URL file, which is why it lives here rather than beside the fetcher.

External metadata

The manifest that keeps frontmatter values outside the document, joined to a collection’s members at run time. See external metadata in the configuration reference for the rules, and keep metadata outside the document for the walkthrough. A caller building its own pipeline loads the index once per run and merges per document. It validates the merged object with locate, and runs the orphan checks when the run is the config corpus.

The vocabulary changed in this release. What was a sidecar is now external metadata, and the file it lives in is a manifest. Every Sidecar* and sidecar* export was renamed accordingly, with no aliases. The rename table below maps each old name to its new one.

Export	Purpose
loadExternalMetadata	Load every manifest of every collection the run covers into one ExternalMetadataIndex. Takes the CollectionConfig[] rather than the config, because the declaration is the collections’. Resolves to null when none of them declares a manifest, which is every setup that existed before the feature. Throws DocmetaError for a manifest that is missing, unparseable, or misshapen, and for an entry setting a key the manifest does not own.
LoadExternalMetadataOptions (type)	Input to loadExternalMetadata. configDir is the directory file and every manifest key resolve from. base is the directory the run’s file labels are relative to, so manifests are reported the same way. offline refuses a URL file rather than fetching it. timeoutMs bounds the fetch, and env is the environment tokenEnv is read from, for tests.
fetchExternalMetadata	Fetch one remote manifest by URL, sending the bearer token tokenEnv names to that origin only. Resolves to the manifest text. Throws DocmetaError naming the URL and the status, never the token, and under offline before any request. loadExternalMetadata calls it for a URL file.
ExternalMetadataFetchOptions (type)	Input to fetchExternalMetadata, made of tokenEnv, timeoutMs, maxBytes, offline, and env, the environment tokenEnv is read from, which defaults to process.env.
EXTERNAL_METADATA_FETCH_TIMEOUT_MS, EXTERNAL_METADATA_FETCH_MAX_BYTES	The fetch’s defaults, 10 000 ms and 5 MB, matching the schema fetch.
ExternalMetadataIndex (type)	Every manifest of a run. owners maps each owned key to every collection that owns it, with the manifest that does. It is a list rather than one entry, because two collections may each legitimately supply the same key. byPath maps an absolute document path to its supplied values. byField maps a join field to its values and each value to the supplied values. entries lists every manifest entry for the orphan checks.
ExternalMetadataEntry (type)	One manifest entry. collection is the collection whose manifest declared it. join is path or the field it is keyed by, and abs is the absolute document path of a path entry, absent for a field entry. It also carries the key as spelled, the manifest’s reported path, and the entry’s line when known.
ExternalMetadataValue (type)	One supplied value, with the collection whose manifest supplied it, the manifest’s reported path, and the key’s line when known. For a list or mapping value, lines maps each node inside it to its manifest line, keyed by the pointer relative to the value.
externalMetadataJoin	The join an ExternalMetadataConfig asks for: its join, or PATH_JOIN when absent.
PATH_JOIN	The join that names documents by path, path, and the default.
mergeExternalMetadata	Merge the index’s values for one document into its ExtractedMetadata. Takes the collections the document belongs to, a memberOf result, and consults only their manifests. A file that is a member of nothing therefore merges nothing. Returns the merged object, the collisions (owned keys the document itself carried, which the caller files as findings), the joins, and a locate callback. Throws DocmetaError when two of the document’s collections own one key. There is nothing about the document to fix, and a precedence rule would be a tiebreak. Stdin never merges by path. An optional sixth argument, { encryptionKey }, returns the run’s key. A join field the page holds encrypted is decrypted with it before matching. With no key, the call throws DocmetaError.
MergedMetadata (type)	What mergeExternalMetadata returns: extracted, collisions, joins, and locate. locate answers with the line of the deepest manifest node a pointer reaches, so /citations/2 is the third item’s line.
ExternalMetadataCollision (type)	One key a document carries that a manifest owns, with the owning manifest and its collection. MergedMetadata.collisions is a list of these.
ExternalMetadataJoin (type)	One field-joined entry a document matched: the field, the value, the manifest file, and its collection. MergedMetadata.joins is a list of these, one per manifest at most. When the page holds the field encrypted, value is the decrypted value it matched on and pageValue is the ciphertext, which is what a finding names.
SourceLocation (type)	What locate answers with: a file, and optionally line and col.
externalMetadataPointer	The /<key> instance path for a collision or duplicate finding, RFC 6901 escaped.
orphanEntries	The path entries naming no loaded document, given the run’s file labels. Empty when the index is null.
orphanJoins	The field entries no loaded document matched, given a map of join field to the values the run’s documents carried. The caller collects that map from each document’s joins, so this runs after the per-file loop. Empty when the index is null.
orphanError	The DocmetaError an orphan check raises, naming the first orphan and counting the rest.
EXTERNAL_OWNED_SCHEMA	The schema ref a collision finding carries: external:owned.
EXTERNAL_DUPLICATE_SCHEMA	The schema ref a duplicate-join finding carries: external:duplicate.
EXTERNAL_KEYWORD	The keyword every external-metadata finding carries: external. Joined, they are the rule ids external:owned/external and external:duplicate/external.

The index is loaded once, membership is per file

loadExternalMetadata takes the collections the run covers; mergeExternalMetadata takes the collections one document belongs to. They are different lists, and passing the run’s list per document would merge a manifest into a file that is not in its collection.

The sidecar rename

Nothing about what a manifest may contain, how it joins, or what a violation reports has changed. The names have. There are no aliases, so an upgrade is a find-and-replace:

Was	Is
SidecarConfig	ExternalMetadataConfig, now on a collection
loadSidecars / LoadSidecarsOptions	loadExternalMetadata / LoadExternalMetadataOptions, taking the collections rather than the config
mergeSidecars	mergeExternalMetadata, taking the collections the file belongs to
SidecarIndex / SidecarEntry / SidecarValue	ExternalMetadataIndex / ExternalMetadataEntry / ExternalMetadataValue
SidecarCollision / SidecarJoin	ExternalMetadataCollision / ExternalMetadataJoin
sidecarJoin / sidecarPointer	externalMetadataJoin / externalMetadataPointer
SIDECAR_OWNED_SCHEMA / SIDECAR_DUPLICATE_SCHEMA / SIDECAR_KEYWORD	EXTERNAL_OWNED_SCHEMA / EXTERNAL_DUPLICATE_SCHEMA / EXTERNAL_KEYWORD
fetchSidecar / SidecarFetchOptions / sidecarUrlProblem	fetchExternalMetadata / ExternalMetadataFetchOptions / externalMetadataUrlProblem
SIDECAR_FETCH_TIMEOUT_MS / SIDECAR_FETCH_MAX_BYTES	EXTERNAL_METADATA_FETCH_TIMEOUT_MS / EXTERNAL_METADATA_FETCH_MAX_BYTES

orphanEntries, orphanJoins, orphanError, PATH_JOIN, MergedMetadata and SourceLocation keep their names and their signatures. The two finding identities are renamed with the vocabulary, which costs a baseline a regeneration.

Encrypted values

A property whose schema marks it x-manni-encrypt is held encrypted on the page, under the family’s encryption key. reencryptMetadata is the metadata tool’s half of changing that key.

Export	Purpose
reencryptMetadata	Re-encrypt every encrypted value in one page’s metadata from fromKey to toKey. Takes the page’s file, its content and an optional format (an extractor name; the file’s extension otherwise). Values are found by their ciphertext at any depth, not through schema marks, and the citations subtree is left to the citation tool. A value under fromKey is rewritten. One already under toKey is done, so an interrupted rotation can run again. One under neither is skipped with does not decrypt under the current key. A nested value rewrites its top-level key through the format’s writer, and everything else is kept. Pure: the caller reads and writes the file.
ReencryptMetadataResult (type)	What reencryptMetadata returns: the new content (the input itself when nothing changed), the rewritten values, and the skipped ones, each a pointer and a message.
ReencryptedValue (type)	One rewritten value. It carries the JSON pointer, and the ciphertext from and to.

Derived metadata

Values computed from git history, CODEOWNERS, GitHub and GitLab rather than written by hand. A derived value never merges into what the schema sees. manni meta derive stamps the managed fields into the document, and validate reports a managed field whose asserted value differs from the derived one. The exports below are the shared vocabulary and the two pure steps every source feeds.

Export	Purpose
DERIVABLE_FIELDS	The seven built-in fields: created, last-updated, authors, owner, reviewed-by, last-reviewed, provenance.
BuiltinDerivableField (type)	The union of those names.
DerivableField (type)	A managed field name, which is one of the built-ins or a key with an entry in derive.commands. The config parser guarantees one or the other, so it is string to the type system.
isBuiltinField	Type guard for a user-supplied field name: whether it is one of the seven built-ins. It answers false for a key with a derive.commands entry, which is derivable but not built in; ask isBuiltinField(f) || Object.hasOwn(commands, f) for the wider question.
DERIVE_SOURCES	The sources derive.sources may name: git, codeowners, github, gitlab, command. Absent in config means all five, of which only the github or gitlab the origin remote matches is consulted.
DeriveSource (type)	The union of those names.
DeriveCommand (type)	One derive.commands entry as the derive context carries it: the run argv, the program first, and the timeoutMs to wait for it.
isDeriveSource	Type guard for a user-supplied source name.
DerivedValue (type)	One fact a source produced. It carries the value, its source, and the evidence a finding quotes, such as a commit, a CODEOWNERS line, or a pull request.
DerivedRecord (type)	Everything derived for one document, as the file and a fields map. A null field means a source was consulted and had no fact; an absent one means no source answered.
SourceStatus (type)	Whether a source can answer at all, with a reason naming the fix when it cannot.
ReviewClient (type)	The GitHub or GitLab half of a derive run: detect the hosting kind and project, status (binary on PATH and authenticated), and mergedChangeFor a commit. Reached through gh or glab; inject one through DeriveContext.reviews or DeriveOptions.reviews to keep the network out.
RemoteIdentity (type)	What detect answers from the origin remote: the kind (github or gitlab), the host, and the project path there.
GitHubClient	A ReviewClient that shells out to gh: the pull request for a commit, then its APPROVED reviews.
GitLabClient	A ReviewClient that shells out to glab: the merge request for a commit, then its approvals.
createReviewClient	Build the client for a repository root. It reads the origin remote, picks GitHubClient or GitLabClient, and wraps it in the review cache.
SpawnOptions (type)	How a client reaches its binary, with the bin (gh or glab on PATH by default), any prefixArgs, the cwd, and a timeoutMs. Tests point bin at a fake script.
run	Run one child process to completion. Stdout is collected, stderr drained and kept, and the child killed after timeoutMs. The review clients and the command source both spawn through it. Rejects with BinMissing when nothing on PATH has the binary’s name.
Run (type)	What run resolves to: the exit code (null when a signal ended the child), stdout, stderr, and whether it timedOut.
BinMissing	The error run rejects with when the binary could not be started at all.
parseOriginUrl	The host and project an origin URL names, for the scp, https and ssh spellings git writes. A local path or a bare host is null.
identityFromOrigin	The RemoteIdentity for a parsed origin, with the kind decided by the host.
cachedClient	A ReviewClient whose mergedChangeFor reads through a ReviewCache. Only a merged answer is stored, and a client with no identity goes straight through.
ReviewSourceInput (type)	One document as the review source sees it, with its label and the newest body-changing commit’s sha. The sha is null for an uncommitted document.
ReviewFacts (type)	What the review source answers for one document: reviewed-by and last-reviewed, each a DerivedValue or null.
ReviewSourceResult (type)	What deriveFromReviews resolves to: the source’s status and its records by label.
deriveFromReviews	The github or gitlab source. One lookup per distinct commit, however many documents share it. An unavailable client is reported in status and never called.
ReviewCache	The on-disk cache of merged answers under REVIEW_CACHE_DIR, keyed by host, project and commit. A disabled cache misses every time and stores nothing.
REVIEW_CACHE_DIR	Where the cache lives, relative to the project root: .manni/meta/review-cache.
REVIEW_CACHE_VERSION	The entry format this version reads. An entry with another version is a miss.
MergedChange (type)	The merged pull or merge request that carried a commit: its id, when it was mergedAt, and its approvals.
Approval (type)	One APPROVED review, the latest per reviewer: the login and when it was submittedAt.
DeriveInput (type)	One document as the sources see it, with its label, absPath, content, and extracted metadata.
DeriveContext (type)	What a derive run holds constant: cwd, base, configDir, the sources and fields in play, an optional codeowners path, the optional commands table, whether to cache, a now clock, and an optional reviews client.
DerivedStatus (type)	How an asserted value stands against the derived one: current, stale, unset, or unknown.
DerivedField (type)	One compared field. It carries the field, the asserted value when the document carries one, the derived value or null, its source and evidence, the status, and whether derive has written it. For provenance it adds ranges, one verdict per range in file lines, each with lines, generated-by, integrity, status (current, moved, changed, stale or unset), evidence, written, and from on a moved or stale range. It adds manifest when a manifest holds the record. Any other field a manifest of the page’s collections owns adds destination, the manifest it is written into. It also adds destinationLine, the key’s line there after the write.
compareDerived	Compare what a document asserts with what a source derived. Pure. Lists compare as sets, so a reordered authors: is current, not stale. A missing or null derived value is unknown.
staleFindings	The findings validate files for a document’s managed fields. Each stale or unset field gets one FieldError, on the line the asserted key sits on. When an optional locate says a manifest supplied the value, it is on the manifest’s line instead (with file). The message names both values and the evidence.
DERIVED_STALE_SCHEMA	The schema ref a derived finding carries: derived:stale.
DERIVED_KEYWORD	The keyword every derived finding carries: derived. Joined, they are the rule id derived:stale/derived.
deriveMetadata	The orchestrator. It resolves every requested field for every input from the sources the run consults. A source is consulted only when a requested field can come from it, and the github or gitlab source rides on git. Precedence is per field, with the first non-null answer winning.
DeriveResult (type)	What deriveMetadata resolves to: a DerivedRecord per input keyed by label, and one SourceStatus per source consulted.
FIELD_SOURCES	Which sources can state each derivable field, in precedence order: github or gitlab ahead of git for reviewed-by and last-reviewed, one source for every other field.
sourcesFor	Which sources can state one field, in precedence order. A built-in gets its FIELD_SOURCES row. A key of the commands table gets command. Any other name gets nothing. A built-in never reaches the command arm.
consultedSources	The sources a run consults, meaning those requested that some requested field can come from, in the requested order. Takes the commands table so command counts when a requested field has an entry.
deriveFromCommands	The command source. Each entry in the table runs once, or once per document when its argv carries {path}, in the given cwd and never through a shell. The first program that is missing, times out, or exits non-zero makes the source unavailable, with nothing further spawned.
CommandSourceOptions (type)	Input to deriveFromCommands: the cwd to run in (the config directory, else the run’s) and an optional spawn seam that points every command at another binary.
CommandSourceResult (type)	What deriveFromCommands resolves to: the source’s status and, by label, each document’s fields as DerivedValue or null.
PATH_PLACEHOLDER	The argv token, {path}, that a per-file command carries where the document’s label goes.
isPerFile	Whether a DeriveCommand runs once per document, which is whether any of its argv carries {path}.
argvFor	A command’s argv with every {path} replaced by a document’s label.
valueOf	What a command’s stdout means. Blank output is null. An object, a list or a quoted string is parsed as JSON. Anything else is the trimmed text, so a bare 1.10 keeps its trailing zero.
assertSourcesAvailable	Throw the exit-2 DocmetaError for the first consulted source that could not answer, with the caller’s hint appended after a semicolon. Availability is reported, not thrown, so each command chooses its own way out.
RESOLVED_VIEW	The name of the third table a query can read, resolved: the effective value per field, over docs and the derived rows.
resolvedColumns	Every column resolved carries, in order: _path, the docs data columns, any derivable field docs lacks, then _origin and _sources.
createResolvedView	Create that view on a database that already holds docs and the derived rows. A field the document carries resolves to the asserted value, including an explicit null; any other resolves to the derived one. _origin names the winner per field and omits a field neither side has. Read-only, because it is a view.
mentionsResolved	Whether a statement names resolved where a table goes, so the view is built only for a query that reads it. The twin of mentionsDerived.

Schema resolution

The precedence chain that decides which schemas apply to a given file. See Schema resolution for the rules these implement.

Export	Purpose
resolveSchemaSet	Resolve the schema set for one file from CLI refs, the document’s $schema, config overrides, and the defaults.
DEFAULT_SCHEMAS	The built-in default schema set, used when nothing else selects one.
collectSchemaPins	Gather the integrity pins a config declares, keyed by schema reference.
schemaEntryRef	Narrow a config schemas: entry, either a bare string or an object, to its reference string.
rebaseConfigSchemaRefs	Rewrite a config’s relative file refs so they resolve against the config’s own directory rather than the process working directory.

Schema loading and integrity

Export	Purpose
listBuiltins	Enumerate the schemas manni meta ships, with their ids and titles.
classifyRef	Decide whether a reference is a builtin id, a file path, or a url.
loadSchema	Resolve any reference to a parsed JSON Schema object, going through the cache and integrity check.
fetchSchemaBytes	The lower-level fetch: the raw bytes plus their provenance, for callers that need the exact payload (integrity pinning does).
FetchedSchema (type)	What fetchSchemaBytes returns: the bytes, the resolved URL, and whether the cache served them.
schemaLoadOptions	Build a LoadSchemaOptions from run-level settings (trust, pins, offline, cache), so every call site derives them the same way.
LoadSchemaOptions (type)	Loader settings. Pins, trust policy, cache behavior, and offline mode.
SchemaPin (type)	An integrity pin. The reference and the digest it must hash to.
integrityOf	The sha256-… digest of a byte payload, in the form a pin records.
isIntegrity	Whether a string is a well-formed integrity digest.
INTEGRITY_SHAPE	The human-readable description of that form, for error messages.

Schema cache

The on-disk cache for schemas fetched over http(s), shared across runs.

Export	Purpose
SchemaCache	Read and write cached remote schemas. Freshness is measured on file mtime, not an embedded timestamp.
ReadOptions (type)	Per-read cache behavior, notably ignoreTtl, which is what --offline needs when no re-fetch is available.
SchemaCacheEntry (type)	One cache record. Version, source URL, fetch time, and the parsed schema.
schemaCacheDir	The cache directory for a given project root.
SCHEMA_CACHE_DIR	The cache path relative to the root (.manni/meta/schema-cache).
SCHEMA_CACHE_VERSION	The entry-format version; a mismatch invalidates an entry.
DEFAULT_TTL_HOURS	How long a cached schema is served before re-fetching, when config says nothing.

Configuration

Loading, parsing, and merging manni.config.yaml. See the configuration reference for what each key means. The top-level collections: key is family-wide rather than the metadata tool’s, and its exports are under Collections.

Export	Purpose
loadConfig	Discover (or take an explicit path to) a config file and parse it. Resolves to null when discovery finds none.
parseConfig	Parse config text that you already have, with a source label for error messages.
LoadedConfig (type)	A parsed config plus where it came from. It carries the file’s path, its dir, and the source label every config message spells it as. It also carries the family-file section it was read from under, and every collections the family file declares. encryptionKey is the file’s top-level key when it has one, and configFile is the file as family discovery found it.
DocmetaConfig (type)	The meta: section itself: schemas, overrides, checks, elements, derive, fill, baseline, schemaTrust, schemaCache, and the rest. It no longer carries paths, exclude or sidecars; the document set and its external metadata are collections, which every tool reads.
resolveRunConfig	Merge config with the run’s inputs and flags into the settings a core actually uses. This is the precedence chain, in one place.
RunConfigOptions (type)	Input to resolveRunConfig: cwd, configPath, noConfig, the positional inputs, the collections names --collection gave (empty or absent means every declared one), and a load callback.
RunConfig (type)	The merged result. It carries the rebased config, the effective inputs, and the base those are relative to. The inputs are the positional ones, or the selected collections’ paths concatenated in declaration order. It names the configDir/configPath/configSection that governed the run and the collections the run covers. It lists every declaredCollections the config declares, each of which is a SQL view whether the run selected it or not. And it carries fromCollections, the corpus invariant every scoped check reads. configFile is the governing file, which the run’s encryption key resolves from.
ConfigNotice (type)	Told to the caller once when a run turns out to be governed by a config: its path and directory.
SchemaEntry (type)	A schemas: entry, either a bare reference string or a SchemaRefEntry.
SchemaRefEntry (type)	The object form. A reference plus its integrity pin.
SchemaTrustConfig (type)	How far a document is trusted to choose its own contract: documentRefs and the optional host allowlist.
DocumentRefTrust (type)	The three trust levels: any, local, none.
FillConfig (type)	Config defaults for fill: provider, model, confidence threshold, cost ceiling, concurrency.
SchemaCacheConfig (type)	Config for the remote-schema cache, currently ttlHours.
CheckConfig (type)	One named corpus check. Its name (the durable half of its findings’ identity) and the SQL query.
DeriveConfig (type)	The derived channel. It is made of the managed fields, the optional sources to consult, and an optional codeowners path relative to the config’s directory. The optional commands table and machines globs complete it. The parser has already asserted the fields are non-empty, unique, and each one of DERIVABLE_FIELDS or a key of commands. loadConfig has also asserted that no field and no commands key is a key an external-metadata manifest owns on any collection. provenance is the one field a manifest may own.
DeriveCommandConfig (type)	One derive.commands entry as the config spells it, with the run argv, the program first, and an optional timeout in seconds. The parser has already asserted run is a non-empty list of non-empty strings and timeout a positive whole number. It has also refused a key that is a built-in field or $schema, and loadConfig refuses one a manifest owns.

Reporters

Pure formatting. A reporter turns a core’s result into text and never writes it anywhere. --quiet lives here rather than in the cores, so a programmatic caller can never mistake a filtered run for an empty one.

Export	Purpose
render	Format a validation run in any report format. SARIF also wants the run’s frame.
renderSarif	The SARIF reporter on its own, for callers that only want that one.
renderJunit	The JUnit XML reporter on its own.
REPORT_FORMATS	The formats validate accepts: pretty, json, github, sarif, junit.
ReportFormat (type)	The union of those names.
isReportFormat	Type guard for a user-supplied format string.
ReportOptions (type)	Options passed to render: color, and everything SarifOptions and JunitOptions carry.
SarifOptions (type)	SARIF-specific options, notably the frame used to build repository-relative URIs.
JunitOptions (type)	JUnit-specific options: the frame, and the classname each testcase carries. That is manni.validate by default; query --check findings ship as manni.query.
QUERY_FORMATS	The formats query accepts: pretty, json, csv, plus the findings formats github, sarif, junit (legal only with --check).
QueryFormat (type)	The union of those names.
isQueryFormat	Type guard for a user-supplied query format string.
COMMON_FORMATS	The two formats every command supports: pretty and json.
CommonFormat (type)	The union of those two names.
isCommonFormat	Type guard for the narrower set, used by get.
renderGet	The reporter behind manni meta get.
GetReportOptions (type)	color and quiet for renderGet.
renderQuery	The reporter behind manni meta query: the aligned table, the row count, and the --check verdict line.
renderQueryCsv	The -f csv fork of the query reporter, giving result rows as CSV. Header always, LF endings, RFC 4180 quoting, and SQL NULL as an empty field.
QueryReportOptions (type)	color and check for renderQuery.
stringifyValue	How a single field value is spelled: (unset) when missing, JSON for anything that is not a string.
renderFill	The reporter behind manni meta fill, across the fill formats.
renderFillGithub	GitHub Actions annotations for the work fill could not do, as one ::error per unfilled required property.
FILL_FORMATS	The formats fill accepts: pretty, json, github.
FillReportFormat (type)	The union of those names.
isFillFormat	Type guard for a user-supplied fill format string.
FillReportOptions (type)	color and quiet for renderFill.
renderDerive	The reporter behind manni meta derive. An apply or dry run renders its own pretty and json; a --check run renders every format through render, so a stale stamp is a finding under derived:stale/derived. The findings formats throw DocmetaError without --check.
DERIVE_FORMATS	The formats derive accepts: pretty, json, github, sarif, junit. The last three need --check.
DeriveReportFormat (type)	The union of those names.
isDeriveFormat	Type guard for a user-supplied derive format string.
DeriveReportOptions (type)	The same options as render: color, quiet, the frame, and onNotice.

Extractors

The per-format metadata layer. Everything after extraction operates on the generic ExtractedMetadata shape, which is why a new input format never touches validation, resolution, or reporting. See supported formats.

Export	Purpose
extractorForExtension	The implemented extractor for a file extension (including the dot), or undefined.
supportedExtensions	Every extension an implemented extractor handles, which is the default set for directory and glob walks.
MetadataExtractor (type)	The extractor interface. Name, extensions, and the read and write entry points.
ExtractedMetadata (type)	The format-independent result of extraction: whether metadata was present, the parsed data, and any parse error.
ExtractOptions (type)	Per-run inputs to extraction beyond the document itself, currently the elements: paths, which lift metadata held in elements rather than attributes. Pass the same value to apply, or a writer re-reads without them and cannot find the key it just wrote.

Frontmatter

The fenced-block path shared by Markdown, MDX, and the fenced form of AsciiDoc and reStructuredText.

Export	Purpose
extractFrontmatter	Read a leading fenced block into ExtractedMetadata, detecting the flavor from the fence.
locateFrontmatter	Locate the block without parsing it. Its fence style and the character offsets it spans.
frontmatterInnerText	The block’s inner text for a located block, LF-normalized with the final terminator removed.
FrontmatterLocation (type)	What locateFrontmatter returns: the flavor and the offsets.
FrontmatterFlavor (type)	The three interchangeable fence flavors: yaml, toml, json.
applyFrontmatter	Merge a patch into a document’s leading block and return the new content. Pure, so the input string is returned unchanged for a no-op patch.
MetadataPatch (type)	Top-level keys to set. Keys whose value is undefined are ignored.
ApplyOptions (type)	Options for applyFrontmatter, currently the flavor used when creating a block from scratch.

Writing files

Export	Purpose
writeFileAtomic	Replace a file atomically, falling back to a direct write with a warning when the rename keeps failing on a locked target. Accepts a Uint8Array so vendored bytes are written byte-for-byte.

Errors

Export	Purpose
DocmetaError	The operational/usage failure the CLI maps to exit code 2. Catch it to distinguish “manni meta could not run” from “the documents did not pass”.

Sibling tools

Each other tool in the family is one namespace export. Its API cannot collide with the flat surface above, and a consumer can see which tool a name belongs to. Each namespace is documented on its own tool’s pages.

Export	Purpose
cite	The citation tool’s programmatic API. It carries the command cores runCheck, runAdd and runUpdate; the per-page check checkCitations, the minter mintCitation and the re-encrypter reencryptCitations; and the primitives hashRange, parseSrc and parseStatements. toValidationResult turns a page report into the ValidationResult above, so the reporters and the baseline work unchanged. CiteError is its exit-2 failure. import { cite } from "@hawkeyexl/manni". See the cite reference.
key	The family encryption key’s API. It carries the command cores runKeySet and runKeyRotate with their option and result types, and the family’s encryption primitives: encryptValue, decryptValue, isEncryptedValue, and resolveEncryptionKey with its KeySource. KeyError is its exit-2 failure. import { key } from "@hawkeyexl/manni". See the key reference.