indexwright 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -5,7 +5,30 @@ 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.1.1] — unreleased
+## [0.2.0] — 2026-08-10
+
+### Added
+
+- A query corpus format, specified in [SPEC.md](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).
+- `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".
+
+### Changed
+
+- SPEC §3 no longer justifies the package split with a gRPC stack for capture. Capture needs none;
+  the split rests on v0.3's replay, which needs a Firestore client. Sections 7–10 shifted to 8–11
+  when the corpus format was inserted as §7.
+
+Nothing about the linter's rules, output, or exit codes changed in this release. `indexwright`
+still declares no runtime dependencies, and now so does `@indexwright/record`.
+
+## [0.1.1] — 2026-08-08
 
 No change to the published files: this release exists to exercise the publishing path itself.
 
@@ -30,5 +53,6 @@ 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.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

@@ -143,21 +143,22 @@ console.log(result.summary.byRule);
 
 ## Scope
 
-v0.1.0 is static analysis of declaration files only: no network access, no credentials, no Firestore
-connection.
-
-Planned, and deliberately split:
-
-- **v0.2 — query capture.** The emulator speaks the Firestore v1 gRPC API in plaintext on a local
-  port, so an intercepting proxy can record observed `StructuredQuery` shapes. This is language- and
-  framework-independent because it operates on the wire protocol.
+`indexwright lint` is static analysis of declaration files only: no network access, no credentials,
+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
+  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.
 - **v0.3 — coverage check.** Replay a captured corpus against a throwaway database with 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.
 
-Coverage will be 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.
+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.
 
 ## Toward 1.0
 
@@ -169,16 +170,22 @@ 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.
+
 ```bash
 npm install
