@instruments/materialgraph 0.1.0 → 0.3.0

package/specifications.js

@@ -0,0 +1,82 @@
+/**
+ * Zero-dependency builders for the specification surface. Turn a plain-language
+ * spec intent into a typed criterion the SDK's two spec operations accept:
+ *
+ * - `search({ filters })` takes {@link SpecFilter} objects — a spec gate layered
+ *   onto a ranked (colour / visual / lexical) search. Build them with
+ *   {@link specTerm}, {@link hasSpec}, and {@link certificationProgramme}.
+ * - `bySpec(specs)` takes `attribute:value` strings — the value-anchored,
+ *   spec-only primitive. Build them with {@link specCriterion} and
+ *   {@link certificationProgrammeCriterion}.
+ *
+ * The point of these helpers: Desk (and any spec-driven caller) never has to
+ * remember that a certification programme lives under a VIRTUAL attribute, nor
+ * hand-format the `attribute:value` string the `bySpec` route splits on its
+ * first `:`.
+ */
+import { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, } from "./spec-types.js";
+/**
+ * A term-equality criterion for `search({ filters })` — the attribute must
+ * carry this canonical value.
+ *
+ * @example
+ * // "same fire class as the seed"
+ * client.search({ similarTo: { variantId }, filters: [specTerm("fire_classifications", "astm_e84_class_a")] });
+ */
+export function specTerm(attributeId, term) {
+    return { attributeId, term };
+}
+/**
+ * A presence criterion for `search({ filters })` — the attribute must have ANY
+ * accepted value.
+ *
+ * @example
+ * // "…and it must have an EPD on record"
+ * client.search({ similarTo: { variantId }, filters: [hasSpec("environmental_product_declaration")] });
+ */
+export function hasSpec(attributeId) {
+    return { attributeId, hasValue: true };
+}
+/**
+ * A certification-programme criterion for `search({ filters })`, pinned to the
+ * virtual attribute so a programme matches wherever it landed at ingest
+ * (compliance / sustainability / material-health / VOC buckets).
+ *
+ * The value may be a display name or alias ("GREENGUARD Gold", "LEED") — the
+ * server resolves it to its canonical programme token before matching — or a
+ * canonical token directly (e.g. `greenguard_certificate`,
+ * `has_greenguard_gold_certification`).
+ *
+ * @example
+ * // "find a GREENGUARD-certified alternative"
+ * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("GREENGUARD Gold")] });
+ */
+export function certificationProgramme(programme) {
+    return { attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, term: programme };
+}
+/**
+ * An `attribute:value` criterion string for `bySpec`. The `bySpec` route splits
+ * on the FIRST `:`, so a value may itself contain colons; the attribute id may
+ * not.
+ *
+ * @example
+ * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
+ */
+export function specCriterion(attributeId, value) {
+    return `${attributeId}:${value}`;
+}
+/**
+ * An `attribute:value` criterion string for `bySpec` that filters by
+ * certification PROGRAMME across all four certification buckets.
+ *
+ * The value may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
+ * server-side to its canonical programme token, or a canonical token directly
+ * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
+ *
+ * @example
+ * // every brand's GREENGUARD-Gold materials
+ * client.bySpec([certificationProgrammeCriterion("GREENGUARD Gold")]);
+ */
+export function certificationProgrammeCriterion(programme) {
+    return specCriterion(CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, programme);
+}

