@instruments/materialgraph 0.6.0 → 0.6.1

package/spec-types.d.ts

@@ -11,12 +11,21 @@
  * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
  * of hand-assembling a magic `attribute:value` string.
  *
- * These criteria drive two operations equally:
- * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
- *   (colour / visual / lexical) search.
- * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ * These criteria drive two operations equally, and choosing between them IS the
+ * routing decision:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
+ *   (colour / visual / lexical) search. Reach for it when relevance still
+ *   matters: "something like this seed, but Class A".
+ * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
  *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`).
+ *   in `./specifications`). Reach for it when the spec is the whole question and
+ *   ranking would be noise.
+ *
+ * Discover the tokens before you spend them: `client.specificationFacets()` for
+ * what is facetable at all, `client.attributeValues()` for one attribute's
+ * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
+ * a phrase into a canonical pair. A hand-guessed token returns an honest empty
+ * answer, which is the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/spec-types.js

@@ -11,12 +11,21 @@
  * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
  * of hand-assembling a magic `attribute:value` string.
  *
- * These criteria drive two operations equally:
- * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
- *   (colour / visual / lexical) search.
- * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ * These criteria drive two operations equally, and choosing between them IS the
+ * routing decision:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
+ *   (colour / visual / lexical) search. Reach for it when relevance still
+ *   matters: "something like this seed, but Class A".
+ * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
  *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`).
+ *   in `./specifications`). Reach for it when the spec is the whole question and
+ *   ranking would be noise.
+ *
+ * Discover the tokens before you spend them: `client.specificationFacets()` for
+ * what is facetable at all, `client.attributeValues()` for one attribute's
+ * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
+ * a phrase into a canonical pair. A hand-guessed token returns an honest empty
+ * answer, which is the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/suggest-types.d.ts

@@ -6,6 +6,11 @@
  * Split out of `types.ts` for the repository's source-file size budget, the same
  * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
  * `types.ts`, so importers see no difference.
+ *
+ * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
+ * what answers a committed query; `mg.suggestColour()` covers colour names and
+ * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
+ * of the best matches, never a census of matching entities.
  */
 /** Which kind of entity a suggestion is — and therefore what `refId` means. */
 export type SuggestKind = "product" | "brand" | "category";
@@ -25,8 +30,12 @@ export interface Suggestion {
     brandSlug: string | null;
     brandName: string | null;
     categoryKey: string | null;
-    /** A representative variant, so a client can open a material record directly. */
+    /**
+     * A representative variant, so a client can open a material record directly.
+     * Opaque, and null when none was picked — not a product without variants.
+     */
     variantId: string | null;
+    /** Variants behind this entity IN MATERIALGRAPH — a coverage figure. */
     variantCount: number;
 }
 /** The suggest response: the query as interpreted, plus the ranked suggestions. */

package/suggest-types.js

@@ -6,6 +6,11 @@
  * Split out of `types.ts` for the repository's source-file size budget, the same
  * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
  * `types.ts`, so importers see no difference.
+ *
+ * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
+ * what answers a committed query; `mg.suggestColour()` covers colour names and
+ * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
+ * of the best matches, never a census of matching entities.
  */
 /**
  * Shape the query string for a suggest call.

package/types.d.ts

@@ -11,8 +11,22 @@
  * that mirrors a server enum is therefore widened with `(string & {})` so a new
  * server value still type-checks, and objects that may grow fields are read
  * structurally (unknown keys pass through untouched — the client never strips).
+ *
+ * READING CONTRACT — the three things callers get wrong, stated once here and
+ * repeated on the types where each one bites:
+ *  1. **Ids are opaque.** Round-trip them verbatim; never parse or construct
+ *     one. See `./identifiers.ts` for which strings are opaque tokens and which
+ *     are canonical vocabulary you discover.
+ *  2. **Absent is not false.** An optional field that is missing means UNKNOWN,
+ *     not "known to be absent in reality" — most dangerously for booleans.
+ *     Values carry `confidence` and `sourceBasis`; report them as claims.
+ *  3. **A page is not a corpus.** `results.length` is this page.
+ *     {@link CountedTotal} — with the `basis` it states — is the claim about the
+ *     match set. Follow the cursor for the rest, and never report a page size as
+ *     a total.
  */
 import type { BySpecVerdict } from "./by-spec-types.js";
