@mailwoman/geographic-model 10.0.0 → 10.2.0

package/lib/schema.ts

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

package/lib/validate.ts

@@ -3,28 +3,11 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Deterministic validation of a {@link GeographicModelDocument}. Plain TypeScript: no reasoner, no
- *   query engine, no schema library, and no I/O — the same input always produces the same issue list.
+ *   Deterministically validate a {@link GeographicModelDocument} without I/O or external schema libraries. Report all
+ *   issues in traversal order and return either the complete valid document or the full issue list.
  *
- *   The validator reports EVERY violation it finds. A record set is authored by hand and read by a
- *   compiler, so a validator that stops at the first problem hands its author one defect per run. It
- *   also never returns a partial document: either the input satisfies every rule and is returned
- *   whole, or nothing is returned and every issue is named with the path it was found at. There is no
- *   third answer in which some records were dropped quietly, because a dropped record is
- *   indistinguishable from a world that does not contain it.
- *
- *   Two passes, in this order, and both always run:
- *
- *   1. **Shape.** Field presence, field types, closed-vocabulary membership, and unknown keys. An
- *      unknown key whose name announces ranking policy — a boost, a penalty, a weight, a rank, a
- *      score — is reported under its own code rather than as an anonymous stray field, because that
- *      is the one authoring mistake this package exists to refuse.
- *   2. **Whole-table references.** Duplicate identifiers, `isA` self-reference and cycles, relation
- *      and concept resolution, relation domain and range kinds, inverse reciprocity, and derivation
- *      inputs. These are answerable only once every table has been read, which is why they are
- *      reported after the shape issues rather than interleaved with them.
- *
- *   Consumed by #1926's compiler, which validates before it emits, and by #1927's authored document.
+ *   Validate record shapes first, then whole-table references such as duplicate IDs, inheritance cycles, relation
+ *   constraints, inverses and derivation inputs.
  */
 
 import { isPlainObject } from "@mailwoman/core/objects"
@@ -52,8 +35,6 @@ import {
 } from "#validation/issues"
 import { checkReferences } from "#validation/references"
 
-export { type ValidationIssue, ValidationIssueCode } from "#validation/issues"
-
 /**
  * The whole document, or every reason it is not one.
  */
@@ -96,54 +77,53 @@ const DERIVED_FACT_FIELDS = [
 const DERIVATION_INPUT_FIELDS = ["kind", "id"] as const
 
 /**
- * ISO 3166-1 alpha-2, upper case. A lower-case or three-letter value is an authoring mistake that would otherwise scope
- * a claim to a country nothing else in the system names.
+ * Uppercase ISO 3166-1 alpha-2 country code.
  */
 const COUNTRY_PATTERN = /^[A-Z]{2}$/
 
 export interface AssertionView {
 	path: string
-	id?: string
-	relation?: string
-	target?: string
+	id: string | null
+	relation: string | null
+	target: string | null
 }
 
 export interface ConceptView {
 	path: string
-	id?: string
-	kind?: ConceptKind
-	isA?: string[]
+	id: string | null
+	kind: ConceptKind | null
+	isA: string[] | null
 	assertions: AssertionView[]
 }
 
 export interface RelationView {
 	path: string
-	id?: string
-	domainKinds?: ConceptKind[]
-	rangeKinds?: ConceptKind[]
-	transitive?: boolean
-	symmetric?: boolean
-	inverse?: string
+	id: string | null
+	domainKinds: ConceptKind[] | null
+	rangeKinds: ConceptKind[] | null
+	transitive: boolean | null
+	symmetric: boolean | null
+	inverse: string | null
 }
 
 export interface MappingView {
 	path: string
-	id?: string
-	concept?: string
+	id: string | null
+	concept: string | null
 }
 
 export interface TripleView {
 	path: string
-	id?: string
-	subject?: string
-	relation?: string
-	object?: string
+	id: string | null
+	subject: string | null
+	relation: string | null
+	object: string | null
 }
 
 export interface DerivationInputView {
 	path: string
-	kind?: DerivationInputKind
-	id?: string
+	kind: DerivationInputKind | null
+	id: string | null
 }
 
 export interface DerivedFactView extends TripleView {
@@ -209,7 +189,7 @@ function readProvenance(issues: ValidationIssue[], path: string, container: Reco
 }
 
 /**
- * Read the `label` and `description` an authored record carries.
+ * Read required label and description fields.
  */
 function readNarration(issues: ValidationIssue[], path: string, value: Record<string, unknown>): void {
 	readString(issues, path, value, "label", true)
@@ -450,29 +430,26 @@ function collectIssues(input: unknown): ValidationIssue[] {
 /**
  * Validate an authored geographic-model document.
  *
- * Returns the document whole, or every reason it is not one. Issues arrive in traversal order — shape issues per record
- * in table order, then whole-table reference issues — so two runs over the same input produce the same list.
+ * @returns The full document or every validation issue in deterministic order.
  */
 export function validateGeographicModelDocument(input: unknown): ValidationResult {
 	const issues = collectIssues(input)
 
 	if (issues.length) return { ok: false, issues }
 
-	// A clean input IS the document — the validator reads, it never rewrites. Keeping the assertion in this function,
-	// where `input` is still `unknown`, is what makes it a single step rather than a cast through `unknown`.
+	// Return the original document without rewriting it.
 	return { ok: true, document: input as GeographicModelDocument }
 }
 
 /**
- * Render every issue as one line, `path: message [code]`, in the order the validator produced them.
+ * Format issues as `path: message [code]`, preserving their order.
  */
 export function formatValidationIssues(issues: readonly ValidationIssue[]): string {
 	return issues.map((issue) => `${issue.path}: ${issue.message} [${issue.code}]`).join("\n")
 }
 
 /**
- * Thrown by {@link parseGeographicModelDocument}. Carries the whole issue list, and states the whole issue list in its
- * message, so a caller that only ever prints `error.message` still sees every violation.
+ * Validation error carrying the complete issue list in both `issues` and `message`.
  */
 export class GeographicModelValidationError extends Error {
 	readonly issues: readonly ValidationIssue[]
@@ -486,9 +463,8 @@ export class GeographicModelValidationError extends Error {
 }
 
 /**
- * Validate and return an authored document, throwing {@link GeographicModelValidationError} with every violation if it
- * does not validate. The throwing form is for callers with no partial-result behavior to offer — a compiler, a build
- * step, a test.
+ * Validate and return the document, or throw with all issues.
+ * Use when partial results are not meaningful.
  */
 export function parseGeographicModelDocument(input: unknown): GeographicModelDocument {
 	const result = validateGeographicModelDocument(input)