@mailwoman/geographic-model 0.0.0 → 9.3.0

package/README.md

@@ -1,21 +1,18 @@
 # @mailwoman/geographic-model
 
-The **world-semantic layer**: stable geographic concepts, the relations between them, mappings from external vocabularies into those concepts, source observations, derived facts, and the provenance of every one of them — authored as records, compiled deterministically into runtime artifacts.
+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.
 
-> **Status: one authored proposition.** The record types and their deterministic validator are here (#1925), along with the loader and compiler that turn authored files into a runtime artifact (#1926) and the first authored document — `pharmacy affords obtain_medication` (#1927). Nothing consumes the artifact at runtime: no resolver integration, no ordering change, no POI behavior change. Whether the proposition is worth anything to a user is what #1928's pre-registered probe measures, and #1930 records the decision.
+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.
 
-The ownership boundary is fixed by the record at [`docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md`](../../docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md) (#1917), under program parent #1916. That document is authoritative for everything below; this README is the package-local summary.
+## Should you install this?
 
-## What this package owns
+Probably not directly — not yet.
 
-- Stable concepts beyond the POI vocabulary, and the identifiers other packages refer to them by.
-- Relation definitions, activities, affordances, and rule modality — the first of which is one proposition: `pharmacy affords obtain_medication`.
-- Mappings from external vocabularies (`@mailwoman/poi-taxonomy` category identifiers, and later others) into world concepts.
-- Source observations, kept separate from derived facts.
-- Derivation provenance on every mapping and every derived fact.
-- Deterministic compilation of the authored records into runtime artifacts, and the validation that refuses a record set which does not compile.
+- 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.
 
-## The schema
+## 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.
 
@@ -33,64 +30,31 @@ Three properties hold by construction:
 - **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.
 
-Identifiers are branded through `type-fest`'s `Tagged` and converted explicitly — `toConceptID`, `toRelationID`, `toRuleID`, `toMappingID`, `toObservationID`, `toDerivedFactID` — the same idiom as `toPOICategoryID` in `@mailwoman/poi-taxonomy`. The brands are compile-time only; the strings survive JSON untouched.
+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.
 
 ## 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.
 
-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 quietly drops the records it could not read is a validator whose output is indistinguishable from a world that does not contain 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.
 
-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`, `relevanceWeight`, `affinityWeight`, 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.
+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.
 
-It is plain deterministic TypeScript with no I/O and no dependencies beyond the two type imports: no reasoner, no query engine, no schema library.
+It is plain deterministic TypeScript with no I/O: no reasoner, no query engine, no schema library.
 
-## The loader
+## 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.
+`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.
 
-**The layout is authoring convenience and carries no meaning.** A concept means the same thing whichever file it was written in, and a file may hold any subset of the tables. One file is special: `model.json`, holding the document's `version` — a version assembled from whichever fragment happened to declare one is a version nobody chose.
+`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.
 
-Two properties make it safe to build an artifact from:
-
-- **Enumeration order cannot reach the output.** The files are sorted by path before any of them is read, so the merged tables are a function of the file names and their contents, never of `readdir` order. `mergeGeographicModelFiles(files)` states the same property without a filesystem, which is how it is tested: any order in, one document out.
-- **Every issue names the file it came from.** The validator addresses a record by its position in the merged table (`$.concepts[7].kind`) — the one address an author cannot see — so the loader keeps a per-record origin and re-addresses each issue. A duplicate identifier names **both** files, the one that claimed it and the one that claimed it first, because "already used" is unactionable without the other half.
-
-What the loader checks on its own is only what the validator cannot see: whether a file parses, whether it is an object, and whether the keys it uses are tables. Everything else is delegated whole.
-
-## The compiler
-
-`compileGeographicModel(input)` validates by delegation — `parseGeographicModelDocument` decides whether a document is well formed, and throws with every violation before a byte is computed — then compiles it into a `CompiledGeographicModel`. There is no second validator, and no partial artifact: a compile produces the whole thing or produces nothing.
-
-**`isA` alone defines semantic inheritance**, and two derivations follow from it:
-
-| In the artifact      | What it is                                                                                                                                                     |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `inheritanceClosure` | Every concept's transitive `isA` ancestors, deduplicated and ordered. One entry per concept, empty list included — a concept that is a kind of nothing says so |
-| `derivedFacts`       | Every ancestor's assertions materialized onto its descendants as `DerivedFactRecord`s, naming the derivation and every record it read                          |
-
-Materializing the assertions is what makes the artifact answer a question rather than point at one: the closure alone would tell a consumer which concepts to go and read, which is the traversal it was supposed to be spared. A descendant that states the same relation and target itself inherits nothing for that pair — the authored record is the more specific one, which is what `isA` means.
-
-A relation declaring `transitive` or `inverse` is **not** closed over. Those fields say what the relation means; materializing them is a reasoning step no executable need has asked for, and general reasoning is excluded from this package. The day one is needed it arrives as its own named derivation beside this one.
-
-Compilation refuses two things the validator cannot see, both about records the compiler is about to write, and both reported with every offending record named: an inherited assertion whose subject kind the relation does not accept, and two derived facts claiming one identifier.
-
-## The artifact
-
-`serializeCompiledModel(model)` produces the canonical bytes. Two rules define them:
-
-- **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.
-- **Every table is ordered by identifier**, under `compareIdentifiers` — code point, never `localeCompare`, whose answer depends on the machine's collation. Arrays inside a record keep the order they were authored in.
-
-Nothing records when compilation ran: `modelVersion` is the authored document's own version, so two builds of one document are byte-identical and a regenerate is a diff only when the records changed. `schemaVersion` is the artifact FORMAT version, and `parseCompiledGeographicModel` refuses an artifact declaring another one rather than reading fields that may have moved.
-
-A committed artifact is these bytes run through `oxfmt`, which inlines short arrays — the same convention `taxonomy.json` follows. So a freshness check compares the **parsed** artifact against a fresh compile, and a byte comparison compares two compiles.
+`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.
 
 `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.
 
-## The authored slice
+## What is authored today
 
-One proposition, frozen by §4 of the boundary record and authored under [`data/model/`](./data/model/):
+The first slice, in [`data/model/`](./data/model/):
 
 ```text
 place
@@ -100,23 +64,21 @@ pharmacy               isA healthcare_facility          affords obtain_medicatio
 activity
 obtain_medication      isA activity
 
-affords                establishment → activity, hard, not transitive, not symmetric
+affords                establishment → activity, not transitive, not symmetric
 poi-taxonomy pharmacy  → the pharmacy concept
 ```
 
-Every concept, assertion and mapping carries `provenance` naming the boundary record and #1927 — the two authorities this slice has. `RelationRecord` carries none, because a relation is vocabulary rather than a claim: it says what `affords` means, and stands behind nothing in particular.
-
-Deliberately absent, and each absence is a statement rather than an omission: no source observations, no hand-authored derived facts, no `countries` scope, and no second establishment class. `isA` inheritance materializes nothing here, because the one assertion sits on `pharmacy` and `pharmacy` has no descendants.
-
-[`data/geographic-model.json`](./data/geographic-model.json) is the committed compilation of those records. **Do not hand-edit it** — regenerate:
+[`data/geographic-model.json`](./data/geographic-model.json) is the committed compilation. **Do not hand-edit it** — regenerate:
 
 ```bash
-node packages/geographic-model/scripts/build-artifact.ts && npx oxfmt packages/geographic-model/data/geographic-model.json
+node packages/geographic-model/lib/scripts/build-artifact.ts && npx oxfmt packages/geographic-model/data/geographic-model.json
 ```
 
-[`data/PROVENANCE.md`](./data/PROVENANCE.md) records what each file states, where the external category id was read from, and why the freshness check compares parsed values. `test/unit/pharmacy-slice.test.ts` asserts all of it against the committed artifact, and names that command when the artifact goes stale.
+[`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.
+
+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.
 
-## What this package must never own
+## Design commitments
 
 Each of these is owned elsewhere, and naming the owner is what keeps a second copy from growing here.
 
@@ -125,30 +87,24 @@ Each of these is owned elsewhere, and naming the owner is what keeps a second co
 | 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                                                            | #1683 — it fits numbers against the identifiers owned here                                               |
-
-Two rules follow from that table and are enforced rather than assumed:
+| Empirical, spatial activity-affordance statistics                                                            | Fitted from data elsewhere in the program — against the identifiers owned here                           |
 
-- **`@mailwoman/core` must not depend on `@mailwoman/geographic-model`.** Core ships the pipeline contract and roughly 9 MB of reference data to every consumer, so a world-semantics dependency there is one every drop-in API inherits without asking for it. [`test/unit/boundaries.test.ts`](./test/unit/boundaries.test.ts) reads core's manifest and fails on the day that changes.
-- **The public surface carries no ranking policy.** The same test reads whatever the entry point exports and refuses a binding whose name announces a boost, a penalty, a weight, a rank, a score, or an ordering.
+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.
 
-The operating rule for the whole boundary is one sentence, verbatim from the record: **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.
+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.
 
-Architecturally excluded for the life of the program, not merely deferred: 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.
+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.
 
-## Why this is not in the release list
+## Where the full design lives
 
-`@mailwoman/geographic-model` is a public, publishable-shaped workspace, and it is deliberately absent from `.release-it.json`'s workspace list. The reason is mechanical rather than editorial: **npm Trusted Publishing cannot create a package that does not exist yet.** A brand-new `@mailwoman/*` name returns `E404` from OIDC, so it needs a one-time manual first publish plus a Trusted Publisher configuration — `scripts/bless-package.ts`, an interactive second-factor step an operator runs — before CI can ever publish it. Adding the name to the release list ahead of that blessing does not publish the package; it fails the next coordinated release at this workspace. `RELEASING.md`'s "Adding a NEW package: it can't be first-published from CI" is the full account.
+This README is the package-local summary. The authoritative documents are in the mailwoman repository:
 
-The absence is therefore recorded, not silent: `SANCTIONED_RELEASE_ABSENCES` in [`scripts/release-stage.ts`](../../scripts/release-stage.ts) carries it with that reason, and `checkReleaseListIdentity` fails on any absence missing from that record. The version stays at `0.0.0` — nothing bumps a workspace outside the release list, and `0.0.0` reads as never published, which is the true statement.
-
-When the package is blessed and its Trusted Publisher is on file, the change is three edits in one commit: add `packages/geographic-model` to `.release-it.json`, remove its entry from `SANCTIONED_RELEASE_ABSENCES`, and update the arithmetic in `AGENTS.md` and `scripts/release-stage.test.ts`.
+- 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 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, as it does in every workspace except `packages/corpus/` and `docs/`. Tests live under `test/unit/` and reach the package through its package name, never a relative path — the contract `scripts/verify-test-contract.ts` enforces.
-
-The manifest's `files` array already declares `data/**/*.json`. Authored records land there, and a glob written now cannot be the one a later publish forgets: `**/*.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. 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.
 
 ## License
 

package/data/geographic-model.json

@@ -16,6 +16,39 @@
 			},
 			"status": "active"
 		},
