@instruments/materialgraph 0.9.1 → 0.11.0

package/types.d.ts

@@ -1,35 +1,7 @@
-/**
- * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
- *
- * These interfaces intentionally have NO runtime dependency on any
- * `@materialgraph/*` package — they are a standalone, publishable mirror of the
- * shapes in `apps/web/public/openapi.yaml` and the captured fixtures under
- * `docs/surface/fixtures/v0.5.0/`. The `contract-parity` test re-checks them
- * against the real Zod schemas so the mirror cannot silently drift.
- * TOLERANT-PARSING CONTRACT: the public surface declares open response enums —
- * "clients must tolerate unknown enum values and unknown fields". Every union
- * that mirrors a server enum is therefore widened with `(string & {})` so a new
- * server value still type-checks, and objects that may grow fields are read
- * structurally (unknown keys pass through untouched — the client never strips).
- *
- * READING CONTRACT — the three things callers get wrong, stated once here and
- * repeated on the types where each one bites:
- *  1. **Ids are opaque.** Round-trip them verbatim; never parse or construct
- *     one. See `./identifiers.ts` for which strings are opaque tokens and which
- *     are canonical vocabulary you discover.
- *  2. **Absent is not false.** An optional field that is missing means UNKNOWN,
- *     not "known to be absent in reality" — most dangerously for booleans.
- *     Values carry `confidence` and `sourceBasis`; report them as claims.
- *  3. **A page is not a corpus.** `results.length` is this page.
- *     {@link CountedTotal} — with the `basis` it states — is the claim about the
- *     match set. Follow the cursor for the rest, and never report a page size as
- *     a total.
- */
-import type { ByColourSwatch } from "./by-colour-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
-import type { SearchFilter, SearchSuggestion } from "./search-refinement-types.js";
+import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
 /** A widened string-literal union: known members autocomplete, unknown values still type-check. */
 export type OpenEnum<T extends string> = T | (string & {});
 /**
@@ -104,6 +76,15 @@ export interface VisualMeaning {
     version?: string;
     appliedAt?: string;
 }
+/** One member of a collapsed result's {@link SearchResultItem.anatomy}. */
+export interface SearchAnatomyMember {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    variantName: string | null;
+    color: string | null;
+    score: number;
+    signals: SearchResultSignals;
+}
 /**
  * One material in a search / match result list.
  *
@@ -121,10 +102,14 @@ export interface SearchResultItem {
     brandSlug: string | null;
     productId: ProductId | null;
     /**
-     * The variant's Material Bank SKU — the same `materialBankId` the material
-     * record carries, so a match card can render straight from a result instead of
-     * paying a per-result lookup. Populated on the MATCH lanes (`match()` and
-     * `matchStream()` frames).
+     * The variant's Material Bank SKU — the ONE EXTERNAL identifier on a result,
+     * in deliberate contrast to the opaque `variantId` above. `variantId` is ours
+     * and means nothing anywhere else; this is the id you are expected to match
+     * against Material Bank's own catalogue, so a result list can be joined to a
+     * cart, an order or an analytics event without a per-result lookup.
+     *
+     * Populated on EVERY lane: `search()` (all four arms), `match()`, and
+     * `matchStream()` frames.
      *
      * ABSENT means no MB identity is known for the variant — never that the SKU
      * cannot be ordered. Presence is the orderability tell; absence is silence.
@@ -150,6 +135,38 @@ export interface SearchResultItem {
     hasImage: boolean;
     palette: PaletteSwatch[];
     colourMeta?: ColourMeta;
+    /**
+     * Present when this material's imagery carries nothing beyond ONE colour, so
+     * a surface should render that colour rather than the photograph — a paint's
+     * photo is a flat fill, and the colour we hold structured beats a JPEG of it.
+     *
+     * The hex is EXTRACTED FROM the product image (a visual likeness), never a
+     * manufacturer-declared colour specification; do not present it as one.
+     * ABSENT means the question was not established (unknown product type,
+     * unextracted or multi-swatch palette) and the image should be rendered — it
+     * NEVER asserts "this is not a coating".
+     */
+    colourChip?: {
+        hex: string;
+    };
+    /**
+     * EXPLAIN-only: the two identities a COLLAPSED result holds, which are not the
+     * same thing and are routinely confused.
+     *
+     * - `representative` — the RANKING identity. Its score is the group's cursor
+     *   key and the item's `signals` describe IT, not the photograph on the card.
+     *   Omitted when the face IS the representative.
+     * - the item's own `variantId` — the DISPLAY identity (the face).
+     *
+     * `siblingsTruncated` says the sibling list was capped: a product can hold
+     * hundreds of colourways, so absence of a sibling is never evidence it does
+     * not exist.
+     */
+    anatomy?: {
+        representative?: SearchAnatomyMember;
+        siblings?: SearchAnatomyMember[];
+        siblingsTruncated?: boolean;
+    };
     /** Fused score — range [0, sum of active weights]; see `maxScore`. */
     score: number;
     /**
@@ -189,6 +206,17 @@ export interface SearchResultItem {
      * dropped by default. Appended after the kept results.
      */
     belowFloor?: boolean;
