@hawkeyexl/manni 0.3.0 → 1.0.0

package/dist/index.d.ts

@@ -177,9 +177,9 @@ interface FieldError {
     /**
      * The file `line` and `col` refer to, when it is not the result's own file.
      *
-     * Set only for a value a sidecar manifest supplied (proposal 0037), spelled
+     * Set only for a value a manifest supplied (proposal 0037), spelled
      * the way the run spells file labels. Absent means the document itself,
-     * which is every violation that existed before sidecars. The finding's
+     * which is every violation that existed before external metadata. The finding's
      * subject file stays `ValidationResult.file`: that is its baseline identity
      * and its SARIF location, and this names where the *value* was written.
      */
@@ -257,6 +257,49 @@ interface FingerprintContext {
     runBase?: string;
 }
 
+/** One external-metadata manifest (proposals 0037, 0038, 0039) joined to a collection. */
+interface ExternalMetadataConfig {
+    file: string;
+    keys: string[];
+    tokenEnv?: string;
+    join?: string;
+}
+/** One named document set, as declared under the top-level `collections:` key. */
+interface CollectionConfig {
+    name: string;
+    paths: string[];
+    exclude: string[];
+    externalMetadata: ExternalMetadataConfig[];
+    /** Where the collection is published; `manni a11y check` seeds from it. */
+    url?: string;
+}
+/**
+ * Whether a URL may name an external-metadata manifest: `https://` anywhere,
+ * or `http://` on a loopback host only, where plaintext leaks nothing.
+ * Userinfo is refused because the URL is printed in every diagnostic and a
+ * secret in it would print too. Returns the reason it may not, or `null`.
+ */
+declare function externalMetadataUrlProblem(url: string): string | null;
+/**
+ * Parse the top-level `collections:` value. Errors are built with `toError`,
+ * so each tool reports a bad family file in its own error class.
+ */
+declare function parseCollections(raw: unknown, source: string, toError: (message: string) => Error): CollectionConfig[];
+/**
+ * The collections a run covers: 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 is an error, because a typo that
+ * silently narrowed the run to nothing would read as a clean pass.
+ */
+declare function selectCollections(collections: readonly CollectionConfig[], names: readonly string[] | undefined, source: string, toError: (message: string) => Error): CollectionConfig[];
+/**
+ * Is this file a member of the collection? `relPath` is posix and already
+ * relative to the config file's directory, so this is arithmetic on a string:
+ * no `stat`, nothing that can fail, and nothing that costs per file. A path
+ * that climbed out of the config directory, and stdin, are members of nothing.
+ */
+declare function isMember(collection: CollectionConfig, relPath: string): boolean;
+
 interface SchemaOverride {
     /**
      * The glob, or globs, this override governs. A file matches when **any** of
@@ -268,20 +311,23 @@ interface SchemaOverride {
      * caller may hand `runValidate` a config object it built itself, and that
      * caller's bare string must keep working. Read it through `overrideGlobs`
      * rather than directly — that is the one place the two shapes collapse.
+     *
+     * Optional since proposal 0041: an entry carries **exactly one** of `files`
+     * or `collection`.
      */
-    files: string | string[];
+    files?: string | string[];
     schemas: string[];
     /**
-     * Optional collection name (proposal 0027): the override group becomes a
-     * SQL view of that name over the `docs` projection, holding exactly the
-     * files this override won schema resolution for. Any string is legal —
-     * view names are quoted identifiers — except the refusals `parseConfig`
-     * makes: a duplicate, `docs` (the table every query already reads), a
-     * blank name, and a name starting `sqlite_` (SQLite reserves the prefix).
-     * A `name:` also requires `schemas:`, because a schema-less override never
-     * wins resolution and its view would be empty by construction.
+     * The collection this override governs (proposal 0041), in place of globs of
+     * its own: it matches the members of the named collection, which are decided
+     * once, at the top level of the family file, for every tool. Must name a
+     * collection `collections:` defines — checked by `loadConfig`, which is the
+     * first place both halves of the file are known.
+     *
+     * This is what `overrides[].name` was for under 0027, inverted: a collection
+     * is the thing that has a name, and an override points at it.
      */
-    name?: string;
+    collection?: string;
     /**
      * Extra element paths for files matching `files`. Unlike `schemas`, which the
      * first matching override *replaces* because a schema set is a complete
@@ -357,40 +403,6 @@ interface CheckConfig {
     /** One SQL statement whose rows follow the finding column convention. */
     query: string;
 }
-/**
- * One sidecar manifest (proposal 0037): a YAML file that supplies a fixed set
- * of top-level keys for named documents, merged into each document's metadata
- * before schema resolution. The private half of a public docset.
- */
-interface SidecarConfig {
-    /**
-     * Manifest path, relative to the config file's directory, or an `https://`
-     * URL (proposal 0038) fetched at the start of every run. A URL serves a
-     * manifest in another public repository as readily as a private one; only
-     * the private one needs `tokenEnv`.
-     */
-    file: string;
-    /**
-     * The top-level keys this manifest owns. Ownership is disjoint across
-     * entries, so two manifests can never disagree about one key, and a
-     * document carrying an owned key is a finding rather than a tiebreak.
-     */
-    keys: string[];
-    /**
-     * Name of an environment variable whose value is sent as a bearer token
-     * when `file` is a URL. The token never appears in the config, a message,
-     * or a report. Refused on a path `file`, where it would do nothing.
-     */
-    tokenEnv?: string;
-    /**
-     * `path` (the default), or the top-level frontmatter field whose value the
-     * manifest's keys name (proposal 0039). A field join survives a rename;
-     * what it cannot survive is two documents sharing one value, which is a
-     * finding on both. Never `$schema`, and never a key this entry owns: the
-     * value that selects an entry cannot come from the entry.
-     */
-    join?: string;
-}
 /** Defaults for the `fill` command; every key is overridable by a CLI flag. */
 interface FillConfig {
     provider?: string;
@@ -412,8 +424,6 @@ interface SchemaCacheConfig {
     ttlHours?: number;
 }
 interface DocmetaConfig {
-    paths?: string[];
-    exclude?: string[];
     /**
      * The default schema set. Each entry is either a reference string or a
      * `{ ref, source?, integrity? }` mapping — see `SchemaEntry`.
@@ -425,11 +435,6 @@ interface DocmetaConfig {
      * run's file set is the config-resolved corpus. See `CheckConfig`.
      */
     checks?: CheckConfig[];
-    /**
-     * Sidecar manifests whose keys are merged into the documents they name.
-     * See `SidecarConfig`.
-     */
-    sidecars?: SidecarConfig[];
     /**
      * Element paths to lift in addition to each format's convention. See
      * `parseElementPath` for the syntax.
@@ -479,17 +484,28 @@ interface LoadedConfig {
     /** Absolute path to the file the config was read from. */
     path: string;
     /**
-     * Directory holding that file. Relative paths written *in* the config —
-     * `paths:`, `exclude:`, local-file schema refs — are meaningful relative to
+     * Directory holding that file. Relative paths written *in* the config — a
+     * collection's `paths:`, local-file schema refs — are meaningful relative to
      * this, not to the directory the command happened to be invoked from.
      */
     dir: string;
+    /**
+     * The file as the user would name it, which is how every config message
+     * spells it. Threaded from `ConfigFile.source` so `selectCollections` can
+     * name the file a `--collection` failed to find a collection in.
+     */
+    source: string;
     /**
      * The family-file key the config was read from under (`"meta"`), when it
      * was. Absent for a pre-family file, whose top level is the config. A
      * command that writes the file back (`schemas vendor`) needs to know.
      */
     section?: string;
+    /**
+     * Every collection the family file declares (proposal 0041), in declaration
+     * order. `[]` for a legacy per-tool file, which carries no family-wide keys.
+     */
+    collections: CollectionConfig[];
 }
 
 /**
@@ -546,24 +562,37 @@ interface RunConfigOptions {
     configPath?: string;
     /** `--no-config`: skip discovery and run on the built-in defaults. */
     noConfig?: boolean;
-    /** Positional inputs; empty means fall back to the config's `paths:`. */
+    /**
+     * Positional inputs; empty means fall back to the configured collections'
+     * `paths:` (proposal 0041).
+     */
     inputs: string[];
+    /**
+     * `--collection <name>`, repeatable: the collections this run covers. Empty
+     * or absent means every declared collection — the same thing, because
+     * commander's repeatable collector hands a caller `[]` when the flag was
+     * never passed (see `selectCollections`).
+     */
+    collections?: string[];
     onConfigLoaded?: (info: ConfigNotice) => void;
 }
 interface RunConfig {
     /** The config, with its local file schema refs already rebased. */
     config: DocmetaConfig | null;
-    /** What to resolve: the positional inputs, or the config's `paths:`. */
+    /**
+     * What to resolve: the positional inputs, or the selected collections'
+     * `paths:`, concatenated in declaration order.
+     */
     inputs: string[];
     /**
      * Directory those inputs — and so every resolved file path, and every file
      * read — are relative to.
      *
-     * A run uses *either* positional paths *or* config `paths:`, never both, so
-     * there is exactly one base per run and no ambiguity about which it is.
-     * Positional paths are typed by a person standing in a shell, so they stay
-     * relative to the working directory; `paths:` globs were written next to the
-     * config, so they resolve from there.
+     * A run uses *either* positional paths *or* the collections' `paths:`, never
+     * both, so there is exactly one base per run and no ambiguity about which it
+     * is. Positional paths are typed by a person standing in a shell, so they
+     * stay relative to the working directory; a collection's globs were written
+     * next to the config, so they resolve from there.
      */
     base: string;
     /**
@@ -584,6 +613,40 @@ interface RunConfig {
      * assumed filename names the wrong file in every one of those setups.
      */
     configPath?: string;
+    /**
+     * The key the tool's config sits under in that file — `meta` for a family
+     * file, `undefined` for a legacy per-tool file whose whole document is the
+     * section.
+     *
+     * Anything that *rewrites* the config by hand has to know: `schemas:` is at
+     * the top level of a legacy file and one level down in a family file, so a
+     * rewriter that assumes the top level silently finds nothing in the shape
+     * proposal 0033 made the default. `query`'s DDL repointing did exactly that
+     * until the 0041 fixtures stopped being legacy files and made it visible.
+     */
+    configSection?: string;
+    /**
+     * The collections this run covers (proposal 0041): every declared one, or
+     * the ones `--collection` named. `[]` when no config governs the run.
+     *
+     * Selected even when the inputs are positional, because membership is what
+     * external metadata attaches to (rule 4) and a file the operator typed is
+     * still a member of whatever collections contain it.
+     */
+    collections: CollectionConfig[];
+    /**
+     * Every collection the config declares, in declaration order — the same list
+     * `collections` narrows. `query` needs both: membership and manifests follow
+     * the *selected* set, while every *declared* collection is a SQL view (0041
+     * rule 11), so a statement naming one the run did not select still answers.
+     */
+    declaredCollections: CollectionConfig[];
+    /**
+     * Whether `inputs` came from the collections rather than the command line.
+     * The corpus invariant every scoped check reads: a positional path means the
+     * operator chose part of the corpus.
+     */
+    fromCollections: boolean;
 }
 /**
  * Settle the three things every command core needs from config before it can
@@ -602,6 +665,12 @@ interface ValidateOptions {
     configPath?: string;
     /** `--no-config`: skip config discovery and use the built-in defaults. */
     noConfig?: boolean;
+    /**
+     * `--collection <name>`, repeatable: run over the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with positional paths; `-` is allowed beside it.
+     */
+    collections?: string[];
     cwd?: string;
     /** Content for the `-` (stdin) input, injected by the CLI/tests. */
     stdinContent?: string;
@@ -668,6 +737,12 @@ interface GetOptions {
     configPath?: string;
     /** `--no-config`: skip config discovery and use the built-in defaults. */
     noConfig?: boolean;
+    /**
+     * `--collection <name>`, repeatable: run over the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with positional paths; `-` is allowed beside it.
+     */
+    collections?: string[];
     cwd?: string;
     /** Content for the `-` (stdin) input, injected by the CLI/tests. */
     stdinContent?: string;
@@ -730,6 +805,12 @@ interface QueryOptions {
     configPath?: string;
     /** `--no-config`: skip config discovery and use the built-in defaults. */
     noConfig?: boolean;
+    /**
+     * `--collection <name>`, repeatable: run over the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with positional paths; `-` is allowed beside it.
+     */
+    collections?: string[];
     cwd?: string;
     /** Content for the `-` (stdin) input, injected by the CLI/tests. */
     stdinContent?: string;
@@ -1125,6 +1206,12 @@ interface FillOptions {
     configPath?: string;
     /** `--no-config`: skip config discovery and use the built-in defaults. */
     noConfig?: boolean;
+    /**
+     * `--collection <name>`, repeatable: run over the named configured
+     * collections instead of every declared one (proposal 0041). Cannot be
+     * combined with positional paths; `-` is allowed beside it.
+     */
+    collections?: string[];
     cwd?: string;
     /** Content for the `-` (stdin) input, injected by the CLI/tests. */
     stdinContent?: string;
@@ -1176,31 +1263,38 @@ declare function runFill(opts: FillOptions): Promise<FillRun>;
 
 /**
  * The `schema` ref a collision finding carries, and so its baseline and rule
- * identity: `sidecar:owned/sidecar`. Shaped like `check:<name>` so
+ * identity: `external:owned/external`. Shaped like `check:<name>` so
  * `classifyRef` passes it through as a built-in id rather than resolving it
  * as a cwd-relative file path, and reserved in the registry for the same
  * reason `check` is.
  */
-declare const SIDECAR_OWNED_SCHEMA = "sidecar:owned";
+declare const EXTERNAL_OWNED_SCHEMA = "external:owned";
 /**
  * The `schema` ref of a duplicate-join finding (0039): two documents carry
  * the same value of a join field, so one manifest entry matched both.
  */
-declare const SIDECAR_DUPLICATE_SCHEMA = "sidecar:duplicate";
-/** The `keyword` every sidecar finding carries: no Ajv keyword produced it. */
-declare const SIDECAR_KEYWORD = "sidecar";
+declare const EXTERNAL_DUPLICATE_SCHEMA = "external:duplicate";
+/**
+ * The `keyword` every external-metadata finding carries: no Ajv keyword
+ * produced it.
+ */
+declare const EXTERNAL_KEYWORD = "external";
 /** The join that names documents by path, and the default. */
 declare const PATH_JOIN = "path";
-/** One value a sidecar supplied, and where it was written. */
-interface SidecarValue {
+/** One value a manifest supplied, and where it was written. */
+interface ExternalMetadataValue {
     value: unknown;
+    /** The collection whose manifest supplied it (proposal 0041). */
+    collection: string;
     /** Manifest path as the run reports it: relative to the run's base, posix — or the URL. */
     file: string;
     /** 1-based line of the key in the manifest, when known. */
     line?: number;
 }
 /** One manifest entry, for the orphan checks. */
-interface SidecarEntry {
+interface ExternalMetadataEntry {
+    /** The collection whose manifest declared it (proposal 0041). */
+    collection: string;
     /** `path`, or the frontmatter field this entry is keyed by. */
     join: string;
     /** Absolute document path, for a path entry. */
@@ -1212,19 +1306,29 @@ interface SidecarEntry {
     /** 1-based line of the entry in the manifest, when known. */
     line?: number;
 }
-/** Every sidecar of a run, loaded once and consulted per document. */
-interface SidecarIndex {
-    /** Owned key -> manifest path as reported. */
-    owners: ReadonlyMap<string, string>;
-    /** Path-joined sidecars: absolute document path -> owned key -> value. */
-    byPath: ReadonlyMap<string, ReadonlyMap<string, SidecarValue>>;
-    /** Field-joined sidecars: field -> value -> owned key -> value. */
-    byField: ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, SidecarValue>>>;
+/** Every manifest of a run, loaded once and consulted per document. */
+interface ExternalMetadataIndex {
+    /**
+     * Owned key -> every collection that owns it, with the manifest that does.
+     *
+     * A list rather than one entry, because two collections may legitimately
+     * each own the same key (0041 rule 5): `guides` and `blog` can both supply
+     * `owner`. Ambiguity only exists for a file that is a member of both, which
+     * is decided per file in `mergeExternalMetadata`.
+     */
+    owners: ReadonlyMap<string, readonly {
+        collection: string;
+        file: string;
+    }[]>;
+    /** Path-joined manifests: absolute document path -> owned key -> value. */
+    byPath: ReadonlyMap<string, ReadonlyMap<string, ExternalMetadataValue>>;
+    /** Field-joined manifests: field -> value -> owned key -> value. */
+    byField: ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, ExternalMetadataValue>>>;
     /** Every manifest entry, in manifest order. */
-    entries: readonly SidecarEntry[];
+    entries: readonly ExternalMetadataEntry[];
 }
-interface LoadSidecarsOptions {
-    /** Directory `sidecars[].file` and every manifest key resolve from. */
+interface LoadExternalMetadataOptions {
+    /** Directory `externalMetadata[].file` and every manifest key resolve from. */
     configDir: string;
     /** Directory the run's file labels are relative to; manifests are reported the same way. */
     base: string;
@@ -1241,20 +1345,24 @@ interface SourceLocation {
     line?: number;
     col?: number;
 }
-/** A key the document carries that a sidecar owns. */
-interface SidecarCollision {
+/** A key the document carries that a manifest owns. */
+interface ExternalMetadataCollision {
     key: string;
     /** The owning manifest, as the run reports it. */
     file: string;
+    /** The collection that manifest belongs to (proposal 0041). */
+    collection: string;
 }
 /** A field-joined entry a document matched (0039). */
-interface SidecarJoin {
+interface ExternalMetadataJoin {
     field: string;
     value: string;
     /** The manifest, as the run reports it. */
     file: string;
+    /** The collection that manifest belongs to (proposal 0041). */
+    collection: string;
 }
-/** What `mergeSidecars` hands back. */
+/** What `mergeExternalMetadata` hands back. */
 interface MergedMetadata {
     /** The document's metadata with every owned key the manifest supplied. */
     extracted: ExtractedMetadata;
@@ -1263,9 +1371,9 @@ interface MergedMetadata {
      * with the manifest that owns it — so the finding names it without a
      * second lookup, and without a fallback for an index that is not there.
      */
-    collisions: SidecarCollision[];
-    /** Field-joined entries this document matched, one per sidecar at most. */
-    joins: SidecarJoin[];
+    collisions: ExternalMetadataCollision[];
+    /** Field-joined entries this document matched, one per manifest at most. */
+    joins: ExternalMetadataJoin[];
     /**
      * Where a merged pointer's value lives. Answers only for a value the
      * manifest supplied — a bare key or its `/key` pointer, and anything
@@ -1274,19 +1382,20 @@ interface MergedMetadata {
      */
     locate: (pointer: string) => SourceLocation | undefined;
 }
-/** The join a sidecar config asks for: `path` unless it names a field. */
-declare function sidecarJoin(sidecar: Pick<SidecarConfig, "join">): string;
+/** The join an external-metadata config asks for: `path` unless it names a field. */
+declare function externalMetadataJoin(manifest: Pick<ExternalMetadataConfig, "join">): string;
 /**
- * Load every configured manifest. Resolves to `null` when the config declares
- * none, which is every setup that existed before this feature.
+ * Load every manifest of every collection the run covers. Resolves to `null`
+ * when none of them declares one, which is every setup that existed before
+ * this feature.
  *
  * Every refusal is a `DocmetaError`: the manifest is a config-supplied input,
  * and one that is missing or misshapen is the run's problem, not a
  * document's (0014).
  */
-declare function loadSidecars(config: DocmetaConfig | null | undefined, opts: LoadSidecarsOptions): Promise<SidecarIndex | null>;
+declare function loadExternalMetadata(collections: readonly CollectionConfig[], opts: LoadExternalMetadataOptions): Promise<ExternalMetadataIndex | null>;
 /**
- * Merge the sidecar values for one document into its extracted metadata.
+ * Merge the external metadata for one document into its extracted metadata.
  *
  * `label` is the document as the run spells it, relative to `base`; a path
  * entry matches on the resolved absolute path, never on the spelling, so a
@@ -1295,13 +1404,17 @@ declare function loadSidecars(config: DocmetaConfig | null | undefined, opts: Lo
  * field, wherever the document lives. Stdin never matches a path entry:
  * there is no file behind it.
  *
+ * `memberOf` names the collections this document belongs to, and only their
+ * manifests are consulted (0041 rule 4). It is the caller's `memberOf(...)`
+ * result, computed once per file.
+ *
  * `present`, `format` and the document's own positions are untouched. A
- * sidecar key is not in the document, so `lineFor` keeps answering
+ * manifest key is not in the document, so `lineFor` keeps answering
  * `undefined` for it, and `locate` answers instead.
  */
-declare function mergeSidecars(label: string, extracted: ExtractedMetadata, index: SidecarIndex | null, base: string): MergedMetadata;
-/** The `/key` pointer for a sidecar finding, RFC 6901 escaped. */
-declare function sidecarPointer(key: string): string;
+declare function mergeExternalMetadata(label: string, extracted: ExtractedMetadata, index: ExternalMetadataIndex | null, memberOf: readonly string[], base: string): MergedMetadata;
+/** The `/key` pointer for an external-metadata finding, RFC 6901 escaped. */
+declare function externalMetadataPointer(key: string): string;
 /**
  * Path entries naming no loaded document.
  *
@@ -1310,16 +1423,16 @@ declare function sidecarPointer(key: string): string;
  * positional path means the operator chose to look at part of the corpus,
  * and an entry for the rest is expected, not orphaned.
  */
-declare function orphanEntries(index: SidecarIndex | null, loaded: readonly string[], base: string): SidecarEntry[];
+declare function orphanEntries(index: ExternalMetadataIndex | null, loaded: readonly string[], base: string, collections?: readonly string[]): ExternalMetadataEntry[];
 /**
  * Field entries no loaded document matched (0039). `matched` is field -> the
  * values documents in the run carried, which the caller collects from each
  * document's `joins` — so this runs after the per-file loop, under the same
  * corpus invariant as `orphanEntries`.
  */
-declare function orphanJoins(index: SidecarIndex | null, matched: ReadonlyMap<string, ReadonlySet<string>>): SidecarEntry[];
+declare function orphanJoins(index: ExternalMetadataIndex | null, matched: ReadonlyMap<string, ReadonlySet<string>>, collections?: readonly string[]): ExternalMetadataEntry[];
 /** The operational error an orphan check raises, naming the first entry. */
-declare function orphanError(orphans: readonly SidecarEntry[]): DocmetaError;
+declare function orphanError(orphans: readonly ExternalMetadataEntry[]): DocmetaError;
 
 declare class Validator {
     private readonly schemaOptions;
@@ -1369,7 +1482,7 @@ declare class Validator {
     validate(data: Record<string, unknown>, refs: string[], lineFor: (pointer: string) => number | undefined, colFor?: (pointer: string) => number | undefined, 
     /**
      * Where a merged value lives when it is not in the document (proposal
-     * 0037): a sidecar manifest's file and line. Consulted before `lineFor`,
+     * 0037): a manifest's file and line. Consulted before `lineFor`,
      * and additive in the way `colFor` was.
      */
     locate?: (pointer: string) => SourceLocation | undefined): Promise<FieldError[]>;
@@ -1389,7 +1502,7 @@ declare const DEFAULT_SCHEMAS: readonly string[];
  * The ref *string* is what `resolveSchemaSet` returns and therefore what every
  * report names, what every baseline fingerprint is taken over, and what keys
  * `Validator`'s compile cache. Widening those to carry a mapping would have
- * changed all three; the `{source, integrity}` sidecar travels separately, in
+ * changed all three; the `{source, integrity}` pair travels separately, in
  * the pin map below.
  */
 declare function schemaEntryRef(entry: SchemaEntry): string;
@@ -1459,9 +1572,63 @@ interface ResolveParams {
      * failure mode this key exists to remove.
      */
     onNotice?: (message: string) => void;
+    /**
+     * The collections this file belongs to (proposal 0041), from `memberOf`.
+     *
+     * What an `overrides[].collection` entry is matched against, in place of the
+     * glob match a `files:` entry gets. Absent means the caller decided
+     * membership does not apply — a library caller with no config file, or a
+     * command that has not resolved it — and a `collection:` override then
+     * matches nothing, rather than everything.
+     */
+    memberOf?: readonly string[];
 }
+
 declare function resolveSchemaSet(params: ResolveParams): string[];
 
+/**
+ * Collection views, and the membership adapter that decides what a collection
+ * contains.
+ *
+ * `memberOf` is proposal 0041's rule 10: which collections a file belongs to,
+ * as path arithmetic against the config file's directory. It is what external
+ * metadata attaches to, what an `overrides[].collection` resolves through, and
+ * — since 0041 rule 7 — what a SQL view holds.
+ *
+ * One meaning of "collection", everywhere. 0027 built each view from the files
+ * an override *won schema resolution for*, so views were disjoint, only a
+ * collection an override pointed at had a view at all, and a file whose own
+ * `$schema` outranked the override was announced as not being in it. 0041
+ * makes a view the set the config says it is: every declared collection is a
+ * view, two views may overlap, and `FROM authors` reads as "the files the
+ * authors collection selects".
+ *
+ * That restores 0021's founding rule, which 0027 had to bend: a plain read
+ * resolves no schemas. Nothing in this module resolves anything, so there is
+ * no trust refusal to demote a file over, no per-file walk to pay for, and no
+ * notice to print. Resolution still honours `overrides[].collection` — it
+ * matches through `memberOf` in `resolve-schema.ts`, which is untouched.
+ *
+ * Shared by both projection consumers — `query` and the corpus checks
+ * `validate` runs — so the two cannot drift on what a collection contains.
+ */
+
+/**
+ * Names of the collections this file belongs to, in declaration order.
+ *
+ * Where the two bases meet. A run labels files relative to `base` — the
+ * working directory for positional paths, the config's directory otherwise —
+ * while membership is decided relative to the config file's directory, because
+ * that is where a collection's globs were written (0004). So the label is
+ * resolved against `base` and then measured from `configDir`.
+ *
+ * Pure path arithmetic (0041 rule 10): no `stat`, nothing that can fail, and
+ * nothing that costs per file. Stdin and anything outside `configDir` are
+ * members of nothing — stdin because there is no file behind it, and `isMember`
+ * refuses a `../` path on its own.
+ */
+declare function memberOf(collections: readonly CollectionConfig[], configDir: string, base: string, label: string): string[];
+
 /** What a well-formed pin looks like, for error messages. */
 declare const INTEGRITY_SHAPE = "sha256-<64 hex characters>";
 /**
@@ -1476,10 +1643,10 @@ declare function integrityOf(bytes: Uint8Array): string;
 declare function isIntegrity(value: string): boolean;
 
 /** Default network timeout, matching the schema fetch. */
-declare const SIDECAR_FETCH_TIMEOUT_MS = 10000;
+declare const EXTERNAL_METADATA_FETCH_TIMEOUT_MS = 10000;
 /** Body cap, matching the schema fetch. */
-declare const SIDECAR_FETCH_MAX_BYTES: number;
-interface SidecarFetchOptions {
+declare const EXTERNAL_METADATA_FETCH_MAX_BYTES: number;
+interface ExternalMetadataFetchOptions {
     /** Environment variable holding a bearer token. Absent means an anonymous request. */
     tokenEnv?: string;
     timeoutMs?: number;
@@ -1489,15 +1656,8 @@ interface SidecarFetchOptions {
     /** For tests: the environment to read `tokenEnv` from. Defaults to `process.env`. */
     env?: Record<string, string | undefined>;
 }
-/**
- * Whether a URL may name a sidecar manifest: `https://` anywhere, or `http://`
- * on a loopback host only, where plaintext leaks nothing. Userinfo is refused
- * because the URL is printed in every diagnostic and a secret in it would
- * print too. Returns the reason it may not, or `null`.
- */
-declare function sidecarUrlProblem(url: string): string | null;
 /** Fetch one remote manifest. Resolves to its text; throws `DocmetaError`. */
-declare function fetchSidecar(url: string, opts?: SidecarFetchOptions): Promise<string>;
+declare function fetchExternalMetadata(url: string, opts?: ExternalMetadataFetchOptions): Promise<string>;
 
 /**
  * Where the cache lives, relative to the project root.
@@ -1846,4 +2006,4 @@ declare function extractorForExtension(ext: string): MetadataExtractor | undefin
 /** Extensions handled by implemented extractors (used for directory walks). */
 declare function supportedExtensions(): string[];
 
-export { type ApplyOptions, type BaselineSummary, COMMON_FORMATS, type CheckConfig, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, type DocmetaConfig, DocmetaError, type DocumentRefTrust, type ExtractOptions, type ExtractedMetadata, FILL_FORMATS, type FetchedSchema, type FieldError, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, INTEGRITY_SHAPE, type JunitOptions, type LoadSchemaOptions, type LoadSidecarsOptions, type LoadedConfig, type MergedMetadata, type MetadataExtractor, type MetadataPatch, PATH_JOIN, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, type ReadOptions, type ReportFormat, type ReportOptions, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, SIDECAR_DUPLICATE_SCHEMA, SIDECAR_FETCH_MAX_BYTES, SIDECAR_FETCH_TIMEOUT_MS, SIDECAR_KEYWORD, SIDECAR_OWNED_SCHEMA, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SidecarCollision, type SidecarConfig, type SidecarEntry, type SidecarFetchOptions, type SidecarIndex, type SidecarJoin, type SidecarValue, type SkipReason, type SourceLocation, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, classifyRef, collectSchemaPins, extractFrontmatter, extractorForExtension, fetchSchemaBytes, fetchSidecar, frontmatterInnerText, getSchemasInfo, integrityOf, isCommonFormat, isFillFormat, isIntegrity, isQueryFormat, isReportFormat, listBuiltins, loadConfig, loadSchema, loadSidecars, locateFrontmatter, mergeSidecars, orphanEntries, orphanError, orphanJoins, parseConfig, rebaseConfigSchemaRefs, render, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, runFill, runGet, runQuery, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, sidecarJoin, sidecarPointer, sidecarUrlProblem, stringifyValue, supportedExtensions, vendorFileName, writeFileAtomic };
+export { type ApplyOptions, type BaselineSummary, COMMON_FORMATS, type CheckConfig, type CollectionConfig, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, type DocmetaConfig, DocmetaError, type DocumentRefTrust, EXTERNAL_DUPLICATE_SCHEMA, EXTERNAL_KEYWORD, EXTERNAL_METADATA_FETCH_MAX_BYTES, EXTERNAL_METADATA_FETCH_TIMEOUT_MS, EXTERNAL_OWNED_SCHEMA, type ExternalMetadataCollision, type ExternalMetadataConfig, type ExternalMetadataEntry, type ExternalMetadataFetchOptions, type ExternalMetadataIndex, type ExternalMetadataJoin, type ExternalMetadataValue, type ExtractOptions, type ExtractedMetadata, FILL_FORMATS, type FetchedSchema, type FieldError, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, INTEGRITY_SHAPE, type JunitOptions, type LoadExternalMetadataOptions, type LoadSchemaOptions, type LoadedConfig, type MergedMetadata, type MetadataExtractor, type MetadataPatch, PATH_JOIN, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, type ReadOptions, type ReportFormat, type ReportOptions, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SkipReason, type SourceLocation, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, classifyRef, collectSchemaPins, externalMetadataJoin, externalMetadataPointer, externalMetadataUrlProblem, extractFrontmatter, extractorForExtension, fetchExternalMetadata, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, integrityOf, isCommonFormat, isFillFormat, isIntegrity, isMember, isQueryFormat, isReportFormat, listBuiltins, loadConfig, loadExternalMetadata, loadSchema, locateFrontmatter, memberOf, mergeExternalMetadata, orphanEntries, orphanError, orphanJoins, parseCollections, parseConfig, rebaseConfigSchemaRefs, render, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, runFill, runGet, runQuery, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, selectCollections, stringifyValue, supportedExtensions, vendorFileName, writeFileAtomic };