+		{
+			"assertions": [
+				{
+					"countries": ["US"],
+					"id": "drugstore-affords-obtain-medication",
+					"modality": "strongly_expected",
+					"provenance": {
+						"authoredAt": "2026-08-27",
+						"notes": "The committed curator statement `{ \"phrase\": \"drugstore\", \"categoryID\": \"pharmacy\", \"locales\": [\"en-US\"] }` says that in en-US this class names the pharmacy category. `strongly_expected` rather than `necessary`: the statement says a US drugstore characteristically dispenses, and neither a locale-scoped synonym nor a row count is a census of dispensing, so a counter-example qualifies this record rather than falsifying it. Scoped to `US` because that is the only country a committed record scopes the class to — CA (369 rows), GB (117) and MX (3) bound a population and assert nothing about what those premises afford, and FR is a measured zero on the shipped layer, so there would be nothing there for the claim to range over.",
+						"source": "mailwoman-curated",
+						"sourceRecord": "packages/poi-taxonomy/data/curated-overlay.json synonyms[drugstore → pharmacy, locales en-US]",
+						"sourceURL": "https://github.com/sister-software/mailwoman/issues/1963",
+						"sourceVersion": "poi-taxonomy table 0.4.0"
+					},
+					"relation": "affords",
+					"target": "obtain_medication"
+				}
+			],
+			"description": "A retail establishment class whose premises characteristically include a counter that dispenses medication to the public.",
+			"id": "drugstore",
+			"isA": ["establishment"],
+			"kind": "establishment",
+			"label": "drugstore",
+			"provenance": {
+				"authoredAt": "2026-08-27",
+				"notes": "Admitted by the wave-1 amendment against a measured recall gap, re-taken on the shipped layer before this record was frozen: one `group by category_id, country` pass over `poi.db` at manifest 2026-07-22.0 counts 7,168 rows under `retail > drugstore` against 82,168 under `health_and_medical > pharmacy` — 8.0% of the two leaves overall and 12.9% within the US (6,679 of 51,624), all of them out of reach of a `pharmacy` query because the branches are disjoint. A kind of `establishment` directly and not of `healthcare_facility`: the external hierarchy puts it under `retail`, and `healthcare_facility` is premises that exist to provide healthcare, which retail premises with a dispensing counter do not. The `poi-taxonomy` mapping the amendment admits as W1-3 is authored beside this record in `mappings.json`, so `obtain_medication` reaches two mapped kinds and the POI branch searches both.",
+				"source": "mailwoman-curated",
+				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4.1 W1-1",
+				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1963",
+				"sourceVersion": "poi.db layer_manifest 2026-07-22.0"
+			},
+			"status": "active"
+		},
 		{
 			"assertions": [],
 			"description": "A class of premises a person can go to.",
@@ -71,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, which is the same claim `affords` makes by declaring `hard` semantics — a counter-example falsifies this record instead of qualifying it. No `countries` scope: the country-conditional part of the question is which OTHER establishment classes afford the activity, and the slice authors no second class.",
+						"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.",
 						"source": "mailwoman-curated",
 						"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4",
 						"sourceURL": "https://github.com/sister-software/mailwoman/issues/1927"
@@ -117,6 +150,10 @@
 			"ancestors": [],
 			"concept": "activity"
 		},
