@instruments/materialgraph 0.26.0 → 0.27.0

package/search-result-validation.d.ts

@@ -1,20 +1,4 @@
 import type { ValidationFailure } from "./validation.js";
-/** `verdictStateSchema` — the six live cell states. */
-export declare const VERDICT_STATES: readonly ["matched", "deviated", "failed", "unverified", "missing", "not_evaluated"];
-/** `attributeVerdictSchema.strength`. */
-export declare const VERDICT_STRENGTHS: readonly ["required", "preferred"];
-/** `verdictBaselineSchema` discriminant — the four arms of what a cell was judged against. */
-export declare const VERDICT_BASELINE_KINDS: readonly ["term", "presence", "seed", "image"];
-/** The `image` baseline arm's own `source` enum. */
-export declare const VERDICT_IMAGE_SOURCES: readonly ["variant", "vector"];
-/** `verdictDeviationSchema.direction`. */
-export declare const VERDICT_DEVIATION_DIRECTIONS: readonly ["above", "below", "other"];
-/** `verdictTrustGapSchema` — why a real value did not clear the trust bar. */
-export declare const VERDICT_TRUST_GAPS: readonly ["below_confidence", "basis_unmet", "proposed"];
-/** `verdictGradeSchema` — the rolled-up card grade. */
-export declare const VERDICT_GRADES: readonly ["meets_all", "close", "hard_no"];
-/** `visualMeaningSchema.basis` — where a meaning came from. */
-export declare const VISUAL_MEANING_BASES: readonly ["canonical_attribute", "image_colour_analysis"];
 /**
  * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
  * the first field that does not match `searchResultItemSchema`. Checks the shape

package/search-result-validation.js

@@ -1,44 +1,23 @@
-import { requireArray, requireBoolean, requireEnum, requireNonEmptyString, requireNonEmptyStringArray, requireNullableBoundedNumber, requireNullableEnum, requireNullableNonEmptyString, requireNullableNumber, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalNumber, requireOptionalString, requireRecord, requireString, requireIntegerAtLeast, } from "./validation.js";
-// ── Closed enum members (canonical `z.enum` mirrors) ─────────────────────────
-/** `verdictStateSchema` — the six live cell states. */
-export const VERDICT_STATES = [
-    "matched",
-    "deviated",
-    "failed",
-    "unverified",
-    "missing",
-    "not_evaluated",
-];
-/** `attributeVerdictSchema.strength`. */
-export const VERDICT_STRENGTHS = ["required", "preferred"];
-/** `verdictBaselineSchema` discriminant — the four arms of what a cell was judged against. */
-export const VERDICT_BASELINE_KINDS = [
-    "term",
-    "presence",
-    "seed",
-    "image",
-];
-/** The `image` baseline arm's own `source` enum. */
-export const VERDICT_IMAGE_SOURCES = ["variant", "vector"];
-/** `verdictDeviationSchema.direction`. */
-export const VERDICT_DEVIATION_DIRECTIONS = [
-    "above",
-    "below",
-    "other",
-];
-/** `verdictTrustGapSchema` — why a real value did not clear the trust bar. */
-export const VERDICT_TRUST_GAPS = [
-    "below_confidence",
-    "basis_unmet",
-    "proposed",
-];
-/** `verdictGradeSchema` — the rolled-up card grade. */
-export const VERDICT_GRADES = ["meets_all", "close", "hard_no"];
-/** `visualMeaningSchema.basis` — where a meaning came from. */
-export const VISUAL_MEANING_BASES = [
-    "canonical_attribute",
-    "image_colour_analysis",
-];
+/**
+ * The one runtime validator for a {@link SearchResultItem} on the wire — the
+ * hand-rolled, zero-runtime-dependency mirror of `searchResultItemSchema`
+ * (`packages/products/src/search/search-result-schema.ts`) and its full
+ * transitive closure, including `searchResultSignalsSchema`.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM THE TYPE MIRROR. `contract-parity.test.ts`
+ * proves the SDK's STATIC types match the canonical schemas. That is a
+ * compile-time proof about shapes; it validates nothing at run time. A malformed
+ * result item arriving over a stream was caught by neither, so the Match reader
+ * now checks every item through here.
+ *
+ * ONE HOME. This module is the single implementation — no copy lives inside
+ * `match-stream.ts`. It is package-internal (not re-exported from `index.ts`)
+ * because a published symbol is a permanent contract, and nothing outside the
+ * SDK needs to call it yet; promoting it later is additive.
+ *
+ * ENUMS ARE CLOSED, matching the canonical `z.enum(…)` members.
+ */
+import { requireArray, requireBoolean, requireEnum, requireNullableNumber, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalString, requireRecord, requireString, } from "./validation.js";
 // ── Leaf checks ──────────────────────────────────────────────────────────────
 /** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
 const checkPaletteSwatch = (value, what, fail) => {
@@ -50,23 +29,6 @@ const checkPaletteSwatch = (value, what, fail) => {
         requireNullableString(record.name, `${what}.name`, fail);
     }
 };
-/**
- * `variants[]` — one entry of a product-collapsed result's ranked variant list
- * (`collapsedVariantSchema`). A SLIM projection, not a nested result item: the
- * checks here are the whole shape.
- */
-const checkCollapsedVariant = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireString(record.variantId, `${what}.variantId`, fail);
-    requireNullableString(record.variantName, `${what}.variantName`, fail);
-    requireNullableString(record.color, `${what}.color`, fail);
-    // `.optional()`, NOT nullable: the emit path omits the key when no palette is
-    // on record rather than sending null.
-    requireOptionalString(record.hex, `${what}.hex`, fail);
-    requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
-    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
-    requireNumber(record.score, `${what}.score`, fail);
-};
 /** `colourMeta` — three independently optional strings. */
 const checkColourMeta = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
