@instruments/materialgraph 0.33.0 → 0.35.0

package/association-types.d.ts

@@ -1,23 +1,23 @@
+import type { Cursor, VariantId } from "./identifiers.js";
+import type { ProductTypeReceipt } from "./material-types.js";
 /**
  * Wire types for the DECLARED FF&E association reads
  * (`GET /api/v1/associated/finishes`, `GET /api/v1/associated/products`).
  *
- * THE AUTHORITY ON "THE MANUFACTURER SAID SO". Every other relationship lens in
+ * THE AUTHORITY ON "THE BRAND SAID SO". Every other relationship lens in
  * this SDK is inference: `pairings` reads order and board activity, `search
  * ({ similarTo })` reads appearance. These two reads are the only ones carrying
- * a compatibility the manufacturer themselves enumerated — this fabric is
+ * a compatibility the brand itself enumerated - this fabric is
  * genuinely available on this chair — and the shapes deliberately share no field
  * 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";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 /**
  * Why an association is believed.
  *
  * Every field is ALWAYS present. `confidence` is a FIXED convention value (0.9)
- * that the ingest writes on every manufacturer-declared edge — it is not a
+ * that the ingest writes on every brand-declared edge - it is not a
  * measurement, it does not vary between edges, and it must never be shown as a
  * score or used to rank. Declared associations carry no ranking at all: that is
  * the point of them.
@@ -25,9 +25,9 @@ import type { ProductTypeReceipt } from "./material-types.js";
 export type DeclaredProvenance = {
     /** The stored convention value (0.9 today). Never a per-edge measurement. */
     confidence: number;
-    /** The manufacturer enumerated this association in their own catalog data. */
+    /** The brand enumerated this association in its own catalog data. */
     basis: "manufacturer_declared";
-    /** The provenance recorded on the edge — the manufacturer catalog feed. */
+    /** The provenance recorded on the edge - the brand catalog feed. */
     source: "warehouse";
 };
 /** The material the question was asked about, resolved to its identity. */
