@instruments/materialgraph 0.16.0 → 0.18.0

package/material-asset-types.d.ts

@@ -39,10 +39,79 @@ export interface MaterialAssetProjectionDownload {
     fileExtension: string | null;
     filename: string | null;
 }
+export type MaterialDocumentStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "unavailable_source" | "dead_link" | "failed_ingest">;
+export type MaterialDocumentCoverageState = OpenEnum<"available" | "none_declared" | "not_ingested" | "unavailable_source" | "dead_link" | "failed_ingest">;
+export interface MaterialDocumentScope {
+    kind: "product" | "variant";
+    id: string;
+}
+export interface MaterialDocumentSource {
+    /** Opaque, public identifier for one source collection; never a PIM/DAM path. */
+    id: string;
+    authority: string;
+    revision: string;
+}
+export interface MaterialDocumentProjectionItem {
+    id: string;
+    scope: MaterialDocumentScope & {
+        inherited: boolean;
+    };
+    declaredScopes: MaterialDocumentScope[];
+    variantAttribution: string[];
+    /** True only for a Product declaration or this exact requested Variant. */
+    appliesToRequestedVariant: boolean;
+    /** Every exact source-grain declaration collapsed into this URL identity. */
+    declarations: Array<{
+        scope: MaterialDocumentScope;
+        source: MaterialDocumentSource;
+        status: MaterialDocumentStatus;
+        readable: boolean;
+    }>;
+    documentType: string | null;
+    originalName: string;
+    status: MaterialDocumentStatus;
+    /** Null for unavailable, dead, or failed source documents. */
+    url: string | null;
+    contentType: string | null;
+    fileExtension: string | null;
+    source: MaterialDocumentSource;
+}
+export interface MaterialDocumentCoverageSource {
+    scope: MaterialDocumentScope;
+    state: MaterialDocumentCoverageState;
+    exact: boolean;
+    declaredCount: number | null;
+    readableCount: number;
+    source: MaterialDocumentSource;
+}
+export interface MaterialDocumentCoverage {
+    productUnion: MaterialDocumentCoverageSummary;
+    requestedVariant: MaterialDocumentCoverageSummary;
+    sources: MaterialDocumentCoverageSource[];
+}
+export interface MaterialDocumentCoverageSummary {
+    state: MaterialDocumentCoverageState;
+    exact: boolean;
+    declaredCount: number | null;
+    readableCount: number;
+}
+export interface MaterialDocumentPageOptions {
+    cursor?: string;
+    limit?: number;
+}
+export interface MaterialDocumentPage {
+    variantId: VariantId;
+    documents: MaterialDocumentProjectionItem[];
+    coverage: MaterialDocumentCoverage;
+    totalDocuments: number;
+    nextCursor: string | null;
+}
 /** Tallies over what this projection returned — never a claim about the brand's own library. */
 export interface MaterialAssetProjectionSummary {
     imageCount: number;
     downloadCount: number;
+    documentCount: number;
+    readableDocumentCount: number;
     downloadedImageCount: number;
 }
 export interface MaterialAssetProjection {
@@ -50,5 +119,7 @@ export interface MaterialAssetProjection {
     variantId: VariantId;
     images: MaterialAssetProjectionImage[];
     downloads: MaterialAssetProjectionDownload[];
+    documents: MaterialDocumentProjectionItem[];
+    documentCoverage: MaterialDocumentCoverage;
     summary: MaterialAssetProjectionSummary;
 }

package/material-resources-client.d.ts

@@ -0,0 +1,15 @@
+/** Material blocks, safe assets, and technical documents over one shared transport. */
+import { HttpTransport } from "./http-transport.js";
+import type { VariantId } from "./identifiers.js";
+import type { MaterialAssetProjection, MaterialDocumentPage, MaterialDocumentPageOptions } from "./material-asset-types.js";
+import type { MaterialBlockProjection } from "./material-block-types.js";
+/** Read known and explicitly unobserved canonical material fields. */
+export declare function materialBlocks(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialBlockProjection>;
+/** Read only redistribution-safe images and downloads for a material. */
+export declare function materialAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialAssetProjection>;
+/**
+ * Read the owning Product's URL-deduplicated document page. Variant declarations
+ * retain exact attribution; consumers inspect `appliesToRequestedVariant`
+ * before presenting a sibling Variant declaration as applicable.
+ */
+export declare function materialDocuments(transport: HttpTransport, variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal): Promise<MaterialDocumentPage>;

package/material-resources-client.js

@@ -0,0 +1,25 @@
+/** Material blocks, safe assets, and technical documents over one shared transport. */
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/** Read known and explicitly unobserved canonical material fields. */
+export function materialBlocks(transport, variantId, signal) {
+    return transport.requestJson(resolveOperation("list_material_blocks"), { signal, pathParams: { variantId } });
+}
+/** Read only redistribution-safe images and downloads for a material. */
+export function materialAssets(transport, variantId, signal) {
+    return transport.requestJson(resolveOperation("list_material_assets"), { signal, pathParams: { variantId } });
+}
+/**
+ * Read the owning Product's URL-deduplicated document page. Variant declarations
+ * retain exact attribution; consumers inspect `appliesToRequestedVariant`
+ * before presenting a sibling Variant declaration as applicable.
+ */
+export function materialDocuments(transport, variantId, options, signal) {
+    return transport.requestJson(resolveOperation("list_material_documents"), {
+        query: options
+            ? { cursor: options.cursor, limit: options.limit }
+            : undefined,
+        signal,
+        pathParams: { variantId },
+    });
+}

package/material-types.d.ts

@@ -133,6 +133,41 @@ export interface MaterialDetail extends MaterialTile {
     installationImageUrl: string | null;
     displayCategory: string | null;
     categoryPath: string[];
+    /** Durable state of image-colour extraction and its variant projection. */
+    colourEvidence: {
+        status: "no_eligible_asset";
+    } | {
+        status: "extractor_not_run";
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    } | {
+        status: "available";
+        basis: "palette" | "palette_and_dominant_oklab" | "dominant_oklab";
+        extractedAt: string;
+        extractionVersion: string | null;
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    } | {
+        status: "projection_missing";
+        extractedAt: string;
+        extractionVersion: string | null;
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    } | {
+        status: "genuinely_colourless";
+        extractedAt: string;
+        extractionVersion: string | null;
+        origin: {
+            assetId: string;
+            method: "colorscope_primary_image";
+        };
+    };
     /** Extracted from imagery — visual likeness, never a declared colour spec. */
     palette: PaletteSwatch[];
     /** What is ON RECORD. An absent attribute is unrecorded, never known-false. */

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 ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], 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 ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], 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 ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], 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 ["applicability", "GET", "/api/v1/applicability", "get_applicability"], 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,25 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
+    [
+        "catalogPages",
+        "GET",
+        "/api/v1/catalogs/{catalogId}/pages",
+        "list_catalog_pages",
+    ],
+    [
+        "catalogPageRepresentation",
+        "GET",
+        "/api/v1/catalog-pages/{pageId}/representation",
+        "get_catalog_page_representation",
+    ],
+    [
+        "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"],
@@ -13,6 +32,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/catalogues/references",
         "get_catalogue_references_batch",
     ],
