@instruments/materialgraph 0.15.0 → 0.17.0

package/by-colour-types.d.ts

@@ -100,6 +100,15 @@ export interface ColourFamilyGate {
      */
     dropped: number;
 }
+/** Receipt for the hard category gate and its treatment of unknown typing. */
+export interface ColourCategoryGate {
+    /** Category names or keys the caller asked the gate to keep. */
+    requested: string[];
+    /** Only accepted primary product types can establish membership. */
+    requiresAcceptedPrimaryProductType: true;
+    /** Unknown/unclassified variants were ineligible, not proven non-members. */
+    unclassifiedVariantsExcluded: true;
+}
 /**
  * Receipt for the colour-identity collapse that turns a variant-grain ranking
  * into a page of TILES — one per (brand, product, dominant hex), one per stored
@@ -177,6 +186,12 @@ export interface ByColourResponse {
      * what says so in counts rather than adjectives.
      */
     familyGate?: ColourFamilyGate;
+    /**
+     * Present only when `category` was asked for. It states that variants without
+     * an accepted primary product type were excluded by the hard gate; absence
+     * means no category gate ran.
+     */
+    categoryGate?: ColourCategoryGate;
     /**
      * What the colour-identity collapse cost this page. Matches are TILES: a page
      * can be SHORTER than `limit` when the pool collapsed harder than the

package/catalogue-client.d.ts

@@ -1,4 +1,4 @@
-import type { CatalogueDocumentAccessResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
+import type { CatalogDocumentList, CatalogProductReferenceList, CatalogueDocumentAccessResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 /** Catalogue publication operations inherited by the public SDK client. */
@@ -13,6 +13,10 @@ export declare class CatalogueClient {
     catalogueReferences(input: {
         variantIds: VariantId[];
     }, signal?: AbortSignal): Promise<CatalogueReferenceBatchResponse>;
+    /** List immutable catalog documents retained from verified source material. */
+    catalogs(signal?: AbortSignal): Promise<CatalogDocumentList>;
+    /** Read every verified product/page reference for one retained catalog. */
+    catalogReferences(catalogId: string, signal?: AbortSignal): Promise<CatalogProductReferenceList>;
     /** Resolve browser-safe access to one immutable catalogue document. */
     catalogueDocumentAccess(documentId: string, signal?: AbortSignal): Promise<CatalogueDocumentAccessResult>;
 }

package/catalogue-client.js