@@ -46,7 +46,7 @@ export type DeclaredAssociation = {
     variantName: string | null;
     /** The role played by this endpoint of the declared edge. */
     role: "finish" | "product";
-    /** The directed relationship asserted by the manufacturer. */
+    /** The directed relationship asserted by the brand. */
     relation: "applicable_finish";
     /** Accepted sampleability when known; absent means unknown. */
     sampleable?: boolean;
@@ -63,7 +63,7 @@ export type DeclaredAssociation = {
      * The eligible variants of this association's product, the set `listVariants`
      * pages. Absent when the product has no eligible variant.
      */
-    colourwayCount?: number;
+    colorwayCount?: number;
 };
 /**
  * One page of declared associations.
@@ -101,7 +101,7 @@ export type AssociatedOptions = {
      * carrying a Material Bank id; absent or `all` is the whole declared set.
      * Membership does not establish sampleability; use `sampleableOnly` for that.
      */
-    corpusScope?: CorpusScope;
+    searchCatalogueSubset?: SearchCatalogueSubset;
     /** Return only associations whose effective sampleability is true. */
     sampleableOnly?: boolean;
     /**

package/associations-client.d.ts

@@ -5,9 +5,9 @@
  * `.associatedProducts` delegate here; the contract lives in this file.
  *
  * DECLARED IS NOT INFERRED — the rule this whole lens exists to make
- * unmissable. These two reads return compatibility the MANUFACTURER stated
+ * unmissable. These two reads return compatibility the BRAND stated
  * ("this fabric is available on this chair"); `pairings()` returns
- * companionship the graph INFERRED from orders, boards and colour. The two
+ * companionship the graph INFERRED from orders, boards and color. The two
  * response shapes share no field, on purpose: render them as separate
  * sections, never concatenate them, and never describe a pairing as
  * "available on".
@@ -17,12 +17,12 @@ import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 /**
  * THE QUESTION: "what finishes can I get on THIS chair?" — the fabrics,
- * leathers and surfaces the MANUFACTURER declares are available on a product
+ * leathers and surfaces the BRAND declares are available on a product
  * variant (GET `/api/v1/associated/finishes`).
  *
  * Instead use `pairings()` for what merely GOES WITH something (inference from
- * orders, boards and colour) and `siblings()` for the same product in another
- * colourway. These are the only relationships the manufacturer themselves
+ * orders, boards and color) and `listVariants()` for the same product in another
+ * colorway. These are the only relationships the brand itself
  * stated: `kind` is always `"declared_association"`, and the shape shares no
  * field with a pairing — see the module docblock for why that matters.
  *
@@ -36,7 +36,7 @@ import type { VariantId } from "./identifiers.js";
 export declare const declaredFinishes: (transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal) => Promise<DeclaredAssociationsResponse>;
 /**
  * THE QUESTION: "what furniture takes THIS fabric?" — the products the
- * MANUFACTURER declares a finish variant is available on (GET
+ * BRAND declares a finish variant is available on (GET
  * `/api/v1/associated/products`).
  *
  * The exact reverse of {@link declaredFinishes} over one stored relationship,
@@ -49,5 +49,5 @@ export declare const declaredFinishes: (transport: HttpTransport, variantId: Var
  * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
  */
 export declare const declaredProducts: (transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal) => Promise<DeclaredAssociationsResponse>;
-/** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
+/** Read brand-declared applicability without collapsing Product/Variant default attribute level. */
 export declare const applicability: (transport: HttpTransport, options: ApplicabilityOptions, signal?: AbortSignal) => Promise<ApplicabilityResponse>;

package/associations-client.js

@@ -1,12 +1,12 @@
 import { resolveOperation } from "./operations.js";
 /**
  * THE QUESTION: "what finishes can I get on THIS chair?" — the fabrics,
- * leathers and surfaces the MANUFACTURER declares are available on a product
+ * leathers and surfaces the BRAND declares are available on a product
  * variant (GET `/api/v1/associated/finishes`).
  *
  * Instead use `pairings()` for what merely GOES WITH something (inference from
- * orders, boards and colour) and `siblings()` for the same product in another
- * colourway. These are the only relationships the manufacturer themselves
+ * orders, boards and color) and `listVariants()` for the same product in another
+ * colorway. These are the only relationships the brand itself
  * stated: `kind` is always `"declared_association"`, and the shape shares no
  * field with a pairing — see the module docblock for why that matters.
  *
@@ -20,7 +20,7 @@ import { resolveOperation } from "./operations.js";
 export const declaredFinishes = async (transport, variantId, options, signal) => await transport.requestJson(resolveOperation("list_associated_finishes"), { query: { variantId, ...options }, signal });
 /**
  * THE QUESTION: "what furniture takes THIS fabric?" — the products the
- * MANUFACTURER declares a finish variant is available on (GET
+ * BRAND declares a finish variant is available on (GET
  * `/api/v1/associated/products`).
  *
  * The exact reverse of {@link declaredFinishes} over one stored relationship,
@@ -33,5 +33,5 @@ export const declaredFinishes = async (transport, variantId, options, signal) =>
  * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
  */
 export const declaredProducts = async (transport, variantId, options, signal) => await transport.requestJson(resolveOperation("list_associated_products"), { query: { variantId, ...options }, signal });
-/** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
+/** Read brand-declared applicability without collapsing Product/Variant default attribute level. */
 export const applicability = async (transport, options, signal) => await transport.requestJson(resolveOperation("get_applicability"), { query: options, signal });

package/brand-types.d.ts

@@ -1,52 +1,48 @@
 /**
- * Query options and wire types for the canonical brands collection
- * (`GET /api/v1/brands`).
- *
- * 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.
+ * Query options and wire types for the canonical brand list
+ * (`GET /api/v1/brands`), the same page and the same input the MCP
+ * `list_brands` tool and the `mg brand list` command take.
  */
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-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.
+     * A brand name, alias or misspelling, e.g. `"Kvadrat"`. Omit to browse the
+     * list by name. Every brand the text matches comes back, so an ambiguous name
+     * is yours to disambiguate.
      */
-    corpusScope?: CorpusScope;
-    /** Fuzzy name filter. Omit for the whole collection. */
-    q?: string;
-    /** Page size. Never a bound on the collection. */
+    query?: string;
+    /**
+     * A category id from `categories.list()`. Keeps brands with at least one
+     * eligible variant in that category scope.
+     */
+    categoryId?: string;
+    /**
+     * Keeps brands with at least one eligible variant in this corpus, by the same
+     * per-variant test `listVariants()` applies. Absent or `"all"` is every brand
+     * that carries materials.
+     */
+    searchCatalogueSubset?: SearchCatalogueSubset;
+    /** Page size, 1 to 50. Never a bound on the list. */
     limit?: number;
-    /** Row offset for the next page. Paired with `meta.hasMore`. */
-    offset?: number;
+    /** The previous page's `pageInfo.endCursor`, with the same `query`, `categoryId` and `searchCatalogueSubset`. */
+    cursor?: string;
 };
