@instruments/materialgraph 0.12.0 → 0.12.1

package/browse-types.d.ts

@@ -1,3 +1,4 @@
+import type { ByColourSwatch } from "./by-colour-types.js";
 /**
  * Wire types for the browse lane — GET `/api/v1/search/browse`.
  *
@@ -12,7 +13,7 @@
  * Nothing about the client's surface changed: `index.ts` re-exports these
  * exactly as before.
  */
-import type { ByColourSwatch } from "./by-colour-types.js";
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { CountedTotal, OpenEnum } from "./types.js";
 /** One item from the pure colour-scalar browse. */
@@ -88,11 +89,7 @@ export interface BrowseResponse {
      * narrowed it. ABSENT means the whole graph: every material MaterialGraph
      * knows, orderable or not.
      */
-    corpusScope?: {
-        scope: OpenEnum<"all" | "materialBankOrderable">;
-        /** What the scope admits, in one sentence, for a human reader. */
-        description: string;
-    };
+    corpusScope?: CorpusScopeReceipt;
 }
 /** Params for the pure colour `search/browse` surface. */
 export interface BrowseParams {
@@ -143,5 +140,5 @@ export interface BrowseParams {
      * scoped page is still a full page and `cursor` still means another eligible
      * row exists.
      */
-    corpusScope?: OpenEnum<"all" | "materialBankOrderable">;
+    corpusScope?: CorpusScope;
 }

package/by-colour-types.d.ts

@@ -6,6 +6,7 @@
  * budget. Same tolerant-parsing contract as the rest of the mirror — response
  * enums are widened so a new server value still type-checks.
  */
+import type { CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { OklabTriple, OpenEnum, PaletteSwatch } from "./types.js";
 /** Coarse group + fine type of a colour match's primary product type. */
@@ -186,11 +187,7 @@ export interface ByColourResponse {
      * counts describe the SCOPED corpus too, because the scope was applied inside
      * retrieval rather than over the page it produced.
      */
-    corpusScope?: {
-        scope: OpenEnum<"all" | "materialBankOrderable">;
-        /** What the scope admits, in one sentence, for a human reader. */
-        description: string;
-    };
+    corpusScope?: CorpusScopeReceipt;
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {

package/corpus-scope-types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The corpus scope vocabulary, declared ONCE for the whole client.
+ *
+ * ── Why this file exists ──
+ * Until MG-1168 the union was spelled inline at six places across the SDK, and
+ * five of them had gone stale: `designShopOrderable` shipped in MG-1144 and
+ * reached only the search request type, so a TypeScript consumer could send the
+ * scope to `/search` and not to `/browse` — against a server that had accepted
+ * it on both since the day it landed. The narrowed RECEIPT types were worse
+ * than the request ones, because a caller could not even name the scope it got
+ * back.
+ *
+ * That is the third hop of the reachability checklist failing quietly: server
+ * correct, published client unable to reach the surface. One alias means the
+ * next member is one edit here rather than six edits nobody is reminded to
+ * make. `corpus-scope-parity.test.ts` in `apps/web/config` fails if this file
+ * falls behind `CORPUS_SCOPES`.
+ *
+ * ── Why `OpenEnum` ──
+ * The server may add a scope before a consumer upgrades. `OpenEnum` keeps the
+ * known members as autocomplete while still accepting a string the server knows
+ * and this build does not, so a new scope is not a compile error in a client
+ * that simply has not been republished yet.
+ */
+import { type OpenEnum } from "./types.js";
+/**
+ * Every corpus a caller may ask for.
+ *
+ * `"all"` (and absence) is the WHOLE GRAPH — every material MaterialGraph
+ * knows, orderable or not. Absence is never a narrower default.
+ *
+ * Three members gate on CHANNEL membership, which is what "can someone buy
+ * this" means: `"materialBankNaOrderable"` (Material Bank North America),
+ * `"materialBankEuOrderable"` (Material Bank Europe) and
+ * `"designShopOrderable"` (DesignShop, with the products DesignShop hides from
+ * browse excluded).
+ *
+ * `"materialBankOrderable"` is NOT one of them, despite the name. It selects
+ * materials carrying a Material Bank identity — PROVENANCE, not a storefront —
+ * and admits about 98% of the graph. Use it to exclude the crawl-sourced brands
+ * that were never in the Material Bank feed; if you mean orderable, use one of
+ * the three above.
+ */
+export type CorpusScope = OpenEnum<"all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaOrderable" | "materialBankOrderable">;
+/**
+ * The corpus a response AND its counts were drawn from. Present only when a
+ * narrowing scope applied — absence means the whole graph. Read it alongside
+ * the counts: a short page under a scope is a small SCOPED corpus, never a
+ * truncated one.
+ */
+export interface CorpusScopeReceipt {
+    scope: CorpusScope;
+    /** What the scope admits, in one sentence, for a human reader. */
+    description: string;
+}

package/corpus-scope-types.js

@@ -0,0 +1,25 @@
+/**
+ * The corpus scope vocabulary, declared ONCE for the whole client.
+ *
+ * ── Why this file exists ──
+ * Until MG-1168 the union was spelled inline at six places across the SDK, and
+ * five of them had gone stale: `designShopOrderable` shipped in MG-1144 and
+ * reached only the search request type, so a TypeScript consumer could send the
+ * scope to `/search` and not to `/browse` — against a server that had accepted
+ * it on both since the day it landed. The narrowed RECEIPT types were worse
+ * than the request ones, because a caller could not even name the scope it got
+ * back.
+ *
+ * That is the third hop of the reachability checklist failing quietly: server
+ * correct, published client unable to reach the surface. One alias means the
+ * next member is one edit here rather than six edits nobody is reminded to
+ * make. `corpus-scope-parity.test.ts` in `apps/web/config` fails if this file
+ * falls behind `CORPUS_SCOPES`.
+ *
+ * ── Why `OpenEnum` ──
+ * The server may add a scope before a consumer upgrades. `OpenEnum` keeps the
+ * known members as autocomplete while still accepting a string the server knows
+ * and this build does not, so a new scope is not a compile error in a client
+ * that simply has not been republished yet.
+ */
+import {} from "./types.js";

package/errors.d.ts

@@ -17,6 +17,12 @@ export interface ProblemDetail {
     suggestions?: string[];
     doc_uri?: string;
     issues?: SanitizedIssue[];
+    /**
+     * MaterialGraph's documented RFC 7807 extension members, sanitized by the
+     * same rules as every other nested value here. Absent when the response did
+     * not carry them. See {@link MATERIALGRAPH_PROBLEM_EXTENSIONS}.
+     */
+    readonly [extension: string]: unknown;
 }
 /** Normalized residual `{ error }` body. Unknown response fields are discarded. */
 export interface SimpleErrorBody {
@@ -61,6 +67,29 @@ interface TransportErrorInput extends MaterialGraphRequestMetadata {
     cause: unknown;
     callerSignal?: AbortSignal;
 }
+/**
+ * MaterialGraph's documented problem EXTENSION members — the only non-standard
+ * keys this client retains.
+ *
+ * ── Why an allow-list and not "keep everything" ──
+ * Dropping unknown members is a deliberate decision here, pinned by a test that
+ * sends `unknown_top_level: "must-not-be-retained"` and asserts it is gone. A
+ * client should not echo arbitrary server-supplied keys into an object the
+ * caller trusts. That decision stands.
+ *
+ * ── Why not "drop everything", which is what it used to do ──
+ * MaterialGraph sends these members precisely so a caller can BRANCH on a
+ * refusal rather than parse its prose, and dropping them silently forced the
+ * opposite. A consumer reported it on 2026-08-21: they received
+ * `populated_alternatives` on the wire, found it absent from the thrown error,
+ * and were left matching a regex against `detail` — the exact coupling the
+ * field was added to remove. All ten members below were unreachable.
+ *
+ * So: the server's own contract is retained, and nothing else is. Adding a
+ * member to a problem response means adding it here too, and
+ * `problem-extension-parity.test.ts` fails when the two disagree.
+ */
+export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "populated_alternatives", "unknown_attributes", "unknown_brands", "valid_group_keys", "valid_type_keys"];
 /** The one error class thrown by all SDK transport and HTTP failures. */
 export declare class MaterialGraphError extends Error {
     readonly kind: MaterialGraphErrorKind;

package/errors.js

@@ -1,5 +1,40 @@
 /** Error and rate-limit contracts for the retry-free MaterialGraph SDK. */
 const RETRIABLE_STATUS = new Set([502, 503, 504]);
+/**
+ * MaterialGraph's documented problem EXTENSION members — the only non-standard
+ * keys this client retains.
+ *
+ * ── Why an allow-list and not "keep everything" ──
+ * Dropping unknown members is a deliberate decision here, pinned by a test that
+ * sends `unknown_top_level: "must-not-be-retained"` and asserts it is gone. A
+ * client should not echo arbitrary server-supplied keys into an object the
+ * caller trusts. That decision stands.
+ *
+ * ── Why not "drop everything", which is what it used to do ──
+ * MaterialGraph sends these members precisely so a caller can BRANCH on a
+ * refusal rather than parse its prose, and dropping them silently forced the
+ * opposite. A consumer reported it on 2026-08-21: they received
+ * `populated_alternatives` on the wire, found it absent from the thrown error,
+ * and were left matching a regex against `detail` — the exact coupling the
+ * field was added to remove. All ten members below were unreachable.
+ *
+ * So: the server's own contract is retained, and nothing else is. Adding a
+ * member to a problem response means adding it here too, and
+ * `problem-extension-parity.test.ts` fails when the two disagree.
+ */
+export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
+    "content_length",
+    "did_you_mean",
+    "empty_brands",
+    "limit_bytes",
+    "missing_env",
+    "populated_alternatives",
+    "unknown_attributes",
+    "unknown_brands",
+    "valid_group_keys",
+    "valid_type_keys",
+];
+const PROBLEM_EXTENSION_KEYS = new Set(MATERIALGRAPH_PROBLEM_EXTENSIONS);
 const MAX_UNEXPECTED_TEXT = 768;
 const MAX_EXTENSION_DEPTH = 8;
 const MAX_EXTENSION_ITEMS = 100;
@@ -89,7 +124,12 @@ function normalizeProblem(body, secrets) {
     }
     const suggestions = sanitizeSuggestions(body.suggestions, secrets);
     const issues = sanitizeIssues(body.issues, secrets);
+    // Extensions FIRST so a malformed one can never shadow a standard member
+    // below. `sanitizeRecord` is the existing redaction and depth/item caps —
+    // this is that machinery finally being reached, not a second sanitizer.
+    const extensions = sanitizeRecord(Object.fromEntries(Object.entries(body).filter(([key]) => PROBLEM_EXTENSION_KEYS.has(key))), secrets, 0);
     return {
+        ...extensions,
         type: safeString(body.type, secrets),
         title: safeString(body.title, secrets),
         status: body.status,

package/exploration-types.d.ts

@@ -1,3 +1,4 @@
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
 export type GraphOperator = "colourways" | "same_category" | "still_listed" | "looks_like" | "same_colour" | "pairs_with" | "often_specified_with" | "substitutes_for" | "more_durable" | "outdoor_suitable" | "lower_cost" | "more_sustainable";
 export interface GraphOperatorAvailability {
@@ -14,7 +15,7 @@ export interface GraphOperatorEvidence {
 }
 export interface CandidateReadInput {
     operator: "looks_like";
-    corpusScope?: "all" | "materialBankOrderable";
+    corpusScope?: CorpusScope;
     limit?: number;
     excludeVariantIds?: VariantId[];
 }
@@ -62,10 +63,7 @@ export interface CandidateSeedEvidence {
 }
 export interface CandidateReadReceipt {
     operator: "looks_like";
-    corpusScope: {
-        scope: "all" | "materialBankOrderable";
-        description: string;
-    } | null;
+    corpusScope: CorpusScopeReceipt | null;
     requestedLimit: number;
     returnedCount: number;
     exclusions: {

package/index.d.ts

@@ -14,7 +14,7 @@ export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export type * from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
 export type * from "./run-events.js";
-export { MaterialGraphError } from "./errors.js";
+export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
 export type * from "./match-types.js";

package/index.js

@@ -4,7 +4,7 @@ export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export { VARY_AXES } from "./composition-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
-export { MaterialGraphError } from "./errors.js";
+export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export { CodesClient } from "./codes-client.js";
 export { ColoursClient } from "./colours-client.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "type": "module",
   "exports": {
     ".": {

package/search-refinement-types.d.ts

@@ -28,14 +28,21 @@ export interface SearchFilterTrust {
     minConfidence?: number;
     /**
      * Demand an EXACT source basis (closed enum — an unknown basis is rejected).
-     * Roughly strongest to weakest as evidence:
-     *  - `tested` — a measured result. The strongest claim available.
+     * Strongest to weakest as evidence:
      *  - `declared` — the manufacturer stated it. Attributable, not independent.
      *  - `catalog_feed` — it arrived in a catalog feed. Trusted at ingest, unreviewed.
      *  - `derived` — MaterialGraph inferred it. Ours, not the manufacturer's — never
      *    present a `derived` value as something the brand claims.
+     *
+     * There is NO `tested` basis. This docblock advertised one as "the strongest
+     * claim available" through 0.12.0, and the union listed `declared` twice in
+     * its place — so a caller reading the documentation would write a value the
+     * server rejects with a 400, and the type would not stop them because the
+     * fourth arm was a duplicate rather than the value described.
+     * `packages/schema/src/source-basis.test.ts` asserts `tested` parses false;
+     * its absence is deliberate, not an omission.
      */
-    sourceBasis?: "catalog_feed" | "declared" | "derived" | "declared";
+    sourceBasis?: "catalog_feed" | "declared" | "derived";
     /** Fold the attribute's own registry confidence requirement in, server-side. */
     meetsRequirement?: true;
 }
@@ -49,6 +56,22 @@ export type SearchFilter = {
     attributeId: string;
     term: string;
     trust?: SearchFilterTrust;
+}
+/**
+ * TERM SET — the attribute must equal any ONE of these. OR within the entry;
+ * AND still holds between entries, so a filter rail composes the same way
+ * whatever it is filtering on.
+ *
+ * The server has accepted this since the term-set arm shipped, and a consumer
+ * has been sending it successfully on the wire — but it was missing from this
+ * union through 0.12.0, so multi-value filtering type-checked nowhere while
+ * working everywhere. Brand multi-select is the common case:
+ * `{attributeId: "brand", terms: ["kvadrat", "interface"]}`.
+ */
+ | {
+    attributeId: string;
+    terms: string[];
+    trust?: SearchFilterTrust;
 } | {
     attributeId: string;
     hasValue: true;

package/search-request-types.d.ts

@@ -5,6 +5,7 @@
  * repo's source-size gate; every name here is re-exported from `types.ts`, so
  * no import path changes.
  */
+import type { CorpusScope } from "./corpus-scope-types.js";
 import type { Cursor, VariantId } from "./identifiers.js";
 import type { SearchFilter } from "./search-refinement-types.js";
 import type { ColourInput, OpenEnum, SearchImageInput } from "./types.js";
@@ -126,10 +127,17 @@ export interface SearchInput {
      * **ABSENT means the WHOLE GRAPH** — every material MaterialGraph knows,
      * orderable or not. Absence is never a narrower default, so a caller that
      * says nothing gets materials it may not be able to buy.
-     * `"materialBankOrderable"` restricts retrieval to materials carrying a
-     * Material Bank identity. `"designShopOrderable"` restricts it to what a
-     * consumer can buy on DesignShop today — about 16,200 materials, with the
-     * products DesignShop hides from browse excluded.
+     * Three scopes gate on CHANNEL membership, which is what "can someone buy
+     * this" means: `"materialBankNaOrderable"` (Material Bank North America,
+     * ~277,000 materials), `"materialBankEuOrderable"` (Material Bank Europe,
+     * ~65,000) and `"designShopOrderable"` (DesignShop, ~34,000, with the
+     * products DesignShop hides from browse excluded).
+     *
+     * `"materialBankOrderable"` is NOT one of them, despite the name. It selects
+     * materials carrying a Material Bank identity — a PROVENANCE signal, not a
+     * storefront — and admits about 98% of the graph. Use it to exclude the
+     * crawl-sourced brands that were never in the Material Bank feed; if you mean
+     * orderable, use one of the three above.
      *
      * A scope answers what is BUYABLE. It never answers what is SUITABLE: scope
      * on channel, then refine on sector. A trade-only material can be right for a
@@ -142,7 +150,7 @@ export interface SearchInput {
      * shortens the page exactly when the query drifts toward the corpus beyond
      * the Material Bank feed, which is unpredictable from outside.
      */
-    corpusScope?: OpenEnum<"all" | "materialBankOrderable" | "designShopOrderable">;
+    corpusScope?: CorpusScope;
     /**
      * OPS/AUDIT escape hatch — do NOT use for normal search. Default behaviour
      * (absent or false) excludes sampling-artifact products: multi-swatch sample

package/types.d.ts

@@ -1,4 +1,32 @@
 import type { BySpecVerdict } from "./by-spec-types.js";
+/**
+ * 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 { CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
@@ -388,11 +416,7 @@ export interface SearchResponse {
      * 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;
-    };
+    corpusScope?: CorpusScopeReceipt;
     /** 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. */