@instruments/taxonomy 1.1.6 → 1.3.0

package/dist/index.d.ts

@@ -1,342 +1,8 @@
-/** An external vocabulary this package crosswalks out to. */
-type ExternalScheme = 
-/** Getty Art & Architecture Thesaurus. ODC-By 1.0 - redistributable with attribution. */
-"aat"
-/** Uniclass 2015 (NBS). CC BY-ND 4.0 - referenced by code, never adapted. */
- | "uniclass"
-/** Wikidata Q-items. CC0. */
- | "wikidata";
 /**
- * SKOS mapping strength, using SKOS's own vocabulary so the published RDF is a direct rendering
- * rather than a translation. `exact` asserts the two terms are interchangeable in retrieval;
- * `close` asserts they are near enough to substitute in most contexts but not all; `broad` and
- * `narrow` assert containment in the named direction; `related` asserts association only.
- */
-type MatchStrength = "exact" | "close" | "broad" | "narrow" | "related";
-interface ExternalMapping {
-    scheme: ExternalScheme;
-    /** The external identifier, verbatim: an AAT subject id, a Uniclass code, a Wikidata Q-number. */
-    identifier: string;
-    /** The external vocabulary's own label for that identifier, verbatim and unedited. */
-    label: string;
-    match: MatchStrength;
-}
-/**
- * Where a term's content came from, and when. Ranks the SOURCE, never the accuracy: a term lifted
- * verbatim from an upstream dictionary is `vendored` whether or not the upstream got it right.
- * Using this field as a proxy for correctness is how confident wrong answers get made.
- */
-type SourceBasis = 
-/** Copied unedited from a named upstream dictionary at a stated snapshot. */
-"vendored"
-/** Written here, from scratch, by a named editor. */
- | "authored"
-/** Written here, but derived from measured usage in a named corpus. */
- | "evidenced"
-/** Written here from one or more named authoritative references, without adopting their term. */
- | "referenced"
-/** Adopted from a published external standard, with its identifier carried. */
- | "standard";
-interface TermProvenance {
-    basis: SourceBasis;
-    /** The upstream file, corpus or standard. Free text, but always specific enough to re-read. */
-    source: string;
-    /** ISO date the source was read. Absent only for `authored`. */
-    snapshot?: string;
-}
-/**
- * A DATED NEGATIVE RESULT: a scheme that was searched for this term and did not have it.
- *
- * This is the field that makes the gap publishable. ADR 0001 section 8 softens the planned
- * invariant "every STYLE and PERIOD term carries an AAT mapping" to "carries a mapping OR carries
- * one of these", because AAT has no consumer interiors coverage at all - a live search for
- * *japandi* returns nothing, and *farmhouse*, *transitional* and *coastal* are absent as interior
- * idioms. Without this field an unmapped term is indistinguishable from an unchecked one, and the
- * two are opposites: one is evidence and the other is a to-do.
- *
- * A dated negative against the best art-and-architecture thesaurus in the world is the clearest
- * available statement of why this vocabulary needs to exist.
- */
-interface SearchedWithout {
-    scheme: ExternalScheme;
-    /** ISO date the search was run. */
-    date: string;
-    /** What was searched, so a reader can repeat it. */
-    query: string;
-    /** Where the search was run, e.g. the SPARQL endpoint. */
-    via: string;
-}
-/**
- * A band, never a count.
- *
- * THE SCALE, stated once so every axis uses the same one. Measured against the corpus named on the
- * term: `dominant` is the top decile of values by frequency, `common` the next, `occasional` a
- * value that appears regularly, `rare` one that barely does, and `unattested` a value the corpus
- * never uses. Set `usage` only where the named corpus can actually speak to the term: omitting it
- * says "not measured here", which is honest, whereas `unattested` against an unrelated corpus
- * would read as a claim about the term rather than about the corpus. The usage figures behind these derive from Material Bank's warehouse and
- * from the DesignShop capture; publishing a raw number would publish a figure from someone else's
- * business. The band carries the signal a reader actually needs - is this term common or rare  -
- * and nothing more.
- */
-type UsageBand = "dominant" | "common" | "occasional" | "rare" | "unattested";
-interface TermUsage {
-    band: UsageBand;
-    /** The corpus the band was measured against, and when. */
-    corpus: string;
-    snapshot: string;
-}
-/**
- * Why a term carries no usage band when the corpus plainly has something to say about it.
- *
- * The distinguishing case is `style.modernism`. DesignShop tags a dominant share of its room
- * schemes `Modern`, but that is the crosswalk row that DECLINES: `Modern` reads as either
- * `style.modernism` or `style.contemporary` and the source never recorded which. Attributing the
- * usage would smuggle in the guess the crosswalk refused to make.
- *
- * Without this field, a reader sees "not measured" and cannot tell that apart from "nobody looked",
- * and those are opposite claims. Same reasoning as `searchedWithout`: an absence somebody reasoned
- * their way to is evidence, and an absence nobody has examined is a to-do.
- */
-interface UsageWithheld {
-    reason: string;
-    /** The corpus that would otherwise have supplied a band. */
-    corpus: string;
-}
-/**
- * A period's extent, as four numbers rather than two.
- *
- * Two dates cannot answer the questions consumers actually ask. "Is 1832 Georgian?" wants the
- * outer edge; "give me a canonical date for Georgian" wants the core. So each period carries a
- * fuzzy interval: `earliest` and `latest` bound what could defensibly be called this period,
- * `start` and `end` bound what uncontroversially is.
- *
- * `end` and `latest` are NULLABLE, and that is load-bearing rather than tidy. An open-ended period
- * closed with the current year needs an arbitrary edit at every release, and the edit is a lie in
- * between: `contemporary` does not end in 2026, it has not ended.
- *
- * SIBLING SPANS ARE ALLOWED TO OVERLAP, deliberately. Georgian and Regency genuinely do. Resolving
- * "what period is 1800?" is therefore an accessor's job, not the data's - see `periodAt`, which
- * prefers the narrowest match and then the un-hedged one. Leaving that to each consumer would get
- * it reinvented differently every time.
- */
-interface PeriodSpan {
-    /** The earliest year anyone would defensibly call this period. */
-    earliest: number;
-    /** The first year it uncontroversially is this period. */
-    start: number;
-    /** The last year it uncontroversially is. Null when the period has not ended. */
-    end: number | null;
-    /** The last year anyone would defensibly call it this. Null when the period has not ended. */
-    latest: number | null;
-    /** True when the boundaries are conventional rather than evidenced by an event. */
-    circa: boolean;
-    /**
-     * Where these dates apply, as ISO 3166-1 alpha-2, or `global`. Regional variance beyond this
-     * belongs in NARROWER TERMS with their own spans, never in a region-to-span map on one term: a
-     * map invites partial coverage, and a narrower term is something a relation can point at.
-     */
-    regions: readonly string[];
-}
-/**
- * What KIND of thing a style term is, because the three kinds have different truth conditions and
- * conflating them is most of why style vocabularies rot.
- *
- * A `movement` has an art-historical literature, dates and adherents, and its boundaries are
- * arguable in the way a scholarly claim is arguable. A `tradition` is a body of regional or
- * vernacular practice, defined by what is done rather than by what was declared. A `market-idiom`
- * is a prototype category the trade converged on, defined by resemblance to central cases and by
- * nothing else - it has no manifesto to appeal to, and asking for necessary and sufficient
- * conditions misunderstands it.
- *
- * Publishing the kind does two things. It tells a reader what sort of disagreement to expect: a
- * dispute about Brutalism is a dispute about the record, a dispute about Farmhouse is a dispute
- * about a prototype, and neither settles like the other. And it is the grouping a browse page needs
- * once STYLE passes about fifty terms, when a flat alphabetical list stops being navigable.
- */
-type StyleKind = "movement" | "tradition" | "market-idiom";
-/**
- * The named predicates a term may carry to another canonical term. Everything that is not ISA
- * lives here, so `broaderSlug` never silently becomes a bag of loose associations.
- */
-type RelationPredicate = 
-/** This element is physically a component of that element. */
-"part-of"
-/** This application or element is typically found in that space. */
- | "typically-in"
-/** This term is a material-suitability claim about that space. */
- | "suitable-for"
-/**
- * The subject exists to serve that sector's market, wherever the building that contains it
- * stands: a hotel room in a mixed-use tower still serves hospitality, an operating room serves
- * healthcare whoever the landlord is. An IDENTITY claim, never an occurrence claim - "occurs
- * only in that sector" is false for almost any room (a multifamily amenity floor holds
- * restrooms, a commercial kitchen and a gym inside `sector.residential`), which is why most
- * rooms rightly carry no edge.
- *
- * ABSENCE IS A CLAIM, NOT A GAP. A SPACE term carrying no serves edge and inheriting none
- * through `broaderSlug` asserts that no market is part of its identity: it serves whatever
- * market its project serves, and a consumer must read it as unrestricted - fail-open - never as
- * a restriction nobody wrote down. What makes that reading safe is `MARKET_NEUTRAL_SPACES`
- * (`axes/space/market-neutral.ts`, with the authoring criterion): every SPACE term either
- * carries an edge or is registered there as reviewed-neutral, and the build fails naming any
- * term that is neither. A reviewed absence and an unreviewed one cannot be confused - the same
- * move `searchedWithout` and `usageWithheld` make.
+ * Taxonomy V1's complete public package surface.
  *
- * Authored on SPACE only, and pinned there by test. The claim's shape would generalise, but
- * TYPOLOGY must never carry it: sector moves when the tenant moves and typology does not, so a
- * typology-to-sector edge dies on conversion - ADR 0001's converted warehouse full of flats is
- * the standing counterexample.
+ * Identity is always a canonical HTTPS URI. The package exports declarative data and the types
+ * needed to consume it; resolution, traversal, ranking, and search policy live in adapters.
  */
