@mailwoman/geographic-model 10.0.0 → 10.2.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,14 +143,17 @@ 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
 	assertion: RelationAssertion
-	countries?: readonly string[]
+	countries: readonly string[] | null
 	inputs: Map<string, DerivationInput>
 }
 
@@ -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,24 +184,22 @@ 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}`
 }
 
-function draftKey(subject: ConceptID, assertion: RelationAssertion, countries: readonly string[] | undefined): string {
+function draftKey(subject: ConceptID, assertion: RelationAssertion, countries: readonly string[] | null): string {
 	const scope = countries?.join(COUNTRY_SEPARATOR) ?? ""
 
 	return `${subject}${KEY_SEPARATOR}${edgeKey(assertion)}${KEY_SEPARATOR}${assertion.modality}${KEY_SEPARATOR}${scope}`
 }
 
 /**
- * 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) {
@@ -256,7 +243,7 @@ function deriveInheritedFacts(
 					continue
 				}
 
-				const countries = assertion.countries?.length ? assertion.countries.toSorted(compareIdentifiers) : undefined
+				const countries = assertion.countries?.length ? assertion.countries.toSorted(compareIdentifiers) : null
 				const key = draftKey(concept.id, assertion, countries)
 				const existing = drafts.get(key)
 				const draft: DerivedDraft = existing ?? { subject: concept.id, assertion, countries, inputs: new Map() }
@@ -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"
@@ -49,3 +35,4 @@ export * from "#compile"
 export * from "#lookup"
 export * from "#schema"
 export * from "#validate"
+export { type ValidationIssue, ValidationIssueCode } from "#validation/issues"