package/sse.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A minimal, dependency-free Server-Sent Events reader — the primitive behind
+ * {@link MaterialGraphClient.streamRunEvents}. Hand-rolled (no `eventsource`,
+ * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
+ * Node route handlers, where `fetch` yields a byte `ReadableStream`.
+ *
+ * The parser follows the WHATWG event-stream tokenizer closely enough for the
+ * `/api/v1/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
+ * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
+ * optional leading space after the field colon. Frames split across network
+ * chunks are held in an internal buffer until their terminating blank line.
+ */
+/** One dispatched SSE frame. `data` is the joined data lines (no trailing newline). */
+export interface SseFrame {
+    id?: string;
+    event?: string;
+    data: string;
+}
+/**
+ * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
+ * returns any frames completed by that text. Call {@link flush} once the stream
+ * ends to dispatch a final frame that had data but no terminating blank line.
+ */
+export declare class SseDecoder {
+    #private;
+    push(text: string): SseFrame[];
+    /** Dispatch a trailing frame that had fields but no closing blank line. */
+    flush(): SseFrame[];
+}
+/**
+ * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
+ * or `signal` aborts (mid-read abort rejections are swallowed once the signal
+ * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
+ */
+export declare function readSseFrames(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseFrame, void, unknown>;

package/sse.js

@@ -0,0 +1,147 @@
+/**
+ * A minimal, dependency-free Server-Sent Events reader — the primitive behind
+ * {@link MaterialGraphClient.streamRunEvents}. Hand-rolled (no `eventsource`,
+ * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
+ * Node route handlers, where `fetch` yields a byte `ReadableStream`.
+ *
+ * The parser follows the WHATWG event-stream tokenizer closely enough for the
+ * `/api/v1/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
+ * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
+ * optional leading space after the field colon. Frames split across network
+ * chunks are held in an internal buffer until their terminating blank line.
+ */
+/**
+ * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
+ * returns any frames completed by that text. Call {@link flush} once the stream
+ * ends to dispatch a final frame that had data but no terminating blank line.
+ */
+export class SseDecoder {
+    #buffer = "";
+    #dataLines = [];
+    #id;
+    #event;
+    #hasFields = false;
+    push(text) {
+        this.#buffer += text;
+        const frames = [];
+        for (;;) {
+            const lineEnd = this.#nextLineEnd();
+            if (lineEnd === null)
+                break;
+            const line = this.#buffer.slice(0, lineEnd.index);
+            this.#buffer = this.#buffer.slice(lineEnd.nextIndex);
+            const frame = this.#consumeLine(line);
+            if (frame)
+                frames.push(frame);
+        }
+        return frames;
+    }
+    /** Dispatch a trailing frame that had fields but no closing blank line. */
+    flush() {
+        if (this.#buffer.length > 0) {
+            // At end of stream a deferred trailing CR is a real terminator, not data.
+            const line = this.#buffer.endsWith("\r") ? this.#buffer.slice(0, -1) : this.#buffer;
+            this.#buffer = "";
+            const frame = this.#consumeLine(line);
+            if (frame)
+                return [frame];
+        }
+        const frame = this.#dispatch();
+        return frame ? [frame] : [];
+    }
+    /** Locate the next line terminator, deferring a lone trailing `\r` (may be `\r\n`). */
+    #nextLineEnd() {
+        for (let i = 0; i < this.#buffer.length; i += 1) {
+            const char = this.#buffer[i];
+            if (char === "\n")
+                return { index: i, nextIndex: i + 1 };
+            if (char === "\r") {
+                if (i === this.#buffer.length - 1)
+                    return null;
+                return this.#buffer[i + 1] === "\n"
+                    ? { index: i, nextIndex: i + 2 }
+                    : { index: i, nextIndex: i + 1 };
+            }
+        }
+        return null;
+    }
+    #consumeLine(line) {
+        if (line.length === 0)
+            return this.#dispatch();
+        if (line.startsWith(":"))
+            return undefined;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "data") {
+            this.#dataLines.push(value);
+            this.#hasFields = true;
+        }
+        else if (field === "event") {
+            this.#event = value;
+            this.#hasFields = true;
+        }
+        else if (field === "id") {
+            this.#id = value;
+            this.#hasFields = true;
+        }
+        return undefined;
+    }
+    #dispatch() {
+        if (!this.#hasFields)
+            return undefined;
+        const frame = { data: this.#dataLines.join("\n") };
+        if (this.#event !== undefined)
+            frame.event = this.#event;
+        if (this.#id !== undefined)
+            frame.id = this.#id;
+        this.#dataLines = [];
+        this.#event = undefined;
+        this.#id = undefined;
+        this.#hasFields = false;
+        return frame;
+    }
+}
+/**
+ * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
+ * or `signal` aborts (mid-read abort rejections are swallowed once the signal
+ * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
+ */
+export async function* readSseFrames(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const sse = new SseDecoder();
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                return;
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                throw error;
+            }
+            if (result.done) {
+                for (const frame of sse.push(decoder.decode()))
+                    yield frame;
+                for (const frame of sse.flush())
+                    yield frame;
+                return;
+            }
+            const text = decoder.decode(result.value, { stream: true });
+            for (const frame of sse.push(text)) {
+                if (signal?.aborted)
+                    return;
+                yield frame;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/types.d.ts

@@ -12,9 +12,19 @@
  * server value still type-checks, and objects that may grow fields are read
  * structurally (unknown keys pass through untouched — the client never strips).
  */
+import type { BySpecVerdict } from "./by-spec-types.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. */
 export type OpenEnum<T extends string> = T | (string & {});
+/**
+ * A JSON value, recursively — exactly what survives a `jsonb` round-trip
+ * unchanged. Used where a payload's SHAPE belongs to its producer but its values
+ * must still be JSON: `Date`, `bigint`, `undefined`, and functions are not.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /** One palette swatch of a material's main image. */
 export interface PaletteSwatch {
     hex: string;
@@ -48,60 +58,15 @@ export interface MaterialColour {
 }
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
-/** The grid-card projection of a material. */
-export interface MaterialTile {
-    variantId: string;
-    brand: string;
-    product: string;
-    variantName: string | null;
-    imageUrl: string | null;
-    imageSource: ImageSource | null;
-    category: string | null;
-    colour: MaterialColour;
-}
-/** A canonical attribute/term pair carried on a detail record. */
-export interface MaterialFacet {
-    attributeId: string;
-    term: string;
-}
-/**
- * One dimensional configuration of a material. Numeric fields are millimetres
- * (mass in kilograms); string fields are the source's own descriptors. The
- * index signature preserves the corpus's long tail of rarer keys.
- */
-export interface DimensionEntry {
-    label?: string;
-    tile_size?: string;
-    measurement_basis?: string;
-    width_mm?: number;
-    length_mm?: number;
-    height_mm?: number;
-    depth_mm?: number;
-    thickness_mm?: number;
-    diameter_mm?: number;
-    visible_projection_mm?: number;
-    weight_kg?: number;
-    [key: string]: unknown;
-}
-/** The record projection of a material — the tile plus detail-only fields. */
-export interface MaterialDetail extends MaterialTile {
-    brandSlug: string;
-    productId: string;
-    color: string | null;
-    materialBankId: string | null;
-    installationImageUrl: string | null;
-    displayCategory: string | null;
-    categoryPath: string[];
-    palette: PaletteSwatch[];
-    facets: MaterialFacet[];
-    dimensions: DimensionEntry[] | null;
-}
+export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, } from "./material-types.js";
 /** Per-signal scores, present on a result when `explain` was requested. */
 export interface SearchResultSignals {
     image: number | null;
     category: number | null;
     colour: number | null;
     lexical: number | null;
+    /** Text→image RERANK cosine — non-null only for a seeded search carrying `text`. */
+    text: number | null;
 }
 /** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
 export interface VisualMeaning {
@@ -131,8 +96,47 @@ export interface SearchResultItem {
     score: number;
     signals?: SearchResultSignals;
     retired?: boolean;
+    /**
+     * Present (true) only on quality-floor rejects returned under `includeBelowFloor`
+     * (match only) — the item failed the match image-quality floor and would be
+     * dropped by default. Appended after the kept results.
+     */
+    belowFloor?: boolean;
     siblingCount?: number;
     visualMeanings?: VisualMeaning[];
+    /**
+     * The shared report card for this hit against the request's `filters` (required
+     * cells) and `preferences` (preferred cells). Present (full view only) whenever a
+     * spec filter or preference was given. Reuses the by-spec verdict shape — the
+     * shared CandidateVerdict mirror; see {@link MaterialVerdict}.
+     */
+    verdict?: BySpecVerdict;
+}
+/** The lean `view:"card"` result item — identity + name + thumbnail + score. */
+export interface SearchCardItem {
+    variantId: string;
+    productId: string | null;
+    brandSlug: string | null;
+    brand: string;
+    /** Product name (the full item's `product`). */
+    name: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    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.
+ */
+export interface CountedTotal {
+    value: number;
+    basis: OpenEnum<"exact" | "lowerBound">;
+}
+/** Feed counts — present under `count:true` or `collapse:"product"`. */
+export interface SearchCounts {
+    variants: CountedTotal;
+    products?: CountedTotal;
 }
 /** The single candidate source a query resolved to. */
 export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical">;
@@ -142,16 +146,22 @@ export interface SearchRerankReport {
     colourWeight?: number;
     colourLabel?: string;
 }
-/** The full search response (both GET and POST forms return this envelope). */
+/**
+ * The search response envelope. `view` discriminates the `results` union:
+ * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
+ * {@link SearchCardItem}s. Every other field is shared. `counts` is present
+ * under `count:true` or `collapse:"product"` (replacing the former
+ * `variantCount`/`productCount`).
+ */
 export interface SearchResponse {
+    view: OpenEnum<"full" | "card">;
     results: SearchResultItem[];
     suggestions: SearchSuggestion[];
     mode: SearchMode;
     maxScore: number;
     cursor?: string;
     rerank?: SearchRerankReport;
-    variantCount?: number;
-    productCount?: number;
+    counts?: SearchCounts;
     note?: string;
     timings?: Record<string, number>;
     /** Echo of the resolved query input (raw image bytes/vector are never echoed). */
@@ -159,6 +169,11 @@ export interface SearchResponse {
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
     seed?: MaterialTile | Record<string, unknown>;
 }
+/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
+export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
+    view: OpenEnum<"card">;
+    results: SearchCardItem[];
+}
 /** An inferred product-type category from the query image, with its boost. */
 export interface MatchCategoryInference {
     productTypeId: string;
@@ -348,31 +363,7 @@ export interface ResolveAttributeResponse {
     candidates: AttributeCandidate[];
 }
 export type * from "./catalog-discovery-types.js";
-export interface BySpecMatchedCell {
-    attributeId: string;
-    confidence: number | null;
-    sourceBasis: string | null;
-}
-export interface BySpecMatch {
-    variantId: string;
-    brand: string;
-    product: string;
-    variant: string;
-    color: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    matched: BySpecMatchedCell[];
-    minConfidence: number | null;
-}
-export interface BySpecResponse {
-    criteria: Array<{
-        attribute: string;
-        value: string;
-    }>;
-    totalMatches: number;
-    brandsSpanned: number;
-    matches: BySpecMatch[];
-}
+export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
     principal: string;
     scopes: string[];
@@ -416,6 +407,11 @@ export interface SearchInput {
     };
     mood?: string;
     sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    /**
+     * Seed a visual search from an existing variant's image (`variantId`) or a
+     * pre-computed image vector (`vector`). Only the `{ variantId }` form carries a
+     * seed variant, so it is the only form `verdicts` can diff a candidate against.
+     */
     similarTo?: {
         variantId: string;
     } | {
@@ -431,12 +427,33 @@ export interface SearchInput {
         category?: number;
         colour?: number;
         lexical?: number;
+        /** Text rerank multiplier applied when a seeded search also carries `text` (default 0.4). */
+        text?: number;
     };
     filters?: SearchFilter[];
+    /**
+     * SOFT spec criteria (rank-never-exclude). Same shape as `filters`; a preference
+     * never removes a result — it adds a `preferred` cell to each hit's `verdict` and
+     * demotes a failed/missing preferred hit WITHIN its page only.
+     */
+    preferences?: SearchFilter[];
     limit?: number;
     cursor?: string;
     explain?: boolean;
     collapse?: OpenEnum<"none" | "product">;
+    /** Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools. */
+    count?: boolean;
+    /** Only return materials with at least one catalog image. Default false (full catalog). */
+    hasImages?: boolean;
+    /**
+     * Opt-in seed-relative verdict cells (MG-629). Only meaningful with
+     * `similarTo: { variantId }`: each hit's `verdict` gains `preferred` cells
+     * diffing its comparable attributes (numeric + a `colour` axis) against the
+     * seed's, with directional deviations. Inert on every other seed form.
+     */
+    verdicts?: boolean;
+    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
+    view?: OpenEnum<"full" | "card">;
 }
 /** Query-string params for the GET `/search` form. */
 export interface SearchGetParams {
@@ -450,6 +467,12 @@ export interface SearchGetParams {
     limit?: number;
     /** "0" or "1" — include per-signal `signals` on each result. */
     explain?: OpenEnum<"0" | "1">;
+    /** "true" — opt in to a `counts.variants` feed total. */
+    count?: OpenEnum<"true">;
+    /** "true" — only return materials with at least one catalog image. */
+    hasImages?: OpenEnum<"true">;
+    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
+    view?: OpenEnum<"full" | "card">;
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {
@@ -485,7 +508,19 @@ export interface MatchInput {
     detectionLabel?: string;
     materialFunction?: string;
     detectionCategory?: string;
+    /**
+     * Opt-in: also return quality-floor rejects, flagged `belowFloor: true` and
+     * appended after the kept results. Absent/false = default behaviour;
+     * `droppedBelowFloor` is unchanged.
+     */
+    includeBelowFloor?: boolean;
     requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
+    /** Hard spec gates forwarded verbatim to the inner search — term match or presence, each with an optional trust bar. */
+    filters?: SearchFilter[];
+    /** Soft criteria (rank-never-exclude). A miss demotes within the page but never removes a hit. */
+    preferences?: SearchFilter[];
+    /** Opt in to seed-relative verdict cells; inert unless the inner search carries a variant seed. */
+    verdicts?: boolean;
 }
 /** Options for a batch material read. */
 export interface MaterialsBatchOptions {
@@ -559,6 +594,98 @@ export interface DemandResponse {
     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;
@@ -742,7 +869,7 @@ export interface ExtractPaletteInput {
 /** Options for a cacheable GET batch read (`materialsCached`). */
 export interface MaterialsBatchGetOptions extends MaterialsBatchOptions {
 }
-/** Options for `brands/{slug}`. */
+/** Options for `brands/{brandSlug}`. */
 export interface BrandOptions {
     /** Alternate fuzzy query; takes precedence over the path slug when present. */
     q?: string;