@instruments/materialgraph 0.12.0 → 0.13.0

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,9 +13,9 @@
  * 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";
+import type { CountedTotal, OpenEnum, SearchFacets } from "./types.js";
 /** One item from the pure colour-scalar browse. */
 export interface BrowseResultItem {
     /** Opaque — round-trip verbatim. */
@@ -43,9 +44,20 @@ export interface BrowseResultItem {
      * from product imagery, not from the manufacturer.
      */
     palette?: ByColourSwatch[];
+    /**
+     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
+     * attribute id. ABSENT entirely when `returnAttributes` was not sent; a key
+     * whose value is `null` means this material carries no accepted value for that
+     * attribute. Three states, all different.
+     */
+    attributes?: Record<string, string | string[] | null>;
 }
-/** The browse orders. `name` (A→Z) is the default; `recent` is newest first. */
-export type BrowseSort = OpenEnum<"name" | "recent" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+/**
+ * The browse orders. `name` (A→Z) is the default, `name_desc` the same index
+ * read Z→A, `recent` newest first; the rest are the colour ramps. `/search`
+ * takes all eight too — one word, one order, on both lanes.
+ */
+export type BrowseSort = OpenEnum<"name" | "name_desc" | "recent" | "light" | "dark" | "vivid" | "muted" | "colourful">;
 /**
  * The browse feed's total — how many materials the browse DESCRIBES, which is
  * never `results.length`.
@@ -78,21 +90,43 @@ export interface BrowseResponse {
      * to label its own listing.
      */
     sort: BrowseSort;
+    /**
+     * The attribute ladder this page was ordered by — present ONLY when `orderBy`
+     * was sent, in which case it SUPERSEDED `sort` (still echoed above, and still
+     * describing nothing this page was ordered by).
+     */
+    orderBy?: {
+        attributeId: string;
+        direction: OpenEnum<"asc" | "desc">;
+    };
+    /**
+     * Reader prose about how the request was interpreted — today, only that
+     * `orderBy` superseded a STATED `sort`. Absent means nothing needed saying.
+     */
+    note?: string;
     /**
      * The total, present ONLY when `count: true` was passed. Absent means it was
      * not asked for — never that the set is empty.
      */
     counts?: BrowseCounts;
+    /**
+     * Per-facet value counts, present ONLY when `facetCounts` was asked for.
+     *
+     * Counted over this browse's OWN match set — the same predicate the page and
+     * `counts` ran under — so every value is `basis:"exact"` and `poolSize` is
+     * ABSENT. That differs from {@link SearchResponse}'s facets, which are
+     * normally counted over a ranked candidate pool and are therefore floors:
+     * browse retrieves no pool, so there is nothing for a figure to be a floor
+     * of. A facet the server could not count in time appears in `absent` with
+     * `reason:"timeout"` and the results are unaffected.
+     */
+    facets?: SearchFacets;
     /**
      * The corpus this page was drawn from — present ONLY when the request
      * 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 {
@@ -136,6 +170,30 @@ export interface BrowseParams {
      * brand's fan deck. An unknown brand is a 400 naming it, never an empty page.
      */
     brands?: string;
+    /**
+     * Typed attribute filters, in the SAME grammar `search` takes — a term, a
+     * term SET (OR within the entry), a presence check or a numeric range, each
+     * optionally carrying a `trust` bar. Entries AND together.
+     *
+     * Each entry is sent as ITS OWN `filters=` parameter, JSON-encoded, which is
+     * what the route reads. Pass the objects; the client does the encoding.
+     *
+     * Applied INSIDE the keyset scan and counted under the same predicate, so a
+     * filtered page still fills to `limit`, `cursor` still means another MATCHING
+     * row exists, and `counts.variants` describes the FILTERED set. An attribute
+     * id outside the registry is a 400 carrying ranked candidates, never an empty
+     * page.
+     */
+    filters?: readonly Record<string, unknown>[];
+    /**
+     * Facet ids to count over this browse's match set — `brand`, `category`, or a
+     * spec attribute id. Sent as one comma-separated `facetCounts=` parameter.
+     *
+     * The response's `facets` block comes back `basis:"exact"` with no
+     * `poolSize`, because browse counts the whole predicate rather than a ranked
+     * pool. Omit it for no `facets` block and no counting cost.
+     */
+    facetCounts?: readonly string[];
     /**
      * Which corpus to walk. ABSENT means the whole graph — every material
      * MaterialGraph knows, orderable or not. `materialBankOrderable` restricts to
@@ -143,5 +201,25 @@ export interface BrowseParams {
      * scoped page is still a full page and `cursor` still means another eligible
      * row exists.
      */
-    corpusScope?: OpenEnum<"all" | "materialBankOrderable">;
+    corpusScope?: CorpusScope;
+    /**
+     * Sort along ONE attribute's declared value ladder instead of a `sort` word —
+     * the same field, ladder and refusals `search` takes. Sent as one JSON-encoded
+     * `orderBy=` parameter; pass the object, the client encodes it.
+     *
+     * SUPERSEDES `sort` when both are given, and the response `note` says so.
+     * Ordering is DECLARED, never inferred from a value's spelling: an attribute
+     * with no stated ladder is a 400 carrying `orderable_attributes`. Materials
+     * off the ladder, or carrying no value, sort LAST in both directions.
+     */
+    orderBy?: {
+        attributeId: string;
+        direction?: OpenEnum<"asc" | "desc">;
+    };
+    /**
+     * Attribute ids whose resolved value rides each result under `attributes`, so
+     * a filtered listing can display what it filtered on. Sent as one
+     * comma-separated `returnAttributes=` parameter.
+     */
+    returnAttributes?: readonly string[];
 }