+    /**
+     * Present (true) only on Match rows the colour probe admitted (match only):
+     * this material is as close in colour as the catalogue gets, and its image
+     * similarity is BELOW the match quality floor by design. It is on the page
+     * because nothing image-retrieved is nearer in colour, not because it cleared
+     * the floor — present it as a colour answer or suppress it knowingly. Absent
+     * (never `false`) on rows that came through image retrieval. Distinct from
+     * {@link SearchResultItem.belowFloor}, which marks rejects returned only under
+     * `includeBelowFloor`.
+     */
+    admittedOnColour?: boolean;
     siblingCount?: number;
     visualMeanings?: VisualMeaning[];
     /**
@@ -223,11 +251,17 @@ export interface SearchCardItem {
  * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
  * a different number from `results.length` (this page).
  *
- * `exact` — the true count (≤ the cap of 1,000, or a facet-MV read). Say "473
- * materials match".
+ * `exact` — the true count. Say "473 materials match".
  * `lowerBound` — a floor (cap hit, ANN-pool bound, or a degraded count). Say
  * "at least 1,000", never "1,000". Never a silent approximation.
  *
+ * The CAP differs by lane, and only `lowerBound` ever tells you one was hit. The
+ * SEARCH feed counts exactly to 1,000 and reports a floor beyond it, because it
+ * counts over attribute and tsquery universes where an unbounded count is a
+ * timeout. The BROWSE feed ({@link BrowseCounts}) is uncapped — a plain count
+ * over the same predicate its page scan ran, so a category of 66,000 reports
+ * 66,000 exactly. Read `basis`; never assume a ceiling.
+ *
  * A response with no `counts` at all states no total: `count: true` is opt-in,
  * and the absence of a total is not a total of zero.
  */
@@ -244,6 +278,54 @@ export interface SearchCounts {
     variants: CountedTotal;
     products?: CountedTotal;
 }
+/**
+ * One value within a facet's counts: the CANONICAL token (send it back verbatim
+ * as a filter term), its display label, and how many variants in the counted
+ * set carry it.
+ */
+export interface SearchFacetValue {
+    value: string;
+    label: string;
+    variants: number;
+}
+/**
+ * One facet's counts. `basis` is the honesty label, and — per the negotiated
+ * MG-1010 contract — its union is CLOSED: exactly `"exact"` or `"lowerBound"`,
+ * never widened, which is why it is not an {@link OpenEnum}. `exact` — each
+ * `variants` figure is a true count under the query's whole predicate
+ * (filter-driven queries only). `lowerBound` — counted over the ranked
+ * candidate pool (`SearchFacets.poolSize`), so each figure is a floor; a
+ * pool-counted value is NEVER `exact`. `truncated` is ALWAYS present: true
+ * when more distinct values existed beyond the reported list.
+ */
+export interface SearchFacetCount {
+    values: SearchFacetValue[];
+    truncated: boolean;
+    basis: "exact" | "lowerBound";
+}
+/**
+ * A requested facet that was not counted, with its reason: `"unsupported"` —
+ * the id is known but facet counting does not cover it; `"timeout"` — the
+ * facet stage's own time budget expired, and the RESULTS are unaffected (the
+ * rail could not count; the page is intact). Render it as "couldn't count",
+ * never as zero.
+ */
+export interface SearchAbsentFacet {
+    facetId: string;
+    reason: OpenEnum<"unsupported" | "timeout">;
+}
+/**
+ * Per-query facet counts (MG-1010) — present ONLY when the request sent
+ * `facetCounts`. `counts` is keyed by requested facet id; every requested
+ * facet not in `absent` has an entry, including empty ones. `poolSize` is
+ * present exactly when the counts are pool-derived.
+ */
+export interface SearchFacets {
+    poolSize?: number;
+    requested: string[];
+    absent: SearchAbsentFacet[];
+    counts: Record<string, SearchFacetCount>;
+}
 /** The single candidate source a query resolved to. */
 export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical">;
 /** Rerank-term report (absent in colour mode — there colour IS the source). */