@@ -74,112 +36,10 @@ const checkColourMeta = (value, what, fail) => {
     requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
     requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
 };
-/** `searchResultSignalsSchema` — five required scores plus additive portrait. */
+/** `searchResultSignalsSchema` — the Match image cosine, nullable. */
 const checkSignals = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
-    if (record.portrait !== undefined) {
-        requireNullableNumber(record.portrait, `${what}.portrait`, fail);
-    }
-    for (const signal of ["image", "category", "colour", "lexical", "text"]) {
-        requireNullableNumber(record[signal], `${what}.${signal}`, fail);
-    }
-};
-/** `visualMeaningSchema` — note the NON-EMPTY `values` array and the closed `basis`. */
-const checkVisualMeaning = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireString(record.id, `${what}.id`, fail);
-    requireString(record.label, `${what}.label`, fail);
-    requireNonEmptyStringArray(record.values, `${what}.values`, fail);
-    requireEnum(record.basis, VISUAL_MEANING_BASES, `${what}.basis`, fail);
-    requireOptionalNumber(record.confidence, `${what}.confidence`, fail);
-    requireOptionalString(record.sourceBasis, `${what}.sourceBasis`, fail);
-    requireOptionalString(record.version, `${what}.version`, fail);
-    requireOptionalString(record.appliedAt, `${what}.appliedAt`, fail);
-};
-// ── Verdict subtree ──────────────────────────────────────────────────────────
-/**
- * `verdictBaselineSchema` — a discriminated union on `kind`. An unknown
- * discriminant is rejected, exactly as `z.discriminatedUnion` rejects it, and
- * each arm carries only the fields it needs.
- */
-const checkVerdictBaseline = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    const kind = requireEnum(record.kind, VERDICT_BASELINE_KINDS, `${what}.kind`, fail);
-    switch (kind) {
-        case "term": {
-            requireNonEmptyString(record.term, `${what}.term`, fail);
-            break;
-        }
-        case "presence": {
-            return;
-        }
-        case "seed": {
-            requireNonEmptyString(record.variantId, `${what}.variantId`, fail);
-            return;
-        }
-        default: {
-            // `image` — the like-this-picture arm.
-            requireEnum(record.source, VERDICT_IMAGE_SOURCES, `${what}.source`, fail);
-            requireNullableNonEmptyString(record.variantId, `${what}.variantId`, fail);
-        }
-    }
-};
-/** `verdictDeviationSchema` — a named near-miss. */
-const checkVerdictDeviation = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireEnum(record.direction, VERDICT_DEVIATION_DIRECTIONS, `${what}.direction`, fail);
-    requireNullableNumber(record.delta, `${what}.delta`, fail);
-    requireNullableString(record.unit, `${what}.unit`, fail);
-    requireNonEmptyString(record.label, `${what}.label`, fail);
-};
-/**
- * `attributeVerdictSchema` — nine fields plus the TWO cross-field invariants its
- * `.superRefine()` enforces. Those are relational rather than field-wise, which
- * is no obstacle to a hand-rolled validator: they are two conditionals, and the
- * schema's own doc calls them out as the reason a malformed cell can never reach
- * a consumer.
- */
-const checkAttributeVerdict = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireNonEmptyString(record.attributeId, `${what}.attributeId`, fail);
-    const state = requireEnum(record.state, VERDICT_STATES, `${what}.state`, fail);
-    requireEnum(record.strength, VERDICT_STRENGTHS, `${what}.strength`, fail);
-    checkVerdictBaseline(record.baseline, `${what}.baseline`, fail);
-    requireNullableString(record.value, `${what}.value`, fail);
-    requireNullableBoundedNumber(record.confidence, `${what}.confidence`, fail, 0, 1);
-    requireNullableString(record.sourceBasis, `${what}.sourceBasis`, fail);
-    if (record.citation !== undefined) {
-        const citation = requireRecord(record.citation, `${what}.citation`, fail);
-        requireNonEmptyString(citation.citationId, `${what}.citation.citationId`, fail);
-        requireNonEmptyString(citation.sourceType, `${what}.citation.sourceType`, fail);
-        const count = requireNumber(citation.count, `${what}.citation.count`, fail);
-        if (!Number.isInteger(count) || count <= 0) {
-            throw fail(`${what}.citation.count must be a positive integer`);
-        }
-    }
-    const { deviation } = record;
-    if (deviation !== null) {
-        checkVerdictDeviation(deviation, `${what}.deviation`, fail);
-    }
-    const trustGap = requireNullableEnum(record.trustGap, VERDICT_TRUST_GAPS, `${what}.trustGap`, fail);
-    // superRefine invariant 1 — a deviation only describes a `deviated` cell.
-    if (deviation !== null && state !== "deviated") {
-        throw fail(`${what}.deviation is set on a cell whose state is "${state}", not "deviated"`);
-    }
-    // superRefine invariant 2 — a trust gap only explains an `unverified` cell.
-    if (trustGap !== null && state !== "unverified") {
-        throw fail(`${what}.trustGap is set on a cell whose state is "${state}", not "unverified"`);
-    }
-};
-/** `candidateVerdictSchema` — the whole report card. */
-const checkCandidateVerdict = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    const cells = requireArray(record.cells, `${what}.cells`, fail);
-    cells.forEach((cell, index) => {
-        checkAttributeVerdict(cell, `${what}.cells[${index}]`, fail);
-    });
-    requireEnum(record.grade, VERDICT_GRADES, `${what}.grade`, fail);
-    requireNullableBoundedNumber(record.minConfidence, `${what}.minConfidence`, fail, 0, 1);
+    requireNullableNumber(record.image, `${what}.image`, fail);
 };
 // ── The item ─────────────────────────────────────────────────────────────────
 /**
@@ -230,24 +90,6 @@ export const checkSearchResultItem = (value, what, fail) => {
     requireOptionalBoolean(record.sampleable, `${what}.sampleable`, fail);
     requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
     requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
-    if (record.siblingCount !== undefined) {
-        requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
-    }
-    if (record.variants !== undefined) {
-        const variants = requireArray(record.variants, `${what}.variants`, fail);
-        variants.forEach((variant, index) => {
-            checkCollapsedVariant(variant, `${what}.variants[${index}]`, fail);
-        });
-    }
-    if (record.visualMeanings !== undefined) {
-        const meanings = requireArray(record.visualMeanings, `${what}.visualMeanings`, fail);
-        meanings.forEach((meaning, index) => {
-            checkVisualMeaning(meaning, `${what}.visualMeanings[${index}]`, fail);
-        });
-    }
-    if (record.verdict !== undefined) {
-        checkCandidateVerdict(record.verdict, `${what}.verdict`, fail);
-    }
 };
 /** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
 export const checkSearchResultItems = (items, what, fail) => {

package/spec-facet-types.d.ts

@@ -29,8 +29,9 @@ export type SpecFacet = {
     isArray: boolean;
     /**
      * How this facet is queried. `token` — pick a value from `values` and send it
-     * as `attribute:value`. `numeric` — `values` is EMPTY and `range` carries the
-     * span; send inclusive bounds via `specRangeCriterion` instead.
+     * as a `{field: attributeId, op: "in", values: [...]}` filter leaf.
+     * `numeric` — `values` is EMPTY and `range` carries the span; send inclusive
+     * bounds as `{field: attributeId, op: "gte"/"lte", value}` leaves instead.
      */
     kind: "token" | "numeric" | (string & {});
     brands: number;