@@ -13,6 +13,14 @@ export class CatalogueClient {
     catalogueReferences(input, signal) {
         return this.#transport.requestJson(resolveOperation("get_catalogue_references_batch"), { body: input, signal });
     }
+    /** List immutable catalog documents retained from verified source material. */
+    catalogs(signal) {
+        return this.#transport.requestJson(resolveOperation("list_catalog_documents"), { signal });
+    }
+    /** Read every verified product/page reference for one retained catalog. */
+    catalogReferences(catalogId, signal) {
+        return this.#transport.requestJson(resolveOperation("list_catalog_product_references"), { pathParams: { catalogId }, signal });
+    }
     /** Resolve browser-safe access to one immutable catalogue document. */
     catalogueDocumentAccess(documentId, signal) {
         return this.#transport.requestJson(resolveOperation("get_catalogue_document_access"), { pathParams: { documentId }, signal });

package/catalogue-types.d.ts

@@ -1,5 +1,13 @@
 /** A verified product location in a specific immutable brand publication. */
 export interface CatalogueReference {
+    anchor: {
+        coordinateSpace: "normalized_0_1000";
+        height: number;
+        kind: "printed_code";
+        width: number;
+        x: number;
+        y: number;
+    };
     variantId: string;
     brand: {
         id: string;
@@ -63,3 +71,32 @@ export type CatalogueDocumentAccessResult = {
     documentId: string;
     status: "unresolved_document" | "unavailable" | "forbidden" | "upstream_failure";
 };
+export interface CatalogDocument {
+    brand: {
+        id: string;
+        name: string;
+    };
+    document: {
+        contentScope: "full_document" | "cover_only";
+        id: string;
+        mediaType: "application/pdf";
+        pageCount: number;
+    };
+    id: string;
+    kind: "document";
+    productStatus: "partial" | "not_processed";
+    title: string;
+}
+export interface CatalogDocumentList {
+    catalogs: CatalogDocument[];
+    source: "verified-source-material-registry";
+}
+export interface CatalogProductReferenceList {
+    catalog: CatalogDocument;
+    coverage: {
+        pagesWithReferences: number;
+        references: number;
+    };
+    references: CatalogueReference[];
+    source: "verified-source-material-registry";
+}

package/codes-client.d.ts

@@ -45,7 +45,7 @@ export declare class CodesClient {
      * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
      * seeded jurisdictions and their coverage tier, the occupancy groups the
      * registry keys on, finish locations, dimensions, classification scales with
-     * classes ordered best-first, and which `ms_room` term correlates to which
+     * classes ordered best-first, and which `room` term correlates to which
      * regulatory axes.
      *
      * Start here — every value the other two calls accept is listed in this one

package/codes-client.js

@@ -14,7 +14,7 @@ export class CodesClient {
      * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
      * seeded jurisdictions and their coverage tier, the occupancy groups the
      * registry keys on, finish locations, dimensions, classification scales with
-     * classes ordered best-first, and which `ms_room` term correlates to which
+     * classes ordered best-first, and which `room` term correlates to which
      * regulatory axes.
      *
      * Start here — every value the other two calls accept is listed in this one

package/codes-types.d.ts

@@ -62,7 +62,7 @@ export interface CodeContextRequest {
      */
     spaceType?: string;
     /**
-     * An `ms_room` term id (e.g. `"hotel_room"`) to correlate the regulatory axes
+     * A `room` term id (e.g. `"hotel_room"`) to correlate the regulatory axes
      * from. Explicit `occupancyGroup` / `spaceType` always win. A room that
      * correlates to neither axis is a 400 naming the axis — never a guess.
      */
@@ -224,7 +224,7 @@ export interface ResolvedCodeContext {
     spaceType: string;
     sprinklered: boolean;
     basis: OpenEnum<"explicit" | "derived_from_room">;
-    /** The `ms_room` term the axes were correlated from, or null. */
+    /** The `room` term the axes were correlated from, or null. */
     roomType: string | null;
 }
 /**
@@ -271,7 +271,7 @@ export interface CodeContextResponse {
         /** Ordered BEST FIRST: index 0 outranks index 1. */
         classes: string[];
     }[];
-    /** `ms_room` → regulatory axes. `null` where the registry refuses to correlate. */
+    /** `room` → regulatory axes. `null` where the registry refuses to correlate. */
     roomCorrelations: {
         roomType: string;
         label: string;

package/composition-types.d.ts

@@ -86,6 +86,23 @@ export interface CompliancePresetRule {
 export interface CompliancePreset {
     rules: CompliancePresetRule[];
 }
+/** Exact project regulatory axes used to attach bounded code citations. */
+export interface ProgrammeRegulatoryAxes {
+    jurisdictionId: string;
+    occupancyGroup: string;
+    sprinklered: boolean;
+}
+/** One caller-declared Programme space. `spaceType` remains open descriptive text. */
+export interface ComposeDeclaredSpace {
+    name: string;
+    spaceType?: string;
+    /** Exact active canonical `room` id used for bounded code evaluation. */
+    regulatoryRoomType?: string;
+}
+/** The spaces this run is explicitly for; omit to retain brief inference. */
+export interface ComposeDeclaredScope {
+    spaces: ComposeDeclaredSpace[];
+}
 /**
  * The `inputJson` for a `compose-material-schemes` run. `batchId` is required;
  * everything else has a server default. `anchors` (max 24) carry externally
@@ -101,6 +118,10 @@ export interface ComposeMaterialSchemesInput {
     exclusions?: SchemeExclusions;
     anchors?: ComposeAnchorInput[];
     compliancePreset?: CompliancePreset;
+    /** Omit to leave Programme code coverage explicitly unevaluated. */
+    regulatoryAxes?: ProgrammeRegulatoryAxes;
+    /** Explicit caller-held space facts; regulatoryRoomType is never inferred. */
+    scope?: ComposeDeclaredScope;
 }
 /**
  * The state of one criterion verdict cell (MG-627: the shared MaterialGraph

package/exploration-types.d.ts

@@ -7,6 +7,8 @@ export interface GraphOperatorAvailability {
     label: string;
     available: boolean;
     basis: string;
+    discoverable: boolean;
+    discoveryBasis: string;
     count?: number;
 }
 export interface GraphOperatorEvidence {

package/index.d.ts

@@ -17,6 +17,7 @@ export type * from "./run-events.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 "./search-collapse-types.js";
 export type * from "./match-types.js";
 export type * from "./browse-types.js";
 export type * from "./catalogue-types.js";
@@ -38,6 +39,7 @@ export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./search-refinement-types.js";
+export type * from "./search-window-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
 export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";

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 ["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 ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], 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 ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], 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 ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], 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

@@ -1,6 +1,13 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
+    [
+        "catalogReferences",
+        "GET",
+        "/api/v1/catalogs/{catalogId}/references",
+        "list_catalog_product_references",
+    ],
     ["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"],

package/package.json

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

package/query-understanding-types.d.ts

@@ -1,3 +1,4 @@
+import type { SearchFilter } from "./search-refinement-types.js";
 import type { OpenEnum } from "./types.js";
 export type QuerySenseKind = OpenEnum<"brand" | "product" | "paint_identity" | "category" | "material" | "colour" | "attribute" | "attribute_value" | "certification">;
 export interface QuerySense {
@@ -26,6 +27,181 @@ export interface QuerySense {
     };
     reason?: string;
 }
+export interface CanonicalLexicalAuthorityReceipt {
+    authority: OpenEnum<"taxonomy" | "colorscope">;
+    version: string;
+    revision: string;
+    digest?: string;
+}
+export interface CanonicalLexicalReading {
+    authority: OpenEnum<"taxonomy" | "colorscope">;
+    identity: string;
+    outcome: OpenEnum<"equivalent" | "ambiguous" | "declined">;
+    executionStatus: OpenEnum<"applied" | "suppressed" | "executable" | "recognized-but-unexecutable" | "declined">;
+    role: OpenEnum<"primary" | "secondary"> | null;
+    kind?: OpenEnum<"domain" | "core-colour" | "paint">;
+    label?: string;
+    libraryId?: string;
+    code?: string;
+    aliasCount?: number;
+    matchForm?: OpenEnum<"name" | "code" | "authoritative-term">;
+    collisionCount?: number;
+    familyId?: string;
+    hex?: string;
+    level?: OpenEnum<"family" | "tone-band" | "branch" | "concept">;
+    lifecycle?: {
+        introducedAt: string;
+        reviewedAt?: string;
+        status: string;
+    };
+    provenance?: {
+        basis: string;
+        snapshot?: string;
+        source: string;
+    };
+}
+export interface CanonicalLexicalMatch {
+    original: string;
+    canonical: string;
+    rule: OpenEnum<"exact" | "plural-to-singular">;
+    span: {
+        start: number;
+        end: number;
+    };
+    coverage: number;
+    readings: CanonicalLexicalReading[];
+    receipt: {
+        original: string;
+        canonical: string;
+        rule: OpenEnum<"exact" | "plural-to-singular">;
+        authorities: CanonicalLexicalAuthorityReceipt[];
+    };
+}
+export interface CanonicalLexicalReceipt {
+    original: string;
+    outcome: OpenEnum<"resolved" | "ambiguous" | "declined" | "partial" | "unresolved">;
+    matches: CanonicalLexicalMatch[];
+    unresolved: CanonicalLexicalMatch[];
+}
+export interface QueryResidualReceipt {
+    kind: OpenEnum<"compound" | "descriptive" | "ambiguous" | "empty">;
+    tokens: string[];
+    resolvedTokens: string[];
+    unresolvedTokens: string[];
+    resolvedRatio: number;
+    comparisonFrame: boolean;
+}
+/** Deterministic criteria compiled from the query before retrieval. */
+export interface QueryCriteriaReceipt {
+    applied: Array<{
+        criterion: SearchFilter;
+        lane: OpenEnum<"filter" | "preference">;
+        lexicalSignal?: {
+            attributeId: string;
+            canonical: string;
+            identity: string;
+            original: string;
+            relation: OpenEnum<"equivalent" | "broader-storage-term">;
+            span: {
+                start: number;
+                end: number;
+            };
+            storedTerm: string;
+        };
+        source: OpenEnum<"compiled" | "taxonomy-adapter">;
+        span: string;
+    }>;
+    conflicts: Array<{
+        attributeId: string;
+        caller: SearchFilter;
+        compiled: SearchFilter;
+        reason: string;
+    }>;
+    exclusions: Array<{
+        criterion: SearchFilter;
+        execution: OpenEnum<"blocked-positive-only-contract">;
+        lane: OpenEnum<"hard" | "soft">;
+        missingValuePolicy: OpenEnum<"retain-unknown">;
+        span: string;
+    }>;
+    preferences: SearchFilter[];
+    residualText: string | null;
+    unresolved: Array<{
+        code: OpenEnum<"missing-searchable-attribute" | "missing-dimension-pair-contract" | "missing-explicit-comparator" | "negative-criterion-contract-blocked" | "registry-contract-drift" | "unsupported-numeric-format" | "unsupported-unit" | "unsupported-strict-comparator">;
+        reason: string;
+        span: string;
+    }>;
+}
+/** How the query named or inferred a product type before retrieval. */
+export interface QueryProductTypeReceipt {
+    kind: OpenEnum<"leaf" | "group" | "vector" | "ambiguous" | "none">;
+    gate: OpenEnum<"hard" | "constrain" | "none">;
+    pass: OpenEnum<"taxonomy" | "synonym" | "display-name" | "group" | "head-noun" | "vector" | "none">;
+    reason: string;
+    displayName: string | null;
+    productTypeId: string | null;
+    groupKey: string | null;
+    productTypeIds: string[];
+    similarity: number | null;
+    margin: number | null;
+    residualText: string;
+    vectorPassRan: boolean;
+    registryVersion: string;
+    durationMs: number;
+    candidates: Array<{
+        productTypeId: string;
+        displayName: string;
+        similarity: number;
+    }>;
+}
+/** The selected retrieval arm; null when the path is browse or criteria-only. */
+export interface QueryArmReceipt {
+    arm: OpenEnum<"dense" | "lexical" | "colour"> | null;
+    reason: string;
+    outcome: OpenEnum<"dense" | "lexical" | "colour" | "browse" | "criteria-only" | "ambiguous">;
+    decidedBy: OpenEnum<"deterministic" | "model">;
+    productTypeGate: OpenEnum<"hard" | "constrain" | "none">;
+    productTypeIds: string[];
+    residual: QueryResidualReceipt;
+    registryVersion: string;
+}
+export interface QueryAmbiguityReceipt {
+    outcome: OpenEnum<"applied" | "abstained" | "refused" | "timeout">;
+    modelId: string | null;
+    providerRan: boolean;
+    durationMs: number;
+    timeoutMs: number;
+    validation: OpenEnum<"valid" | "invalid" | "not-run">;
+    refusalCode: string | null;
+    confidence: number | null;
+    routing: OpenEnum<"compound" | "descriptive"> | null;
+    productTypeIds: string[];
+    changedArm: boolean;
+}
+export interface QueryCategoryScopeReceipt {
+    source: OpenEnum<"caller" | "anchor">;
+    mechanism: OpenEnum<"sql-predicate" | "allowlist" | "prune">;
+    variantCount: number | null;
+    ceiling: number;
+    specScanBounded?: boolean;
+    [key: string]: unknown;
+}
+export interface QuerySpecAllowlistReceipt {
+    limit: number;
+    returned: number;
+    truncated: boolean;
+    emptyMeansScarcity: boolean;
+}
+export interface QueryUnsatisfiableNarrowing {
+    narrowing: OpenEnum<"product-type">;
+    gate: OpenEnum<"hard">;
+    productTypeId: string;
+    displayName: string;
+    productTypeIds: string[];
+    pass: string;
+    evidence: OpenEnum<"zero-accepted-variants">;
+    relaxedTo: OpenEnum<"none">;
+}
 /** Inspectable interpretation of the raw query by ordinary MaterialGraph search. */
 export interface QueryUnderstanding {
     version: OpenEnum<"1">;
@@ -35,4 +211,12 @@ export interface QueryUnderstanding {
     status: OpenEnum<"resolved" | "ambiguous" | "partial" | "unresolved">;
     mode: OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
     senses: QuerySense[];
+    canonicalLexical?: CanonicalLexicalReceipt;
+    criteria?: QueryCriteriaReceipt;
+    productType?: QueryProductTypeReceipt;
+    arm?: QueryArmReceipt;
+    ambiguity?: QueryAmbiguityReceipt;
+    categoryScope?: QueryCategoryScopeReceipt;
+    specAllowlist?: QuerySpecAllowlistReceipt;
+    unsatisfiableNarrowing?: QueryUnsatisfiableNarrowing;
 }

package/resolve-types.d.ts

@@ -25,7 +25,7 @@
  * - `category` — a product-category taxonomy node key.
  * - `attribute` — a registry attribute id: the LEFT half of an `attribute:value`
  *   pair, for `mg.bySpec()` or `search({ filters })`.
- * - `attribute_value` — a value-dictionary term, namespaced (`ms_sheen.matte`):
+ * - `attribute_value` — a value-dictionary term, namespaced (`sheen.matte`):
  *   the RIGHT half.
  * - `jurisdiction` — a code jurisdiction id (`us-tx`), for `mg.codeAdvisory()`.
  * - `occupancy_group` — an IBC occupancy group (`R-1`), the other axis the code

package/search-collapse-types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The product-collapsed view of a search result — what `collapse: "product"`
+ * hands back beside each card. Kept out of `types.ts` for the same reason
+ * `palette-search-types.ts` and `by-colour-types.ts` are: that file is at its
+ * source-size ceiling, and this is a self-contained corner of the contract.
+ *
+ * READ THIS FIRST, because the default is the opposite of what "duplicates"
+ * intuition suggests. MaterialGraph search is VARIANT-based: without `collapse`,
+ * every matching variant comes back as its own result, and that is correct —
+ * twelve SKUs of one tile are twelve separately orderable products, not twelve
+ * copies of one. Product grouping is an optional VIEW over that, not a fix for
+ * it.
+ *
+ * When you do ask for the view, the product arrives CARRYING its variants
+ * (`SearchResultItem.variants`) rather than a bare count, so a colourway strip
+ * renders from the same response as the card. That array is CAPPED at 12, while
+ * `SearchResultItem.siblingCount` stays the complete tally — so a truncated list
+ * is decidable from the response alone: `(siblingCount ?? 0) + 1 >
+ * variants.length`. A full-length array is never on its own evidence that the
+ * product holds no further variants.
+ */
+import type { VariantId } from "./identifiers.js";
+import type { SearchResultSignals } from "./types.js";
+/**
+ * One variant of a product-collapsed result.
+ *
+ * A slim shape, deliberately: the fields a colourway strip renders, projected
+ * from the row the engine already held in memory, so the array costs no extra
+ * query. It is NOT a nested search result — no `attributes`, `palette`,
+ * `verdict` or `productType` — because those come from per-result reads the
+ * engine issues for the card only. Fetch the variant by `variantId` when you
+ * need its full record.
+ */
+export interface CollapsedVariant {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    /** The variant's own label; for paint, the colourway name. Null when unnamed. */
+    variantName: string | null;
+    /** The variant's coarse colour family. */
+    color: string | null;
+    /**
+     * `#rrggbb` dominant colour EXTRACTED FROM the variant's image — a visual
+     * likeness, never a manufacturer-declared colour specification. ABSENT means
+     * no palette is on record: unknown, never "this variant has no colour".
+     */
+    hex?: string;
+    imageUrl: string | null;
+    /**
+     * The variant's Material Bank SKU, on the same contract as the result item's:
+     * ABSENT means no MB identity is on record, never that it cannot be ordered.
+     */
+    materialBankId?: string;
+    /** This variant's own fused score — the value the array is ordered by. */
+    score: number;
+}
+/**
+ * One member of a collapsed result's `SearchResultItem.anatomy` — the
+ * EXPLAIN-only readout of the same grouping {@link CollapsedVariant} publishes.
+ * Where a collapsed variant is what a surface renders, this is what an operator
+ * inspects: it carries the per-arm `signals` that made the variant a candidate.
+ */
+export interface SearchAnatomyMember {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    variantName: string | null;
+    color: string | null;
+    score: number;
+    signals: SearchResultSignals;
+}

package/search-collapse-types.js

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

package/search-refinement-types.d.ts

@@ -76,6 +76,13 @@ export type SearchFilter = {
     attributeId: string;
     hasValue: true;
     trust?: SearchFilterTrust;
+}
+/** Date-sensitive presence is currently executable only for EPD expiration. */
+ | {
+    attributeId: "epd_expiration_date";
+    hasValue: true;
+    asOf: string;
+    trust?: SearchFilterTrust;
 } | {
     attributeId: string;
     /** Inclusive lower bound. Omit for a ceiling-only range. */
@@ -90,29 +97,31 @@ export interface SearchSuggestion {
     /** Complete replacement request, not a partial patch. */
     request: SearchInput;
 }
-/** One of the two readings a {@link SearchDisambiguation} offers. */
+/** One reading a {@link SearchDisambiguation} offers. */
 export interface SearchInterpretation {
     id: string;
     label: string;
     kind: string;
-    /** True for the reading that ACTUALLY RAN and produced this page. */
+    /** True for the reading that ran; all false means the engine chose none. */
     isDefault: boolean;
     /** The colour this reading resolved to, when the ambiguity was a colour one. */
     hex?: string;
     /** Complete replacement request, not a partial patch. */
     request: SearchInput;
 }
+/** The governed ambiguity classes emitted by MaterialGraph search. */
+export type SearchDisambiguationKind = "compliance-phrase" | "colour-material" | "paint-colour" | "paint-identity";
 /**
- * The server saying a query had TWO defensible readings, and which one it took.
+ * The server saying a query had multiple defensible readings.
  *
- * `interpretations` always holds exactly two, the one that ran flagged
- * `isDefault`. Each carries a complete executable request, so offering the
- * other reading is a re-issue rather than a patch. Ignoring this block does not
+ * The reading that ran is flagged `isDefault`; every reading is false when the
+ * engine deliberately chose none. Each carries a complete executable request,
+ * so choosing a reading is a re-issue rather than a patch. Ignoring this block does not
  * make the ambiguity go away — it makes it invisible to the person who asked.
  */
 export interface SearchDisambiguation {
-    /** Which ambiguity this is: "compliance-phrase", "colour-material", "paint-colour". */
-    kind: string;
+    /** Compliance, colour-material, paint-colour, or paint-identity ambiguity. */
+    kind: SearchDisambiguationKind;
     /** The ambiguous term or phrase. */
     term: string;
     interpretations: SearchInterpretation[];

package/search-response-receipt-types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @module sdk/search-response-receipt-types
+ * @description Inspectable routing, rerank, and compound-constraint receipts
+ * emitted by ordinary Search responses.
+ */
+import type { OpenEnum } from "./types.js";
+/** The primary ranking source a query resolved to and reports as its mode. */
+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">;
+    colourWeight?: number;
+    colourLabel?: string;
+}
+/** One stage in the explain-only ledger of transformations that actually ran. */
+export type SearchQueryTransformStage = {
+    stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
+    applied: true;
+} | {
+    stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
+    applied: false;
+    reason: string;
+};
+/** Explain-only category gate selected by query understanding. */
+export interface SearchCategoryAnchor {
+    /**
+     * A leaf type id; the group key when `source` is `"group"`; or the canonical
+     * category noun when `source` is `"head-noun"`. Gate on `productTypeIds`.
+     */
+    productTypeId: string;
+    /**
+     * The leaf type ids a `"group"` or `"head-noun"` anchor expanded to; absent
+     * for leaf sources.
+     */
+    productTypeIds?: readonly string[];
+    displayName: string;
+    similarity: number;
+    margin: number | null;
+    source: OpenEnum<"taxonomy" | "synonym" | "display-name" | "group" | "head-noun" | "vector">;
+    /** Hard category eligibility is applied inside lexical candidate selection. */
+    candidateSource?: OpenEnum<"lexical">;
+    applied: boolean;
+}
+/** Explain-only brand gate selected by query understanding. */
+export interface SearchBrandAnchor {
+    brandSlug: string;
+    brandName: string;
+    confidence: number;
+    margin: number | null;
+    tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
+    variantCount: number;
+    applied: boolean;
+}
+/** A real brand candidate the engine deliberately declined to gate on. */
+export interface SearchBrandSkip {
+    reason: OpenEnum<"ambiguous" | "weak-tier" | "too-broad">;
+    candidates?: string[];
+}
+/**
+ * EXPLAIN-only receipt of the query shape that executed. This is distinct from
+ * the separate Search Plan compiler operation: it reports execution and never
+ * causes it.
+ */
+export interface SearchExecutionPlan {
+    grain: OpenEnum<"variant" | "product">;
+    weights: {
+        image: number;
+        category: number;
+        colour: number;
+        lexical: number;
+        text: number;
+    };
+    queryTransform: SearchQueryTransformStage[];
+    categoryAnchor?: SearchCategoryAnchor;
+    brandAnchor?: SearchBrandAnchor;
+    brandSkipped?: SearchBrandSkip;
+}
+/** Why a compound colour constraint returned a full or short page. */
+export interface CompoundColourAbundanceReceipt {
+    grain: OpenEnum<"variant" | "product">;
+    requested: number;
+    eligible: number;
+    candidateWindow: number;
+    sourceExhausted: boolean;
+    state: OpenEnum<"filled" | "corpus_scarcity" | "evidence_unavailable" | "retrieval_window_exhausted">;
+}
+/**
+ * Eligibility proof for an explicit or taxonomy-backed colour inside a compound
+ * text query. Counts describe the bounded candidate pool, not the whole corpus.
+ */
+export interface CompoundColourConstraintReceipt {
+    basis: OpenEnum<"explicit" | "detected-strong">;
+    family: string;
+    queryHexes: string[];
+    considered: number;
+    kept: number;
+    dropped: number;
+    unknown: number;
+    adjacent: number;
+    abundance?: CompoundColourAbundanceReceipt;
+}
+/** Why a hard form constraint returned a full or short page. */
+export interface CompoundFormAbundanceReceipt {
+    grain: OpenEnum<"variant" | "product">;
+    requested: number;
+    eligible: number;
+    candidateWindow: number;
+    sourceExhausted: boolean;
+    state: OpenEnum<"filled" | "corpus_scarcity" | "evidence_unavailable" | "retrieval_window_exhausted">;
+}
+/**
+ * Hard form eligibility for a compound text query. Product and variant names
+ * may retrieve a candidate but never prove that it satisfies the form.
+ */
+export interface CompoundFormConstraintReceipt {
+    instruction: OpenEnum<"subway" | "plank" | "square" | "hexagon" | "penny-round">;
+    considered: number;
+    kept: number;
+    dropped: number;
+    contradicted: number;
+    unknown: number;
+    abundance: CompoundFormAbundanceReceipt;
+}

package/search-response-receipt-types.js

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

package/search-result-validation.js

@@ -49,6 +49,23 @@ function checkPaletteSwatch(value, what, fail) {
     if (record.name !== undefined)
         requireNullableString(record.name, `${what}.name`, fail);
 }
+/**
+ * `variants[]` — one entry of a product-collapsed result's ranked variant list
+ * (`collapsedVariantSchema`). A SLIM projection, not a nested result item: the
+ * checks here are the whole shape.
+ */
+function checkCollapsedVariant(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    requireString(record.variantId, `${what}.variantId`, fail);
+    requireNullableString(record.variantName, `${what}.variantName`, fail);
+    requireNullableString(record.color, `${what}.color`, fail);
+    // `.optional()`, NOT nullable: the emit path omits the key when no palette is
+    // on record rather than sending null.
+    requireOptionalString(record.hex, `${what}.hex`, fail);
+    requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
+    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
+    requireNumber(record.score, `${what}.score`, fail);
+}
 /** `colourMeta` — three independently optional strings. */
 function checkColourMeta(value, what, fail) {
     const record = requireRecord(value, what, fail);
@@ -192,6 +209,10 @@ export function checkSearchResultItem(value, what, fail) {
     if (record.siblingCount !== undefined) {
         requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
     }
+    if (record.variants !== undefined) {
+        const variants = requireArray(record.variants, `${what}.variants`, fail);
+        variants.forEach((variant, index) => checkCollapsedVariant(variant, `${what}.variants[${index}]`, fail));
+    }
     if (record.visualMeanings !== undefined) {
         const meanings = requireArray(record.visualMeanings, `${what}.visualMeanings`, fail);
         meanings.forEach((meaning, index) => checkVisualMeaning(meaning, `${what}.visualMeanings[${index}]`, fail));

package/search-window-types.d.ts

@@ -0,0 +1,17 @@
+/** The bounded candidate window that produced a search page. */
+export interface SearchWindowReceipt {
+    /** Versioned budget profile; interpret the remaining fields under this version. */
+    profile: "interactive-r1" | (string & {});
+    /** Candidate depth used by the final retrieval. */
+    candidateTier: number;
+    /** Every candidate retrieval, including required fallbacks and optional recovery. */
+    retrievalRounds: number;
+    /** Candidate-retrieval wall time only, in milliseconds. */
+    retrievalMs: number;
+    /** True when the serving source proved there were no more candidates. */
+    exhaustive: boolean;
+    /** True when product-grain scarcity caused one jump to the deep ceiling. */
+    deepened: boolean;
+    /** True when a still-short page exhausted its bounded recovery allowance. */
+    budgetExhausted: boolean;
+}

package/search-window-types.js

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

package/spec-types.d.ts

@@ -70,10 +70,16 @@ export interface SpecTermFilter {
  * {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID} (a programme is matched by name,
  * never by bare presence).
  */
-export interface SpecPresenceFilter {
+export type SpecPresenceFilter = {
     attributeId: string;
     hasValue: true;
 }
+/** Date-sensitive presence is currently executable only for EPD expiration. */
+ | {
+    attributeId: "epd_expiration_date";
+    hasValue: true;
+    asOf: string;
+};
 /**
  * A certification-programme criterion — a {@link SpecTermFilter} pinned to the
  * virtual {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. Structurally assignable

package/types.d.ts

@@ -5,7 +5,7 @@ import type { BySpecVerdict } from "./by-spec-types.js";
  * 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
+ * `src/__tests__/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
@@ -30,8 +30,11 @@ 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 { CollapsedVariant, SearchAnatomyMember } from "./search-collapse-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
-/** A widened string-literal union: known members autocomplete, unknown values still type-check. */
+import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport } from "./search-response-receipt-types.js";
+import type { SearchWindowReceipt } from "./search-window-types.js";
+export type * from "./search-response-receipt-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
 /**
  * A JSON value, recursively — exactly what survives a `jsonb` round-trip
@@ -105,15 +108,6 @@ export interface VisualMeaning {
     version?: string;
     appliedAt?: string;
 }
-/** One member of a collapsed result's {@link SearchResultItem.anatomy}. */
-export interface SearchAnatomyMember {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    variantName: string | null;
-    color: string | null;
-    score: number;
-    signals: SearchResultSignals;
-}
 /**
  * One material in a search / match result list.
  *
@@ -246,7 +240,10 @@ export interface SearchResultItem {
      * `includeBelowFloor`.
      */
     admittedOnColour?: boolean;
+    /** Variants HIDDEN behind this card by `collapse: "product"` — the COMPLETE tally, even when {@link variants} is capped. */
     siblingCount?: number;
+    /** The product's matching variants, MOST RELEVANT FIRST — present exactly under `collapse: "product"`, capped, and led by the group's RANKING representative, which is NOT always this item. {@link CollapsedVariant} states the full contract. */
+    variants?: CollapsedVariant[];
     visualMeanings?: VisualMeaning[];
     /**
      * The shared report card for this hit against the request's `filters` (required
@@ -389,14 +386,6 @@ export interface SearchRefinementReceipt {
     schemaVersion: string;
     projectionVersion: number;
 }
-/** The single candidate source a query resolved to. */
-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">;
-    colourWeight?: number;
-    colourLabel?: string;
-}
 /**
  * The search response envelope. `view` discriminates the `results` union:
  * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
@@ -416,9 +405,14 @@ export interface SearchResponse {
     suggestions: SearchSuggestion[];
     mode: SearchMode;
     maxScore: number;
-    /** Opaque keyset for the next page. Absent = end of the walk, not an error. */
     cursor?: Cursor;
+    window?: SearchWindowReceipt;
     rerank?: SearchRerankReport;
+    /** Hard compound eligibility and abundance receipts, when applied. */
+    colourConstraint?: CompoundColourConstraintReceipt;
+    formConstraint?: CompoundFormConstraintReceipt;
+    /** Explain-only receipt of the query shape and transform ledger that ran. */
+    plan?: SearchExecutionPlan;
     counts?: SearchCounts;
     /**
      * The `#rrggbb` colours the colour signal ACTUALLY ran on, after
@@ -443,8 +437,9 @@ export interface SearchResponse {
     /** A detected mood term overridden by a stronger colour reading. */
     supersededMoodId?: string;
     /**
-     * Present when the query had TWO defensible readings. Says which one ran and
-     * offers the other as a complete executable request.
+     * Present when the query had multiple defensible readings. Says which one
+     * ran, or leaves every reading non-default when the engine chose none. Every
+     * reading carries a complete executable replacement request.
      */
     disambiguation?: SearchDisambiguation;
     /** Structured receipt of the standard query-understanding decisions. */