@instruments/materialgraph 0.25.0 → 0.27.0

package/types.d.ts

@@ -1,6 +1,4 @@
-export type { SearchResponse } from "./search-response-types.js";
 import type { ResponseAttribution } from "./attribution-types.js";
-import type { BySpecVerdict } from "./by-spec-types.js";
 /**
  * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
  * These interfaces intentionally have NO runtime dependency on any
@@ -27,24 +25,20 @@ import type { BySpecVerdict } from "./by-spec-types.js";
  *     match set. Follow the cursor for the rest, and never report a page size as
  *     a total.
  */
-import type { CorpusScopeReceipt } from "./corpus-scope-types.js";
+import type { CorpusScope } from "./corpus-scope-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
-import type { MaterialDetail, MaterialTile, SiblingTile } from "./material-types.js";
-import type { QueryUnderstanding } from "./query-understanding-types.js";
-import type { CollapsedVariant, SearchAnatomyMember } from "./search-collapse-types.js";
-import type { MoodInterpretation } from "./search-mood-types.js";
-import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
-import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRefinementReceipt, SearchRerankReport, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
-import type { SearchWindowReceipt } from "./search-window-types.js";
+import type { FilterOp } from "./list-variants-types.js";
+import type { MaterialDetail, MaterialTile } from "./material-types.js";
+import type { SearchMode, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
+export type { SearchResponse } from "./search-response-types.js";
 export type * from "./search-response-receipt-types.js";
-export type { MoodInterpretation } from "./search-mood-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
 export type { JsonValue } from "./json-value-types.js";
 /**
  * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
  * IMAGERY, so read it as visual likeness, never as a declared colour spec.
  */
-export interface PaletteSwatch {
+export type PaletteSwatch = {
     hex: string;
     proportion: number;
     /** Stored human colour name for the swatch, when one was extracted. */
@@ -56,21 +50,21 @@ export interface PaletteSwatch {
      * derived here" — never "achromatic".
      */
     oklab?: OklabTriple;
-}
+};
 /** Loose colour metadata for a search result's main image; every field is independently optional. */
-export interface ColourMeta {
+export type ColourMeta = {
     mood?: string;
     dominantFamily?: string;
     dominantHex?: string;
-}
+};
 /** OKLab triple. */
-export interface OklabTriple {
+export type OklabTriple = {
     l: number;
     a: number;
     b: number;
-}
+};
 /** The material's dominant-colour block (tile/detail projections). */
-export interface MaterialColour {
+export type MaterialColour = {
     dominantHex: string | null;
     hsl: {
         h: number;
@@ -80,42 +74,26 @@ export interface MaterialColour {
     oklab: OklabTriple | null;
     chroma: number | null;
     vibrancy: number | null;
-}
+};
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
-export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, SiblingTile, } from "./material-types.js";
-/** Per-signal scores, present on a result when `explain` was requested. */
-export interface SearchResultSignals {
-    /** Voyage similarity in the dedicated variant text-portrait space. */
-    portrait?: number | null;
+export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, } from "./material-types.js";
+/**
+ * Match only: the image-space cosine between the query image and this row's
+ * image, in [0,1]. Null when it was not measured.
+ */
+export type SearchResultSignals = {
     image: number | null;
-    category: number | null;
-    colour: number | null;
-    lexical: number | null;
-    /** Compatibility slot for retired seeded secondary scoring; currently null. */
-    text: number | null;
-}
-/** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
-export interface VisualMeaning {
-    id: string;
-    label: string;
-    values: string[];
-    basis: OpenEnum<"canonical_attribute" | "image_colour_analysis">;
-    confidence?: number;
-    sourceBasis?: string;
-    version?: string;
-    appliedAt?: string;
-}
+};
 /**
  * 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".
+ * `retired`, `productType`) 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".
  */
-export interface SearchResultItem {
+export type SearchResultItem = {
     /** This hit's attribution key — see {@link ResponseAttribution}. Opaque. */
     resultId?: string;
     /** Accepted sampleability fact. Absent means unknown, never false. */
@@ -157,7 +135,20 @@ export interface SearchResultItem {
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
+    /**
+     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest. Key a
+     * cache or dedupe on it rather than the URL. ABSENT means no hash is on
+     * record, never that there is no image.
+     */
+    imageSha256?: string;
     hasImage: boolean;
+    /**
+     * How many eligible variants the row's product has, the same set
+     * `listVariants` pages, so a follow-up list returns this many: the card's
+     * "12 colourways". ABSENT means the product is unknown or has no eligible
+     * variant.
+     */
+    variantCount?: number;
     palette: PaletteSwatch[];
     colourMeta?: ColourMeta;
     /**
@@ -175,28 +166,14 @@ export interface SearchResultItem {
         hex: string;
     };
     /**
-     * EXPLAIN-only: the two identities a COLLAPSED result holds, which are not the
-     * same thing and are routinely confused.
-     *
-     * - `representative` — the RANKING identity. Its score is the group's cursor
-     *   key and the item's `signals` describe IT, not the photograph on the card.
-     *   Omitted when the face IS the representative.
-     * - the item's own `variantId` — the DISPLAY identity (the face).
-     *
-     * `siblingsTruncated` says the sibling list was capped: a product can hold
-     * hundreds of colourways, so absence of a sibling is never evidence it does
-     * not exist.
+     * Selected mode's weighted primary score; see `maxScore`. On a Match page
+     * this is the retrieval score and does NOT order the page: the order is
+     * colour agreement, then `confidence` (MG-1900).
      */
-    anatomy?: {
-        representative?: SearchAnatomyMember;
-        siblings?: SearchAnatomyMember[];
-        siblingsTruncated?: boolean;
-    };
-    /** Selected mode's weighted primary score; see `maxScore`. */
     score: number;
     /**
      * Match only. How close this material is to the query, as an ABSOLUTE
-     * image-space similarity in [0,1] adjusted for colour — the same unit as
+     * image-space similarity in [0,1], not adjusted for colour — the same unit as
      * `qualityFloor` and `comparison.bestRejected`, so all three sit on one axis.
      *
      * Never normalised against the page, so the same material reads the same in
@@ -205,7 +182,9 @@ export interface SearchResultItem {
      * "99%+"); `Math.round` prints 100% from 0.995 up. Capping it server-side
      * would put it on a different ceiling from `comparison.bestRejected`, which
      * publishes the same unit uncapped, and the two are meant to be comparable.
-     * `score` is the ranking value and lives on a different scale.
+     * A Match page lists rows whose colour agrees (`colourDistance` under 0.1)
+     * first, then unmeasured ones, then the rest, and orders each set by this
+     * number. `score` is the retrieval score and lives on a different scale.
      */
     confidence?: number;
     /**
@@ -215,8 +194,9 @@ export interface SearchResultItem {
      */
     confidenceBand?: "strong" | "good" | "fair" | "weak";
     /**
-     * Match only. Proportion-weighted OKLab distance from the query crop's palette
-     * to this material's. `null` means the material carries no stored palette —
+     * Match only. OKLab earth mover's distance between the query crop's palette
+     * and this material's, reading both palettes' proportions. Under 0.1 the
+     * colour agrees. `null` means the material carries no stored palette —
      * UNKNOWN colour, never "no colour" and never "distant". Absent when the
      * colour stage did not run.
      */
@@ -242,18 +222,6 @@ export interface SearchResultItem {
      * `includeBelowFloor`.
      */
     admittedOnColour?: boolean;
-    /** Variants HIDDEN behind this card by `collapse: "product"` — the COMPLETE tally, even when {@link variants} is capped. */
-    siblingCount?: number;
-    /** The product's matching variants, MOST RELEVANT FIRST — present exactly under `collapse: "product"`, capped, and led by the group's RANKING representative, which is NOT always this item. {@link CollapsedVariant} states the full contract. */
-    variants?: CollapsedVariant[];
-    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;
     /**
      * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
      * attribute id. ABSENT entirely when `returnAttributes` was not sent.
@@ -266,48 +234,40 @@ export interface SearchResultItem {
      * attribute rather than a list of candidates.
      */
     attributes?: Record<string, string | string[] | null>;
-}
+};
 /**
  * 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. 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.
+ * `lowerBound` — a floor (cap hit or an ANN-pool bound). Say "at least
+ * 1,000", never "1,000". Never a silent approximation.
+ * `unknown` — the count query itself faulted (MG-2104): `value` is the pool
+ * this page was drawn from, NOT a claim about the corpus — do not print it as
+ * a bound. Check the response's `degraded.parts` for `"variant-count"`.
  *
- * The CAP differs by lane, and only `lowerBound` ever tells you one was hit. The
- * SEARCH feed counts exactly to 1,000 and reports a floor beyond it, because it
- * counts over attribute and tsquery universes where an unbounded count is a
- * timeout. The BROWSE feed ({@link BrowseCounts}) is uncapped — a plain count
- * over the same predicate its page scan ran, so a category of 66,000 reports
- * 66,000 exactly. Read `basis`; never assume a ceiling.
+ * Only `lowerBound` ever tells you a cap was hit. The SEARCH feed counts
+ * exactly to 1,000 and reports a floor beyond it, because it counts over
+ * attribute and tsquery universes where an unbounded count is a timeout. Read
+ * `basis`; never assume a ceiling.
  *
  * 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 {
+export type CountedTotal = {
     value: number;
-    basis: OpenEnum<"exact" | "lowerBound">;
-}
-/**
- * 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;
-}
+    basis: OpenEnum<"exact" | "lowerBound" | "unknown">;
+};
 /**
  * One value within a facet's counts: the CANONICAL token (send it back verbatim
  * as a filter term), its display label, and how many variants in the counted
  * set carry it.
  */
-export interface SearchFacetValue {
+export type SearchFacetValue = {
     value: string;
     label: string;
     variants: number;
-}
+};
 /**
  * One facet's counts. `basis` is the honesty label, and — per the negotiated
  * MG-1010 contract — its union is CLOSED: exactly `"exact"` or `"lowerBound"`,
@@ -318,11 +278,11 @@ export interface SearchFacetValue {
  * pool-counted value is NEVER `exact`. `truncated` is ALWAYS present: true
  * when more distinct values existed beyond the reported list.
  */
-export interface SearchFacetCount {
+export type SearchFacetCount = {
     values: SearchFacetValue[];
     truncated: boolean;
     basis: "exact" | "lowerBound";
-}
+};
 /**
  * A requested facet that was not counted, with its reason: `"unsupported"` —
  * the id is known but facet counting does not cover it; `"timeout"` — the
@@ -330,159 +290,74 @@ export interface SearchFacetCount {
  * rail could not count; the page is intact). Render it as "couldn't count",
  * never as zero.
  */
-export interface SearchAbsentFacet {
+export type SearchAbsentFacet = {
     facetId: string;
     reason: OpenEnum<"unsupported" | "timeout">;
-}
+};
 /**
  * Per-query facet counts (MG-1010) — present ONLY when the request sent
  * `facetCounts`. `counts` is keyed by requested facet id; every requested
  * facet not in `absent` has an entry, including empty ones. `poolSize` is
  * present exactly when the counts are pool-derived.
  */
-export interface SearchFacets {
+export type SearchFacets = {
     poolSize?: number;
     requested: string[];
     absent: SearchAbsentFacet[];
     counts: Record<string, SearchFacetCount>;
-}
+};
 /**
  * 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`).
+ * {@link SearchCardItem}s. Every other field is shared.
  *
- * 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.
+ * A PAGE, NOT A CORPUS. `results.length` is what you were handed; follow
+ * `cursor` for the rest. "I found 24 materials" is wrong whenever `limit` was
+ * 24.
  */
-export interface SearchData extends SearchResponseExplainReceipts {
+export type SearchData = {
     /** Result attribution — see {@link ResponseAttribution}. `basis` is `mode` verbatim here. */
     attribution?: ResponseAttribution;
+    /**
+     * Present when a word no material carries was corrected before the search
+     * ran: the page shows results for `to` (ADR 0031).
+     */
+    correctedQuery?: {
+        from: string;
+        to: string;
+    };
     view: OpenEnum<"full" | "card">;
     /** THIS PAGE. Its length is a page size, never a total. */
     results: SearchResultItem[];
-    suggestions: SearchSuggestion[];
+    /** Always empty: the one search offers no refinements. */
+    suggestions: never[];
     mode: SearchMode;
-    /**
-     * Which dense text lane answered, when one did (MG-1796). `image-text` — the
-     * query carried evidence it describes appearance, so it was ranked against
-     * image vectors; `variant-text` — ranked against each variant's written
-     * portrait.
-     *
-     * ABSENT means the answer did not come from the dense text arm at all: `mode`
-     * was never `text`, or the text arm resolved without a lane. Absence is
-     * UNKNOWN and never a default of `image-text` — treating it as one asserts a
-     * dense reading of a lexical, colour or browse answer. Absent too from any
-     * response produced by a server predating MG-1793.
-     *
-     * An {@link OpenEnum} because the lane vocabulary can grow: a value you do
-     * not recognise is a lane this client predates, not a malformed response.
-     */
-    textLane?: OpenEnum<"image-text" | "variant-text">;
+    /** The first result's rank score, 1. */
     maxScore: number;
     cursor?: Cursor;
-    window?: SearchWindowReceipt;
-    rerank?: SearchRerankReport;
-    /** Hard compound eligibility and abundance receipts, when applied. */
-    colourConstraint?: CompoundColourConstraintReceipt;
-    formConstraint?: CompoundFormConstraintReceipt;
-    /** Explain-only receipt of the query shape and transform ledger that ran. */
-    plan?: SearchExecutionPlan;
-    counts?: SearchCounts;
-    /**
-     * The `#rrggbb` colours the colour signal ACTUALLY ran on, after
-     * minor-proportion accents were dropped. Present whenever the request carried
-     * explicit `colours`. Compare against your request: a difference means the
-     * search that ran is not the search that was asked for.
-     */
-    effectiveColours?: string[];
-    /**
-     * Colours removed from the query for carrying a `weight` below the 5% accent
-     * threshold. EMPTY is the normal case. Non-empty and the dropped colours are
-     * absent from colour retrieval and ranking entirely — they did not merely
-     * rank low. To keep a small accent in the query, give it `role: "accent"`.
-     */
-    droppedColours?: string[];
-    /** Per-query facet counts — present ONLY when the request sent `facetCounts`. */
-    facets?: SearchFacets;
-    /** Receipt that narrows the exact finalized pool behind lower-bound facets. */
-    refinement?: SearchRefinementReceipt;
+    /** One or more sentences written for a person; absent when there is nothing to say. */
     note?: string;
     timings?: Record<string, number>;
-    /** A detected mood term overridden by a stronger colour reading. */
-    supersededMoodId?: string;
-    /**
-     * Explicit standard-search mood reading; null ids mean no selected mood.
-     * Absent when mood was not evaluated or an older server produced the result.
-     */
-    moodInterpretation?: MoodInterpretation;
-    /**
-     * Present when the query had multiple defensible readings. Says which one
-     * ran, or leaves every reading non-default when the engine chose none. Every
-     * reading carries a complete executable replacement request.
-     */
-    disambiguation?: SearchDisambiguation;
-    /** Structured receipt of the standard query-understanding decisions. */
-    understanding?: QueryUnderstanding;
-    /**
-     * The corpus this page AND its `counts` were drawn from — present ONLY when
-     * the request narrowed it. ABSENT means the whole graph: every material
-     * MaterialGraph knows, orderable or not. Read it alongside `counts`: a short
-     * page under a scope is a small SCOPED corpus, not a truncated one.
-     */
-    corpusScope?: CorpusScopeReceipt;
     /** Echo of the resolved query input (raw image bytes/vector are never echoed). */
     query?: Record<string, unknown>;
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
     seed?: MaterialTile | Record<string, unknown>;
-}
-export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
-export interface ColourFacetTerm {
-    id: string;
-    label: string;
-    aliases: string[];
-    variants: number;
-    brands: number;
-}
-export interface ColourFacetDictionary {
-    attributeId: ColourDictionaryId;
-    name: string;
-    description: string;
-    terms: ColourFacetTerm[];
-}
-export interface ColourFacetsResponse {
-    count: number;
-    dictionaries: ColourFacetDictionary[];
-}
-export interface CategoryNode {
-    key: string;
-    name: string;
-    parentKey: string | null;
-    path: string;
-    level: OpenEnum<"group" | "type">;
-}
-export interface TaxonomyResponse {
-    count: number;
-    categories: CategoryNode[];
-}
-export interface DemandMomentum {
+} & SearchResponseExplainReceipts;
+export type DemandMomentum = {
     state: OpenEnum<"rising" | "fading" | "stable" | "emerging" | "insufficient_volume">;
     percentChange: number | null;
     trailingSpecCount: number;
     priorSpecCount: number;
-}
-export interface CompanionDemand {
+};
+export type CompanionDemand = {
     specCount: number;
     projectCount: number;
     momentum: DemandMomentum | null;
-}
-export interface ProjectTypeShare {
+};
+export type ProjectTypeShare = {
     projectType: string;
     projectCount: number;
-}
+};
 /**
  * A pairing item from the behavioural arm — real order evidence, or board
  * curation when this seed has no order edges.
@@ -499,9 +374,15 @@ export interface ProjectTypeShare {
  *
  * See {@link ColourPairing} for the third, non-evidential arm.
  */
-export interface CospecPairing {
+export type CospecPairing = {
     /** The evidence tier. `cospec` = orders; `considered` = boards. Read it before phrasing. */
     source: "cospec" | "considered";
+    /**
+     * Membership of the requested `corpusScope`: true in, false out, null when
+     * the graph cannot say. Absent when no narrowing scope was asked for. It
+     * flags, it never removes (MG-2292).
+     */
+    inScope?: boolean | null;
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     brand: string;
@@ -536,29 +417,34 @@ export interface CospecPairing {
     topProjectTypes: ProjectTypeShare[];
     /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
-}
+};
 /**
  * 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 {
+export type ColourPairing = {
     source: "colour";
     score: number;
+    /**
+     * Membership of the requested `corpusScope`: true in, false out, null when
+     * the graph cannot say. Absent when no narrowing scope was asked for. It
+     * flags, it never removes (MG-2292).
+     */
+    inScope?: boolean | null;
     /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
-}
+} & MaterialTile;
 export type PairingOrderMode = "relevance" | "lightness_asc" | "lightness_desc";
-export type PairingCorpus = "all" | "material_bank";
-export interface PairingRanking {
+export type PairingRanking = {
     anchorColourSimilarity: number | null;
     lightness: number | null;
     anchorColourSimilarityMeasurable: boolean;
     lightnessMeasurable: boolean;
     basis: OpenEnum<"dominant_colour_oklab">;
-}
-export interface PairingOrdering {
+};
+export type PairingOrdering = {
     requested: OpenEnum<PairingOrderMode>;
     applied: OpenEnum<PairingOrderMode>;
     direction: OpenEnum<"ascending" | "descending">;
@@ -570,14 +456,14 @@ export interface PairingOrdering {
     };
     missingValues: OpenEnum<"last">;
     tieBreak: OpenEnum<"variantId_asc">;
-}
+};
 /**
  * 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 {
+export type PairingsResponse = {
     seed: MaterialTile;
     /** A rail, not a ranked corpus — mixed evidence tiers, capped by `limit`. */
     items: PairingItem[];
@@ -598,70 +484,86 @@ export interface PairingsResponse {
     ordering?: PairingOrdering;
     /** Opaque continuation bound to the seed, filters, corpus, and order. */
     nextCursor?: Cursor;
-}
-export interface MaterialResponse {
+};
+export type MaterialResponse = {
     material: MaterialDetail;
-    /** Present only when `include: "siblings"` was requested. */
-    siblings?: SiblingTile[];
-}
-export interface SiblingsResponse {
-    siblings: SiblingTile[];
-}
-/**
- * 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[];
-    /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
-    missingIds: VariantId[];
-}
-/**
- * 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[];
-    /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
-    missingIds: VariantId[];
-}
-export interface SuggestColourResponse {
-    suggestions: Array<{
+};
+export type SuggestColourResponse = {
+    suggestions: {
         term: string;
         hex: string;
         libraryId?: string;
         kind: string;
-    }>;
-}
-export interface AttributeCandidate {
-    attributeId: string;
+    }[];
+};
+/**
+ * How a {@link AttributeListItem} matched the query. Declared here rather than
+ * imported: this package is published, so it may not reach across into
+ * `@materialgraph/products`, whose `listAttributesResultSchema` is the source
+ * of truth this wire type tracks. `method` is deliberately open - a server
+ * that grows a method must not break an older client.
+ */
+export type AttributeMatch = {
+    method: OpenEnum<"exact" | "alias" | "fuzzy" | "vector">;
+    /** The id, name or alias that matched, or null for a match by meaning. */
+    matchedText: string | null;
+    /** Fuse distance, 0 best. Compares only within one method. */
+    distance?: number;
+    /** Cosine similarity, 1 best. Compares only within one method. */
+    similarity?: number;
+};
+/** One attribute definition on a `listAttributes()` page. */
+export type AttributeListItem = {
+    id: string;
     name: string;
     description: string;
-    score: number;
-    facetable: boolean;
+    valueKind: string;
+    unitId: string | null;
+    /** The value dictionary its values come from, or null. */
+    dictionaryId: string | null;
+    blockIds: string[];
+    /** The `listVariants()` filter ops it accepts; empty when it cannot filter on it. */
+    filterOps: FilterOp[];
+    filterable: boolean;
+    /** Present only when the page answers a query. */
+    match?: AttributeMatch;
+    /** Live variants in the requested categories stating it; absent without `categoryIds`. */
+    statedBy?: number;
+};
+/** An attribute a block-scoped `listAttributes()` query missed, named with its real blocks. */
+export type OutsideScopeAttribute = {
+    id: string;
+    name: string;
     blockIds: string[];
-}
-export interface ResolveAttributeResponse {
-    query: string;
-    candidates: AttributeCandidate[];
-}
+};
+export type ListAttributesResult = {
+    items: AttributeListItem[];
+    /** Page one only: matches outside `blockIds` ranking above the best item. Absent when the check did not apply. */
+    outsideScope?: OutsideScopeAttribute[];
+    /** Live variants across the requested categories; absent without `categoryIds`. */
+    liveVariants?: number;
+    pageInfo: {
+        endCursor: string | null;
+        hasNextPage: boolean;
+    };
+};
 export type * from "./catalog-discovery-types.js";
 export type * from "./resolve-types.js";
 export type * from "./resolve-colour-types.js";
 export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
-export interface WhoamiResponse {
+export type WhoamiResponse = {
     principal: string;
     scopes: string[];
-}
+};
 /** A single colour entry in a search palette — exactly one of `hex` or `name`. */
-export interface ColourInput {
+export type ColourInput = {
     hex?: string;
     name?: string;
     weight?: number;
     role?: OpenEnum<"any" | "is" | "accent">;
     sourceName?: string;
-}
+};
 /** A raw incoming image to search by. */
 export type SearchImageInput = {
     type: "url";
@@ -670,21 +572,10 @@ export type SearchImageInput = {
     type: "base64";
     data: string;
 };
-export type { SearchGetParams, SearchInput } from "./search-request-types.js";
-/** 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">;
-}
+export type { SearchGetParams, SearchIndexFilter, SearchInput, } from "./search-request-types.js";
+export type { SearchIndexPlan, SearchPlanReceipt, } from "./search-index-plan-types.js";
 /** Options for a pairings read. */
-export interface PairingsOptions {
+export type PairingsOptions = {
     /** Comma-separated coarse category display names; filters both arms. */
     categories?: string;
     /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
@@ -693,34 +584,33 @@ export interface PairingsOptions {
     sampledOnly?: boolean;
     /** Graph-owned order applied within fixed cospec → considered → colour tiers. */
     order?: PairingOrderMode;
-    /** Optional Material Bank/orderable gate; requires an explicit `order`. */
-    corpus?: PairingCorpus;
+    /** Flags each item's `inScope` against this scope; never narrows the rail. */
+    corpusScope?: CorpusScope;
     /** The previous response's `nextCursor`, passed back verbatim. */
     cursor?: Cursor;
-}
-/** Options for `catalog/attributes/resolve`. */
-export interface ResolveAttributeOptions {
-    limit?: number;
-    facetableOnly?: boolean;
-}
-/** Options for `search/specifications`. */
-export interface BySpecOptions {
+};
+/** Options for `listAttributes()` (GET `/api/v1/catalog/attributes`). */
+export type ListAttributesOptions = {
+    /** An attribute id, name, misspelling or meaning, e.g. "reduces echo". */
+    query?: string;
+    /** Keep attributes in any of these blocks. */
+    blockIds?: string[];
+    /** Category ids from `categories.list()`; keeps attributes their templates carry. */
+    categoryIds?: string[];
+    /** Keep only attributes `listVariants()` can filter on. */
+    filterableOnly?: boolean;
+    /** Items per page, 1 to 50. Default 20. */
     limit?: number;
-    /**
-     * Numeric range criteria as `attribute:min..max` strings, ANDed with the
-     * `spec` criteria. Build them with `specRangeCriterion` rather than by hand —
-     * both bounds are inclusive and at least one is required, and a hand-built
-     * token with neither is refused by the server rather than matching everything.
-     */
-    ranges?: string[];
-}
+    /** `pageInfo.endCursor` from the previous page, with the same query and scope. */
+    cursor?: 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 {
+export type DemandQuarter = {
     quarter: string;
     specCount: number;
     projectCount: number;
-}
+};
 /**
  * Which behavioural signal a demand read is scoped to — and therefore what a
  * number drawn from it may honestly be called.
@@ -736,12 +626,12 @@ export interface DemandQuarter {
  */
 export type DemandSignal = OpenEnum<"sampled" | "considered" | "specified">;
 export type * from "./demand-batch-types.js";
-export interface ExtractedPalette {
-    colors: Array<{
+export type ExtractedPalette = {
+    colors: {
         hex: string;
         name: string;
         proportion: number;
-    }>;
+    }[];
     dominant: {
         family: string;
         hex: string;
@@ -749,108 +639,15 @@ export interface ExtractedPalette {
         oklch: string;
     } | null;
     mood: string;
-}
-export interface ExtractPaletteResponse {
+};
+export type ExtractPaletteResponse = {
     palette: ExtractedPalette | null;
-}
+};
 export type * from "./spec-facet-types.js";
-export interface ApplicableSpecAttribute {
-    id: string;
-    name: string;
-    valueKind: string;
-    required: boolean;
-}
-export interface ApplicableSpecBlock {
-    blockId: string;
-    name: string;
-    applicability: OpenEnum<"required" | "recommended" | "optional" | "unusual">;
-    attributes: ApplicableSpecAttribute[];
-}
-export interface ApplicableSpecsResponse {
-    found: boolean;
-    productType: {
-        id: string;
-        name: string;
-    } | null;
-    blocks: ApplicableSpecBlock[];
-    hint?: string;
-}
-export interface GlossaryAttributeMatch {
-    kind: "attribute";
-    id: string;
-    name: string;
-    description: string;
-    valueKind: string;
-    unit?: string;
-    facetable: boolean;
-    comparable: boolean;
-    dictionaryId?: string;
-    usedInBlocks: string[];
-}
-export interface GlossaryValueMatch {
-    kind: "value";
-    id: string;
-    label: string;
-    description?: string;
-    aliases: string[];
-    dictionaryId: string;
-    dictionaryName: string;
-    attributeIds: string[];
-}
-export interface GlossaryTermResponse {
-    found: boolean;
-    term: string;
-    match: GlossaryAttributeMatch | GlossaryValueMatch | null;
-    alternates?: Array<{
-        kind: OpenEnum<"attribute" | "value">;
-        id: string;
-        label: string;
-    }>;
-}
-export interface BrandProfile {
-    id: string;
-    slug: string;
-    name: string;
-    marketSegment: string;
-    headquartersCity: string | null;
-    headquartersCountry: string | null;
-    parentBrand: {
-        id: string;
-        name: string;
-    } | null;
-    positioning: string | null;
-    ownershipType: string | null;
-    foundedYear: number | null;
-    description: string | null;
-    website: string | null;
-}
-export interface BrandProfileResponse {
-    found: boolean;
-    query: string;
-    brand: BrandProfile | null;
-    /** Trade / spec signals ON RECORD, keyed by attribute id. Absent = no value held (never infer false). */
-    trade: Record<string, boolean | string>;
-    links: Array<{
-        label: string;
-        url: string;
-    }>;
-    alternates: Array<{
-        id: string;
-        name: string;
-    }>;
-}
 /** Body for `POST /api/v1/search/palettes/extract`. */
-export interface ExtractPaletteInput {
+export type ExtractPaletteInput = {
     /** The query image as a data URI or bare base64 string. */
     image: string;
     /** Max palette swatches to return (default 6). */
     max?: number;
-}
-/** Options for a cacheable GET batch read (`materialsCached`). */
-export interface MaterialsBatchGetOptions extends MaterialsBatchOptions {
-}
-/** Options for `brands/{brandSlug}`. */
-export interface BrandOptions {
-    /** Alternate fuzzy query; takes precedence over the path slug when present. */
-    q?: string;
-}
+};