indexwright 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,16 +5,63 @@ All notable changes to this project are documented here. The format follows
 versioning. Pre-1.0, rule additions and message changes may land in minor releases; the `json`
 output shape is the stable contract.
 
+## [0.3.0] — 2026-09-21
+
+The other half of the file. `fieldOverrides` — single-field index configuration — was typed
+`unknown[]` and read by nothing; it is now validated to the same depth as `indexes` and reduced to
+a canonical form, so that `@indexwright/record` 0.7.0 can reconcile a declaration against a live
+field listing on the one key the linter will report on. No rule reads it yet, and nothing about the
+linter's output or exit codes changes. The package also moves inside the repository, to
+`packages/indexwright`, without moving anything about what is published.
+
+### Added
+
+- **`fieldOverrides` is validated and has a canonical form** (issues #53 and #54). The file's other
+  half was typed `unknown[]` and read by nothing. It is now held to the same depth as `indexes` —
+  an entry needs `collectionGroup`, `fieldPath`, and an `indexes` array (empty for an exemption),
+  each index exactly one of `order`, `arrayConfig`, and `vectorConfig` (and a `queryScope`, read as
+  `COLLECTION` when omitted, as the Firebase CLI does), and `ttl` a boolean when present — and `analyseOverrides` reduces each to an `AnalysedOverride` keyed as
+  `<collectionGroup>::<fieldPath>::<queryScope>:<direction>|…`, sorted, with entries alike in scope and
+  direction collapsed, as the set it is. No rule reads it yet; the form exists so that `@indexwright/record` can reconcile a
+  declaration against a live field listing on the same key the linter will report on, rather than
+  on a second model. A file whose `fieldOverrides` cannot be read that way is now malformed, where
+  it previously passed unexamined. `fieldDirection` accepts any object carrying the three configs,
+  which every `IndexField` still is.
+
+### Changed
+
+- `IndexDocument.fieldOverrides` is typed `FieldOverride[]`, no longer `unknown[]`. A consumer
+  that built one by hand with entries of another shape stops compiling.
+- The package now lives at `packages/indexwright` rather than at the repository root, so that
+  `@indexwright/record` can depend on it from the working tree instead of from a published release.
+  Nothing about the published package moves: same name, same bin, same `exports`, same
+  dependency-free guarantee.
+- `SPEC.md` is no longer shipped inside the tarball. It specifies both packages, so it belongs to
+  the repository rather than to either one, and `files` cannot reach above a package directory. The
+  alternative — copying it in at pack time — runs through `prepublishOnly`, which npm skips entirely
+  under `ignore-scripts=true`; that would make the verified tarball and the published one differ in
+  exactly the way `verify-package` exists to catch. The spec is linked from the README and is in the
+  repository.
+
+### Notes
+
+- **The override key carries no marker telling it from an index key.** `posts::tags::COLLECTION:…`
+  and `posts::COLLECTION::tags:…` are the same shape read by different rules, and a reader that
+  does not know which listing a key came from cannot tell them apart by the string alone. Decided
+  and left as it is for this release: no rule reports an override key yet and the `json` output
+  does not carry one, so adding a marker later would change nothing that is a contract today, while
+  adding one now would fix a spelling nothing has needed.
+
 ## [0.2.0] — 2026-08-10
 
 ### Added
 
-- A query corpus format, specified in [SPEC.md](SPEC.md) §7 and versioned by its own
+- A query corpus format, specified in [SPEC.md](https://github.com/uny/indexwright/blob/main/SPEC.md) §7 and versioned by its own
   `corpusVersion` rather than by any package's release number. It is the contract between capture
   and the coverage check, and the first indexwright artefact meant to be committed and reviewed in
   a diff alongside `firestore.indexes.json`.
 - `@indexwright/record`, a separate package that writes one. See
-  [its changelog](packages/record/CHANGELOG.md).
+  [its changelog](https://github.com/uny/indexwright/blob/main/packages/record/CHANGELOG.md).
 - `indexwright record` now says that the verb ships in `@indexwright/record` and how to run it,
   instead of reporting an unknown command. The cost of splitting the family into two packages is a
   second package to discover, and "unknown command" reads as "indexwright cannot do this".
@@ -53,6 +100,7 @@ First release. Static analysis of `firestore.indexes.json`; no network access, n
   `__name__` to the same resource.
 - A provisional JavaScript API, so the rules can run without spawning a process.
 
+[0.3.0]: https://github.com/uny/indexwright/releases/tag/v0.3.0
 [0.2.0]: https://github.com/uny/indexwright/releases/tag/v0.2.0
 [0.1.1]: https://github.com/uny/indexwright/releases/tag/v0.1.1
 [0.1.0]: https://github.com/uny/indexwright/releases/tag/v0.1.0

package/README.md

@@ -88,7 +88,7 @@ measured your own noise level.
 | `quota-headroom` | The declared index count is close to the per-database limit. |
 
 Each rule's rationale, its known false positives, and the exact detection condition are in
-[SPEC.md](SPEC.md) §5.
+[SPEC.md](https://github.com/uny/indexwright/blob/main/SPEC.md) §5.
 
 ### A note on `__name__`
 
@@ -147,7 +147,7 @@ console.log(result.summary.byRule);
 no Firestore connection. Answering *is this index needed* takes the queries, which is a separate
 package:
 
-- **v0.2 — query capture, shipped.** [`@indexwright/record`](packages/record) runs a test suite
+- **v0.2 — query capture, shipped.** [`@indexwright/record`](https://github.com/uny/indexwright/tree/main/packages/record) runs a test suite
   with `FIRESTORE_EMULATOR_HOST` pointed at a pass-through proxy and records the `StructuredQuery`
   shapes it observes as a corpus. This is language- and framework-independent because it operates
   on the wire protocol rather than on source code.
@@ -158,7 +158,7 @@ package:
 Coverage is bounded by what actually exercises the proxy. A query no test issues is not observed,
 and absence of observation is not evidence that an index is unused. That limit is inherent; the
 narrower ones that are not — the Firebase Web SDK's transport, and snapshot listeners — are
-[named in the spec](SPEC.md) and counted in the corpus rather than passed over.
+[named in the spec](https://github.com/uny/indexwright/blob/main/SPEC.md) and counted in the corpus rather than passed over.
 
 ## Toward 1.0
 
@@ -170,8 +170,8 @@ Until then the version stays below 1.0 and the rules stay provisional.
 
 ## Development
 
-This is an npm workspace holding two packages: `indexwright` at the root and
-[`@indexwright/record`](packages/record) under `packages/`. Both scripts cover both.
+This is an npm workspace holding two packages under `packages/`: `indexwright` and
+[`@indexwright/record`](https://github.com/uny/indexwright/tree/main/packages/record). Both scripts cover both.
 
 ```bash
 npm install

package/dist/index.d.ts

@@ -8,11 +8,11 @@
 export { formatGithub, type GithubOutput } from './format/github.js';
 export { formatJson } from './format/json.js';
 export { formatText } from './format/text.js';
-export { analyse, canonicalFields, fieldDirection, implicitNameDirection, indexKey, NAME_FIELD, } from './key.js';
+export { analyse, analyseOverrides, canonicalFields, canonicalSingleFieldIndexes, fieldDirection, formatSingleFieldIndex, implicitNameDirection, indexKey, NAME_FIELD, overrideKey, type IndexConfig, } from './key.js';
 export { DEFAULT_QUOTA, DEFAULT_QUOTA_THRESHOLD, lintDocuments, lintFiles, lintTexts, type DocumentInput, type LintOptions, type TextInput, } from './lint.js';
 export { MalformedInputError, parseDocument, validateDocument } from './parse.js';
 export { getRule, isRuleId, rules } from './rules/index.js';
 export { RULE_IDS } from './types.js';
-export type { AnalysedIndex, CanonicalField, CompositeIndex, Finding, IndexDocument, IndexField, LintError, LintResult, LintSummary, OutputFormat, Rule, RuleContext, RuleId, RuleOptions, } from './types.js';
+export type { AnalysedIndex, AnalysedOverride, CanonicalField, CanonicalSingleFieldIndex, CompositeIndex, FieldOverride, Finding, IndexDocument, IndexField, LintError, LintResult, LintSummary, OutputFormat, Rule, RuleContext, RuleId, RuleOptions, SingleFieldIndex, } from './types.js';
 export { VERSION } from './version.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,UAAU,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,aAAa,EACb,SAAS,EACT,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,OAAO,EACP,aAAa,EACb,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,MAAM,EACN,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,QAAQ,EACR,UAAU,EACV,WAAW,EACX,KAAK,WAAW,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,aAAa,EACb,SAAS,EACT,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,OAAO,EACP,aAAa,EACb,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,MAAM,EACN,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -8,7 +8,7 @@
 export { formatGithub } from './format/github.js';
 export { formatJson } from './format/json.js';
 export { formatText } from './format/text.js';
-export { analyse, canonicalFields, fieldDirection, implicitNameDirection, indexKey, NAME_FIELD, } from './key.js';
+export { analyse, analyseOverrides, canonicalFields, canonicalSingleFieldIndexes, fieldDirection, formatSingleFieldIndex, implicitNameDirection, indexKey, NAME_FIELD, overrideKey, } from './key.js';
 export { DEFAULT_QUOTA, DEFAULT_QUOTA_THRESHOLD, lintDocuments, lintFiles, lintTexts, } from './lint.js';
 export { MalformedInputError, parseDocument, validateDocument } from './parse.js';
 export { getRule, isRuleId, rules } from './rules/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,UAAU,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,aAAa,EACb,SAAS,EACT,SAAS,GAIV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiBtC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,QAAQ,EACR,UAAU,EACV,WAAW,GAEZ,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,aAAa,EACb,SAAS,EACT,SAAS,GAIV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAqBtC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/key.d.ts

@@ -1,12 +1,14 @@
-import type { AnalysedIndex, CanonicalField, IndexDocument, IndexField } from './types.js';
+import type { AnalysedIndex, AnalysedOverride, CanonicalField, CanonicalSingleFieldIndex, IndexDocument, IndexField, SingleFieldIndex } from './types.js';
 export declare const NAME_FIELD = "__name__";
+/** The three configs a field can carry, which a composite index's field and a single-field index share. */
+export type IndexConfig = Pick<IndexField, 'order' | 'arrayConfig' | 'vectorConfig'>;
 /**
  * The direction a field contributes to the canonical key.
  *
  * `parse.ts` guarantees exactly one of `order`, `arrayConfig`, and `vectorConfig` is present, so
  * the fallback is unreachable for validated input.
  */
-export declare function fieldDirection(field: IndexField): string;
+export declare function fieldDirection(field: IndexConfig): string;
 /**
  * The direction Firestore would give the document key it appends to this field list.
  *
@@ -32,4 +34,30 @@ export declare function formatField(field: CanonicalField): string;
 export declare function indexKey(collectionGroup: string, queryScope: string, fields: readonly CanonicalField[]): string;
 /** Precompute the canonical form once so every rule shares one interpretation of the document. */
 export declare function analyse(document: IndexDocument): AnalysedIndex[];
+export declare function formatSingleFieldIndex(index: CanonicalSingleFieldIndex): string;
+/**
+ * The canonical key of a field override (SPEC §5, *Canonical override key*).
+ *
+ * The same three-part shape as `indexKey`, with the field path where the query scope sits and the
+ * scope inside each entry — a single-field index names one field, so what varies per entry is the
+ * scope. `indexes` must already be in canonical order; the key is a rendering, not a sort.
+ */
+export declare function overrideKey(collectionGroup: string, fieldPath: string, indexes: readonly CanonicalSingleFieldIndex[]): string;
+/**
+ * Reduce an override's declared set to canonical form.
+ *
+ * A composite index's fields are a sequence and their order is part of the key; an override's
+ * indexes are a set, and Firestore holds at most one single-field index per (scope, direction) of
+ * a field. So the entries are sorted, and entries that agree on scope and direction are collapsed
+ * to one: two spellings of one configuration reach the same key, while two configurations that
+ * differ in any member cannot. The collapse reads only what the key reads — two entries alike in
+ * scope and direction but differing in a key the form does not see (`density`, `unique`) collapse
+ * too, and `source.indexes` keeps both for a consumer that refuses what the key cannot express.
+ */
+export declare function canonicalSingleFieldIndexes(indexes: readonly SingleFieldIndex[]): CanonicalSingleFieldIndex[];
+/**
+ * The counterpart of `analyse` for the document's other half. An absent `fieldOverrides` is an
+ * empty set, which is what a hand-written file without the key means.
+ */
+export declare function analyseOverrides(document: IndexDocument): AnalysedOverride[];
 //# sourceMappingURL=key.d.ts.map

package/dist/key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAkB,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3G,eAAO,MAAM,UAAU,aAAa,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQxD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAM3E;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,+FAA+F;IAC/F,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,eAAe,CAS9E;AAMD,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEzD;AAED,wBAAgB,QAAQ,CACtB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC,MAAM,CAER;AAED,kGAAkG;AAClG,wBAAgB,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,aAAa,EAAE,CAEhE"}
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EAGzB,aAAa,EACb,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,UAAU,aAAa,CAAC;AAErC,2GAA2G;AAC3G,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,aAAa,GAAG,cAAc,CAAC,CAAC;AAErF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAQzD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAM3E;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,+FAA+F;IAC/F,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,eAAe,CAS9E;AAMD,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEzD;AAED,wBAAgB,QAAQ,CACtB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC,MAAM,CAER;AAED,kGAAkG;AAClG,wBAAgB,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,aAAa,EAAE,CAEhE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CAE/E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,yBAAyB,EAAE,GAC5C,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GACnC,yBAAyB,EAAE,CAe7B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,gBAAgB,EAAE,CAI5E"}

package/dist/key.js

@@ -1,3 +1,4 @@
+import { compareStrings } from './collections.js';
 export const NAME_FIELD = '__name__';
 /**
  * The direction a field contributes to the canonical key.
@@ -61,6 +62,63 @@ export function indexKey(collectionGroup, queryScope, fields) {
 export function analyse(document) {
     return document.indexes.map((source, position) => analyseIndex(source, position));
 }
+export function formatSingleFieldIndex(index) {
+    return `${index.queryScope}:${index.direction}`;
+}
+/**
+ * The canonical key of a field override (SPEC §5, *Canonical override key*).
+ *
+ * The same three-part shape as `indexKey`, with the field path where the query scope sits and the
+ * scope inside each entry — a single-field index names one field, so what varies per entry is the
+ * scope. `indexes` must already be in canonical order; the key is a rendering, not a sort.
+ */
+export function overrideKey(collectionGroup, fieldPath, indexes) {
+    return `${collectionGroup}::${fieldPath}::${indexes.map(formatSingleFieldIndex).join('|')}`;
+}
+/**
+ * Reduce an override's declared set to canonical form.
+ *
+ * A composite index's fields are a sequence and their order is part of the key; an override's
+ * indexes are a set, and Firestore holds at most one single-field index per (scope, direction) of
+ * a field. So the entries are sorted, and entries that agree on scope and direction are collapsed
+ * to one: two spellings of one configuration reach the same key, while two configurations that
+ * differ in any member cannot. The collapse reads only what the key reads — two entries alike in
+ * scope and direction but differing in a key the form does not see (`density`, `unique`) collapse
+ * too, and `source.indexes` keeps both for a consumer that refuses what the key cannot express.
+ */
+export function canonicalSingleFieldIndexes(indexes) {
+    const seen = new Set();
+    const canonical = [];
+    for (const index of indexes) {
+        const entry = { queryScope: index.queryScope, direction: fieldDirection(index) };
+        // Not the rendered `scope:direction`, which is not injective — nothing forbids `:` in either
+        // part. `JSON.stringify` over the pair is, without an assumption about the vocabulary.
+        const identity = JSON.stringify([entry.queryScope, entry.direction]);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        canonical.push(entry);
+    }
+    return canonical.sort((a, b) => compareStrings(a.queryScope, b.queryScope) || compareStrings(a.direction, b.direction));
+}
+/**
+ * The counterpart of `analyse` for the document's other half. An absent `fieldOverrides` is an
+ * empty set, which is what a hand-written file without the key means.
+ */
+export function analyseOverrides(document) {
+    return (document.fieldOverrides ?? []).map((source, position) => analyseOverride(source, position));
+}
+function analyseOverride(source, position) {
+    const indexes = canonicalSingleFieldIndexes(source.indexes);
+    return {
+        source,
+        position,
+        collectionGroup: source.collectionGroup,
+        fieldPath: source.fieldPath,
+        indexes,
+        key: overrideKey(source.collectionGroup, source.fieldPath, indexes),
+    };
+}
 function analyseIndex(source, position) {
     const { fields, redundantNameDirection } = canonicalFields(source.fields);
     return {

package/dist/key.js.map

@@ -1 +1 @@
-{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC;IACxD,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,WAAW,CAAC;IACpE,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QAClD,OAAO,UAAU,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IACtE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA6B;IACjE,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;QAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IAC9C,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAA6B;IAC3D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,IAAI,IAAI,IAAI,CAAC,SAAS,KAAK,UAAU,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,KAAK,KAAK,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,sBAAsB,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACpF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,sBAAsB,EAAE,IAAI,EAAE,CAAC;AAChF,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAiB;IACzC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAqB;IAC/C,OAAO,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,eAAuB,EACvB,UAAkB,EAClB,MAAiC;IAEjC,OAAO,GAAG,eAAe,KAAK,UAAU,KAAK,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,OAAO,CAAC,QAAuB;IAC7C,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,SAAS,YAAY,CAAC,MAAsB,EAAE,QAAgB;IAC5D,MAAM,EAAE,MAAM,EAAE,sBAAsB,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1E,OAAO;QACL,MAAM;QACN,QAAQ;QACR,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM;QACN,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;QAChE,sBAAsB;KACvB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"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"}

package/dist/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,aAAa,EAAc,MAAM,YAAY,CAAC;AAE5E;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAyB;CAChD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAUzD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAa5D"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAyB;CAChD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAUzD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA4B5D"}

package/dist/parse.js

@@ -29,7 +29,19 @@ export function validateDocument(raw) {
         throw new MalformedInputError('"indexes" must be an array');
     }
     const validated = indexes.map((entry, i) => validateIndex(entry, `indexes[${i}]`));
-    return { ...raw, indexes: validated };
+    // Optional, because a hand-written file usually has none and the Firebase CLI omits the key when
+    // an export has none. Present, it is validated to the same depth as `indexes`: an override this
+    // tool cannot read is one it would otherwise pass through *as* read, and the consumer that
+    // reconciles it against a live listing would then vouch for a field it never examined (#53).
+    const overrides = raw['fieldOverrides'];
+    if (overrides === undefined) {
+        return { ...raw, indexes: validated };
+    }
+    if (!Array.isArray(overrides)) {
+        throw new MalformedInputError('"fieldOverrides" must be an array');
+    }
+    const validatedOverrides = overrides.map((entry, i) => validateOverride(entry, `fieldOverrides[${i}]`));
+    return { ...raw, indexes: validated, fieldOverrides: validatedOverrides };
 }
 function validateIndex(raw, path) {
     if (!isObject(raw)) {
@@ -55,6 +67,48 @@ function validateField(raw, path) {
         throw new MalformedInputError(`${path}: must be an object`);
     }
     const fieldPath = requireString(raw['fieldPath'], `${path}: "fieldPath"`);
+    validateConfig(raw, path);
+    return { ...raw, fieldPath };
+}
+function validateOverride(raw, path) {
+    if (!isObject(raw)) {
+        throw new MalformedInputError(`${path}: must be an object`);
+    }
+    const collectionGroup = requireString(raw['collectionGroup'], `${path}: "collectionGroup"`);
+    const fieldPath = requireString(raw['fieldPath'], `${path}: "fieldPath"`);
+    // Empty is not the error it is for a composite index: an override declaring no indexes is an
+    // exemption, which is a configuration Firestore holds and an export writes out.
+    const indexes = raw['indexes'];
+    if (!Array.isArray(indexes)) {
+        throw new MalformedInputError(`${path}: "indexes" must be an array`);
+    }
+    const validatedIndexes = indexes.map((entry, i) => validateSingleFieldIndex(entry, `${path}.indexes[${i}]`));
+    // Checked for type only. Whether the field has a TTL policy is not something a canonical form
+    // reads, but a value that is not a boolean is not a TTL declaration the Firebase CLI would write.
+    if (raw['ttl'] !== undefined && typeof raw['ttl'] !== 'boolean') {
+        throw new MalformedInputError(`${path}: "ttl" must be a boolean`);
+    }
+    return { ...raw, collectionGroup, fieldPath, indexes: validatedIndexes };
+}
+function validateSingleFieldIndex(raw, path) {
+    if (!isObject(raw)) {
+        throw new MalformedInputError(`${path}: must be an object`);
+    }
+    // Absent, the scope is `COLLECTION`: the Firebase CLI's validator checks `queryScope` only when
+    // it is present and its own exports always write it, so an omission is a hand-written file, and
+    // `COLLECTION` is the default the CLI itself supplies when it upgrades an old-format composite
+    // index. A present value is still held to a string.
+    const queryScope = raw['queryScope'] === undefined
+        ? 'COLLECTION'
+        : requireString(raw['queryScope'], `${path}: "queryScope"`);
+    validateConfig(raw, path);
+    return { ...raw, queryScope };
+}
+/**
+ * The one-of check a composite index's field and a single-field index share: exactly one of
+ * `order`, `arrayConfig`, and `vectorConfig`, each of the right type.
+ */
+function validateConfig(raw, path) {
     const configured = ['order', 'arrayConfig', 'vectorConfig'].filter((name) => raw[name] !== undefined);
     if (configured.length === 0) {
         throw new MalformedInputError(`${path}: needs one of "order", "arrayConfig", or "vectorConfig"`);
@@ -71,7 +125,6 @@ function validateField(raw, path) {
     if (raw['vectorConfig'] !== undefined && !isObject(raw['vectorConfig'])) {
         throw new MalformedInputError(`${path}: "vectorConfig" must be an object`);
     }
-    return { ...raw, fieldPath };
 }
 function requireString(value, label) {
     if (typeof value !== 'string') {

package/dist/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -23,10 +23,46 @@ export interface CompositeIndex {
     fields: IndexField[];
     [key: string]: unknown;
 }
+/**
+ * One entry of a field override's `indexes` array: a single-field index.
+ *
+ * The same three configs as `IndexField`, minus `fieldPath` — the override names the field once,
+ * above — plus the `queryScope` a composite index carries at the top level. A single-field index is
+ * one field, so the scope is the only thing that varies from entry to entry besides the direction.
+ */
+export interface SingleFieldIndex {
+    /**
+     * `COLLECTION` or `COLLECTION_GROUP` in practice; not validated against an enumeration. `parse.ts`
+     * fills in `COLLECTION` when the declaration omits it, as the Firebase CLI does.
+     */
+    queryScope: string;
+    order?: string;
+    arrayConfig?: string;
+    vectorConfig?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * One entry of the document's `fieldOverrides` array.
+ *
+ * Firestore indexes every field of every document by default; an override replaces that default
+ * for one field of one collection group with the set declared in `indexes`. The set is the *whole*
+ * configuration the field ends up with, not a delta — an export materialises the defaults an
+ * override keeps — and an empty set is an exemption: the field is not indexed at all.
+ *
+ * `ttl` is carried and not analysed. It decides when a document is deleted, not which queries are
+ * served, so nothing that reads a canonical form has a use for it.
+ */
+export interface FieldOverride {
+    collectionGroup: string;
+    fieldPath: string;
+    indexes: SingleFieldIndex[];
+    ttl?: boolean;
+    [key: string]: unknown;
+}
 /** A parsed and validated `firestore.indexes.json`. */
 export interface IndexDocument {
     indexes: CompositeIndex[];
-    fieldOverrides?: unknown[];
+    fieldOverrides?: FieldOverride[];
     [key: string]: unknown;
 }
 /** A field reduced to the two things the canonical key is built from. */
@@ -52,6 +88,33 @@ export interface AnalysedIndex {
      */
     readonly redundantNameDirection: string | null;
 }
+/** A single-field index reduced to the two things its canonical form is built from. */
+export interface CanonicalSingleFieldIndex {
+    queryScope: string;
+    /** `ASCENDING`, `DESCENDING`, `CONTAINS`, or `VECTOR(<dimension>)`. */
+    direction: string;
+}
+/**
+ * A field override with its canonical form precomputed, the counterpart of `AnalysedIndex`.
+ *
+ * Built by `analyseOverrides` and shared with `@indexwright/record`, which reconciles it against a
+ * live field listing; a rule reading `fieldOverrides` reads this rather than the source (issues #53
+ * and #54 ask for one model, not two).
+ */
+export interface AnalysedOverride {
+    /** The declaration as written, including any keys indexwright does not understand. */
+    readonly source: FieldOverride;
+    /** Position within the document's `fieldOverrides` array, for messages that need to point at one. */
+    readonly position: number;
+    readonly collectionGroup: string;
+    readonly fieldPath: string;
+    /**
+     * The declared set, in canonical order: sorted by query scope, then direction, with entries alike
+     * in both collapsed to one (`source.indexes` keeps them all). Empty for an exemption.
+     */
+    readonly indexes: readonly CanonicalSingleFieldIndex[];
+    readonly key: string;
+}
 export declare const RULE_IDS: readonly ["scope-mismatch", "field-order-variant", "explicit-name-field", "quota-headroom"];
 export type RuleId = (typeof RULE_IDS)[number];
 /** A single warning. Never an error: see SPEC §8. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsDH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,gBAAgB;IAChB,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;CACR,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyHH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,gBAAgB;IAChB,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;CACR,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indexwright",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Linter for Firestore composite index declarations (firestore.indexes.json)",
   "keywords": [
     "firestore",
@@ -10,18 +10,16 @@
     "linter",
     "static-analysis"
   ],
-  "homepage": "https://github.com/uny/indexwright#readme",
+  "homepage": "https://github.com/uny/indexwright/tree/main/packages/indexwright#readme",
   "bugs": "https://github.com/uny/indexwright/issues",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/uny/indexwright.git"
+    "url": "git+https://github.com/uny/indexwright.git",
+    "directory": "packages/indexwright"
   },
   "license": "Apache-2.0",
   "author": "Yuki Nagai",
   "type": "module",
-  "workspaces": [
-    "packages/*"
-  ],
   "bin": {
     "indexwright": "dist/cli.js"
   },
@@ -36,22 +34,18 @@
   "files": [
     "dist",
     "README.md",
-    "SPEC.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=22"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsc --build --force tsconfig.json packages/record/tsconfig.json",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p packages/record/tsconfig.json",
-    "test": "npm run build && node --test \"test/*.test.js\" \"packages/*/test/*.test.js\"",
-    "verify-package": "npm run build && node scripts/verify-package.mjs && node scripts/verify-record-package.mjs",
+    "build": "tsc --build --force",
+    "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.2",
-    "typescript": "^5.7.2"
   }
 }

package/SPEC.md

@@ -1,683 +0,0 @@
-# indexwright — Specification
-
-Linter and query-coverage checker for Firestore composite indexes.
-
-Status: **v0.2.0 (draft)**. Pre-1.0: rules and CLI surface may change between minor versions.
-
----
-
-## 1. Why this exists
-
-Firestore composite indexes are declared as data (`firestore.indexes.json`) and applied as
-whole-state. Three properties of the platform make that declaration hard to get right, and none of
-them are addressed by existing tooling.
-
-**The emulator does not enforce composite indexes.** The Firestore emulator "does not track
-composite indexes and instead executes any valid query." A query that will fail in production with
-`FAILED_PRECONDITION` passes locally. Strict indexing in the emulator is not a planned feature.
-
-**Firestore exposes no per-index usage metrics.** Index entry reads are billed but do not appear in
-the usage dashboard, and there is no index-level metric. You cannot ask the platform which of your
-indexes are actually used, so you cannot safely identify unused ones.
-
-**The index-matching rule is undocumented.** Google's documentation states that field ordering must
-be specified, but does not define how field order maps to query shape — in particular whether the
-relative order of equality and `array-contains` fields before the range fields affects matching.
-This means index changes cannot be validated against documentation; only empirically.
-
-The asymmetry is stark: security rules have an official test harness
-(`@firebase/rules-unit-testing`) and can be verified in the emulator. **Composite indexes have no
-equivalent.** A survey of GitHub and npm found no linter for `firestore.indexes.json`; the only
-adjacent projects are three abandoned index *generators* (0–6 stars, last pushed 2021–2025).
-
-Consequently, index declarations drift into states that are detectable by inspection but that
-nothing inspects: inconsistent `queryScope` within a collection, near-duplicate indexes that differ
-only in field order, artifacts of round-tripping through live exports, and silent approach to the
-per-database index quota.
-
-## 2. What this is not
-
-**indexwright cannot determine whether an index is needed.** That question requires the queries,
-which live in application code, not in the index declaration. No rule in this specification asserts
-that an index is unnecessary, and no output should be read as authorising a deletion.
-
-Deleting a composite index is not symmetric with adding one: an addition does not disturb existing
-queries while it backfills, but a deletion breaks its queries the moment it takes effect, and
-restoring it requires a fresh backfill. **A linter that only sees the declaration must never be the
-basis for a deletion.**
-
-What indexwright asserts is narrower and safer: *these declarations are structurally inconsistent
-with each other, and a human should look.*
-
-## 3. Scope
-
-### v0.1.0
-
-Static analysis of index declaration files. Four rules (§5). No network access, no credentials, no
-Firestore connection.
-
-### Planned
-
-- **v0.2 — query capture.** The Firestore emulator speaks the public Firestore v1 gRPC API in
-  plaintext on a local port. An intercepting proxy can decode `RunQuery` requests and record the
-  observed `StructuredQuery` shapes, yielding a query corpus harvested from execution rather than
-  hand-written. This is independent of language and framework, because it operates on the wire
-  protocol rather than on source code — but not of transport: the emulator also serves the Firebase
-  Web SDK over WebChannel rather than gRPC, and a suite driven from a browser does not pass through
-  a gRPC proxy at all. v0.2 captures the gRPC transport, which is what server-side SDKs use. The
-  corpus format is specified in §7.
-- **v0.3 — coverage check.** Replay a captured corpus against a throwaway Firestore database that
-  has the candidate index set applied, and report queries that fail with `FAILED_PRECONDITION`.
-  The oracle is Firestore itself; indexwright does not reimplement the undocumented matching rule.
-
-The v0.2/v0.3 split is deliberate: capture is cheap and offline, while the coverage decision is
-delegated to the platform. Reimplementing index matching would risk emitting false
-`FAILED_PRECONDITION` verdicts and blocking development on a rule that is not published.
-
-**Packaging of v0.2/v0.3.** `record` and `check` run inside an adopter's project, so whatever they
-depend on lands in an adopter's tree, and the build-time carve-out of §8 does not reach them. They
-ship as a separate package, `@indexwright/record`. **`indexwright` itself acquires no runtime
-dependency, in any version.**
-
-The cost being separated is `check`'s, not `record`'s. Replay executes captured shapes against a
-real database and reads the status Firestore answers with, which means a Firestore client — the
-thing §8 exists to keep out of a linter that runs on every push, in every CI job, in projects that
-may never touch Firestore from a server. `check` runs where a project is already talking to
-Firestore server-side and has already resolved that client transitively. The dependency is added
-where it is very likely already resolved, and is absent where it would be new.
-
-Capture turned out not to need one. An earlier draft of this section justified the split with a
-gRPC stack for `record` too — `@grpc/grpc-js` and protobuf definitions for the Firestore v1 API, on
-the grounds that hand-writing a decoder for a wire format owned by someone else is not a cost worth
-paying. Neither half held. `@grpc/grpc-js` implements clients and servers for services known at
-build time; a transparent proxy is `node:http2` and raw frames, and grpc-js has no part in it. And
-§7 fixes a closed operator vocabulary and requires an unrecognised enum value to be counted rather
-than named, so the enum table has to exist in-tree whichever library reads the bytes — what a
-protobuf runtime would add on top of it is varint and length-delimited parsing over field numbers
-that a released `.proto` cannot renumber. `@indexwright/record` v0.2 therefore declares no runtime
-dependency either, and takes one when `check` arrives.
-
-It does not depend on `indexwright` yet. Capture reads no index declarations, so the index model
-and the `json` contract are `check`'s needs rather than `record`'s. Declaring the dependency early
-would put a package in an adopter's tree that nothing imports.
-
-The cost is a second package to discover. `indexwright record` in an installation that has only the
-linter must say where the verb lives, not report an unknown command.
-
-**Known limit of v0.2/v0.3:** coverage is bounded by what actually exercises the proxy. A query that
-no test issues is not observed, and absence of observation is not evidence that an index is unused.
-That much is inherent. Two further gaps are not, and are implementation gaps v0.2 ships with: a
-suite driven through the Firebase Web SDK does not reach a gRPC proxy at all, and a query issued as
-a snapshot listener travels by `Listen` rather than `RunQuery` and is counted rather than recorded
-(§7). Both narrow what a corpus covers without narrowing what it appears to cover, which is why §7
-counts them out loud.
-
-## 4. CLI
-
-```
-indexwright lint <file...> [options]
-
-Options:
-  --format <fmt>        text (default) | json | github
-  --max-warnings <n>    exit 1 if warnings exceed n (default: unlimited → always exit 0)
-  --rule <id>           run only the given rule; repeatable
-  --disable <id>        skip the given rule; repeatable
-  --quota <n>           per-database composite index limit for R4 (default: 1000)
-  --quota-threshold <p> warn above this fraction of the limit (default: 0.8)
-```
-
-### Exit codes
-
-| Code | Meaning |
-|-----:|:--------|
-| 0 | Completed. Warnings may have been emitted (default policy). |
-| 1 | Warning count exceeded `--max-warnings`. |
-| 2 | Usage error, unreadable file, or malformed input. |
-
-**The default is exit 0 even with findings.** A linter whose rules have unmeasured false-positive
-rates must not gate a pipeline by default. Adopters opt into enforcement with `--max-warnings`
-once they have measured their own noise level.
-
-### Input
-
-Any file in the `firestore.indexes.json` shape:
-
-```jsonc
-{
-  "indexes": [
-    {
-      "collectionGroup": "…",
-      "queryScope": "COLLECTION" | "COLLECTION_GROUP",
-      "fields": [ { "fieldPath": "…", "order": "ASCENDING" | "DESCENDING" }
-                | { "fieldPath": "…", "arrayConfig": "CONTAINS" }
-                | { "fieldPath": "…", "vectorConfig": { … } } ],
-      "density": "…"          // optional, passed through
-    }
-  ],
-  "fieldOverrides": [ … ]     // parsed, not analysed in v0.1.0
-}
-```
-
-Multiple files may be passed; each is analysed independently. Rules are not applied across files.
-
-### Validation
-
-A file is **malformed** when it is not valid JSON, when the top level is not an object, when
-`indexes` is absent or is not an array, when an index lacks `collectionGroup`, `queryScope`, or a
-non-empty `fields`, or when a field lacks `fieldPath` or declares none — or more than one — of
-`order`, `arrayConfig`, and `vectorConfig`.
-
-Nothing beyond that is refused. The *values* of `queryScope` and `order` are not checked against an
-enumeration, unknown keys anywhere are ignored, and a declaration that repeats a `fieldPath` within
-one index — which does occur in live exports — is carried through rather than rejected. Refusing to
-analyse a file is the harshest outcome available to a tool that otherwise only warns, and it costs
-the reader every other index in the file, so it is reserved for input that cannot be read as an
-index declaration at all.
-
-Malformed input does not abort the run. Each file is read and analysed on its own: files that parse
-are linted and their findings reported, files that do not are reported as errors, and the process
-exits 2 once every file has been handled. Reporting only the first bad file would hide findings in
-the files that were fine.
-
-## 5. Rules
-
-Every rule emits **warnings**, never errors. Each finding carries: rule id, file, a canonical index
-key, and a one-line reason. A finding that concerns the file as a whole rather than any particular
-index carries a **null** key.
-
-A rule whose subject is a *set* of indexes emits one grouped finding for that set, not one finding
-per member. The finding's `key` is the lexicographically smallest member key and `related` holds the
-remaining member keys, sorted ascending and de-duplicated. This keeps the warning count proportional
-to the number of problems rather than to the number of indexes, which matters because
-`--max-warnings` is counted in findings.
-
-### Canonical index key
-
-```
-<collectionGroup>::<queryScope>::<fieldPath>:<direction>|<fieldPath>:<direction>|…
-```
-
-where `direction` is `ASCENDING`, `DESCENDING`, `CONTAINS`, or — for a `vectorConfig` field —
-`VECTOR(<dimension>)`, written `VECTOR(?)` when no dimension is declared. A trailing implicit
-`__name__` entry is stripped before forming the key, so that declarations that differ only in
-whether the document key is written explicitly resolve to the same resource.
-
-### The implicit `__name__` direction
-
-Firestore appends the document key to every composite index, and its direction is not declared, so
-stripping it requires knowing which direction it would have had. indexwright defines that direction
-as **the `order` of the last preceding field that carries an `order`, or `ASCENDING` when no
-preceding field carries one** — the latter arising when the index ends with an `arrayConfig` field.
-
-This is not published behaviour. It is read off live exports, which render the key explicitly:
-`[type ASC, createdAt DESC, __name__ DESC]`, `[public ASC, startAt ASC, __name__ ASC]`, and
-`[isRecommended ASC, tags CONTAINS, __name__ ASC]` are all shapes an export produces.
-
-The definition is used only to decide whether a written `__name__` is redundant, and the decision is
-deliberately one-sided: a trailing `__name__` is stripped **only** when its direction equals the
-value above, and one that differs — `[totalNbUses DESC, __name__ ASC]` occurs in real exports — is
-treated as meaningful and kept. A wrong definition can therefore fail to merge two spellings of one
-index, but can never merge two indexes that are actually distinct.
-
----
-
-### R1 · `scope-mismatch`
-
-**Detects.** Within one `collectionGroup`, more than one distinct `queryScope` is declared. One
-finding is emitted per affected `collectionGroup`, reporting how many indexes each scope holds.
-
-The scope with the fewest indexes is named as the minority, and the finding's keys are that scope's
-indexes. When no scope holds a strict minority — an even split — the finding says so instead of
-naming one, and reports the keys of the lexicographically first scope. It still fires: the detection
-condition is that the scopes disagree, and an even split is a disagreement. Suppressing it would
-narrow the rule to a shape the rule does not claim.
-
-**Rationale.** A `COLLECTION`-scoped index does not serve a collection-group query, and vice versa.
-When every other index on a collection uses one scope and a newly added one uses the other, the new
-declaration is frequently a mistake that will surface only as a production `FAILED_PRECONDITION`.
-
-**False positives.** Legitimate when an application queries the same collection both as a single
-collection and as a collection group. This is why the rule warns rather than fails.
-
----
-
-### R2 · `field-order-variant`
-
-**Detects.** Two or more indexes that share `collectionGroup`, `queryScope`, and the same *set* of
-`fieldPath:direction` pairs, but declare them in different orders.
-
-"Same set" means the same *multiset*: a `fieldPath` that repeats within one index is unusual but not
-rejected (§4), and comparing multisets keeps the grouping well defined when it does. The comparison
-runs on the canonicalised field list, so an index that writes `__name__` explicitly groups with one
-that does not. Two indexes that are byte-identical do not constitute different orders and do not
-fire this rule.
-
-**Rationale.** Firestore treats a different field order as a different index. Each variant consumes
-write amplification, storage, and quota independently. Variants proliferate easily: a query change
-that reorders fields adds a new index without removing the old one, and round-tripping through a
-live export can reintroduce an ordering that was intended to be replaced.
-
-**False positives.** Legitimate when distinct queries genuinely require distinct orderings — for
-example, two queries that order by the same two fields in opposite directions. The finding asks for
-that justification to be recorded, not for one variant to be removed.
-
-**Output.** All members of the variant group are listed together, so the reader can judge the set
-rather than one member at a time.
-
----
-
-### R3 · `explicit-name-field`
-
-**Detects.** An index whose **last** `fields` entry is an explicit `__name__` carrying the implicit
-default direction (§5, *The implicit `__name__` direction*). A `__name__` written anywhere other
-than last, or written last with a direction other than the default, is not flagged.
-
-**Rationale.** Firestore appends the document key implicitly; live exports render it explicitly.
-An explicit `__name__` in a hand-maintained declaration is therefore a signature of a value that
-round-tripped through an export rather than being authored directly. It does not change the
-resource identity, but it makes the file inconsistent and can mask genuine duplicates from
-naive text comparison.
-
-**False positives.** Explicit `__name__` with a direction that differs from the implicit default is
-meaningful and should not be flagged. The rule only fires on a trailing `__name__` matching the
-implicit default.
-
----
-
-### R4 · `quota-headroom`
-
-**Detects.** The number of composite indexes in the file exceeds `--quota-threshold` of `--quota`.
-
-**Rationale.** Composite indexes are capped per database. The limit is reached gradually and
-silently; the first symptom is a failed index creation at deploy time, which is a poor moment to
-discover it. Reporting headroom continuously makes the trend visible.
-
-The comparison is a strict `count > quota × threshold`, so the defaults (1000, 0.8) fire at 801.
-
-**False positives.** None in principle; the threshold is configurable because appropriate headroom
-depends on the rate of index growth.
-
-**Output.** The finding is about the file, not about any one index, so its `key` is `null` and its
-`related` is empty. One finding per file at most.
-
-## 6. Output formats
-
-**`text`** — human-readable, grouped by rule, intended for a terminal.
-
-**`json`** — a stable machine-readable shape:
-
-```jsonc
-{
-  "version": "0.1.0",
-  "files": ["…"],
-  "summary": { "warnings": 0, "errors": 0, "byRule": { "scope-mismatch": 0, … } },
-  "findings": [
-    {
-      "rule": "scope-mismatch",
-      "file": "…",
-      "key": "…",             // null for a finding about the file as a whole
-      "message": "…",
-      "related": ["…"]        // other keys in the same finding group; [] when there are none
-    }
-  ],
-  "errors": [
-    { "file": "…", "message": "…" }   // files that could not be read or parsed
-  ]
-}
-```
-
-`files` lists every file the run was given, whether or not it parsed, sorted by path. `byRule` holds
-one entry for every rule that ran after `--rule` and `--disable` were applied, including rules that
-found nothing; a rule that did not run is absent rather than zero. `findings` is sorted by file,
-then by rule in the order of §5, then by key with a null key sorting first. `related` is sorted
-ascending. `errors` is sorted by file. Every field is always present: `related` is `[]` rather than
-omitted, and `errors` is `[]` on a clean run.
-
-**`github`** — GitHub Actions workflow commands (`::warning file=…::`) plus a Markdown summary
-suitable for `$GITHUB_STEP_SUMMARY`.
-
-## 7. Query corpus (v0.2)
-
-`record` writes a **query corpus**: the set of distinct query shapes observed on the emulator's wire
-during a run, conventionally `firestore.queries.json`. The corpus is the contract between capture
-(v0.2) and the coverage check (v0.3), and it is meant to be committed alongside
-`firestore.indexes.json` and reviewed in a diff like any other declaration.
-
-A query enters the corpus when its request is observed, whatever the server answers next. One that
-failed still describes something the application issues — and a query that failed *because an index
-was missing* is precisely the case v0.3 exists to find, so waiting for a successful status would
-drop the most interesting entries in the file.
-
-`record` writes the corpus whole, replacing whatever was there, and writes it atomically so that an
-interrupted run leaves the previous file intact rather than a truncated one. Replacing rather than
-merging is the honest reading: a corpus is evidence of what one run exercised, and a run that
-executed three tests did not exercise the other two hundred. The cost is that a filtered or aborted
-run produces a diff that deletes query shapes which still exist — which is a visible deletion a
-reviewer can question, where a merge would have produced a file that silently outlives the tests
-that justified it.
-
-### What a shape is
-
-A shape is the part of a `StructuredQuery` that determines which index can serve it: the collection,
-the query scope, the filter tree, and the sort order. Everything else is discarded.
-
-**Values are not recorded.** A query's values are customer data, and the corpus is a file that
-persists in a repository. They are also unnecessary: index selection is a function of field paths,
-operators, and directions, not of what is compared against. Discarding them removes the part of a
-captured query most likely to carry a secret, and the only part that changes between runs of the
-same test.
-
-It does not make the corpus non-sensitive, and nothing here should be read as saying so. Field paths
-are recorded verbatim, and a field path is not always static: `members.alice@example.com` is an
-ordinary way to query a map, and it is at once a real identifier and a corpus entry that will never
-recur. Collection ids carry schema and sometimes tenancy. A corpus describes an application's data
-model, and it earns the access controls of the repository it is committed to — it does not become
-publishable by having had its values stripped.
-
-**Project and database are not recorded.** They are properties of the environment the capture ran
-in, not of the query, and recording them would make a corpus captured against one emulator instance
-look different from the same corpus captured against another.
-
-**`limit`, `offset`, cursors, and `select` are not recorded.** None of them changes which index
-serves the query; a projection is served by the index the underlying query already needs.
-
-**Occurrence counts are not recorded.** A corpus is a set, not a histogram. A count changes on every
-run without changing anything about what must be indexed, which would make the file churn in every
-diff and train reviewers to skim it. `record` reports counts on stderr, where they are useful for
-triage and where they do not have to be committed.
-
-### Vocabulary
-
-The corpus reuses the declaration vocabulary of §5, so that a corpus entry and an index key can be
-read against each other with one translation, which the table below states in full: an
-`ARRAY_CONTAINS` filter is served by a field declared `arrayConfig: CONTAINS`.
-
-| Corpus | Source on the wire | Aligns with |
-|:--|:--|:--|
-| `collectionGroup` | `CollectionSelector.collection_id` | index `collectionGroup` |
-| `queryScope` — `COLLECTION` \| `COLLECTION_GROUP` | `all_descendants` | index `queryScope` |
-| `direction` — `ASCENDING` \| `DESCENDING` | `Order.direction` | field `order` |
-| `op` — `ARRAY_CONTAINS` | `FieldFilter.Operator` | field `arrayConfig: CONTAINS` |
-
-Operators are written with their protobuf enum names: `LESS_THAN`, `LESS_THAN_OR_EQUAL`,
-`GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `EQUAL`, `NOT_EQUAL`, `ARRAY_CONTAINS`, `IN`,
-`ARRAY_CONTAINS_ANY`, `NOT_IN` for a field filter; `IS_NAN`, `IS_NULL`, `IS_NOT_NAN`, `IS_NOT_NULL`
-for a unary filter; `AND` and `OR` for a composite. Enum names rather than SDK spellings, for the
-same reason §5 writes `ASCENDING` rather than `asc`: the file speaks Firestore's own vocabulary, so
-an entry can be read against a wire capture without a lookup table in between. The list is closed —
-an operator outside it is not written into the corpus under a name of indexwright's invention, and
-protobuf would hand it over as a bare number anyway. It is counted instead, as below.
-
-**A published default is applied; an unpublished one is not guessed at.** Every one of these enums
-has a zero value, and the two cases are not alike. `Order.direction` is documented to default to
-`ASCENDING`, so an `Order` that arrives as `DIRECTION_UNSPECIFIED` is recorded as `ASCENDING` —
-that is Firestore's own statement of what the value means, not indexwright's guess, and skipping the
-query instead would drop a real index requirement on the strength of a field the client simply left
-at its default. `OPERATOR_UNSPECIFIED`, an operator added after this specification was written, and
-any other value the vocabulary above cannot name have no such published meaning: the query is
-skipped and counted rather than guessed at. `StructuredQuery.from` is a repeated field, and the same
-line applies — an entry holds exactly one `collectionGroup`, so a query that does not carry exactly
-one selector with a non-empty `collection_id` is skipped, because the corpus has no way to say what
-it means rather than because its meaning is unknown.
-
-### Canonical query key
-
-```
-<collectionGroup>::<queryScope>::<where>::<orderBy>
-```
-
-`<where>` serialises the filter tree: a field or unary filter as `<fieldPath>:<op>`, a composite as
-`<op>(<child>|<child>|…)`. The root is always a composite — `StructuredQuery.where` may be a bare
-field or unary filter, and is then wrapped in an `AND` — so a query with one filter serialises as
-`AND(status:EQUAL)` and a query with none as `AND()`. A root that is already a composite keeps its
-own operator: a top-level `OR` is `OR(…)`, never `AND(OR(…))`. `<orderBy>` is
-`<fieldPath>:<direction>` joined by `|`, and is empty when the query declares no sort order. A
-two-filter, two-sort query keys as:
-
-```
-orders::COLLECTION::AND(amount:GREATER_THAN|status:EQUAL)::amount:DESCENDING|createdAt:ASCENDING
-```
-
-`<collectionGroup>` and `<fieldPath>` are escaped before they are joined: a backslash becomes `\\`,
-each of `:`, `|`, `(`, `)` is prefixed with one, and every character below `U+0020` becomes `\uXXXX`.
-Enum names need no escaping but are subject to the same rule, so that decoding is uniform. The
-control-character clause is not about ambiguity but about §6's requirement that a value read off an
-untrusted input cannot forge a line of output: a key holding a raw newline would end the line it was
-printed on.
-
-Escaping is what makes the key injective, and the key is what entries are de-duplicated on. A field
-path may hold any of these characters — Firestore quotes a path in backticks precisely so that it
-can — and unescaped, one path spelled `` `a:EQUAL|b` `` serialises identically to two filters on `a`
-and `b`. Two distinct queries would then share an entry and only one of them would ever be replayed,
-which is the failure this section closes on: not a gap in coverage but a gap that looks like
-coverage.
-
-Both `AND` and `OR` are commutative, so a composite's children are sorted by their own serialised
-form, compared by Unicode code point, before joining. This makes the key independent of the order
-the filters were written in, which is what allows two spellings of one query to collapse into one
-corpus entry. A composite child carrying the same operator as its parent is flattened into it, since
-`AND(a|AND(b|c))` and `AND(a|b|c)` are one query; nesting under a *different* operator is meaningful
-and is kept. Sort order is *not* commutative and is preserved as sent.
-
-Repeated children are kept rather than de-duplicated, for the reason §5 compares multisets:
-`tier == "a" OR tier == "b"` is a two-disjunct query whose shape is `OR(tier:EQUAL|tier:EQUAL)`, and
-collapsing it to one disjunct would describe a query that was never issued.
-
-### File shape
-
-```jsonc
-{
-  "corpusVersion": 1,
-  "queries": [
-    {
-      "key": "orders::COLLECTION::AND(status:EQUAL)::createdAt:DESCENDING",
-      "collectionGroup": "orders",
-      "queryScope": "COLLECTION",
-      "where": {
-        "op": "AND",
-        "filters": [
-          { "fieldPath": "status", "op": "EQUAL" }
-        ]
-      },
-      "orderBy": [
-        { "fieldPath": "createdAt", "direction": "DESCENDING" }
-      ]
-    }
-  ],
-  "skipped": ["aggregation-query"]
-}
-```
-
-A node carrying `filters` is a composite; a node carrying `fieldPath` is a leaf; no node carries
-both, and none carries neither. Every field is always present, as in §6: `where` is a composite even
-when the query filtered nothing, `orderBy` is `[]` rather than omitted, and `skipped` is `[]` on a
-run that discarded nothing. `queries` is sorted by `key` and `skipped` holds the distinct reasons
-observed, sorted ascending — a set, so that it is as diff-stable as the rest of the file. Both sorts
-compare by Unicode code point. Counts for each reason go to stderr.
-
-The stored `where` is the normalised tree the key was computed from, not the tree as it arrived:
-children sorted, same-operator composites flattened, exactly as *Canonical query key* describes. Two
-recorders that observe the same query in different spellings therefore write the same bytes, which
-they would not if the key were normalised and the tree left as sent — the entry that happened to
-win de-duplication would decide the file.
-
-`key` is derived from the four fields beneath it and carries nothing they do not: it is there so
-that entries can be sorted, de-duplicated, and cited in a review without re-serialising the tree. It
-is unique within `queries`. A reader handed an entry that breaks any of this — a `key` disagreeing
-with its own tree, a node that is both leaf and composite, a member the format does not define —
-refuses the file rather than repairing it, because the readings it would be choosing between are
-different queries and picking one is how a corpus comes to describe coverage it never had.
-
-`corpusVersion` is an integer that names the format, not the tool: it changes only when a corpus
-written by one version can no longer be read correctly by another, and it does not move when
-`@indexwright/record` is released. A reader handed a `corpusVersion` it does not know refuses the
-file and says so. It does not fall back to reading what it recognises, which would silently mis-read
-exactly the change the integer exists to announce.
-
-### Implicit fields are not materialised
-
-Firestore appends the document key to every query's sort order, and promotes an inequality field
-into it. `record` neither adds those fields nor removes them: the corpus records the sort order as
-sent.
-
-What is sent is not the same for every client. The Node server SDK serialises the orders the
-application wrote and leaves the rest to the server; the Firebase Web SDK normalises first, so a
-`where('age', '>', 18)` reaches the wire already carrying `age ASCENDING, __name__ ASCENDING`. One
-application query therefore has two legitimate corpus shapes depending on which SDK issued it, and
-a corpus is comparable across runs of one project rather than across projects. Recording what was
-sent is what keeps that difference visible; normalising in either direction would hide it behind a
-rule this specification would have had to invent.
-
-This is deliberate. §5 has to define the implicit `__name__` direction because a linter comparing
-two declarations has no other way to tell whether they name the same resource. A corpus has no such
-need: the v0.3 oracle is Firestore itself, which applies the real rule. Materialising a guessed
-`__name__` into the corpus would put an unpublished behaviour into a durable file and make every
-entry wrong if the guess were wrong. When a human reads a corpus entry against an index key, §5's
-definition is the one that applies.
-
-### Replay without values
-
-v0.3 must turn a corpus entry back into a query it can execute, and the entry has no values to put
-back. It synthesises them: a unary filter needs none, `IN`, `NOT_IN`, and `ARRAY_CONTAINS_ANY` need
-a one-element array, and everything else needs a single scalar. "Everything else" is a finite list
-rather than a default, because the vocabulary above enumerates the operators a corpus may hold and
-anything outside it was skipped at capture as `unsupported-shape`.
-
-Two shapes are not free-form and cannot be synthesised from the same rule. A `__name__` filter takes
-a document reference under the collection being queried, not a scalar, because Firestore validates
-the operand's type against the document key before it selects an index. And an entry whose root
-composite has no children replays with `where` omitted altogether, not as an empty `AND`: a wire
-`CompositeFilter` must carry at least one filter. Both would otherwise fail with `INVALID_ARGUMENT`,
-and an `INVALID_ARGUMENT` is not a `FAILED_PRECONDITION`. v0.3 reports the latter and never the
-former: a replay that comes back invalid is either a synthesis this section got wrong or a query
-that was already invalid when it was captured — the corpus admits those, since it records what was
-sent rather than what succeeded — and neither is a statement about the index set. Both are reported
-as un-replayable entries, which is a defect in the tooling or the test that issued them.
-
-This rests on the claim above — that index selection does not depend on the compared value or its
-type. The claim is consistent with how the field is indexed rather than the value, but it is not
-published, and it is the one assumption in v0.3 that a synthesised replay could get wrong. If it is
-false, replay reports `FAILED_PRECONDITION` where a real query would have succeeded, which is a
-false positive of exactly the kind §2 forbids acting on. v0.3 must test the claim before it reports.
-
-### What is not captured
-
-`record` captures `RunQuery`. Everything else the proxy sees, it counts under one of the reasons
-below and records nothing:
-
-- **`Listen`** — a snapshot listener carries its query in `Target.QueryTarget.structured_query` and
-  issues no `RunQuery` at all. Its index requirements are exactly those of the query it holds, so
-  this is the one omission that costs coverage rather than preventing a misreport: a suite whose
-  only exercise of a collection is `onSnapshot` yields a corpus with no entry for it. Counted as
-  `listen-query`, and named in §3 as a gap rather than an inherent limit. Capturing it is the first
-  extension worth making.
-- **`PartitionQuery`** — carries a `StructuredQuery` the same way, but as a bulk-read entry point
-  rather than an application query. Counted as `partition-query`.
-- **`RunAggregationQuery`** — `count()`, `sum()`, and `average()` carry a `StructuredQuery` and have
-  their own index requirements, which are not necessarily those of the underlying query. Recording
-  the inner query would misreport them, so v0.2 counts them as `aggregation-query`. Capturing them
-  properly is a v0.3-or-later extension.
-- **`find_nearest`** — vector search is counted as `vector-query` for the same reason: it is served
-  by a `vectorConfig` index whose matching rule this specification does not yet model.
-- **A shape the vocabulary cannot express** — an unrecognised or unspecified enum value, or a `from`
-  that does not name exactly one collection. Counted as `unsupported-shape`.
-- **A query-bearing RPC this specification does not model** — `ExecutePipeline` carries a
-  `StructuredPipeline` rather than a `StructuredQuery`, and pipelines are outside v0.2. Counted as
-  `unsupported-rpc`, so that `skipped: []` keeps meaning *nothing was declined* rather than *nothing
-  the proxy happened to recognise was declined*. The same reason covers any other method on the
-  Firestore service that is neither captured above nor on the list of methods known to carry no
-  query at all: a method added after this was written is counted, not assumed harmless.
-- **A message compressed with an encoding `record` cannot undo** — gRPC marks compression per
-  message and names the codec in `grpc-encoding`. `gzip` and `deflate` are undone and the message
-  read; anything else is counted as `unsupported-encoding`. A client that negotiates a codec this
-  package does not implement would otherwise have every query it sent vanish without trace.
-- **Bytes that do not parse** — a truncated frame, a body that ends mid-message, or a payload that
-  is not the message the method declares. Counted as `undecodable-message`. This is the one reason
-  that indicates a defect rather than a boundary: it should not occur against a conforming client,
-  and a corpus carrying it is reporting that something read the wire wrongly.
-
-`skipped` draws from that closed vocabulary and nothing else. No text decoded from the wire is ever
-interpolated into a reason: the corpus is committed, and a free-text field fed by intercepted
-traffic is a second way for data to reach the repository after values have been stripped from the
-first.
-
-They are reported rather than dropped silently. §3's known limit — that coverage is bounded by what
-exercises the proxy — is about queries no test issues; a query that *was* issued and then discarded
-without trace would be a different and worse failure, because it would look like coverage.
-
-## 8. Design principles
-
-**Warn, do not fail.** The rules encode heuristics whose false-positive rates are, at v0.1.0,
-unmeasured. Shipping them as blocking checks would teach users to suppress the tool. Enforcement is
-opt-in and per-adopter.
-
-**Never authorise a deletion.** See §2. No output phrasing may suggest that an index is unused or
-safe to remove.
-
-**No dependencies in `indexwright`.** A linter that pulls a dependency tree into a build pipeline
-undermines its own purpose. Argument parsing and formatting are implemented in-tree, and the
-published package declares no runtime dependencies. This is a property of the package rather than
-an aspiration of the project: it holds in every version, and a test asserts it.
-
-The principle is about what lands in an adopter's tree, so build- and test-time tooling that never
-ships is out of its scope. It is not a claim that no part of indexwright may depend on anything.
-Where a verb needs a library it cannot reasonably write — the Firestore client behind `check` (§3)
-— that verb ships as its own package instead of as a dependency of the linter. What the principle
-forbids is making every adopter of `lint` pay for it.
-
-`@indexwright/record` holds the line further than the principle requires: at v0.2 it declares no
-runtime dependency either, because capture turned out to need none (§3). That is not a promise it
-makes for every version, and `check` will end it.
-
-**No network, no credentials, in `lint`.** Static analysis must be runnable in any environment,
-including a sandboxed CI step with no cloud access. Network use is confined to the planned
-`record`/`check` verbs, which are separate commands in a separate package (§3).
-
-**Delegate undocumented semantics to the platform.** Where Firestore's behaviour is not published —
-principally index matching — indexwright measures rather than models. This bounds what the tool can
-claim, which is the point.
-
-**Deterministic output.** Findings are emitted in a stable sort order (file, rule, key), so that
-output can be diffed across runs.
-
-## 9. Testing
-
-Rules are tested against small hand-written fixtures that isolate one condition each, with explicit
-positive and negative cases.
-
-**Assertions are never written against a real project's index file.** A test that asserts a finding
-count over live data fails whenever that data legitimately changes, which trains maintainers to
-edit the test rather than read it. Fixtures encode the invariant; real files are for manual
-exploration only.
-
-## 10. Compatibility
-
-- Node.js ≥ 22, ESM.
-- Input schema follows the Firebase CLI's `firestore.indexes.json`. Unknown keys are preserved and
-  ignored rather than rejected, so that a newer field does not break linting.
-- Semantic versioning. Pre-1.0, rule additions and message changes may land in minor releases;
-  the `json` output shape is the stable contract and changes only in major releases after 1.0.
-- The package also exports a JavaScript API, so the rules can be run without spawning a process.
-  That API is **provisional**: it is not part of the stable contract before 1.0 and may change in
-  any minor release. Only the `json` output shape carries the compatibility promise.
-- indexwright is published as a family: `indexwright`, the linter, and — from v0.2 —
-  `@indexwright/record`, capture and coverage. Both carry no runtime dependencies at v0.2; `check`
-  will give the second one a Firestore client (§3). They version independently, and their version
-  numbers are not held in step: `@indexwright/record` 0.2.0 and `indexwright` 0.2.0 coincide only
-  because the family reached v0.2 together. When `check` lands and declares a range of
-  `indexwright` whose `json` contract it reads, that range is what ties them, not the numbers.
-- The query corpus (§7) is the second stable contract, and the only one that crosses a package
-  boundary as a file. It is versioned by its own `corpusVersion` rather than by either package's
-  release number, so a writer and a reader agree on the integer and not on each other's versions.
-  Everything else in `@indexwright/record` is provisional before 1.0 on the same terms as the
-  JavaScript API above.
-
-## 11. Toward 1.0
-
-1.0 requires, at minimum:
-
-- Measured false-positive rates for R1 and R2 across more than one real project.
-- At least one adopter outside the project of origin.
-- A decision, informed by that data, on whether any rule should default to failing.
-
-Until then the version stays below 1.0 and the README states plainly that the rules are provisional.