-export type BrandCatalogListItem = {
-    id: string;
-    slug: string;
-    name: string;
-    primaryMarketSegment: string;
-    homepageUrl: string | null;
-    /** Products INGESTED into MaterialGraph, not the brand's own catalog size. */
-    productCount: number;
-    /** Variants ingested into MaterialGraph. A coverage figure, not a claim about the brand. */
-    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[];
+export type BrandItem = {
     /**
-     * A PAGE IS NOT A CORPUS, spelled out:
-     *  - `count` — items on THIS page.
-     *  - `total` — brands matching the query overall. The number to quote.
-     *  - `limit` / `offset` — the window that produced this page.
-     *  - `hasMore` — whether another page exists. Keep walking while true.
+     * The brand's slug: the value `listVariants()`' `brand` filter and
+     * `resolveVariant()`' `brandId` take. Never a display name.
      */
-    meta: {
-        count: number;
-        total: number;
-        limit: number;
-        offset: number;
-        hasMore: boolean;
+    brandId: string;
+    name: string;
+    /** The brand's homepage, or null when none is on record. */
+    website: string | null;
+};
+export type ListBrandsPage = {
+    /** THIS PAGE. Follow `pageInfo.endCursor` for the rest; a page is not a total. */
+    items: BrandItem[];
+    pageInfo: {
+        /** Null on the last page. */
+        endCursor: string | null;
+        hasNextPage: boolean;
     };
 };

package/brand-types.js

@@ -1,8 +1,6 @@
 /**
- * Query options and wire types for the canonical brands collection
- * (`GET /api/v1/brands`).
- *
- * 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.
+ * Query options and wire types for the canonical brand list
+ * (`GET /api/v1/brands`), the same page and the same input the MCP
+ * `list_brands` tool and the `mg brand list` command take.
  */
 export {};

package/brands-client.d.ts

@@ -1,17 +1,30 @@
 /**
- * The BRAND lens: the catalogue collection, as a thin wrapper over the shared
+ * The BRAND lens: the brand list, 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 this read returns is
- * coverage — what MaterialGraph has ingested — and never a claim about how
- * many products the brand sells.
+ * A brand is a COMPANY, not a catalogue. The list says which brands have
+ * eligible materials in the scope asked for, and nothing about how many
+ * products a brand sells.
  */
-import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
+import type { BrandsOptions, ListBrandsPage } from "./brand-types.js";
 import type { HttpTransport } from "./http-transport.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.
+ * THE QUESTION: "which brands are in here?" Cursor-paged like every other
+ * list: follow `pageInfo.endCursor` with the same options until `hasNextPage`
+ * is false.
+ *
+ * To list one brand's materials, pass its `brandId` (its slug, never a display
+ * name) as the `brand` filter value:
+ *
+ * @example
+ * const { items } = await mg.brands({ query: "Autex", searchCatalogueSubset: "materialBankNaOrderable" });
+ * const brand = items.find((b) => b.brandId === "autex-acoustics");
+ * if (!brand) throw new Error("autex-acoustics is not on this page");
+ * const page = await mg.listVariants({
+ *   searchCatalogueSubset: "materialBankNaOrderable",
+ *   filters: { terms: [{ field: "brand", op: "in", values: [brand.brandId] }] },
+ *   limit: 3,
+ * });
  */
-export declare const listBrands: (transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal) => Promise<BrandCatalogListPage>;
+export declare const listBrands: (transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal) => Promise<ListBrandsPage>;

package/brands-client.js

@@ -1,15 +1,29 @@
 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.
+ * THE QUESTION: "which brands are in here?" Cursor-paged like every other
+ * list: follow `pageInfo.endCursor` with the same options until `hasNextPage`
+ * is false.
+ *
+ * To list one brand's materials, pass its `brandId` (its slug, never a display
+ * name) as the `brand` filter value:
+ *
+ * @example
+ * const { items } = await mg.brands({ query: "Autex", searchCatalogueSubset: "materialBankNaOrderable" });
+ * const brand = items.find((b) => b.brandId === "autex-acoustics");
+ * if (!brand) throw new Error("autex-acoustics is not on this page");
+ * const page = await mg.listVariants({
+ *   searchCatalogueSubset: "materialBankNaOrderable",
+ *   filters: { terms: [{ field: "brand", op: "in", values: [brand.brandId] }] },
+ *   limit: 3,
+ * });
  */
 export const listBrands = async (transport, options = {}, signal) => await transport.requestJson(resolveOperation("list_brands"), {
     query: {
-        corpusScope: options.corpusScope,
+        categoryId: options.categoryId,
+        cursor: options.cursor,
         limit: options.limit,
-        offset: options.offset,
-        q: options.q,
+        query: options.query,
+        searchCatalogueSubset: options.searchCatalogueSubset,
     },
     signal,
 });

