@mailwoman/geographic-model 0.0.0

package/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/geographic-model` — the world-semantic layer: stable concepts beyond the POI
+ *   vocabulary, relation definitions, activities and affordances, rule modality, source
+ *   observations, derived facts, derivation provenance, deterministic compilation and validation,
+ *   and mappings from external vocabularies into world concepts.
+ *
+ *   The public surface is the authored-record schema (`./schema.ts`), its deterministic validator
+ *   (`./validate.ts`), the compiler that turns a validated document into the runtime artifact
+ *   (`./compile.ts`), the artifact's shape and canonical bytes (`./artifact.ts`), and the lookups a
+ *   runtime consumer reads it through (`./lookup.ts`). All five are re-exported here and all five are
+ *   reachable as curated subpaths.
+ *
+ *   The authoring loader (`./load.ts`, the `./load` subpath) is deliberately NOT re-exported here. It
+ *   is the only module in the package that touches a filesystem, and it belongs to the build step that
+ *   produces an artifact rather than to the consumers that read one. The first authored document
+ *   arrives with #1927; this entry point carries no data.
+ *
+ *   Four things this package must never hold, each owned elsewhere and each a rule the review
+ *   applies rather than a preference:
+ *
+ *   1. **Ranking policy.** No weights, boosts, penalties, or candidate-ordering API — not as a
+ *      function, not as a type. Candidate ordering belongs to `@mailwoman/resolver`, and the decode
+ *      objective to `@mailwoman/neural` plus `@mailwoman/core/decoder`. Knowledge here creates
+ *      observations; it never overrides learned interpretation.
+ *   2. **A second POI vocabulary.** External and curated POI categories, their containment
+ *      hierarchy, the Overture-leaf translation, the query-phrase lexicon and the brand table all
+ *      belong to `@mailwoman/poi-taxonomy`. This package maps INTO those identifiers.
+ *   3. **A second coverage register.** Dataset identity and coverage epistemics belong to
+ *      `@mailwoman/core/layers`. An expected-but-absent observation becomes negative evidence only
+ *      where `supportsExclusion` permits it there.
+ *   4. **Empirical affordance statistics.** #1683 fits those. This package owns the stable
+ *      activity and affordance identifiers they are fitted against, and nothing numeric about them.
+ *
+ *   `@mailwoman/core` must not depend on this package. 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. Reversing that direction is an explicit amendment to
+ *   the boundary record, not a convenience during implementation.
+ *
+ *   Boundary record: `docs/superpowers/specs/2026-08-26-geographic-model-boundaries.md` (#1917).
+ *   Program parent: #1916.
+ */
+
+export * from "./artifact.ts"
+export * from "./compile.ts"
+export * from "./lookup.ts"
+export * from "./schema.ts"
+export * from "./validate.ts"

package/load.ts

@@ -0,0 +1,396 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The authoring loader: a directory of JSON files in, one {@link GeographicModelDocument} out.
+ *
+ *   **The filesystem 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. What a
+ *   directory does carry is one manifest — `model.json`, holding the document's `version` — because a
+ *   version assembled from whichever fragment happened to declare one is a version nobody chose.
+ *
+ *   Two properties make the loader safe to build an artifact from:
+ *
+ *   1. **Enumeration order cannot reach the output.** {@link mergeGeographicModelFiles} sorts the
+ *      files it was handed before reading any of them, so the merged tables are a function of the file
+ *      NAMES and their contents. `readdir` order, and therefore the filesystem, is out of the answer.
+ *   2. **Every issue names the file it came from.** The document validator addresses a record by its
+ *      position in the merged table (`$.concepts[7].kind`), which is the one thing an author cannot
+ *      see; the loader keeps a per-record origin and re-addresses each issue to its source file. 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.
+ *
+ *   Validation itself is delegated whole to `./validate.ts`. 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.
+ */
+
+import { readdirSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+import { compareIdentifiers } from "./artifact.ts"
+import type { GeographicModelDocument } from "./schema.ts"
+import { validateGeographicModelDocument } from "./validate.ts"
+import {
+	add,
+	checkFieldNames,
+	isPlainObject,
+	readArray,
+	readString,
+	type ValidationIssue,
+	ValidationIssueCode,
+} from "./validation-issues.ts"
+
+/**
+ * The manifest every model directory carries: the document's `version`, and nothing else.
+ */
+export const MODEL_MANIFEST_FILENAME = "model.json"
+
+/**
+ * The keys a source file may use. They are the document's tables, minus the manifest's `version`.
+ */
+const TABLE_FIELDS = ["relations", "concepts", "mappings", "observations", "derivedFacts"] as const
+
+type TableField = (typeof TABLE_FIELDS)[number]
+
+const MANIFEST_FIELDS = ["version"] as const
+
+/**
+ * The document path a record occupies, e.g. `$.concepts[7]` or `$.concepts[7].assertions[1]`. Group 3 is present only
+ * for an assertion, which is the one record that nests.
+ */
+const RECORD_PATH_PATTERN = /^\$\.([A-Za-z]+)\[(\d+)\](?:\.assertions\[(\d+)\])?/u
+
+/**
+ * Every way loading can fail. The document validator's whole vocabulary, plus the one failure only a loader meets: a
+ * file that is not JSON at all.
+ */
+export const LoadIssueCode = {
+	...ValidationIssueCode,
+	/**
+	 * A source file could not be parsed as JSON. Emitted by the loader alone; the document validator is handed values,
+	 * never text.
+	 */
+	MalformedJSON: "malformed_json",
+} as const
+
+export type LoadIssueCode = (typeof LoadIssueCode)[keyof typeof LoadIssueCode]
+
+/**
+ * One violation, addressed to the file an author can open.
+ */
+export interface SourcedIssue {
+	/**
+	 * The source file, relative to the model directory, with `/` separators on every platform.
+	 */
+	file: string
+	/**
+	 * The JSONPath-style address into the MERGED document, kept so a reader can find the record in the table the
+	 * validator saw.
+	 */
+	path: string
+	code: LoadIssueCode
+	message: string
+	/**
+	 * For a duplicate identifier: the file that claimed it first.
+	 */
+	otherFile?: string
+}
+
+/**
+ * One authoring file: its path relative to the model directory, and its text.
+ */
+export interface GeographicModelSourceFile {
+	path: string
+	text: string
+}
+
+/**
+ * Render every issue as one line, `file:path: message [code]`, in the order the loader produced them.
+ */
+export function formatSourcedIssues(issues: readonly SourcedIssue[]): string {
+	return issues
+		.map((issue) => {
+			const claimant = issue.otherFile ? ` — first claimed in ${issue.otherFile}` : ""
+
+			return `${issue.file}:${issue.path}: ${issue.message}${claimant} [${issue.code}]`
+		})
+		.join("\n")
+}
+
+/**
+ * Thrown when a model directory does not load. Carries every issue, and states them all in its message, so a caller
+ * that only prints `error.message` still sees the whole list.
+ */
+export class GeographicModelLoadError extends Error {
+	readonly issues: readonly SourcedIssue[]
+
+	constructor(issues: readonly SourcedIssue[]) {
+		super(`geographic-model source does not load (${issues.length} issues)\n${formatSourcedIssues(issues)}`)
+
+		this.name = "GeographicModelLoadError"
+		this.issues = issues
+	}
+}
+
+/**
+ * Where one record came from, kept so a validation issue addressed to the merged table can be re-addressed to a file.
+ */
+interface RecordOrigin {
+	file: string
+	/**
+	 * The table the record was appended to, or `assertions` for one nested inside a concept — the namespace its
+	 * identifier is unique within.
+	 */
+	table: string
+	id?: string
+}
+
+interface MergeState {
+	issues: SourcedIssue[]
+	tables: Record<TableField, unknown[]>
+	origins: Map<string, RecordOrigin>
+	/**
+	 * Table → identifier → the file that used it first. The validator reports the SECOND claimant, so this is what names
+	 * the other half of the pair.
+	 */
+	firstClaims: Map<string, Map<string, string>>
+	version?: string
+}
+
+function sourced(file: string, issues: readonly ValidationIssue[]): SourcedIssue[] {
+	return issues.map((issue) => ({ file, path: issue.path, code: issue.code, message: issue.message }))
+}
+
+/**
+ * Parse one source file, or report why it could not be parsed.
+ *
+ * The house wrapper lives in `@mailwoman/core/objects`, and this package takes no dependency on `@mailwoman/core` — the
+ * boundary record keeps world semantics out of core, and a build-time loader is not the reason to reverse it. The
+ * parser's own message is also the useful half of the report here, which a wrapper returning a fallback discards.
+ */
+function readSourceJSON(file: GeographicModelSourceFile, issues: SourcedIssue[]): unknown {
+	try {
+		// oxlint-disable-next-line no-restricted-properties -- see the note above.
+		return JSON.parse(file.text)
+	} catch (error) {
+		issues.push({
+			file: file.path,
+			path: "$",
+			code: LoadIssueCode.MalformedJSON,
+			message: error instanceof Error ? error.message : String(error),
+		})
+
+		return undefined
+	}
+}
+
+function claim(state: MergeState, table: string, id: string | undefined, file: string): void {
+	if (id === undefined) return
+
+	const claims = state.firstClaims.get(table) ?? new Map<string, string>()
+
+	state.firstClaims.set(table, claims)
+
+	if (!claims.has(id)) {
+		claims.set(id, file)
+	}
+}
+
+function recordID(entry: unknown): string | undefined {
+	if (!isPlainObject(entry)) return undefined
+
+	return typeof entry.id === "string" ? entry.id : undefined
+}
+
+function readManifestFile(state: MergeState, file: GeographicModelSourceFile, value: unknown): void {
+	const issues: ValidationIssue[] = []
+
+	if (!isPlainObject(value)) {
+		add(issues, "$", ValidationIssueCode.WrongType, `\`${MODEL_MANIFEST_FILENAME}\` must be an object`)
+	} else {
+		checkFieldNames(issues, "$", value, MANIFEST_FIELDS)
+
+		state.version = readString(issues, "$", value, "version", true)
+	}
+
+	state.issues.push(...sourced(file.path, issues))
+}
+
+/**
+ * Append one file's tables to the merged document, recording where every record came from.
+ */
+function readTableFile(state: MergeState, file: GeographicModelSourceFile, value: unknown): void {
+	const issues: ValidationIssue[] = []
+
+	if (!isPlainObject(value)) {
+		add(issues, "$", ValidationIssueCode.WrongType, "a geographic-model source file must be an object")
+
+		state.issues.push(...sourced(file.path, issues))
+
+		return
+	}
+
+	// `version` is admitted to the field check and then refused on its own, so the report names where a version belongs
+	// instead of only saying the field is unknown here.
+	checkFieldNames(issues, "$", value, [...TABLE_FIELDS, ...MANIFEST_FIELDS])
+
+	if ("version" in value) {
+		add(
+			issues,
+			"$.version",
+			ValidationIssueCode.UnknownField,
+			`the document's \`version\` is authored in \`${MODEL_MANIFEST_FILENAME}\`, not in a table file`
+		)
+	}
+
+	for (const table of TABLE_FIELDS) {
+		if (!(table in value)) continue
+
+		for (const entry of readArray(issues, "$", value, table, false) ?? []) {
+			const index = state.tables[table].length
+			const id = recordID(entry)
+			const documentPath = `${table}[${index}]`
+
+			state.tables[table].push(entry)
+			state.origins.set(documentPath, { file: file.path, table, id })
+			claim(state, table, id, file.path)
+
+			if (table !== "concepts" || !isPlainObject(entry) || !Array.isArray(entry.assertions)) continue
+
+			for (const [position, assertion] of entry.assertions.entries()) {
+				const assertionID = recordID(assertion)
+
+				state.origins.set(`${documentPath}.assertions[${position}]`, {
+					file: file.path,
+					table: "assertions",
+					id: assertionID,
+				})
+
+				claim(state, "assertions", assertionID, file.path)
+			}
+		}
+	}
+
+	state.issues.push(...sourced(file.path, issues))
+}
+
+/**
+ * Re-address one validation issue from its position in the merged document to the file the record was authored in.
+ */
+function attribute(state: MergeState, issue: ValidationIssue): SourcedIssue {
+	const match = RECORD_PATH_PATTERN.exec(issue.path)
+	const nested = match?.[3]
+	const key = match ? `${match[1]}[${match[2]}]${nested ? `.assertions[${nested}]` : ""}` : undefined
+	const origin = key ? state.origins.get(key) : undefined
+
+	// A document-level issue — `$.version`, or the root itself — is about the manifest, which is the only file that
+	// contributes anything outside a table.
+	const file = origin?.file ?? MODEL_MANIFEST_FILENAME
+
+	const claimant =
+		issue.code === ValidationIssueCode.DuplicateID && origin?.id
+			? state.firstClaims.get(origin.table)?.get(origin.id)
+			: undefined
+
+	return {
+		file,
+		path: issue.path,
+		code: issue.code,
+		message: issue.message,
+		...(claimant ? { otherFile: claimant } : {}),
+	}
+}
+
+/**
+ * Merge authoring files into one document, and validate the result.
+ *
+ * The files are sorted by path before anything is read, so any enumeration order produces the same tables in the same
+ * order. Throws {@link GeographicModelLoadError} with every issue, each addressed to its source file; returns nothing
+ * partial.
+ */
+export function mergeGeographicModelFiles(files: readonly GeographicModelSourceFile[]): GeographicModelDocument {
+	const state: MergeState = {
+		issues: [],
+		tables: { relations: [], concepts: [], mappings: [], observations: [], derivedFacts: [] },
+		origins: new Map(),
+		firstClaims: new Map(),
+	}
+
+	const ordered = files.toSorted((left, right) => compareIdentifiers(left.path, right.path))
+	const manifest = ordered.find((file) => file.path === MODEL_MANIFEST_FILENAME)
+
+	if (!manifest) {
+		state.issues.push({
+			file: MODEL_MANIFEST_FILENAME,
+			path: "$",
+			code: LoadIssueCode.MissingField,
+			message: `a model directory carries \`${MODEL_MANIFEST_FILENAME}\`, holding the document's \`version\``,
+		})
+	}
+
+	for (const file of ordered) {
+		const value = readSourceJSON(file, state.issues)
+
+		if (value === undefined) continue
+
+		if (file === manifest) {
+			readManifestFile(state, file, value)
+
+			continue
+		}
+
+		readTableFile(state, file, value)
+	}
+
+	// A record issue cannot be addressed to a file that failed to parse, so the structural pass reports alone.
+	if (state.issues.length) throw new GeographicModelLoadError(state.issues)
+
+	const result = validateGeographicModelDocument({ version: state.version, ...state.tables })
+
+	if (!result.ok) {
+		throw new GeographicModelLoadError(result.issues.map((issue) => attribute(state, issue)))
+	}
+
+	return result.document
+}
+
+/**
+ * Every `*.json` file under `root`, relative to it, in code-point order.
+ *
+ * Directory entries are sorted at each level rather than taken as `readdir` returns them, so the list is a property of
+ * 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 })
+	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))
+
+			continue
+		}
+
+		if (entry.isFile() && entry.name.endsWith(".json")) {
+			found.push(path)
+		}
+	}
+
+	return found
+}
+
+/**
+ * Load a model directory: read every `*.json` file under it, merge them, and validate the result.
+ *
+ * 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") }))
+
+	return mergeGeographicModelFiles(files)
+}

package/lookup.ts

@@ -0,0 +1,129 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The read surface over a compiled artifact: every question answered by one map probe, none by
+ *   walking the graph.
+ *
+ *   The shape is deliberate. `@mailwoman/geographic-model` compiles authored records into an artifact
+ *   precisely so a runtime consumer never traverses anything — so the index exposes lookups
+ *   (`concept`, `ancestorsOf`, `derivedFactsAbout`, `conceptsForExternalID`) and no walk, no cursor,
+ *   and no query language.
+ *
+ *   Two absences are distinguished everywhere, because they are different answers. A lookup for a
+ *   concept the artifact does not carry returns `undefined` — the model cannot speak to it. A lookup
+ *   for a concept it does carry, which nothing was derived about, returns an empty list — the model
+ *   carries it and states nothing. A reader that collapsed the two would report "no ancestors" for a
+ *   concept it had never heard of.
+ */
+
+import type { POICategoryID } from "@mailwoman/poi-taxonomy/types"
+
+import { type CompiledGeographicModel, compareIdentifiers } from "./artifact.ts"
+import type {
+	ConceptID,
+	ConceptRecord,
+	DerivedFactRecord,
+	ExternalVocabulary,
+	RelationID,
+	RelationRecord,
+} from "./schema.ts"
+
+/**
+ * Lookups over one compiled artifact.
+ */
+export interface GeographicModelIndex {
+	/**
+	 * The artifact these lookups read, so a consumer holding the index never has to carry both.
+	 */
+	readonly model: CompiledGeographicModel
+	/**
+	 * One concept record, or `undefined` when the artifact does not carry it.
+	 */
+	concept(id: ConceptID): ConceptRecord | undefined
+	/**
+	 * One relation definition, or `undefined` when the artifact does not carry it.
+	 */
+	relation(id: RelationID): RelationRecord | undefined
+	/**
+	 * Every concept this one is a kind of, transitively, in code-point order. Empty for a concept that is a kind of
+	 * nothing; `undefined` for a concept the artifact does not carry.
+	 */
+	ancestorsOf(id: ConceptID): readonly ConceptID[] | undefined
+	/**
+	 * Every derived fact whose subject is this concept, in artifact order. Empty for a concept nothing was derived about;
+	 * `undefined` for a concept the artifact does not carry.
+	 */
+	derivedFactsAbout(id: ConceptID): readonly DerivedFactRecord[] | undefined
+	/**
+	 * The concepts a mapping translates this external identifier into, in code-point order.
+	 *
+	 * An empty list is a true negative rather than an unread answer: the artifact carries every mapping the document
+	 * authored, so nothing having declared this identifier is the whole of what there is to know about it.
+	 */
+	conceptsForExternalID(vocabulary: ExternalVocabulary, externalID: POICategoryID): readonly ConceptID[]
+}
+
+function externalKey(vocabulary: ExternalVocabulary, externalID: string): string {
+	return `${vocabulary}\u0000${externalID}`
+}
+
+/**
+ * Index a compiled artifact for reading.
+ *
+ * Every table is walked once here so that no table is ever walked again. Nothing is copied — the records handed back
+ * are the artifact's own.
+ */
+export function createGeographicModelIndex(model: CompiledGeographicModel): GeographicModelIndex {
+	const concepts = new Map<string, ConceptRecord>(model.concepts.map((concept) => [String(concept.id), concept]))
+	const relations = new Map<string, RelationRecord>(model.relations.map((relation) => [String(relation.id), relation]))
+
+	const ancestors = new Map<string, readonly ConceptID[]>(
+		model.inheritanceClosure.map((entry) => [String(entry.concept), entry.ancestors])
+	)
+
+	const facts = new Map<string, DerivedFactRecord[]>()
+	const external = new Map<string, ConceptID[]>()
+
+	for (const fact of model.derivedFacts) {
+		const subject = String(fact.subject)
+		const existing = facts.get(subject)
+
+		if (existing) {
+			existing.push(fact)
+
+			continue
+		}
+
+		facts.set(subject, [fact])
+	}
+
+	for (const mapping of model.mappings) {
+		const key = externalKey(mapping.vocabulary, String(mapping.externalID))
+		const existing = external.get(key)
+
+		if (!existing) {
+			external.set(key, [mapping.concept])
+
+			continue
+		}
+
+		if (!existing.includes(mapping.concept)) {
+			existing.push(mapping.concept)
+		}
+	}
+
+	return {
+		model,
+		concept: (id) => concepts.get(String(id)),
+		relation: (id) => relations.get(String(id)),
+		ancestorsOf: (id) => ancestors.get(String(id)),
+		derivedFactsAbout: (id) => (concepts.has(String(id)) ? (facts.get(String(id)) ?? []) : undefined),
+		conceptsForExternalID: (vocabulary, externalID) => {
+			const matches = external.get(externalKey(vocabulary, String(externalID)))
+
+			return matches ? matches.toSorted(compareIdentifiers) : []
+		},
+	}
+}