@@ -45,9 +46,3 @@ export type SpecFacetsListResponse = {
     count: number;
     facets: SpecFacet[];
 };
-export type SpecFacetsDistributionResponse = {
-    mode: "distribution";
-    attributeId: string;
-    count: number;
-    values: SpecFacetValue[];
-};

package/spec-types.d.ts

@@ -16,16 +16,17 @@
  * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
  *   (colour / visual / lexical) search. Reach for it when relevance still
  *   matters: "something like this seed, but Class A".
- * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
- *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`). Reach for it when the spec is the whole question and
- *   ranking would be noise.
+ * - `client.listVariants({ filters })` — the value-anchored, SPEC-ONLY
+ *   primitive, which takes a `{field: attributeId, op, ...}` filter leaf
+ *   (build one term with the helpers in `./specifications`, or a plain
+ *   object literal for anything else). Reach for it when the spec is the
+ *   whole question and ranking would be noise.
  *
  * Discover the tokens before you spend them: `client.specificationFacets()` for
  * what is facetable at all, `client.attributeValues()` for one attribute's
- * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
- * a phrase into a canonical pair. A hand-guessed token returns an honest empty
- * answer, which is the hardest kind of bug to see.
+ * values, `client.listAttributes({ query })` to turn a phrase into a canonical
+ * attribute id. A hand-guessed token returns an honest empty answer, which is
+ * the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it
@@ -57,17 +58,23 @@ export type CertificationProgrammeAttributeId = typeof CERTIFICATION_PROGRAMME_A
  * A term-equality spec criterion: the attribute must carry this canonical value,
  * e.g. `{ attributeId: "fire_classifications", term: "astm_e84_class_a" }`.
  * Discover valid `attributeId`/`term` pairs via `client.specificationFacets()`
- * and `client.attributeValues()`, or resolve free text with
- * `client.resolveAttribute()`.
+ * and `client.attributeValues()`, or find an attribute from free text with
+ * `client.listAttributes({ query })`.
  */
 export type SpecTermFilter = {
     attributeId: string;
     term: string;
 };
-/** A negative spec criterion; absence of a value remains unproven. */
+/**
+ * A negative spec criterion. `whenUnstated` (absent = `"drop"`) controls what an
+ * UNKNOWN effective value does: `"drop"` requires a known value, so a variant
+ * that never states the attribute does not pass; `"pass"` admits it — a variant
+ * only fails by STATING the excluded term.
+ */
 export type SpecExclusionFilter = {
     attributeId: string;
     excludesTerm: string;
+    whenUnstated?: "drop" | "pass";
 };
 /**
  * A presence spec criterion: the attribute must have ANY accepted value —

package/spec-types.js

@@ -16,16 +16,17 @@
  * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
  *   (colour / visual / lexical) search. Reach for it when relevance still
  *   matters: "something like this seed, but Class A".
- * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
- *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`). Reach for it when the spec is the whole question and
- *   ranking would be noise.
+ * - `client.listVariants({ filters })` — the value-anchored, SPEC-ONLY
+ *   primitive, which takes a `{field: attributeId, op, ...}` filter leaf
+ *   (build one term with the helpers in `./specifications`, or a plain
+ *   object literal for anything else). Reach for it when the spec is the
+ *   whole question and ranking would be noise.
  *
  * Discover the tokens before you spend them: `client.specificationFacets()` for
  * what is facetable at all, `client.attributeValues()` for one attribute's
- * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
- * a phrase into a canonical pair. A hand-guessed token returns an honest empty
- * answer, which is the hardest kind of bug to see.
+ * values, `client.listAttributes({ query })` to turn a phrase into a canonical
+ * attribute id. A hand-guessed token returns an honest empty answer, which is
+ * the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/specifications.d.ts

@@ -1,6 +1,12 @@
 import type { CertificationProgrammeFilter, SpecExclusionFilter, SpecPresenceFilter, SpecTermFilter } from "./spec-types.js";
-/** A hard criterion excluding one known canonical value while retaining only variants with known values. */
-export declare const excludeSpec: (attributeId: string, excludesTerm: string) => SpecExclusionFilter;
+/**
+ * A hard criterion excluding one canonical value.
+ *
+ * By default retains only variants with a KNOWN value (unstated does not
+ * pass). Pass `whenUnstated: "pass"` to admit unstated variants too — only a
+ * variant that STATES the excluded term is dropped.
+ */
+export declare const excludeSpec: (attributeId: string, excludesTerm: string, whenUnstated?: "drop" | "pass") => SpecExclusionFilter;
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.
@@ -24,61 +30,13 @@ export declare const hasSpec: (attributeId: string) => SpecPresenceFilter;
  * virtual attribute so a programme matches wherever it landed at ingest
  * (compliance / sustainability / material-health / VOC buckets).
  *
