@hawkeyexl/manni 2.12.1 → 3.0.0

package/dist/index.d.ts

@@ -311,7 +311,12 @@ interface FingerprintContext {
 /** One external-metadata manifest (proposals 0037, 0038, 0039) joined to a collection. */
 interface ExternalMetadataConfig {
     file: string;
-    keys: string[];
+    /**
+     * The top-level keys the manifest owns. Absent (proposal 0068), it owns
+     * what each page's schemas mark `x-manni-location: external`, as `ownsKey`
+     * decides.
+     */
+    keys?: string[];
     tokenEnv?: string;
     join?: string;
 }
@@ -411,6 +416,158 @@ interface ConfigFile {
     encryptionKeyPrevious?: string;
 }
 
+interface BuiltinInfo {
+    id: string;
+    title: string;
+    description: string;
+}
+/**
+ * A schema `meta.register` loaded from a local file (proposal 0070), named
+ * everywhere by its own `$id`, as a built-in is named by its id.
+ */
+interface RegisteredSchema {
+    /** The schema's `$id`: `vendor:name:version`, or an `https://` URL. */
+    id: string;
+    /** The file, relative to the config file's directory, with forward slashes. */
+    file: string;
+    /** The file's absolute path. */
+    path: string;
+    /** The parsed schema: the object every lookup of `id` returns. */
+    schema: Record<string, unknown>;
+}
+/** The registered schemas of one config, keyed by `$id`. */
+type RegisteredSchemas = ReadonlyMap<string, RegisteredSchema>;
+declare function listBuiltins(): BuiltinInfo[];
+type RefKind = "builtin" | "file" | "url";
+declare function classifyRef(ref: string): {
+    kind: RefKind;
+    ref: string;
+};
+/**
+ * What a config recorded about one reference beyond the reference itself.
+ *
+ * Kept out of the ref string deliberately: the ref appears in every report,
+ * every baseline fingerprint, and `Validator`'s compile cache key, so it has to
+ * stay exactly the string the user wrote.
+ */
+interface SchemaPin {
+    /** Where the reference was vendored from — a URL, or a local path. */
+    source?: string;
+    /** `sha256-<64 hex>` the file's bytes must hash to. */
+    integrity?: string;
+}
+interface LoadSchemaOptions {
+    /**
+     * Directory a **relative local-file** ref is resolved against.
+     *
+     * Omitted means `process.cwd()`, which is what the CLI wants and what this
+     * always did. A library caller passing `cwd` to a command core needs the
+     * ref measured from *that* directory instead: `rebaseConfigSchemaRefs`
+     * deliberately leaves refs untouched when the config already sits in the
+     * run's `cwd`, so `./schema/house.json` arrives here exactly as written and
+     * was then read against the wrong directory.
+     *
+     * Resolved at read time rather than by rewriting the ref, and that choice is
+     * load-bearing: the ref string is what reports name, what `Validator` keys
+     * its compile cache on, and what every baseline fingerprint is taken over.
+     * Rewriting it to an absolute path would silently move every recorded
+     * baseline. `canonicalSchemaRef` in `baseline.ts` already measures a relative
+     * ref from the run's `cwd`, so this makes loading agree with fingerprinting
+     * rather than introducing a new convention.
+     */
+    fileBase?: string;
+    /** Abort a remote fetch after this many ms (default 10_000). */
+    timeoutMs?: number;
+    /** Reject a remote schema whose body exceeds this many bytes (default 5 MB). */
+    maxBytes?: number;
+    /**
+     * Directory for the cross-run schema cache. Omitted means **no disk cache**:
+     * the registry never guesses a project root, so a library caller gets the
+     * in-process behavior until it opts in. The command cores pass
+     * `schemaCacheDir(configDir ?? cwd)`.
+     */
+    cacheDir?: string;
+    /** Hours a cached entry stays fresh; `0` disables the cache (default 24). */
+    ttlHours?: number;
+    /**
+     * Never touch the network. A URL ref resolves from the disk cache — ignoring
+     * the TTL, since there is no re-fetch to fall back on — and an uncached one
+     * fails naming the URL. Built-ins and local files are unaffected.
+     *
+     * This is a *durability* control, not a trust boundary, and it never was:
+     * whether a document may name a URL at all is decided upstream by
+     * `schemaTrust` in `resolveSchemaSet`, which is the last place that still
+     * knows a ref came from a document rather than from an operator (proposal
+     * 0015). `offline` used to block that case by accident and was the only thing
+     * standing there; it is now free to mean only what it says.
+     */
+    offline?: boolean;
+    /**
+     * Provenance and integrity pins, keyed on the reference exactly as it is
+     * passed to `loadSchema`. Built by `collectSchemaPins` from the **rebased**
+     * config, so both sides spell a local path the same way; a config with no
+     * mapping-form `schemas:` entries produces an empty map and none of this
+     * runs.
+     */
+    pins?: ReadonlyMap<string, SchemaPin>;
+    /**
+     * The schemas `meta.register` loaded (proposal 0070), keyed by `$id`. A ref
+     * naming one resolves to its file's schema before anything else is
+     * consulted, so a registered `https://` id is never fetched.
+     */
+    registered?: RegisteredSchemas;
+}
+/** A fetched schema, with the bytes it arrived as. */
+interface FetchedSchema {
+    /** Exactly what the server sent, undecoded. */
+    bytes: Buffer;
+    /** The same payload, parsed and guarded. */
+    schema: Record<string, unknown>;
+}
+/**
+ * Fetch, size-cap, parse, and guard a remote schema. At most two requests.
+ *
+ * Exported for `schemas vendor`, which needs the raw bytes to write and to
+ * hash. Sharing this path rather than fetching separately is what keeps
+ * vendoring subject to the same size cap, retry policy, and payload guard as
+ * validation — a vendored error envelope would otherwise be committed to the
+ * repository and pass every document from then on.
+ *
+ * Deliberately **not** routed through the disk cache or `offline`: vendoring is
+ * an explicit request to download, and the cache stores a parsed schema rather
+ * than the bytes a pin has to be taken over.
+ */
+declare function fetchSchemaBytes(ref: string, options?: LoadSchemaOptions): Promise<FetchedSchema>;
+/**
+ * Settle the remote-schema options for one run, from the config and the flag.
+ *
+ * Lives here rather than in a command core because all three commands need the
+ * same answer, and because "where does the cache live" is a property of schema
+ * loading, not of `validate`. `root` is the config's directory when a config
+ * governs the run, so a developer running from `docs/` shares the cache with
+ * CI running from the repo root instead of quietly keeping a second one.
+ */
+declare function schemaLoadOptions(args: {
+    root: string;
+    /**
+     * Where a relative local-file schema ref is measured from — the run's `cwd`,
+     * not `root`. The two differ when a config was discovered in an ancestor, and
+     * a `--schema ./x.json` typed on the command line belongs to the directory
+     * the user was standing in, not to the config's.
+     */
+    fileBase?: string;
+    /** Config `schemaCache.ttlHours`. */
+    ttlHours?: number;
+    /** `--offline`, else config `offline:`. */
+    offline?: boolean;
+    /** From `collectSchemaPins(config)`; omitted when the config pins nothing. */
+    pins?: ReadonlyMap<string, SchemaPin>;
+    /** The config's registered schemas (`config.registered`), when it has any. */
+    registered?: RegisteredSchemas;
+}): LoadSchemaOptions;
+/** Load and return the JSON Schema object for a reference. */
+declare function loadSchema(ref: string, options?: LoadSchemaOptions): Promise<Record<string, unknown>>;
+
 /** Lines as an entry writes them: an integer for one line, `"L1-L2"` for several. */
 type LineSpec = number | string;
 /** Page lines as an editor numbers them, 1-based and inclusive. */
@@ -557,6 +714,16 @@ interface RangeResult {
 /** The seven built-in fields, in the order messages list them. */
 declare const DERIVABLE_FIELDS: readonly ["created", "last-updated", "authors", "owner", "reviewed-by", "last-reviewed", "provenance"];
 type BuiltinDerivableField = (typeof DERIVABLE_FIELDS)[number];
+/**
+ * The merge-safe fields (proposal 0069), in the order messages list them:
+ * the ones whose stamp, written in a pull request, still reads current after
+ * a squash merge. `derive.fields` absent manages these, and on each page only
+ * the ones its schemas claim.
+ */
+declare const MERGE_SAFE_FIELDS: readonly ["owner", "created", "last-updated", "provenance"];
+/** The dated fields the git source reads from the stamp a fact commit carries. */
+declare const STAMPED_DATE_FIELDS: readonly ["created", "last-updated"];
+type StampedDateField = (typeof STAMPED_DATE_FIELDS)[number];
 /**
  * A managed field name: one of the seven built-ins, or a key with an entry in
  * `derive.commands`. The config parser guarantees one or the other.
@@ -644,7 +811,14 @@ interface DeriveInput {
      * (proposal 0046), so evidence rule 2 reads the manifest's blob at each
      * commit rather than the page's frontmatter. Absent: the page's own.
      */
-    provenanceManifest?: ProvenanceManifestRef;
+    provenanceManifest?: ManifestRef;
+    /**
+     * Where the page's `created` and `last-updated` live when a manifest owns
+     * them (proposal 0069, rule 1), so the git source reads the stamp a fact
+     * commit carries from the manifest's blob at that commit as well as from
+     * the page's. A field with no entry: the page's own.
+     */
+    stampManifests?: Partial<Readonly<Record<StampedDateField, ManifestRef>>>;
     /**
      * `manni meta derive <path>:L1-L2 --generated-by <name>`: the file lines
      * each target names go to `generatedBy`, committed or not, unless evidence
@@ -657,8 +831,8 @@ interface DeriveInput {
         generatedBy: string;
     };
 }
-/** A manifest that holds one page's `provenance`, as the git source reads it at a commit. */
-interface ProvenanceManifestRef {
+/** A manifest that holds one page's managed field, as the git source reads it at a commit. */
+interface ManifestRef {
     /** The manifest file, absolute. */
     absPath: string;
     /** The page's key there: its path relative to the config directory, or its join value. */
@@ -801,6 +975,17 @@ interface SchemaOverride {
      * trap.
      */
     elements?: string[];
+    /**
+     * Put the default set first, then this entry's `schemas` (proposal 0070).
+     * Absent or `false` means the entry's `schemas` replace the set, as an
+     * override always did. An override never inherits the top-level `schemas`.
+     */
+    defaults?: boolean;
+    /**
+     * Stack the strict version of each default or registered schema in the
+     * entry's set right after its base, where one exists.
+     */
+    strict?: boolean;
 }
 /**
  * A `schemas:` entry in its long form: a reference plus where it came from and
@@ -886,8 +1071,12 @@ interface DeriveConfig {
      * The managed fields. Each is one of `DERIVABLE_FIELDS` or a key of
      * `commands`, never `$schema`, and never a key a manifest owns: a value
      * with two authorities has none.
+     *
+     * Absent means the merge-safe fields (`MERGE_SAFE_FIELDS`, proposal 0069),
+     * each managed only on a page whose schemas claim it as a top-level
+     * property. `[]` manages nothing. Read it through `managedFields`.
      */
-    fields: DerivableField[];
+    fields?: DerivableField[];
     /** Which sources to consult; absent means all of `DERIVE_SOURCES`. */
     sources?: DeriveSource[];
     /**
@@ -909,6 +1098,12 @@ interface DeriveConfig {
      * through `machinesOf`.
      */
     machines?: string[];
+    /**
+     * The collections whose members derive manages (proposal 0070). A file in
+     * none of them is neither stamped nor compared. Absent means every
+     * validated file. Read it through `deriveCovers`.
+     */
+    collections?: string[];
 }
 /** Defaults for the `fill` command; every key is overridable by a CLI flag. */
 interface FillConfig {
@@ -932,10 +1127,33 @@ interface SchemaCacheConfig {
 }
 interface DocmetaConfig {
     /**
-     * The default schema set. Each entry is either a reference string or a
-     * `{ ref, source?, integrity? }` mapping — see `SchemaEntry`.
+     * The schemas every file no override matches is judged by. Each entry is
+     * either a reference string or a `{ ref, source?, integrity? }` mapping —
+     * see `SchemaEntry`. They join the default set unless `defaults` is false.
      */
     schemas?: SchemaEntry[];
+    /**
+     * Put the default set first, then `schemas`, for the files no override
+     * matches (proposal 0070). Absent means `true`; `false` makes `schemas`
+     * replace the default set.
+     */
+    defaults?: boolean;
+    /**
+     * For those files, stack the strict version of each default or registered
+     * schema in the set right after its base, where one exists. Absent means
+     * `false`.
+     */
+    strict?: boolean;
+    /**
+     * JSON Schema files, or directories of them (`*.json`, recursively),
+     * relative to the config file. Each is loaded once and named by its `$id`.
+     */
+    register?: string[];
+    /**
+     * The schemas `register` names, loaded by `loadConfig` and keyed by `$id`.
+     * Not a key of the file: it is what the file's `register` produced.
+     */
+    registered?: RegisteredSchemas;
     overrides?: SchemaOverride[];
     /**
      * Named corpus checks `validate` runs after the per-file schemas, when the
@@ -1592,7 +1810,21 @@ declare function loadExternalMetadata(collections: readonly CollectionConfig[],
  */
 declare function mergeExternalMetadata(label: string, extracted: ExtractedMetadata, index: ExternalMetadataIndex | null, memberOf: readonly string[], base: string, options?: {
     encryptionKey?: () => string | undefined;
+    /**
+     * The top-level keys the document's schemas mark `x-manni-location:
+     * external` (proposal 0068), which is what a manifest with no `keys`
+     * owns. Absent, such a manifest owns nothing for this document.
+     */
+    marked?: ReadonlySet<string>;
 }): MergedMetadata;
+/**
+ * The top-level keys one document's schemas mark `x-manni-location:
+ * external`, read over `probe`: the document's metadata with everything its
+ * keyless manifests supply for it (proposal 0068). `undefined` when the
+ * document's schemas cannot be resolved or loaded, so the caller reports that
+ * the way it always has and a keyless manifest owns nothing for it.
+ */
+type PageMarks = (label: string, probe: Readonly<Record<string, unknown>>, memberOf: readonly string[]) => Promise<ReadonlySet<string> | undefined>;
 /** The `/key` pointer for an external-metadata finding, RFC 6901 escaped. */
 declare function externalMetadataPointer(key: string): string;
 /**
@@ -1622,134 +1854,6 @@ declare function orphanJoins(index: ExternalMetadataIndex | null, matched: Reado
 /** The operational error an orphan check raises, naming the first entry. */
 declare function orphanError(orphans: readonly ExternalMetadataEntry[]): DocmetaError;
 
-interface BuiltinInfo {
-    id: string;
-    title: string;
-    description: string;
-}
-declare function listBuiltins(): BuiltinInfo[];
-type RefKind = "builtin" | "file" | "url";
-declare function classifyRef(ref: string): {
-    kind: RefKind;
-    ref: string;
-};
-/**
- * What a config recorded about one reference beyond the reference itself.
- *
- * Kept out of the ref string deliberately: the ref appears in every report,
- * every baseline fingerprint, and `Validator`'s compile cache key, so it has to
- * stay exactly the string the user wrote.
- */
-interface SchemaPin {
-    /** Where the reference was vendored from — a URL, or a local path. */
-    source?: string;
-    /** `sha256-<64 hex>` the file's bytes must hash to. */
-    integrity?: string;
-}
-interface LoadSchemaOptions {
-    /**
-     * Directory a **relative local-file** ref is resolved against.
-     *
-     * Omitted means `process.cwd()`, which is what the CLI wants and what this
-     * always did. A library caller passing `cwd` to a command core needs the
-     * ref measured from *that* directory instead: `rebaseConfigSchemaRefs`
-     * deliberately leaves refs untouched when the config already sits in the
-     * run's `cwd`, so `./schema/house.json` arrives here exactly as written and
-     * was then read against the wrong directory.
-     *
-     * Resolved at read time rather than by rewriting the ref, and that choice is
-     * load-bearing: the ref string is what reports name, what `Validator` keys
-     * its compile cache on, and what every baseline fingerprint is taken over.
-     * Rewriting it to an absolute path would silently move every recorded
-     * baseline. `canonicalSchemaRef` in `baseline.ts` already measures a relative
-     * ref from the run's `cwd`, so this makes loading agree with fingerprinting
-     * rather than introducing a new convention.
-     */
-    fileBase?: string;
-    /** Abort a remote fetch after this many ms (default 10_000). */
-    timeoutMs?: number;
-    /** Reject a remote schema whose body exceeds this many bytes (default 5 MB). */
-    maxBytes?: number;
-    /**
-     * Directory for the cross-run schema cache. Omitted means **no disk cache**:
-     * the registry never guesses a project root, so a library caller gets the
-     * in-process behavior until it opts in. The command cores pass
-     * `schemaCacheDir(configDir ?? cwd)`.
-     */
-    cacheDir?: string;
-    /** Hours a cached entry stays fresh; `0` disables the cache (default 24). */
-    ttlHours?: number;
-    /**
-     * Never touch the network. A URL ref resolves from the disk cache — ignoring
-     * the TTL, since there is no re-fetch to fall back on — and an uncached one
-     * fails naming the URL. Built-ins and local files are unaffected.
-     *
-     * This is a *durability* control, not a trust boundary, and it never was:
-     * whether a document may name a URL at all is decided upstream by
-     * `schemaTrust` in `resolveSchemaSet`, which is the last place that still
-     * knows a ref came from a document rather than from an operator (proposal
-     * 0015). `offline` used to block that case by accident and was the only thing
-     * standing there; it is now free to mean only what it says.
-     */
-    offline?: boolean;
-    /**
-     * Provenance and integrity pins, keyed on the reference exactly as it is
-     * passed to `loadSchema`. Built by `collectSchemaPins` from the **rebased**
-     * config, so both sides spell a local path the same way; a config with no
-     * mapping-form `schemas:` entries produces an empty map and none of this
-     * runs.
-     */
-    pins?: ReadonlyMap<string, SchemaPin>;
-}
-/** A fetched schema, with the bytes it arrived as. */
-interface FetchedSchema {
-    /** Exactly what the server sent, undecoded. */
-    bytes: Buffer;
-    /** The same payload, parsed and guarded. */
-    schema: Record<string, unknown>;
-}
-/**
- * Fetch, size-cap, parse, and guard a remote schema. At most two requests.
- *
- * Exported for `schemas vendor`, which needs the raw bytes to write and to
- * hash. Sharing this path rather than fetching separately is what keeps
- * vendoring subject to the same size cap, retry policy, and payload guard as
- * validation — a vendored error envelope would otherwise be committed to the
- * repository and pass every document from then on.
- *
- * Deliberately **not** routed through the disk cache or `offline`: vendoring is
- * an explicit request to download, and the cache stores a parsed schema rather
- * than the bytes a pin has to be taken over.
- */
-declare function fetchSchemaBytes(ref: string, options?: LoadSchemaOptions): Promise<FetchedSchema>;
-/**
- * Settle the remote-schema options for one run, from the config and the flag.
- *
- * Lives here rather than in a command core because all three commands need the
- * same answer, and because "where does the cache live" is a property of schema
- * loading, not of `validate`. `root` is the config's directory when a config
- * governs the run, so a developer running from `docs/` shares the cache with
- * CI running from the repo root instead of quietly keeping a second one.
- */
-declare function schemaLoadOptions(args: {
-    root: string;
-    /**
-     * Where a relative local-file schema ref is measured from — the run's `cwd`,
-     * not `root`. The two differ when a config was discovered in an ancestor, and
-     * a `--schema ./x.json` typed on the command line belongs to the directory
-     * the user was standing in, not to the config's.
-     */
-    fileBase?: string;
-    /** Config `schemaCache.ttlHours`. */
-    ttlHours?: number;
-    /** `--offline`, else config `offline:`. */
-    offline?: boolean;
-    /** From `collectSchemaPins(config)`; omitted when the config pins nothing. */
-    pins?: ReadonlyMap<string, SchemaPin>;
-}): LoadSchemaOptions;
-/** Load and return the JSON Schema object for a reference. */
-declare function loadSchema(ref: string, options?: LoadSchemaOptions): Promise<Record<string, unknown>>;
-
 /**
  * `x-manni-location` (proposal 0047): where a schema would like a top-level
  * key's value stored, on the page or in external metadata.
@@ -1843,6 +1947,16 @@ declare class Validator {
      * whose evaluated branches say both gives that key no preference.
      */
     locationPreferences(data: Record<string, unknown>, refs: string[]): Promise<Map<string, LocationPreference>>;
+    /**
+     * The top-level property names the schemas in `refs` claim: the keys of
+     * each schema's own `properties`, each once. What a page's schema set
+     * claims decides which merge-safe fields a `derive:` block with no `fields`
+     * manages on it (proposal 0069). A property reached only through `allOf`,
+     * `$ref` or a conditional is not counted, so a schema that should manage a
+     * field names it in its root `properties`. A schema that fails to load or
+     * compile throws, as it would for `validate`.
+     */
+    claimedProperties(refs: readonly 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
@@ -2129,8 +2243,16 @@ interface QueryRun {
 }
 declare function runQuery(opts: QueryOptions): Promise<QueryRun>;
 
+/** One schema `meta.register` loaded: its `$id` and its file. */
+interface RegisteredInfo {
+    id: string;
+    /** Relative to the config file, with forward slashes. */
+    file: string;
+}
 interface SchemasInfo {
     builtins: BuiltinInfo[];
+    /** The governing config's registered schemas (proposal 0070). */
+    registered: RegisteredInfo[];
     formats: {
         name: string;
         extensions: string[];
@@ -2138,7 +2260,7 @@ interface SchemasInfo {
         writable: boolean;
     }[];
 }
-declare function getSchemasInfo(): SchemasInfo;
+declare function getSchemasInfo(registered?: RegisteredSchemas): SchemasInfo;
 /**
  * Where a vendored schema lands by default.
  *
@@ -2381,6 +2503,17 @@ interface FillOptions {
     concurrency?: number;
     /** Include the filled document on each result (used for stdin and tests). */
     includeContent?: boolean;
+    /**
+     * The glossary term labels offered for the fields that name a term. When
+     * given, they are used instead of the registered term label source (see
+     * `src/shared/term-labels.ts`). When absent, that source is used, if any.
+     *
+     * Labels only. The registered source also knows each term's id, which a
+     * term relation (`broader`, `narrower`, `related-terms`, `see`) accepts as
+     * `term check` does. With `termLabels`, no ids are known, so a relation
+     * value must be a label; an id is retried and then skipped.
+     */
+    termLabels?: readonly string[];
     /** Test seam: bypasses `makeProvider`, so no API key is needed. */
     inferenceProvider?: InferenceProvider;
     /**
@@ -2606,11 +2739,15 @@ declare function reencryptMetadata(page: {
 }): 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
- * does not require it, so adding it fails nothing that passed before.
- * Diataxis is deliberately absent: it both requires and constrains `type`, so
- * defaulting it would fail every repo not already on Diataxis.
+ * The default set (proposal 0070): what a file is judged by when nothing
+ * replaces it, and what `schemas:` joins unless `defaults: false`.
+ *
+ * Seven-Action constrains `action`, a key documents don't otherwise carry,
+ * and requires nothing. Diataxis is deliberately absent: it both requires and
+ * constrains `type`, so defaulting it would fail every repo not already on
+ * Diataxis. The manni vocabularies follow; core requires `title` and
+ * `description`, and nothing else in the set requires anything.
+ * Terminology, artifact-evals and every `-strict` overlay stay opt-in.
  */
 declare const DEFAULT_SCHEMAS: readonly string[];
 /**
@@ -3542,7 +3679,7 @@ interface CitationSource {
     /** The git commit hash the pin was taken at: 7 to 64 lowercase hex. */
     "commit-sha"?: string;
 }
-/** One entry of `citations`, as the schema (`manni:citations:1.0.0-proposal.4`) spells it. */
+/** One entry of `citations`, as the schema (`manni:citations:1.0.0`) spells it. */
 interface Citation {
     id?: string;
     claim?: CitationClaim;
@@ -4992,6 +5129,45 @@ declare function shiftedEntries(opts: ShiftOptions): Shifted;
 /** A copy of a manifest entry with its `claim.lines` replaced. */
 declare function withClaimLines(entry: unknown, lines: LineSpec): unknown;
 
+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;
+
 /** The one key cite keeps in a manifest. */
 declare const CITATIONS_KEY = "citations";
 /** A manifest that owns `citations` for one collection. */
@@ -5011,6 +5187,15 @@ interface CitationManifest {
      * created by the first write.
      */
     pattern?: string;
+    /**
+     * The manifest names no `keys` (proposal 0068), so it keeps a page's
+     * citations only when the page's schemas mark `citations` external. The
+     * declaration, for `ownsKey`.
+     */
+    implied?: {
+        collection: CollectionConfig;
+        manifest: ExternalMetadataConfig;
+    };
 }
 /** Where one page's citations are kept, and what the manifest already holds. */
 interface PageSidecar {
@@ -5035,7 +5220,7 @@ interface CitationSidecars {
     configDir: string;
     /** Directory the run's file labels are relative to. */
     base: string;
-    forPage(label: string, content: string, format?: string): PageSidecar;
+    forPage(label: string, content: string, format?: string): Promise<PageSidecar>;
     /**
      * Manifest entries naming a page this run did not load, under meta's own
      * corpus invariant. `covered` names the collections a `--collection` run
@@ -5069,6 +5254,11 @@ interface LoadSidecarOptions {
     key?: string;
     /** The tool's error class; `CiteError` unless a sibling command says otherwise. */
     toError?: (message: string) => Error;
+    /**
+     * What a page's schemas mark external (proposal 0068), asked only for a
+     * page a manifest with no `keys` may keep citations for.
+     */
+    marks?: () => Promise<PageMarks | undefined>;
 }
 /** `collection <name>: citations cannot come from a URL manifest, because cite writes them.` */
 declare function urlManifestRefusal(source: string, collection: string): string;
@@ -5106,45 +5296,6 @@ declare function sidecarsFor(run: CiteRun, over?: {
     pages?: readonly string[];
 }): 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 entry's one key: what an edit rewrites, and what a conflict is about. */
 interface ManifestKey {
     /** The entry, as the manifest spells it. */
@@ -6050,4 +6201,4 @@ declare namespace index {
   export { type index_EncryptionContext as EncryptionContext, index_KeyError as KeyError, type index_KeyRotateOptions as KeyRotateOptions, type index_KeyRotateResult as KeyRotateResult, type index_KeySetOptions as KeySetOptions, type index_KeySetResult as KeySetResult, type index_KeySource as KeySource, type index_ResolvedKey as ResolvedKey, type index_RotateManifest as RotateManifest, type index_RotateOutcome as RotateOutcome, type index_RotatePage as RotatePage, type index_RotatedCitation as RotatedCitation, type index_RotatedManifestValue as RotatedManifestValue, type index_RotatedMetadata as RotatedMetadata, type index_RotatedValue as RotatedValue, type index_SkippedCitation as SkippedCitation, type index_SkippedManifestValue as SkippedManifestValue, type index_SkippedMetadata as SkippedMetadata, type index_SkippedValue as SkippedValue, index_decryptValue as decryptValue, index_encryptValue as encryptValue, index_isEncryptedValue as isEncryptedValue, index_resolveEncryptionKey as resolveEncryptionKey, index_runKeyRotate as runKeyRotate, index_runKeySet as runKeySet };
 }
 
-export { type ApplyOptions, type Approval, type BaselineSummary, BinMissing, type BuiltinDerivableField, COMMON_FORMATS, type CheckConfig, type CollectionConfig, type CommandSourceOptions, type CommandSourceResult, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, DERIVABLE_FIELDS, DERIVED_KEYWORD, DERIVED_STALE_SCHEMA, DERIVE_FORMATS, DERIVE_SOURCES, type DerivableField, type DeriveCommand, type DeriveCommandConfig, type DeriveConfig, type DeriveContext, type DeriveFileResult, type DeriveInput, type DeriveOptions, type DeriveReportFormat, type DeriveReportOptions, type DeriveResult, type DeriveRun, type DeriveSource, type DeriveSummary, type DerivedField, type DerivedRecord, type DerivedStatus, type DerivedValue, type DocmetaConfig, DocmetaError, type DocumentRefTrust, EXTERNAL_DUPLICATE_SCHEMA, EXTERNAL_KEYWORD, EXTERNAL_METADATA_FETCH_MAX_BYTES, EXTERNAL_METADATA_FETCH_TIMEOUT_MS, EXTERNAL_OWNED_SCHEMA, type ExternalMetadataCollision, type ExternalMetadataConfig, type ExternalMetadataEntry, type ExternalMetadataFetchOptions, type ExternalMetadataIndex, type ExternalMetadataJoin, type ExternalMetadataValue, type ExtractOptions, type ExtractedMetadata, FIELD_SOURCES, FILL_FORMATS, type FetchedSchema, type FieldError, type FieldLocation, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, GitHubClient, GitLabClient, INTEGRITY_SHAPE, type JunitOptions, LOCATION_KEYWORD, type LoadExternalMetadataOptions, type LoadSchemaOptions, type LoadedConfig, type LocationPreference, type MergedChange, type MergedMetadata, type MetadataExtractor, type MetadataPatch, PATH_JOIN, PATH_PLACEHOLDER, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, RESOLVED_VIEW, REVIEW_CACHE_DIR, REVIEW_CACHE_VERSION, type ReadOptions, type ReencryptMetadataResult, type ReencryptedValue, type RelocateOptions, type RelocateResult, type RemoteIdentity, type ReportFormat, type ReportOptions, ReviewCache, type ReviewClient, type ReviewFacts, type ReviewSourceInput, type ReviewSourceResult, type Run, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SkipReason, type SourceLocation, type SourceStatus$1 as SourceStatus, type SpawnOptions, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, argvFor, assertSourcesAvailable, cachedClient, index$1 as cite, classifyRef, collectSchemaPins, compareDerived, consultedSources, createResolvedView, createReviewClient, deriveFromCommands, deriveFromReviews, deriveMetadata, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, identityFromOrigin, integrityOf, isBuiltinField, isCommonFormat, isDeriveFormat, isDeriveSource, isErrorSeverity, isFillFormat, isIntegrity, isMember, isPerFile, isQueryFormat, isReportFormat, index as key, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mentionsResolved, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, parseOriginUrl, rebaseConfigSchemaRefs, reencryptMetadata, render, renderDerive, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, resolvedColumns, run, runDerive, runFill, runGet, runQuery, runRelocate, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, selectCollections, sourcesFor, staleFindings, stringifyValue, supportedExtensions, valueOf, vendorFileName, writeFileAtomic };
+export { type ApplyOptions, type Approval, type BaselineSummary, BinMissing, type BuiltinDerivableField, COMMON_FORMATS, type CheckConfig, type CollectionConfig, type CommandSourceOptions, type CommandSourceResult, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, DERIVABLE_FIELDS, DERIVED_KEYWORD, DERIVED_STALE_SCHEMA, DERIVE_FORMATS, DERIVE_SOURCES, type DerivableField, type DeriveCommand, type DeriveCommandConfig, type DeriveConfig, type DeriveContext, type DeriveFileResult, type DeriveInput, type DeriveOptions, type DeriveReportFormat, type DeriveReportOptions, type DeriveResult, type DeriveRun, type DeriveSource, type DeriveSummary, type DerivedField, type DerivedRecord, type DerivedStatus, type DerivedValue, type DocmetaConfig, DocmetaError, type DocumentRefTrust, EXTERNAL_DUPLICATE_SCHEMA, EXTERNAL_KEYWORD, EXTERNAL_METADATA_FETCH_MAX_BYTES, EXTERNAL_METADATA_FETCH_TIMEOUT_MS, EXTERNAL_OWNED_SCHEMA, type ExternalMetadataCollision, type ExternalMetadataConfig, type ExternalMetadataEntry, type ExternalMetadataFetchOptions, type ExternalMetadataIndex, type ExternalMetadataJoin, type ExternalMetadataValue, type ExtractOptions, type ExtractedMetadata, FIELD_SOURCES, FILL_FORMATS, type FetchedSchema, type FieldError, type FieldLocation, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, GitHubClient, GitLabClient, INTEGRITY_SHAPE, type JunitOptions, LOCATION_KEYWORD, type LoadExternalMetadataOptions, type LoadSchemaOptions, type LoadedConfig, type LocationPreference, MERGE_SAFE_FIELDS, 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 RegisteredSchema, type RegisteredSchemas, type RelocateOptions, type RelocateResult, type RemoteIdentity, type ReportFormat, type ReportOptions, ReviewCache, type ReviewClient, type ReviewFacts, type ReviewSourceInput, type ReviewSourceResult, type Run, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SkipReason, type SourceLocation, type SourceStatus$1 as SourceStatus, type SpawnOptions, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, argvFor, assertSourcesAvailable, cachedClient, index$1 as cite, classifyRef, collectSchemaPins, compareDerived, consultedSources, createResolvedView, createReviewClient, deriveFromCommands, deriveFromReviews, deriveMetadata, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, identityFromOrigin, integrityOf, isBuiltinField, isCommonFormat, isDeriveFormat, isDeriveSource, isErrorSeverity, isFillFormat, isIntegrity, isMember, isPerFile, isQueryFormat, isReportFormat, index as key, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mentionsResolved, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, parseOriginUrl, rebaseConfigSchemaRefs, reencryptMetadata, render, renderDerive, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, resolvedColumns, run, runDerive, runFill, runGet, runQuery, runRelocate, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, selectCollections, sourcesFor, staleFindings, stringifyValue, supportedExtensions, valueOf, vendorFileName, writeFileAtomic };