@instruments/taxonomy 0.3.0 → 1.1.0

package/README.md

@@ -1,116 +1,53 @@
 # @instruments/taxonomy
 
-The canonical materials taxonomy for the Material Instruments ecosystem: the governed **dictionaries** (material families, sectors, and the hierarchical application zones) plus the **consumer crosswalks** that map an external vendor's local vocabulary onto the canon. This package is the single publishable home of the Material Semantics vocabularies that were previously vendored per-repo as drifting local copies.
+The canonical, data-only interiors and architecture terminology corpus.
 
-It also publishes appearance concepts and a portable taste-assertion contract. Applications own their evidence stores and ranking policy; this package owns shared meaning, source crosswalk verdicts, and the envelope that lets evidence travel without turning a source label into fact.
+## Version one contract
 
-## Install
+The package root exports the governed corpus and its release metadata:
 
-```sh
-pnpm add @instruments/taxonomy
-```
-
-## Import paths
-
-### `@instruments/taxonomy` — the dictionaries
+- `TAXONOMY_BASE_URI` — the authority used for every canonical concept URI.
+- `KNOWLEDGE_GRAPH` — normalized axis, facet, and concept nodes plus typed, bidirectional edges.
+- `LEXICAL_ENTRIES` — exhaustive declarative `equivalent`, `ambiguous`, and `declined` records for every canonical or observed authored spelling.
+- `TAXONOMY_CORPUS_METADATA` — deterministic node, edge, and lexical counts with the corpus revision, snapshot, and package version.
+- `TAXONOMY_CORPUS_REVISION`, `TAXONOMY_SNAPSHOT`, and `TAXONOMY_VERSION` — the exact content fingerprint, source snapshot, and package release identifiers.
 
-The pinned public vocabularies: `MATERIAL_FAMILIES` (17), `SECTORS` (10), `APPLICATIONS` (88 — 30 top-level zones plus 58 children). Each ships a `*_TERMS` array of labelled `TaxonomyTerm`s, an `as const` id tuple, a string-literal type, and a `Set`-backed guard.
+It also exports the TypeScript types for those values. It does not export a resolver, matcher, ranker, search route, local IDs, semantic IDs, or legacy aliases. Consumers build policy on top of the same data; the repository's private HTTP adapter is one such consumer.
 
-```ts
-import {
-  APPLICATIONS,
-  MATERIAL_FAMILIES,
-  applicationTopLevelOf,
-  isMaterialFamily,
-  type Application,
-} from "@instruments/taxonomy";
+Every public identity is a permanent HTTPS URI with lowercase kebab-case path segments:
 
-isMaterialFamily("wood"); // true
-applicationTopLevelOf("stair_tread"); // "stair_elevator"
-applicationTopLevelOf("wall"); // "wall" (already top-level)
+```text
+https://taxonomy.materialinstruments.com/id/axis/material
+https://taxonomy.materialinstruments.com/id/facet/palette/hue
+https://taxonomy.materialinstruments.com/id/material/walnut
 ```
 
-### `@instruments/taxonomy/crosswalks/miu` — the MIU consumer crosswalk
+ColorScope remains authoritative for colour concepts. Taxonomy does not mint graph nodes or URIs for ColorScope-governed terms; lexical records reference ColorScope identifiers without merging them into Taxonomy hierarchy. For example, `walnut` has a governed primary material reading and a secondary ColorScope reading.
 
-Maps the Materials In Use (MIU) local vocabularies onto the canonical dictionaries. Total, compile-time-checked `Record` maps plus string accessors that resolve unknown input to `null` instead of throwing.
+## Install and consume
 
-```ts
-import {
-  miuFamilyToCanonical,
-  MIU_SURFACE_APPLICATION_TO_CANONICAL,
-} from "@instruments/taxonomy/crosswalks/miu";
-
-miuFamilyToCanonical("ceramic_porcelain"); // "tile"
-miuFamilyToCanonical("greenery_planting"); // null (declines to classify)
-MIU_SURFACE_APPLICATION_TO_CANONICAL.railing; // "stair_railing"
+```sh
+pnpm add @instruments/taxonomy
 ```
 