- * The value may be a display name or alias ("GREENGUARD Gold", "LEED") — the
- * server resolves it to its canonical programme token before matching — or a
- * canonical token directly (e.g. `greenguard_certificate`,
- * `has_greenguard_gold_certification`).
+ * The value is a canonical programme token (e.g. `greenguard_certificate`,
+ * `has_greenguard_gold_certification`). The one search matches tokens on its
+ * index and does not resolve display names, so a name such as
+ * "GREENGUARD Gold" is a 400 naming the term.
  *
  * @example
  * // "find a GREENGUARD-certified alternative"
- * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("GREENGUARD Gold")] });
+ * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("has_greenguard_gold_certification")] });
  */
 export declare const certificationProgramme: (programme: string) => CertificationProgrammeFilter;
-/**
- * An `attribute:value` criterion string for `bySpec`. The `bySpec` route splits
- * on the FIRST `:`, so a value may itself contain colons; the attribute id may
- * not.
- *
- * @example
- * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
- */
-export declare const specCriterion: (attributeId: string, value: string) => string;
-/**
- * An `attribute:min..max` RANGE criterion string for `bySpec`, for a
- * NUMBER-valued spec (`light_reflectance_value`, `nrc_rating`,
- * `slip_resistance_dcof`, …). Pass the result in `bySpec`'s `ranges` option.
- *
- * BOTH BOUNDS ARE INCLUSIVE — `{ min: 60 }` matches a value of exactly 60 —
- * because spec language is written that way ("LRV of 60 or more", "DCOF ≥ 0.42")
- * and because inclusive-both-ends means adjacent ranges overlap at the join
- * rather than leaving a gap that hides products.
- *
- * At least one bound is REQUIRED: a range with neither is a presence check, and
- * this throws rather than sending a criterion the server would have to refuse.
- * Discover which attributes take a range — and the span they actually occupy —
- * from `specificationFacets()`: those are the facets with `kind: "numeric"`.
- *
- * @example
- * // light paints, every brand at once
- * client.bySpec([], { ranges: [specRangeCriterion("light_reflectance_value", { min: 60 })] });
- * @example
- * // a mid-tone band
- * specRangeCriterion("light_reflectance_value", { min: 30, max: 45 }); // "light_reflectance_value:30..45"
- */
-export declare const specRangeCriterion: (attributeId: string, bounds: {
-    min?: number;
-    max?: number;
-}) => string;
-/**
- * An `attribute:value` criterion string for `bySpec` that filters by
- * certification PROGRAMME across all four certification buckets.
- *
- * The value may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
- * server-side to its canonical programme token, or a canonical token directly
- * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
- *
- * @example
- * // every brand's GREENGUARD-Gold materials
- * client.bySpec([certificationProgrammeCriterion("GREENGUARD Gold")]);
- */
-export declare const certificationProgrammeCriterion: (programme: string) => string;

package/specifications.js