@@ -275,8 +357,42 @@ export interface SearchResponse {
     cursor?: Cursor;
     rerank?: SearchRerankReport;
     counts?: SearchCounts;
+    /**
+     * The `#rrggbb` colours the colour signal ACTUALLY ran on, after
+     * minor-proportion accents were dropped. Present whenever the request carried
+     * explicit `colours`. Compare against your request: a difference means the
+     * search that ran is not the search that was asked for.
+     */
+    effectiveColours?: string[];
+    /**
+     * Colours removed from the query for carrying a `weight` below the 5% accent
+     * threshold. EMPTY is the normal case. Non-empty and the dropped colours are
+     * absent from colour retrieval and ranking entirely — they did not merely
+     * rank low. To keep a small accent in the query, give it `role: "accent"`.
+     */
+    droppedColours?: string[];
+    /** Per-query facet counts — present ONLY when the request sent `facetCounts`. */
+    facets?: SearchFacets;
     note?: string;
     timings?: Record<string, number>;
+    /** A detected mood term overridden by a stronger colour reading. */
+    supersededMoodId?: string;
+    /**
+     * Present when the query had TWO defensible readings. Says which one ran and
+     * offers the other as a complete executable request.
+     */
+    disambiguation?: SearchDisambiguation;
+    /**
+     * The corpus this page AND its `counts` were drawn from — present ONLY when
+     * the request narrowed it. ABSENT means the whole graph: every material
+     * MaterialGraph knows, orderable or not. Read it alongside `counts`: a short
+     * page under a scope is a small SCOPED corpus, not a truncated one.
+     */
+    corpusScope?: {
+        scope: OpenEnum<"all" | "materialBankOrderable">;
+        /** What the scope admits, in one sentence, for a human reader. */
+        description: string;
+    };
     /** Echo of the resolved query input (raw image bytes/vector are never echoed). */
     query?: Record<string, unknown>;
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
@@ -287,47 +403,6 @@ export interface SearchCardResponse extends Omit<SearchResponse, "view" | "resul
     view: OpenEnum<"card">;
     results: SearchCardItem[];
 }