package/by-spec-types.d.ts

@@ -51,7 +51,7 @@ export type BySpecVerdictCell = {
     /** Trust in `value`, 0–1. Null = unrecorded, which is weaker than a low score. */
     confidence: number | null;
     /** Where `value` came from (`tested` > `declared` > `catalog_feed` > `derived`). */
-    sourceBasis: string | null;
+    valueOrigin: string | null;
     /**
      * Why an `unverified` cell missed the bar; null otherwise.
      *  - `below_confidence` — the value is real but scored under the floor.

package/catalog-discovery-types.d.ts

@@ -3,7 +3,7 @@
  *
  * THE LENS: turning a HUMAN PHRASE into the canonical vocabulary the spec
  * surfaces accept. Nothing here returns materials — it returns the tokens you
- * then spend on `mg.bySpec()` or `mg.search({ filters })`.
+ * then spend on `mg.listVariants({ filters })`.
  */
 import type { OpenEnum } from "./types.js";
 /**
@@ -17,13 +17,13 @@ export type ResolveValueCandidate = {
     dictionaryId?: string;
     score: number;
     tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
-    /** Present only for a colour_family candidate resolved via the colorscope fallback. */
+    /** Present only for a color_family candidate resolved via the colorscope fallback. */
     via?: OpenEnum<"colorscope">;
 };
 /**
  * The resolver's verdict on ONE free-text token — the single shape every
  * resolving surface speaks, so a caller learns to read it once. Carried per bad
- * criterion by `bySpec`'s `unresolvedCriteria`.
+ * criterion by `BySpecUnresolvedCriterion`, a shape no current method returns.
  *
  * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
  * `candidates` list means the phrase genuinely matched several terms — taking

package/catalogue-client.d.ts

@@ -3,71 +3,23 @@ import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 import type { ResolveVariantInput, ResolveVariantOutput } from "./resolve-variant-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);
     /**
-     * THE QUESTION: "what does this manufacturer page or code resolve to in the
+     * THE QUESTION: "what does this brand 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
+     * Exact and scoreless: a sibling colorway, a similar image or a brand match
      * alone never identifies a variant. Read `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.
      */
     resolveVariant(input: ResolveVariantInput, signal?: AbortSignal): Promise<ResolveVariantOutput>;
