@instruments/materialgraph 0.17.0 → 0.19.0

package/catalogue-types.d.ts

@@ -2,12 +2,32 @@
 export interface CatalogueReference {
     anchor: {
         coordinateSpace: "normalized_0_1000";
+        /** Page carrying the printed code; defaults to page.documentPage. Do not draw it on another page. */
+        documentPage?: number;
         height: number;
         kind: "printed_code";
         width: number;
         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;
@@ -35,7 +55,7 @@ export interface CatalogueReference {
         brandItemCode: string;
     };
     status: "verified";
-    isPrimary: true;
+    isPrimary: boolean;
 }
 export type CatalogueReferenceResult = {
     variantId: string;
@@ -43,7 +63,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 +85,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 +142,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 +165,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/citation-types.d.ts

@@ -0,0 +1,34 @@
+/** Small handle carried by a verdict cell. Resolve it only when evidence is opened. */
+export interface VerdictCitation {
+    citationId: string;
+    sourceType: string;
+    count: number;
+}
+export interface ResolvedVerdictCitation {
+    citationId: string;
+    sourceType: string;
+    source: {
+        kind: "source_record" | "source_material" | "source_fact" | "url" | "asset" | "download" | "manual_note" | "agent_output";
+        /** Canonical source/fact/asset/download id, a public source URL, or the claim-source handle when no public reference is available. */
+        ref: string;
+        title?: string;
+        url?: string;
+        /** Same-origin public asset proxy path when retained bytes are available. */
+        publicPath?: string;
+        sourceId?: string;
+        sourceFactId?: string;
+        sourceAssetId?: string;
+        sourceDownloadId?: string;
+        locator?: {
+            page?: number;
+            selector?: string;
+            xPath?: string;
+            imageBox?: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+        };
+    };
+}

package/citation-types.js

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

package/client-browse.d.ts

@@ -52,6 +52,7 @@ export declare function browseQuery(params: BrowseParams): {
     count: BrowseParams["count"];
     types: BrowseParams["types"];
     brands: BrowseParams["brands"];
+    role: BrowseParams["role"];
     filters: string[] | undefined;
     facetCounts: string | undefined;
     corpusScope: BrowseParams["corpusScope"];

package/client-browse.js

@@ -28,6 +28,7 @@ export function browseQuery(params) {
         count: params.count,
         types: params.types,
         brands: params.brands,
+        role: params.role,
         filters: params.filters?.map((entry) => JSON.stringify(entry)),
         facetCounts: params.facetCounts?.join(","),
         corpusScope: params.corpusScope,

package/client-vocabulary.d.ts

@@ -0,0 +1,10 @@
+import { HttpTransport } from "./http-transport.js";
+import type { ColourFacetsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
+export declare function colourFacets(transport: HttpTransport, signal?: AbortSignal): Promise<ColourFacetsResponse>;
+export declare function resolveColour(transport: HttpTransport, name: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
+export declare function suggestColour(transport: HttpTransport, q: string, options?: {
+    limit?: number;
+}, signal?: AbortSignal): Promise<SuggestColourResponse>;
+export declare function suggest(transport: HttpTransport, q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
+export declare function resolveAttribute(transport: HttpTransport, q: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
+export declare function resolveAttributeValue(transport: HttpTransport, attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;

package/client-vocabulary.js

@@ -0,0 +1,32 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+import { suggestQuery } from "./suggest-types.js";
+export function colourFacets(transport, signal) {
+    return transport.requestJson(resolveOperation("get_colour_facets"), { signal });
+}
+export function resolveColour(transport, name, signal) {
+    return transport.requestJson(resolveOperation("resolve_colour_name"), { query: { name }, signal });
+}
+export function suggestColour(transport, q, options, signal) {
+    return transport.requestJson(resolveOperation("suggest_colour_names"), { query: { q, limit: options?.limit }, signal });
+}
+export function suggest(transport, q, options, signal) {
+    return transport.requestJson(resolveOperation("search_suggest"), { query: suggestQuery(q, options), signal });
+}
+export function resolveAttribute(transport, q, options, signal) {
+    return transport.requestJson(resolveOperation("catalog_resolve_attribute"), {
+        query: {
+            q,
+            limit: options?.limit,
+            facetableOnly: options?.facetableOnly,
+        },
+        signal,
+    });
+}
+export function resolveAttributeValue(transport, attributeId, query, options, signal) {
+    return transport.requestJson(resolveOperation("catalog_resolve_value"), {
+        query: { q: query, limit: options?.limit },
+        pathParams: { attributeId },
+        signal,
+    });
+}

package/client.d.ts

@@ -1,6 +1,7 @@
 import { CatalogueClient } from "./catalogue-client.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
 import { type RateLimit } from "./errors.js";
+import { ScheduleReferencesClient } from "./schedule-references-client.js";
 export * from "./client-config.js";
 import { type BrowseNamespace } from "./client-browse.js";
 import { type ExplorationNamespace } from "./client-exploration.js";
@@ -8,9 +9,10 @@ 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 type { ResolvedVerdictCitation } from "./citation-types.js";
 import { CodesClient } from "./codes-client.js";
 import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
 import { ColoursClient } from "./colours-client.js";
@@ -18,8 +20,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";
@@ -27,6 +28,8 @@ import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRu
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
+import type { FindSubstitutesOptions, FindSubstitutesResponse } from "./substitute-types.js";
+import type { ProductTypeCoverageOptions, ProductTypeStatusCoverage } from "./taxonomy-coverage-types.js";
 import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
@@ -65,6 +68,7 @@ import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecRespon
  */
 export declare class MaterialGraphClient extends CatalogueClient {
     #private;
+    readonly scheduleReferences: ScheduleReferencesClient;
     readonly baseUrl: string;
     /**
      * THE QUESTION: "show me everything in this category / this brand, in a plain
@@ -217,20 +221,10 @@ 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>;
+    materialRenderAssets(variantId: VariantId, signal?: AbortSignal): Promise<import("./render-assets-types.js").MaterialRenderAssets>;
+    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.
      *
@@ -250,14 +244,17 @@ export declare class MaterialGraphClient extends CatalogueClient {
      *
      * READ `item.source` BEFORE PHRASING: the rail mixes three tiers of evidence —
      * `cospec` (real orders), `considered` (board activity), `colour` (palette
-     * look-alike). Only `cospec` supports "specified together". `cospecCount` tells
+     * look-alike). Only `cospec` supports "sampled together". `cospecCount` tells
      * you how much of the rail is real order evidence.
      */
     pairings(variantId: VariantId, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
+    /** Find bounded, exact-spec substitutes for one opaque variant id. */
+    findSubstitutes(variantId: VariantId, options?: FindSubstitutesOptions, signal?: AbortSignal): Promise<FindSubstitutesResponse>;
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     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
@@ -288,58 +285,19 @@ export declare class MaterialGraphClient extends CatalogueClient {
         view?: "tile";
         idKind?: MaterialsBatchGetOptions["idKind"];
     }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
-    /**
-     * THE QUESTION: "what colour WORDS may I use?" — family, mood and undertone
-     * with live counts. Vocabulary, not values: instead use `colours.profiles()`
-     * for a category's palette, {@link MaterialGraphClient.byColour} to search by a
-     * colour, {@link MaterialGraphClient.resolveColour} to turn a NAME into a hex.
-     */
+    /** Vocabulary families and counts; use `colours.profiles()` for a material palette. */
     colourFacets(signal?: AbortSignal): Promise<ColourFacetsResponse>;
-    /**
-     * THE QUESTION: "what hex is 'Hague Blue'?" — the step before
-     * {@link MaterialGraphClient.byColour} when you hold a name rather than a hex.
-     * A `null` match means unrecognised, not "no such colour".
-     */
+    /** Resolve a colour name to its canonical hex when recognised. */
     resolveColour(name: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q: string, options?: {
         limit?: number;
     }, signal?: AbortSignal): Promise<SuggestColourResponse>;
-    /**
-     * THE QUESTION: "what is the user starting to type?" It ranks NAMES, not
-     * materials — instead use {@link MaterialGraphClient.search} once they commit,
-     * {@link MaterialGraphClient.suggestColour} for colour names, and
-     * {@link MaterialGraphClient.searchVocabulary} for attribute/value tokens.
-     *
-     * Entity typeahead across products, brands and categories
-     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
-     * lookup, no embedding call and no model. Every suggestion carries the
-     * `refId` it resolves to — a product id, a brand slug, or a product-type key
-     * — so selecting one should navigate to that entity rather than re-running
-     * `label` as a search.
-     *
-     * @example
-     * const { suggestions } = await client.suggest("carr", { kind: "product" });
-     */
+    /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
     suggest(q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
-    /**
-     * THE QUESTION: "the user said 'fire rating' — which canonical attribute is
-     * that?" Free text in, canonical `attributeId`s out; pair with
-     * {@link MaterialGraphClient.resolveAttributeValue} for the VALUE, then spend
-     * the pair on {@link MaterialGraphClient.bySpec} or `search({ filters })`.
-     * Instead use {@link MaterialGraphClient.specificationFacets} to browse rather
-     * than resolve.
-     */
+    /** Resolve free text to a canonical attribute id. */
     resolveAttribute(q: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
-    /**
-     * THE QUESTION: "the user said 'class A' — what canonical term is that, under
-     * THIS attribute?" The value half of the pair
-     * {@link MaterialGraphClient.resolveAttribute} starts. Read
-     * `resolution.recommendedAction`, not just `best`: `ambiguous` means ask.
-     *
-     * @param attributeId Canonical vocabulary, not an opaque id — discover it, do
-     * not invent it.
-     */
+    /** Resolve a value under a canonical attribute id; inspect `recommendedAction` for ambiguity. */
     resolveAttributeValue(attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
     /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<import("./catalog-discovery-types.js").VocabularySearchResponse>;
@@ -375,6 +333,12 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * {@link MaterialGraphClient.applicableSpecs}). Discover, never hand-write.
      */
     taxonomy(signal?: AbortSignal): Promise<TaxonomyResponse>;
+    /**
+     * Exact current primary-type status counts by retained source category path.
+     * `comparisonThreshold` is a reporting cutoff only: it never promotes a
+     * proposal into an accepted category.
+     */
+    productTypeCoverage(options?: ProductTypeCoverageOptions, signal?: AbortSignal): Promise<ProductTypeStatusCoverage>;
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
@@ -546,6 +510,8 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
      */
     runSchedule(runId: RunId, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+    /** Follow a verdict cell's citation handle to its canonical claim source. */
+    citation(citationId: string, signal?: AbortSignal): Promise<ResolvedVerdictCitation>;
     /**
      * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
      *