@instruments/taxonomy 0.2.0 → 0.3.0

package/dist/mapping-pvHk5VjC.d.ts

@@ -0,0 +1,31 @@
+import { a as BundleMemberInput, M as MatchStrength } from './match-CWzTEuL-.js';
+
+type CrosswalkMapping = {
+    status: "resolved";
+    assertions: readonly BundleMemberInput[];
+    match: MatchStrength;
+    note?: string;
+} | {
+    status: "ambiguous";
+    alternatives: readonly (readonly BundleMemberInput[])[];
+    match: MatchStrength;
+    note?: string;
+} | {
+    status: "declined";
+    reason: string;
+};
+/** A compound row: the source value is fully carried by the assertions together. */
+declare const resolved: (...assertions: readonly string[]) => CrosswalkMapping;
+/** One canonical term, interchangeable with the source value in retrieval. */
+declare const constitutive: (assertion: string) => CrosswalkMapping;
+/**
+ * A row that is not an identity. The strength says how it falls short and the note says why, both
+ * required: an approximation nobody had to justify is how a close match ships as an exact one.
+ */
+declare const approximates: (match: Exclude<MatchStrength, "exact">, note: string, ...assertions: readonly string[]) => CrosswalkMapping;
+/** The source is known to mean one of these and never recorded which. `match` grades each reading. */
+declare const ambiguous: (match: MatchStrength, ...assertions: readonly string[]) => CrosswalkMapping;
+/** A curated refusal. Distinct from an absent row, which means nobody has looked. */
+declare const declined: (reason: string) => CrosswalkMapping;
+
+export { type CrosswalkMapping as C, ambiguous as a, approximates as b, constitutive as c, declined as d, resolved as r };

package/dist/{match-BDI6Evro.d.ts → match-CWzTEuL-.d.ts}

@@ -348,6 +348,42 @@ interface AlternativesMatch {
 }
 /** The strongest eligible reading wins; bundle identity makes ties deterministic. */
 declare const matchAlternatives: (alternatives: CanonicalAlternatives, candidateAssertions: Iterable<string>) => AlternativesMatch;