-### Canonical bundles and match semantics
-
-Consumers compose qualified assertions into canonical bundles rather than minting app-specific compound tags. Every constitutive assertion is required; matched constitutive assertions score 2 and matched accents score 1. Unroled assertions default to accent, extra candidate annotations are not penalised, and the package publishes residential and commercial test vectors so another language can reproduce the ranking exactly.
-
 ```ts
-import { defineBundle, matchBundle } from "@instruments/taxonomy";
-
-const quietKitchen = defineBundle([
-  { assertion: "space.kitchen", role: "constitutive" },
-  { assertion: "mood.calm" },
-  { assertion: "style.minimalism" },
-]);
-
-matchBundle(quietKitchen, ["space.kitchen", "mood.calm"]);
-// { eligible: true, score: 0.75, ... }
-```
-
-`defineAlternatives` preserves a source term known to have one of several readings without guessing. The DesignShop and materia `Modern` crosswalk rows now carry an explicit any-of between `style.modernism` and `style.contemporary` instead of disappearing from downstream joins.
-
-### Appearance axes
-
-Product category, specific material, pattern, finish, format and construction are independent axes. That separation is deliberate: plain porcelain, geometric porcelain and stone-effect porcelain share `material.porcelain` while carrying different pattern concepts. A commercial carpet and residential wallcovering use the same pattern semantics; there is no “commercial style” branch.
-
-Requirement concepts name dimensions such as slip resistance, availability and fire performance. The assertion envelope carries the operator and required value separately, because a taxonomy can name the question but cannot assert that a particular product passes it.
-
-### `@instruments/taxonomy/crosswalks/designshop`
-
-The frozen DesignShop vocabulary resolves through a versioned four-state crosswalk:
+import {
+  KNOWLEDGE_GRAPH,
+  LEXICAL_ENTRIES,
+  TAXONOMY_CORPUS_METADATA,
+} from "@instruments/taxonomy";
 
-```ts
-import { canonicaliseDesignShop } from "@instruments/taxonomy/crosswalks/designshop";
+const walnut = KNOWLEDGE_GRAPH.nodes.find(
+  (node) =>
+    node.kind === "concept" &&
+    node.uri === "https://taxonomy.materialinstruments.com/id/material/walnut"
+);
 
-canonicaliseDesignShop({
-  provenance: {
-    sourceRecordId: "scheme:123",
-    sourceSnapshotVersion: "designshop-estate-1",
-    sourceSystem: "designshop",
-  },
-  sourceField: "pattern",
-  sourceValue: "Solid",
-});
-// resolved -> pattern.plain
+const walnutReadings = LEXICAL_ENTRIES.find(
+  (entry) => entry.phrase === "walnut"
+);
 ```
 
-`resolved`, `ambiguous`, `unresolved` and `declined` are different results. Unknown input remains unresolved with its raw value intact; only a curated row can decline. `Modern` remains an ambiguous choice between contemporary and modernism until another source or a person confirms one reading. `DESIGNSHOP_APPEARANCE_TEST_VECTORS` is the executable consumer contract.
-
-### `@instruments/taxonomy/taste`
-
-`PortableTasteAssertion` separates actor, taste subject and project; taste, context and requirement roles; canonical and unresolved meaning; scope, authority, polarity, time and provenance. It intentionally contains no boost, rank or serving weight. Those are application policy, not portable meaning. Requirement assertions additionally carry a typed constraint.
-
-`PORTABLE_ASSERTION_TEST_VECTORS` gives TypeScript and non-TypeScript consumers stable fixtures for serialization and contract tests.
-
-## Provenance and the re-sync ritual
-
-The dictionaries are lifted **verbatim** from materialgraph — `packages/schema/src/registry/value-dictionaries.ts`, snapshot `2026-07-08` (see the exported `PROVENANCE` constant). Every term was lifecycle-active at that snapshot; lifecycle fields are deferred from the published shape until governance needs them.
-
-To re-sync: re-read the upstream file, re-check the terms list, the `broaderTermId` edges, and the lifecycle fields, then bump this package. `src/materialgraph-sync.test.ts` mechanises the check — it reads a sibling `~/Sites/materialgraph` checkout and asserts every id is still present upstream (skipping only when that checkout is absent).
-
-## The other-vs-null policy
-
-For families and sectors, `other` is a **positive** classification — the canon's own dictionary would file the term under `other`. `null` **declines** to classify: it is not a member at all, it spans members, or any claim (including `other`) would be false. `unknown` therefore always maps to `null`, never `other` — unknown is epistemic ("we couldn't identify it") while other is ontological ("identified; fits no bucket"); the application crosswalk has no `other` term at all, so there its policy collapses to mapped-or-`null`.
-
-## Versioning
-
-Semver; changesets will drive releases later. Consumers should keep a **single pin** of this package. The anti-pattern to avoid is the colorscope `3.6.0` / `3.7.1` split, where two pinned copies of the same taxonomy drifted apart inside one dependency graph — the exact fragmentation this package exists to end.
-
-## Roadmap
+Changes to canonical meaning or identity are governed corpus changes. There is deliberately no backward-compatibility layer in V1; consumers migrate to the canonical URI.
 
-Additive minors, all backward-compatible: an exported Material Bank category tree artifact, and per-term lifecycle fields (status, deprecation, successor pointers) once governance requires them.
+Pin the exact package version and compare `TAXONOMY_CORPUS_REVISION` when a deployment needs to detect content drift. The revision is computed from the normalized graph and lexical entries, so it changes when governed corpus content changes even if the V1 API shape does not.