@instruments/taxonomy 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,28 +1,223 @@
-interface TaxonomyTerm {
+import { T as Term } from './match-BDI6Evro.js';
+export { A as AlternativeReason, a as AlternativesMatch, b as BundleMatch, c as BundleMember, B as BundleMemberInput, d as BundleRole, C as CanonicalAlternatives, e as CanonicalBundle, D as DEFAULT_BUNDLE_ROLE, E as ExternalMapping, f as ExternalScheme, M as MATCH_TEST_VECTORS, g as MATCH_WEIGHTS, h as MatchStrength, i as MatchTestCandidate, j as MatchTestVector, P as PeriodSpan, R as RelationPredicate, k as RelationRole, S as SearchedWithout, l as SourceBasis, m as StyleKind, n as TermProvenance, o as TermRelation, p as TermStatus, q as TermUsage, U as UsageBand, r as UsageWithheld, s as defineAlternatives, t as defineBundle, u as matchAlternatives, v as matchBundle } from './match-BDI6Evro.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';
+
+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[];
+
+/** The deliberately produced state of the exposed surface, not its material or motif. */
+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[];
+
+/** Visible surface organisation or motif, independent of the substance carrying it. */
+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"];
 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, 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, MATERIAL_FAMILIES, MATERIAL_FAMILY_TERMS, MATERIAL_TERMS, MOOD_ANCHORS, MOOD_TERMS, 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 PlaceFacet, REQUIREMENT_TERMS, SECTORS, SECTOR_TERMS, SPACE_ANCHORS, SPACE_SECTORS, SPACE_TERMS, STYLE_ANCHORS, STYLE_TERMS, type Sector, type SpaceSector, type StyleId, TYPOLOGY_TERMS, type TaxonomyTerm, Term, anchorsFor, applicationTopLevelOf, axisById, axisTerms, isApplication, isMaterialFamily, isSector, marketsServed, moodAnchorsFor, periodAnchorsFor, periodAt, periodsAt, placeAnchorsFor, spaceAnchorsFor };