@@ -1,22 +1,32 @@
 /**
- * Zero-dependency builders for the specification surface. Turn a plain-language
- * spec intent into a typed criterion the SDK's two spec operations accept:
- *
- * - `search({ filters })` takes {@link SpecFilter} objects — a spec gate layered
- *   onto a ranked (colour / visual / lexical) search. Build them with
- *   {@link specTerm}, {@link hasSpec}, and {@link certificationProgramme}.
- * - `bySpec(specs)` takes `attribute:value` strings — the value-anchored,
- *   spec-only primitive. Build them with {@link specCriterion} and
- *   {@link certificationProgrammeCriterion}.
+ * Zero-dependency builders for the specification surface. Turn a
+ * plain-language spec intent into a typed {@link SpecFilter} `search({
+ * filters })` accepts: hard token sets on the one search's index, run in the
+ * same query. Build them with {@link specTerm}, {@link hasSpec}, and
+ * {@link certificationProgramme}.
  *
  * The point of these helpers: Desk (and any spec-driven caller) never has to
- * remember that a certification programme lives under a VIRTUAL attribute, nor
- * hand-format the `attribute:value` string the `bySpec` route splits on its
- * first `:`.
+ * remember that a certification programme lives under a VIRTUAL attribute.
+ *
+ * A hard specification across every brand (formerly `bySpec`, built with
+ * `specCriterion`/`specRangeCriterion`) is now `list_variants`'s `filters`:
+ * `{field: attributeId, op: "in", values: [...]}` for a term,
+ * `{field: attributeId, op: "gte"/"lte"/etc, value}` for a number — a plain
+ * object literal needs no encoder (MG-2222).
  */
 import { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-/** A hard criterion excluding one known canonical value while retaining only variants with known values. */
-export const excludeSpec = (attributeId, excludesTerm) => ({ attributeId, excludesTerm });
+/**
+ * A hard criterion excluding one canonical value.
+ *
+ * By default retains only variants with a KNOWN value (unstated does not
+ * pass). Pass `whenUnstated: "pass"` to admit unstated variants too — only a
+ * variant that STATES the excluded term is dropped.
+ */
+export const excludeSpec = (attributeId, excludesTerm, whenUnstated) => ({
+    attributeId,
+    excludesTerm,
+    ...(whenUnstated === undefined ? {} : { whenUnstated }),
+});
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.
@@ -43,70 +53,16 @@ export const hasSpec = (attributeId) => ({
  * virtual attribute so a programme matches wherever it landed at ingest
  * (compliance / sustainability / material-health / VOC buckets).
  *
- * The value may be a display name or alias ("GREENGUARD Gold", "LEED") — the
- * server resolves it to its canonical programme token before matching — or a
- * canonical token directly (e.g. `greenguard_certificate`,
- * `has_greenguard_gold_certification`).
+ * The value is a canonical programme token (e.g. `greenguard_certificate`,
+ * `has_greenguard_gold_certification`). The one search matches tokens on its
+ * index and does not resolve display names, so a name such as
+ * "GREENGUARD Gold" is a 400 naming the term.
  *
  * @example
  * // "find a GREENGUARD-certified alternative"
- * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("GREENGUARD Gold")] });
+ * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("has_greenguard_gold_certification")] });
  */
 export const certificationProgramme = (programme) => ({
     attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID,
     term: programme,
 });
