@instruments/materialgraph 0.25.0 → 0.27.0

package/samplize-colorvec.js

@@ -3,43 +3,54 @@ export const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
 export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
 const decodeVector = (encoded) => {
     const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
-    if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4)
+    if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4) {
         throw new Error("Invalid colour vector size.");
+    }
     const view = new DataView(bytes.buffer);
     return Array.from({ length: EMBEDDING_VECTOR_SIZE }, (_, i) => view.getFloat32(i * 4, true));
 };
 const facets = ["brand", "family", "lightness", "intensity"];
 const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 export const samplizeSolidColorVector = (hex) => {
-    if (!/^#[0-9a-f]{6}$/i.test(hex))
+    if (!/^#[0-9a-f]{6}$/i.test(hex)) {
         throw new Error("A six-digit published colour is required.");
+    }
     return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
 };
 /** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
-export function selectSamplizeEligiblePaints(paints, input) {
+export const selectSamplizeEligiblePaints = (paints, input) => {
     const reference = input.reference
         ? paints.find((p) => p.variantId === input.reference)
         : undefined;
-    if (input.reference && !reference)
+    if (input.reference && !reference) {
         throw new Error("The reference is absent from this catalogue version.");
-    const low = input.lightnessMin ?? 0, high = input.lightnessMax ?? 1;
-    const cool = input.temperatureMin ?? -0.4, warm = input.temperatureMax ?? 0.4;
+    }
+    const low = input.lightnessMin ?? 0;
+    const high = input.lightnessMax ?? 1;
+    const cool = input.temperatureMin ?? -0.4;
+    const warm = input.temperatureMax ?? 0.4;
     if (![low, high, cool, warm].every(Number.isFinite) ||
         low > high ||
-        cool > warm)
+        cool > warm) {
         throw new Error("Appearance ranges must be finite and ordered.");
+    }
     const candidates = paints.filter((p) => {
-        if (!reference)
+        if (!reference) {
             return true;
-        if (p.variantId === reference.variantId)
+        }
+        if (p.variantId === reference.variantId) {
             return false;
-        if (input.direction === "lighter")
+        }
+        if (input.direction === "lighter") {
             return p.oklab.L > reference.oklab.L;
-        if (input.direction === "darker")
+        }
+        if (input.direction === "darker") {
             return p.oklab.L < reference.oklab.L;
-        if (input.direction === "muted")
+        }
+        if (input.direction === "muted") {
             return (Math.hypot(p.oklab.a, p.oklab.b) <
                 Math.hypot(reference.oklab.a, reference.oklab.b));
+        }
         return true;
     });
     const matches = (p, omit) => p.oklab.L >= low &&
@@ -50,25 +61,30 @@ export function selectSamplizeEligiblePaints(paints, input) {
     const counts = {
         brand: {},
         family: {},
-        lightness: {},
         intensity: {},
+        lightness: {},
     };
-    for (const p of candidates)
-        for (const f of facets)
-            if (matches(p, f))
+    for (const p of candidates) {
+        for (const f of facets) {
+            if (matches(p, f)) {
                 counts[f][p[f]] = (counts[f][p[f]] ?? 0) + 1;
+            }
+        }
+    }
     const eligible = candidates.filter((p) => matches(p));
-    return { reference, eligible, counts };
-}
+    return { counts, eligible, reference };
+};
 /** Official portable MG ranking over its complete versioned sampling-channel projection. */
-export function createSamplizeColorVecIndex(cache) {
+export const createSamplizeColorVecIndex = (cache) => {
     if (cache.embeddingVersion !== EMBEDDING_VERSION ||
-        cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION)
+        cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION) {
         throw new Error("The colour cache uses an incompatible embedding or ranking version. Refresh it before searching.");
+    }
     if (!cache.sourceVersion ||
         !cache.dictionaryVersion ||
-        !Number.isFinite(Date.parse(cache.generatedAt)))
+        !Number.isFinite(Date.parse(cache.generatedAt))) {
         throw new Error("The colour cache is missing its provenance.");
+    }
     const paints = cache.paints.map((p) => ({
         ...p,
         vector: typeof p.vector === "string" ? decodeVector(p.vector) : p.vector,
@@ -78,8 +94,9 @@ export function createSamplizeColorVecIndex(cache) {
         if (identities.has(paint.variantId) ||
             paint.vector.length !== EMBEDDING_VECTOR_SIZE ||
             !paint.vector.every(Number.isFinite) ||
-            ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite))
+            ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite)) {
             throw new Error("The colour cache contains invalid or duplicate paint records.");
+        }
         identities.add(paint.variantId);
     }
     const vectors = new Map();
@@ -88,8 +105,9 @@ export function createSamplizeColorVecIndex(cache) {
         let value = vectors.get(key);
         if (!value) {
             value = samplizeSolidColorVector(hex);
-            if (vectors.size >= 512)
+            if (vectors.size >= 512) {
                 vectors.delete(vectors.keys().next().value);
+            }
             vectors.set(key, value);
         }
         return value;
@@ -97,36 +115,42 @@ export function createSamplizeColorVecIndex(cache) {
     return {
         search(input) {
             const limit = input.limit ?? 48;
-            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
                 throw new Error("Choose between 1 and 100 suggestions.");
+            }
             const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
             const palette = (input.palette?.length
                 ? input.palette
                 : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
                 .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
-                .sort((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
+                .toSorted((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
             if (palette.length > 12 ||
                 palette.some((p) => !Number.isFinite(p.proportion) ||
                     p.proportion <= 0 ||
-                    p.proportion > 1))
+                    p.proportion > 1)) {
                 throw new Error("Supply up to twelve positive image colour shares.");
+            }
             const total = palette.reduce((sum, p) => sum + p.proportion, 0);
             const buckets = palette.map((p, position) => ({
                 ...p,
+                paints: [],
                 position,
-                vector: vectorFor(p.hex),
                 quota: Math.floor((limit * p.proportion) / total),
                 remainder: ((limit * p.proportion) / total) % 1,
-                paints: [],
+                vector: vectorFor(p.hex),
             }));
             let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
-            for (const p of [...buckets].sort((a, b) => b.remainder - a.remainder || a.position - b.position))
-                if (remaining-- > 0)
+            for (const p of [...buckets].toSorted((a, b) => b.remainder - a.remainder || a.position - b.position)) {
+                if (remaining-- > 0) {
                     p.quota++;
+                }
+            }
             for (const paint of eligible) {
-                let best = buckets[0], score = embeddingCosineSimilarity(paint.vector, best.vector);
+                let best = buckets[0];
+                let score = embeddingCosineSimilarity(paint.vector, best.vector);
                 for (let i = 1; i < buckets.length; i++) {
-                    const candidate = buckets[i], next = embeddingCosineSimilarity(paint.vector, candidate.vector);
+                    const candidate = buckets[i];
+                    const next = embeddingCosineSimilarity(paint.vector, candidate.vector);
                     if (next > score) {
                         best = candidate;
                         score = next;
@@ -135,33 +159,33 @@ export function createSamplizeColorVecIndex(cache) {
                 best.paints.push({ id: paint.variantId, score });
             }
             const groups = buckets
-                .sort((a, b) => b.proportion - a.proportion || a.position - b.position)
+                .toSorted((a, b) => b.proportion - a.proportion || a.position - b.position)
                 .map((p) => {
                 const ids = p.paints
-                    .sort((a, b) => b.score - a.score || identityOrder(a.id, b.id))
+                    .toSorted((a, b) => b.score - a.score || identityOrder(a.id, b.id))
                     .slice(0, p.quota)
                     .map((paint) => paint.id);
                 return {
                     hex: p.hex,
+                    ids,
                     proportion: p.proportion,
                     quota: p.quota,
-                    ids,
                     shortfall: p.quota - ids.length,
                 };
             });
             const ids = groups.flatMap((p) => p.ids);
             return {
-                ids,
-                groups,
-                limited: eligible.length > ids.length,
-                eligibleCount: eligible.length,
+                countBasis: "complete-catalogue",
                 counts,
-                sourceVersion: cache.sourceVersion,
                 dictionaryVersion: cache.dictionaryVersion,
+                eligibleCount: eligible.length,
                 embeddingVersion: cache.embeddingVersion,
+                groups,
+                ids,
+                limited: eligible.length > ids.length,
                 rankingVersion: cache.rankingVersion,
-                countBasis: "complete-catalogue",
+                sourceVersion: cache.sourceVersion,
             };
         },
     };
-}
+};

package/schema-resource-types.d.ts

@@ -8,40 +8,46 @@ export type SchemaResource = "blocks" | "attributes" | "verticals" | "productTyp
  * it must cover cannot drift apart.
  */
 export declare const SCHEMA_RESOURCE_OPERATION_IDS: {
-    readonly blocks: "list_schema_blocks";
     readonly attributes: "list_schema_attributes";
-    readonly verticals: "list_schema_verticals";
+    readonly blocks: "list_schema_blocks";
+    readonly mappings: "list_schema_mappings";
+    readonly productTypeTemplates: "list_schema_product_type_templates";
     readonly productTypes: "list_schema_product_types";
+    readonly sourceRequirements: "list_schema_source_requirements";
     readonly units: "list_schema_units";
     readonly valueDictionaries: "list_schema_value_dictionaries";
-    readonly sourceRequirements: "list_schema_source_requirements";
-    readonly productTypeTemplates: "list_schema_product_type_templates";
-    readonly mappings: "list_schema_mappings";
+    readonly verticals: "list_schema_verticals";
 };
 export type SchemaResourceRequest = SchemaResource;
-export interface SchemaLifecycle {
+export type SchemaLifecycle = {
     status: OpenEnum<"draft" | "active" | "deprecated">;
     introducedIn: string;
     deprecatedIn?: string;
     supersededBy?: string;
-}
-export interface SchemaExternalMapping {
+};
+export type SchemaExternalMapping = {
     target: OpenEnum<"schema_org" | "ifc_pset" | "bsdd" | "iso_23387" | "eclass" | "gs1_gdm" | "gdsn" | "etim" | "uniclass">;
     targetPath: string;
     mappingType: OpenEnum<"direct" | "transform" | "derived" | "classification" | "semantic">;
+    /**
+     * SKOS mapping strength, read from the MaterialGraph side. Only `exact`
+     * licenses substituting one concept for the other.
+     */
+    matchStrength?: SchemaMatchStrength;
     notes?: string;
-}
-export interface SchemaBlockItem {
+};
+export type SchemaMatchStrength = OpenEnum<"exact" | "close" | "broad" | "narrow" | "related">;
+export type SchemaBlockItem = {
     id: string;
     semanticId: string;
     lifecycle: SchemaLifecycle;
     name: string;
     description: string;
     attributeIds: string[];
-}
-export type KnownSchemaQuantityKind = "length" | "area" | "volume" | "mass" | "time" | "temperature" | "currency" | "ratio" | "density" | "coverage" | "emissions" | "force" | "power" | "voltage" | "current" | "frequency" | "luminous_flux" | "color_temperature" | "count" | "unitless";
+};
+export type KnownSchemaQuantityKind = "length" | "area" | "volume" | "mass" | "time" | "temperature" | "currency" | "ratio" | "density" | "coverage" | "emissions" | "force" | "thermal_conductivity" | "power" | "voltage" | "current" | "frequency" | "luminous_flux" | "color_temperature" | "count" | "unitless";
 export type SchemaQuantityKind = OpenEnum<KnownSchemaQuantityKind>;
-export interface SchemaAttributeItem {
+export type SchemaAttributeItem = {
     id: string;
     semanticId: string;
     lifecycle: SchemaLifecycle;
@@ -58,14 +64,14 @@ export interface SchemaAttributeItem {
     comparable: boolean;
     usedInBlocks: string[];
     enumValues: string[] | null;
-}
-export interface SchemaVerticalItem {
+};
+export type SchemaVerticalItem = {
     id: string;
     displayName: string;
     description: string;
-}
+};
 export type SchemaApplicability = OpenEnum<"required" | "recommended" | "optional" | "unusual">;
-export interface SchemaProductTypeBlock {
+export type SchemaProductTypeBlock = {
     blockId: string;
     applicability: SchemaApplicability;
     requiredAttributes?: string[];
@@ -74,19 +80,21 @@ export interface SchemaProductTypeBlock {
     completenessWeight?: number;
     notes?: string;
     optional?: boolean;
-}
-export interface SchemaProductTypeItem {
+};
+export type SchemaProductTypeItem = {
     id: string;
     name: string;
     description?: string;
+    /** Display names this type carried before a rename, kept so they still find it. */
+    formerNames?: string[];
     verticalId: string;
     parentProductTypeGroupId?: string;
     blocks: SchemaProductTypeBlock[];
     productTypeSpecificAttributes?: string[];
     semanticId: string;
     lifecycle: SchemaLifecycle;
-}
-export interface SchemaUnitItem {
+};
+export type SchemaUnitItem = {
     id: string;
     name: string;
     symbol: string;
@@ -97,10 +105,14 @@ export interface SchemaUnitItem {
         offset?: number;
     };
     notes?: string;
+    /** UN/CEFACT Rec 20 common code (schema.org `unitCode`); absent when Rec 20 has none. */
+    uncefactCode?: string;
+    /** QUDT unit IRI, where exactly one QUDT unit matches. */
+    qudtUnit?: string;
     semanticId: string;
     lifecycle: SchemaLifecycle;
-}
-export interface SchemaValueDictionaryTerm {
+};
+export type SchemaValueDictionaryTerm = {
     id: string;
     label: string;
     aliases?: string[];
@@ -108,20 +120,20 @@ export interface SchemaValueDictionaryTerm {
     externalMappings?: SchemaExternalMapping[];
     semanticId: string;
     lifecycle: SchemaLifecycle;
-}
-export interface SchemaValueDictionaryItem {
+};
+export type SchemaValueDictionaryItem = {
     id: string;
     name: string;
     description: string;
     terms: SchemaValueDictionaryTerm[];
     semanticId: string;
     lifecycle: SchemaLifecycle;
-}
+};
 export type KnownSchemaSourceType = "manufacturer_page" | "technical_data_sheet" | "safety_data_sheet" | "test_report" | "certificate" | "image" | "commerce_page" | "catalog_pdf" | "derived_analysis";
 export type SchemaSourceType = OpenEnum<KnownSchemaSourceType>;
 export type KnownSchemaSourceMethod = "manual_review" | "agent_extract" | "pdf_extract" | "image_analysis" | "html_scrape" | "structured_feed" | "calculation";
 export type SchemaSourceMethod = OpenEnum<KnownSchemaSourceMethod>;
-export interface SchemaSourceRequirementItem {
+export type SchemaSourceRequirementItem = {
     id: string;
     name: string;
     description: string;
@@ -130,11 +142,11 @@ export interface SchemaSourceRequirementItem {
     minConfidence: number;
     reviewRequired: boolean;
     freshnessDays?: number;
-    sourceBasis?: OpenEnum<"declared" | "derived" | "declared">;
+    sourceBasis?: OpenEnum<"declared" | "derived">;
     semanticId: string;
     lifecycle: SchemaLifecycle;
-}
-export interface SchemaProductTypeTemplateBlock {
+};
+export type SchemaProductTypeTemplateBlock = {
     blockId: string;
     applicability: SchemaApplicability;
     requiredAttributes?: string[];
@@ -142,8 +154,8 @@ export interface SchemaProductTypeTemplateBlock {
     sourceRequirementId?: string;
     completenessWeight?: number;
     notes?: string;
-}
-export interface SchemaProductTypeTemplateItem {
+};
+export type SchemaProductTypeTemplateItem = {
     id: string;
     name: string;
     productTypeId: string;
@@ -152,17 +164,18 @@ export interface SchemaProductTypeTemplateItem {
     notes?: string;
     semanticId: string;
     lifecycle: SchemaLifecycle;
-}
-export interface SchemaMappingItem {
+};
+export type SchemaMappingItem = {
     target: SchemaExternalMapping["target"];
     subjectKind?: OpenEnum<"attribute" | "block" | "product_type" | "template" | "unit" | "value_dictionary" | "value_dictionary_term">;
     subjectId?: string;
     canonicalPath: string;
     targetPath: string;
     mappingType: SchemaExternalMapping["mappingType"];
+    matchStrength?: SchemaMatchStrength;
     notes?: string;
-}
-export interface SchemaResourceItemMap {
+};
+export type SchemaResourceItemMap = {
     blocks: SchemaBlockItem;
     attributes: SchemaAttributeItem;
     verticals: SchemaVerticalItem;
@@ -172,10 +185,10 @@ export interface SchemaResourceItemMap {
     sourceRequirements: SchemaSourceRequirementItem;
     productTypeTemplates: SchemaProductTypeTemplateItem;
     mappings: SchemaMappingItem;
-}
-export interface SchemaResourceResponse<K extends SchemaResource = SchemaResource> {
+};
+export type SchemaResourceResponse<K extends SchemaResource = SchemaResource> = {
     kind: K;
     schemaVersion: string;
     items: SchemaResourceItemMap[K][];
     totalCount: number;
-}
+};

package/schema-resource-types.js

@@ -5,13 +5,13 @@
  * it must cover cannot drift apart.
  */
 export const SCHEMA_RESOURCE_OPERATION_IDS = {
-    blocks: "list_schema_blocks",
     attributes: "list_schema_attributes",
-    verticals: "list_schema_verticals",
+    blocks: "list_schema_blocks",
+    mappings: "list_schema_mappings",
+    productTypeTemplates: "list_schema_product_type_templates",
     productTypes: "list_schema_product_types",
+    sourceRequirements: "list_schema_source_requirements",
     units: "list_schema_units",
     valueDictionaries: "list_schema_value_dictionaries",
-    sourceRequirements: "list_schema_source_requirements",
-    productTypeTemplates: "list_schema_product_type_templates",
-    mappings: "list_schema_mappings",
+    verticals: "list_schema_verticals",
 };

package/search-card-types.d.ts

@@ -19,7 +19,7 @@ import type { OpenEnum, SearchData, SearchResponse } from "./types.js";
  * `variantId` at `view: "full"` or via `material()` before claiming anything the
  * card does not carry.
  */
-export interface SearchCardItem {
+export type SearchCardItem = {
     /** Accepted sampleability fact. Absent means unknown, never false. */
     sampleable?: boolean;
     /** Opaque — round-trip verbatim. */
@@ -31,6 +31,19 @@ export interface SearchCardItem {
     name: string;
     variantName: string | null;
     imageUrl: string | null;
+    /**
+     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest. Key a
+     * cache or dedupe on it rather than the URL. ABSENT means no hash is on
+     * record, never that there is no image.
+     */
+    imageSha256?: string;
+    /**
+     * How many eligible variants the row's product has, the same set
+     * `listVariants` pages, so a follow-up list returns this many: the card's
+     * "12 colourways". ABSENT means the product is unknown or has no eligible
+     * variant.
+     */
+    variantCount?: number;
     /**
      * The manufacturer's own item code, the same key the full item carries.
      * Reach for it when two cards read alike: `name` is the PRODUCT name, and a
@@ -54,11 +67,20 @@ export interface SearchCardItem {
      * attribute rather than a list of candidates.
      */
     attributes?: Record<string, string | string[] | null>;
-}
+};
 /** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
-export interface SearchCardResponse extends Omit<SearchResponse, "data"> {
+export type SearchCardResponse = {
     data: Omit<SearchData, "view" | "results"> & {
         view: OpenEnum<"card">;
         results: SearchCardItem[];
     };
-}
+} & Omit<SearchResponse, "data">;
+/**
+ * The request forms the server answers with {@link SearchCardResponse}:
+ * `view: "card"`, or `intent: "typeahead"`, which forces the card view.
+ */
+export type CardProjectionRequest = {
+    view: "card";
+} | {
+    intent: "typeahead";
+};

package/search-index-plan-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module search-index-plan-types
+ * @description The plan the one search ran on, as `/search` reports it under
+ * `explain.plan` (ADR 0031). Mirrors `searchIndexPlanReceiptSchema` in
+ * `@materialgraph/products/search-index/plan-schema`; `key-parity.test.ts`
+ * holds the two to the same fields.
+ */
+import type { CorpusScope } from "./corpus-scope-types.js";
+/** One attribute the plan wants: its terms, or any value when `presence`. */
+export type SearchIndexPlanWant = {
+    attributeId: string;
+    /** Share of the category's materials stating the attribute, 0 to 1. */
+    fill: number;
+    /** The words it was read from, or `"(filter)"` for a caller's filter. */
+    phrase: string;
+    /** Any stated value satisfies it; `terms` is then empty. */
+    presence?: true;
+    /** A hard want removes rows; a soft one only counts toward the order. */
+    strength: "hard" | "soft";
+    terms: string[];
+};
+/**
+ * The query's plan: the category, makers, wanted and excluded attribute terms,
+ * the colour, the words left for text, and the caller's corpus scope.
+ */
+export type SearchIndexPlan = {
+    brands: {
+        ids: string[];
+        names: string[];
+        phrase: string;
+    } | null;
+    category: {
+        label: string;
+        phrase: string;
+        productTypeIds: string[];
+    } | null;
+    colour: {
+        family12: string[];
+        familyId: string;
+        hex: string;
+        oklab: [number, number, number];
+        phrase: string;
+    } | null;
+    /** Present only when the caller sent a scope narrower than the whole graph. */
+    corpusScope?: Exclude<CorpusScope, "all">;
+    excludeBrands: string[];
+    excludes: {
+        attributeId: string;
+        phrase: string;
+        term: string;
+    }[];
+    /** Words the reading did not place, left for the text match. */
+    leftover: string[];
+    normalised: string;
+    softAlone: boolean;
+    vendorColourNames: string[];
+    wants: SearchIndexPlanWant[];
+};
+/**
+ * Which reading a search ran on (`version`, `source`), whether it came from
+ * the cache, the plan itself, and its signature, so two runs of one request
+ * can be compared plan for plan.
+ */
+export type SearchPlanReceipt = {
+    cached: boolean;
+    plan: SearchIndexPlan;
+    signature: string;
+    source: "dictionary" | "jev";
+    version: string;
+};

package/search-refinement-types.d.ts

@@ -1,5 +1,4 @@
-/** Types for structured refinements returned by MaterialGraph search. */
-import type { SearchInput } from "./types.js";
+/** The spec-filter vocabulary MaterialGraph's filter and preference inputs share. */
 /**
  * A hard canonical-attribute filter accepted by the search engine — a term match
  * (`{ attributeId, term }`), a presence check (`{ attributeId, hasValue: true }`)
@@ -23,7 +22,7 @@ import type { SearchInput } from "./types.js";
  * of this object — without it, "no GREENGUARD results" reads as "nobody is
  * certified" when it means "nobody is certified TO THIS EVIDENTIAL STANDARD".
  */
-export interface SearchFilterTrust {
+export type SearchFilterTrust = {
     /** Confidence floor, 0–1. A value below it is excluded, not marked failed. */
     minConfidence?: number;
     /**
@@ -45,7 +44,7 @@ export interface SearchFilterTrust {
     sourceBasis?: "catalog_feed" | "declared" | "derived";
     /** Fold the attribute's own registry confidence requirement in, server-side. */
     meetsRequirement?: true;
-}
+};
 /**
  * One HARD criterion. Applied as a restriction BEFORE ranking, so a filtered
  * search's empty result means "nothing on record satisfies this", never "nothing
@@ -57,10 +56,16 @@ export type SearchFilter = {
     term: string;
     trust?: SearchFilterTrust;
 } | {
-    /** Known effective values are required, and this term must be absent. */
     attributeId: string;
     excludesTerm: string;
     trust?: SearchFilterTrust;
+    /**
+     * What an UNKNOWN effective value does. Absent or `"drop"` (default)
+     * requires a known effective value — a variant that never states the
+     * attribute does not pass. `"pass"` admits it — a variant only fails by
+     * STATING the excluded term.
+     */
+    whenUnstated?: "drop" | "pass";
 }
 /**
  * TERM SET — the attribute must equal any ONE of these. OR within the entry;
@@ -96,38 +101,3 @@ export type SearchFilter = {
     max?: number;
     trust?: SearchFilterTrust;
 };
-/** One structured refinement returned with a search response. */
-export interface SearchSuggestion {
-    label: string;
-    /** Complete replacement request, not a partial patch. */
-    request: SearchInput;
-}
-/** One reading a {@link SearchDisambiguation} offers. */
-export interface SearchInterpretation {
-    id: string;
-    label: string;
-    kind: string;
-    /** True for the reading that ran; all false means the engine chose none. */
-    isDefault: boolean;
-    /** The colour this reading resolved to, when the ambiguity was a colour one. */
-    hex?: string;
-    /** Complete replacement request, not a partial patch. */
-    request: SearchInput;
-}
-/** The governed ambiguity classes emitted by MaterialGraph search. */
-export type SearchDisambiguationKind = "compliance-phrase" | "colour-material" | "paint-colour" | "paint-identity";
-/**
- * The server saying a query had multiple defensible readings.
- *
- * The reading that ran is flagged `isDefault`; every reading is false when the
- * engine deliberately chose none. Each carries a complete executable request,
- * so choosing a reading is a re-issue rather than a patch. Ignoring this block does not
- * make the ambiguity go away — it makes it invisible to the person who asked.
- */
-export interface SearchDisambiguation {
-    /** Compliance, colour-material, paint-colour, or paint-identity ambiguity. */
-    kind: SearchDisambiguationKind;
-    /** The ambiguous term or phrase. */
-    term: string;
-    interpretations: SearchInterpretation[];
-}

package/search-refinement-types.js

@@ -1 +1,2 @@
+/** The spec-filter vocabulary MaterialGraph's filter and preference inputs share. */
 export {};