@mailwoman/geographic-model 10.0.0 → 10.1.0

package/lib/compile.ts

@@ -3,32 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Deterministic compilation of a validated {@link GeographicModelDocument} into the runtime artifact.
+ *   Compiles a validated {@link GeographicModelDocument} into the runtime artifact deterministically.
  *
- *   The compiler validates by DELEGATION: `parseGeographicModelDocument` is the only thing that
- *   decides whether a document is well formed, and it throws with every violation before a single byte
- *   is computed. There is no second validator here, and no partial artifact on failure — a compile
- *   either produces the whole artifact or produces nothing.
+ *   `parseGeographicModelDocument` performs all document validation and throws before compilation
+ *   starts. A compile either returns the whole artifact or throws.
  *
- *   **`isA` alone defines semantic inheritance.** Two things follow from it, and they are the whole
- *   derivation surface:
+ *   Only `isA` defines inheritance. The compiler materializes the transitive `isA` closure for each
+ *   concept. It copies each ancestor's assertions onto descendants as {@link DerivedFactRecord}
+ *   entries. The compiler does not close over relations marked `transitive` or `inverse`.
  *
- *   1. The transitive `isA` closure is materialized per concept, so a consumer asks "what is this a
- *      kind of" with one lookup rather than by walking the graph at query time.
- *   2. Every assertion an ancestor carries is materialized onto its descendants as a
- *      {@link DerivedFactRecord}, naming {@link DERIVATION_ISA_INHERITANCE} and every record the
- *      derivation read. Without this a consumer would still be traversing — the closure alone tells it
- *      which concepts to go and read, which is the traversal it was supposed to be spared.
- *
- *   A relation declaring `transitive` or `inverse` is NOT closed over. Those fields are vocabulary
- *   describing what the relation means; materializing them is a reasoning step no executable need has
- *   asked for, and the boundary record excludes general reasoning from this package. The day one is
- *   needed it arrives as its own named derivation beside this one.
- *
- *   Cycles never reach the derivations: `parseGeographicModelDocument` refuses a direct or indirect
- *   `isA` cycle and names the trail it followed, so a cyclic document fails as a validation error
- *   rather than as a hang. The walk below is breadth-first over a visited set regardless, which makes
- *   it total for any graph rather than for the graphs the validator happens to admit.
+ *   The validator rejects `isA` cycles, but the ancestor walk also tracks visited concepts, so it
+ *   terminates on any graph.
  */
 
 import { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
@@ -48,34 +33,38 @@ import {
 } from "#schema"
 import { parseGeographicModelDocument } from "#validate"
 /**
- * The name a fact derived by `isA` inheritance carries in its `derivation` field. A consumer branches on this rather
- * than on where the record sits.
+ * The `derivation` value of a fact derived by `isA` inheritance.
  */
 export const DERIVATION_ISA_INHERITANCE = "isa-assertion-inheritance"
 
 /**
- * Every way compilation can refuse a document the validator accepted.
+ * Reasons that compilation rejects a document that passed validation.
  *
- * Both are discovered while writing derived records, which is why the validator cannot report them: they are properties
- * of what the compiler is about to write, not of what the author wrote.
+ * Both problems concern the derived records.
+ * The validator never sees those records.
  */
 export const CompileIssueCode = {
 	/**
-	 * An inherited assertion would land on a concept whose kind the relation does not accept on the asserting side.
-	 * Emitting it would put a record in the artifact that the document validator would reject if it were authored.
+	 * An inherited assertion would apply to a concept whose kind the relation's `domainKinds` excludes.
 	 */
 	InheritedDomainKindMismatch: "inherited_domain_kind_mismatch",
 	/**
-	 * Two derived facts claim one identifier. Reachable when an authored derived fact takes an identifier a derivation
-	 * also produces, or when authored identifiers carry the separators the derived form is built from.
+	 * Two derived facts share one identifier.
+	 *
+	 * This happens when an authored derived fact uses an identifier that a derivation also
+	 * produces, or when authored identifiers contain the separators of the derived form.
 	 */
 	DuplicateDerivedFactID: "duplicate_derived_fact_id",
 } as const
 
+/**
+ * A {@link CompileIssueCode} value.
+ */
+
 export type CompileIssueCode = (typeof CompileIssueCode)[keyof typeof CompileIssueCode]
 
 /**
- * One reason a document that validates does not compile.
+ * One reason that a valid document does not compile.
  */
 export interface CompileIssue {
 	code: CompileIssueCode
@@ -83,8 +72,8 @@ export interface CompileIssue {
 }
 
 /**
- * Thrown by {@link compileGeographicModel}. Carries every reason at once, and states them all in its message, so a
- * caller that only prints `error.message` still sees the whole list.
+ * The error that {@link compileGeographicModel} throws.
+ * Its message lists every issue.
  */
 export class GeographicModelCompileError extends Error {
 	readonly issues: readonly CompileIssue[]
@@ -100,8 +89,8 @@ export class GeographicModelCompileError extends Error {
 }
 
 /**
- * The order derivation inputs are listed in. Grouping by table first keeps a long input list readable; the identifier
- * breaks ties inside a table.
+ * Sort order of derivation inputs by kind.
+ * Identifiers break ties within a kind.
  */
 const DERIVATION_INPUT_ORDER: readonly DerivationInputKind[] = [
 	DerivationInputKind.Concept,
@@ -113,14 +102,14 @@ const DERIVATION_INPUT_ORDER: readonly DerivationInputKind[] = [
 ]
 
 /**
- * The separator for the compound keys this module groups by. `U+0000` cannot appear in a readable identifier without
- * being visible in it, so two different key tuples cannot collapse onto one string. The derived IDENTIFIERS written
- * into the artifact use readable separators instead, and are checked for collisions once they are all built.
+ * Separator for internal grouping keys.
+ *
+ * Identifiers never contain `U+0000`, so distinct key tuples cannot produce the same string.
  */
 const KEY_SEPARATOR = "\u0000"
 
 /**
- * The separator between country codes inside a derived identifier.
+ * Separator between country codes in a derived identifier.
  */
 const COUNTRY_SEPARATOR = "+"
 
@@ -129,11 +118,8 @@ function compareByID(left: { id: string }, right: { id: string }): number {
 }
 
 /**
- * Walk `isA` upward from one concept and return every concept reachable, in code-point order.
- *
- * Breadth-first over a visited set: each concept is expanded once, so the walk terminates on any graph and the answer
- * does not depend on how the parents were authored. The concept itself is never in its own list — it could only get
- * there around a cycle, and the validator refuses those before the compiler runs.
+ * Returns every concept reachable from `conceptID` through `isA`, sorted by code point.
+ * The result excludes the concept itself.
  */
 function ancestorsOfConcept(
 	conceptID: ConceptID,
@@ -142,8 +128,8 @@ function ancestorsOfConcept(
 	const visited = new Set<string>()
 	const frontier: ConceptID[] = [...(parents.get(conceptID) ?? [])]
 
-	// An array iterator reads entries appended during the walk, which is what makes this breadth-first rather than a
-	// pass over the direct parents.
+	// The array iterator also visits entries pushed during the loop.
+	// This makes the walk breadth-first.
 	for (const next of frontier) {
 		if (next === conceptID || visited.has(next)) continue
 
@@ -157,9 +143,12 @@ function ancestorsOfConcept(
 }
 
 /**
- * One derived fact under construction. Drafts are keyed by the proposition they state, so two ancestors asserting the
- * same thing produce ONE fact naming both of them as inputs, while two ancestors asserting the same triple under
- * different modality produce two facts — a contradiction a consumer can see, rather than a silent choice between them.
+ * One derived fact under construction.
+ *
+ * Drafts are keyed by subject, relation, target, modality and countries.
+ * Two ancestors with the same assertion produce one fact that lists both as inputs.
+ *
+ * Assertions that differ only in modality produce separate facts, so a contradiction stays visible.
  */
 interface DerivedDraft {
 	subject: ConceptID
@@ -183,8 +172,9 @@ function draftInputs(draft: DerivedDraft): DerivationInput[] {
 }
 
 /**
- * The identifier a derived fact carries. Built from the proposition it states, so it is stable across edits elsewhere
- * in the document, and readable, so a reader meeting one in a diff can tell what it says.
+ * Builds a readable derived-fact identifier from the fact's proposition.
+ *
+ * The identifier stays stable when unrelated parts of the document change.
  */
 function derivedFactID(draft: DerivedDraft): string {
 	const scope = draft.countries?.length ? `:${draft.countries.join(COUNTRY_SEPARATOR)}` : ""
@@ -194,7 +184,7 @@ function derivedFactID(draft: DerivedDraft): string {
 }
 
 /**
- * The relation and target one assertion is about — the pair a descendant's own assertion speaks for.
+ * Returns a key for an assertion's relation and target.
  */
 function edgeKey(assertion: RelationAssertion): string {
 	return `${assertion.relation}${KEY_SEPARATOR}${assertion.target}`
@@ -207,11 +197,9 @@ function draftKey(subject: ConceptID, assertion: RelationAssertion, countries: r
 }
 
 /**
- * Materialize every ancestor's assertions onto their descendants.
+ * Copies each ancestor's assertions onto its descendants as derived facts.
  *
- * A concept that authors its own assertion for the same relation and target inherits nothing for that pair. The
- * authored record is the more specific one, which is what `isA` means, and re-stating the pair would put two modalities
- * for one proposition into the artifact with no rule saying which of them holds.
+ * A concept's own assertion for a relation and target overrides every inherited assertion for that pair.
  */
 function deriveInheritedFacts(
 	concepts: readonly ConceptRecord[],
@@ -233,9 +221,8 @@ function deriveInheritedFacts(
 		for (const ancestorID of entry.ancestors) {
 			const ancestor = conceptByID.get(String(ancestorID))
 
-			// Validation refuses an `isA` naming an undeclared concept, and an assertion naming an undeclared relation,
-			// so both resolve for any document that reached the compiler. The guards keep the walk total; they do not
-			// describe a state the artifact can hold.
+			// Validation guarantees that every referenced concept and relation exists.
+			// These guards only satisfy the type checker.
 			if (!ancestor) continue
 
 			for (const assertion of ancestor.assertions) {
@@ -305,14 +292,12 @@ function checkDerivedIdentifiers(facts: readonly DerivedFactRecord[], issues: Co
 }
 
 /**
- * Compile an authored geographic-model document into its runtime artifact.
+ * Compiles an authored geographic-model document into its runtime artifact.
  *
- * Throws `GeographicModelValidationError` with every violation if the input is not a valid document, and
- * {@link GeographicModelCompileError} with every reason if it validates but its derivations cannot be written. Nothing
- * partial is ever returned.
+ * The artifact's tables are new sorted arrays that hold the authored records unchanged.
  *
- * The document is read, never rewritten: the artifact's tables are new arrays holding the authored records themselves,
- * ordered by identifier, and the derived tables are new records built beside them.
+ * @throws {GeographicModelValidationError} When the input is not a valid document.
+ * @throws {GeographicModelCompileError} When the document is valid but its derived facts are invalid.
  */
 export function compileGeographicModel(input: unknown): CompiledGeographicModel {
 	const document: GeographicModelDocument = parseGeographicModelDocument(input)

package/lib/index.ts

@@ -3,45 +3,31 @@
  * @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.
+ * `@mailwoman/geographic-model` — the world-semantic layer: stable concepts beyond the POI
+ * vocabulary, relation definitions, activities, affordances, rule modality, source observations,
+ * derived facts, derivation provenance, deterministic compilation, plus validation.
  *
- *   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 belongs to the build step rather than
+ * to the consumers that read an artifact.
  *
- *   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:
  *
- *   Four things this package must never hold, each owned elsewhere and each a rule the review
- *   applies rather than a preference:
+ * 1. The resolver owns ranking policy. It defines weights, boosts, penalties and candidate order.
+ *    The resolver package also owns rank order. The neural package and `@mailwoman/core/decoder` own
+ *    the decode objective. This package creates observations and leaves candidate order to the resolver.
+ * 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 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`, and an expected-but-absent observation becomes negative evidence only
+ *    where `supportsExclusion` permits it there.
+ * 4. Empirical affordance statistics — this package owns the stable activity and affordance identifiers.
+ *    It does not own numeric values fitted against those identifiers.
  *
- *   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.
+ * `@mailwoman/core` must not depend on this package: core ships the pipeline interface 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.
  */
 
 export * from "#artifact"

package/lib/load.ts

@@ -3,27 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The authoring loader: a directory of JSON files in, one {@link GeographicModelDocument} out.
+ *   Loads a directory of JSON files into one {@link GeographicModelDocument}.
  *
- *   **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.
+ *   File layout does not assign meaning to a file. Any file may hold any subset of the tables.
+ *   Only `model.json` may declare the document's `version`.
  *
- *   Two properties make the loader safe to build an artifact from:
+ *   The loader sorts files by path before reading them, so directory enumeration order never affects
+ *   the output. It records the source file of every record and maps each validation issue back to that
+ *   file. A duplicate-identifier issue also reports the file that used the identifier first.
  *
- *   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.
+ *   `./validate.ts` performs document validation. The loader checks only that each file parses, holds
+ *   an object and uses known table keys.
  */
 
 import { readLocalTextFile } from "@mailwoman/core/fs/readers"
@@ -43,12 +33,13 @@ import {
 	ValidationIssueCode,
 } from "#validation/issues"
 /**
- * The manifest every model directory carries: the document's `version`, and nothing else.
+ * The manifest file that every model directory contains.
+ * It holds only the document's `version`.
  */
 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`.
+ * The table keys that a non-manifest source file may use.
  */
 const TABLE_FIELDS = ["relations", "concepts", "mappings", "observations", "derivedFacts"] as const
 
@@ -57,49 +48,49 @@ 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.
+ * Matches a record's path in the merged document, such as `$.concepts[7]` or `$.concepts[7].assertions[1]`.
+ * Group 3 matches only for a nested assertion.
  */
 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.
+ * Load issue codes: every validation code plus `MalformedJSON`.
  */
 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.
+	 * A source file is not valid JSON.
 	 */
 	MalformedJSON: "malformed_json",
 } as const
 
+/**
+ * A {@link LoadIssueCode} value.
+ */
 export type LoadIssueCode = (typeof LoadIssueCode)[keyof typeof LoadIssueCode]
 
 /**
- * One violation, addressed to the file an author can open.
+ * One load issue, attributed to its source file.
  */
 export interface SourcedIssue {
 	/**
-	 * The source file, relative to the model directory, with `/` separators on every platform.
+	 * The source file path 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.
+	 * The JSONPath-style location in the merged document.
 	 */
 	path: string
 	code: LoadIssueCode
 	message: string
 	/**
-	 * For a duplicate identifier: the file that claimed it first.
+	 * For a duplicate identifier, the file that used the identifier first.
 	 */
 	otherFile?: string
 }
 
 /**
- * One authoring file: its path relative to the model directory, and its text.
+ * A source file's path relative to the model directory, plus its text.
  */
 export interface GeographicModelSourceFile {
 	path: string
@@ -107,7 +98,7 @@ export interface GeographicModelSourceFile {
 }
 
 /**
- * Render every issue as one line, `file:path: message [code]`, in the order the loader produced them.
+ * Formats each issue as one `file:path: message [code]` line, in input order.
  */
 export function formatSourcedIssues(issues: readonly SourcedIssue[]): string {
 	return issues
@@ -120,8 +111,8 @@ export function formatSourcedIssues(issues: readonly SourcedIssue[]): string {
 }
 
 /**
- * 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.
+ * The error thrown when a model directory does not load.
+ * Its message lists every issue.
  */
 export class GeographicModelLoadError extends Error {
 	readonly issues: readonly SourcedIssue[]
@@ -135,13 +126,13 @@ export class GeographicModelLoadError extends Error {
 }
 
 /**
- * Where one record came from, kept so a validation issue addressed to the merged table can be re-addressed to a file.
+ * The source of one record in the merged document.
  */
 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.
+	 * The record's table, or `assertions` for an assertion nested in a concept.
+	 * Identifiers are unique within a table.
 	 */
 	table: string
 	id?: string
@@ -152,8 +143,8 @@ interface MergeState {
 	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.
+	 * Maps each table to its identifiers and the file that used each identifier first.
+	 * The validator reports only the second use.
 	 */
 	firstClaims: Map<string, Map<string, string>>
 	version?: string
@@ -164,11 +155,9 @@ function sourced(file: string, issues: readonly ValidationIssue[]): SourcedIssue
 }
 
 /**
- * Parse one source file, or report why it could not be parsed.
+ * Parses one source file, or records the parse failure and returns `undefined`.
  *
- * 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.
+ * The loader calls `JSON.parse` directly because the report needs the parser's error message.
  */
 function readSourceJSON(file: GeographicModelSourceFile, issues: SourcedIssue[]): unknown {
 	try {
@@ -219,7 +208,7 @@ function readManifestFile(state: MergeState, file: GeographicModelSourceFile, va
 }
 
 /**
- * Append one file's tables to the merged document, recording where every record came from.
+ * Appends one file's tables to the merged document and records each record's origin.
  */
 function readTableFile(state: MergeState, file: GeographicModelSourceFile, value: unknown): void {
 	const issues: ValidationIssue[] = []
@@ -232,8 +221,7 @@ function readTableFile(state: MergeState, file: GeographicModelSourceFile, value
 		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.
+	// The field check allows `version` so that the specific error below can say where it belongs.
 	checkFieldNames(issues, "$", value, [...TABLE_FIELDS, ...MANIFEST_FIELDS])
 
 	if ("version" in value) {
@@ -277,7 +265,7 @@ function readTableFile(state: MergeState, file: GeographicModelSourceFile, value
 }
 
 /**
- * Re-address one validation issue from its position in the merged document to the file the record was authored in.
+ * Attributes one validation issue to the file that contains the record.
  */
 function attribute(state: MergeState, issue: ValidationIssue): SourcedIssue {
 	const match = RECORD_PATH_PATTERN.exec(issue.path)
@@ -285,8 +273,7 @@ function attribute(state: MergeState, issue: ValidationIssue): SourcedIssue {
 	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.
+	// Only the manifest contributes fields outside the tables, so it owns document-level issues.
 	const file = origin?.file ?? MODEL_MANIFEST_FILENAME
 
 	const claimant =
@@ -304,11 +291,11 @@ function attribute(state: MergeState, issue: ValidationIssue): SourcedIssue {
 }
 
 /**
- * Merge authoring files into one document, and validate the result.
+ * Merges source files into one document and validates it.
+ *
+ * The function sorts files by path first, so the input order never affects 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.
+ * @throws {GeographicModelLoadError} With every issue, each attributed to its source file.
  */
 export function mergeGeographicModelFiles(files: readonly GeographicModelSourceFile[]): GeographicModelDocument {
 	const state: MergeState = {
@@ -344,7 +331,7 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
 		readTableFile(state, file, value)
 	}
 
-	// A record issue cannot be addressed to a file that failed to parse, so the structural pass reports alone.
+	// Validation issues cannot be attributed reliably after a structural failure, so those failures stop here.
 	if (state.issues.length) throw new GeographicModelLoadError(state.issues)
 
 	const result = validateGeographicModelDocument({ version: state.version, ...state.tables })
@@ -357,11 +344,9 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
 }
 
 /**
- * Every `*.json` file under `root`, relative to it, in code-point order.
+ * Lists every `*.json` file under `root` as a relative path, sorted by code point at each level.
  *
- * 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.
+ * Symbolic links are skipped because only regular files and directories match.
  */
 async function listSourceFiles(root: string, prefix = ""): Promise<string[]> {
 	const entries = await Globerator.from("*", {
@@ -390,9 +375,9 @@ async function listSourceFiles(root: string, prefix = ""): Promise<string[]> {
 }
 
 /**
- * Load a model directory: read every `*.json` file under it, merge them, and validate the result.
+ * Reads every `*.json` file under `root`, merges the files and validates the merged document.
  *
- * Throws {@link GeographicModelLoadError} with every issue, each addressed to its source file.
+ * @throws {GeographicModelLoadError} With every issue, each attributed to its source file.
  */
 export async function loadGeographicModelDirectory(root: string): Promise<GeographicModelDocument> {
 	const paths = await listSourceFiles(root)