@mailwoman/geographic-model 9.4.0 → 10.1.0

package/README.md

@@ -1,20 +1,20 @@
 # @mailwoman/geographic-model
 
-Authored geographic semantics for the [mailwoman](https://www.npmjs.com/package/mailwoman) geocoder: stable concepts (`pharmacy`, `obtain_medication`), the relations a curator can state between them (`pharmacy affords obtain_medication`), mappings into external vocabularies, source observations, and derived facts — every record carrying provenance, and all of it compiled deterministically into a lookup artifact the runtime reads.
+Authored geographic semantics for the [mailwoman](https://www.npmjs.com/package/mailwoman) geocoder: stable concepts (`pharmacy`, `obtain_medication`), the relations a curator can state between them (`pharmacy affords obtain_medication`), mappings into external vocabularies, source observations, and derived facts. Every record carries provenance, and the package compiles all of it deterministically into a lookup artifact that the runtime reads.
 
-The design problem it exists to solve: a geocoder benefits from knowing that a pharmacy is a place where you obtain medication, but the moment that knowledge becomes a ranking rule, authored opinion starts overriding what the models learned from data. This package holds the knowledge in a shape that CANNOT become ranking policy — no numeric field exists anywhere in the schema, and the compiled artifact answers lookups, never orderings.
+A geocoder benefits from knowing that a pharmacy is a place where you obtain medication. Once that knowledge becomes a ranking rule, however, authored opinion starts overriding what the models learned from data. This package stores the knowledge in a shape that cannot become ranking policy. The schema has no numeric field, and the compiled artifact answers lookups and never orderings.
 
 ## Should you install this?
 
-Probably not directly — not yet.
+You probably should not install it directly yet.
 
-- If you want a geocoder, install [`mailwoman`](https://www.npmjs.com/package/mailwoman). It consumes this package where its experiments call for it.
-- **Do not depend on version `0.0.0`.** It exists to establish the package name. The first supported release ships with the next coordinated mailwoman release, and the API is unstable until a `1.x`.
-- What you can evaluate today: the schema, the validator, the compiler, and the committed artifact — all shipped as readable TypeScript source and JSON in this repository.
+- If you want a geocoder, install [`mailwoman`](https://www.npmjs.com/package/mailwoman). It uses this package where its experiments need it.
+- **Do not depend on version `0.0.0`.** That version exists to reserve the package name. The first supported release ships with the next coordinated mailwoman release, and the API is unstable until a `1.x`.
+- You can evaluate the schema, the validator, the compiler, and the committed artifact today. All of them ship as readable TypeScript source and JSON in this repository.
 
 ## The shape of the data
 
-One document holds six tables, and all six are required — a hand-authored file writes `"derivedFacts": []` rather than leaving the table out, because an absent table and an empty table are different claims.
+One document holds six tables, and all six are required. A hand-authored file writes `"derivedFacts": []` instead of leaving the table out, because an absent table and an empty table make different claims.
 
 | Table          | Record                                  | What it is                                                                                                                            |
 | -------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -26,35 +26,35 @@ One document holds six tables, and all six are required — a hand-authored file
 
 Three properties hold by construction:
 
-- **No numeric field exists anywhere.** Not a strength, not a confidence, not a count. `Modality` is an ordinal vocabulary of words (`necessary`, `prohibited`, `strongly_expected`, … `strongly_unusual`) and the package exports no order over it, because a number on an authored relationship is a ranking weight whatever it is called.
-- **Authored, observed, and derived are three types, not three uses of one type.** Their identifiers carry separate brands, so one is not assignable where another is expected, and they live in separate tables so a curation decision has to be made deliberately rather than by a record sitting in a convenient place.
-- **A derived fact carries its provenance structurally.** It has no `source` field: its `derivation` plus its `inputs` are the provenance, and every input carries source provenance in turn. A source string can be copied onto a record that did not come from it; an input list either resolves or the document does not validate.
+- **The schema has no numeric field.** It has no strength, confidence, or count. `Modality` is an ordinal vocabulary of words (`necessary`, `prohibited`, `strongly_expected`, … `strongly_unusual`), and the package exports no order over it, because a number on an authored relationship acts as a ranking weight whatever it is called.
+- **Authored, observed, and derived records are three distinct types.** Their identifiers carry separate brands, so one cannot be assigned where another is expected. They live in separate tables, so a curator must make each curation decision deliberately instead of relying on where a record happens to sit.
+- **A derived fact carries its provenance in its structure.** It has no `source` field. Its `derivation` and its `inputs` form the provenance, and every input carries source provenance in turn. A source string can be copied onto a record that did not come from that source, but an input list must resolve or the document fails validation.
 
-Identifiers are branded through `type-fest`'s `Tagged` and converted explicitly — `toConceptID`, `toRelationID`, `toRuleID`, `toMappingID`, `toObservationID`, `toDerivedFactID`. The brands are compile-time only; the strings survive JSON untouched.
+Identifiers are branded through `type-fest`'s `Tagged` and converted explicitly with `toConceptID`, `toRelationID`, `toRuleID`, `toMappingID`, `toObservationID`, and `toDerivedFactID`. The brands exist only at compile time, and the strings pass through JSON unchanged.
 
 ## The validator
 
-`validateGeographicModelDocument(input)` returns the whole document or every reason it is not one. `parseGeographicModelDocument(input)` is the throwing form, and its `GeographicModelValidationError` states every violation in `error.message` as well as on `error.issues`, so a caller that only prints the message still sees all of them.
+`validateGeographicModelDocument(input)` returns either the whole document or every reason it is invalid. `parseGeographicModelDocument(input)` is the throwing form. Its `GeographicModelValidationError` states every violation in `error.message` as well as on `error.issues`, so a caller that only prints the message still sees all of them.
 
-It reports **every** violation, each addressed by a JSONPath-style location such as `$.concepts[0].assertions[1].modality`. It never returns a partial document: a validator that drops the records it could not read, without reporting them, is a validator whose output is indistinguishable from a world that does not contain them.
+The validator reports **every** violation, each with a JSONPath-style location such as `$.concepts[0].assertions[1].modality`. It never returns a partial document. If a validator silently dropped the records it could not read, its output would look the same as a world that did not contain those records.
 
-Two passes, both of which always run. **Shape** covers field presence and types, closed-vocabulary membership, and unknown keys — with a field whose name announces ranking policy (`score`, `boost`, `penalty`, `rankWeight`, and anything else matching the same fragments) reported under its own code rather than as an anonymous stray field. **Whole-table references** covers duplicate identifiers, `isA` self-reference and cycles, relation and concept resolution, relation domain and range kinds, inverse reciprocity, and derivation inputs.
+The validator runs two passes, and both always run. The **shape** pass covers field presence and types, closed-vocabulary membership, and unknown keys. A field whose name suggests ranking policy (`score`, `boost`, `penalty`, `rankWeight`, and anything else matching the same fragments) is reported under its own code instead of as an anonymous stray field. The **whole-table references** pass covers duplicate identifiers, `isA` self-reference and cycles, relation and concept resolution, relation domain and range kinds, inverse reciprocity, and derivation inputs.
 
-It is plain deterministic TypeScript with no I/O: no reasoner, no query engine, no schema library.
+The validator is plain deterministic TypeScript with no I/O. It uses no reasoner, query engine, or schema library.
 
 ## The loader, the compiler, and the artifact
 
-`loadGeographicModelDirectory(root)` (the `./load` subpath, the one module here that touches a filesystem) reads every `*.json` file under a directory and merges them into one document. The file layout is authoring convenience and carries no meaning; enumeration order cannot reach the output, and every validation issue names the file it came from.
+`loadGeographicModelDirectory(root)` reads every `*.json` file under a directory and merges them into one document. It lives in the `./load` subpath and is the only module here that touches a filesystem. The file layout is an authoring convenience and carries no meaning. Enumeration order cannot affect the output, and every validation issue identifies the file it came from.
 
-`compileGeographicModel(input)` validates by delegation, then compiles. **`isA` alone defines semantic inheritance**: the artifact carries every concept's transitive ancestors and every ancestor's assertions materialized onto descendants as derived facts naming their derivation and inputs. A relation declaring `transitive` or `inverse` is **not** closed over — those fields say what the relation means, and general reasoning is excluded from this package for its lifetime.
+`compileGeographicModel(input)` delegates validation and then compiles. **`isA` alone defines semantic inheritance.** The artifact carries every concept's transitive ancestors, and it copies every ancestor's assertions onto descendants as derived facts that record their derivation and inputs. The compiler does **not** compute closures for a relation that declares `transitive` or `inverse`. Those fields describe what the relation means, and general reasoning is excluded from this package for its lifetime.
 
-`serializeCompiledModel(model)` produces canonical bytes: keys in code-point order at every depth, tables ordered by identifier, and nothing recording when compilation ran — two builds of one document are byte-identical, so a regenerate is a diff only when the records changed.
+`serializeCompiledModel(model)` produces canonical bytes. Keys appear in code-point order at every depth, tables are ordered by identifier, and no field records when compilation ran. Two builds of one document are byte-identical, so regenerating produces a diff only when the records changed.
 
-`createGeographicModelIndex(model)` (the `./lookup` subpath) is the read surface: `concept`, `relation`, `ancestorsOf`, `derivedFactsAbout`, `conceptsForExternalID`. Lookups only — no walk, no cursor, no query language, because removing query-time traversal is the reason the artifact exists. Two absences stay distinguishable throughout: a concept the artifact does not carry answers `undefined`, and a concept it carries with nothing derived about it answers an empty list.
+`createGeographicModelIndex(model)` in the `./lookup` subpath is the read interface: `concept`, `relation`, `ancestorsOf`, `derivedFactsAbout`, `conceptsForExternalID`. It supports lookups only, without walks, cursors, or a query language, because the artifact exists to remove query-time traversal. Two kinds of absence stay distinguishable. A concept that the artifact does not carry answers `undefined`, and a carried concept with no derived facts answers an empty list.
 
 ## What is authored today
 
-The first slice, in [`data/model/`](./data/model/):
+The first record set is in [`data/model/`](./data/model/):
 
 ```text
 place
@@ -64,47 +64,47 @@ pharmacy               isA healthcare_facility          affords obtain_medicatio
 activity
 obtain_medication      isA activity
 
-affords                establishment → activity, not transitive, not symmetric
+affords                establishment → activity, neither transitive nor symmetric
 poi-taxonomy pharmacy  → the pharmacy concept
 ```
 
-[`data/geographic-model.json`](./data/geographic-model.json) is the committed compilation. **Do not hand-edit it** — regenerate:
+[`data/geographic-model.json`](./data/geographic-model.json) is the committed compilation. **Do not hand-edit it.** Regenerate it instead:
 
 ```bash
-node packages/geographic-model/lib/scripts/build-artifact.ts && npx oxfmt packages/geographic-model/data/geographic-model.json
+node packages/geographic-model/tools/build-artifact.ts && npx oxfmt packages/geographic-model/data/geographic-model.json
 ```
 
-[`data/PROVENANCE.md`](./data/PROVENANCE.md) records what each file states and where each external category id was read from. A reviewed amendment admitted a first breadth wave — a `drugstore` concept, a US-scoped `affords` assertion on it, and a second `poi-taxonomy` mapping — and all three are authored, under the same provenance discipline. One activity therefore reaches two establishment classes, which is what the schema was shaped to express and what the POI branch searches as a union.
+[`data/PROVENANCE.md`](./data/PROVENANCE.md) records what each file states and where each external category id was read from. A reviewed amendment added a first breadth wave: a `drugstore` concept, a US-scoped `affords` assertion on it, and a second `poi-taxonomy` mapping. All three are authored under the same provenance rules. One activity therefore reaches two establishment classes. The schema was designed to express that case, and the POI branch searches the two classes as a union.
 
-Measured, not promised: with this one proposition injected behind an off-by-default flag, activity-phrased queries against the live geocoder moved from 0 of 4 answered to 3 of 4 (a pharmacy 0.41 km from the Denver anchor), with all 6 control queries unchanged. That measurement — pre-registered before the code existed, frozen by hash, decided against committed thresholds — is why the package continues to grow.
+In a measurement, this one proposition was injected behind an off-by-default flag. Activity-phrased queries against the live geocoder went from 0 of 4 answered to 3 of 4 (a pharmacy 0.41 km from the Denver anchor), and all 6 control queries were unchanged. The measurement was pre-registered before the code existed, frozen by hash, and judged against committed thresholds. Its result is why the package continues to grow.
 
 ## Design commitments
 
-Each of these is owned elsewhere, and naming the owner is what keeps a second copy from growing here.
+Each of these concerns belongs to another package. The ownership list prevents a second copy from growing here.
 
 | Not here                                                                                                     | Owner                                                                                                    |
 | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
 | Relevance weights, boosts, penalties, any candidate-ordering API — even a type                               | `@mailwoman/resolver` (ordering), `@mailwoman/neural` + `@mailwoman/core/decoder` (the decode objective) |
 | POI categories, their containment hierarchy, the Overture-leaf translation, the query-phrase lexicon, brands | `@mailwoman/poi-taxonomy`                                                                                |
 | Dataset identity and coverage epistemics                                                                     | `@mailwoman/core/layers`                                                                                 |
-| Empirical, spatial activity-affordance statistics                                                            | Fitted from data elsewhere in the program — against the identifiers owned here                           |
+| Empirical, spatial activity-affordance statistics                                                            | Fitted from data elsewhere in the program, against the identifiers owned here                            |
 
-Two rules are enforced by tests rather than assumed: `@mailwoman/core` must not depend on this package (core ships the pipeline contract plus ~9 MB of reference data to every consumer, and a world-semantics dependency there is one every drop-in API inherits without asking), and the public surface carries no ranking policy — a binding whose name announces a boost, penalty, weight, rank, score, or ordering fails the suite.
+Tests enforce two rules. First, `@mailwoman/core` must not depend on this package. Core ships the pipeline interface plus ~9 MB of reference data to every consumer, so every drop-in API would inherit a world-semantics dependency added there. Second, the public API carries no ranking policy. A binding whose name suggests a boost, penalty, weight, rank, score, or ordering fails the suite.
 
-The operating rule for the whole boundary is one sentence: **knowledge creates observations; it never overrides learned interpretation.** A record here may create a fact, an anomaly, a contradiction, or a coverage-qualified absence. It may not create an imperative.
+One rule governs the whole boundary: **knowledge creates observations; it never overrides learned interpretation.** A record here may create a fact, an anomaly, a contradiction, or a coverage-qualified absence. It may not create an imperative.
 
-Architecturally excluded for the life of the package: an OWL/DL reasoner, a SPARQL endpoint, a triplestore, a general-purpose knowledge-graph service, and any query-time traversal of the authoring JSON. Authored records are source material compiled into artifacts — artifacts, not a service.
+The package architecture excludes the following for its whole life: an OWL/DL reasoner, a SPARQL endpoint, a triplestore, a general-purpose knowledge-graph service, and any query-time traversal of the authoring JSON. Authored records are source material that compiles into artifacts, and the package provides no service.
 
 ## Where the full design lives
 
 This README is the package-local summary. The authoritative documents are in the mailwoman repository:
 
-- The ownership boundary and the frozen first slice: [`docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md`](https://github.com/sister-software/mailwoman/blob/main/docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md)
+- The ownership boundary and the frozen first record set: [`docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md`](https://github.com/sister-software/mailwoman/blob/main/docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md)
 - The program that governs growth, with its decision points: [sister-software/mailwoman#1916](https://github.com/sister-software/mailwoman/issues/1916)
 
 ## Layout
 
-Source lives at the workspace root. Tests live under `test/unit/` and reach the package through its package name, never a relative path. The manifest's `files` array declares `data/**/*.json` explicitly — `**/*.ts` does not cover JSON, and a data file absent from `files` is a package that installs without the data it exists to carry.
+Source lives at the workspace root. Each test sits beside the module it covers under `lib/`. The manifest's `files` array declares `data/**/*.json` explicitly. `**/*.ts` does not match JSON, and a data file missing from `files` would leave the installed package without the data it exists to carry.
 
 ## License
 

package/data/geographic-model.json

@@ -74,7 +74,7 @@
 			"label": "healthcare facility",
 			"provenance": {
 				"authoredAt": "2026-08-26",
-				"notes": "The one intermediate class the frozen slice names between `pharmacy` and `establishment`. It carries no assertion of its own: a claim authored here would be inherited by every later healthcare class, which is breadth the program has not decided on.",
+				"notes": "The one intermediate class the frozen record set names between `pharmacy` and `establishment`. It carries no assertion of its own: a claim authored here would be inherited by every later healthcare class, which is breadth the program has not decided on.",
 				"source": "mailwoman-curated",
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927"
@@ -90,7 +90,7 @@
 			"label": "obtaining medication",
 			"provenance": {
 				"authoredAt": "2026-08-26",
-				"notes": "The frozen slice's activity, and a stable identifier this package owns. Issue #1683 may later fit empirical statistics against it; nothing numeric about it is authored here.",
+				"notes": "The frozen record set's activity, and a stable identifier this package owns. Issue #1683 may later fit empirical statistics against it; nothing numeric about it is authored here.",
 				"source": "mailwoman-curated",
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927"
@@ -104,7 +104,7 @@
 					"modality": "necessary",
 					"provenance": {
 						"authoredAt": "2026-08-26",
-						"notes": "The proposition the first slice exists to state. `necessary` because dispensing medication to the public is what makes premises a pharmacy rather than a neighbouring retail class — a counter-example falsifies this record instead of qualifying it. The relation is `defeasible`, which says whether `affords` assertions admit exceptions at all and is what lets a `strongly_expected` record sit beside this one coherently; it does not weaken this claim. No `countries` scope: the country-conditional part of the question is which OTHER establishment classes afford the activity, and each of those carries its own scope.",
+						"notes": "The proposition the first record set exists to state. `necessary` because dispensing medication to the public is what makes premises a pharmacy rather than a neighbouring retail class — a counter-example falsifies this record instead of qualifying it. The relation is `defeasible`, which says whether `affords` assertions admit exceptions at all and is what lets a `strongly_expected` record sit beside this one coherently; it does not weaken this claim. No `countries` scope: the country-conditional part of the question is which OTHER establishment classes afford the activity, and each of those carries its own scope.",
 						"source": "mailwoman-curated",
 						"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 						"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927"
@@ -120,7 +120,7 @@
 			"label": "pharmacy",
 			"provenance": {
 				"authoredAt": "2026-08-26",
-				"notes": "The frozen slice's entity kind. Mapped into `@mailwoman/poi-taxonomy`'s `pharmacy` category by `mappings.json`; the mapping carries the external identifier, and this record carries what the class affords.",
+				"notes": "The frozen record set's entity kind. Mapped into `@mailwoman/poi-taxonomy`'s `pharmacy` category by `mappings.json`; the mapping carries the external identifier, and this record carries what the class affords.",
 				"source": "mailwoman-curated",
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927"
@@ -136,7 +136,7 @@
 			"label": "place",
 			"provenance": {
 				"authoredAt": "2026-08-26",
-				"notes": "The class an establishment is sited in. Authored because the frozen slice's entity kind needs one, and no wider upper ontology is authored around it.",
+				"notes": "The class an establishment is sited in. Authored because the frozen record set's entity kind needs one, and no wider upper ontology is authored around it.",
 				"source": "mailwoman-curated",
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927"

package/data/model/concepts.json

@@ -12,7 +12,7 @@
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927",
 				"authoredAt": "2026-08-26",
-				"notes": "The class an establishment is sited in. Authored because the frozen slice's entity kind needs one, and no wider upper ontology is authored around it."
+				"notes": "The class an establishment is sited in. Authored because the frozen record set's entity kind needs one, and no wider upper ontology is authored around it."
 			},
 			"status": "active"
 		},
@@ -44,7 +44,7 @@
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927",
 				"authoredAt": "2026-08-26",
-				"notes": "The one intermediate class the frozen slice names between `pharmacy` and `establishment`. It carries no assertion of its own: a claim authored here would be inherited by every later healthcare class, which is breadth the program has not decided on."
+				"notes": "The one intermediate class the frozen record set names between `pharmacy` and `establishment`. It carries no assertion of its own: a claim authored here would be inherited by every later healthcare class, which is breadth the program has not decided on."
 			},
 			"status": "active"
 		},
@@ -65,7 +65,7 @@
 						"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 						"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927",
 						"authoredAt": "2026-08-26",
-						"notes": "The proposition the first slice exists to state. `necessary` because dispensing medication to the public is what makes premises a pharmacy rather than a neighbouring retail class — a counter-example falsifies this record instead of qualifying it. The relation is `defeasible`, which says whether `affords` assertions admit exceptions at all and is what lets a `strongly_expected` record sit beside this one coherently; it does not weaken this claim. No `countries` scope: the country-conditional part of the question is which OTHER establishment classes afford the activity, and each of those carries its own scope."
+						"notes": "The proposition the first record set exists to state. `necessary` because dispensing medication to the public is what makes premises a pharmacy rather than a neighbouring retail class — a counter-example falsifies this record instead of qualifying it. The relation is `defeasible`, which says whether `affords` assertions admit exceptions at all and is what lets a `strongly_expected` record sit beside this one coherently; it does not weaken this claim. No `countries` scope: the country-conditional part of the question is which OTHER establishment classes afford the activity, and each of those carries its own scope."
 					}
 				}
 			],
@@ -74,7 +74,7 @@
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927",
 				"authoredAt": "2026-08-26",
-				"notes": "The frozen slice's entity kind. Mapped into `@mailwoman/poi-taxonomy`'s `pharmacy` category by `mappings.json`; the mapping carries the external identifier, and this record carries what the class affords."
+				"notes": "The frozen record set's entity kind. Mapped into `@mailwoman/poi-taxonomy`'s `pharmacy` category by `mappings.json`; the mapping carries the external identifier, and this record carries what the class affords."
 			},
 			"status": "active"
 		},
@@ -139,7 +139,7 @@
 				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927",
 				"authoredAt": "2026-08-26",
-				"notes": "The frozen slice's activity, and a stable identifier this package owns. Issue #1683 may later fit empirical statistics against it; nothing numeric about it is authored here."
+				"notes": "The frozen record set's activity, and a stable identifier this package owns. Issue #1683 may later fit empirical statistics against it; nothing numeric about it is authored here."
 			},
 			"status": "active"
 		}

package/lib/artifact.ts

@@ -3,31 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The compiled runtime artifact: its shape, its canonical bytes, and the reader that turns those
- *   bytes back into a typed value.
+ *   Defines the compiled geographic model artifact, its canonical serialization and its reader.
  *
- *   A runtime consumer reads THIS and never the authored records. That is the whole point of the
- *   artifact, and it is why the shape carries every table plus the materialized `isA` closure: a
- *   consumer that had to walk `concepts[].isA` to answer a question about one concept would be doing
- *   query-time traversal, which the boundary record excludes.
+ *   Runtime consumers read the artifact instead of the authored records. The artifact includes the
+ *   materialized `isA` closure so that consumers never traverse `concepts[].isA` at query time.
  *
- *   Two determinism rules define the bytes, and both are stated so a reader can check them:
- *
- *   1. **Every object's keys are emitted in code-point order**, at every depth. A rule that
- *      canonicalizes by itself beats a hand-kept field order, which drifts the first time the schema
- *      gains a field.
- *   2. **Every table is ordered by identifier**, under {@link compareIdentifiers} — code point, never
- *      `localeCompare`, whose answer depends on the machine's collation. Arrays INSIDE a record keep
- *      the order they were authored in; the compiler writes the tables, so it orders those.
- *
- *   Nothing here records when compilation ran. `modelVersion` is the authored document's own version,
- *   so two builds of one document are byte-identical, and a clock in the artifact would make every
- *   regenerate a diff.
- *
- *   Boundary record: `docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md` (#1917).
+ *   Serialization is deterministic. Object keys use code-point order at every depth.
+ *   The compiler sorts each table by identifier in code-point order. Arrays inside a record keep authored order.
+ *   The artifact records no build time. Two builds of one document are byte-identical.
  */
 
-import { prettyJSON } from "@mailwoman/core/json"
+import { prettyJSON, stringifyJSON } from "@mailwoman/core/json"
 import { isPlainObject } from "@mailwoman/core/objects"
 import { compareByCodePoint } from "@mailwoman/core/strings/compare"
 
@@ -41,19 +27,18 @@ import type {
 } from "#schema"
 
 /**
- * The artifact FORMAT version — incremented by hand when the compiled shape changes, so a reader meeting an artifact it
- * was not written for says so instead of quietly reading fields that moved.
+ * The artifact format version.
  *
- * It is not data about the world, which is why a number is allowed here and nowhere in `./schema.ts`.
+ * Increment it whenever the compiled shape changes, so that a reader rejects
+ * an artifact it cannot interpret.
  */
 export const ARTIFACT_SCHEMA_VERSION = 1
 
 /**
- * One concept's transitive `isA` ancestors, materialized so a consumer answers "what is this a kind of" with a lookup.
+ * One concept's transitive `isA` ancestors.
  *
- * Every concept gets an entry, including one with no ancestors at all: an entry with an empty list says the concept was
- * compiled and is a kind of nothing, and a missing entry would say the same thing while also being what an absent
- * concept looks like.
+ * Every compiled concept has an entry, even with an empty ancestor list,
+ * so a missing entry always means an unknown concept.
  */
 export interface InheritanceClosureEntry {
 	concept: ConceptID
@@ -61,18 +46,18 @@ export interface InheritanceClosureEntry {
 }
 
 /**
- * The whole compiled artifact.
+ * The compiled artifact.
  *
- * The five authored tables travel unchanged — the compiler orders them and rewrites no record — beside the two tables
- * it computes: {@link InheritanceClosureEntry} per concept, and the derived facts the closure materializes.
+ * The compiler sorts the authored tables without changing any record.
+ * It adds the inheritance closure and the derived facts that it computes.
  */
 export interface CompiledGeographicModel {
 	/**
-	 * The format version of this artifact — {@link ARTIFACT_SCHEMA_VERSION} at the time it was written.
+	 * The format version, equal to {@link ARTIFACT_SCHEMA_VERSION} when the artifact was written.
 	 */
 	schemaVersion: number
 	/**
-	 * The authored document's own `version`. Never a build date.
+	 * The authored document's `version`.
 	 */
 	modelVersion: string
 	relations: readonly RelationRecord[]
@@ -81,22 +66,16 @@ export interface CompiledGeographicModel {
 	observations: readonly SourceObservationRecord[]
 	inheritanceClosure: readonly InheritanceClosureEntry[]
 	/**
-	 * The authored derived facts, plus every fact the compiler's derivations produced. Each names the procedure that
-	 * wrote it and every record that procedure read.
+	 * The authored derived facts plus the facts that the compiler derived.
+	 *
+	 * Each fact records its procedure and every record that the procedure read.
 	 */
 	derivedFacts: readonly DerivedFactRecord[]
 }
 
 /**
- * The artifact's stated order: UTF-16 code point, ascending.
- *
- * `String.prototype.localeCompare` is the trap this exists to avoid — its answer depends on the machine's collation, so
- * an artifact ordered with it is reproducible only on the machine that built it.
- */
-
-/**
- * Rebuild `value` with every object's keys in code-point order, at every depth. Arrays keep their order — ordering
- * those is the compiler's job, and doing it here would silently reorder authored data.
+ * Copies `value` with object keys in code-point order at every depth and drops `undefined` entries.
+ * Arrays keep their order.
  */
 function canonicalize(value: unknown): unknown {
 	if (Array.isArray(value)) return value.map(canonicalize)
@@ -117,12 +96,11 @@ function canonicalize(value: unknown): unknown {
 }
 
 /**
- * The artifact's canonical bytes: tab-indented, one trailing newline, keys in code-point order.
+ * Serializes the artifact as tab-indented JSON with a trailing newline and sorted keys.
  *
- * Tab indentation and the trailing newline match the repository's other committed JSON tables (`taxonomy.json`,
- * `brands.json`). A committed copy of these bytes is the generator's output run through `oxfmt`, which inlines short
- * arrays — so a freshness check compares the PARSED artifact against a fresh compile, and a byte comparison compares
- * two compiles.
+ * The committed copy also passes through `oxfmt`, which inlines short arrays.
+ * A freshness check compares parsed values.
+ * A byte comparison applies only to two compiler outputs.
  */
 export function serializeCompiledModel(model: CompiledGeographicModel): string {
 	return prettyJSON(canonicalize(model))
@@ -140,8 +118,7 @@ export class GeographicModelArtifactError extends Error {
 }
 
 /**
- * The tables every artifact carries. A reader that finds one missing refuses rather than answering every question about
- * that table with an empty list.
+ * The tables that every artifact must contain.
  */
 const ARTIFACT_TABLES = [
 	"concepts",
@@ -153,16 +130,13 @@ const ARTIFACT_TABLES = [
 ] as const
 
 /**
- * Why `value` is not a compiled artifact, or nothing when it is one.
- *
- * Kept separate from {@link parseCompiledGeographicModel} so the reader casts the value it was HANDED, still typed
- * `unknown`, rather than a narrowed shape it would have to launder through a second cast to widen again.
+ * Returns the reason `value` is not a compiled artifact, or `undefined` when it is one.
  */
 function artifactProblem(value: unknown): string | undefined {
 	if (!isPlainObject(value)) return "a compiled geographic model must be an object"
 
 	if (value.schemaVersion !== ARTIFACT_SCHEMA_VERSION) {
-		return `this reader understands artifact schema version ${ARTIFACT_SCHEMA_VERSION}; the artifact declares ${JSON.stringify(value.schemaVersion)}`
+		return `this reader understands artifact schema version ${ARTIFACT_SCHEMA_VERSION}; the artifact declares ${stringifyJSON(value.schemaVersion)}`
 	}
 
 	if (typeof value.modelVersion !== "string" || !value.modelVersion.trim().length) {
@@ -177,13 +151,11 @@ function artifactProblem(value: unknown): string | undefined {
 }
 
 /**
- * Read a parsed artifact — the value `JSON.parse` produced from the compiled bytes — as a
- * {@link CompiledGeographicModel}.
+ * Reads a value from `JSON.parse` as a {@link CompiledGeographicModel}.
  *
- * It checks the format version and the presence of every table, and does NOT re-validate the records. An artifact is
- * generated from a document that `parseGeographicModelDocument` already accepted; re-checking every record here would
- * be a second validator, and the version check is what catches the failure this reader can actually meet — an artifact
- * written by a different compiler.
+ * The reader checks the format version, the model version and the presence of every table.
+ * It does not revalidate records, because the compiler accepts only documents
+ * that already passed validation.
  */
 export function parseCompiledGeographicModel(input: unknown): CompiledGeographicModel {
 	const problem = artifactProblem(input)