+		{
+			"ancestors": ["establishment", "place"],
+			"concept": "drugstore"
+		},
 		{
 			"ancestors": ["place"],
 			"concept": "establishment"
@@ -139,6 +176,20 @@
 		}
 	],
 	"mappings": [
+		{
+			"concept": "drugstore",
+			"externalID": "drugstore",
+			"id": "poi-taxonomy-drugstore",
+			"provenance": {
+				"authoredAt": "2026-08-28",
+				"notes": "W1-3 of the wave-1 amendment, read back from the committed table at version 0.4.0 (Overture schema v1.17.0): `{ id: drugstore, hierarchy: [retail, drugstore], source: overture }`. The category declares no `overtureCategories`, so `resolveOvertureCategories(\"drugstore\")` is the identity `[\"drugstore\"]`, and the leaf is disjoint from `health_and_medical > pharmacy` — which is why 7,168 rows were out of reach of a `pharmacy` query. With this record `obtain_medication` reaches two mapped kinds; that is the SET the POI branch searches, and no field here states a preference between them. The mapping states that the external identifier names this concept and nothing else.",
+				"source": "mailwoman-curated",
+				"sourceRecord": "packages/poi-taxonomy/data/taxonomy.json categories[drugstore]",
+				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1980",
+				"sourceVersion": "poi-taxonomy table 0.4.0"
+			},
+			"vocabulary": "poi-taxonomy"
+		},
 		{
 			"concept": "pharmacy",
 			"externalID": "pharmacy",
@@ -154,7 +205,7 @@
 			"vocabulary": "poi-taxonomy"
 		}
 	],
