@instruments/taxonomy 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,28 +1,300 @@
-interface TaxonomyTerm {
+import { R as RelationPredicate, T as Term, M as MatchStrength } from './match-CWzTEuL-.js';
+export { A as AlternativeReason, b as AlternativesMatch, c as BundleMatch, d as BundleMember, a as BundleMemberInput, B as BundleRole, e as BundleSearch, f as CandidateAnnotations, C as CanonicalAlternatives, g as CanonicalBundle, D as DEFAULT_BUNDLE_ROLE, E as ExternalMapping, h as ExternalScheme, i as MATCH_TEST_VECTORS, j as MATCH_WEIGHTS, k as MatchTestCandidate, l as MatchTestVector, m as MatchTier, P as PeriodSpan, n as RankedCandidate, o as RelationRole, S as SearchOptions, p as SearchedWithout, q as SourceBasis, r as StyleKind, s as TermProvenance, t as TermRelation, u as TermStatus, v as TermUsage, U as UsageBand, w as UsageWithheld, x as defineAlternatives, y as defineBundle, z as matchAlternatives, F as matchBundle, G as searchBundle } from './match-CWzTEuL-.js';
+export { C as CrosswalkMapping, a as ambiguousMapping, b as approximateMapping, c as constitutiveMapping, d as declinedMapping, r as resolvedMapping } from './mapping-pvHk5VjC.js';
+export { AmbiguousAssertionMeaning, AmbiguousCanonicalisation, AssertionAuthority, AssertionMeaning, AssertionPolarity, AssertionProvenance, AssertionRole, AssertionScope, CanonicalisationInput, CanonicalisationVerdict, DeclinedCanonicalisation, PORTABLE_ASSERTION_TEST_VECTORS, PortableAssertionTestVector, PortableTasteAssertion, ProjectContextAssertion, RequirementAssertion, RequirementConstraint, RequirementOperator, ResolvedAssertionMeaning, ResolvedCanonicalisation, TASTE_ASSERTION_CONTRACT_VERSION, TAXONOMY_SNAPSHOT_VERSION, TasteAssertion, UnresolvedAssertionMeaning, UnresolvedCanonicalisation, assertionMeaningFrom } from './taste.js';
+
+/** The relation predicates, at runtime. TypeScript cannot enumerate a union, so this is by hand. */
+declare const RELATION_PREDICATES: readonly ["blend-of", "evokes", "influenced-by", "part-of", "reads-as", "related-to", "serves", "suitable-for", "typically-in"];
+/** Where a canonical term lives, and what it is called in the one spelling that counts. */
+interface TermLocation {
+    axisId: string;
+    facetId: string;
+    termId: string;
+    /** `<axis>.<term>`, or `<axis>.<facet>.<term>` on a faceted axis. ADR 0001's target form. */
+    qualifiedId: string;
+    term: Term;
+}
+/** A parsed assertion: an optional relation predicate wrapping a term reference. */
+interface ParsedAssertion {
+    predicate?: RelationPredicate;
+    /** The term reference, verbatim and unfolded. */
+    target: string;
+}
+interface ResolvedAssertion extends ParsedAssertion {
+    location: TermLocation;
+    /** The spelling the matcher compares on: `predicate(qualifiedId)` or a bare `qualifiedId`. */
+    canonical: string;
+    /** True when the named term is deprecated. Resolves anyway; a published id must keep resolving. */
+    deprecated: boolean;
+    /** The term that replaced it, when deprecated. */
+    supersededBy?: string;
+}
+/**
+ * Split `evokes(place.region.nordic)` into its predicate and target. A bare term reference parses
+ * to a target and no predicate. An unrecognised predicate does NOT parse: `foo(bar)` is not an
+ * assertion with an exotic predicate, it is a string nobody has defined.
+ */
+declare const parseAssertion: (assertion: string) => ParsedAssertion | undefined;
+/** Every canonical term, with the qualified id that names it. */
+declare const TERM_LOCATIONS: readonly TermLocation[];
+/** Every accepted spelling of every term, folded. Exported so a consumer can size the vocabulary. */
+declare const ASSERTION_KEYS: ReadonlySet<string>;
+/** Resolve any published spelling of a term to the one location it names. */
+declare const resolveTerm: (reference: string) => TermLocation | undefined;
+/**
+ * Resolve a whole assertion, predicate included. Returns undefined when the predicate is not one
+ * `term.ts` defines, or when the target names no canonical term.
+ */
+declare const resolveAssertion: (assertion: string) => ResolvedAssertion | undefined;
+/**
+ * The spelling the matcher compares on.
+ *
+ * An assertion this package cannot resolve folds to ITSELF rather than to nothing. That is the
+ * difference between a matcher and a gate: a consumer's private tag must still match its own
+ * counterpart on the other side, and only the canon's own artefacts are held to resolving.
+ */
+declare const canonicalAssertion: (assertion: string) => string;
+/** True when this package can resolve the assertion to a canonical term. */
+declare const isCanonicalAssertion: (assertion: string) => boolean;
+/** The assertions this package cannot resolve, in input order. The failure message IS the work item. */
+declare const unknownAssertions: (assertions: Iterable<string>) => readonly string[];
+/** Assertions naming a term that still resolves but has been superseded, with its successor. */
+declare const deprecatedAssertions: (assertions: Iterable<string>) => readonly {
+    assertion: string;
+    supersededBy: string;
+}[];
+
+/**
+ * The SKOS property each strength renders to.
+ *
+ * `skos:relatedMatch`, not `skos:related`: the target sits in another scheme, and SKOS reserves the
+ * unqualified property for associations inside one scheme.
+ */
+declare const SKOS_MATCH_PREDICATE: Readonly<Record<MatchStrength, string>>;
+/** The strengths, at runtime. TypeScript cannot enumerate a union, so this is by hand. */
+declare const MATCH_STRENGTHS: readonly ["broad", "close", "exact", "narrow", "related"];
+/**
+ * True when the row asserts the two concepts are interchangeable. The only strength a consumer may
+ * treat as an identity; everything else is an approximation it has been told about.
+ */
+declare const isInterchangeable: (strength: MatchStrength) => boolean;
+
+declare const ELEMENT_TERMS: readonly Term[];
+
+/** How a product or material is made; never a claim about its style or visible motif. */
+declare const CONSTRUCTION_TERMS: readonly Term[];
+
+/** Kept for consumers importing the axis as one list; prefer the facets. */
+declare const FINISH_TERMS: readonly Term[];
+
+/** The supplied physical unit or delivery shape, independent of material and installation pattern. */
+declare const FORMAT_TERMS: readonly Term[];
+
+/** Specific substance or material system; narrower than the retrieval-oriented material family. */
+declare const MATERIAL_TERMS: readonly Term[];
+
+declare const MOOD_TERMS: readonly Term[];
+
+/** Kept for consumers importing the axis as one list; prefer the facets. */
+declare const PATTERN_TERMS: readonly Term[];
+
+/** What kind of purchasable or specifiable thing the record describes, independent of substance. */
+declare const PRODUCT_CATEGORY_TERMS: readonly Term[];
+
+/** A dimension on which a project can impose a constraint; the assertion carries its operator/value. */
+declare const REQUIREMENT_TERMS: readonly Term[];
+
+declare const PALETTE_HUE_TERMS: readonly Term[];
+declare const PALETTE_TEMPERATURE_TERMS: readonly Term[];
+declare const PALETTE_CHARACTER_TERMS: readonly Term[];
+/** The three palette facets, each a closed dictionary in its own right. */
+declare const PALETTE_FACETS: readonly ["hue", "temperature", "character"];
+type PaletteFacet = (typeof PALETTE_FACETS)[number];
+
+declare const PERIOD_TERMS: readonly Term[];
+/**
+ * The periods a year could belong to, best match first.
+ *
+ * Sibling spans overlap on purpose - Georgian and Regency genuinely do - so "what period is 1800?"
+ * has no single answer in the data. Resolving it lives here rather than in each consumer, because
+ * a tie-break reinvented five times is five different answers to one question.
+ *
+ * THE RANKING, and it is not quite the one TAX-10 proposed. That ticket said prefer the narrowest
+ * match, then the un-hedged one. Narrowest-first alone gets 1800 wrong: it returns Regency, whose
+ * core is 1811-1820, over Georgian, whose core contains 1800 outright. So the first key is whether
+ * the year falls in the period's UNCONTROVERSIAL CORE at all:
+ *
+ *   1. a core match beats an edge match          1800 is Georgian, only arguably Regency
+ *   2. then narrowest core                       1815 is Regency, not merely Georgian
+ *   3. then `circa: false`                       dated boundaries beat conventional ones
+ *   4. among edge matches, least far outside     1832 is late Georgian, not late Regency
+ *
+ * `strict` drops the edge matches entirely, which is the difference between "give me a canonical
+ * period for this year" and "could this year defensibly be called that".
+ */
+declare const periodsAt: (year: number, { strict }?: {
+    strict?: boolean | undefined;
+}) => readonly Term[];
+/** The single best period for a year, or undefined when none covers it. */
+declare const periodAt: (year: number, options?: {
+    strict?: boolean;
+}) => Term | undefined;
+
+declare const PLACE_REGION_TERMS: readonly Term[];
+declare const PLACE_LANDSCAPE_TERMS: readonly Term[];
+declare const PLACE_FACETS: readonly ["region", "landscape"];
+type PlaceFacet = (typeof PLACE_FACETS)[number];
+
+declare const STYLE_TERMS: readonly Term[];
+
+type StyleId = (typeof STYLE_TERMS)[number]["id"];
+/** At least one anchor, so a key cannot be added and left empty. */
+type Anchors$1 = readonly [string, ...string[]];
+declare const STYLE_ANCHORS: Readonly<Record<string, Anchors$1>>;
+/** The anchors for a style term, or undefined when the id names no style. */
+declare const anchorsFor: (styleId: string) => Anchors$1 | undefined;
+
+declare const MOOD_ANCHORS: Readonly<Record<string, Anchors$1>>;
+/** The anchors for a mood term, or undefined when the id names no mood. */
+declare const moodAnchorsFor: (moodId: string) => Anchors$1 | undefined;
+
+declare const PERIOD_ANCHORS: Readonly<Record<string, Anchors$1>>;
+/** The anchors for a period term, or undefined when the id names no period. */
+declare const periodAnchorsFor: (periodId: string) => Anchors$1 | undefined;
+
+declare const PLACE_ANCHORS: Readonly<Record<string, Anchors$1>>;
+/** The anchors for a place term, or undefined when the id names no place. */
+declare const placeAnchorsFor: (placeId: string) => Anchors$1 | undefined;
+
+type Anchors = readonly [string, ...string[]];
+/**
+ * Every space anchor, one file per sector so each stays inside the line budget and reads
+ * alphabetically within its own group.
+ */
+declare const SPACE_ANCHORS: Readonly<Record<string, Anchors>>;
+/** The anchors for a space term, or undefined when the id names no space. */
+declare const spaceAnchorsFor: (spaceId: string) => Anchors | undefined;
+
+/**
+ * A sector of the SPACE axis: a group of rooms that answer the same programme question.
+ *
+ * NOT THE SECTOR AXIS, despite the shared word, and the collision is old rather than chosen:
+ * these are PROGRAMME groups (where you sleep, wash, eat), while `sector.*` is the market a
+ * project serves. The market claim lives on individual terms as `serves` edges - see
+ * `marketsServed` below and the register in `space/market-neutral.ts` - and this grouping makes
+ * no market claim at all: the "healthcare" file holds `clean_room`, which serves no single
+ * market, and the "domestic" file is a programme word, not `sector.residential`.
+ *
+ * NOT A FACET, and not part of a term's identifier. `space.scullery` is the id whatever sector the
+ * scullery is filed under, and re-filing a room must never move its URI. This is a browse
+ * structure, and it exists because 197 rooms sorted alphabetically put Operating Room next to
+ * Orangery - which is a list you can search and not a list you can read.
+ *
+ * NOR IS IT `broaderTermId`. A scullery is not a kind of "Dining", so an ISA edge would be false;
+ * ADR 0001's relation rule is explicit that subsumption means every instance of the narrower term
+ * is an instance of the broader one. Sector is a filing decision about the vocabulary, which is a
+ * different kind of claim from a fact about the world, and conflating the two is how hierarchies
+ * fill up with things that are not parents.
+ */
+interface SpaceSector {
     id: string;
+    /** The reader's word for the sector. */
     label: string;
-    /** Explicitly authored Material Semantics id (dashed); absent where upstream authored none. */
-    semanticId?: string;
-    /** Parent term id for hierarchical dictionaries (applications). */
-    broaderTermId?: string;
+    terms: readonly Term[];
 }
+/**
+ * The seventeen sectors, in the order a browse page should show them.
+ *
+ * Ordered by programme rather than alphabetically or by size: where you arrive, where you move,
+ * where you sleep, wash, eat, gather, and so on out to the specialised sectors and the unclassified
+ * tail. A reader looking for their own corner of the built environment finds it by walking through
+ * a building, which is the order this list is in.
+ *
+ * `SPACE_TERMS` is DERIVED from this, so the flat list and the grouped one cannot disagree. It was
+ * previously the other way round - seventeen spreads into one array, with the grouping expressed
+ * only by which file a term happened to sit in, where nothing outside the package could read it.
+ */
+declare const SPACE_SECTORS: readonly SpaceSector[];
+declare const SPACE_TERMS: readonly Term[];
+/**
+ * The markets a space exists to serve, resolved through its ISA chain, or null where no market is
+ * part of the room's identity.
+ *
+ * THE ACCESSOR EXISTS SO THE INHERITANCE IS NOT REINVENTED. A `serves` edge restricts every
+ * descendant - each suite is a hotel room, so each suite serves hospitality - and a consumer
+ * reading raw edges would see `suite` carrying none and read it as unrestricted. The walk stops at
+ * the NEAREST edge-bearing ancestor, because a child's own edges are a narrower claim that
+ * replaces the inherited one rather than adding to it (`training_room` serves workplace inside a
+ * neutral `classroom`).
+ *
+ * Null is a reviewed claim, not a gap: the term serves whatever market its project serves. The
+ * register in `space/market-neutral.ts` is what makes that true, and the disposition test in
+ * `axes.test.ts` is what keeps it true. Answering "what belongs in a residential scheme" is
+ * therefore: every term whose result is null or includes "residential" - the neutral majority
+ * spans all sectors, and excluding it would fail closed.
+ */
+declare const marketsServed: (termId: string) => readonly Sector[] | null;
+
+declare const MARKET_NEUTRAL_SPACES: ReadonlySet<string>;
+
+declare const TYPOLOGY_TERMS: readonly Term[];
+
+declare const AXIS_IDS: readonly ["material_family", "product_category", "material", "pattern", "finish", "format", "construction", "requirement", "sector", "application", "space", "element", "typology", "style", "period", "mood", "palette", "place", "tier", "procurement", "strategy", "form", "density"];
+type AxisId = (typeof AXIS_IDS)[number];
+interface AxisFacet {
+    id: string;
+    label: string;
+    terms: readonly Term[];
+}
+interface Axis {
+    id: AxisId;
+    label: string;
+    /** The question the axis answers, in a reader's words. One line. */
+    question: string;
+    /**
+     * Where this axis ends and its nearest neighbour begins, with the criterion that decides it.
+     * Rendered verbatim on the axis page, because a boundary nobody can read is a boundary that gets
+     * re-litigated.
+     */
+    boundary: string;
+    /** `authored` ships terms. `declared` is a real question with no terms yet, and says so. */
+    status: "authored" | "declared";
+    /** Single-dictionary axes carry one facet named for the axis. */
+    facets: readonly AxisFacet[];
+    /** Why the axis has no terms yet. Present only when status is "declared". */
+    gap?: string;
+}
+declare const AXES: readonly Axis[];
+declare const axisById: (id: AxisId) => Axis | undefined;
+/** Every term on an axis, across all its facets. */
+declare const axisTerms: (axis: Axis) => readonly Term[];
+
+declare const MATERIAL_FAMILY_TERMS: readonly Term[];
+declare const SECTOR_TERMS: readonly Term[];
+declare const APPLICATION_TERMS: readonly Term[];
+
+/**
+ * The published term shape. Widened in 0.2.0 from the original three fields to the full `Term` in
+ * `./term`, which adds external mappings, provenance, usage bands, supersession and typed
+ * relations. Every added field is optional, so this is a backward-compatible minor exactly as the
+ * banner above planned: "adding them later is a backward-compatible minor".
+ */
+type TaxonomyTerm = Term;
+
 declare const PROVENANCE: {
     readonly snapshot: "2026-07-08";
     readonly source: "materialgraph packages/schema/src/registry/value-dictionaries.ts";
 };
-declare const MATERIAL_FAMILY_TERMS: readonly TaxonomyTerm[];
 declare const MATERIAL_FAMILIES: readonly ["paint", "wall_finish", "wallcovering", "textile", "upholstery", "carpet", "wood", "stone", "tile", "terrazzo", "metal", "glass", "resilient_flooring", "composite", "concrete", "leather", "other"];
 type MaterialFamily = (typeof MATERIAL_FAMILIES)[number];
 declare const isMaterialFamily: (value: string) => value is MaterialFamily;
-declare const SECTOR_TERMS: readonly TaxonomyTerm[];
 declare const SECTORS: readonly ["hospitality", "healthcare", "workplace", "residential", "retail", "education", "civic", "mixed_use", "transportation", "other"];
 type Sector = (typeof SECTORS)[number];
 declare const isSector: (value: string) => value is Sector;
-declare const APPLICATION_TERMS: readonly TaxonomyTerm[];
-declare const APPLICATIONS: readonly ["wall", "flooring", "ceiling", "bath", "kitchen", "furniture", "lighting", "door", "window", "facade", "countertop", "fireplace", "stair_elevator", "bedding", "decor", "vertically_hanging", "transportation", "pool_fountain", "paving_deck", "partition", "millwork", "cabinetry", "masonry", "roof", "garage", "bar", "awning_umbrella", "recreation_sport", "ornamentation", "aquatic_environments", "wall_backsplash", "wall_upholstered", "wall_wet_shower", "flooring_wet_area", "flooring_entrance", "flooring_radiant_heat", "flooring_or_lab", "flooring_anti_fatigue", "flooring_esd", "flooring_safety_slip", "flooring_raised_access", "flooring_rigid_core", "flooring_dining_area", "flooring_subject_oil", "flooring_walk_in_freezer", "flooring_ramps_inclines", "furniture_seating", "furniture_headboard", "furniture_slipcover", "furniture_systems", "furniture_tackboard", "furniture_throw_pillow", "fireplace_firebox", "fireplace_hearth", "fireplace_mantel", "fireplace_surround", "bedding_bed_scarf", "bedding_sheets", "bedding_skirt", "bedding_bedspread", "bedding_box_spring_cover", "stair_riser", "stair_tread", "stair_railing", "stair_elevator_cladding", "vh_drapery", "vh_privacy_curtain", "vh_shower_curtain", "vh_theatrical_curtain", "vh_window_shade", "transportation_automotive", "transportation_aviation", "transportation_marine", "pool_coping", "pool_decking", "pool_lining", "paving_covered_areas", "paving_patio", "partition_toilet", "masonry_structural", "masonry_veneer", "recreation_gymnasium", "recreation_playground", "recreation_weightlifting", "awning", "tensile_structure", "umbrella", "countertop_chemical_resistant"];
+declare const APPLICATIONS: readonly ["wall", "flooring", "ceiling", "bath", "kitchen", "furniture", "lighting", "door", "window", "facade", "countertop", "fireplace", "stair_elevator", "bedding", "decor", "vertically_hanging", "transportation", "pool_fountain", "paving_deck", "partition", "millwork", "cabinetry", "masonry", "roof", "garage", "bar", "awning_umbrella", "recreation_sport", "ornamentation", "aquatic_environments", "upholstery", "trim", "wall_backsplash", "wall_upholstered", "wall_wet_shower", "flooring_wet_area", "flooring_entrance", "flooring_radiant_heat", "flooring_or_lab", "flooring_anti_fatigue", "flooring_esd", "flooring_safety_slip", "flooring_raised_access", "flooring_rigid_core", "flooring_dining_area", "flooring_subject_oil", "flooring_walk_in_freezer", "flooring_ramps_inclines", "furniture_seating", "furniture_headboard", "furniture_slipcover", "furniture_systems", "furniture_tackboard", "furniture_throw_pillow", "fireplace_firebox", "fireplace_hearth", "fireplace_mantel", "fireplace_surround", "bedding_bed_scarf", "bedding_sheets", "bedding_skirt", "bedding_bedspread", "bedding_box_spring_cover", "stair_riser", "stair_tread", "stair_railing", "stair_elevator_cladding", "vh_drapery", "vh_privacy_curtain", "vh_shower_curtain", "vh_theatrical_curtain", "vh_window_shade", "transportation_automotive", "transportation_aviation", "transportation_marine", "pool_coping", "pool_decking", "pool_lining", "paving_covered_areas", "paving_patio", "partition_toilet", "masonry_structural", "masonry_veneer", "recreation_gymnasium", "recreation_playground", "recreation_weightlifting", "awning", "tensile_structure", "umbrella", "countertop_chemical_resistant"];
 type Application = (typeof APPLICATIONS)[number];
 declare const isApplication: (value: string) => value is Application;
 declare const APPLICATION_PARENTS: Readonly<Partial<Record<Application, Application>>>;
 declare const applicationTopLevelOf: (application: Application) => Application;
 
-export { APPLICATIONS, APPLICATION_PARENTS, APPLICATION_TERMS, type Application, MATERIAL_FAMILIES, MATERIAL_FAMILY_TERMS, type MaterialFamily, PROVENANCE, SECTORS, SECTOR_TERMS, type Sector, type TaxonomyTerm, applicationTopLevelOf, isApplication, isMaterialFamily, isSector };
+export { APPLICATIONS, APPLICATION_PARENTS, APPLICATION_TERMS, ASSERTION_KEYS, AXES, AXIS_IDS, type Anchors$1 as Anchors, type Application, type Axis, type AxisFacet, type AxisId, CONSTRUCTION_TERMS, ELEMENT_TERMS, FINISH_TERMS, FORMAT_TERMS, MARKET_NEUTRAL_SPACES, MATCH_STRENGTHS, MATERIAL_FAMILIES, MATERIAL_FAMILY_TERMS, MATERIAL_TERMS, MOOD_ANCHORS, MOOD_TERMS, MatchStrength, type MaterialFamily, PALETTE_CHARACTER_TERMS, PALETTE_FACETS, PALETTE_HUE_TERMS, PALETTE_TEMPERATURE_TERMS, PATTERN_TERMS, PERIOD_ANCHORS, PERIOD_TERMS, PLACE_ANCHORS, PLACE_FACETS, PLACE_LANDSCAPE_TERMS, PLACE_REGION_TERMS, PRODUCT_CATEGORY_TERMS, PROVENANCE, type PaletteFacet, type ParsedAssertion, type PlaceFacet, RELATION_PREDICATES, REQUIREMENT_TERMS, RelationPredicate, type ResolvedAssertion, SECTORS, SECTOR_TERMS, SKOS_MATCH_PREDICATE, SPACE_ANCHORS, SPACE_SECTORS, SPACE_TERMS, STYLE_ANCHORS, STYLE_TERMS, type Sector, type SpaceSector, type StyleId, TERM_LOCATIONS, TYPOLOGY_TERMS, type TaxonomyTerm, Term, type TermLocation, anchorsFor, applicationTopLevelOf, axisById, axisTerms, canonicalAssertion, deprecatedAssertions, isApplication, isCanonicalAssertion, isInterchangeable, isMaterialFamily, isSector, marketsServed, moodAnchorsFor, parseAssertion, periodAnchorsFor, periodAt, periodsAt, placeAnchorsFor, resolveAssertion, resolveTerm, spaceAnchorsFor, unknownAssertions };