-/**
- * An `attribute:value` criterion string for `bySpec`. The `bySpec` route splits
- * on the FIRST `:`, so a value may itself contain colons; the attribute id may
- * not.
- *
- * @example
- * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
- */
-export const specCriterion = (attributeId, value) => `${attributeId}:${value}`;
-/**
- * An `attribute:min..max` RANGE criterion string for `bySpec`, for a
- * NUMBER-valued spec (`light_reflectance_value`, `nrc_rating`,
- * `slip_resistance_dcof`, …). Pass the result in `bySpec`'s `ranges` option.
- *
- * BOTH BOUNDS ARE INCLUSIVE — `{ min: 60 }` matches a value of exactly 60 —
- * because spec language is written that way ("LRV of 60 or more", "DCOF ≥ 0.42")
- * and because inclusive-both-ends means adjacent ranges overlap at the join
- * rather than leaving a gap that hides products.
- *
- * At least one bound is REQUIRED: a range with neither is a presence check, and
- * this throws rather than sending a criterion the server would have to refuse.
- * Discover which attributes take a range — and the span they actually occupy —
- * from `specificationFacets()`: those are the facets with `kind: "numeric"`.
- *
- * @example
- * // light paints, every brand at once
- * client.bySpec([], { ranges: [specRangeCriterion("light_reflectance_value", { min: 60 })] });
- * @example
- * // a mid-tone band
- * specRangeCriterion("light_reflectance_value", { min: 30, max: 45 }); // "light_reflectance_value:30..45"
- */
-export const specRangeCriterion = (attributeId, bounds) => {
-    const { min, max } = bounds;
-    if (min === undefined && max === undefined) {
-        throw new Error(`specRangeCriterion("${attributeId}") needs a min, a max, or both — a range with neither would match every recorded value. Use hasSpec() for a presence check.`);
-    }
-    if (min !== undefined && max !== undefined && min > max) {
-        throw new Error(`specRangeCriterion("${attributeId}") is inverted (min ${min} > max ${max}) and can only ever match nothing.`);
-    }
-    return `${attributeId}:${min ?? ""}..${max ?? ""}`;
-};
-/**
- * An `attribute:value` criterion string for `bySpec` that filters by
- * certification PROGRAMME across all four certification buckets.
- *
- * The value may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
- * server-side to its canonical programme token, or a canonical token directly
- * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
- *
- * @example
- * // every brand's GREENGUARD-Gold materials
- * client.bySpec([certificationProgrammeCriterion("GREENGUARD Gold")]);
- */
-export const certificationProgrammeCriterion = (programme) => specCriterion(CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, programme);

package/suggest-types.d.ts

@@ -12,11 +12,10 @@
  * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
  * of the best matches, never a census of matching entities.
  */
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /** Which kind of entity a suggestion is — and therefore what `refId` means. */
 export type SuggestKind = "product" | "brand" | "category";
 /** How the query met the suggestion's label. Strongest first. */
-export type SuggestMatch = "prefix" | "word" | "contains" | "fuzzy";
+export type SuggestMatch = "prefix" | "word" | "fuzzy";
 /** One ranked typeahead suggestion, carrying the identity it resolves to. */
 export type Suggestion = {
     kind: SuggestKind;
@@ -36,17 +35,15 @@ export type Suggestion = {
      * Opaque, and null when none was picked — not a product without variants.
      */
     variantId: string | null;
-    /** Variants behind this entity IN MATERIALGRAPH — a coverage figure. */
+    /** How many of this entity's variants the search index holds: a coverage figure. */
     variantCount: number;
 };
 /** The suggest response: the query as interpreted, plus the ranked suggestions. */
 export type SuggestResponse = {
-    /** The normalised query the corpus was matched against. */
+    /** The typed words the search index was matched against. */
     query: string;
-    /** Ranked best-match-first. Empty when nothing came close — a miss, not an error. */
+    /** Ranked best-match-first. Empty when nothing came close: a miss, not an error. */
     suggestions: Suggestion[];
-    /** Present only when a narrowing governed corpus was applied. */
-    corpusScope?: CorpusScopeReceipt;
 };
 /** Options for {@link MaterialGraphClient.suggest}. */
 export type SuggestOptions = {
@@ -54,8 +51,6 @@ export type SuggestOptions = {
     limit?: number;
     /** Restrict to these kinds. Omit for all of them. */
     kind?: SuggestKind | SuggestKind[];
-    /** Governed corpus membership; absent means the whole graph. */
-    corpusScope?: CorpusScope;
 };
 /**
  * Shape the query string for a suggest call.
@@ -69,5 +64,4 @@ export declare const suggestQuery: (q: string, options?: SuggestOptions) => {
     q: string;
     limit?: number;
     kind?: string;
-    corpusScope?: CorpusScope;
 };

package/suggest-types.js

@@ -24,5 +24,5 @@ export const suggestQuery = (q, options) => {
     const kind = Array.isArray(options?.kind)
         ? options.kind.join(",")
         : options?.kind;
-    return { corpusScope: options?.corpusScope, kind, limit: options?.limit, q };
+    return { kind, limit: options?.limit, q };
 };