-	"modelVersion": "0.1.0",
+	"modelVersion": "0.3.0",
 	"observations": [],
 	"relations": [
 		{
@@ -163,7 +214,7 @@
 			"id": "affords",
 			"label": "affords",
 			"rangeKinds": ["activity"],
-			"semantics": "hard",
+			"semantics": "defeasible",
 			"symmetric": false,
 			"transitive": false
 		}

package/data/model/concepts.json

@@ -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, which is the same claim `affords` makes by declaring `hard` semantics — a counter-example falsifies this record instead of qualifying it. No `countries` scope: the country-conditional part of the question is which OTHER establishment classes afford the activity, and the slice authors no second class."
+						"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."
 					}
 				}
 			],
@@ -78,6 +78,39 @@
 			},
 			"status": "active"
 		},
+		{
+			"id": "drugstore",
+			"label": "drugstore",
+			"description": "A retail establishment class whose premises characteristically include a counter that dispenses medication to the public.",
+			"kind": "establishment",
+			"isA": ["establishment"],
+			"assertions": [
+				{
+					"id": "drugstore-affords-obtain-medication",
+					"relation": "affords",
+					"target": "obtain_medication",
+					"modality": "strongly_expected",
+					"countries": ["US"],
+					"provenance": {
+						"source": "mailwoman-curated",
+						"sourceVersion": "poi-taxonomy table 0.4.0",
+						"sourceRecord": "packages/poi-taxonomy/data/curated-overlay.json synonyms[drugstore → pharmacy, locales en-US]",
+						"sourceURL": "https://github.com/sister-software/mailwoman/issues/1963",
+						"authoredAt": "2026-08-27",
+						"notes": "The committed curator statement `{ \"phrase\": \"drugstore\", \"categoryID\": \"pharmacy\", \"locales\": [\"en-US\"] }` says that in en-US this class names the pharmacy category. `strongly_expected` rather than `necessary`: the statement says a US drugstore characteristically dispenses, and neither a locale-scoped synonym nor a row count is a census of dispensing, so a counter-example qualifies this record rather than falsifying it. Scoped to `US` because that is the only country a committed record scopes the class to — CA (369 rows), GB (117) and MX (3) bound a population and assert nothing about what those premises afford, and FR is a measured zero on the shipped layer, so there would be nothing there for the claim to range over."
+					}
+				}
+			],
+			"provenance": {
+				"source": "mailwoman-curated",
+				"sourceVersion": "poi.db layer_manifest 2026-07-22.0",
+				"sourceRecord": "docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md §4.1 W1-1",
+				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1963",
+				"authoredAt": "2026-08-27",
+				"notes": "Admitted by the wave-1 amendment against a measured recall gap, re-taken on the shipped layer before this record was frozen: one `group by category_id, country` pass over `poi.db` at manifest 2026-07-22.0 counts 7,168 rows under `retail > drugstore` against 82,168 under `health_and_medical > pharmacy` — 8.0% of the two leaves overall and 12.9% within the US (6,679 of 51,624), all of them out of reach of a `pharmacy` query because the branches are disjoint. A kind of `establishment` directly and not of `healthcare_facility`: the external hierarchy puts it under `retail`, and `healthcare_facility` is premises that exist to provide healthcare, which retail premises with a dispensing counter do not. The `poi-taxonomy` mapping the amendment admits as W1-3 is authored beside this record in `mappings.json`, so `obtain_medication` reaches two mapped kinds and the POI branch searches both."
+			},
+			"status": "active"
+		},
 		{
 			"id": "activity",
 			"label": "activity",

package/data/model/mappings.json

@@ -13,6 +13,20 @@
 				"authoredAt": "2026-08-26",
 				"notes": "Read from the committed table at version 0.4.0 (Overture schema v1.17.0): `{ id: pharmacy, label: Pharmacy, hierarchy: [health_and_medical, pharmacy], basicLabel: Pharmacy, osmTag: amenity=pharmacy, source: overture }`. The category declares no `overtureCategories`, so `resolveOvertureCategories(\"pharmacy\")` is the identity `[\"pharmacy\"]`. The mapping states that the external identifier names this concept, and nothing else — the containment hierarchy, the Overture-leaf translation and the phrase lexicon stay owned by `@mailwoman/poi-taxonomy`."
 			}
