@mailwoman/geographic-model 10.0.0 → 10.2.0

package/lib/validation/issues.ts

@@ -3,20 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The issue vocabulary and the primitive field readers `./validate.ts` is built from.
+ * The issue vocabulary and the primitive field readers `./validate.ts` is built from.
  *
- *   Every reader takes the issue list it appends to and returns `undefined` when it could not read the
- *   field. That shape is deliberate: a reader that threw would end the pass at the first defect, and a
- *   reader that substituted a default would convert "I could not read this" into a value, which at a
- *   validation boundary is the same as inventing one. Returning nothing, having said why, lets the
- *   caller skip the checks that depended on the field and keep running the ones that did not.
- *
- *   `./validate.ts` re-exports {@link ValidationIssueCode} and {@link ValidationIssue}; the readers
- *   stay internal to the package.
+ * Every reader appends issues to the supplied list and returns `null` when it cannot read a field.
+ * The pass records each defect and continues.
+ * A default would turn an unreadable field into a value and invent data at the validation boundary.
  */
 
 /**
- * Every way a document can fail validation. Closed, so a consumer branches on the code rather than on message prose.
+ * Every way a document can fail validation.
+ *
+ * The set is closed, so a consumer branches on the code rather than on message prose.
  */
 export const ValidationIssueCode = {
 	MissingField: "missing_field",
@@ -26,12 +23,12 @@ export const ValidationIssueCode = {
 	 */
 	EmptyValue: "empty_value",
 	/**
-	 * A list that must carry entries was empty.
+	 * A list that must contain entries was empty.
 	 */
 	EmptyList: "empty_list",
 	UnknownField: "unknown_field",
 	/**
-	 * A field whose name announces ranking policy. Refused wherever it appears, at any depth.
+	 * A field whose name announces ranking policy, refused wherever it appears at any depth.
 	 */
 	RankingField: "ranking_field",
 	UnknownConceptKind: "unknown_concept_kind",
@@ -64,8 +61,8 @@ export type ValidationIssueCode = (typeof ValidationIssueCode)[keyof typeof Vali
  */
 export interface ValidationIssue {
 	/**
-	 * A JSONPath-style address into the validated input, e.g. `$.concepts[0].assertions[1].modality`. The document root
-	 * is `$`.
+	 * A JSONPath-style address into the validated input whose root is `$`,
+	 * e.g. `$.concepts[0].assertions[1].modality`.
 	 */
 	path: string
 	code: ValidationIssueCode
@@ -73,9 +70,8 @@ export interface ValidationIssue {
 }
 
 /**
- * Name fragments that announce ranking policy. Matched case-insensitively against every field name at every depth, so
- * `score`, `boost`, `penalty`, `rankWeight`, `relevanceWeight`, and `affinityWeight` are refused by one rule rather
- * than by an enumeration that a seventh spelling walks past.
+ * Name fragments that announce ranking policy, matched case-insensitively against every field name
+ * at every depth so a new spelling is refused by one rule rather than added to an enumeration.
  */
 const RANKING_FIELD_FRAGMENTS = [
 	"boost",
@@ -138,7 +134,7 @@ export function readString(
 	container: Record<string, unknown>,
 	key: string,
 	required: boolean
-): string | undefined {
+): string | null {
 	const value = container[key]
 	const fieldPath = `${path}.${key}`
 
@@ -147,19 +143,19 @@ export function readString(
 			add(issues, fieldPath, ValidationIssueCode.MissingField, `\`${key}\` is required`)
 		}
 
-		return undefined
+		return null
 	}
 
 	if (typeof value !== "string") {
 		add(issues, fieldPath, ValidationIssueCode.WrongType, `\`${key}\` must be a string`)
 
-		return undefined
+		return null
 	}
 
-	if (!value.trim().length) {
+	if (!value.trim()) {
 		add(issues, fieldPath, ValidationIssueCode.EmptyValue, `\`${key}\` must not be blank`)
 
-		return undefined
+		return null
 	}
 
 	return value
@@ -170,20 +166,20 @@ export function readBoolean(
 	path: string,
 	container: Record<string, unknown>,
 	key: string
-): boolean | undefined {
+): boolean | null {
 	const value = container[key]
 	const fieldPath = `${path}.${key}`
 
 	if (value === undefined) {
 		add(issues, fieldPath, ValidationIssueCode.MissingField, `\`${key}\` is required`)
 
-		return undefined
+		return null
 	}
 
 	if (typeof value !== "boolean") {
 		add(issues, fieldPath, ValidationIssueCode.WrongType, `\`${key}\` must be a boolean`)
 
-		return undefined
+		return null
 	}
 
 	return value
@@ -195,7 +191,7 @@ export function readArray(
 	container: Record<string, unknown>,
 	key: string,
 	required: boolean
-): unknown[] | undefined {
+): unknown[] | null {
 	const value = container[key]
 	const fieldPath = `${path}.${key}`
 
@@ -204,13 +200,13 @@ export function readArray(
 			add(issues, fieldPath, ValidationIssueCode.MissingField, `\`${key}\` is required`)
 		}
 
-		return undefined
+		return null
 	}
 
 	if (!Array.isArray(value)) {
 		add(issues, fieldPath, ValidationIssueCode.WrongType, `\`${key}\` must be an array`)
 
-		return undefined
+		return null
 	}
 
 	return value
@@ -222,10 +218,10 @@ export function readStringArray(
 	container: Record<string, unknown>,
 	key: string,
 	required: boolean
-): string[] | undefined {
+): string[] | null {
 	const entries = readArray(issues, path, container, key, required)
 
-	if (!entries) return undefined
+	if (!entries) return null
 
 	const values: string[] = []
 
@@ -238,7 +234,7 @@ export function readStringArray(
 			continue
 		}
 
-		if (!entry.trim().length) {
+		if (!entry.trim()) {
 			add(issues, entryPath, ValidationIssueCode.EmptyValue, "must not be blank")
 
 			continue
@@ -257,10 +253,10 @@ export function readVocabularyValue<T extends string>(
 	key: string,
 	allowed: readonly T[],
 	code: ValidationIssueCode
-): T | undefined {
+): T | null {
 	const value = readString(issues, path, container, key, true)
 
-	if (value === undefined) return undefined
+	if (!value) return null
 
 	const match = allowed.find((candidate) => candidate === value)
 
@@ -268,7 +264,7 @@ export function readVocabularyValue<T extends string>(
 		add(issues, `${path}.${key}`, code, `\`${value}\` is not one of ${listVocabulary(allowed)}`)
 	}
 
-	return match
+	return match ?? null
 }
 
 export function readVocabularyArray<T extends string>(
@@ -278,10 +274,10 @@ export function readVocabularyArray<T extends string>(
 	key: string,
 	allowed: readonly T[],
 	code: ValidationIssueCode
-): T[] | undefined {
+): T[] | null {
 	const values = readStringArray(issues, path, container, key, true)
 
-	if (!values) return undefined
+	if (!values) return null
 
 	const matched: T[] = []
 

package/lib/validation/references.ts

@@ -18,9 +18,10 @@ import type {
 import { add, listVocabulary, type ValidationIssue, ValidationIssueCode } from "#validation/issues"
 
 /**
- * Index a table by identifier, reporting every record after the first that claims an identifier already taken.
+ * Index a table by identifier, reporting every record after the first that
+ * claims an identifier already taken.
  */
-function indexByID<T extends { path: string; id?: string }>(
+function indexByID<T extends { path: string; id: string | null }>(
 	issues: ValidationIssue[],
 	records: readonly T[],
 	label: string
@@ -28,7 +29,7 @@ function indexByID<T extends { path: string; id?: string }>(
 	const index = new Map<string, T>()
 
 	for (const record of records) {
-		if (record.id === undefined) continue
+		if (!record.id) continue
 
 		if (index.has(record.id)) {
 			add(
@@ -48,24 +49,22 @@ function indexByID<T extends { path: string; id?: string }>(
 }
 
 interface EdgeCheck {
-	subjectKind?: ConceptKind
+	subjectKind: ConceptKind | null
 	subjectPath: string
-	relationID?: string
+	relationID: string | null
 	relationPath: string
-	objectID?: string
+	objectID: string | null
 	objectPath: string
 }
 
 /**
- * Resolve one subject–relation–object edge and check it against the relation's declared domain and range kinds.
- *
- * Shared by authored assertions, source observations, and derived facts. The three differ in who stands behind them and
- * in what provenance they carry, and the structural question asked of them is the same one.
+ * Resolve one subject–relation–object edge and check it against the relation's declared domain
+ * and range kinds shared by authored assertions, source observations and derived facts.
  */
 function checkEdge(issues: ValidationIssue[], edge: EdgeCheck, tables: ReferenceTables): void {
-	const relation = edge.relationID === undefined ? undefined : tables.relations.get(edge.relationID)
+	const relation = edge.relationID ? tables.relations.get(edge.relationID) : null
 
-	if (edge.relationID !== undefined && !relation) {
+	if (edge.relationID && !relation) {
 		add(
 			issues,
 			edge.relationPath,
@@ -74,9 +73,9 @@ function checkEdge(issues: ValidationIssue[], edge: EdgeCheck, tables: Reference
 		)
 	}
 
-	const object = edge.objectID === undefined ? undefined : tables.concepts.get(edge.objectID)
+	const object = edge.objectID ? tables.concepts.get(edge.objectID) : null
 
-	if (edge.objectID !== undefined && !object) {
+	if (edge.objectID && !object) {
 		add(
 			issues,
 			edge.objectPath,
@@ -133,7 +132,7 @@ function checkRelation(
 		}
 	}
 
-	if (relation.inverse === undefined) return
+	if (!relation.inverse) return
 
 	const inverse = index.get(relation.inverse)
 
@@ -186,13 +185,11 @@ function checkRelation(
 }
 
 /**
- * Follow `isA` upward from one concept and report the trail if it returns to where it started.
- *
- * The direct self-edge is left out of the walk: `checkIsA` already reports that as a self-reference, at the entry that
- * carries it, and a second report saying the same concept cycles through itself tells its author nothing new.
+ * Follow `isA` upward from one concept and report the trail if it returns to where it started,
+ * leaving the direct self-edge to `checkIsA`'s self-reference report.
  */
-function findIsACycle(start: ConceptView, concepts: ReadonlyMap<string, ConceptView>): string[] | undefined {
-	if (start.id === undefined) return undefined
+function findIsACycle(start: ConceptView, concepts: ReadonlyMap<string, ConceptView>): string[] | null {
+	if (!start.id) return null
 
 	const startID = start.id
 	const visited = new Set<string>()
@@ -217,7 +214,7 @@ function findIsACycle(start: ConceptView, concepts: ReadonlyMap<string, ConceptV
 		}
 	}
 
-	return undefined
+	return null
 }
 
 function checkIsA(issues: ValidationIssue[], concept: ConceptView, concepts: ReadonlyMap<string, ConceptView>): void {
@@ -260,7 +257,7 @@ function checkDerivationInputs(issues: ValidationIssue[], fact: DerivedFactView,
 	}
 
 	for (const input of fact.inputs) {
-		if (input.kind === undefined || input.id === undefined) continue
+		if (!input.kind || !input.id) continue
 
 		if (input.kind === DerivationInputKind.DerivedFact && input.id === fact.id) {
 			add(issues, `${input.path}.id`, ValidationIssueCode.SelfReference, "a derived fact is not one of its own inputs")
@@ -322,7 +319,7 @@ export function checkReferences(issues: ValidationIssue[], view: DocumentView):
 	}
 
 	for (const mapping of view.mappings) {
-		if (mapping.concept !== undefined && !concepts.has(mapping.concept)) {
+		if (mapping.concept && !concepts.has(mapping.concept)) {
 			add(
 				issues,
 				`${mapping.path}.concept`,
@@ -333,9 +330,9 @@ export function checkReferences(issues: ValidationIssue[], view: DocumentView):
 	}
 
 	for (const triple of [...view.observations, ...view.derivedFacts]) {
-		const subject = triple.subject === undefined ? undefined : concepts.get(triple.subject)
+		const subject = triple.subject ? concepts.get(triple.subject) : null
 
-		if (triple.subject !== undefined && !subject) {
+		if (triple.subject && !subject) {
 			add(
 				issues,
 				`${triple.path}.subject`,
@@ -347,7 +344,7 @@ export function checkReferences(issues: ValidationIssue[], view: DocumentView):
 		checkEdge(
 			issues,
 			{
-				subjectKind: subject?.kind,
+				subjectKind: subject?.kind ?? null,
 				subjectPath: `${triple.path}.subject`,
 				relationID: triple.relation,
 				relationPath: `${triple.path}.relation`,

package/out/artifact.d.ts

@@ -3,61 +3,46 @@
  * @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 type { ConceptID, ConceptRecord, DerivedFactRecord, ExternalMappingRecord, RelationRecord, SourceObservationRecord } 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 declare 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;
     ancestors: readonly ConceptID[];
 }
 /**
- * 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[];
@@ -66,18 +51,18 @@ 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 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 declare function serializeCompiledModel(model: CompiledGeographicModel): string;
 /**
@@ -87,13 +72,11 @@ export declare class GeographicModelArtifactError extends Error {
     constructor(message: string);
 }
 /**
- * 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 declare function parseCompiledGeographicModel(input: unknown): CompiledGeographicModel;
 //# sourceMappingURL=artifact.d.ts.map

package/out/artifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../lib/artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,MAAM,SAAS,CAAA;AAEhB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,SAAS,CAAA;IAClB,SAAS,EAAE,SAAS,SAAS,EAAE,CAAA;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IACpC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAClC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAA;IAC1C,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAChD,kBAAkB,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD;;;OAGG;IACH,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAC1C;AA+BD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAE7E;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACtD,YAAY,OAAO,EAAE,MAAM,EAI1B;CACD;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAMpF"}
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../lib/artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,MAAM,SAAS,CAAA;AAEhB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,SAAS,CAAA;IAClB,SAAS,EAAE,SAAS,SAAS,EAAE,CAAA;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IACpC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAClC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAA;IAC1C,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAChD,kBAAkB,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD;;;;OAIG;IACH,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAC1C;AAwBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAE7E;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACtD,YAAY,OAAO,EAAE,MAAM,EAI1B;CACD;AAmCD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAMpF"}

package/out/artifact.js

@@ -3,48 +3,28 @@
  * @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";
 /**
- * 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;
 /**
- * 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) {
     if (Array.isArray(value))
@@ -61,12 +41,11 @@ function canonicalize(value) {
     return canonical;
 }
 /**
- * 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) {
     return prettyJSON(canonicalize(model));
@@ -81,8 +60,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",
@@ -93,33 +71,28 @@ const ARTIFACT_TABLES = [
     "relations",
 ];
 /**
- * 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 `null` when it is one.
  */
 function artifactProblem(value) {
     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) {
+    if (typeof value.modelVersion !== "string" || !value.modelVersion.trim()) {
         return "`modelVersion` must be a non-blank string";
     }
     const missing = ARTIFACT_TABLES.filter((table) => !Array.isArray(value[table]));
     if (!missing.length)
-        return undefined;
+        return null;
     return `the artifact is missing ${missing.map((table) => `\`${table}\``).join(", ")}`;
 }
 /**
- * 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) {
     const problem = artifactProblem(input);

package/out/artifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../lib/artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAWpE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAyCxC;;;;;GAKG;AAEH;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAc;IACnC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IAExD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEvC,MAAM,SAAS,GAA4B,EAAE,CAAA;IAE7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACnE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;QAExB,IAAI,KAAK,KAAK,SAAS;YAAE,SAAQ;QAEjC,SAAS,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC;IAED,OAAO,SAAS,CAAA;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA8B;IACpE,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACtD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAA;QAEd,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;IAC3C,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,eAAe,GAAG;IACvB,UAAU;IACV,cAAc;IACd,oBAAoB;IACpB,UAAU;IACV,cAAc;IACd,WAAW;CACF,CAAA;AAEV;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACtC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,+CAA+C,CAAA;IAEjF,IAAI,KAAK,CAAC,aAAa,KAAK,uBAAuB,EAAE,CAAC;QACrD,OAAO,mDAAmD,uBAAuB,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAA;IAClJ,CAAC;IAED,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;QACjF,OAAO,2CAA2C,CAAA;IACnD,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAE/E,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,SAAS,CAAA;IAErC,OAAO,2BAA2B,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AACtF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAc;IAC1D,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IAEtC,IAAI,OAAO;QAAE,MAAM,IAAI,4BAA4B,CAAC,OAAO,CAAC,CAAA;IAE5D,OAAO,KAAgC,CAAA;AACxC,CAAC"}
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../lib/artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAWpE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAyCxC;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAc;IACnC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IAExD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEvC,MAAM,SAAS,GAA4B,EAAE,CAAA;IAE7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACnE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;QAExB,IAAI,KAAK,KAAK,SAAS;YAAE,SAAQ;QAEjC,SAAS,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC;IAED,OAAO,SAAS,CAAA;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA8B;IACpE,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACtD,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAA;QAEd,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;IAC3C,CAAC;CACD;AAED;;GAEG;AACH,MAAM,eAAe,GAAG;IACvB,UAAU;IACV,cAAc;IACd,oBAAoB;IACpB,UAAU;IACV,cAAc;IACd,WAAW;CACF,CAAA;AAEV;;GAEG;AACH,SAAS,eAAe,CAAC,KAAc;IACtC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,+CAA+C,CAAA;IAEjF,IAAI,KAAK,CAAC,aAAa,KAAK,uBAAuB,EAAE,CAAC;QACrD,OAAO,mDAAmD,uBAAuB,2BAA2B,aAAa,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAA;IACjJ,CAAC;IAED,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1E,OAAO,2CAA2C,CAAA;IACnD,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAE/E,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAEhC,OAAO,2BAA2B,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAc;IAC1D,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IAEtC,IAAI,OAAO;QAAE,MAAM,IAAI,4BAA4B,CAAC,OAAO,CAAC,CAAA;IAE5D,OAAO,KAAgC,CAAA;AACxC,CAAC"}