+import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { SearchFilter, SearchSuggestion } from "./search-refinement-types.js";
 /** A widened string-literal union: known members autocomplete, unknown values still type-check. */
@@ -79,13 +93,22 @@ export interface VisualMeaning {
     version?: string;
     appliedAt?: string;
 }
-/** One material in a search / match result list. */
+/**
+ * One material in a search / match result list.
+ *
+ * ABSENT IS NOT FALSE. The optional fields here (`colourMeta`, `signals`,
+ * `retired`, `siblingCount`, `visualMeanings`, `verdict`) are absent when the
+ * request did not ask for them or the graph holds no answer — never because the
+ * answer is "no". A missing `retired` is not "still current"; a missing
+ * `visualMeanings` is not "this material has no visual meaning".
+ */
 export interface SearchResultItem {
-    variantId: string;
+    /** Opaque — round-trip verbatim into `material()`, `pairings()`, `similarTo`. */
+    variantId: VariantId;
     brand: string;
     product: string;
     brandSlug: string | null;
-    productId: string | null;
+    productId: ProductId | null;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -112,10 +135,18 @@ export interface SearchResultItem {
      */
     verdict?: BySpecVerdict;
 }
-/** The lean `view:"card"` result item — identity + name + thumbnail + score. */
+/**
+ * The lean `view:"card"` result item — identity + name + thumbnail + score.
+ *
+ * A PROJECTION, not a smaller answer: a field the card omits (palette, verdict,
+ * signals, availability) is unread here, never known-absent. Re-read the same
+ * `variantId` at `view: "full"` or via `material()` before claiming anything the
+ * card does not carry.
+ */
 export interface SearchCardItem {
-    variantId: string;
-    productId: string | null;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    productId: ProductId | null;
     brandSlug: string | null;
     brand: string;
     /** Product name (the full item's `product`). */
@@ -125,15 +156,26 @@ export interface SearchCardItem {
     score: number;
 }
 /**
- * A feed total with its honesty basis. `exact` — the true count (≤ the cap of
- * 1,000, or a facet-MV read). `lowerBound` — a floor (cap hit, ANN-pool bound,
- * or a degraded count). Never a silent approximation.
+ * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
+ * a different number from `results.length` (this page).
+ *
+ * `exact` — the true count (≤ the cap of 1,000, or a facet-MV read). Say "473
+ * materials match".
+ * `lowerBound` — a floor (cap hit, ANN-pool bound, or a degraded count). Say
+ * "at least 1,000", never "1,000". Never a silent approximation.
+ *
+ * A response with no `counts` at all states no total: `count: true` is opt-in,
+ * and the absence of a total is not a total of zero.
  */
 export interface CountedTotal {
     value: number;
     basis: OpenEnum<"exact" | "lowerBound">;
 }
-/** Feed counts — present under `count:true` or `collapse:"product"`. */
+/**
+ * Feed counts — present ONLY under `count:true` or `collapse:"product"`. This is
+ * the corpus-level claim; `results.length` is the page. Never report one as the
+ * other.
+ */
 export interface SearchCounts {
     variants: CountedTotal;
     products?: CountedTotal;
@@ -152,14 +194,21 @@ export interface SearchRerankReport {
  * {@link SearchCardItem}s. Every other field is shared. `counts` is present
  * under `count:true` or `collapse:"product"` (replacing the former
  * `variantCount`/`productCount`).
+ *
+ * A PAGE, NOT A CORPUS. `results.length` is what you were handed;
+ * {@link SearchCounts} is the only statement about the match set, and only when
+ * you asked for it. Follow `cursor` for the rest. "I found 24 materials" is
+ * wrong whenever `limit` was 24.
  */
 export interface SearchResponse {
     view: OpenEnum<"full" | "card">;
+    /** THIS PAGE. Its length is a page size, never a total. */
     results: SearchResultItem[];
     suggestions: SearchSuggestion[];
     mode: SearchMode;
     maxScore: number;
-    cursor?: string;
+    /** Opaque keyset for the next page. Absent = end of the walk, not an error. */
+    cursor?: Cursor;
     rerank?: SearchRerankReport;
     counts?: SearchCounts;
     note?: string;
@@ -180,8 +229,17 @@ export interface MatchCategoryInference {
     displayName: string;
     boost: number;
 }
-/** The Material Match response (non-streaming form). */
+/**
+ * The Material Match response (non-streaming form).
+ *
+ * `poolSize` is the candidate pool the floor was applied to, NOT a corpus total
+ * and NOT "how many materials look like this". An empty `results` with
+ * `droppedBelowFloor > 0` means "candidates existed and none was good enough" —
+ * a different answer from `poolSize: 0`, which means the image found nothing to
+ * search against at all.
+ */
 export interface MatchResponse {
+    /** THIS answer, capped by `limit`. Not a total. */
     results: SearchResultItem[];
     inferredCategories: MatchCategoryInference[];
     qualityFloor: number;
@@ -195,9 +253,17 @@ export interface MatchCategory {
     group: string | null;
     type: string | null;
 }
-/** One colour-palette match. */
+/**
+ * One colour-palette match.
+ *
+ * `hex`, `distance` and `closeness` are OKLab geometry over colour EXTRACTED
+ * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report it as visual
+ * likeness ("reads close to this colour"), never as a stated colour
+ * specification.
+ */
 export interface ByColourMatch {
-    variantId: string;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
     brand: string;
     product: string;
     color: string | null;
@@ -216,16 +282,18 @@ export interface ByColourResponse {
         categories?: string[];
         oklab?: OklabTriple;
     };
+    /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
     count: number;
     matches: ByColourMatch[];
 }
 /** One item from the pure colour-scalar browse. */
 export interface BrowseResultItem {
-    variantId: string;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
     brand: string;
     product: string;
     brandSlug: string | null;
-    productId: string | null;
+    productId: ProductId | null;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -236,10 +304,17 @@ export interface BrowseResultItem {
     };
     retired?: boolean;
 }
-/** A single page of the colour browse. `cursor` is the keyset for the next page. */
+/**
+ * A single page of the colour browse — the SDK's one genuinely cursor-paginated
+ * surface. `results.length` is this page and the browse states no total at all,
+ * so a corpus claim can only come from walking every page
+ * (`client.browse.pages(...)` does the loop).
+ */
 export interface BrowseResponse {
+    /** THIS PAGE. */
     results: BrowseResultItem[];
-    cursor?: string;
+    /** Opaque keyset for the next page. Absent = the walk is finished. */
+    cursor?: Cursor;
 }
 export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
 export interface ColourFacetTerm {
@@ -285,17 +360,34 @@ export interface ProjectTypeShare {
     projectType: string;
     projectCount: number;
 }
-/** A pairing item backed by real co-specification (order) evidence. */
+/**
+ * A pairing item from the behavioural arm — real order evidence, or board
+ * curation when this seed has no order edges.
+ *
+ * WHAT YOU MAY CLAIM, per `source`:
+ *  - `cospec` — real ORDER co-occurrence. The two materials were ordered
+ *    together on real projects. "Specified together" is honest here.
+ *  - `considered` — BOARD ACTIVITY only (moodboard curation). Somebody put them
+ *    on a board together; nobody is known to have bought them together. Say
+ *    "often boarded together" / "considered alongside" and NEVER "specified
+ *    together". The server falls back to this arm seed-by-seed when the seed
+ *    carries no `sampled` edges, so a single response can be entirely
+ *    `considered`.
+ *
+ * See {@link ColourPairing} for the third, non-evidential arm.
+ */
 export interface CospecPairing {
+    /** The evidence tier. `cospec` = orders; `considered` = boards. Read it before phrasing. */
     source: "cospec" | "considered";
-    variantId: string;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
     brand: string;
     product: string;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
     brandSlug: string;
-    productId: string;
+    productId: ProductId;
     category: string | null;
     projectCount: number;
     customerCount: number;
@@ -304,16 +396,31 @@ export interface CospecPairing {
     demand: CompanionDemand | null;
     topProjectTypes: ProjectTypeShare[];
 }
-/** A pairing item topped up from colour palette-similarity (merely looks adjacent). */
+/**
+ * A pairing item topped up from colour palette-similarity — a LOOK-ALIKE, not
+ * evidence. Nobody ordered these together and nobody boarded them together; the
+ * palettes sit near each other in OKLab. Say "shares a palette with" and never
+ * "specified together" or "often paired with".
+ */
 export interface ColourPairing extends MaterialTile {
     source: "colour";
     score: number;
 }
+/**
+ * One pairing, discriminated by `source` into three tiers of very different
+ * strength: `cospec` (real orders) > `considered` (board activity) > `colour`
+ * (palette look-alike). Branch on `source` before you write a sentence about it.
+ */
 export type PairingItem = CospecPairing | ColourPairing;
 export interface PairingsResponse {
     seed: MaterialTile;
+    /** A rail, not a ranked corpus — mixed evidence tiers, capped by `limit`. */
     items: PairingItem[];
-    /** How many items came from real order evidence (the cospec arm). */
+    /**
+     * How many `items` came from real ORDER evidence (`source: "cospec"`). Zero
+     * with a full rail means every item is board activity or colour look-alike —
+     * check it before presenting the rail as demand evidence.
+     */
     cospecCount: number;
 }
 export interface MaterialResponse {
@@ -324,15 +431,23 @@ export interface MaterialResponse {
 export interface SiblingsResponse {
     siblings: MaterialTile[];
 }
-/** Batch read of tile projections. */
+/**
+ * Batch read of tile projections. `materials` is NOT positional — resolve by
+ * `variantId`, and read `missingIds` rather than inferring absence from length.
+ */
 export interface MaterialsBatchTileResponse {
     materials: MaterialTile[];
-    missingIds: string[];
+    /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
+    missingIds: VariantId[];
 }
-/** Batch read of detail projections. */
+/**
+ * Batch read of detail projections. `materials` is NOT positional — resolve by
+ * `variantId`, and read `missingIds` rather than inferring absence from length.
+ */
 export interface MaterialsBatchDetailResponse {
     materials: MaterialDetail[];
-    missingIds: string[];
+    /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
+    missingIds: VariantId[];
 }
 export interface ResolveColourResponse {
     match: {
@@ -414,7 +529,7 @@ export interface SearchInput {
      * seed variant, so it is the only form `verdicts` can diff a candidate against.
      */
     similarTo?: {
-        variantId: string;
+        variantId: VariantId;
     } | {
         vector: string;
     };
@@ -438,11 +553,16 @@ export interface SearchInput {
      * demotes a failed/missing preferred hit WITHIN its page only.
      */
     preferences?: SearchFilter[];
+    /** Page size — the size of ONE page, never a bound on the match set. */
     limit?: number;
-    cursor?: string;
+    /** The previous response's `cursor`, passed back verbatim. Never synthesise one. */
+    cursor?: Cursor;
     explain?: boolean;
     collapse?: OpenEnum<"none" | "product">;
-    /** Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools. */
+    /**
+     * Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools.
+     * Without it the response states NO total — and a page size is not one.
+     */
     count?: boolean;
     /** Only return materials with at least one catalog image. Default false (full catalog). */
     hasImages?: boolean;
@@ -464,7 +584,8 @@ export interface SearchGetParams {
     mood?: string;
     sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
     tol?: OpenEnum<"tight" | "normal" | "loose">;
-    variantId?: string;
+    /** Seed the search from this variant's image. Opaque — pass it through verbatim. */
+    variantId?: VariantId;
     limit?: number;
     /** "0" or "1" — include per-signal `signals` on each result. */
     explain?: OpenEnum<"0" | "1">;
@@ -492,7 +613,12 @@ export interface ByColourParams {
 /** Params for the pure colour `search/browse` surface. */
 export interface BrowseParams {
     sort: OpenEnum<"light" | "dark" | "vivid" | "muted" | "colourful">;
-    cursor?: string;
+    /**
+     * The previous page's `cursor`, verbatim. Opaque keyset state — not an offset.
+     * Changing `sort`, `limit` or `types` invalidates it.
+     */
+    cursor?: Cursor;
+    /** Page size. */
     limit?: number;
     /** Comma-separated product-type ids to restrict the browse to. */
     types?: string;
@@ -525,7 +651,14 @@ export interface MatchInput {
 }
 /** Options for a batch material read. */
 export interface MaterialsBatchOptions {
+    /** Projection depth. `tile` omits fields rather than reporting them absent. */
     view?: "tile" | "detail";
+    /**
+     * Which id space `ids` are in — MaterialGraph's own opaque `variantId`
+     * (default) or Material Bank's `materialBankId`. Both are opaque; they are NOT
+     * interchangeable, and passing one under the other's `idKind` returns
+     * `missingIds`, not an error.
+     */
     idKind?: OpenEnum<"variantId" | "materialBankId">;
 }
 /** Options for a pairings read. */
@@ -543,184 +676,28 @@ export interface ResolveAttributeOptions {
 export interface BySpecOptions {
     limit?: number;
 }
-/** A resolved seed material (identity block shared by the demand reads). */
-export interface DemandSeed {
-    variantId: string;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    brandSlug: string;
-    productId: string;
-}
+export type * from "./demand-types.js";
+/** One quarter's tally. Sparse across a series — an absent quarter is not a zero. */
 export interface DemandQuarter {
     quarter: string;
     specCount: number;
     projectCount: number;
 }
-/** Headline demand stats for a seed: counts, quarterly series, momentum. */
-export interface MaterialDemandStats {
-    specCount: number;
-    projectCount: number;
-    customerCount: number;
-    byQuarter: DemandQuarter[];
-    momentum: DemandMomentum;
-}
-/** `getMaterialDemand` result, passed through verbatim by the `/demand` route. */
-export interface MaterialDemandResult {
-    found: boolean;
-    query: string;
-    seed: DemandSeed | null;
-    window: "trailing_36mo";
-    demand: MaterialDemandStats | null;
-}
 /**
- * `getCoSpecifiedMaterials` result, passed through verbatim. The `companions`
- * list (materials specified alongside the seed) is included but left loosely
- * typed — there is no captured fixture to pin its full shape.
+ * Which behavioural signal a demand read is scoped to — and therefore what a
+ * number drawn from it may honestly be called.
+ *
+ *  - `sampled` — real ORDER co-occurrence. The default everywhere. Present as
+ *    "specified together" / "specified on N projects".
+ *  - `considered` — board / moodboard CURATION. Somebody assembled them; nobody
+ *    is known to have bought them. Present as "considered alongside", never as
+ *    a specification.
+ *  - `specified` — the won tier. STATS ONLY: no co-specification edges are built
+ *    at this grain, so asking for `specified` companions is a rejected request,
+ *    not an empty result.
  */
-export interface CoSpecifiedResult {
-    found: boolean;
-    resolution: OpenEnum<"resolved" | "ambiguous" | "not_found">;
-    query: string;
-    seed: DemandSeed | null;
-    seedCategory: string | null;
-    seedAlternatives: DemandSeed[];
-    companions?: unknown[];
-}
-/** The `/api/v1/demand` envelope — both domain reads side by side, verbatim. */
-export interface DemandResponse {
-    query: string;
-    demand: MaterialDemandResult;
-    cospec: CoSpecifiedResult;
-}
-/** Which behavioural signal candidate demand is read from. */
 export type DemandSignal = OpenEnum<"sampled" | "considered" | "specified">;
-/**
- * Body for `POST /api/v1/demand/batch` — enrich 1–48 already-selected candidate
- * ids with their real specification demand, in input order and cardinality.
- */
-export interface DemandBatchInput {
-    /** 1–48 canonical variant ids. Order AND cardinality are preserved — duplicates are echoed, never collapsed. */
-    variantIds: string[];
-    /** The behavioural signal to read demand from. Defaults to `sampled` (order co-occurrence) server-side. */
-    signal?: DemandSignal;
-    /** Optional declared context (e.g. `{ projectType: "hospitality" }`) — echoed for provenance, never used to rank or filter. */
-    context?: Record<string, string>;
-}
-/** Headline population behind the metric — this variant's own counts. */
-export interface DemandBatchPopulation {
-    specCount: number;
-    projectCount: number;
-    customerCount: number;
-}
-/** The consideration→specification funnel (project-grain; `exclusionRate` is annotate-only). */
-export interface DemandBatchFunnel {
-    consideredProjects: number;
-    specifiedProjects: number;
-    excludedCount: number;
-    exclusionRate: number;
-}
-/** Per-result guardrail status — present on `internal` (`mg:admin`) results only. */
-export interface DemandBatchEvidence {
-    belowPrivacyFloor: boolean;
-    belowQualityFloor: boolean;
-    suppressedForPublic: boolean;
-}
-/** A variant that carries a usable demand signal. */
-export interface DemandBatchAvailableResult {
-    variantId: string;
-    state: "available";
-    population: DemandBatchPopulation;
-    /** Exact per-quarter counts (sparse — zero-spec quarters are absent). */
-    intervals: DemandQuarter[];
-    momentum: DemandMomentum;
-    /** The funnel; null when the signal is not `sampled` or no `considered` row/session exists. */
-    funnel: DemandBatchFunnel | null;
-    /** Exact guardrail evidence for `internal` callers; null for public. */
-    evidence: DemandBatchEvidence | null;
-}
-/** A variant with a stats row that is below the public quality floor. */
-export interface DemandBatchInsufficientResult {
-    variantId: string;
-    state: "insufficient_data";
-}
-/** A variant with no stats — indistinguishable from a privacy-suppressed one for public callers. */
-export interface DemandBatchNoSignalResult {
-    variantId: string;
-    state: "no_signal";
-}
-/** A requested id that resolves to no real variant. */
-export interface DemandBatchUnknownResult {
-    variantId: string;
-    state: "unknown_variant";
-}
-/** One discriminated result per input id, in input order and cardinality. */
-export type DemandBatchResult = DemandBatchAvailableResult | DemandBatchInsufficientResult | DemandBatchNoSignalResult | DemandBatchUnknownResult;
-/** The `POST /api/v1/demand/batch` envelope. */
-export interface DemandBatchResponse {
-    /** The completed ingestion-session id these counts were mined in (the dataset generation). */
-    generationId: string;
-    metric: "specification_demand";
-    /** The metric universe — the window and signal the counts are scoped to. */
-    universe: {
-        window: "trailing_36mo";
-        signal: DemandSignal;
-        description: string;
-    };
-    /** The guardrail status under which `results` were projected. */
-    guardrail: {
-        audience: OpenEnum<"public" | "internal">;
-        minProjectCount: number;
-        minCustomerCount: number;
-    };
-    /** Outcome tallies over `results` — never a denominator for the metric. */
-    coverage: {
-        requested: number;
-        available: number;
-        insufficientData: number;
-        noSignal: number;
-        unknownVariant: number;
-    };
-    /** The echoed declared context, or null when none was supplied. */
-    context: Record<string, string> | null;
-    results: DemandBatchResult[];
-}
-export interface CoordinateSeed extends DemandSeed {
-    /** The input reference this seed resolved from. */
-    resolvedFrom: string;
-}
-export interface CoordinateCompanion {
-    variantId: string;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    brandSlug: string;
-    productId: string;
-    totalLift: number;
-    liftLabel: string;
-    seedMatchCount: number;
-    seedContributions: Array<{
-        seedVariantId: string;
-        lift: number;
-    }>;
-    demand: CompanionDemand | null;
-    swatches: Array<{
-        hex: string;
-        proportion: number;
-    }>;
-    /** Annotate-only appearance similarity — never reorders companions in v1. */
-    colourFit: number | null;
-}
-export interface CoordinateResponse {
-    seeds: CoordinateSeed[];
-    unresolved: string[];
-    window: "trailing_36mo";
-    companions: CoordinateCompanion[];
-}
+export type * from "./demand-batch-types.js";
 export interface ExtractedPalette {
     colors: Array<{
         hex: string;
@@ -848,18 +825,6 @@ export interface BrandProfileResponse {
         name: string;
     }>;
 }
-/** Seed a demand read by EXACTLY ONE of `variantId` or `material`. */
-export interface DemandParams {
-    variantId?: string;
-    material?: string;
-}
-/** Body for `POST /api/v1/pairings/coordinate`. */
-export interface CoordinateInput {
-    materials?: string[];
-    variantIds?: string[];
-    projectType?: string;
-    limit?: number;
-}
 /** Body for `POST /api/v1/search/palettes/extract`. */
 export interface ExtractPaletteInput {
     /** The query image as a data URI or bare base64 string. */