package/by-colour-types.d.ts

@@ -6,7 +6,9 @@
  * 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 { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
+import type { QueryUnderstanding } from "./query-understanding-types.js";
 import type { OklabTriple, OpenEnum, PaletteSwatch } from "./types.js";
 /** Coarse group + fine type of a colour match's primary product type. */
 export interface MatchCategory {
@@ -26,6 +28,12 @@ export interface ByColourMatch {
     variantId: VariantId;
     brand: string;
     product: string;
+    /** Record-route brand identity. */
+    brandSlug?: string | null;
+    /** Opaque MaterialGraph product-family identity. */
+    productId?: string | null;
+    /** Material Bank cart/order join key; absent when not on record. */
+    materialBankId?: string;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -147,6 +155,8 @@ export interface ColourLaneReceipt {
 /** The `search/colours` response. */
 export interface ByColourResponse {
     query: {
+        /** Raw query provenance, when supplied. */
+        q?: string;
         colours: string[];
         categories?: string[];
         /**
@@ -186,14 +196,14 @@ 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;
+    /** Shared standard-search query-understanding receipt. */
+    understanding?: QueryUnderstanding;
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {
+    /** Raw material-domain query provenance for shared query understanding. */
+    q?: string;
     /** A single hex (with or without `#`). */
     hex?: string;
     /** A palette — repeated as one `colour` query entry each. */
@@ -235,5 +245,7 @@ export interface ByColourParams {
      * drop.
      */
     family?: string;
+    /** Narrow retrieval inside the server query; absent means the whole graph. */
+    corpusScope?: CorpusScope;
     limit?: number;
 }

package/client-browse.d.ts

@@ -33,6 +33,17 @@ export type BrowsePageFetcher = (params: BrowseParams, signal?: AbortSignal) =>
  * route and never reached it from here, so the fan deck was unreachable through
  * the published client while the server had supported it all along. When the
  * route gains a param, it gains a line HERE too, or it is not shipped.
+ *
+ * It happened again, and twice: `filters` shipped with MG-1576 and `facetCounts`
+ * with MG-1590, and neither had a line here. Attribute filtering — the thing
+ * MG-1588 spent a materialized view making fast — was therefore unreachable
+ * through the published client for as long as it existed on the route. Both are
+ * enrolled below, along with MG-1593's `orderBy` and `returnAttributes`.
+ *
+ * `filters` is a REPEATED parameter and `facetCounts` a comma list, because that
+ * is what the route reads: the transport appends an array once per element, so
+ * the array shape and the comma-joined string are each doing exactly what the
+ * server expects rather than being two spellings of one idea.
  */
 export declare function browseQuery(params: BrowseParams): {
     sort: BrowseParams["sort"];
@@ -41,7 +52,11 @@ export declare function browseQuery(params: BrowseParams): {
     count: BrowseParams["count"];
     types: BrowseParams["types"];
     brands: BrowseParams["brands"];
+    filters: string[] | undefined;
+    facetCounts: string | undefined;
     corpusScope: BrowseParams["corpusScope"];
+    orderBy: string | undefined;
+    returnAttributes: string | undefined;
 };
 /**
  * Walk every page from `params.cursor` onward.

package/client-browse.js

@@ -8,6 +8,17 @@
  * route and never reached it from here, so the fan deck was unreachable through
  * the published client while the server had supported it all along. When the
  * route gains a param, it gains a line HERE too, or it is not shipped.
+ *
+ * It happened again, and twice: `filters` shipped with MG-1576 and `facetCounts`
+ * with MG-1590, and neither had a line here. Attribute filtering — the thing
+ * MG-1588 spent a materialized view making fast — was therefore unreachable
+ * through the published client for as long as it existed on the route. Both are
+ * enrolled below, along with MG-1593's `orderBy` and `returnAttributes`.
+ *
+ * `filters` is a REPEATED parameter and `facetCounts` a comma list, because that
+ * is what the route reads: the transport appends an array once per element, so
+ * the array shape and the comma-joined string are each doing exactly what the
+ * server expects rather than being two spellings of one idea.
  */
 export function browseQuery(params) {
     return {
@@ -17,7 +28,15 @@ export function browseQuery(params) {
         count: params.count,
         types: params.types,
         brands: params.brands,
+        filters: params.filters?.map((entry) => JSON.stringify(entry)),
+        facetCounts: params.facetCounts?.join(","),
         corpusScope: params.corpusScope,
+        // `orderBy` is JSON-encoded and `returnAttributes` comma-joined because that
+        // is what the route reads — the same two transports `filters` and
+        // `facetCounts` already use. Enrolled HERE at the same time they shipped on
+        // the route, which is the thing the three misses above did not do.
+        orderBy: params.orderBy ? JSON.stringify(params.orderBy) : undefined,
+        returnAttributes: params.returnAttributes?.join(","),
     };
 }
 /**

package/client.d.ts

@@ -19,6 +19,7 @@ import type { MatchStreamEvent } from "./match-stream-types.js";
 import type { MatchInput, MatchResponse } from "./match-types.js";
 import type { MaterialAssetProjection } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { MaterialQueryPlan } from "./material-query-plan-types.js";
 import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
 import { resolvePhrasesRequest as resolvePhrases } from "./resolve-client.js";
 import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
@@ -127,17 +128,13 @@ export declare class MaterialGraphClient {
      * {@link MaterialGraphClient.match} for a photo, {@link MaterialGraphClient.pairings}
      * for what goes WITH something, {@link MaterialGraphClient.suggest} for typeahead.
      *
-     * The full search primitive (POST `/api/v1/search`). Layer a hard
-     * specification gate onto a ranked (colour / visual / lexical / seed) search
-     * via `input.filters` — each entry is a typed {@link SearchFilter} criterion:
-     * a term match (`{ attributeId, term }`), a presence check
-     * (`{ attributeId, hasValue: true }`), or a certification programme
-     * (`{ attributeId: "certification_programme", term }`). This is the seam for
-     * "a GREENGUARD-certified alternative to THIS material" (seed by `similarTo`,
-     * gate by `filters`) or "the same fire class, with an EPD on record". Build the
-     * filters with the `certificationProgramme` / `specTerm` / `hasSpec` helpers.
+     * The full POST search primitive. `input.filters` layers typed hard
+     * specification gates onto ranked colour/visual/lexical/seed search. Build
+     * them with `certificationProgramme`, `specTerm`, or `hasSpec`.
      */
     search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
+    /** Whole materials ask → inspectable meanings and complete safe search requests. */
+    planQuery(query: string, signal?: AbortSignal): Promise<MaterialQueryPlan>;
     /**
      * The same question as {@link MaterialGraphClient.search}; the difference is
      * transport — a cacheable, link-shareable GET for queries that must survive in

package/client.js

@@ -157,19 +157,17 @@ export class MaterialGraphClient {
      * {@link MaterialGraphClient.match} for a photo, {@link MaterialGraphClient.pairings}
      * for what goes WITH something, {@link MaterialGraphClient.suggest} for typeahead.
      *
-     * The full search primitive (POST `/api/v1/search`). Layer a hard
-     * specification gate onto a ranked (colour / visual / lexical / seed) search
-     * via `input.filters` — each entry is a typed {@link SearchFilter} criterion:
-     * a term match (`{ attributeId, term }`), a presence check
-     * (`{ attributeId, hasValue: true }`), or a certification programme
-     * (`{ attributeId: "certification_programme", term }`). This is the seam for
-     * "a GREENGUARD-certified alternative to THIS material" (seed by `similarTo`,
-     * gate by `filters`) or "the same fire class, with an EPD on record". Build the
-     * filters with the `certificationProgramme` / `specTerm` / `hasSpec` helpers.
+     * The full POST search primitive. `input.filters` layers typed hard
+     * specification gates onto ranked colour/visual/lexical/seed search. Build
+     * them with `certificationProgramme`, `specTerm`, or `hasSpec`.
      */
     search(input, signal) {
         return this.#post("search_materials_post", input, signal);
     }
+    /** Whole materials ask → inspectable meanings and complete safe search requests. */
+    planQuery(query, signal) {
+        return this.#post("plan_material_query", { query }, signal);
+    }
     /**
      * The same question as {@link MaterialGraphClient.search}; the difference is
      * transport — a cacheable, link-shareable GET for queries that must survive in
@@ -235,6 +233,7 @@ export class MaterialGraphClient {
      */
     byColour(params, signal) {
         return this.#get("search_by_colour", {
+            q: params.q,
             hex: params.hex,
             colour: params.colour,
             l: params.l,
@@ -243,6 +242,7 @@ export class MaterialGraphClient {
             category: params.category,
             brand: params.brand,
             family: params.family,
+            corpusScope: params.corpusScope,
             limit: params.limit,
         }, signal);
     }

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/demand-types.d.ts

@@ -95,6 +95,26 @@ export interface CoordinateCompanion {
     imageUrl: string | null;
     brandSlug: string;
     productId: ProductId;
+    /**
+     * How this companion relates to the SEED SET — the closest relation that
+     * applies to any seed.
+     *
+     * `companion` is foreign to every seed: a maker the caller did not pick.
+     * `brand_sibling` shares a brand with some seed. `colourway` is a seed's own
+     * product restyled, and completes nothing.
+     *
+     * READ IT BEFORE CLAIMING BREADTH. Measured across the live edges (MG-1007),
+     * 70.6% are same-brand and 24.3% are the seed's own product in another
+     * colourway; on a two-seed rail, 27 of 40 companions came from the seeds' own
+     * two brands. A surface headed "makers you haven't picked" that does not
+     * filter on this is making a claim the evidence does not support — the
+     * measured case showed two distinct makers under a heading promising seven.
+     *
+     * The server has always sent this field; it was absent from this interface
+     * until 2026-08-23, so consumers could not see it and hand-rolled the same
+     * comparison against `brandSlug` themselves.
+     */
+    relation: "companion" | "brand_sibling" | "colourway";
     totalLift: number;
     liftLabel: string;
     seedMatchCount: number;

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", "orderable_attributes", "populated_alternatives", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "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,43 @@
 /** 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",
+    "orderable_attributes",
+    "populated_alternatives",
+    "unknown_attributes",
+    "unknown_brands",
+    "unknown_fields",
+    "unorderable_attribute",
+    "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 +127,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";
@@ -28,6 +28,8 @@ export { ColoursClient } from "./colours-client.js";
 export type { ColoursTransport } from "./colours-client.js";
 export type * from "./colour-aggregate-types.js";
 export type * from "./palette-search-types.js";
+export type * from "./query-understanding-types.js";
+export type * from "./material-query-plan-types.js";
 export type * from "./association-types.js";
 export type * from "./brand-types.js";
 export type * from "./fan-deck-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/material-query-plan-types.d.ts

@@ -0,0 +1,154 @@
+/** Hand-mirrored wire types for `POST /api/v1/search/plan`. */
+import type { QuerySense } from "./query-understanding-types.js";
+import type { ResolvedMeaning } from "./resolve-types.js";
+import type { SearchInput } from "./search-request-types.js";
+import type { OpenEnum } from "./types.js";
+export type MaterialQueryVocabularyKind = OpenEnum<"attribute" | "dictionary_term" | "inline_enum" | "product_type" | "product_type_group">;
+export interface MaterialQuerySpan {
+    start: number;
+    end: number;
+    text: string;
+}
+export interface MaterialQueryOwner {
+    attributeId: string;
+    attributeName: string;
+}
+export interface MaterialQueryLifecycle {
+    status: string;
+    introducedIn?: string;
+    deprecatedIn?: string;
+    supersededBy?: string;
+}
+export type MaterialQueryOntologyContext = {
+    description: string;
+    valueKind: string;
+    valueDictionaryId?: string;
+} | {
+    dictionaryId: string;
+    dictionaryName: string;
+    owningAttributes: Array<{
+        id: string;
+        name: string;
+    }>;
+    lifecycle: MaterialQueryLifecycle;
+} | {
+    attributeId: string;
+    attributeName: string;
+} | {
+    description: string;
+    lifecycle: MaterialQueryLifecycle;
+    parentProductTypeGroupId?: string;
+} | {
+    description: string;
+};
+export interface MaterialQueryApplicability {
+    status: OpenEnum<"all" | "some" | "none" | "unknown">;
+    categoryId?: string;
+    productTypeIds: string[];
+    applicableProductTypeIds: string[];
+}
+export interface MaterialQueryCoverage {
+    variants: number;
+    basis: OpenEnum<"facet_index">;
+    scope: OpenEnum<"corpus">;
+}
+export interface MaterialQueryReachability {
+    status: OpenEnum<"positive" | "zero" | "unknown">;
+    categoryId: string;
+    basis: OpenEnum<"bounded_probe" | "unmeasured">;
+}
+export interface MaterialQueryCandidate {
+    kind: MaterialQueryVocabularyKind;
+    subjectType: MaterialQueryVocabularyKind;
+    subjectId: string;
+    label: string;
+    context: MaterialQueryOntologyContext;
+    score: number;
+    tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
+    evidence: {
+        source: OpenEnum<"registry" | "query_domain_embedding">;
+        span: MaterialQuerySpan;
+    };
+    outcome: OpenEnum<"recognized" | "suggested" | "executable" | "ambiguous" | "refused">;
+    owners: MaterialQueryOwner[];
+    selectedOwner?: MaterialQueryOwner;
+    applicability?: MaterialQueryApplicability;
+    coverage?: MaterialQueryCoverage;
+    reachability?: MaterialQueryReachability;
+    reason?: string;
+}
+export interface MaterialQueryCriterion {
+    source: {
+        subjectType: MaterialQueryVocabularyKind;
+        subjectId: string;
+        span: MaterialQuerySpan;
+    };
+    attribute: {
+        id: string;
+        name: string;
+    };
+    ownerAlternatives: MaterialQueryOwner[];
+    operator: OpenEnum<"term" | "presence" | "numeric_range">;
+    term?: string;
+    min?: number;
+    max?: number;
+    coverage: MaterialQueryCoverage;
+    applicability: MaterialQueryApplicability;
+    reachability?: MaterialQueryReachability;
+}
+export type MaterialQueryStandardMeaning = ResolvedMeaning | QuerySense;
+export type MaterialQueryAmbiguityAlternative = (MaterialQueryOwner & {
+    kind: OpenEnum<"owner">;
+}) | {
+    kind: OpenEnum<"subject">;
+    subjectType: MaterialQueryVocabularyKind;
+    subjectId: string;
+    label: string;
+} | {
+    kind: OpenEnum<"standard_meaning">;
+    meaning: MaterialQueryStandardMeaning;
+};
+export interface MaterialQueryPlan {
+    version: OpenEnum<"1">;
+    verdict: OpenEnum<"executable" | "partial" | "refused">;
+    rawQuery: string;
+    normalisedQuery: string;
+    registry: {
+        corpusSize: number;
+        contentHash: string;
+    };
+    candidates: MaterialQueryCandidate[];
+    category: {
+        key: string;
+        name: string;
+        level: OpenEnum<"group" | "type">;
+        parentKey: string | null;
+        source: {
+            subjectType: MaterialQueryVocabularyKind;
+            subjectId: string;
+            span: MaterialQuerySpan;
+        };
+    } | null;
+    criteria: MaterialQueryCriterion[];
+    colour: {
+        family?: string;
+        undertone?: string;
+    } | null;
+    residualText: string;
+    unspentSpans: Array<MaterialQuerySpan & {
+        reason: OpenEnum<"residual" | "ambiguous" | "refused">;
+    }>;
+    ambiguities: Array<{
+        subjectType: MaterialQueryVocabularyKind;
+        subjectId: string;
+        span: MaterialQuerySpan;
+        reason: string;
+        alternatives: MaterialQueryAmbiguityAlternative[];
+    }>;
+    standardMeanings: Array<{
+        span: MaterialQuerySpan;
+        meanings: MaterialQueryStandardMeaning[];
+    }>;
+    /** Complete ordinary-search requests authored by MaterialGraph. Execute verbatim. */
+    requests: SearchInput[];
+}

package/material-query-plan-types.js

@@ -0,0 +1 @@
+export {};

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["sourceMaterialComments", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["sourceMaterialComments", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -2,6 +2,7 @@ import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
     ["search", "POST", "/api/v1/search", "search_materials_post"],
+    ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
     ["searchGet", "GET", "/api/v1/search", "search_materials_get"],
     ["match", "POST", "/api/v1/search/match", "match_material"],
     ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],

package/package.json

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

package/query-understanding-types.d.ts

@@ -0,0 +1,38 @@
+import type { OpenEnum } from "./types.js";
+export type QuerySenseKind = OpenEnum<"brand" | "product" | "paint_identity" | "category" | "material" | "colour" | "attribute" | "attribute_value" | "certification">;
+export interface QuerySense {
+    id: string;
+    kind: QuerySenseKind;
+    label: string;
+    outcome: OpenEnum<"applied" | "ambiguous" | "recognized" | "refused">;
+    effect: OpenEnum<"restrict" | "prioritize" | "rerank" | "offer" | "none">;
+    confidence: number;
+    evidence: {
+        source: string;
+        matchedText: string;
+        span?: {
+            start: number;
+            end: number;
+        };
+    };
+    entity?: {
+        brandSlug?: string;
+        productId?: string;
+        variantId?: string;
+        materialBankId?: string;
+        productTypeId?: string;
+        paintCode?: string;
+        hex?: string;
+    };
+    reason?: string;
+}
+/** Inspectable interpretation of the raw query by ordinary MaterialGraph search. */
+export interface QueryUnderstanding {
+    version: OpenEnum<"1">;
+    rawQuery: string;
+    normalisedQuery: string;
+    residualText: string;
+    status: OpenEnum<"resolved" | "ambiguous" | "partial" | "unresolved">;
+    mode: OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
+    senses: QuerySense[];
+}

package/query-understanding-types.js

@@ -0,0 +1 @@
+export {};

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";
@@ -30,7 +31,41 @@ export interface SearchInput {
         };
     };
     mood?: string;
-    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    /**
+     * Re-order the final scored results. `relevance` (default) keeps the fused
+     * score; `light` / `dark` / `vivid` / `muted` / `colourful` are the colour
+     * ramps; `name` (A→Z), `name_desc` (Z→A) and `recent` (newest first) are the
+     * catalogue orders — the same three `/search/browse` walks the corpus in, so
+     * one word means one order on both lanes.
+     */
+    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful" | "name" | "name_desc" | "recent">;
+    /**
+     * Sort along ONE attribute's declared value ladder — a SEPARATE axis from
+     * `sort`, which stays the closed relevance / colour / catalogue vocabulary.
+     *
+     * `direction` defaults to `"asc"`. Sent together with `sort`, `orderBy` wins
+     * and the response `note` says so — a UI holding both controls can send both.
+     *
+     * Ordering is DECLARED, never inferred from how a value is spelled: an
+     * attribute with no stated ladder is a 400 carrying the orderable set in
+     * `orderable_attributes`, not a quiet fall back to relevance. A material whose
+     * value is off the ladder, or which carries no value at all, sorts LAST in
+     * both directions — it is still a real material, it just has no rung.
+     */
+    orderBy?: {
+        attributeId: string;
+        direction?: OpenEnum<"asc" | "desc">;
+    };
+    /**
+     * Attribute ids whose resolved value should ride each result under
+     * `attributes` — so a page you filtered by `price_tier` can DISPLAY the tier
+     * without a second call per material. Up to 8.
+     *
+     * Three response states, all different: no `attributes` key means you did not
+     * ask, a key with `null` means nothing is on record for that material, and
+     * anything else is the value. An unknown attribute id is a 400 naming it.
+     */
+    returnAttributes?: string[];
     /**
      * Seed a visual search from an existing variant's image (`variantId`), from a
      * Material Bank SKU (`materialBankId`), or from a pre-computed image vector
@@ -99,6 +134,11 @@ export interface SearchInput {
      * `facets.absent`. Absent = no `facets` in the response, no counting cost.
      */
     facetCounts?: string[];
+    /**
+     * Opaque five-minute receipt from a prior pool-derived faceted search.
+     * Resubmitting it may only narrow that exact finalized pool.
+     */
+    refinementToken?: string;
     /** Only return materials with at least one catalog image. Default false (full catalog). */
     hasImages?: boolean;
     /**
@@ -126,10 +166,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 +189,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
@@ -156,7 +203,7 @@ export interface SearchGetParams {
     colours?: string;
     logic?: OpenEnum<"all" | "any">;
     mood?: string;
-    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful" | "name" | "name_desc" | "recent">;
     tol?: OpenEnum<"tight" | "normal" | "loose">;
     /** Seed the search from this variant's image. Opaque — pass it through verbatim. */
     variantId?: VariantId;
@@ -169,4 +216,12 @@ export interface SearchGetParams {
     hasImages?: OpenEnum<"true">;
     /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
+    /**
+     * One JSON OBJECT, e.g. `{"attributeId":"price_tier","direction":"desc"}` —
+     * the `orderBy` field of the POST body, JSON-encoded because a query string
+     * has no nested values. Same spelling as `filters=` on `/search/browse`.
+     */
+    orderBy?: string;
+    /** Comma-separated attribute ids — the `returnAttributes` list. */
+    returnAttributes?: string;
 }

package/types.d.ts

@@ -1,6 +1,35 @@
 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 { QueryUnderstanding } from "./query-understanding-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 & {});
@@ -226,6 +255,18 @@ export interface SearchResultItem {
      * shared CandidateVerdict mirror; see {@link MaterialVerdict}.
      */
     verdict?: BySpecVerdict;
+    /**
+     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
+     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
+     *
+     * Three states, all different, and reading them as two is the mistake this
+     * shape exists to prevent: no `attributes` key means you did not ask; a key
+     * whose value is `null` means this material carries no accepted value for that
+     * attribute; anything else is what the graph holds. Values resolve with the
+     * normal variant-over-product precedence, and an array is a multi-valued
+     * attribute rather than a list of candidates.
+     */
+    attributes?: Record<string, string | string[] | null>;
 }
 /**
  * The lean `view:"card"` result item — identity + name + thumbnail + score.
@@ -246,6 +287,18 @@ export interface SearchCardItem {
     variantName: string | null;
     imageUrl: string | null;
     score: number;
+    /**
+     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
+     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
+     *
+     * Three states, all different, and reading them as two is the mistake this
+     * shape exists to prevent: no `attributes` key means you did not ask; a key
+     * whose value is `null` means this material carries no accepted value for that
+     * attribute; anything else is what the graph holds. Values resolve with the
+     * normal variant-over-product precedence, and an array is a multi-valued
+     * attribute rather than a list of candidates.
+     */
+    attributes?: Record<string, string | string[] | null>;
 }
 /**
  * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
@@ -326,8 +379,16 @@ export interface SearchFacets {
     absent: SearchAbsentFacet[];
     counts: Record<string, SearchFacetCount>;
 }
+/** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
+export interface SearchRefinementReceipt {
+    token: string;
+    expiresAt: string;
+    poolSize: number;
+    schemaVersion: string;
+    projectionVersion: number;
+}
 /** The single candidate source a query resolved to. */
-export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical">;
+export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
 /** Rerank-term report (absent in colour mode — there colour IS the source). */
 export interface SearchRerankReport {
     colour?: OpenEnum<"ok" | "failed" | "skipped">;
@@ -373,6 +434,8 @@ export interface SearchResponse {
     droppedColours?: string[];
     /** Per-query facet counts — present ONLY when the request sent `facetCounts`. */
     facets?: SearchFacets;
+    /** Receipt that narrows the exact finalized pool behind lower-bound facets. */
+    refinement?: SearchRefinementReceipt;
     note?: string;
     timings?: Record<string, number>;
     /** A detected mood term overridden by a stronger colour reading. */
@@ -382,17 +445,15 @@ export interface SearchResponse {
      * offers the other as a complete executable request.
      */
     disambiguation?: SearchDisambiguation;
+    /** Structured receipt of the standard query-understanding decisions. */
+    understanding?: QueryUnderstanding;
     /**
      * 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;
-    };
+    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. */