@instruments/materialgraph 0.17.0 → 0.18.0

package/association-types.d.ts

@@ -90,3 +90,64 @@ export interface AssociatedOptions {
      */
     cursor?: Cursor;
 }
+export type ApplicabilitySubject = {
+    kind: "product";
+    id: string;
+} | {
+    kind: "variant";
+    id: VariantId;
+};
+export type ApplicabilityCoverageState = "available" | "partial" | "none_declared" | "not_ingested" | "source_not_applicable" | "unavailable";
+export interface ApplicabilityCoverage {
+    state: ApplicabilityCoverageState;
+    countKind: "exact" | "partial";
+    declaredCount: number | null;
+    sourceAuthority: string;
+    sourceLocator: string;
+    sourceRevision: string;
+}
+export interface ApplicabilityFact {
+    id: string;
+    subject: ApplicabilitySubject;
+    finish: {
+        kind: "variant";
+        id: VariantId;
+    };
+    relation: "applicable_finish";
+    evidenceScope: "manufacturer_declared";
+    declaringBrandId: string;
+    source: {
+        authority: string;
+        locator: string;
+        revision: string;
+    };
+    lifecycle: "active";
+}
+export interface ApplicabilitySourceEntry {
+    scope: {
+        sourceAuthority: string;
+        sourceLocator: string;
+    };
+    /** Null when facts exist but this direction has no coverage census. */
+    coverage: ApplicabilityCoverage | null;
+    /** Revisions carried by active facts, independent from the coverage revision. */
+    factRevisions: string[];
+    /** Active facts from this source only. */
+    facts: ApplicabilityFact[];
+}
+/** Source-grained response; sources are never merged or given hidden precedence. */
+export interface ApplicabilityResponse {
+    kind: "manufacturer_declared_applicability";
+    requestedSubject: ApplicabilitySubject;
+    direction: "forward" | "reverse";
+    sources: ApplicabilitySourceEntry[];
+}
+export type ApplicabilityOptions = {
+    subjectKind: "product";
+    subjectId: string;
+    direction: "forward";
+} | {
+    subjectKind: "variant";
+    subjectId: VariantId;
+    direction: "forward" | "reverse";
+};

package/associations-client.d.ts

@@ -12,7 +12,7 @@
  * sections, never concatenate them, and never describe a pairing as
  * "available on".
  */
-import type { AssociatedOptions, DeclaredAssociationsResponse } from "./association-types.js";
+import type { ApplicabilityOptions, ApplicabilityResponse, AssociatedOptions, DeclaredAssociationsResponse } from "./association-types.js";
 import { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 /**
@@ -49,3 +49,5 @@ export declare function declaredFinishes(transport: HttpTransport, variantId: Va
  * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
  */
 export declare function declaredProducts(transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<DeclaredAssociationsResponse>;
+/** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
+export declare function applicability(transport: HttpTransport, options: ApplicabilityOptions, signal?: AbortSignal): Promise<ApplicabilityResponse>;

package/associations-client.js

@@ -38,3 +38,7 @@ export function declaredFinishes(transport, variantId, options, signal) {
 export function declaredProducts(transport, variantId, options, signal) {
     return transport.requestJson(resolveOperation("list_associated_products"), { query: { variantId, ...options }, signal });
 }
+/** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
+export function applicability(transport, options, signal) {
+    return transport.requestJson(resolveOperation("get_applicability"), { query: options, signal });
+}

package/catalogue-client.d.ts

@@ -1,4 +1,4 @@
-import type { CatalogDocumentList, CatalogProductReferenceList, CatalogueDocumentAccessResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
+import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, 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,10 +13,19 @@ export declare class CatalogueClient {
     catalogueReferences(input: {
         variantIds: VariantId[];
     }, signal?: AbortSignal): Promise<CatalogueReferenceBatchResponse>;
+    /** List product collections with governed catalogue-channel membership. */
+    catalogueCollections(options?: CatalogueCollectionsOptions, signal?: AbortSignal): Promise<CatalogueChannelCollectionsResponse>;
     /** List immutable catalog documents retained from verified source material. */
     catalogs(signal?: AbortSignal): Promise<CatalogDocumentList>;
+    /** List stable one-based page identities and their representation status. */
+    catalogPages(catalogId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }, signal?: AbortSignal): Promise<CatalogPageListResult>;
+    /** Read a retained page representation or its exact missing-artifact receipt. */
+    catalogPageRepresentation(pageId: string, signal?: AbortSignal): Promise<CataloguePageRepresentationReadResult>;
     /** Read every verified product/page reference for one retained catalog. */
-    catalogReferences(catalogId: string, signal?: AbortSignal): Promise<CatalogProductReferenceList>;
+    catalogReferences(catalogId: string, signal?: AbortSignal): Promise<CatalogProductReferenceReadResult>;
     /** Resolve browser-safe access to one immutable catalogue document. */
     catalogueDocumentAccess(documentId: string, signal?: AbortSignal): Promise<CatalogueDocumentAccessResult>;
 }

package/catalogue-client.js

@@ -13,10 +13,29 @@ export class CatalogueClient {
     catalogueReferences(input, signal) {
         return this.#transport.requestJson(resolveOperation("get_catalogue_references_batch"), { body: input, signal });
     }
+    /** List product collections with governed catalogue-channel membership. */
+    catalogueCollections(options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("list_catalogue_channel_collections"), {
+            query: {
+                limit: options.limit,
+                offset: options.offset,
+                sampleLimit: options.sampleLimit,
+            },
+            signal,
+        });
+    }
     /** List immutable catalog documents retained from verified source material. */
     catalogs(signal) {
         return this.#transport.requestJson(resolveOperation("list_catalog_documents"), { signal });
     }
+    /** List stable one-based page identities and their representation status. */
+    catalogPages(catalogId, options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("list_catalog_pages"), { pathParams: { catalogId }, query: options, signal });
+    }
+    /** Read a retained page representation or its exact missing-artifact receipt. */
+    catalogPageRepresentation(pageId, signal) {
+        return this.#transport.requestJson(resolveOperation("get_catalog_page_representation"), { pathParams: { pageId }, 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 });

package/catalogue-types.d.ts

@@ -8,6 +8,24 @@ export interface CatalogueReference {
         x: number;
         y: number;
     };
+    productRegion?: {
+        coordinateSpace: "normalized_0_1000";
+        height: number;
+        kind: "product_region";
+        review: {
+            approvedBy: string;
+            confidence: {
+                evidenceBasis: "human_visual_review" | "model_assisted_visual_review";
+                level: "reviewed";
+            };
+            method: "human" | "model_assisted";
+            model?: string;
+            reviewedAt: string;
+        };
+        width: number;
+        x: number;
+        y: number;
+    };
     variantId: string;
     brand: {
         id: string;
@@ -43,7 +61,16 @@ export type CatalogueReferenceResult = {
     reference: CatalogueReference;
 } | {
     variantId: string;
-    status: "no_verified_reference" | "unresolved_variant" | "unavailable" | "upstream_failure";
+    status: "no_verified_reference";
+} | {
+    variantId: string;
+    status: "unresolved_variant";
+} | {
+    variantId: string;
+    status: "unavailable";
+} | {
+    variantId: string;
+    status: "upstream_failure";
 };
 export interface CatalogueReferenceBatchResponse {
     results: CatalogueReferenceResult[];
@@ -56,6 +83,50 @@ export interface CatalogueReferenceBatchResponse {
         upstreamFailure: number;
     };
 }
+/** Bounds for the flat catalogue-channel collection shelf. */
+export interface CatalogueCollectionsOptions {
+    limit?: number;
+    offset?: number;
+    sampleLimit?: number;
+}
+/** One representative product image carried by a catalogue collection. */
+export interface CatalogueCollectionSampleProduct {
+    assetId: string;
+    imageUrl: string;
+    sourceImageUrl: string;
+    productId: string;
+    productName: string;
+    variantId: string;
+    variantName: string | null;
+}
+/** A product collection whose variants have governed catalogue membership. */
+export interface CatalogueChannelCollection {
+    id: string;
+    slug: string;
+    name: string;
+    homepageUrl: string | null;
+    productCount: number;
+    variantCount: number;
+    sampleProducts: CatalogueCollectionSampleProduct[];
+}
+/** The flat, paginated catalogue-channel collection read model. */
+export interface CatalogueChannelCollectionsResponse {
+    collections: CatalogueChannelCollection[];
+    channel: {
+        token: "catalogue";
+        basis: "governed_variant_membership";
+    };
+    counts: {
+        basis: "exact_current_channel_membership";
+    };
+    pagination: {
+        count: number;
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
 export interface CatalogueDocumentAccess {
     documentId: string;
     contentType: "application/pdf";
@@ -69,9 +140,19 @@ export type CatalogueDocumentAccessResult = {
     access: CatalogueDocumentAccess;
 } | {
     documentId: string;
-    status: "unresolved_document" | "unavailable" | "forbidden" | "upstream_failure";
+    status: "unresolved_document";
+} | {
+    documentId: string;
+    status: "unavailable";
+} | {
+    documentId: string;
+    status: "forbidden";
+} | {
+    documentId: string;
+    status: "upstream_failure";
 };
 export interface CatalogDocument {
+    availability: "available";
     brand: {
         id: string;
         name: string;
@@ -82,21 +163,212 @@ export interface CatalogDocument {
         mediaType: "application/pdf";
         pageCount: number;
     };
+    edition: CatalogEdition;
     id: string;
     kind: "document";
     productStatus: "partial" | "not_processed";
+    receipt: CatalogAvailableReceipt;
     title: string;
 }
+export interface CatalogEdition {
+    id: string;
+    label: string;
+    title: string;
+}
+export interface CatalogAvailableReceipt {
+    extraction: {
+        references: number;
+        status: "partial" | "not_processed";
+    };
+    failures: CatalogFailureReceipt[];
+    pages: {
+        documentPositionBase: 1;
+        pageCount: number;
+    };
+    render: {
+        failedPages: Array<{
+            documentPage: number;
+            reason: string;
+        }>;
+        renderedPages: number;
+        status: "complete" | "partial" | "not_recorded";
+    };
+    source: {
+        checksum: {
+            algorithm: "sha256";
+            value: string;
+        };
+        sourceBasis: "brand_supplied";
+        retainedUrl: string;
+        status: "retained";
+    };
+}
+export interface CatalogFailureReceipt {
+    count: number;
+    reason: string;
+    stage: "source" | "render" | "extraction";
+}
+export interface UnavailableCatalogDocument {
+    availability: "source_unavailable";
+    brand: {
+        id: string;
+        name: string;
+    };
+    document: null;
+    edition: CatalogEdition;
+    id: string;
+    kind: "document";
+    productStatus: "not_processed";
+    receipt: {
+        extraction: {
+            references: 0;
+            status: "blocked_source_unavailable";
+        };
+        failures: CatalogFailureReceipt[];
+        pages: {
+            documentPositionBase: 1;
+            pageCount: null;
+        };
+        render: {
+            failedPages: never[];
+            renderedPages: 0;
+            status: "blocked_source_unavailable";
+        };
+        source: {
+            reason: "retained_source_not_found";
+            status: "unavailable";
+        };
+    };
+    title: string;
+}
+export type CatalogPublication = CatalogDocument | UnavailableCatalogDocument;
 export interface CatalogDocumentList {
-    catalogs: CatalogDocument[];
+    catalogs: CatalogPublication[];
     source: "verified-source-material-registry";
 }
 export interface CatalogProductReferenceList {
     catalog: CatalogDocument;
     coverage: {
+        documentPages: {
+            total: number;
+            withVerifiedReferences: number;
+        };
         pagesWithReferences: number;
+        precision: {
+            reason: "labelled_denominator_not_recorded";
+            status: "not_measured";
+        };
+        productCoverage: {
+            reason: "source_product_denominator_not_recorded";
+            status: "not_measured";
+        };
         references: number;
+        unmatched: {
+            reasons: "unmatched_source_products_not_recorded"[];
+            status: "not_measured";
+        };
     };
     references: CatalogueReference[];
     source: "verified-source-material-registry";
+    status: "available";
 }
+export interface CatalogProductReferenceUnavailable {
+    catalog: UnavailableCatalogDocument;
+    reason: "retained_source_not_found";
+    status: "source_unavailable";
+}
+export type CatalogProductReferenceReadResult = CatalogProductReferenceList | CatalogProductReferenceUnavailable;
+export interface CataloguePageRequiredArtifact {
+    mediaType: "image/webp";
+    version: "catalogue-page-webp-v1";
+}
+export interface CataloguePageAvailableArtifact extends Omit<CataloguePageRequiredArtifact, "version"> {
+    bucket: "materialgraph";
+    key: string;
+    url: string;
+}
+export type CataloguePage = {
+    catalogId: string;
+    documentId: string;
+    editionId: string;
+    id: string;
+    original: {
+        documentId: string;
+        documentPage: number;
+    };
+    page: {
+        documentPage: number;
+        printedPageLabel?: string;
+    };
+    representation: {
+        artifact: CataloguePageAvailableArtifact;
+        status: "available";
+    };
+} | {
+    catalogId: string;
+    documentId: string;
+    editionId: string;
+    id: string;
+    original: {
+        documentId: string;
+        documentPage: number;
+    };
+    page: {
+        documentPage: number;
+        printedPageLabel?: string;
+    };
+    representation: {
+        requiredArtifact: CataloguePageRequiredArtifact;
+        reason: "retained_representation_not_found";
+        status: "unavailable";
+    };
+};
+type CataloguePageAvailable = Extract<CataloguePage, {
+    representation: {
+        status: "available";
+    };
+}>;
+type CataloguePageUnavailable = Extract<CataloguePage, {
+    representation: {
+        status: "unavailable";
+    };
+}>;
+export type CatalogPageListResult = {
+    catalog: CatalogDocument;
+    pages: CataloguePage[];
+    pagination: {
+        count: number;
+        hasMore: boolean;
+        limit: number;
+        offset: number;
+        total: number;
+    };
+    representationCoverage: {
+        available: number;
+        failuresByReason: Array<{
+            count: number;
+            reason: "retained_representation_not_found";
+        }>;
+        total: number;
+        unavailable: number;
+    };
+    status: "available";
+} | {
+    catalog: UnavailableCatalogDocument;
+    reason: "retained_source_not_found";
+    status: "source_unavailable";
+};
+export type CataloguePageRepresentationReadResult = {
+    artifact: CataloguePageAvailableArtifact;
+    page: CataloguePageAvailable;
+    status: "available";
+} | {
+    requiredArtifact: CataloguePageRequiredArtifact;
+    page: CataloguePageUnavailable;
+    reason: "retained_representation_not_found";
+    status: "unavailable";
+} | {
+    pageId: string;
+    status: "unresolved_page";
+};
+export {};

package/client.d.ts

@@ -8,7 +8,7 @@ export type { BrowseNamespace } from "./client-browse.js";
 export type { ExplorationNamespace } from "./client-exploration.js";
 import { type SourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
 export type { SourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
-import type { AssociatedOptions } from "./association-types.js";
+import type { ApplicabilityOptions, AssociatedOptions } from "./association-types.js";
 import type { BrandsOptions } from "./brand-types.js";
 import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
 import { CodesClient } from "./codes-client.js";
@@ -18,8 +18,7 @@ import type { VarySchemesRequest, VarySchemesResponse } from "./composition-type
 import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
 import type { MatchStreamEvent } from "./match-stream-types.js";
 import type { MatchInput, MatchResponse } from "./match-types.js";
-import type { MaterialAssetProjection } from "./material-asset-types.js";
-import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { MaterialDocumentPageOptions } from "./material-asset-types.js";
 import type { MaterialQueryPlan } from "./material-query-plan-types.js";
 import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
 import { resolvePhrasesRequest as resolvePhrases } from "./resolve-client.js";
@@ -217,20 +216,9 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * goes with this one, and `search({ similarTo })` for one that LOOKS like it.
      */
     siblings(variantId: VariantId, signal?: AbortSignal): Promise<SiblingsResponse>;
-    /**
-     * THE QUESTION: "what do we actually KNOW about this material, and what have we
-     * simply not checked?" The only read that distinguishes a determined absence
-     * from an unasked question — every field carries a `status`, so this is the one
-     * surface entitled to back a negative ("no fire rating").
-     * {@link MaterialGraphClient.material} cannot: there an absence is merely unknown.
-     */
-    materialBlocks(variantId: VariantId, signal?: AbortSignal): Promise<MaterialBlockProjection>;
-    /**
-     * THE QUESTION: "what images and documents may I SHOW for this material?" — the
-     * redistribution-safe set (GET `/api/v1/materials/{variantId}/assets`), not
-     * every file on record.
-     */
-    materialAssets(variantId: VariantId, signal?: AbortSignal): Promise<MaterialAssetProjection>;
+    materialBlocks(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-block-types.js").MaterialBlockProjection>;
+    materialAssets(variantId: VariantId, signal?: AbortSignal): Promise<import("./material-asset-types.js").MaterialAssetProjection>;
+    materialDocuments(variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal): Promise<import("./material-asset-types.js").MaterialDocumentPage>;
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
      *
@@ -258,6 +246,7 @@ export declare class MaterialGraphClient extends CatalogueClient {
     associatedFinishes(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
     /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
     associatedProducts(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
+    applicability(options: ApplicabilityOptions, signal?: AbortSignal): Promise<import("./association-types.js").ApplicabilityResponse>;
     /**
      * THE QUESTION: "hydrate these ids I already hold" (POST
      * `/api/v1/materials/batch`, ≤ 100 ids) — never a discovery call. Throws

package/client.js

@@ -10,13 +10,14 @@ export * from "./client-config.js";
 import { browseQuery, createBrowseNamespace, } from "./client-browse.js";
 import { createExplorationNamespace, } from "./client-exploration.js";
 import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.js";
-import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import * as assoc from "./associations-client.js";
 import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
 import { slotPools as slotPoolsCall, varyScheme as varySchemeCall, } from "./composition-client.js";
 import { coordinate as coordinateCall } from "./coordinate-client.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
+import { materialAssets as materialAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
 import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 import { resolvePhrasesRequest as resolvePhrases, searchVocabularyRequest, } from "./resolve-client.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
@@ -275,27 +276,14 @@ export class MaterialGraphClient extends CatalogueClient {
     siblings(variantId, signal) {
         return this.#get("get_material_siblings", undefined, signal, { variantId });
     }
-    /**
-     * THE QUESTION: "what do we actually KNOW about this material, and what have we
-     * simply not checked?" The only read that distinguishes a determined absence
-     * from an unasked question — every field carries a `status`, so this is the one
-     * surface entitled to back a negative ("no fire rating").
-     * {@link MaterialGraphClient.material} cannot: there an absence is merely unknown.
-     */
     materialBlocks(variantId, signal) {
-        return this.#get("list_material_blocks", undefined, signal, {
-            variantId,
-        });
+        return materialBlocksCall(this.#transport, variantId, signal);
     }
-    /**
-     * THE QUESTION: "what images and documents may I SHOW for this material?" — the
-     * redistribution-safe set (GET `/api/v1/materials/{variantId}/assets`), not
-     * every file on record.
-     */
     materialAssets(variantId, signal) {
-        return this.#get("list_material_assets", undefined, signal, {
-            variantId,
-        });
+        return materialAssetsCall(this.#transport, variantId, signal);
+    }
+    materialDocuments(variantId, options, signal) {
+        return materialDocumentsCall(this.#transport, variantId, options, signal);
     }
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
@@ -328,11 +316,14 @@ export class MaterialGraphClient extends CatalogueClient {
     }
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     associatedFinishes(variantId, options, signal) {
-        return declaredFinishes(this.#transport, variantId, options, signal);
+        return assoc.declaredFinishes(this.#transport, variantId, options, signal);
     }
     /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
     associatedProducts(variantId, options, signal) {
-        return declaredProducts(this.#transport, variantId, options, signal);
+        return assoc.declaredProducts(this.#transport, variantId, options, signal);
+    }
+    applicability(options, signal) {
+        return assoc.applicability(this.#transport, options, signal);
     }
     materials(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {

package/corpus-scope-types.d.ts

@@ -29,19 +29,21 @@ import { type OpenEnum } from "./types.js";
  * `"all"` (and absence) is the WHOLE GRAPH — every material MaterialGraph
  * knows, orderable or not. Absence is never a narrower default.
  *
- * Three members gate on CHANNEL membership, which is what "can someone buy
- * this" means: `"materialBankNaOrderable"` (Material Bank North America),
+ * Four members gate on governed CHANNEL membership:
+ * `"materialBankNaOrderable"` (Material Bank North America),
  * `"materialBankEuOrderable"` (Material Bank Europe) and
  * `"designShopOrderable"` (DesignShop, with the products DesignShop hides from
  * browse excluded).
+ * `"materialBankNaAndCatalogue"` is a single producer-side union of Material
+ * Bank North America and governed Catalogue channel membership.
  *
  * `"materialBankOrderable"` is NOT one of them, despite the name. It selects
  * materials carrying a Material Bank identity — PROVENANCE, not a storefront —
  * and admits about 98% of the graph. Use it to exclude the crawl-sourced brands
  * that were never in the Material Bank feed; if you mean orderable, use one of
- * the three above.
+ * the channel-backed scopes above.
  */
-export type CorpusScope = OpenEnum<"all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaOrderable" | "materialBankOrderable">;
+export type CorpusScope = OpenEnum<"all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
 /**
  * The corpus a response AND its counts were drawn from. Present only when a
  * narrowing scope applied — absence means the whole graph. Read it alongside

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 ["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"]];
+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

@@ -2,6 +2,18 @@ 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",
@@ -20,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",
@@ -44,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",
@@ -103,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.17.0",
+  "version": "0.18.0",
   "type": "module",
   "exports": {
     ".": {

package/query-understanding-types.d.ts

@@ -63,7 +63,7 @@ export interface CanonicalLexicalReading {
 export interface CanonicalLexicalMatch {
     original: string;
     canonical: string;
-    rule: OpenEnum<"exact" | "plural-to-singular">;
+    rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
     span: {
         start: number;
         end: number;
@@ -73,7 +73,7 @@ export interface CanonicalLexicalMatch {
     receipt: {
         original: string;
         canonical: string;
-        rule: OpenEnum<"exact" | "plural-to-singular">;
+        rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
         authorities: CanonicalLexicalAuthorityReceipt[];
     };
 }
@@ -158,6 +158,7 @@ export interface QueryProductTypeReceipt {
 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">;
@@ -189,8 +190,10 @@ export interface QueryCategoryScopeReceipt {
 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">;

package/search-collapse-types.d.ts

@@ -50,7 +50,7 @@ export interface CollapsedVariant {
      * 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. */
+    /** This variant's own mode-primary score — the value the array is ordered by. */
     score: number;
 }
 /**

package/search-request-types.d.ts

@@ -32,8 +32,8 @@ export interface SearchInput {
     };
     mood?: string;
     /**
-     * Re-order the final scored results. `relevance` (default) keeps the fused
-     * score; `light` / `dark` / `vivid` / `muted` / `colourful` are the colour
+     * Re-order the final scored results. `relevance` (default) keeps the selected
+     * mode's primary score; `light` / `dark` / `vivid` / `muted` / `colourful` are the colour
      * ramps; `name` (A→Z), `name_desc` (Z→A) and `recent` (newest first) are the
      * catalogue orders — the same three `/search/browse` walks the corpus in, so
      * one word means one order on both lanes.
@@ -100,12 +100,18 @@ export interface SearchInput {
         boost?: string;
         filter?: string[];
     };
+    /**
+     * Optional multipliers for the selected mode's one ordering signal. At most
+     * one is applied: image for image/image-text, lexical for lexical/browse, and
+     * colour for colour mode. Non-mode keys are accepted for compatibility but
+     * cannot activate secondary scoring.
+     */
     weights?: {
         image?: number;
         category?: number;
         colour?: number;
         lexical?: number;
-        /** Text rerank multiplier applied when a seeded search also carries `text` (default 0.4). */
+        /** Compatibility field; seeded text does not activate secondary scoring. */
         text?: number;
     };
     filters?: SearchFilter[];
@@ -120,6 +126,7 @@ export interface SearchInput {
     /** The previous response's `cursor`, passed back verbatim. Never synthesise one. */
     cursor?: Cursor;
     explain?: boolean;
+    /** Public POST defaults to distinct products; send `"none"` for individual variants. */
     collapse?: OpenEnum<"none" | "product">;
     /**
      * Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools.
@@ -156,7 +163,7 @@ export interface SearchInput {
      * `"search"` (default) is the full engine. `"typeahead"` is the as-you-type
      * profile: lexical-only with prefix match on the final token, forced
      * `view: "card"`, `limit` capped at 24, and no mood/colour detection tiers,
-     * semantic fallback, category boost, colour rerank, refinement suggestions,
+     * semantic fallback, secondary scoring, refinement suggestions,
      * counts, or meanings. `textModes` is ignored under typeahead.
      */
     intent?: OpenEnum<"search" | "typeahead">;
@@ -166,22 +173,26 @@ export interface SearchInput {
      * **ABSENT means the WHOLE GRAPH** — every material MaterialGraph knows,
      * orderable or not. Absence is never a narrower default, so a caller that
      * says nothing gets materials it may not be able to buy.
-     * Three scopes gate on CHANNEL membership, which is what "can someone buy
-     * this" means: `"materialBankNaOrderable"` (Material Bank North America,
+     * Three transaction-oriented scopes gate on governed CHANNEL membership:
+     * `"materialBankNaOrderable"` (Material Bank North America,
      * ~277,000 materials), `"materialBankEuOrderable"` (Material Bank Europe,
      * ~65,000) and `"designShopOrderable"` (DesignShop, ~34,000, with the
      * products DesignShop hides from browse excluded).
+     * `"materialBankNaAndCatalogue"` is a governed discovery corpus: the single
+     * producer-side union of Material Bank North America and Catalogue editorial
+     * membership. It is not a buyability claim, and a catalogue reference alone
+     * does not establish membership.
      *
      * `"materialBankOrderable"` is NOT one of them, despite the name. It selects
      * materials carrying a Material Bank identity — a PROVENANCE signal, not a
      * storefront — and admits about 98% of the graph. Use it to exclude the
      * crawl-sourced brands that were never in the Material Bank feed; if you mean
-     * orderable, use one of the three above.
+     * orderable, use one of the channel-backed scopes above.
      *
-     * A scope answers what is BUYABLE. It never answers what is SUITABLE: scope
-     * on channel, then refine on sector. A trade-only material can be right for a
-     * room and still unbuyable, and most of what a consumer can buy is
-     * commercial-suited product.
+     * A scope answers membership in its named distribution or visibility
+     * surface; the token-specific description states whether that means
+     * transaction or editorial inclusion. It never answers what is SUITABLE:
+     * scope on channel, then refine on sector.
      *
      * The scope is applied INSIDE the query: `limit` fills with eligible rows,
      * `counts` describe the SCOPED corpus, and the response echoes the scope.
@@ -203,6 +214,8 @@ export interface SearchGetParams {
     colours?: string;
     logic?: OpenEnum<"all" | "any">;
     mood?: string;
+    /** Governed corpus applied inside retrieval; absent means the whole graph. */
+    corpusScope?: CorpusScope;
     sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful" | "name" | "name_desc" | "recent">;
     tol?: OpenEnum<"tight" | "normal" | "loose">;
     /** Seed the search from this variant's image. Opaque — pass it through verbatim. */

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

@@ -1,17 +1,55 @@
 /**
  * @module sdk/search-response-receipt-types
- * @description Inspectable routing, rerank, and compound-constraint receipts
- * emitted by ordinary Search responses.
+ * @description Inspectable routing, compatibility, 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). */
+/**
+ * Compatibility receipt for non-mode colour handling. Current one-signal
+ * ordering reports it skipped at weight 0; colour may still be diagnostic or a
+ * hard displayed-image constraint, but does not blend into score.
+ */
 export interface SearchRerankReport {
     colour?: OpenEnum<"ok" | "failed" | "skipped">;
     colourWeight?: number;
     colourLabel?: string;
 }
+/** Stage counts retained when an explain-enabled search returns no results. */
+export interface SearchEmptyOutcomeCounts {
+    retrieved: number;
+    afterPrune: number;
+    final: number;
+}
+/**
+ * Explain-only evidence for why a completed search returned no results.
+ * `proven-corpus-empty` is exhaustive; every other empty remains explicitly
+ * unproven rather than being presented as catalogue absence.
+ */
+export type SearchEmptyOutcome = {
+    kind: "proven-corpus-empty";
+    basis: OpenEnum<"spec-allowlist" | "brand-scope">;
+    exhaustive: true;
+    sourceEmpty?: boolean | null;
+    counts?: SearchEmptyOutcomeCounts;
+} | {
+    kind: "unproven-empty";
+    reason: OpenEnum<"allowlist-truncated" | "retrieval-window-not-exhaustive" | "source-empty" | "post-retrieval-rejected" | "pagination-empty" | "no-authoritative-empty-proof">;
+    sourceEmpty?: boolean | null;
+    counts?: SearchEmptyOutcomeCounts;
+};
+/** Explain-only coverage of substantive query terms in the lexical projection. */
+export interface SearchTermCoverageReceipt {
+    status: OpenEnum<"covered" | "uncovered" | "unavailable" | "skipped">;
+    terms: string[];
+    note?: string;
+}
+/** Explain-only outcome receipts shared by full and card search responses. */
+export interface SearchResponseExplainReceipts {
+    emptyOutcome?: SearchEmptyOutcome;
+    termCoverage?: SearchTermCoverageReceipt;
+}
 /** One stage in the explain-only ledger of transformations that actually ran. */
 export type SearchQueryTransformStage = {
     stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
@@ -63,7 +101,10 @@ export interface SearchBrandSkip {
  */
 export interface SearchExecutionPlan {
     grain: OpenEnum<"variant" | "product">;
+    /** Which 2048D Voyage projection served a text-mode request. */
+    textLane?: OpenEnum<"image-text" | "variant-text">;
     weights: {
+        portrait: number;
         image: number;
         category: number;
         colour: number;
@@ -71,6 +112,13 @@ export interface SearchExecutionPlan {
         text: number;
     };
     queryTransform: SearchQueryTransformStage[];
+    /** Ordered, explain-only request-understanding execution trace. */
+    steps?: Array<{
+        key: string;
+        status: OpenEnum<"executed" | "skipped">;
+        reason: string;
+        durationMs: number;
+    }>;
     categoryAnchor?: SearchCategoryAnchor;
     brandAnchor?: SearchBrandAnchor;
     brandSkipped?: SearchBrandSkip;

package/search-result-validation.js

@@ -73,9 +73,12 @@ function checkColourMeta(value, what, fail) {
     requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
     requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
 }
-/** `searchResultSignalsSchema` — five nullable numbers, all required keys. */
+/** `searchResultSignalsSchema` — five required scores plus additive portrait. */
 function checkSignals(value, what, fail) {
     const record = requireRecord(value, what, fail);
+    if (record.portrait !== undefined) {
+        requireNullableNumber(record.portrait, `${what}.portrait`, fail);
+    }
     for (const signal of ["image", "category", "colour", "lexical", "text"]) {
         requireNullableNumber(record[signal], `${what}.${signal}`, fail);
     }

package/search-window-types.d.ts

@@ -4,14 +4,22 @@ export interface SearchWindowReceipt {
     profile: "interactive-r1" | (string & {});
     /** Candidate depth used by the final retrieval. */
     candidateTier: number;
-    /** Every candidate retrieval, including required fallbacks and optional recovery. */
+    /** Candidate retrieval count; `searchMaterials` reports exactly one selected retrieval. */
     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;
+    /**
+     * Candidate attrition through the selected retrieval source. Absent when the
+     * response path did not perform ordinary retrieval (for example typeahead).
+     */
+    candidateCounts?: {
+        /** Provider-returned matches before bounded selection; null for SQL/exact arms. */
+        rawProviderMatches: number | null;
+        /** Matches selected from that provider response; null for SQL/exact arms. */
+        selectedMatches: number | null;
+        /** Canonical candidates returned by the selected retrieval arm. */
+        hydratedCanonicalCandidates: number;
+    };
 }

package/suggest-types.d.ts

@@ -12,6 +12,7 @@
  * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
  * of the best matches, never a census of matching entities.
  */
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /** Which kind of entity a suggestion is — and therefore what `refId` means. */
 export type SuggestKind = "product" | "brand" | "category";
 /** How the query met the suggestion's label. Strongest first. */
@@ -44,6 +45,8 @@ export interface SuggestResponse {
     query: string;
     /** Ranked best-match-first. Empty when nothing came close — a miss, not an error. */
     suggestions: Suggestion[];
+    /** Present only when a narrowing governed corpus was applied. */
+    corpusScope?: CorpusScopeReceipt;
 }
 /** Options for {@link MaterialGraphClient.suggest}. */
 export interface SuggestOptions {
@@ -51,6 +54,8 @@ export interface SuggestOptions {
     limit?: number;
     /** Restrict to these kinds. Omit for all of them. */
     kind?: SuggestKind | SuggestKind[];
+    /** Governed corpus membership; absent means the whole graph. */
+    corpusScope?: CorpusScope;
 }
 /**
  * Shape the query string for a suggest call.
@@ -64,4 +69,5 @@ export declare function suggestQuery(q: string, options?: SuggestOptions): {
     q: string;
     limit?: number;
     kind?: string;
+    corpusScope?: CorpusScope;
 };

package/suggest-types.js

@@ -24,5 +24,5 @@ export function suggestQuery(q, options) {
     const kind = Array.isArray(options?.kind)
         ? options.kind.join(",")
         : options?.kind;
-    return { q, limit: options?.limit, kind };
+    return { q, limit: options?.limit, kind, corpusScope: options?.corpusScope };
 }

package/types.d.ts

@@ -32,7 +32,7 @@ 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, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport } from "./search-response-receipt-types.js";
+import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport, SearchResponseExplainReceipts } 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 & {});
@@ -90,11 +90,13 @@ export type ImageSource = OpenEnum<"r2" | "origin">;
 export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, } from "./material-types.js";
 /** Per-signal scores, present on a result when `explain` was requested. */
 export interface SearchResultSignals {
+    /** Voyage similarity in the dedicated variant text-portrait space. */
+    portrait?: number | null;
     image: number | null;
     category: number | null;
     colour: number | null;
     lexical: number | null;
-    /** Text→image RERANK cosine — non-null only for a seeded search carrying `text`. */
+    /** Compatibility slot for retired seeded secondary scoring; currently null. */
     text: number | null;
 }
 /** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
@@ -190,7 +192,7 @@ export interface SearchResultItem {
         siblings?: SearchAnatomyMember[];
         siblingsTruncated?: boolean;
     };
-    /** Fused score — range [0, sum of active weights]; see `maxScore`. */
+    /** Selected mode's weighted primary score; see `maxScore`. */
     score: number;
     /**
      * Match only. How close this material is to the query, as an ABSOLUTE
@@ -398,7 +400,7 @@ export interface SearchRefinementReceipt {
  * you asked for it. Follow `cursor` for the rest. "I found 24 materials" is
  * wrong whenever `limit` was 24.
  */
-export interface SearchResponse {
+export interface SearchResponse extends SearchResponseExplainReceipts {
     view: OpenEnum<"full" | "card">;
     /** THIS PAGE. Its length is a page size, never a total. */
     results: SearchResultItem[];