+/** How well a candidate answered the query. `exact` matched every member, accents included. */
+type MatchTier = "exact" | "eligible" | "relaxed";
+/** A subject to rank: an opaque id and the assertions annotating it. */
+interface CandidateAnnotations {
+    id: string;
+    assertions: readonly string[];
+}
+interface RankedCandidate {
+    id: string;
+    tier: MatchTier;
+    match: BundleMatch;
+}
+interface BundleSearch {
+    /** The strongest tier present. Absent when no candidate carried even one member. */
+    tier?: MatchTier;
+    results: readonly RankedCandidate[];
+    /** True when nothing was eligible and the relaxed tier was served in its place. */
+    relaxed: boolean;
+    /**
+     * Constitutive members NO candidate in this corpus carries. Populated only when nothing was
+     * eligible, because that is when it is the answer: these are the conjuncts the corpus cannot
+     * satisfy, and naming them is what turns an empty result into a usable one.
+     */
+    blocking: readonly string[];
+}
+interface SearchOptions {
+    /** Refuse the relaxed tier: return nothing rather than a labelled partial answer. */
+    strict?: boolean;
+    /** Truncate the ranked list. Applied after ordering, so it never changes which result is first. */
+    limit?: number;
+}
+/**
+ * Rank a corpus against a bundle under the published rule. Deterministic: the same corpus in any
+ * input order returns the same list.
+ */
+declare const searchBundle: (bundle: CanonicalBundle, candidates: Iterable<CandidateAnnotations>, options?: SearchOptions) => BundleSearch;
 interface MatchTestCandidate {
     assertions: readonly string[];
     id: string;
@@ -364,4 +400,4 @@ interface MatchTestVector {
  */
 declare const MATCH_TEST_VECTORS: readonly MatchTestVector[];
 
-export { type AlternativeReason as A, type BundleMemberInput as B, type CanonicalAlternatives as C, DEFAULT_BUNDLE_ROLE as D, type ExternalMapping as E, MATCH_TEST_VECTORS as M, type PeriodSpan as P, type RelationPredicate as R, type SearchedWithout as S, type Term as T, type UsageBand as U, type AlternativesMatch as a, type BundleMatch as b, type BundleMember as c, type BundleRole as d, type CanonicalBundle as e, type ExternalScheme as f, MATCH_WEIGHTS as g, type MatchStrength as h, type MatchTestCandidate as i, type MatchTestVector as j, type RelationRole as k, type SourceBasis as l, type StyleKind as m, type TermProvenance as n, type TermRelation as o, type TermStatus as p, type TermUsage as q, type UsageWithheld as r, defineAlternatives as s, defineBundle as t, matchAlternatives as u, matchBundle as v };
+export { type AlternativeReason as A, type BundleRole as B, type CanonicalAlternatives as C, DEFAULT_BUNDLE_ROLE as D, type ExternalMapping as E, matchBundle as F, searchBundle as G, type MatchStrength as M, type PeriodSpan as P, type RelationPredicate as R, type SearchOptions as S, type Term as T, type UsageBand as U, type BundleMemberInput as a, type AlternativesMatch as b, type BundleMatch as c, type BundleMember as d, type BundleSearch as e, type CandidateAnnotations as f, type CanonicalBundle as g, type ExternalScheme as h, MATCH_TEST_VECTORS as i, MATCH_WEIGHTS as j, type MatchTestCandidate as k, type MatchTestVector as l, type MatchTier as m, type RankedCandidate as n, type RelationRole as o, type SearchedWithout as p, type SourceBasis as q, type StyleKind as r, type TermProvenance as s, type TermRelation as t, type TermStatus as u, type TermUsage as v, type UsageWithheld as w, defineAlternatives as x, defineBundle as y, matchAlternatives as z };

package/dist/taste.d.ts

@@ -1,4 +1,4 @@
-import { C as CanonicalAlternatives, e as CanonicalBundle } from './match-BDI6Evro.js';
+import { C as CanonicalAlternatives, g as CanonicalBundle, M as MatchStrength } from './match-CWzTEuL-.js';
 
 declare const TASTE_ASSERTION_CONTRACT_VERSION: "1.0.0";
 declare const TAXONOMY_SNAPSHOT_VERSION: "2026-08-25";
@@ -124,10 +124,21 @@ interface CanonicalisationBase extends CanonicalisationInput {
 interface ResolvedCanonicalisation extends CanonicalisationBase {
     status: "resolved";
     canonical: CanonicalBundle;
+    /**
+     * How strongly the canonical bundle stands for the source value, in SKOS's own vocabulary. A
+     * consumer may treat `exact` as an identity and must treat everything else as an approximation
+     * it has been told about. See `crosswalks/strength.ts` for the direction convention.
+     */
+    match: MatchStrength;
+    /** Why the row is not exact. Present whenever `match` is not `exact`. */
+    note?: string;
 }
 interface AmbiguousCanonicalisation extends CanonicalisationBase {
     status: "ambiguous";
     alternatives: CanonicalAlternatives;
+    /** How strongly each alternative would stand for the source value, were it the right reading. */
+    match: MatchStrength;
+    note?: string;
 }
 interface UnresolvedCanonicalisation extends CanonicalisationBase {
     status: "unresolved";

package/dist/taste.js

@@ -5,7 +5,7 @@ import {
   PORTABLE_ASSERTION_TEST_VECTORS,
   TASTE_ASSERTION_CONTRACT_VERSION,
   TAXONOMY_SNAPSHOT_VERSION
-} from "./chunk-XLUE3IC2.js";
+} from "./chunk-FCMCKNQF.js";
 export {
   PORTABLE_ASSERTION_TEST_VECTORS,
   TASTE_ASSERTION_CONTRACT_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/taxonomy",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Canonical materials taxonomy for the Material Instruments ecosystem — governed dictionaries (material families, sectors, applications) and consumer crosswalks.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -22,6 +22,10 @@
       "types": "./dist/crosswalks/miu.d.ts",
       "import": "./dist/crosswalks/miu.js"
     },
+    "./crosswalks/materialgraph": {
+      "types": "./dist/crosswalks/materialgraph.d.ts",
+      "import": "./dist/crosswalks/materialgraph.js"
+    },
     "./crosswalks/designshop": {
       "types": "./dist/crosswalks/designshop.d.ts",
       "import": "./dist/crosswalks/designshop.js"

package/dist/chunk-C2ZPDTOU.js

@@ -1,151 +0,0 @@
-// src/match.ts
-var ROLE_WEIGHT = {
-  accent: 1,
-  constitutive: 2
-};
-var MATCH_WEIGHTS = ROLE_WEIGHT;
-var DEFAULT_BUNDLE_ROLE = "accent";
-var checkedAssertion = (assertion) => {
-  const normalized = assertion.trim();
-  if (normalized.length === 0) {
-    throw new Error("a canonical assertion cannot be empty");
-  }
-  return normalized;
-};
-var defineBundle = (inputs) => {
-  if (inputs.length === 0) {
-    throw new Error("a canonical bundle must contain at least one assertion");
-  }
-  const byAssertion = /* @__PURE__ */ new Map();
-  for (const input of inputs) {
-    const assertion = checkedAssertion(input.assertion);
-    const role = input.role ?? DEFAULT_BUNDLE_ROLE;
-    const previous = byAssertion.get(assertion);
-    byAssertion.set(assertion, previous === "constitutive" ? previous : role);
-  }
-  const members = [...byAssertion].map(([assertion, role]) => ({ assertion, role })).toSorted((a, b) => a.assertion.localeCompare(b.assertion) || a.role.localeCompare(b.role));
-  const serialization = members.map(({ assertion, role }) => `${role}:${assertion}`).join("|");
-  return {
-    id: `bundle:${encodeURIComponent(serialization)}`,
-    kind: "all-of",
-    members,
-    serialization
-  };
-};
-var defineAlternatives = (inputs, reason) => {
-  const bySerialization = /* @__PURE__ */ new Map();
-  for (const input of inputs) {
-    const bundle = "kind" in input ? input : defineBundle(input);
-    bySerialization.set(bundle.serialization, bundle);
-  }
-  const alternatives = [...bySerialization.values()].toSorted(
-    (a, b) => a.serialization.localeCompare(b.serialization)
-  );
-  if (alternatives.length < 2) {
-    throw new Error("canonical alternatives must contain at least two distinct bundles");
-  }
-  const serialization = alternatives.map(({ id }) => id).join("||");
-  return {
-    alternatives,
-    id: `alternatives:${encodeURIComponent(serialization)}`,
-    kind: "any-of",
-    reason,
-    serialization
-  };
-};
-var matchBundle = (bundle, candidateAssertions) => {
-  const candidate = new Set(candidateAssertions);
-  const matched = bundle.members.filter(({ assertion }) => candidate.has(assertion));
-  const missing = bundle.members.filter(({ assertion }) => !candidate.has(assertion));
-  const missingConstitutive = missing.filter(({ role }) => role === "constitutive").map(({ assertion }) => assertion);
-  const missingAccents = missing.filter(({ role }) => role === "accent").map(({ assertion }) => assertion);
-  const eligible = missingConstitutive.length === 0;
-  const availableWeight = bundle.members.reduce((sum, { role }) => sum + ROLE_WEIGHT[role], 0);
-  const matchedWeight = matched.reduce((sum, { role }) => sum + ROLE_WEIGHT[role], 0);
-  return {
-    eligible,
-    matched: matched.map(({ assertion }) => assertion),
-    missingAccents,
-    missingConstitutive,
-    score: eligible ? matchedWeight / availableWeight : 0
-  };
-};
-var matchAlternatives = (alternatives, candidateAssertions) => {
-  const assertions = [...candidateAssertions];
-  const ranked = alternatives.alternatives.map((alternative) => ({ alternative, match: matchBundle(alternative, assertions) })).toSorted(
-    (a, b) => Number(b.match.eligible) - Number(a.match.eligible) || b.match.score - a.match.score || a.alternative.id.localeCompare(b.alternative.id)
-  );
-  const [strongest] = ranked;
-  if (strongest === void 0) {
-    throw new Error("canonical alternatives contain no bundles");
-  }
-  return strongest;
-};
-var COTTAGE = "evokes(typology.cottage)";
-var COTSWOLDS = "evokes(place.region.cotswolds)";
-var SHELTERING = "mood.sheltering";
-var GREEN = "palette.hue.green";
-var RESTAURANT = "space.restaurant";
-var INDUSTRIAL = "style.industrial";
-var MOODY = "mood.moody";
-var COOL = "palette.temperature.cool";
-var MATCH_TEST_VECTORS = [
-  {
-    candidates: [
-      {
-        assertions: [COTTAGE, COTSWOLDS, SHELTERING, GREEN],
-        id: "residential-exact"
-      },
-      {
-        assertions: [COTTAGE, SHELTERING, GREEN],
-        id: "residential-near"
-      },
-      {
-        assertions: [COTSWOLDS, SHELTERING, GREEN],
-        id: "residential-wrong-building"
-      }
-    ],
-    expectedEligibleOrder: ["residential-exact", "residential-near"],
-    id: "cotswolds-green-cosy-cottage",
-    query: defineBundle([
-      { assertion: COTTAGE, role: "constitutive" },
-      { assertion: COTSWOLDS },
-      { assertion: SHELTERING },
-      { assertion: GREEN }
-    ])
-  },
-  {
-    candidates: [
-      {
-        assertions: [RESTAURANT, INDUSTRIAL, MOODY, COOL],
-        id: "commercial-exact"
-      },
-      {
-        assertions: [RESTAURANT, INDUSTRIAL, MOODY],
-        id: "commercial-near"
-      },
-      {
-        assertions: ["typology.restaurant", INDUSTRIAL, MOODY],
-        id: "commercial-wrong-scale"
-      }
-    ],
-    expectedEligibleOrder: ["commercial-exact", "commercial-near"],
-    id: "moody-industrial-restaurant",
-    query: defineBundle([
-      { assertion: RESTAURANT, role: "constitutive" },
-      { assertion: INDUSTRIAL, role: "constitutive" },
-      { assertion: MOODY },
-      { assertion: COOL }
-    ])
-  }
-];
-
-export {
-  MATCH_WEIGHTS,
-  DEFAULT_BUNDLE_ROLE,
-  defineBundle,
-  defineAlternatives,
-  matchBundle,
-  matchAlternatives,
-  MATCH_TEST_VECTORS
-};