@instruments/materialgraph 0.16.0 → 0.17.0

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/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";

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.16.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/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

@@ -4,7 +4,7 @@
  * emitted by ordinary Search responses.
  */
 import type { OpenEnum } from "./types.js";
-/** The single candidate source a query resolved to. */
+/** 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 {
@@ -23,11 +23,22 @@ export type SearchQueryTransformStage = {
 };
 /** 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<"synonym" | "display-name" | "vector">;
+    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. */
@@ -78,7 +89,7 @@ export interface CompoundColourAbundanceReceipt {
  * text query. Counts describe the bounded candidate pool, not the whole corpus.
  */
 export interface CompoundColourConstraintReceipt {
-    provenance: OpenEnum<"explicit" | "detected-strong">;
+    basis: OpenEnum<"explicit" | "detected-strong">;
     family: string;
     queryHexes: string[];
     considered: number;
@@ -88,3 +99,25 @@ export interface CompoundColourConstraintReceipt {
     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-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/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

@@ -30,8 +30,9 @@ 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";
-import type { CompoundColourConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport } from "./search-response-receipt-types.js";
+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 & {});
@@ -107,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.
  *
@@ -248,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
@@ -410,13 +405,12 @@ 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;
-    /** Boundedness and retrieval-cost receipt on current Search responses. */
     window?: SearchWindowReceipt;
     rerank?: SearchRerankReport;
-    /** Hard compound-colour eligibility and abundance receipt, when applied. */
+    /** 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;
@@ -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. */