-/** One item from the pure colour-scalar browse. */
-export interface BrowseResultItem {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    brandSlug: string | null;
-    productId: ProductId | null;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    scalars: {
-        l: number | null;
-        chroma: number | null;
-        vibrancy: number | null;
-    };
-    retired?: boolean;
-    /**
-     * The row's own image palette — the FULL stored palette of the SAME image
-     * `imageUrl` serves, uncapped and in stored order, each swatch with `oklab`
-     * (see {@link ByColourSwatch}), so a card can render, sort or group colours
-     * without a second call. A one-swatch palette means the extractor found one
-     * colour (solid-colour materials are genuinely monochrome), not that the list
-     * was trimmed. ABSENT when no palette is on record for that image: absent
-     * means unknown, NOT that the material has no colours. These swatches come
-     * from product imagery, not from the manufacturer.
-     */
-    palette?: ByColourSwatch[];
-}
-/**
- * A single page of the colour browse — the SDK's one genuinely cursor-paginated
- * surface. `results.length` is this page and the browse states no total at all,
- * so a corpus claim can only come from walking every page
- * (`client.browse.pages(...)` does the loop).
- */
-export interface BrowseResponse {
-    /** THIS PAGE. */
-    results: BrowseResultItem[];
-    /** Opaque keyset for the next page. Absent = the walk is finished. */
-    cursor?: Cursor;
-}
 export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
 export interface ColourFacetTerm {
     id: string;
@@ -400,6 +475,22 @@ export interface CospecPairing {
     imageUrl: string | null;
     brandSlug: string;
     productId: ProductId;
+    /**
+     * How this companion relates to the seed — the distinction raw order evidence
+     * does not carry, and the one that decides what you may claim.
+     *
+     * - `companion` — a DIFFERENT BRAND entirely. This is the cross-brand claim
+     *   the rail exists to make.
+     * - `brand_sibling` — the seed's own brand, a different product.
+     * - `colourway` — the seed's own product, restyled.
+     *
+     * **70.6% of edges are same-brand**, so a consumer that ignores this reports
+     * the seed's own family as cross-brand intelligence (MG-1007).
+     *
+     * Optional because responses captured before the field existed are genuinely
+     * in the wild; absent means "from an older version", never "unrelated".
+     */
+    relation?: "companion" | "brand_sibling" | "colourway";
     category: string | null;
     projectCount: number;
     customerCount: number;
@@ -543,121 +634,7 @@ export type SearchImageInput = {
     type: "base64";
     data: string;
 };
-/**
- * The POST `/search` JSON body — the `searchMaterials` contract. Every field is
- * optional; supply at least one signal (`text`, `colours`, `mood`, `similarTo`,
- * or `image`). Passed through to the server verbatim.
- */
-export interface SearchInput {
-    text?: string;
-    textModes?: Array<OpenEnum<"visual" | "lexical">>;
-    colours?: ColourInput[];
-    colourLogic?: OpenEnum<"all" | "any">;
-    colourTolerance?: OpenEnum<"tight" | "normal" | "loose">;
-    colourAppearance?: {
-        lightness?: {
-            min: number;
-            max: number;
-        };
-        warmth?: {
-            min: number;
-            max: number;
-        };
-    };
-    mood?: string;
-    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
-    /**
-     * Seed a visual search from an existing variant's image (`variantId`) or a
-     * pre-computed image vector (`vector`). Only the `{ variantId }` form carries a
-     * seed variant, so it is the only form `verdicts` can diff a candidate against.
-     */
-    similarTo?: {
-        variantId: VariantId;
-    } | {
-        vector: string;
-    };
-    image?: SearchImageInput;
-    category?: {
-        boost?: string;
-        filter?: string[];
-    };
-    weights?: {
-        image?: number;
-        category?: number;
-        colour?: number;
-        lexical?: number;
-        /** Text rerank multiplier applied when a seeded search also carries `text` (default 0.4). */
-        text?: number;
-    };
-    filters?: SearchFilter[];
-    /**
-     * SOFT spec criteria (rank-never-exclude). Same shape as `filters`; a preference
-     * never removes a result — it adds a `preferred` cell to each hit's `verdict` and
-     * demotes a failed/missing preferred hit WITHIN its page only.
-     */
-    preferences?: SearchFilter[];
-    /** Page size — the size of ONE page, never a bound on the match set. */
-    limit?: number;
-    /** The previous response's `cursor`, passed back verbatim. Never synthesise one. */
-    cursor?: Cursor;
-    explain?: boolean;
-    collapse?: OpenEnum<"none" | "product">;
-    /**
-     * Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools.
-     * Without it the response states NO total — and a page size is not one.
-     */
-    count?: boolean;
-    /** Only return materials with at least one catalog image. Default false (full catalog). */
-    hasImages?: boolean;
-    /**
-     * Opt-in seed-relative verdict cells (MG-629). Only meaningful with
-     * `similarTo: { variantId }`: each hit's `verdict` gains `preferred` cells
-     * diffing its comparable attributes (numeric + a `colour` axis) against the
-     * seed's, with directional deviations. Inert on every other seed form.
-     */
-    verdicts?: boolean;
-    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
-    view?: OpenEnum<"full" | "card">;
-}
-/** Query-string params for the GET `/search` form. */
-export interface SearchGetParams {
-    q?: string;
-    colours?: string;
-    logic?: OpenEnum<"all" | "any">;
-    mood?: string;
-    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
-    tol?: OpenEnum<"tight" | "normal" | "loose">;
-    /** Seed the search from this variant's image. Opaque — pass it through verbatim. */
-    variantId?: VariantId;
-    limit?: number;
-    /** "0" or "1" — include per-signal `signals` on each result. */
-    explain?: OpenEnum<"0" | "1">;
-    /** "true" — opt in to a `counts.variants` feed total. */
-    count?: OpenEnum<"true">;
-    /** "true" — only return materials with at least one catalog image. */
-    hasImages?: OpenEnum<"true">;
-    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
-    view?: OpenEnum<"full" | "card">;
-}
-/** Params for the pure colour `search/browse` surface. */
-export interface BrowseParams {
-    sort: OpenEnum<"light" | "dark" | "vivid" | "muted" | "colourful">;
-    /**
-     * The previous page's `cursor`, verbatim. Opaque keyset state — not an offset.
-     * Changing `sort`, `limit` or `types` invalidates it.
-     */
-    cursor?: Cursor;
-    /** Page size. */
-    limit?: number;
-    /**
-     * Comma-separated taxonomy keys to restrict the browse to, at EITHER tier of
-     * `/api/v1/taxonomy/categories`. A GROUP key (`tile_surfaces`) expands to
-     * every product type under it, a TYPE key (`ceramic_porcelain_tile`) stands
-     * for itself, and a mixed list is their deduplicated union. A key in neither
-     * tier is a 400 listing the valid keys — never an empty page.
-     */
-    types?: string;
-}
+export type { SearchGetParams, SearchInput } from "./search-request-types.js";
 /** Options for a batch material read. */
 export interface MaterialsBatchOptions {
     /** Projection depth. `tile` omits fields rather than reporting them absent. */
@@ -691,6 +668,13 @@ export interface ResolveAttributeOptions {
 /** Options for `search/specifications`. */
 export interface BySpecOptions {
     limit?: number;
+    /**
+     * Numeric range criteria as `attribute:min..max` strings, ANDed with the
+     * `spec` criteria. Build them with `specRangeCriterion` rather than by hand —
+     * both bounds are inclusive and at least one is required, and a hand-built
+     * token with neither is refused by the server rather than matching everything.
+     */
+    ranges?: string[];
 }
 export type * from "./demand-types.js";
 /** One quarter's tally. Sparse across a series — an absent quarter is not a zero. */
@@ -731,31 +715,7 @@ export interface ExtractedPalette {
 export interface ExtractPaletteResponse {
     palette: ExtractedPalette | null;
 }
-export interface SpecFacetValue {
-    value: string;
-    variants: number;
-    brands: number;
-    label?: string;
-}
-export interface SpecFacet {
-    attributeId: string;
-    name: string;
-    isArray: boolean;
-    brands: number;
-    values: SpecFacetValue[];
-    description?: string;
-}
-export interface SpecFacetsListResponse {
-    mode: "facets";
-    count: number;
-    facets: SpecFacet[];
-}
-export interface SpecFacetsDistributionResponse {
-    mode: "distribution";
-    attributeId: string;
-    count: number;
-    values: SpecFacetValue[];
-}
+export type * from "./spec-facet-types.js";
 export interface ApplicableSpecAttribute {
     id: string;
     name: string;

package/validation.d.ts

@@ -34,6 +34,18 @@ export declare function requireOptionalString(value: unknown, what: string, fail
 export declare function requireNullableString(value: unknown, what: string, fail: ValidationFailure): string | null;
 /** A `z.string().min(1).nullable()`. */
 export declare function requireNullableNonEmptyString(value: unknown, what: string, fail: ValidationFailure): string | null;
+/**
+ * A `z.string().trim().min(1).max(max)`.
+ *
+ * The `.trim()` is a TRANSFORM, so the schema's parsed output is the trimmed
+ * string and its length bounds apply AFTER trimming. A mirror that checked the
+ * raw length would disagree with the schema twice over: it would accept a
+ * whitespace-only value the schema rejects, and reject a padded value the schema
+ * accepts. Returns the trimmed string, which is what the schema returns.
+ */
+export declare function requireTrimmedBoundedString(value: unknown, what: string, max: number, fail: ValidationFailure): string;
+/** A `z.string().trim().min(1).max(max).nullable()`. */
+export declare function requireNullableTrimmedBoundedString(value: unknown, what: string, max: number, fail: ValidationFailure): string | null;
 /** A `z.boolean()`. */
 export declare function requireBoolean(value: unknown, what: string, fail: ValidationFailure): boolean;
 /** A `z.boolean().optional()`. */

package/validation.js

@@ -55,6 +55,29 @@ export function requireNullableNonEmptyString(value, what, fail) {
         return null;
     return requireNonEmptyString(value, what, fail);
 }
+/**
+ * A `z.string().trim().min(1).max(max)`.
+ *
+ * The `.trim()` is a TRANSFORM, so the schema's parsed output is the trimmed
+ * string and its length bounds apply AFTER trimming. A mirror that checked the
+ * raw length would disagree with the schema twice over: it would accept a
+ * whitespace-only value the schema rejects, and reject a padded value the schema
+ * accepts. Returns the trimmed string, which is what the schema returns.
+ */
+export function requireTrimmedBoundedString(value, what, max, fail) {
+    const text = requireString(value, what, fail).trim();
+    if (text.length === 0)
+        throw fail(`${what} is empty once trimmed`);
+    if (text.length > max)
+        throw fail(`${what} is longer than ${max} characters (${text.length})`);
+    return text;
+}
+/** A `z.string().trim().min(1).max(max).nullable()`. */
+export function requireNullableTrimmedBoundedString(value, what, max, fail) {
+    if (value === null)
+        return null;
+    return requireTrimmedBoundedString(value, what, max, fail);
+}
 /** A `z.boolean()`. */
 export function requireBoolean(value, what, fail) {
     if (typeof value !== "boolean")