-npm test                  # builds, then runs the suite against dist/
-npm run verify-package    # builds, packs, installs the tarball, exercises the bin and the API
+npm test                  # builds, then runs both suites against dist/
+npm run verify-package    # builds, packs, installs each tarball, exercises the bins and the APIs
 ```
 
 Both scripts build first as an explicit step rather than through a `pre` hook, because npm skips
 `pre`/`post` scripts entirely under `ignore-scripts=true` — a setting many developers turn on. With
 a hook, that configuration silently tests whatever `dist/` happened to be lying around.
 
+The packages version independently and release from separate tags: `v0.2.0` publishes the linter,
+`record-v0.2.0` publishes the recorder.
+
 ## License
 
 Apache-2.0

package/SPEC.md

@@ -2,7 +2,7 @@
 
 Linter and query-coverage checker for Firestore composite indexes.
 
-Status: **v0.1.0 (draft)**. Pre-1.0: rules and CLI surface may change between minor versions.
+Status: **v0.2.0 (draft)**. Pre-1.0: rules and CLI surface may change between minor versions.
 
 ---
 
@@ -61,8 +61,11 @@ Firestore connection.
 - **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 language- and framework-independent, because it operates on the wire
-  protocol rather than on source code.
+  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.
@@ -71,29 +74,43 @@ The v0.2/v0.3 split is deliberate: capture is cheap and offline, while the cover
 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.** Capture needs a gRPC stack — `@grpc/grpc-js` and protobuf definitions
-for the Firestore v1 API — and hand-writing a decoder for a wire format owned by someone else is
-not a cost worth paying. That collides with §7: `record` and `check` run inside an adopter's
-project, so their dependencies land in an adopter's tree, and the build-time carve-out does not
-reach them.
-
-They therefore ship as a separate package, `@indexwright/record`, which depends on `indexwright`
-for the index model and the `json` contract. **`indexwright` itself acquires no runtime dependency,
-in any version.**
-
-The split is not a workaround; it puts each cost where it is cheapest. `lint` runs on every push,
-in every CI job, in projects that may never touch Firestore from a server — that is where a
-transitive dependency tree is least welcome. `record` runs against a local emulator, in a project
-that is already talking to Firestore server-side and therefore already resolves `@grpc/grpc-js`
-transitively through `@google-cloud/firestore`. The dependency is added where it is very likely
-already resolved, and is absent where it would be new.
+**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.
-This limit is inherent, not an implementation gap.
+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
 
@@ -319,7 +336,276 @@ 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. Design principles
+## 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
@@ -335,10 +621,14 @@ 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 gRPC stack behind `record` (§3) —
-that verb ships as its own package instead of as a dependency of the linter. What the principle
+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).
@@ -350,7 +640,7 @@ 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.
 
-## 8. Testing
+## 9. Testing
 
 Rules are tested against small hand-written fixtures that isolate one condition each, with explicit
 positive and negative cases.
@@ -360,7 +650,7 @@ count over live data fails whenever that data legitimately changes, which trains
 edit the test rather than read it. Fixtures encode the invariant; real files are for manual
 exploration only.
 
-## 9. Compatibility
+## 10. Compatibility
 
 - Node.js ≥ 22, ESM.
 - Input schema follows the Firebase CLI's `firestore.indexes.json`. Unknown keys are preserved and
@@ -370,12 +660,19 @@ exploration only.
 - 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, which carries no runtime
-  dependencies, and — from v0.2 — `@indexwright/record`, capture and coverage, which depends on the
-  linter and on a gRPC stack (§3). They version independently; `@indexwright/record` declares the
-  range of `indexwright` whose `json` contract it reads.
-
-## 10. Toward 1.0
+- 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:
 

package/dist/args.d.ts

@@ -18,7 +18,7 @@ export type Command = LintCommand | {
     kind: 'version';
 };
 /**
- * Parsed in-tree rather than with a dependency (SPEC §7). Supports `--flag value` and
+ * Parsed in-tree rather than with a dependency (SPEC §8). Supports `--flag value` and
  * `--flag=value`, and `--` to end option parsing.
  */
 export declare function parseArgs(argv: readonly string[]): Command;

package/dist/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEvD,6EAA6E;AAC7E,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAI3E;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6E1D;AA+DD,wBAAgB,KAAK,IAAI,MAAM,CA0B9B"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEvD,6EAA6E;AAC7E,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAoB3E;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA2F1D;AA+DD,wBAAgB,KAAK,IAAI,MAAM,CA6B9B"}

package/dist/args.js

@@ -7,7 +7,17 @@ export class UsageError extends Error {
 }
 const FORMATS = ['text', 'json', 'github'];
 /**
- * Parsed in-tree rather than with a dependency (SPEC §7). Supports `--flag value` and
+ * Verbs that belong to the family but not to this package.
+ *
+ * `indexwright` carries no runtime dependency in any version (SPEC §8), so capture — which needs a
+ * proxy and a wire decoder — ships separately. Only verbs that exist are listed: pointing at a
+ * package that does not implement one yet would be a worse answer than not knowing.
+ */
+const ELSEWHERE = {
+    record: { home: '@indexwright/record', bin: 'indexwright-record' },
+};
+/**
+ * Parsed in-tree rather than with a dependency (SPEC §8). Supports `--flag value` and
  * `--flag=value`, and `--` to end option parsing.
  */
 export function parseArgs(argv) {
@@ -19,6 +29,18 @@ export function parseArgs(argv) {
         return { kind: 'version' };
     const [command, ...rest] = argv;
     if (command !== 'lint') {
+        // SPEC §3: the cost of splitting the family into two packages is a second package to
+        // discover, so a verb that lives in the other one has to say where it went. Reporting it as
+        // an unknown command would read as "indexwright cannot do this".
+        // An own-property lookup, not `in`: `ELSEWHERE` inherits from `Object.prototype`, so `in`
+        // also answers yes for `constructor` and `toString` and the message would then name the
+        // package as "undefined" instead of reporting an unknown command.
+        const elsewhere = Object.hasOwn(ELSEWHERE, command ?? '') ? ELSEWHERE[command] : undefined;
+        if (elsewhere !== undefined) {
+            const { home, bin } = elsewhere;
+            throw new UsageError(`"${command}" is not part of indexwright; it ships as ${home}. ` +
+                `Install it with "npm install --save-dev ${home}" and run "${bin}".`);
+        }
         throw new UsageError(`unknown command "${command}"; the only command is "lint"`);
     }
     const files = [];
@@ -165,6 +187,9 @@ export function usage() {
         '  0  completed; warnings may have been emitted',
         '  1  warning count exceeded --max-warnings',
         '  2  usage error, unreadable file, or malformed input',
+        '',
+        'Capturing the queries a test suite issues is a separate package, @indexwright/record,',
+        'so that this one keeps no runtime dependencies.',
     ].join('\n');
 }
 //# sourceMappingURL=args.js.map

package/dist/args.js.map

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

package/dist/collections.d.ts

@@ -1,4 +1,4 @@
-/** Small ordering and grouping helpers. Determinism is a stated requirement (SPEC §7). */
+/** Small ordering and grouping helpers. Determinism is a stated requirement (SPEC §8). */
 export declare function compareStrings(a: string, b: string): number;
 /** Group while remembering first-seen order, so callers can sort explicitly rather than by luck. */
 export declare function groupBy<T>(items: Iterable<T>, keyOf: (item: T) => string): Map<string, T[]>;

package/dist/collections.js

@@ -1,4 +1,4 @@
-/** Small ordering and grouping helpers. Determinism is a stated requirement (SPEC §7). */
+/** Small ordering and grouping helpers. Determinism is a stated requirement (SPEC §8). */
 export function compareStrings(a, b) {
     if (a < b)
         return -1;

package/dist/format/github.d.ts

@@ -7,7 +7,7 @@ export interface GithubOutput {
 }
 /**
  * Findings are annotations without a line number: locating a finding inside the JSON would need a
- * position-tracking parser, which v0.1.0 does not carry (SPEC §4).
+ * position-tracking parser, which v0.1.0 does not carry (SPEC §5).
  */
 export declare function formatGithub(result: LintResult): GithubOutput;
 //# sourceMappingURL=github.d.ts.map

package/dist/format/github.js

@@ -1,7 +1,7 @@
 import { oneLine } from './inline.js';
 /**
  * Findings are annotations without a line number: locating a finding inside the JSON would need a
- * position-tracking parser, which v0.1.0 does not carry (SPEC §4).
+ * position-tracking parser, which v0.1.0 does not carry (SPEC §5).
  */
 export function formatGithub(result) {
     const commands = [

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * The JavaScript API.
  *
- * Provisional before 1.0 (SPEC §9): only the `json` output shape carries the compatibility promise.
+ * Provisional before 1.0 (SPEC §10): only the `json` output shape carries the compatibility promise.
  * This exists so the rules can be run without spawning a process — from a test, a codemod, or a
  * bespoke reporter.
  */

package/dist/index.js

@@ -1,7 +1,7 @@
 /**
  * The JavaScript API.
  *
- * Provisional before 1.0 (SPEC §9): only the `json` output shape carries the compatibility promise.
+ * Provisional before 1.0 (SPEC §10): only the `json` output shape carries the compatibility promise.
  * This exists so the rules can be run without spawning a process — from a test, a codemod, or a
  * bespoke reporter.
  */

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  *
  * The input types mirror `firestore.indexes.json` loosely on purpose: unknown keys are carried
  * through rather than rejected, so a field added by a future Firebase release does not break
- * linting (SPEC §9).
+ * linting (SPEC §10).
  */
 /** One entry of an index's `fields` array. */
 export interface IndexField {
@@ -54,7 +54,7 @@ export interface AnalysedIndex {
 }
 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 §7. */
+/** A single warning. Never an error: see SPEC §8. */
 export interface Finding {
     rule: RuleId;
     file: string;

package/dist/types.js

@@ -3,7 +3,7 @@
  *
  * The input types mirror `firestore.indexes.json` loosely on purpose: unknown keys are carried
  * through rather than rejected, so a field added by a future Firebase release does not break
- * linting (SPEC §9).
+ * linting (SPEC §10).
  */
 export const RULE_IDS = [
     'scope-mismatch',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indexwright",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Linter for Firestore composite index declarations (firestore.indexes.json)",
   "keywords": [
     "firestore",
@@ -19,6 +19,9 @@
   "license": "Apache-2.0",
   "author": "Yuki Nagai",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "bin": {
     "indexwright": "dist/cli.js"
   },
@@ -41,10 +44,10 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc --build --force",
-    "typecheck": "tsc --noEmit",
-    "test": "npm run build && node --test \"test/*.test.js\"",
-    "verify-package": "npm run build && node scripts/verify-package.mjs",
+    "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",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {