@instruments/materialgraph 0.26.0 → 0.27.0

package/association-types.d.ts

@@ -10,6 +10,7 @@
  * with {@link PairingItem}, so the two can never be concatenated into one list.
  * Present them as separate sections, and never describe a pairing as available.
  */
+import type { CorpusScope } from "./corpus-scope-types.js";
 import type { Cursor, VariantId } from "./identifiers.js";
 import type { ProductTypeReceipt } from "./material-types.js";
 /**
@@ -54,13 +55,22 @@ export type DeclaredAssociation = {
     /** Review receipt; proposed types are never accepted categories. */
     productTypeReceipt: ProductTypeReceipt;
     declared: DeclaredProvenance;
+    /** The accepted display category, for a card's kind pill. Null when none is accepted. */
+    kindLabel: string | null;
+    /** The accepted `price_tier` term (`$` to `$$$$$`). Absent means unknown, never cheap. */
+    priceTier?: string;
+    /**
+     * The eligible variants of this association's product, the set `listVariants`
+     * pages. Absent when the product has no eligible variant.
+     */
+    colourwayCount?: number;
 };
 /**
  * One page of declared associations.
  *
  * READ `totalAssociations`, NOT `associations.length`, when rendering a count
  * like "Compatible Finishes (128)": the array is one page (up to 48), the total
- * is the whole set for this subject, direction and corpus. A page is not a
+ * is the whole set for this subject, direction and corpus scope. A page is not a
  * corpus — walk `nextCursor` before making any claim about the full set.
  */
 export type DeclaredAssociationsResponse = {
@@ -71,7 +81,7 @@ export type DeclaredAssociationsResponse = {
      */
     kind: "declared_association";
     associations: DeclaredAssociation[];
-    /** The TRUE count for this subject, direction and corpus. Not the page size. */
+    /** The TRUE count for this subject, direction and corpus scope. Not the page size. */
     totalAssociations: number;
     /** How many associations this page carries. */
     returnedCount: number;
@@ -86,16 +96,17 @@ export type AssociatedOptions = {
      */
     limit?: number;
     /**
-     * Source identity scope. `material_bank` returns associations pointing at a
-     * variant carrying a Material Bank SKU. A SKU alone does not establish current
-     * sampleability; use `sampleableOnly` for an accepted availability fact.
+     * Narrows the associations, `totalAssociations` and the cursor to one corpus
+     * scope. `materialBankOrderable` keeps associations pointing at a variant
+     * carrying a Material Bank id; absent or `all` is the whole declared set.
+     * Membership does not establish sampleability; use `sampleableOnly` for that.
      */
-    corpus?: "all" | "material_bank";
+    corpusScope?: CorpusScope;
     /** Return only associations whose effective sampleability is true. */
     sampleableOnly?: boolean;
     /**
      * The previous response's `nextCursor`, passed back verbatim. A cursor is
-     * bound to its subject, direction and corpus — replaying it against a
+     * bound to its subject, direction and corpus scope - replaying it against a
      * different one is a 400, never a silently different page.
      */
     cursor?: Cursor;

package/attribution-types.d.ts

@@ -13,12 +13,12 @@
 /**
  * The ranking basis, in one vocabulary across both ranked routes.
  *
- * The first five values are `search()`'s `mode` verbatim, and there
+ * The first seven values are `search()`'s `mode` verbatim, and there
  * `attribution.basis === mode` always. `"match"` is what `match()` reports;
  * that route has no `mode`, so this is the only field its outcomes can be
  * grouped by.
  */
-export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity-browse" | "agent" | "match";
+export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity-browse" | "agent" | "attribute" | "match";
 /**
  * Envelope-level attribution receipt, on every successful ranked response.
  *

package/brand-types.d.ts

@@ -5,7 +5,13 @@
  * The SDK's one OFFSET-paginated surface — everything else that pages uses an
  * opaque cursor. `meta` is where the page/corpus distinction is settled here.
  */
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 export type BrandsOptions = {
+    /**
+     * Which corpus to list from. Narrows the brands AND the corpus their counts
+     * are drawn from, inside the query. Absent or `"all"` is the whole graph.
+     */
+    corpusScope?: CorpusScope;
     /** Fuzzy name filter. Omit for the whole collection. */
     q?: string;
     /** Page size. Never a bound on the collection. */
@@ -25,6 +31,8 @@ export type BrandCatalogListItem = {
     variantCount: number;
 };
 export type BrandCatalogListPage = {
+    /** Present only when a narrowing scope applied; absence means the whole graph. */
+    corpusScope?: CorpusScopeReceipt;
     /** THIS PAGE. Its length is `meta.count`, never `meta.total`. */
     items: BrandCatalogListItem[];
     /**

package/brands-client.d.ts

@@ -1,48 +1,17 @@
 /**
- * The BRAND lens: the catalogue collection, one brand's profile, and one
- * brand's whole colour range, as thin wrappers over the shared
- * {@link HttpTransport}. `MaterialGraphClient.brands` / `.brand` /
- * `.brandColourDeck` delegate here; the contract lives in this file.
+ * The BRAND lens: the catalogue collection, as a thin wrapper over the shared
+ * {@link HttpTransport}. `MaterialGraphClient.brands` delegates here; the
+ * contract lives in this file.
  *
- * A brand is a COMPANY, not a catalogue. Every count these reads return is
+ * A brand is a COMPANY, not a catalogue. Every count this read returns is
  * coverage — what MaterialGraph has ingested — and never a claim about how
  * many products the maker sells.
  */
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
-import type { BrandFanDeck } from "./fan-deck-types.js";
 import type { HttpTransport } from "./http-transport.js";
-import type { BrandOptions, BrandProfileResponse } from "./types.js";
 /**
  * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
  * one OFFSET-paginated surface: read `meta.total` for the collection size and
- * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
- * brand's profile and trade signals.
+ * `meta.hasMore` to keep walking.
  */
 export declare const listBrands: (transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal) => Promise<BrandCatalogListPage>;
-/**
- * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
- * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
- * key means no value is held — never infer `false`. Instead use `search()` to
- * find their materials; this describes the company, not the catalog.
- */
-export declare const brandProfile: (transport: HttpTransport, brandSlug: string, options?: BrandOptions, signal?: AbortSignal) => Promise<BrandProfileResponse>;
-/**
- * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
- * Colours grouped by family — creams together, then greys, then browns — and
- * ordered light to dark within each. No stored scalar produces that order: a
- * lightness sort interleaves the whites and the creams, and a reader loses the
- * sense that they are looking at two different families.
- *
- * Deliberately unpaginated, so there is no cursor to walk and no all-brands
- * form: family order is only correct over a COMPLETE range, because the greys
- * cannot be placed against the browns while holding one page of each. A range
- * past the server ceiling reports `truncatedAt` rather than being quietly cut,
- * and an absent `truncatedAt` means the deck is whole.
- *
- * Every swatch carries the maker's PUBLISHED hex — this read never returns a
- * colour derived from imagery. For "what is near this colour, across makers"
- * use `byColour()` instead.
- *
- * @param brandSlug The brand's slug, as `listBrands()` reports it.
- */
-export declare const brandColourDeck: (transport: HttpTransport, brandSlug: string, signal?: AbortSignal) => Promise<BrandFanDeck>;

package/brands-client.js

@@ -2,40 +2,14 @@ import { resolveOperation } from "./operations.js";
 /**
  * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
  * one OFFSET-paginated surface: read `meta.total` for the collection size and
- * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
- * brand's profile and trade signals.
+ * `meta.hasMore` to keep walking.
  */
 export const listBrands = async (transport, options = {}, signal) => await transport.requestJson(resolveOperation("list_brands"), {
-    query: { limit: options.limit, offset: options.offset, q: options.q },
-    signal,
-});
-/**
- * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
- * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
- * key means no value is held — never infer `false`. Instead use `search()` to
- * find their materials; this describes the company, not the catalog.
- */
-export const brandProfile = async (transport, brandSlug, options, signal) => await transport.requestJson(resolveOperation("get_brand_profile"), { pathParams: { brandSlug }, query: { q: options?.q }, signal });
-/**
- * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
- * Colours grouped by family — creams together, then greys, then browns — and
- * ordered light to dark within each. No stored scalar produces that order: a
- * lightness sort interleaves the whites and the creams, and a reader loses the
- * sense that they are looking at two different families.
- *
- * Deliberately unpaginated, so there is no cursor to walk and no all-brands
- * form: family order is only correct over a COMPLETE range, because the greys
- * cannot be placed against the browns while holding one page of each. A range
- * past the server ceiling reports `truncatedAt` rather than being quietly cut,
- * and an absent `truncatedAt` means the deck is whole.
- *
- * Every swatch carries the maker's PUBLISHED hex — this read never returns a
- * colour derived from imagery. For "what is near this colour, across makers"
- * use `byColour()` instead.
- *
- * @param brandSlug The brand's slug, as `listBrands()` reports it.
- */
-export const brandColourDeck = async (transport, brandSlug, signal) => await transport.requestJson(resolveOperation("brand_colour_deck"), {
-    pathParams: { brandSlug },
+    query: {
+        corpusScope: options.corpusScope,
+        limit: options.limit,
+        offset: options.offset,
+        q: options.q,
+    },
     signal,
 });

package/by-colour-types.d.ts

@@ -37,11 +37,22 @@ export type ByColourMatch = {
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
+    /**
+     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest.
+     * ABSENT means no hash is on record, never that there is no image.
+     */
+    imageSha256?: string;
     hex: string | null;
     distance: number;
     closeness: number;
     category: MatchCategory | null;
     oklab: OklabTriple | null;
+    /**
+     * Whether the reported `hex` has a hue compatible with the query colour, by
+     * colorscope's `isHueCompatible` at its default thresholds. A flag, never a
+     * gate. ABSENT when the match has no hex or the query was a palette.
+     */
+    hueCompatible?: boolean;
     /**
      * Where `hex` came from — PER MATCH, never per response. `"declared"`: the
      * manufacturer published it (a paint's own colour system), so it may be
@@ -111,7 +122,13 @@ export type ColourFamilyGate = {
 };
 /** Receipt for the hard category gate and its treatment of unknown typing. */
 export type ColourCategoryGate = {
-    /** Category names or keys the caller asked the gate to keep. */
+    /**
+     * Present when the caller named no category: the page then holds surface
+     * materials only (the `materials` product-type groups, listed in
+     * `requested`), so lights, taps and furniture do not answer a colour.
+     */
+    defaulted?: true;
+    /** Category names or keys the gate kept: the caller's, or the default groups. */
     requested: string[];
     /** Only accepted primary product types can establish membership. */
     requiresAcceptedPrimaryProductType: true;
@@ -121,8 +138,8 @@ export type ColourCategoryGate = {
 /**
  * Receipt for the colour-identity collapse that turns a variant-grain ranking
  * into a page of TILES — one per (brand, product, dominant hex), one per stored
- * photograph. The live endpoint always sends it; it is optional here only so
- * responses captured before the collapse existed still type-check.
+ * photograph. Only responses stored before the one search carry it: the one
+ * search pages one row per product, so nothing collapses now.
  */
 export type ColourCollapse = {
     /** Ranked rows the collapse examined — this page's pool, never a corpus total. */
@@ -136,17 +153,15 @@ export type ColourCollapse = {
  * Receipt naming which retrieval lane answered, and the colours it actually ran
  * on. The live endpoint always sends it.
  *
- * Two lanes answer two different questions. A ONE-COLOUR query is a CONTAINMENT
- * question — which materials hold a swatch near this colour — and is answered as
- * a bounded OKLab ball over stored palette swatches. A multi-colour query is a
- * SIMILARITY question — which palettes as a whole resemble this palette — and is
- * answered by nearest-neighbour over the palette embedding. The two rank on
- * different geometries, so `colourDistance` on a match means a different thing
- * in each and is NOT comparable across them.
+ * Every live page says `index`: the one search's colour key, the colour's
+ * family on the search index, nearest first by OKLab distance. A palette is
+ * ordered by its first colour, and `droppedColours` names the rest.
+ * `containment` and `palette` appear only on responses stored before the one
+ * search.
  */
 export type ColourLaneReceipt = {
     /** Which lane answered. Widened so a new server lane still type-checks. */
-    lane: OpenEnum<"containment" | "palette">;
+    lane: OpenEnum<"index" | "containment" | "palette">;
     /** Why this lane, in one sentence, for a human reader. */
     reason: string;
     /**
@@ -247,7 +262,11 @@ export type ByColourParams = {
     l?: number;
     a?: number;
     b?: number;
-    /** HARD category filter — display names or taxonomy ids (repeatable). */
+    /**
+     * HARD category filter — display names or taxonomy ids (repeatable). Absent,
+     * the page holds surface materials only (`categoryGate.defaulted`), so
+     * lights, taps and furniture do not answer a colour.
+     */
     category?: string | string[];
     /**
      * HARD brand filter (repeatable) — a canonical brand id, exact brand SLUG
@@ -283,8 +302,16 @@ export type ByColourParams = {
      * drop.
      */
     family?: string;
-    /** Single-colour order; omitted keeps representative browsing order. */
+    /**
+     * Kept so existing callers still parse: every page is ordered nearest first
+     * by the one search's colour key, so both values return the same page.
+     */
     order?: "representative" | "nearest";
+    /**
+     * Order by the colour of an existing Variant: materials the same colour as
+     * this one. Used when no hex, colour or OKLab triple is given.
+     */
+    variantId?: string;
     /** Maximum OKLab distance to each match's reported hex. Single-colour only. */
     maxColourDistance?: number;
     /** Narrow retrieval inside the server query; absent means the whole graph. */

package/by-spec-types.d.ts

@@ -1,18 +1,5 @@
 import type { ValueResolution } from "./catalog-discovery-types.js";
 import type { VerdictCitation } from "./citation-types.js";
-import type { VariantId } from "./identifiers.js";
-/**
- * One criterion a match satisfied, with the trust behind it.
- *
- * `confidence` (0–1) and `sourceBasis` are the CLAIM's provenance, not decoration
- * — quote them wherever the value is quoted. A `null` on either means the trust
- * is unrecorded, which is weaker than a low number, not stronger.
- */
-export type BySpecMatchedCell = {
-    attributeId: string;
-    confidence: number | null;
-    sourceBasis: string | null;
-};
 /**
  * The six states a verdict cell can report — and what each licenses you to say.
  *
@@ -97,19 +84,6 @@ export type BySpecVerdict = {
  * so search-surface code can name it for what it is rather than duplicating it.
  */
 export type MaterialVerdict = BySpecVerdict;
-export type BySpecMatch = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    variant: string;
-    color: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    matched: BySpecMatchedCell[];
-    minConfidence: number | null;
-    verdict: BySpecVerdict;
-};
 /**
  * One criterion the server could not resolve to canonical vocabulary, with the
  * resolver's ranked suggestions for it.
@@ -138,44 +112,3 @@ export type BySpecUnresolvedCriterion = {
     /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
     resolution: ValueResolution;
 };
-/**
- * The find-by-spec envelope — A PAGE, AND NOTHING BUT A PAGE.
- *
- * Read `totalMatches` carefully: despite the name it is the route's own words,
- * "Size of the returned (limited) sample, not the true corpus total" — it is
- * literally `matches.length` under the `limit` you asked for. This surface
- * states NO corpus total, so "N materials meet this specification" is not a
- * claim you can make from one response. Raise `limit`, or say "at least N".
- * `brandsSpanned` is likewise the brand count OF THIS SAMPLE.
- *
- * And check `unresolvedCriteria` BEFORE reading any of that: when it is present
- * the numbers beside it describe a query that never ran.
- */
-export type BySpecResponse = {
-    /** The criteria as parsed — check them before trusting a surprising result. */
-    criteria: {
-        attribute: string;
-        value: string;
-    }[];
-    /** `matches.length`, i.e. THIS SAMPLE under `limit`. Never a corpus total. */
-    totalMatches: number;
-    /** Distinct brands in the returned sample — a lower bound on cross-brand reach. */
-    brandsSpanned: number;
-    /** The sample, photo-first, capped by `limit`. */
-    matches: BySpecMatch[];
-    /**
-     * Present ONLY when a criterion failed exact canonical-vocabulary membership —
-     * and its presence means THE QUERY WAS NEVER RUN. A pre-flight gate short-circuits
-     * before the search, so the rest of the envelope is a placeholder rather than
-     * a finding: `matches` is `[]` and `totalMatches` is `0` because nothing was
-     * searched, not because nothing qualifies. Reporting that zero as "no material
-     * meets this specification" states a fact about the corpus on the strength of
-     * a question nobody asked it.
-     *
-     * Treat these criteria as UNAPPLIED and surface them: retry with a
-     * `resolution.candidates` id (subject to `recommendedAction` — `ambiguous`
-     * means ask, not pick), or say the value could not be resolved. Absent means
-     * every criterion resolved and the query did run.
-     */
-    unresolvedCriteria?: BySpecUnresolvedCriterion[];
-};

package/by-spec-types.js

@@ -1,7 +1,9 @@
-// ── Catalog / spec — find-by-spec wire types ─────────────────────────────────
+// ── Catalog / spec: verdict wire types ──────────────────────────────────────
 //
-// Hand-maintained mirror of the `CatalogBySpecResponse` OpenAPI schema (the
-// source of truth on the wire); the `sdk-openapi-parity` test gates this against
-// the generated spec. Split out of `types.ts` to keep that file under its growth
-// baseline; re-exported from `types.ts` so importers see no change.
+// Hand-maintained mirror of the shared CandidateVerdict and of the pre-flight
+// unresolved-criterion contract. The by-spec ROUTE these once described
+// (`catalog_by_spec`) moved to `list_variants`'s `filters` (MG-2222); the
+// verdict and unresolved-criterion shapes below are independent of that route
+// and stay. Split out of `types.ts` to keep that file under its growth
+// baseline; re-exported from `types.ts`.
 export {};

package/catalog-discovery-types.d.ts

@@ -6,10 +6,6 @@
  * then spend on `mg.bySpec()` or `mg.search({ filters })`.
  */
 import type { OpenEnum } from "./types.js";
-/** Options for resolving a free-text value against one attribute's dictionary. */
-export type ResolveAttributeValueOptions = {
-    limit?: number;
-};
 /**
  * One ranked canonical value candidate. `tier` says HOW it matched, strongest
  * first: `exact_id` > `exact_alias` > `lexical` > `semantic`. A `semantic` hit
@@ -26,8 +22,7 @@ export type ResolveValueCandidate = {
 };
 /**
  * The resolver's verdict on ONE free-text token — the single shape every
- * resolving surface speaks, so a caller learns to read it once. Returned whole
- * by {@link MaterialGraphClient.resolveAttributeValue}, and carried per bad
+ * resolving surface speaks, so a caller learns to read it once. Carried per bad
  * criterion by `bySpec`'s `unresolvedCriteria`.
  *
  * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
@@ -52,16 +47,6 @@ export type ValueResolution = {
     candidates: ResolveValueCandidate[];
     recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
 };
-/** Response from resolving a free-text value against one attribute's dictionary. */
-export type ResolveAttributeValueResponse = {
-    attribute: {
-        id: string;
-        name: string;
-        dictionaryId: string;
-    };
-    /** The verdict on `q`. Read `recommendedAction` — see {@link ValueResolution}. */
-    resolution: ValueResolution;
-};
 /** Options for searching registry attributes and value-dictionary terms together. */
 export type VocabularySearchOptions = {
     limit?: number;

package/catalogue-client.d.ts

@@ -1,45 +1,26 @@
-import type { BrandMostSampledResponse } from "./brand-most-sampled-types.js";
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
-import type { CompareInput, CompareResponse } from "./compare-types.js";
-import type { CreateCorrectionInput, CorrectionResponse, CorrectionsListResponse } from "./correction-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
-import type { IdentifySelectedPageInput, IdentifySelectedPageResult } from "./identify-types.js";
-import type { MatchRejection, MatchRejectionList, RejectMatchResultInput } from "./match-rejection-types.js";
+import type { IdentifyResponse, IdentifyVariantInput } from "./identify-types.js";
 import type { SamplizeCatalogueOptions, SamplizeCataloguePage } from "./samplize-catalogue-types.js";
 import type { SamplizeColorVecCache } from "./samplize-colorvec.js";
 /** Catalogue publication operations inherited by the public SDK client. */
 export declare class CatalogueClient {
     #private;
     protected constructor(transport: HttpTransport);
-    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
-    brandMostSampled(brandId: string, options?: {
-        limit?: number;
-    }, signal?: AbortSignal): Promise<BrandMostSampledResponse>;
-    /** Compare canonical Variants without searching or ranking them. */
-    compare(input: CompareInput, signal?: AbortSignal): Promise<CompareResponse>;
-    /** Submit confirmed caller-authored review work; never changes accepted truth. */
-    createCorrection(input: CreateCorrectionInput, options: {
-        idempotencyKey: string;
-        signal?: AbortSignal;
-    }): Promise<CorrectionResponse>;
-    getCorrection(correctionId: string, signal?: AbortSignal): Promise<CorrectionResponse>;
-    listCorrections(input?: {
-        cursor?: string;
-        limit?: number;
-    }, signal?: AbortSignal): Promise<CorrectionsListResponse>;
     /**
-     * Record "not this" on one result a match showed, against the response it
-     * came from. `responseId` is that response's `attribution.responseId`; the
-     * call needs the same key the match was made with. Repeating a rejection
-     * returns the original receipt. This judges the match ranking and is never a
-     * catalogue correction - wrong product facts go through `createCorrection`.
+     * THE QUESTION: "what does this manufacturer page or code resolve to in the
+     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
+     * {@link CatalogueClient.brands} - inherited by {@link MaterialGraphClient})
+     * when there is no page to read.
+     *
+     * Exact and scoreless: a sibling colourway, a similar image or a brand match
+     * alone never identifies a variant. Read `data.outcome` - `identified` names
+     * an exact stored variant, `placed` an exact brand with no variant match,
+     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
+     * never a guess. The submitted URL is never persisted.
      */
-    rejectMatchResult(responseId: string, input: RejectMatchResultInput, signal?: AbortSignal): Promise<MatchRejection>;
-    /** Read one match response back with every rejection recorded against it. */
-    matchRejections(responseId: string, signal?: AbortSignal): Promise<MatchRejectionList>;
-    /** Identify the canonical graph subject for one explicitly selected page. */
-    identify(input: IdentifySelectedPageInput, signal?: AbortSignal): Promise<IdentifySelectedPageResult>;
+    identify(input: IdentifyVariantInput, signal?: AbortSignal): Promise<IdentifyResponse>;
     /** Complete producer-owned vectors and classifications for portable colour matching. */
     samplizeColorVecCache(sourceVersion: string, signal?: AbortSignal): Promise<SamplizeColorVecCache>;
     /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */

package/catalogue-client.js

@@ -5,54 +5,18 @@ export class CatalogueClient {
     constructor(transport) {
         this.#transport = transport;
     }
-    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
-    async brandMostSampled(brandId, options = {}, signal) {
-        return await this.#transport.requestJson(resolveOperation("brands.most_sampled"), { query: { brandId, ...options }, signal });
-    }
-    /** Compare canonical Variants without searching or ranking them. */
-    async compare(input, signal) {
-        return await this.#transport.requestJson(resolveOperation("retrieval.compare"), {
-            body: input,
-            signal,
-        });
-    }
-    /** Submit confirmed caller-authored review work; never changes accepted truth. */
-    async createCorrection(input, options) {
-        if (!/^[\u0021-\u007E]{1,200}$/u.test(options.idempotencyKey)) {
-            throw new Error("A valid Idempotency-Key is required for Correction submission.");
-        }
-        return await this.#transport.requestJson(resolveOperation("corrections.create"), {
-            body: input,
-            ...options,
-        });
-    }
-    async getCorrection(correctionId, signal) {
-        return await this.#transport.requestJson(resolveOperation("corrections.get"), {
-            pathParams: { correctionId },
-            signal,
-        });
-    }
-    async listCorrections(input = {}, signal) {
-        return await this.#transport.requestJson(resolveOperation("corrections.list"), {
-            query: input,
-            signal,
-        });
-    }
     /**
-     * Record "not this" on one result a match showed, against the response it
-     * came from. `responseId` is that response's `attribution.responseId`; the
-     * call needs the same key the match was made with. Repeating a rejection
-     * returns the original receipt. This judges the match ranking and is never a
-     * catalogue correction - wrong product facts go through `createCorrection`.
+     * THE QUESTION: "what does this manufacturer page or code resolve to in the
+     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
+     * {@link CatalogueClient.brands} - inherited by {@link MaterialGraphClient})
+     * when there is no page to read.
+     *
+     * Exact and scoreless: a sibling colourway, a similar image or a brand match
+     * alone never identifies a variant. Read `data.outcome` - `identified` names
+     * an exact stored variant, `placed` an exact brand with no variant match,
+     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
+     * never a guess. The submitted URL is never persisted.
      */
-    async rejectMatchResult(responseId, input, signal) {
-        return await this.#transport.requestJson(resolveOperation("reject_match_result"), { body: input, pathParams: { responseId }, signal });
-    }
-    /** Read one match response back with every rejection recorded against it. */
-    async matchRejections(responseId, signal) {
-        return await this.#transport.requestJson(resolveOperation("list_match_rejections"), { pathParams: { responseId }, signal });
-    }
-    /** Identify the canonical graph subject for one explicitly selected page. */
     async identify(input, signal) {
         return await this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });
     }

package/catalogue-types.d.ts

@@ -57,6 +57,43 @@ export interface CatalogueReference {
     status: "verified";
     isPrimary: boolean;
 }
+/**
+ * Why a known variant has no verified reference. None of these says the
+ * product is missing from the printed book; nobody records how many of a
+ * brand's products a publication contains.
+ */
+export type CatalogueReferenceAbsenceReason = 
+/**
+ * The registry retains no publication for the variant's brand. It says
+ * nothing about whether the maker publishes one.
+ */
+"no_publication_on_record"
+/** The edition is known but its document is not retained. */
+ | "publication_source_unavailable"
+/** The document is retained but no page has been reviewed. */
+ | "publication_not_reviewed"
+/** Pages were reviewed and this product is not among the references yet. */
+ | "product_not_yet_referenced";
+/** The brand publication a `no_verified_reference` result was judged against. */
+export type CatalogueReferencePublication = {
+    brand: {
+        id: string;
+        name: string;
+    };
+    catalogue: {
+        id: string;
+        title: string;
+    };
+    /** Null when the edition's document is not retained. */
+    documentId: string | null;
+    edition: {
+        id: string;
+        label: string;
+        title?: string;
+    };
+    /** Reviewed references the publication holds; present only when its pages were reviewed. */
+    referencedProductCount?: number;
+};
 export type CatalogueReferenceResult = {
     variantId: string;
     status: "verified";
@@ -64,6 +101,9 @@ export type CatalogueReferenceResult = {
 } | {
     variantId: string;
     status: "no_verified_reference";
+    reason: CatalogueReferenceAbsenceReason;
+    /** Absent only when `reason` is `no_publication_on_record`. */
+    publication?: CatalogueReferencePublication;
 } | {
     variantId: string;
     status: "unresolved_variant";