@instruments/taxonomy 5.1.1 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/match.d.ts CHANGED
@@ -2,7 +2,7 @@ import type { RelationRole } from "./term.js";
2
2
  /** The role an assertion plays inside a compound expression. */
3
3
  export type BundleRole = RelationRole;
4
4
  export interface BundleMemberInput {
5
- /** A qualified canonical term or typed relation, e.g. `style.minimalism`. */
5
+ /** A concept ID or typed relation, e.g. `a7auece` or `evokes(73tu18p)`. */
6
6
  assertion: string;
7
7
  /** Defaults to accent: an unspecified role is evidence of presence, not necessity. */
8
8
  role?: BundleRole;
package/dist/term.d.ts CHANGED
@@ -71,34 +71,6 @@ export interface TermProvenance {
71
71
  /** ISO date the source was read. Absent only for `authored`. */
72
72
  snapshot?: string;
73
73
  }
74
- /**
75
- * A canonical identity governed by ColorScope rather than Taxonomy.
76
- *
77
- * This is data copied from ColorScope, not an inference from provenance prose. A term carrying it
78
- * has ColorScope's own permanent URI as its identity: Taxonomy lists the term so that anything in
79
- * the graph can relate to it, and never defines it.
80
- */
81
- export interface ColorScopeAuthority {
82
- authority: "colorscope";
83
- authorityUri: "https://colorscope.materialinstruments.com";
84
- identifier: string;
85
- referenceKind: keyof ColorScopeReferenceKinds;
86
- /** ColorScope's permanent URI for the concept. */
87
- uri: string;
88
- }
89
- interface ColorScopeReferenceKinds {
90
- /** ColorScope's `basic-tone` concepts: light, mid, dark, muted, vivid. */
91
- "basic-tone": true;
92
- "chroma-level": true;
93
- "color-family": true;
94
- "lightness-level": true;
95
- /** ColorScope's `modifier` concepts, such as washed. */
96
- modifier: true;
97
- "named-color": true;
98
- /** ColorScope's `palette` concepts, which read as palette compositions. */
99
- "palette-mood": true;
100
- "temperature-level": true;
101
- }
102
74
  /**
103
75
  * A DATED NEGATIVE RESULT: a scheme that was searched for this term and did not have it.
104
76
  *
@@ -234,19 +206,21 @@ export type StyleKind = "movement" | "tradition" | "market-idiom";
234
206
  */
235
207
  export type ElementPlacement = "field" | "joinery" | "trim" | "overhead" | "underfoot" | "feature" | "unpainted";
236
208
  export interface Term {
237
- /** Lowercase kebab-case path segment used only inside this concept's canonical URI. */
209
+ /** Assigned in authored data; drafts acquire an ID before graph publication. */
210
+ id?: string;
211
+ /** Readable kebab-case label, independent of the permanent ID. */
238
212
  slug: string;
239
213
  label: string;
240
- /** Present when another package, currently ColorScope, owns this term's canonical identity. */
241
- canonicalAuthority?: ColorScopeAuthority;
242
- /** A representative sRGB color, copied from the owning authority. Present on some ColorScope terms only. */
214
+ /** Exact-match identifiers in the source authority. */
215
+ exactMatch?: readonly string[];
216
+ /** A representative sRGB color, copied from the source authority. Present on color families only. */
243
217
  hex?: string;
244
218
  /**
245
219
  * Parent term id. Carries TAXONOMIC SUBSUMPTION ONLY - every instance of this term must be an
246
220
  * instance of the parent. Part-of, used-in, typically-found-in and evokes are relations, and
247
221
  * belong in `related`, never here. See ADR 0001.
248
222
  */
249
- broaderSlug?: string;
223
+ broaderId?: string;
250
224
  /** One sentence, stating the boundary rather than restating the label. */
251
225
  definition?: string;
252
226
  /** Other correct names for this term. */
@@ -305,7 +279,7 @@ export interface Term {
305
279
  }
306
280
  /**
307
281
  * The named predicates a term may carry to another canonical term. Everything that is not ISA
308
- * lives here, so `broaderSlug` never silently becomes a bag of loose associations.
282
+ * lives here, so `broaderId` never silently becomes a bag of loose associations.
309
283
  */
310
284
  export type RelationPredicate =
311
285
  /**
@@ -338,7 +312,7 @@ export type RelationPredicate =
338
312
  * rooms rightly carry no edge.
339
313
  *
340
314
  * ABSENCE IS A CLAIM, NOT A GAP. A SPACE term carrying no serves edge and inheriting none
341
- * through `broaderSlug` asserts that no market is part of its identity: it serves whatever
315
+ * through `broaderId` asserts that no market is part of its identity: it serves whatever
342
316
  * market its project serves, and a consumer must read it as unrestricted - fail-open - never as
343
317
  * a restriction nobody wrote down. What makes that reading safe is `MARKET_NEUTRAL_SPACES`
344
318
  * (`axes/space/market-neutral.ts`, with the authoring criterion): every SPACE term either
@@ -360,7 +334,7 @@ export type RelationPredicate =
360
334
  /**
361
335
  * This material is shelved under that material family when products made of it are retrieved.
362
336
  * A RETRIEVAL claim, never subsumption: a material family is a consumer's filter, not a level of
363
- * the material hierarchy, so it is never a `broaderSlug`. Authored on MATERIAL only, pointing at
337
+ * the material hierarchy, so it is never a `broaderId`. Authored on MATERIAL only, pointing at
364
338
  * MATERIAL_FAMILY, or at `material.plastic`, the one grouping on the material axis that parents
365
339
  * nothing, and pinned there by test. It is authored on the highest material term it
366
340
  * holds for and READ DOWN the material hierarchy: oak is shelved under Wood because wood is, and
@@ -395,7 +369,7 @@ export type RelationRole =
395
369
  export interface TermRelation {
396
370
  predicate: RelationPredicate;
397
371
  /**
398
- * Fully qualified target: `<axis>.<term id>`, or `<axis>.<facet>.<term id>` on a faceted axis.
372
+ * The permanent ID of the target concept. ColorScope retains its authority identity until MSC-11.
399
373
  *
400
374
  * QUALIFICATION IS LOAD-BEARING, not a formatting preference. One `evokes` predicate works only
401
375
  * because the target's axis types the reference: `evokes(place.region.nordic)` says "place"
@@ -410,4 +384,3 @@ export interface TermRelation {
410
384
  target: string;
411
385
  role?: RelationRole;
412
386
  }
413
- export {};
package/dist/v1.d.ts CHANGED
@@ -1,15 +1,12 @@
1
1
  import type { Axis, FacetHolds } from "./axes/index.js";
2
2
  import type { ElementPlacement, ExternalMapping, ExternalScheme, PeriodSpan, RelationPredicate, SearchedWithout, StyleKind, TermProvenance, TermUsage, UsageWithheld } from "./term.js";
3
3
  export type { FacetHolds } from "./axes/index.js";
4
- export declare const TAXONOMY_BASE_URI: "https://taxonomy.materialinstruments.com";
5
4
  export declare const TAXONOMY_SNAPSHOT: "2026-10-02";
6
- export declare const TAXONOMY_VERSION: "5.1.1";
5
+ export declare const TAXONOMY_VERSION: "5.3.0";
7
6
  export declare const COLORSCOPE_BASE_URI: "https://colorscope.materialinstruments.com";
8
- export type CanonicalConceptUri = `${typeof TAXONOMY_BASE_URI}/id/${string}`;
7
+ export type ConceptId = string;
9
8
  /** ColorScope's permanent URI for a concept it owns. */
10
- export type ColorScopeConceptUri = `${typeof COLORSCOPE_BASE_URI}/id/${string}`;
11
- /** The identity of a concept node: this corpus's own URI, or the owning authority's. */
12
- export type ConceptUri = CanonicalConceptUri | ColorScopeConceptUri;
9
+ export type ColorScopeConceptIdentity = `${typeof COLORSCOPE_BASE_URI}/id/${string}`;
13
10
  export interface Lifecycle {
14
11
  introducedAt: string;
15
12
  reviewedAt: string;
@@ -18,8 +15,8 @@ export interface Governance {
18
15
  explanation: string;
19
16
  lifecycle: Lifecycle;
20
17
  provenance: TermProvenance;
21
- /** Who owns the thing described: Taxonomy, or ColorScope for the color concepts it lists. */
22
- steward: "@instruments/taxonomy" | "@materialinstruments/colorscope";
18
+ /** The steward of the published Taxonomy record. */
19
+ steward: "@instruments/taxonomy";
23
20
  }
24
21
  export interface AxisNode {
25
22
  boundary: string;
@@ -33,7 +30,7 @@ export interface AxisNode {
33
30
  question: string;
34
31
  slug: string;
35
32
  status: "authored" | "declared";
36
- uri: string;
33
+ id: string;
37
34
  }
38
35
  export interface FacetNode {
39
36
  axis: string;
@@ -46,7 +43,7 @@ export interface FacetNode {
46
43
  order: number;
47
44
  provenance: TermProvenance;
48
45
  slug: string;
49
- uri: string;
46
+ id: string;
50
47
  }
51
48
  export interface ExternalReference {
52
49
  authority: ExternalScheme;
@@ -61,11 +58,10 @@ export interface ConceptNode {
61
58
  externalReferences?: readonly ExternalReference[];
62
59
  facet: string;
63
60
  governance: Governance;
64
- /**
65
- * Who owns the concept. `colorscope` marks a color concept Taxonomy lists but does not define:
66
- * its `uri` is ColorScope's own permanent URI, and its meaning is ColorScope's.
67
- */
68
- governedBy: "taxonomy" | "colorscope";
61
+ /** Taxonomy governs every concept, including imported snapshots. */
62
+ governedBy: "taxonomy";
63
+ /** Exact-match identifiers in the source authority. */
64
+ exactMatch?: readonly string[];
69
65
  /** A representative sRGB color, copied from ColorScope. Present on color families only. */
70
66
  hex?: string;
71
67
  kind: "concept";
@@ -81,7 +77,7 @@ export interface ConceptNode {
81
77
  slug: string;
82
78
  span?: PeriodSpan;
83
79
  styleKind?: StyleKind;
84
- uri: ConceptUri;
80
+ id: ConceptId;
85
81
  usage?: TermUsage;
86
82
  usageWithheld?: UsageWithheld;
87
83
  }
@@ -112,9 +108,9 @@ export type MeaningPriority = "primary" | "secondary";
112
108
  export interface TaxonomyTarget {
113
109
  authority: "taxonomy";
114
110
  meaningPriority?: MeaningPriority;
115
- uri: CanonicalConceptUri;
111
+ id: ConceptId;
116
112
  }
117
- export declare const COLOR_SCOPE_REFERENCE_KINDS: readonly ["basic-tone", "chroma-level", "color-family", "lightness-level", "modifier", "named-color", "palette-mood", "temperature-level"];
113
+ export declare const COLOR_SCOPE_REFERENCE_KINDS: readonly ["chroma-level", "lightness-level", "modifier", "named-color"];
118
114
  export type ColorScopeReferenceKind = (typeof COLOR_SCOPE_REFERENCE_KINDS)[number];
119
115
  export interface ColorScopeTarget {
120
116
  authority: "colorscope";
@@ -123,11 +119,9 @@ export interface ColorScopeTarget {
123
119
  referenceKind: ColorScopeReferenceKind;
124
120
  meaningPriority?: MeaningPriority;
125
121
  /**
126
- * ColorScope's permanent URI for the concept. For a family, temperature level, basic tone or
127
- * palette composition this is also the URI of a node in this graph; a named color has no node
128
- * here and is read at ColorScope.
122
+ * The external ColorScope identity. Imported palette concepts use TaxonomyTarget instead.
129
123
  */
130
- uri: ColorScopeConceptUri;
124
+ id: ColorScopeConceptIdentity;
131
125
  }
132
126
  export type PhraseMeaning = TaxonomyTarget | ColorScopeTarget;
133
127
  export type MeaningContext = "color" | "material";
@@ -164,5 +158,5 @@ export declare const TAXONOMY_CORPUS_METADATA: {
164
158
  readonly phraseEntryCount: number;
165
159
  readonly revision: string;
166
160
  readonly snapshot: "2026-10-02";
167
- readonly version: "5.1.1";
161
+ readonly version: "5.3.0";
168
162
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@instruments/taxonomy",
3
- "version": "5.1.1",
3
+ "version": "5.3.0",
4
4
  "description": "Canonical data-only interiors and architecture knowledge graph and lexical corpus.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {
@@ -26,8 +26,8 @@
26
26
  },
27
27
  "devDependencies": {
28
28
  "@howells/lint": "^3.10.2",
29
- "@materialinstruments/colorscope": "10.4.0",
30
29
  "@types/node": "^26.6.6",
30
+ "boubakikid": "^1.0.1",
31
31
  "tsup": "^8.5.1",
32
32
  "typescript": "^7.0.2",
33
33
  "vitest": "^5.1.0"
@@ -38,6 +38,8 @@
38
38
  "lint": "howells-check .",
39
39
  "lint:fix": "howells-fix .",
40
40
  "test": "vitest run",
41
- "typecheck": "tsc --noEmit"
41
+ "typecheck": "tsc --noEmit",
42
+ "mint:id": "node --experimental-strip-types scripts/mint-id.ts",
43
+ "assign:identifiers": "node ../../tools/assign-taxonomy-identifiers.mjs"
42
44
  }
43
45
  }
@@ -1,44 +0,0 @@
1
- import type { CanonicalAlternatives, CanonicalBundle } from "./match.js";
2
- import type { AssertionMeaning, AssertionProvenance } from "./taste-assertion.js";
3
- import type { MatchStrength } from "./term.js";
4
- export interface CanonicalizationInput {
5
- sourceSystem: string;
6
- sourceField: string;
7
- sourceValue: string;
8
- provenance: AssertionProvenance;
9
- }
10
- interface CanonicalizationBase extends CanonicalizationInput {
11
- crosswalkVersion: string;
12
- taxonomySnapshotVersion: string;
13
- }
14
- export interface ResolvedCanonicalization extends CanonicalizationBase {
15
- status: "resolved";
16
- canonical: CanonicalBundle;
17
- /**
18
- * How strongly the canonical bundle stands for the source value, in SKOS's own vocabulary. A
19
- * consumer may treat `exact` as an identity and must treat everything else as an approximation
20
- * it has been told about. See `crosswalks/strength.ts` for the direction convention.
21
- */
22
- match: MatchStrength;
23
- /** Why the row is not exact. Present whenever `match` is not `exact`. */
24
- note?: string;
25
- }
26
- export interface AmbiguousCanonicalization extends CanonicalizationBase {
27
- status: "ambiguous";
28
- alternatives: CanonicalAlternatives;
29
- /** How strongly each alternative would stand for the source value, were it the right reading. */
30
- match: MatchStrength;
31
- note?: string;
32
- }
33
- export interface UnresolvedCanonicalization extends CanonicalizationBase {
34
- status: "unresolved";
35
- }
36
- export interface DeclinedCanonicalization extends CanonicalizationBase {
37
- status: "declined";
38
- reason: string;
39
- }
40
- /** Four honest outcomes: absence of a mapping is never silently treated as a decline or a match. */
41
- export type CanonicalizationVerdict = ResolvedCanonicalization | AmbiguousCanonicalization | UnresolvedCanonicalization | DeclinedCanonicalization;
42
- /** Convert a usable verdict to assertion meaning; a declined value does not assert anything. */
43
- export declare const assertionMeaningFrom: (verdict: CanonicalizationVerdict) => AssertionMeaning | null;
44
- export {};
@@ -1,112 +0,0 @@
1
- import type { CanonicalAlternatives, CanonicalBundle } from "./match.js";
2
- export declare const TASTE_ASSERTION_CONTRACT_VERSION: "1.0.0";
3
- export declare const TAXONOMY_SNAPSHOT_VERSION: "2026-08-31";
4
- export type AssertionRole = "taste" | "project_context" | "requirement";
5
- export type AssertionAuthority = "explicit" | "behavioral" | "inferred";
6
- export type AssertionPolarity = "positive" | "negative" | "never";
7
- export type AssertionScope = {
8
- kind: "person";
9
- } | {
10
- kind: "household";
11
- householdId: string;
12
- } | {
13
- kind: "project";
14
- projectId: string;
15
- } | {
16
- kind: "room_type";
17
- roomTypeId: string;
18
- } | {
19
- kind: "room";
20
- roomId: string;
21
- } | {
22
- kind: "surface";
23
- roomId: string;
24
- surfaceId: string;
25
- };
26
- export interface AssertionProvenance {
27
- /** The application, import or instrument that produced the observation. */
28
- sourceSystem: string;
29
- /** Version of the source data, prompt, fixture or export used when the evidence was observed. */
30
- sourceSnapshotVersion: string;
31
- sourceRecordId?: string;
32
- sourceUrl?: string;
33
- /** Optional id for the observation from which this assertion was proposed. */
34
- observationId?: string;
35
- }
36
- interface SourceMeaning {
37
- /** Source vocabulary field, before canonicalization. */
38
- sourceField: string;
39
- /** Verbatim source value; never replaced by the canonical label. */
40
- sourceValue: string;
41
- /** Version of the source-specific mapping policy. */
42
- crosswalkVersion: string;
43
- /** Version of the canonical vocabulary against which mapping ran. */
44
- taxonomySnapshotVersion: string;
45
- }
46
- export interface ResolvedAssertionMeaning extends SourceMeaning {
47
- kind: "resolved";
48
- canonical: CanonicalBundle;
49
- }
50
- export interface AmbiguousAssertionMeaning extends SourceMeaning {
51
- kind: "ambiguous";
52
- alternatives: CanonicalAlternatives;
53
- }
54
- export interface UnresolvedAssertionMeaning extends SourceMeaning {
55
- kind: "unresolved";
56
- }
57
- export type AssertionMeaning = ResolvedAssertionMeaning | AmbiguousAssertionMeaning | UnresolvedAssertionMeaning;
58
- interface PortableAssertionBase {
59
- /** Stable application-owned identifier for this assertion event. */
60
- id: string;
61
- contractVersion: typeof TASTE_ASSERTION_CONTRACT_VERSION;
62
- actorId: string;
63
- /** Whose taste or project view the assertion describes; never inferred from actorId. */
64
- subjectId: string;
65
- /** Project context is explicit even when the assertion's scope is durable and personal. */
66
- projectId: string;
67
- authority: AssertionAuthority;
68
- polarity: AssertionPolarity;
69
- scope: AssertionScope;
70
- meaning: AssertionMeaning;
71
- provenance: AssertionProvenance;
72
- observedAt: string;
73
- confirmedAt?: string;
74
- validFrom?: string;
75
- validUntil?: string;
76
- /** Logical withdrawal is append-only; physical privacy deletion is an application concern. */
77
- retractedAt?: string;
78
- supersedesAssertionId?: string;
79
- }
80
- export interface TasteAssertion extends PortableAssertionBase {
81
- role: "taste";
82
- }
83
- export interface ProjectContextAssertion extends PortableAssertionBase {
84
- role: "project_context";
85
- }
86
- export type RequirementOperator = "equals" | "not_equals" | "at_least" | "at_most" | "includes" | "excludes";
87
- export interface RequirementConstraint {
88
- operator: RequirementOperator;
89
- value: boolean | number | string;
90
- unit?: string;
91
- }
92
- export interface RequirementAssertion extends PortableAssertionBase {
93
- role: "requirement";
94
- /** The dimension is canonical meaning; the source-owned required value remains typed here. */
95
- constraint: RequirementConstraint;
96
- }
97
- /** Portable evidence semantics only. Ranking weights and serving policy belong to each consumer. */
98
- export type PortableTasteAssertion = TasteAssertion | ProjectContextAssertion | RequirementAssertion;
99
- export interface PortableAssertionTestVector {
100
- assertion: PortableTasteAssertion;
101
- id: string;
102
- expected: {
103
- actorId: string;
104
- subjectId: string;
105
- projectId: string;
106
- role: AssertionRole;
107
- meaningKind: AssertionMeaning["kind"];
108
- };
109
- }
110
- /** Executable fixtures for consumers serializing the portable envelope in another repository. */
111
- export declare const PORTABLE_ASSERTION_TEST_VECTORS: readonly PortableAssertionTestVector[];
112
- export {};
package/dist/taste.d.ts DELETED
@@ -1,2 +0,0 @@
1
- export { assertionMeaningFrom, type AmbiguousCanonicalization, type CanonicalizationInput, type CanonicalizationVerdict, type DeclinedCanonicalization, type ResolvedCanonicalization, type UnresolvedCanonicalization, } from "./canonicalization.js";
2
- export { type AmbiguousAssertionMeaning, type AssertionAuthority, type AssertionMeaning, type AssertionPolarity, type AssertionProvenance, type AssertionRole, type AssertionScope, type PortableAssertionTestVector, type PortableTasteAssertion, PORTABLE_ASSERTION_TEST_VECTORS, type ProjectContextAssertion, type RequirementAssertion, type RequirementConstraint, type RequirementOperator, type ResolvedAssertionMeaning, TAXONOMY_SNAPSHOT_VERSION, TASTE_ASSERTION_CONTRACT_VERSION, type TasteAssertion, type UnresolvedAssertionMeaning, } from "./taste-assertion.js";