@instruments/materialgraph 0.6.0 → 0.6.1

package/brand-types.d.ts

@@ -1,7 +1,16 @@
-/** Query options and wire types for the canonical brands collection. */
+/**
+ * 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.
+ */
 export interface BrandsOptions {
+    /** Fuzzy name filter. Omit for the whole collection. */
     q?: string;
+    /** Page size. Never a bound on the collection. */
     limit?: number;
+    /** Row offset for the next page. Paired with `meta.hasMore`. */
     offset?: number;
 }
 export interface BrandCatalogListItem {
@@ -10,11 +19,21 @@ export interface BrandCatalogListItem {
     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 interface BrandCatalogListPage {
+    /** THIS PAGE. Its length is `meta.count`, never `meta.total`. */
     items: BrandCatalogListItem[];
+    /**
+     * 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.
+     */
     meta: {
         count: number;
         total: number;

package/brand-types.js

@@ -1 +1,8 @@
+/**
+ * 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.
+ */
 export {};

package/by-spec-types.d.ts

@@ -1,9 +1,33 @@
+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 interface BySpecMatchedCell {
     attributeId: string;
     confidence: number | null;
     sourceBasis: string | null;
 }
-/** The six states a verdict cell can report; open per the response-enum policy. */
+/**
+ * The six states a verdict cell can report — and what each licenses you to say.
+ *
+ *  - `matched` — an accepted value satisfies the criterion. Claimable.
+ *  - `deviated` — an accepted value is directionally off, and `deviation` names
+ *    by how much. Claimable WITH the deviation, never as a plain pass.
+ *  - `failed` — an accepted value exists and does not satisfy the criterion. A
+ *    real negative: this material does not meet it.
+ *  - `unverified` — a real value exists but did not clear the trust bar
+ *    (`trustGap` says which). NOT a failure and NOT a pass — say "on record but
+ *    unverified".
+ *  - `missing` — no accepted value to evaluate. UNKNOWN, never "does not have
+ *    it". This is the absent-is-not-false state.
+ *  - `not_evaluated` — the engine did not check. Says nothing about the material.
+ *
+ * Only `failed` supports a negative claim. `missing` and `unverified` do not.
+ */
 export type BySpecVerdictState = "matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated";
 /**
  * One cell of a match's report card — how a single requested criterion scored.
@@ -27,6 +51,7 @@ export interface BySpecVerdictCell {
         source: "variant" | "vector";
         variantId: string | null;
     };
+    /** The candidate's own accepted value, or null when there is none to report. */
     value: string | null;
     deviation: {
         direction: "above" | "below" | "other";
@@ -34,11 +59,30 @@ export interface BySpecVerdictCell {
         unit: string | null;
         label: string;
     } | null;
+    /** 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;
+    /**
+     * Why an `unverified` cell missed the bar; null otherwise.
+     *  - `below_confidence` — the value is real but scored under the floor.
+     *  - `basis_unmet` — the value's source is weaker than the criterion demanded.
+     *  - `proposed` — the value is awaiting acceptance and is not yet on record.
+     */
     trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
 }
-/** A match's full report card: every cell, the rolled-up grade, weakest confidence. */
+/**
+ * A match's full report card: every cell, the rolled-up grade, weakest confidence.
+ *
+ * `grade` folds `cells` and is deliberately conservative:
+ *  - `meets_all` — every REQUIRED cell is `matched`. All-green, nothing else.
+ *  - `close` — no required cell `failed`, but something is `deviated`,
+ *    `unverified` or `missing`. Present the gap, never round it up to a pass.
+ *  - `hard_no` — at least one required cell `failed` on a real value.
+ *
+ * `minConfidence` is the WEAKEST cell's confidence — the honest ceiling on the
+ * whole card, not an average. Quote it alongside the grade.
+ */
 export interface BySpecVerdict {
     cells: BySpecVerdictCell[];
     grade: "meets_all" | "close" | "hard_no";
@@ -51,7 +95,8 @@ export interface BySpecVerdict {
  */
 export type MaterialVerdict = BySpecVerdict;
 export interface BySpecMatch {
-    variantId: string;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
     brand: string;
     product: string;
     variant: string;
@@ -62,12 +107,26 @@ export interface BySpecMatch {
     minConfidence: number | null;
     verdict: BySpecVerdict;
 }
+/**
+ * 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.
+ */
 export interface BySpecResponse {
+    /** The criteria as parsed — check them before trusting a surprising result. */
     criteria: Array<{
         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[];
 }

package/catalog-discovery-types.d.ts

@@ -1,10 +1,20 @@
-/** Catalog value-discovery contracts mirrored from the canonical HTTP routes. */
+/**
+ * Catalog value-discovery contracts mirrored from the canonical HTTP routes.
+ *
+ * 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 })`.
+ */
 import type { OpenEnum } from "./types.js";
 /** Options for resolving a free-text value against one attribute's dictionary. */
 export interface ResolveAttributeValueOptions {
     limit?: number;
 }
-/** One ranked canonical value candidate. */
+/**
+ * One ranked canonical value candidate. `tier` says HOW it matched, strongest
+ * first: `exact_id` > `exact_alias` > `lexical` > `semantic`. A `semantic` hit
+ * is a guess worth confirming, not an equivalence.
+ */
 export interface ResolveValueCandidate {
     id: string;
     label: string;
@@ -21,6 +31,13 @@ export interface ResolveAttributeValueResponse {
         name: string;
         dictionaryId: string;
     };
+    /**
+     * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
+     * `candidates` list means the phrase genuinely matched several terms — taking
+     * `best` silently there is how a query ends up answering a question nobody
+     * asked. `unresolved` means the vocabulary holds nothing like it, which is not
+     * the same as the corpus holding no such materials.
+     */
     resolution: {
         status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
         query: string;

package/client-browse.d.ts

@@ -10,7 +10,13 @@
  * testing on its own.
  */
 import type { BrowseParams, BrowseResponse } from "./types.js";
-/** `client.browse(...)` — callable for one page, `.pages()` for the whole walk. */
+/**
+ * `client.browse(...)` — callable for ONE PAGE, `.pages()` for the whole walk.
+ *
+ * The distinction is the whole point: the single-call form hands you a page and
+ * states no total, so a corpus claim can only come from `.pages()`. Never report
+ * one page's length as "how many materials there are".
+ */
 export interface BrowseNamespace {
     (params: BrowseParams, signal?: AbortSignal): Promise<BrowseResponse>;
     pages(params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;