+    [
+        "catalogueCollections",
+        "GET",
+        "/api/v1/catalogues/collections",
+        "list_catalogue_channel_collections",
+    ],
     [
         "catalogueDocumentAccess",
         "GET",
@@ -37,6 +62,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/assets",
         "list_material_assets",
     ],
+    [
+        "materialDocuments",
+        "GET",
+        "/api/v1/materials/{variantId}/documents",
+        "list_material_documents",
+    ],
     [
         "exploration.operators",
         "GET",
@@ -96,6 +127,7 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/associated/products",
         "list_associated_products",
     ],
+    ["applicability", "GET", "/api/v1/applicability", "get_applicability"],
     ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"],
     [
         "materialsCached",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.16.0",
+  "version": "0.18.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,184 @@ 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" | "typo-to-canonical">;
+    span: {
+        start: number;
+        end: number;
+    };
+    coverage: number;
+    readings: CanonicalLexicalReading[];
+    receipt: {
+        original: string;
+        canonical: string;
+        rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
+        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;
+    reasonDetail?: OpenEnum<"derived-colour-veto" | "typo-recovery" | "literal-compound-without-type">;
+    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;
+    retrieved?: number;
+    truncated: boolean;
+    emptyMeansScarcity: boolean;
+    outcome?: OpenEnum<"corpus-scarcity" | "retrieval-miss" | "unknown">;
+}
+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 +214,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 mode-primary 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[];