- | "serves"
-/** This style or idiom draws on that place idiom or period. */
- | "evokes"
-/** This style descends from that style. */
- | "influenced-by"
-/** This style is a deliberate blend of two or more named styles, and is defined by being so. */
- | "blend-of"
-/** This surface reads as a material it is not made of. */
- | "reads-as"
-/** Association with no stronger claim available. */
- | "related-to";
-
-declare const TAXONOMY_BASE_URI: "https://taxonomy.materialinstruments.com";
-declare const TAXONOMY_SNAPSHOT: "2026-09-01";
-declare const TAXONOMY_VERSION: "1.1.6";
-type CanonicalConceptUri = `${typeof TAXONOMY_BASE_URI}/id/${string}`;
-type LifecycleStatus = "active" | "deprecated";
-interface Lifecycle {
-    introducedAt: string;
-    reviewedAt: string;
-    status: LifecycleStatus;
-    supersededBy?: CanonicalConceptUri;
-}
-interface Governance {
-    explanation: string;
-    lifecycle: Lifecycle;
-    provenance: TermProvenance;
-    steward: "@instruments/taxonomy";
-}
-interface AxisNode {
-    boundary: string;
-    gap?: string;
-    governance: Governance;
-    kind: "axis";
-    label: string;
-    lifecycle: Lifecycle;
-    order: number;
-    provenance: TermProvenance;
-    question: string;
-    slug: string;
-    status: "authored" | "declared";
-    uri: string;
-}
-interface FacetNode {
-    axis: string;
-    governance: Governance;
-    kind: "facet";
-    label: string;
-    lifecycle: Lifecycle;
-    order: number;
-    provenance: TermProvenance;
-    slug: string;
-    uri: string;
-}
-interface ExternalReference {
-    authority: "aat" | "uniclass" | "wikidata";
-    identifier: string;
-    label: string;
-    match: ExternalMapping["match"];
-}
-interface ConceptNode {
-    altLabels?: readonly string[];
-    axis: string;
-    definition?: string;
-    externalReferences?: readonly ExternalReference[];
-    facet: string;
-    governance: Governance;
-    governedBy: "taxonomy";
-    kind: "concept";
-    label: string;
-    lifecycle: Lifecycle;
-    note?: string;
-    order: number;
-    provenance: TermProvenance;
-    rank?: number;
-    searchedWithout?: readonly SearchedWithout[];
-    seenAs?: readonly string[];
-    slug: string;
-    span?: PeriodSpan;
-    styleKind?: StyleKind;
-    uri: CanonicalConceptUri;
-    usage?: TermUsage;
-    usageWithheld?: UsageWithheld;
-}
-type KnowledgeGraphNode = AxisNode | FacetNode | ConceptNode;
-type GraphPredicate = RelationPredicate | "belongs-to-axis" | "belongs-to-facet" | "broader" | "narrower" | "has-concept" | "has-facet" | "has-part" | "typically-contains" | "supported-by" | "served-by" | "evoked-by" | "influences" | "blended-into" | "reading-of";
-interface KnowledgeGraphEdge {
-    assertion: "asserted" | "inverse";
-    from: string;
-    governance: Governance;
-    lifecycle: Lifecycle;
-    predicate: GraphPredicate;
-    provenance: TermProvenance;
-    role?: "constitutive" | "accent";
-    to: string;
-}
-interface KnowledgeGraph {
-    edges: readonly KnowledgeGraphEdge[];
-    nodes: readonly KnowledgeGraphNode[];
-}
-declare const KNOWLEDGE_GRAPH: KnowledgeGraph;
-interface TaxonomyTarget {
-    authority: "taxonomy";
-    role?: "primary" | "secondary";
-    uri: CanonicalConceptUri;
-}
-declare const COLOR_SCOPE_REFERENCE_KINDS: readonly ["chroma-level", "color-family", "lightness-level", "named-color", "palette-mood", "temperature-level"];
-type ColorScopeReferenceKind = (typeof COLOR_SCOPE_REFERENCE_KINDS)[number];
-interface ColorScopeTarget {
-    authority: "colorscope";
-    authorityUri: "https://colorscope.materialinstruments.com";
-    identifier: string;
-    referenceKind: ColorScopeReferenceKind;
-    role?: "primary" | "secondary";
-}
-type LexicalTarget = TaxonomyTarget | ColorScopeTarget;
-type LexicalContext = "colour" | "material";
-interface LexicalBase {
-    explanation: string;
-    governance: Governance;
-    phrase: string;
-}
-type LexicalEntry = (LexicalBase & {
-    outcome: "equivalent";
-    target: LexicalTarget;
-}) | (LexicalBase & {
-    contextualPreferences?: readonly {
-        context: LexicalContext;
-        target: LexicalTarget;
-    }[];
-    /** An explicitly authored default reading; never inferred from array order. */
-    defaultTarget?: LexicalTarget;
-    outcome: "ambiguous";
-    readings: readonly [LexicalTarget, LexicalTarget, ...LexicalTarget[]];
-}) | (LexicalBase & {
-    outcome: "declined";
-    reason: string;
-});
-/** Declarative readings only. Consumers choose indexing and application behaviour. */
-declare const LEXICAL_ENTRIES: readonly LexicalEntry[];
-/** Content address for CI drift checks; changes whenever the public corpus representation changes. */
-declare const TAXONOMY_CORPUS_REVISION: string;
-declare const TAXONOMY_CORPUS_METADATA: {
-    readonly edgeCount: number;
-    readonly lexicalEntryCount: number;
-    readonly nodeCount: number;
-    readonly revision: string;
-    readonly snapshot: "2026-09-01";
-    readonly version: "1.1.6";
-};
-
-export { type AxisNode, COLOR_SCOPE_REFERENCE_KINDS, type CanonicalConceptUri, type ColorScopeReferenceKind, type ColorScopeTarget, type ConceptNode, type ExternalReference, type FacetNode, type Governance, type GraphPredicate, KNOWLEDGE_GRAPH, type KnowledgeGraph, type KnowledgeGraphEdge, type KnowledgeGraphNode, LEXICAL_ENTRIES, type LexicalContext, type LexicalEntry, type LexicalTarget, type Lifecycle, type LifecycleStatus, type PeriodSpan, type SearchedWithout, type StyleKind, TAXONOMY_BASE_URI, TAXONOMY_CORPUS_METADATA, TAXONOMY_CORPUS_REVISION, TAXONOMY_SNAPSHOT, TAXONOMY_VERSION, type TaxonomyTarget, type TermProvenance, type TermUsage, type UsageWithheld };
+export { type AxisNode, type CanonicalConceptUri, COLOR_SCOPE_REFERENCE_KINDS, type ColorScopeReferenceKind, type ColorScopeTarget, type ConceptNode, type ExternalReference, type FacetNode, type Governance, type GraphPredicate, type KnowledgeGraph, type KnowledgeGraphEdge, type KnowledgeGraphNode, KNOWLEDGE_GRAPH, type LexicalEntry, type LexicalContext, LEXICAL_ENTRIES, type Lifecycle, type LifecycleStatus, type LexicalTarget, TAXONOMY_BASE_URI, TAXONOMY_CORPUS_METADATA, TAXONOMY_CORPUS_REVISION, TAXONOMY_SNAPSHOT, TAXONOMY_VERSION, type TaxonomyTarget, } from "./v1.js";
+export type { ElementPlacement, PeriodSpan, SearchedWithout, StyleKind, TermProvenance, TermUsage, UsageWithheld, } from "./term.js";