+		},
+		{
+			"id": "poi-taxonomy-drugstore",
+			"concept": "drugstore",
+			"vocabulary": "poi-taxonomy",
+			"externalID": "drugstore",
+			"provenance": {
+				"source": "mailwoman-curated",
+				"sourceVersion": "poi-taxonomy table 0.4.0",
+				"sourceRecord": "packages/poi-taxonomy/data/taxonomy.json categories[drugstore]",
+				"sourceURL": "https://github.com/sister-software/mailwoman/issues/1980",
+				"authoredAt": "2026-08-28",
+				"notes": "W1-3 of the wave-1 amendment, read back from the committed table at version 0.4.0 (Overture schema v1.17.0): `{ id: drugstore, hierarchy: [retail, drugstore], source: overture }`. The category declares no `overtureCategories`, so `resolveOvertureCategories(\"drugstore\")` is the identity `[\"drugstore\"]`, and the leaf is disjoint from `health_and_medical > pharmacy` — which is why 7,168 rows were out of reach of a `pharmacy` query. With this record `obtain_medication` reaches two mapped kinds; that is the SET the POI branch searches, and no field here states a preference between them. The mapping states that the external identifier names this concept and nothing else."
+			}
 		}
 	]
 }

package/data/model/model.json

@@ -1,3 +1,3 @@
 {
-	"version": "0.1.0"
+	"version": "0.3.0"
 }

