@mailwoman/geographic-model 0.0.0

package/out/schema.d.ts

@@ -0,0 +1,366 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The authored-record schema for `@mailwoman/geographic-model`: the stable identifiers, the closed
+ *   vocabularies, and the record shapes for concepts, relations, external-vocabulary mappings, source
+ *   observations, and derived facts.
+ *
+ *   Three properties hold by construction, and they are why the file reads the way it does.
+ *
+ *   **No numeric field exists anywhere in this schema** — not a strength, not a confidence, not a
+ *   count. {@link Modality} is an ordinal vocabulary of WORDS and this module exports no order over
+ *   it, because a number attached to an authored relationship is a ranking weight whatever it is
+ *   called, and ranking belongs to `@mailwoman/resolver` and `@mailwoman/neural`.
+ *
+ *   **An authored assertion, a source observation, and a derived fact are three different types.** A
+ *   {@link RelationAssertion} is authored by a curator and lives on the concept it is about; a
+ *   {@link SourceObservationRecord} records what a named external source states and never enters the
+ *   concept table; a {@link DerivedFactRecord} names the procedure that produced it and every input
+ *   that procedure read. Their identifiers are separately branded, so one is not assignable where
+ *   another is expected.
+ *
+ *   **Every record carries provenance, and a derived fact carries it structurally.** A derived fact
+ *   has no {@link SourceProvenance} of its own: its `derivation` plus its resolved `inputs` ARE its
+ *   provenance, and each input carries source provenance in turn.
+ *
+ *   Identifier namespaces are per-table. A {@link ConceptID} and a {@link RelationID} may read the
+ *   same string without colliding; the brands are what keep them apart in a consumer.
+ *
+ *   Consumed by `./validate.ts` (which refuses a document violating any rule above), by #1926's
+ *   deterministic compiler, and by the first authored document in #1927.
+ *
+ *   Boundary record: `docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md` (#1917).
+ */
+import type { POICategoryID } from "@mailwoman/poi-taxonomy/types";
+import type { Tagged } from "type-fest";
+/**
+ * A concept identifier, e.g. `pharmacy`, `obtain_medication`. Branded — convert via {@link toConceptID}.
+ */
+export type ConceptID = Tagged<string, "GeographicConceptID">;
+/**
+ * Brand a raw string as a {@link ConceptID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export declare function toConceptID(id: string): ConceptID;
+/**
+ * A relation identifier, e.g. `affords`. Branded — convert via {@link toRelationID}.
+ */
+export type RelationID = Tagged<string, "GeographicRelationID">;
+/**
+ * Brand a raw string as a {@link RelationID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export declare function toRelationID(id: string): RelationID;
+/**
+ * The identifier of one authored {@link RelationAssertion}. Branded — convert via {@link toRuleID}.
+ */
+export type RuleID = Tagged<string, "GeographicRuleID">;
+/**
+ * Brand a raw string as a {@link RuleID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export declare function toRuleID(id: string): RuleID;
+/**
+ * The identifier of one {@link ExternalMappingRecord}. Branded — convert via {@link toMappingID}.
+ */
+export type MappingID = Tagged<string, "GeographicMappingID">;
+/**
+ * Brand a raw string as a {@link MappingID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export declare function toMappingID(id: string): MappingID;
+/**
+ * The identifier of one {@link SourceObservationRecord}. Branded — convert via {@link toObservationID}.
+ */
+export type ObservationID = Tagged<string, "GeographicObservationID">;
+/**
+ * Brand a raw string as an {@link ObservationID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export declare function toObservationID(id: string): ObservationID;
+/**
+ * The identifier of one {@link DerivedFactRecord}. Branded — convert via {@link toDerivedFactID}.
+ */
+export type DerivedFactID = Tagged<string, "GeographicDerivedFactID">;
+/**
+ * Brand a raw string as a {@link DerivedFactID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export declare function toDerivedFactID(id: string): DerivedFactID;
+/**
+ * The complete set of concept kinds. Three, deliberately: the first executable slice needs an establishment class, an
+ * activity, and the place class an establishment is sited in. Widening this vocabulary is a reviewed schema revision,
+ * which is the review cost the program accepted in exchange for refusing speculative upper-ontology breadth.
+ */
+export declare const ConceptKind: {
+    /**
+     * A geographic place — an area or a point that other things are sited in or near.
+     */
+    readonly Place: "place";
+    /**
+     * A class of premises a person can go to, e.g. `pharmacy`.
+     */
+    readonly Establishment: "establishment";
+    /**
+     * Something a person does, e.g. `obtain_medication`. The identifier is owned here; any statistics fitted against it
+     * are owned by #1683.
+     */
+    readonly Activity: "activity";
+};
+export type ConceptKind = (typeof ConceptKind)[keyof typeof ConceptKind];
+/**
+ * How strongly an assertion, an observation, or a derived fact claims its proposition holds.
+ *
+ * The vocabulary is ordinal in meaning and this module exports no order over it, on purpose. An exported rank would be
+ * one arithmetic step from a weight, and an authored weight is the single thing the package boundary forbids.
+ */
+export declare const Modality: {
+    /**
+     * Holds in every instance; a counter-example falsifies the record rather than qualifying it.
+     */
+    readonly Necessary: "necessary";
+    /**
+     * Never holds.
+     */
+    readonly Prohibited: "prohibited";
+    readonly StronglyExpected: "strongly_expected";
+    readonly Expected: "expected";
+    readonly WeaklyExpected: "weakly_expected";
+    /**
+     * Consistent with the concept and asserts nothing about how often it holds.
+     */
+    readonly Possible: "possible";
+    readonly Unusual: "unusual";
+    readonly StronglyUnusual: "strongly_unusual";
+};
+export type Modality = (typeof Modality)[keyof typeof Modality];
+/**
+ * Whether a relation's assertions admit exceptions.
+ */
+export declare const RelationSemantics: {
+    /**
+     * An exception is a defect in the record set.
+     */
+    readonly Hard: "hard";
+    /**
+     * An exception is expected and does not falsify the relation.
+     */
+    readonly Defeasible: "defeasible";
+};
+export type RelationSemantics = (typeof RelationSemantics)[keyof typeof RelationSemantics];
+/**
+ * A concept's authoring lifecycle. It says whether a consumer should read the record, and nothing about how much the
+ * record is worth.
+ */
+export declare const ConceptStatus: {
+    /**
+     * Authored, not yet reviewed. A compiler may refuse to emit it.
+     */
+    readonly Draft: "draft";
+    readonly Active: "active";
+    /**
+     * Kept so existing references resolve; no new reference should be authored against it.
+     */
+    readonly Deprecated: "deprecated";
+};
+export type ConceptStatus = (typeof ConceptStatus)[keyof typeof ConceptStatus];
+/**
+ * The external vocabularies a concept can be mapped into. One today, and the mapping record below is typed against it
+ * directly; a second vocabulary turns {@link ExternalMappingRecord} into a union discriminated on `vocabulary`.
+ */
+export declare const ExternalVocabulary: {
+    /**
+     * `@mailwoman/poi-taxonomy` category identifiers — the owner of external and curated POI categories.
+     */
+    readonly POITaxonomy: "poi-taxonomy";
+};
+export type ExternalVocabulary = (typeof ExternalVocabulary)[keyof typeof ExternalVocabulary];
+/**
+ * Where a record came from. `source` is required and non-empty on every record that carries provenance: a record whose
+ * source is blank is indistinguishable from a record nobody stands behind.
+ */
+export interface SourceProvenance {
+    /**
+     * The naming authority, dataset, publication, or curator, e.g. `overture-places` or `mailwoman-curated`.
+     */
+    source: string;
+    /**
+     * The source's own version or release string, when it has one, e.g. an Overture release.
+     */
+    sourceVersion?: string;
+    /**
+     * The identifier of the specific record within the source, when the claim is traceable to one.
+     */
+    sourceRecord?: string;
+    sourceURL?: string;
+    /**
+     * ISO 8601 calendar date the record was authored, `YYYY-MM-DD`.
+     */
+    authoredAt?: string;
+    notes?: string;
+}
+/**
+ * One relation's definition. Relations are vocabulary, not claims: the record says what the relation MEANS and which
+ * concept kinds may stand on either side of it, and asserts nothing about any particular pair.
+ */
+export interface RelationRecord {
+    id: RelationID;
+    label: string;
+    description: string;
+    /**
+     * The concept kinds allowed on the asserting side.
+     */
+    domainKinds: ConceptKind[];
+    /**
+     * The concept kinds allowed on the target side.
+     */
+    rangeKinds: ConceptKind[];
+    transitive: boolean;
+    symmetric: boolean;
+    /**
+     * The relation reading the same edge in the other direction. When present it must resolve, and the relation it names
+     * must name this one back.
+     */
+    inverse?: RelationID;
+    semantics: RelationSemantics;
+}
+/**
+ * One authored claim, attached to the concept it is about. This is curated semantics — what a curator states holds, not
+ * what a dataset was observed to contain.
+ */
+export interface RelationAssertion {
+    id: RuleID;
+    relation: RelationID;
+    target: ConceptID;
+    modality: Modality;
+    /**
+     * ISO 3166-1 alpha-2 codes the claim is scoped to. Absent means the curator scoped it to nowhere in particular, which
+     * is a weaker statement than scoping it to everywhere.
+     */
+    countries?: string[];
+    provenance: SourceProvenance;
+}
+/**
+ * One concept, and everything authored about it.
+ */
+export interface ConceptRecord {
+    id: ConceptID;
+    label: string;
+    description: string;
+    kind: ConceptKind;
+    /**
+     * Broader concepts this one is a kind of. May be empty; may not name this concept, directly or around a cycle.
+     */
+    isA: ConceptID[];
+    assertions: RelationAssertion[];
+    provenance: SourceProvenance;
+    status: ConceptStatus;
+}
+/**
+ * A translation from an external vocabulary's identifier into a concept owned here. It carries no semantics of its own:
+ * it says which external identifier names the same thing, and on whose authority.
+ */
+export interface ExternalMappingRecord {
+    id: MappingID;
+    concept: ConceptID;
+    vocabulary: ExternalVocabulary;
+    /**
+     * The identifier in the external vocabulary. Typed as a `POICategoryID` because `poi-taxonomy` is the only member of
+     * {@link ExternalVocabulary}; a second member makes this field a per-vocabulary type.
+     */
+    externalID: POICategoryID;
+    provenance: SourceProvenance;
+}
+/**
+ * A proposition a named external source states, recorded in this model's vocabulary.
+ *
+ * It is kept out of the concept table on purpose. An observation is evidence about the world that someone else
+ * collected; promoting one into an authored assertion is a curation decision that has to be made and provenanced
+ * explicitly, never by the record sitting in a convenient place.
+ */
+export interface SourceObservationRecord {
+    id: ObservationID;
+    subject: ConceptID;
+    relation: RelationID;
+    object: ConceptID;
+    modality: Modality;
+    /**
+     * ISO 3166-1 alpha-2 codes the source scoped its statement to.
+     */
+    countries?: string[];
+    provenance: SourceProvenance;
+}
+/**
+ * Which table a {@link DerivationInput} points into.
+ */
+export declare const DerivationInputKind: {
+    readonly Concept: "concept";
+    readonly Relation: "relation";
+    readonly Assertion: "assertion";
+    readonly Mapping: "mapping";
+    readonly Observation: "observation";
+    readonly DerivedFact: "derived_fact";
+};
+export type DerivationInputKind = (typeof DerivationInputKind)[keyof typeof DerivationInputKind];
+/**
+ * One record a derivation read. The union is discriminated on `kind` so the identifier's brand matches the table it
+ * resolves against.
+ */
+export type DerivationInput = {
+    kind: typeof DerivationInputKind.Concept;
+    id: ConceptID;
+} | {
+    kind: typeof DerivationInputKind.Relation;
+    id: RelationID;
+} | {
+    kind: typeof DerivationInputKind.Assertion;
+    id: RuleID;
+} | {
+    kind: typeof DerivationInputKind.Mapping;
+    id: MappingID;
+} | {
+    kind: typeof DerivationInputKind.Observation;
+    id: ObservationID;
+} | {
+    kind: typeof DerivationInputKind.DerivedFact;
+    id: DerivedFactID;
+};
+/**
+ * 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.
+ */
+export interface DerivedFactRecord {
+    id: DerivedFactID;
+    /**
+     * The deterministic procedure that produced this fact, named so a reader can re-run it.
+     */
+    derivation: string;
+    /**
+     * Every record the derivation read. At least one, and each must resolve.
+     */
+    inputs: DerivationInput[];
+    subject: ConceptID;
+    relation: RelationID;
+    object: ConceptID;
+    modality: Modality;
+    countries?: string[];
+}
+/**
+ * One authored document: the whole record set a validator, and later a compiler, reads at once.
+ *
+ * All six fields are required, `derivedFacts` included. A hand-authored file therefore writes `"derivedFacts": []`,
+ * which is the point — an absent table and an empty table are different claims, and the format that allows the first to
+ * stand in for the second is the format where a dropped table reads as a world with no derived facts in it.
+ */
+export interface GeographicModelDocument {
+    /**
+     * The document's own schema/data version.
+     */
+    version: string;
+    relations: RelationRecord[];
+    concepts: ConceptRecord[];
+    mappings: ExternalMappingRecord[];
+    observations: SourceObservationRecord[];
+    derivedFacts: DerivedFactRecord[];
+}
+//# sourceMappingURL=schema.d.ts.map

package/out/schema.d.ts.map

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

package/out/schema.js

@@ -0,0 +1,166 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The authored-record schema for `@mailwoman/geographic-model`: the stable identifiers, the closed
+ *   vocabularies, and the record shapes for concepts, relations, external-vocabulary mappings, source
+ *   observations, and derived facts.
+ *
+ *   Three properties hold by construction, and they are why the file reads the way it does.
+ *
+ *   **No numeric field exists anywhere in this schema** — not a strength, not a confidence, not a
+ *   count. {@link Modality} is an ordinal vocabulary of WORDS and this module exports no order over
+ *   it, because a number attached to an authored relationship is a ranking weight whatever it is
+ *   called, and ranking belongs to `@mailwoman/resolver` and `@mailwoman/neural`.
+ *
+ *   **An authored assertion, a source observation, and a derived fact are three different types.** A
+ *   {@link RelationAssertion} is authored by a curator and lives on the concept it is about; a
+ *   {@link SourceObservationRecord} records what a named external source states and never enters the
+ *   concept table; a {@link DerivedFactRecord} names the procedure that produced it and every input
+ *   that procedure read. Their identifiers are separately branded, so one is not assignable where
+ *   another is expected.
+ *
+ *   **Every record carries provenance, and a derived fact carries it structurally.** A derived fact
+ *   has no {@link SourceProvenance} of its own: its `derivation` plus its resolved `inputs` ARE its
+ *   provenance, and each input carries source provenance in turn.
+ *
+ *   Identifier namespaces are per-table. A {@link ConceptID} and a {@link RelationID} may read the
+ *   same string without colliding; the brands are what keep them apart in a consumer.
+ *
+ *   Consumed by `./validate.ts` (which refuses a document violating any rule above), by #1926's
+ *   deterministic compiler, and by the first authored document in #1927.
+ *
+ *   Boundary record: `docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md` (#1917).
+ */
+/**
+ * Brand a raw string as a {@link ConceptID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export function toConceptID(id) {
+    return id;
+}
+/**
+ * Brand a raw string as a {@link RelationID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export function toRelationID(id) {
+    return id;
+}
+/**
+ * Brand a raw string as a {@link RuleID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export function toRuleID(id) {
+    return id;
+}
+/**
+ * Brand a raw string as a {@link MappingID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export function toMappingID(id) {
+    return id;
+}
+/**
+ * Brand a raw string as an {@link ObservationID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export function toObservationID(id) {
+    return id;
+}
+/**
+ * Brand a raw string as a {@link DerivedFactID}. Purely a compile-time assertion; the string is unchanged.
+ */
+export function toDerivedFactID(id) {
+    return id;
+}
+/**
+ * The complete set of concept kinds. Three, deliberately: the first executable slice needs an establishment class, an
+ * activity, and the place class an establishment is sited in. Widening this vocabulary is a reviewed schema revision,
+ * which is the review cost the program accepted in exchange for refusing speculative upper-ontology breadth.
+ */
+export const ConceptKind = {
+    /**
+     * A geographic place — an area or a point that other things are sited in or near.
+     */
+    Place: "place",
+    /**
+     * A class of premises a person can go to, e.g. `pharmacy`.
+     */
+    Establishment: "establishment",
+    /**
+     * Something a person does, e.g. `obtain_medication`. The identifier is owned here; any statistics fitted against it
+     * are owned by #1683.
+     */
+    Activity: "activity",
+};
+/**
+ * How strongly an assertion, an observation, or a derived fact claims its proposition holds.
+ *
+ * The vocabulary is ordinal in meaning and this module exports no order over it, on purpose. An exported rank would be
+ * one arithmetic step from a weight, and an authored weight is the single thing the package boundary forbids.
+ */
+export const Modality = {
+    /**
+     * Holds in every instance; a counter-example falsifies the record rather than qualifying it.
+     */
+    Necessary: "necessary",
+    /**
+     * Never holds.
+     */
+    Prohibited: "prohibited",
+    StronglyExpected: "strongly_expected",
+    Expected: "expected",
+    WeaklyExpected: "weakly_expected",
+    /**
+     * Consistent with the concept and asserts nothing about how often it holds.
+     */
+    Possible: "possible",
+    Unusual: "unusual",
+    StronglyUnusual: "strongly_unusual",
+};
+/**
+ * Whether a relation's assertions admit exceptions.
+ */
+export const RelationSemantics = {
+    /**
+     * An exception is a defect in the record set.
+     */
+    Hard: "hard",
+    /**
+     * An exception is expected and does not falsify the relation.
+     */
+    Defeasible: "defeasible",
+};
+/**
+ * A concept's authoring lifecycle. It says whether a consumer should read the record, and nothing about how much the
+ * record is worth.
+ */
+export const ConceptStatus = {
+    /**
+     * Authored, not yet reviewed. A compiler may refuse to emit it.
+     */
+    Draft: "draft",
+    Active: "active",
+    /**
+     * Kept so existing references resolve; no new reference should be authored against it.
+     */
+    Deprecated: "deprecated",
+};
+/**
+ * The external vocabularies a concept can be mapped into. One today, and the mapping record below is typed against it
+ * directly; a second vocabulary turns {@link ExternalMappingRecord} into a union discriminated on `vocabulary`.
+ */
+export const ExternalVocabulary = {
+    /**
+     * `@mailwoman/poi-taxonomy` category identifiers — the owner of external and curated POI categories.
+     */
+    POITaxonomy: "poi-taxonomy",
+};
+/**
+ * Which table a {@link DerivationInput} points into.
+ */
+export const DerivationInputKind = {
+    Concept: "concept",
+    Relation: "relation",
+    Assertion: "assertion",
+    Mapping: "mapping",
+    Observation: "observation",
+    DerivedFact: "derived_fact",
+};
+//# sourceMappingURL=schema.js.map

package/out/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAUH;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACrC,OAAO,EAAe,CAAA;AACvB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACtC,OAAO,EAAgB,CAAA;AACxB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAU;IAClC,OAAO,EAAY,CAAA;AACpB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACrC,OAAO,EAAe,CAAA;AACvB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU;IACzC,OAAO,EAAmB,CAAA;AAC3B,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU;IACzC,OAAO,EAAmB,CAAA;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IAC1B;;OAEG;IACH,KAAK,EAAE,OAAO;IACd;;OAEG;IACH,aAAa,EAAE,eAAe;IAC9B;;;OAGG;IACH,QAAQ,EAAE,UAAU;CACX,CAAA;AAIV;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACvB;;OAEG;IACH,SAAS,EAAE,WAAW;IACtB;;OAEG;IACH,UAAU,EAAE,YAAY;IACxB,gBAAgB,EAAE,mBAAmB;IACrC,QAAQ,EAAE,UAAU;IACpB,cAAc,EAAE,iBAAiB;IACjC;;OAEG;IACH,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,eAAe,EAAE,kBAAkB;CAC1B,CAAA;AAIV;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC;;OAEG;IACH,IAAI,EAAE,MAAM;IACZ;;OAEG;IACH,UAAU,EAAE,YAAY;CACf,CAAA;AAIV;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B;;OAEG;IACH,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB;;OAEG;IACH,UAAU,EAAE,YAAY;CACf,CAAA;AAIV;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC;;OAEG;IACH,WAAW,EAAE,cAAc;CAClB,CAAA;AA6HV;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAClC,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,WAAW,EAAE,aAAa;IAC1B,WAAW,EAAE,cAAc;CAClB,CAAA"}

package/out/scripts/build-artifact.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Generator for `data/geographic-model.json` — the committed compiled artifact, built from the
+ *   authored records under `data/model/`.
+ *
+ *   The build step is the whole of what this file does: load the authoring directory, compile it,
+ *   serialize the result. Every decision inside those three calls belongs to `../load.ts`,
+ *   `../compile.ts` and `../artifact.ts`, and none of them is re-made here.
+ *
+ *   **A committed artifact is these bytes run through `oxfmt`.** The repository formatter also formats
+ *   committed JSON, and it inlines short arrays, which `JSON.stringify` cannot reproduce. So the
+ *   freshness check in `test/unit/pharmacy-slice.test.ts` compares the PARSED artifact against a fresh
+ *   compile, and byte equality is asserted between two compiles instead. The same convention holds
+ *   `taxonomy.json` in `@mailwoman/poi-taxonomy`; its `data/PROVENANCE.md` states it for that table.
+ *
+ *   Nothing here reaches `@mailwoman/core`: the package's build project declares no reference to it in
+ *   either direction, and a generator is not the reason to reverse that. `import.meta.main` is what
+ *   `runIfScript` reads anyway, and reading it directly keeps this file inside the package's own
+ *   dependency graph.
+ */
+import { type CompiledGeographicModel } from "../artifact.ts";
+/**
+ * The command that rewrites the committed artifact. Stated once, and quoted by the freshness test's failure message, so
+ * a reader who trips it is told what to run rather than left to reconstruct it.
+ */
+export declare const REGENERATE_ARTIFACT_COMMAND = "node packages/geographic-model/scripts/build-artifact.ts && npx oxfmt packages/geographic-model/data/geographic-model.json";
+/**
+ * The authoring directory and the artifact it compiles to.
+ *
+ * Two candidates, because this module runs from two places: `scripts/` in the repository, where `data/` is one level
+ * up, and `out/scripts/` in a published tarball, where it is two. Probing for the file distinguishes those from a
+ * genuinely missing `data/`, which throws with both paths named.
+ */
+export declare function packagedModelPaths(): {
+    source: string;
+    artifact: string;
+};
+/**
+ * Load the authored records and compile them. Throws with every violation if they do not load, and with every reason if
+ * they load but do not compile; nothing partial is returned.
+ */
+export declare function compileAuthoredGeographicModel(): CompiledGeographicModel;
+/**
+ * Read the committed artifact. The format version is checked; the records are not re-validated, because they were
+ * validated on the way in.
+ */
+export declare function readCompiledGeographicModel(): CompiledGeographicModel;
+//# sourceMappingURL=build-artifact.d.ts.map

package/out/scripts/build-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-artifact.d.ts","sourceRoot":"","sources":["../../scripts/build-artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,EAAE,KAAK,uBAAuB,EAAwD,MAAM,gBAAgB,CAAA;AAInH;;;GAGG;AACH,eAAO,MAAM,2BAA2B,+HACqF,CAAA;AAE7H;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASzE;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,uBAAuB,CAExE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,uBAAuB,CAOrE"}

package/out/scripts/build-artifact.js

@@ -0,0 +1,78 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Generator for `data/geographic-model.json` — the committed compiled artifact, built from the
+ *   authored records under `data/model/`.
+ *
+ *   The build step is the whole of what this file does: load the authoring directory, compile it,
+ *   serialize the result. Every decision inside those three calls belongs to `../load.ts`,
+ *   `../compile.ts` and `../artifact.ts`, and none of them is re-made here.
+ *
+ *   **A committed artifact is these bytes run through `oxfmt`.** The repository formatter also formats
+ *   committed JSON, and it inlines short arrays, which `JSON.stringify` cannot reproduce. So the
+ *   freshness check in `test/unit/pharmacy-slice.test.ts` compares the PARSED artifact against a fresh
+ *   compile, and byte equality is asserted between two compiles instead. The same convention holds
+ *   `taxonomy.json` in `@mailwoman/poi-taxonomy`; its `data/PROVENANCE.md` states it for that table.
+ *
+ *   Nothing here reaches `@mailwoman/core`: the package's build project declares no reference to it in
+ *   either direction, and a generator is not the reason to reverse that. `import.meta.main` is what
+ *   `runIfScript` reads anyway, and reading it directly keeps this file inside the package's own
+ *   dependency graph.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseCompiledGeographicModel, serializeCompiledModel } from "../artifact.js";
+import { compileGeographicModel } from "../compile.js";
+import { loadGeographicModelDirectory } from "../load.js";
+/**
+ * The command that rewrites the committed artifact. Stated once, and quoted by the freshness test's failure message, so
+ * a reader who trips it is told what to run rather than left to reconstruct it.
+ */
+export const REGENERATE_ARTIFACT_COMMAND = "node packages/geographic-model/scripts/build-artifact.ts && npx oxfmt packages/geographic-model/data/geographic-model.json";
+/**
+ * The authoring directory and the artifact it compiles to.
+ *
+ * Two candidates, because this module runs from two places: `scripts/` in the repository, where `data/` is one level
+ * up, and `out/scripts/` in a published tarball, where it is two. Probing for the file distinguishes those from a
+ * genuinely missing `data/`, which throws with both paths named.
+ */
+export function packagedModelPaths() {
+    const candidates = [resolve(import.meta.dirname, "../data"), resolve(import.meta.dirname, "../../data")];
+    const found = candidates.find((candidate) => existsSync(resolve(candidate, "model/model.json")));
+    if (!found) {
+        throw new Error(`geographic-model: could not find data/model — looked in ${candidates.join(", ")}`);
+    }
+    return { source: resolve(found, "model"), artifact: resolve(found, "geographic-model.json") };
+}
+/**
+ * Load the authored records and compile them. Throws with every violation if they do not load, and with every reason if
+ * they load but do not compile; nothing partial is returned.
+ */
+export function compileAuthoredGeographicModel() {
+    return compileGeographicModel(loadGeographicModelDirectory(packagedModelPaths().source));
+}
+/**
+ * Read the committed artifact. The format version is checked; the records are not re-validated, because they were
+ * validated on the way in.
+ */
+export function readCompiledGeographicModel() {
+    const text = readFileSync(packagedModelPaths().artifact, "utf8");
+    // A corrupt committed artifact is a broken build, and the `SyntaxError` names the offset. The package's parse
+    // wrappers live in `@mailwoman/core`, which this package deliberately does not depend on.
+    // oxlint-disable-next-line no-restricted-properties -- see the note above.
+    return parseCompiledGeographicModel(JSON.parse(text));
+}
+function main() {
+    const { artifact } = packagedModelPaths();
+    const model = compileAuthoredGeographicModel();
+    writeFileSync(artifact, serializeCompiledModel(model));
+    console.log(`wrote ${artifact}: ${model.concepts.length} concepts, ${model.relations.length} relations, ${model.mappings.length} mappings, ${model.observations.length} observations, ${model.derivedFacts.length} derived facts (model ${model.modelVersion})`);
+}
+// `import.meta.main` is undefined under a Vite/vitest module graph, so importing this module from a test stays
+// side-effect-free and never rewrites the committed artifact.
+if (import.meta.main) {
+    main();
+}
+//# sourceMappingURL=build-artifact.js.map