-    /** 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. */
-    samplizeCatalogueSearch(input: {
-        palette?: {
-            hex: string;
-            proportion: number;
-        }[];
-        query?: string;
-        reference?: string;
-        direction?: "similar" | "lighter" | "darker" | "muted";
-        lightnessMin?: number;
-        lightnessMax?: number;
-        temperatureMin?: number;
-        temperatureMax?: number;
-        family?: string[];
-        lightness?: string[];
-        intensity?: string[];
-        brand?: string[];
-        sourceVersion: string;
-        limit?: number;
-    }, signal?: AbortSignal): Promise<{
-        target?: {
-            ref: string;
-            hex: string;
-            name?: string;
-            source: string;
-            confidence?: number;
-        };
-        embeddingVersion?: string;
-        rankingVersion?: string;
-        dictionaryVersion?: string;
-        eligibleCount?: number;
-        groups?: {
-            hex: string;
-            proportion: number;
-            quota: number;
-            ids: string[];
-            shortfall: number;
-        }[];
-        ids: string[];
-        limited: boolean;
-        sourceVersion: string;
-        counts: Record<string, Record<string, number>>;
-        countBasis: string;
-        basis: string;
-    }>;
     /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
     samplizeCatalogue(options?: SamplizeCatalogueOptions, signal?: AbortSignal): Promise<SamplizeCataloguePage>;
     /**

package/catalogue-client.js

@@ -6,12 +6,12 @@ export class CatalogueClient {
         this.#transport = transport;
     }
     /**
-     * THE QUESTION: "what does this manufacturer page or code resolve to in the
+     * THE QUESTION: "what does this brand 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
+     * Exact and scoreless: a sibling colorway, a similar image or a brand match
      * alone never identifies a variant. Read `outcome` - `identified` names
      * an exact stored variant, `placed` an exact brand with no variant match,
      * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
@@ -20,14 +20,6 @@ export class CatalogueClient {
     async resolveVariant(input, signal) {
         return await this.#transport.requestJson(resolveOperation("resolve_variant"), { body: input, signal });
     }
-    /** Complete producer-owned vectors and classifications for portable colour matching. */
-    async samplizeColorVecCache(sourceVersion, signal) {
-        return await this.#transport.requestJson(resolveOperation("samplize_colorvec_cache"), { query: { sourceVersion }, signal });
-    }
-    /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
-    async samplizeCatalogueSearch(input, signal) {
-        return await this.#transport.requestJson(resolveOperation("samplize_catalogue_search"), { body: input, signal });
-    }
     /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
     async samplizeCatalogue(options = {}, signal) {
         return await this.#transport.requestJson(resolveOperation("samplize_catalogue_products"), { query: { ...options }, signal });

package/catalogue-types.d.ts

@@ -240,7 +240,7 @@ export interface CatalogAvailableReceipt {
             algorithm: "sha256";
             value: string;
         };
-        sourceBasis: "brand_supplied";
+        valueOrigin: "brand_supplied";
         retainedUrl: string;
         status: "retained";
     };

package/categories-client.d.ts

@@ -2,8 +2,7 @@
  * The category-tree surface, namespaced as `mg.categories` (MG-2226). Replaces
  * `taxonomy()` / `GET /api/v1/taxonomy/categories`, retired with no shim.
  *
