@instruments/materialgraph 0.12.1 → 0.13.0

package/browse-types.d.ts

@@ -15,7 +15,7 @@ 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. */
@@ -44,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`.
@@ -79,11 +90,37 @@ 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
@@ -133,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
@@ -141,4 +202,24 @@ export interface BrowseParams {
      * row exists.
      */
     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,8 +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 { CorpusScopeReceipt } from "./corpus-scope-types.js";
+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 {
@@ -27,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;
@@ -148,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[];
         /**
@@ -188,9 +197,13 @@ export interface ByColourResponse {
      * retrieval rather than over the page it produced.
      */
     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. */
@@ -232,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/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

@@ -89,7 +89,7 @@ interface TransportErrorInput extends MaterialGraphRequestMetadata {
  * 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"];
+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

@@ -28,9 +28,12 @@ export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
     "empty_brands",
     "limit_bytes",
     "missing_env",
+    "orderable_attributes",
     "populated_alternatives",
     "unknown_attributes",
     "unknown_brands",
+    "unknown_fields",
+    "unorderable_attribute",
     "valid_group_keys",
     "valid_type_keys",
 ];

package/index.d.ts

@@ -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/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.1",
+  "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-request-types.d.ts

@@ -31,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
@@ -100,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;
     /**
@@ -164,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;
@@ -177,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

@@ -29,6 +29,7 @@ import type { BySpecVerdict } from "./by-spec-types.js";
 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 & {});
@@ -254,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.
@@ -274,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
@@ -354,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">;
@@ -401,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. */
@@ -410,6 +445,8 @@ 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