@instruments/taxonomy 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,8 @@
 # @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 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.
+
+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.
 
 ## Install
 
@@ -16,9 +14,7 @@ pnpm add @instruments/taxonomy
 
 ### `@instruments/taxonomy` — the dictionaries
 
-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.
+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.
 
 ```ts
 import {
@@ -36,9 +32,7 @@ applicationTopLevelOf("wall"); // "wall" (already top-level)
 
 ### `@instruments/taxonomy/crosswalks/miu` — the MIU consumer crosswalk
 
-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.
+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.
 
 ```ts
 import {
@@ -51,35 +45,72 @@ miuFamilyToCanonical("greenery_planting"); // null (declines to classify)
 MIU_SURFACE_APPLICATION_TO_CANONICAL.railing; // "stair_railing"
 ```
 
+### 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:
+
+```ts
+import { canonicaliseDesignShop } from "@instruments/taxonomy/crosswalks/designshop";
+
+canonicaliseDesignShop({
+  provenance: {
+    sourceRecordId: "scheme:123",
+    sourceSnapshotVersion: "designshop-estate-1",
+    sourceSystem: "designshop",
+  },
+  sourceField: "pattern",
+  sourceValue: "Solid",
+});
+// resolved -> pattern.plain
+```
+
+`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.
+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).
+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`.
+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.
+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
 
-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.
+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.