package/out/artifact.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ *
+ *   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.
+ *
+ *   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).
+ */
+import type { ConceptID, ConceptRecord, DerivedFactRecord, ExternalMappingRecord, RelationRecord, SourceObservationRecord } from "./schema.ts";
+/**
+ * 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.
+ *
+ * It is not data about the world, which is why a number is allowed here and nowhere in `./schema.ts`.
+ */
+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.
+ *
+ * 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.
+ */
+export interface InheritanceClosureEntry {
+    concept: ConceptID;
+    ancestors: readonly ConceptID[];
+}
+/**
+ * The whole 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.
+ */
+export interface CompiledGeographicModel {
+    /**
+     * The format version of this artifact — {@link ARTIFACT_SCHEMA_VERSION} at the time it was written.
+     */
+    schemaVersion: number;
+    /**
+     * The authored document's own `version`. Never a build date.
+     */
+    modelVersion: string;
+    relations: readonly RelationRecord[];
+    concepts: readonly ConceptRecord[];
+    mappings: readonly ExternalMappingRecord[];
+    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.
+     */
+    derivedFacts: readonly DerivedFactRecord[];
+}
+/**
+ * The artifact's stated order: UTF-16 code point, ascending.
+ *
+ * `String.prototype.localeCompare` is the trap this exists to avoid — its answer depends on the machine's collation, so
+ * an artifact ordered with it is reproducible only on the machine that built it.
+ */
+export declare function compareIdentifiers(left: string, right: string): number;
+/**
+ * The artifact's canonical bytes: tab-indented, one trailing newline, keys in code-point order.
+ *
+ * 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.
+ */
+export declare function serializeCompiledModel(model: CompiledGeographicModel): string;
+/**
+ * Thrown when a value cannot be read as a compiled artifact.
+ */
+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}.
+ *
+ * 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.
+ */
+export declare function parseCompiledGeographicModel(input: unknown): CompiledGeographicModel;
+//# sourceMappingURL=artifact.d.ts.map

package/out/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACX,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,MAAM,aAAa,CAAA;AAGpB;;;;;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;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMtE;AAwBD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAE7E;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;gBAC1C,OAAO,EAAE,MAAM;CAK3B;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAMpF"}