package/data/model/relations.json

@@ -8,7 +8,7 @@
 			"rangeKinds": ["activity"],
 			"transitive": false,
 			"symmetric": false,
-			"semantics": "hard"
+			"semantics": "defeasible"
 		}
 	]
 }

package/{artifact.ts → lib/artifact.ts}

@@ -27,6 +27,10 @@
  *   Boundary record: `docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md` (#1917).
  */
 
+import { prettyJSON } from "@mailwoman/core/json"
+import { isPlainObject } from "@mailwoman/core/objects"
+import { compareByCodePoint } from "@mailwoman/core/strings/compare"
+
 import type {
 	ConceptID,
 	ConceptRecord,
@@ -34,8 +38,7 @@ import type {
 	ExternalMappingRecord,
 	RelationRecord,
 	SourceObservationRecord,
-} from "./schema.ts"
-import { isPlainObject } from "./validation-issues.ts"
+} from "#schema"
 
 /**
  * The artifact FORMAT version — incremented by hand when the compiled shape changes, so a reader meeting an artifact it
@@ -90,13 +93,7 @@ export interface CompiledGeographicModel {
  * `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.
  */
-export function compareIdentifiers(left: string, right: string): number {
-	if (left < right) return -1
-
-	if (left > right) return 1
-
-	return 0
-}
+export { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
 
 /**
  * Rebuild `value` with every object's keys in code-point order, at every depth. Arrays keep their order — ordering
@@ -109,7 +106,7 @@ function canonicalize(value: unknown): unknown {
 
 	const canonical: Record<string, unknown> = {}
 
-	for (const key of Object.keys(value).toSorted(compareIdentifiers)) {
+	for (const key of Object.keys(value).toSorted(compareByCodePoint)) {
 		const entry = value[key]
 
 		if (entry === undefined) continue
@@ -129,7 +126,7 @@ function canonicalize(value: unknown): unknown {
  * two compiles.
  */
 export function serializeCompiledModel(model: CompiledGeographicModel): string {
-	return `${JSON.stringify(canonicalize(model), null, "\t")}\n`
+	return prettyJSON(canonicalize(model))
 }
 
 /**

package/{compile.ts → lib/compile.ts}

@@ -36,7 +36,7 @@ import {
 	type CompiledGeographicModel,
 	compareIdentifiers,
 	type InheritanceClosureEntry,
-} from "./artifact.ts"
+} from "#artifact"
 import {
 	type ConceptID,
 	type ConceptRecord,
@@ -48,8 +48,8 @@ import {
 	type RelationRecord,
 	toConceptID,
 	toDerivedFactID,
-} from "./schema.ts"
-import { parseGeographicModelDocument } from "./validate.ts"
+} from "#schema"
+import { parseGeographicModelDocument } from "#validate"
 
 /**
  * The name a fact derived by `isA` inheritance carries in its `derivation` field. A consumer branches on this rather

package/{index.ts → lib/index.ts}

@@ -44,8 +44,8 @@
  *   Program parent: #1916.
  */
 
-export * from "./artifact.ts"
-export * from "./compile.ts"
-export * from "./lookup.ts"
-export * from "./schema.ts"
-export * from "./validate.ts"
+export * from "#artifact"
+export * from "#compile"
+export * from "#lookup"
+export * from "#schema"
+export * from "#validate"

package/{load.ts → lib/load.ts}

@@ -26,21 +26,21 @@
  *   keys it uses are tables.
  */
 
-import { readdirSync, readFileSync } from "node:fs"
-import { resolve } from "node:path"
+import { readDirectoryEntries, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { isPlainObject } from "@mailwoman/core/objects"
+import { resolvePath } from "path-ts"
 
-import { compareIdentifiers } from "./artifact.ts"
-import type { GeographicModelDocument } from "./schema.ts"
-import { validateGeographicModelDocument } from "./validate.ts"
+import { compareIdentifiers } from "#artifact"
+import type { GeographicModelDocument } from "#schema"
+import { validateGeographicModelDocument } from "#validate"
 import {
 	add,
 	checkFieldNames,
-	isPlainObject,
 	readArray,
 	readString,
 	type ValidationIssue,
 	ValidationIssueCode,
-} from "./validation-issues.ts"
+} from "#validation-issues"
 
 /**
  * The manifest every model directory carries: the document's `version`, and nothing else.
@@ -363,15 +363,15 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
  * the tree and not of the filesystem that stored it. Symbolic links are not followed: a model directory is source, and
  * a link out of it is a record whose home nobody can state.
  */
-function listSourceFiles(root: string, prefix = ""): string[] {
-	const entries = readdirSync(resolve(root, prefix), { withFileTypes: true })
+async function listSourceFiles(root: string, prefix = ""): Promise<string[]> {
+	const entries = await readDirectoryEntries(resolvePath(root, prefix))
 	const found: string[] = []
 
 	for (const entry of entries.toSorted((left, right) => compareIdentifiers(left.name, right.name))) {
 		const path = prefix ? `${prefix}/${entry.name}` : entry.name
 
 		if (entry.isDirectory()) {
-			found.push(...listSourceFiles(root, path))
+			found.push(...(await listSourceFiles(root, path)))
 
 			continue
 		}
@@ -389,8 +389,13 @@ function listSourceFiles(root: string, prefix = ""): string[] {
  *
  * Throws {@link GeographicModelLoadError} with every issue, each addressed to its source file.
  */
-export function loadGeographicModelDirectory(root: string): GeographicModelDocument {
-	const files = listSourceFiles(root).map((path) => ({ path, text: readFileSync(resolve(root, path), "utf8") }))
+export async function loadGeographicModelDirectory(root: string): Promise<GeographicModelDocument> {
+	const paths = await listSourceFiles(root)
+	const files: GeographicModelSourceFile[] = []
+
+	for (const path of paths) {
+		files.push({ path, text: await readLocalTextFile(resolvePath(root, path)) })
+	}
 
 	return mergeGeographicModelFiles(files)
 }

package/{lookup.ts → lib/lookup.ts}

@@ -20,7 +20,7 @@
 
 import type { POICategoryID } from "@mailwoman/poi-taxonomy/types"
 
-import { type CompiledGeographicModel, compareIdentifiers } from "./artifact.ts"
+import { type CompiledGeographicModel, compareIdentifiers } from "#artifact"
 import type {
 	ConceptID,
 	ConceptRecord,
@@ -28,7 +28,7 @@ import type {
 	ExternalVocabulary,
 	RelationID,
 	RelationRecord,
-} from "./schema.ts"
+} from "#schema"
 
 /**
  * Lookups over one compiled artifact.

package/{schema.ts → lib/schema.ts}

@@ -358,9 +358,9 @@ export type DerivationInput =
  * A fact a named procedure computed from named inputs. Never hand-authored: #1926's compiler writes this table, and the
  * validator refuses a fact whose derivation is unnamed or whose inputs do not resolve.
  *
- * There is no provenance field. The derivation plus the inputs is the provenance, and it is the stronger kind — a
- * source string can be copied onto a record that did not come from it, while an input list either resolves or the
- * document does not validate.
+ * There is no provenance field. The derivation plus the inputs is the provenance and the stronger kind — a source
+ * string can be copied onto a record that did not come from it, while an input list either resolves or the document
+ * does not validate.
  */
 export interface DerivedFactRecord {
 	id: DerivedFactID

package/{validate.ts → lib/validate.ts}

@@ -27,6 +27,8 @@
  *   Consumed by #1926's compiler, which validates before it emits, and by #1927's authored document.
  */
 
+import { isPlainObject } from "@mailwoman/core/objects"
+
 import {
 	ConceptKind,
 	ConceptStatus,
@@ -35,11 +37,10 @@ import {
 	type GeographicModelDocument,
 	Modality,
 	RelationSemantics,
-} from "./schema.ts"
+} from "#schema"
 import {
 	add,
 	checkFieldNames,
-	isPlainObject,
 	listVocabulary,
 	readArray,
 	readBoolean,
@@ -49,9 +50,9 @@ import {
 	readVocabularyValue,
 	type ValidationIssue,
 	ValidationIssueCode,
-} from "./validation-issues.ts"
+} from "#validation-issues"
 
-export { type ValidationIssue, ValidationIssueCode } from "./validation-issues.ts"
+export { type ValidationIssue, ValidationIssueCode } from "#validation-issues"
 
 /**
  * The whole document, or every reason it is not one.