- * `list()` pages the tree (roots, one node's children, or a name/meaning
- * search), and `get(id)` reads one node in full: its place, the names and
+ * `list()` pages the tree (roots, one node's children, or a name search), and `get(id)` reads one node in full: its place, the names and
  * phrases that find it, and the canonical taxonomy concepts it relates to.
  *
  * A category id is a TREE KEY, never a canonical `product_category` value,
@@ -14,8 +13,7 @@
  *
  * The namespace holds no transport of its own: the client hands it a bound
  * `get` callback, so auth, rate-limit accounting and error shaping stay in
- * exactly one place. `mg.browse` and `mg.codes` set the precedent for a
- * namespace over flat methods.
+ * exactly one place.
  */
 import type { CategoriesGetResult, CategoriesListInput, CategoriesListResult } from "./category-types.js";
 import type { QueryParams } from "./http-transport.js";
@@ -31,7 +29,7 @@ export declare class CategoriesClient {
      * One bounded page of the category tree (GET `/api/v1/categories`). With
      * nothing set, the top-level categories; `parentId` alone, that category's
      * direct children; `query`, every category (or only `parentId` and
-     * everything under it) by name, phrase, near spelling or meaning: the
+     * everything under it) by name, phrase or near spelling: the
      * first method that finds anything wins, and every match it finds is
      * returned, ranked by method then distance.
      *

package/categories-client.js

@@ -7,7 +7,7 @@ export class CategoriesClient {
      * One bounded page of the category tree (GET `/api/v1/categories`). With
      * nothing set, the top-level categories; `parentId` alone, that category's
      * direct children; `query`, every category (or only `parentId` and
-     * everything under it) by name, phrase, near spelling or meaning: the
+     * everything under it) by name, phrase or near spelling: the
      * first method that finds anything wins, and every match it finds is
      * returned, ranked by method then distance.
      *

package/category-types.d.ts

@@ -7,12 +7,8 @@
  * `getCategoryInputSchema` / `getCategoryResultSchema` Zod contracts the routes
  * are built from.
  *
- * A category id is a TREE KEY (a product-type group or a product type, e.g.
- * `"tile_surfaces"`), never a canonical `product_category` value (a termId such
- * as `"wall_panel"`). The two vocabularies look alike and are not
- * interchangeable, and a termId passed where an id belongs is refused, naming
- * which it is. `get(id).productCategory` is where a category relates to its
- * termIds; category filters elsewhere in the SDK take the id, never the termId.
+ * Category ids identify original Material Bank nodes. Reviewed equivalent nodes
+ * retain their stable ids; every node carries its exact source path.
  */
 import type { OpenEnum } from "./types.js";
 /** A category named by id, as in `ancestors` and `children`. */
@@ -20,32 +16,29 @@ export type CategoryRef = {
     id: string;
     name: string;
 };
-export type CategoryKind = OpenEnum<"group" | "product_type">;
-/**
- * How one item matched a `query`: `exact` (the id or a name), `alias` (a
- * phrase that names the category), `fuzzy` (a near spelling) or `vector`
- * (similar meaning, from the served vocabulary embeddings). Earlier methods
- * are surer; a page holds matches from one method only.
- */
+export type CategoryKind = OpenEnum<"category">;
+/** How a query matched source category names or exact paths through the lexical matcher. */
 export type CategoryMatch = {
-    /** The name, former name or phrase that matched. Null for `vector`, which compares meaning. */
+    /** The name or source path that matched. */
     matchedText: string | null;
-    method: OpenEnum<"exact" | "alias" | "fuzzy" | "vector">;
+    method: OpenEnum<"exact" | "alias" | "fuzzy">;
 };
 /**
  * One item on a `categories.list` page: what picks the next call. `get(id)`
- * has the description, ancestors, children, names and concepts.
+ * has the source path, depth, ancestors and children.
  */
 export type CategoryItem = {
     /** Whether `categories.list({ parentId: this.id })` lists anything. */
     hasChildren: boolean;
-    /** A tree key, not a canonical `product_category` value. */
+    /** A source category identity, also used in product_category memberships. */
     id: string;
     /** Present only when the page answers a `query`. */
     match?: CategoryMatch;
     name: string;
     /** The parent category's id, or null for a top-level category. */
     parentId: string | null;
+    path: string;
+    depth: number;
 };
 export type CategoriesPageInfo = {
     /** Pass back as `cursor` with the same `query` and `parentId` for the next page. */
@@ -69,13 +62,7 @@ export type CategoriesListResult = {
     notice?: string;
     pageInfo: CategoriesPageInfo;
 };
-/**
- * One canonical taxonomy concept a category relates to. `termId` is the value
- * a record's `product_category` attribute holds, not the category id. `match`
- * is present only for product types: `exact` (the same thing), `close`,
- * `broad` (the concept contains this type) or `narrow` (the concept is one
- * kind within this type).
- */
+/** Independent semantic mapping metadata; it does not assert source category membership. */
 export type CategoryConcept = {
     label: string;
     match?: OpenEnum<"exact" | "close" | "broad" | "narrow">;
@@ -84,10 +71,7 @@ export type CategoryConcept = {
 };
 export type CategoryProductCategory = {
     concepts: CategoryConcept[];
-    /**
-     * The `product_category` value a record holds when the category alone
-     * decides it. Null for groups and for `conditional` or `unmapped` types.
-     */
+    /** Legacy semantic mapping value, separate from source product_category enum[] values. */
     recordValue: string | null;
     /**
      * `mapped`: the category fixes its canonical concepts. `conditional`: each
@@ -106,9 +90,12 @@ export type CategoriesGetResult = {
     description: string | null;
     /** Names this category carried before a rename; they still find it. */
     formerNames: string[];
-    /** A tree key, not a canonical `product_category` value. */
+    /** A source category identity, also used in product_category memberships. */
     id: string;
     kind: CategoryKind;
     name: string;
-    productCategory: CategoryProductCategory;
+    /** Complete original Material Bank path; reviewed equivalents may retain a different stable id. */
+    path: string;
+    /** Zero-based depth in the source hierarchy. */
+    depth: number;
 };

package/citation-types.d.ts

@@ -8,7 +8,7 @@ export type ResolvedVerdictCitation = {
     citationId: string;
     sourceType: string;
     source: {
-        kind: "source_record" | "source_material" | "source_fact" | "url" | "asset" | "download" | "manual_note" | "agent_output";
+        kind: "source_record" | "source_material" | "source_statement" | "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;
@@ -16,7 +16,7 @@ export type ResolvedVerdictCitation = {
         /** Same-origin public asset proxy path when retained bytes are available. */
         publicPath?: string;
         sourceId?: string;
-        sourceFactId?: string;
+        sourceStatementId?: string;
         sourceAssetId?: string;
         sourceDownloadId?: string;
         locator?: {