@instruments/materialgraph 0.9.1 → 0.11.0

package/search-request-types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @module search-request-types
+ * The two request shapes for the `/search` surface — the POST JSON body and the
+ * GET query-string form. Split out of `types.ts` so neither file outgrows the
+ * repo's source-size gate; every name here is re-exported from `types.ts`, so
+ * no import path changes.
+ */
+import type { Cursor, VariantId } from "./identifiers.js";
+import type { SearchFilter } from "./search-refinement-types.js";
+import type { ColourInput, OpenEnum, SearchImageInput } from "./types.js";
+/**
+ * The POST `/search` JSON body — the `searchMaterials` contract. Every field is
+ * optional; supply at least one signal (`text`, `colours`, `mood`, `similarTo`,
+ * or `image`). Passed through to the server verbatim.
+ */
+export interface SearchInput {
+    text?: string;
+    textModes?: Array<OpenEnum<"visual" | "lexical">>;
+    colours?: ColourInput[];
+    colourLogic?: OpenEnum<"all" | "any">;
+    colourTolerance?: OpenEnum<"tight" | "normal" | "loose">;
+    colourAppearance?: {
+        lightness?: {
+            min: number;
+            max: number;
+        };
+        warmth?: {
+            min: number;
+            max: number;
+        };
+    };
+    mood?: string;
+    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    /**
+     * Seed a visual search from an existing variant's image (`variantId`), from a
+     * Material Bank SKU (`materialBankId`), or from a pre-computed image vector
+     * (`vector`).
+     *
+     * `materialBankId` exists so a caller already holding a SKU does not have to
+     * ask us to translate it before it can ask us anything useful — one call, not
+     * two. It resolves to the variant server-side and then behaves identically to
+     * the `{ variantId }` form, seed verdicts included. A SKU that names no
+     * variant is a 400 carrying the offending value: never an empty result set,
+     * never a silent fall back to unseeded search.
+     *
+     * The `{ vector }` form carries no seed variant, so it is the only one
+     * `verdicts` cannot diff a candidate against.
+     */
+    similarTo?: {
+        variantId: VariantId;
+    } | {
+        materialBankId: string;
+    } | {
+        vector: string;
+    };
+    /**
+     * Canonical variants that must not appear in the returned page. The server
+     * applies these exclusions before the page limit, so consumers can request
+     * unseen results without shortening an already-bounded page client-side.
+     * Maximum 256; ids are opaque.
+     */
+    excludeVariantIds?: VariantId[];
+    image?: SearchImageInput;
+    category?: {
+        boost?: string;
+        filter?: string[];
+    };
+    weights?: {
+        image?: number;
+        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[];
+    /** Page size — the size of ONE page, never a bound on the match set. */
+    limit?: number;
+    /** 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.
+     * Without it the response states NO total — and a page size is not one.
+     */
+    count?: boolean;
+    /**
+     * Opt-in per-query facet counts (MG-1010): up to 10 facet ids — `"brand"`,
+     * `"category"`, or spec attribute ids — and the response carries a `facets`
+     * block counting each facet's values WITHIN this query's match set. An
+     * unknown id is a 400 naming it; a known but uncountable id lands in
+     * `facets.absent`. Absent = no `facets` in the response, no counting cost.
+     */
+    facetCounts?: string[];
+    /** 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">;
+    /**
+     * Budget profile for the search primitive.
+     *
+     * `"search"` (default) is the full engine. `"typeahead"` is the as-you-type
+     * profile: lexical-only with prefix match on the final token, forced
+     * `view: "card"`, `limit` capped at 24, and no mood/colour detection tiers,
+     * semantic fallback, category boost, colour rerank, refinement suggestions,
+     * counts, or meanings. `textModes` is ignored under typeahead.
+     */
+    intent?: OpenEnum<"search" | "typeahead">;
+    /**
+     * Which corpus to answer from.
+     *
+     * **ABSENT means the WHOLE GRAPH** — every material MaterialGraph knows,
+     * orderable or not. Absence is never a narrower default, so a caller that
+     * says nothing gets materials it may not be able to buy.
+     * `"materialBankOrderable"` restricts retrieval to materials carrying a
+     * Material Bank identity. `"designShopOrderable"` restricts it to what a
+     * consumer can buy on DesignShop today — about 16,200 materials, with the
+     * products DesignShop hides from browse excluded.
+     *
+     * A scope answers what is BUYABLE. It never answers what is SUITABLE: scope
+     * on channel, then refine on sector. A trade-only material can be right for a
+     * room and still unbuyable, and most of what a consumer can buy is
+     * commercial-suited product.
+     *
+     * The scope is applied INSIDE the query: `limit` fills with eligible rows,
+     * `counts` describe the SCOPED corpus, and the response echoes the scope.
+     * That is what post-filtering a page cannot give you — a client-side filter
+     * shortens the page exactly when the query drifts toward the corpus beyond
+     * the Material Bank feed, which is unpredictable from outside.
+     */
+    corpusScope?: OpenEnum<"all" | "materialBankOrderable" | "designShopOrderable">;
+    /**
+     * OPS/AUDIT escape hatch — do NOT use for normal search. Default behaviour
+     * (absent or false) excludes sampling-artifact products: multi-swatch sample
+     * cards, which are orderable samples and never specifiable materials.
+     */
+    includeSamplingArtifacts?: boolean;
+}
+/** Query-string params for the GET `/search` form. */
+export interface SearchGetParams {
+    q?: string;
+    colours?: string;
+    logic?: OpenEnum<"all" | "any">;
+    mood?: string;
+    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    tol?: OpenEnum<"tight" | "normal" | "loose">;
+    /** 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">;
+    /** "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">;
+}

package/search-request-types.js

@@ -0,0 +1 @@
+export {};

package/search-result-validation.js

@@ -12,17 +12,33 @@ export const VERDICT_STATES = [
 /** `attributeVerdictSchema.strength`. */
 export const VERDICT_STRENGTHS = ["required", "preferred"];
 /** `verdictBaselineSchema` discriminant — the four arms of what a cell was judged against. */
-export const VERDICT_BASELINE_KINDS = ["term", "presence", "seed", "image"];
+export const VERDICT_BASELINE_KINDS = [
+    "term",
+    "presence",
+    "seed",
+    "image",
+];
 /** The `image` baseline arm's own `source` enum. */
 export const VERDICT_IMAGE_SOURCES = ["variant", "vector"];
 /** `verdictDeviationSchema.direction`. */
-export const VERDICT_DEVIATION_DIRECTIONS = ["above", "below", "other"];
+export const VERDICT_DEVIATION_DIRECTIONS = [
+    "above",
+    "below",
+    "other",
+];
 /** `verdictTrustGapSchema` — why a real value did not clear the trust bar. */
-export const VERDICT_TRUST_GAPS = ["below_confidence", "basis_unmet", "proposed"];
+export const VERDICT_TRUST_GAPS = [
+    "below_confidence",
+    "basis_unmet",
+    "proposed",
+];
 /** `verdictGradeSchema` — the rolled-up card grade. */
 export const VERDICT_GRADES = ["meets_all", "close", "hard_no"];
 /** `visualMeaningSchema.basis` — where a meaning came from. */
-export const VISUAL_MEANING_BASES = ["canonical_attribute", "image_colour_analysis"];
+export const VISUAL_MEANING_BASES = [
+    "canonical_attribute",
+    "image_colour_analysis",
+];
 // ── Leaf checks ──────────────────────────────────────────────────────────────
 /** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
 function checkPaletteSwatch(value, what, fail) {
@@ -165,6 +181,7 @@ export function checkSearchResultItem(value, what, fail) {
         checkSignals(record.signals, `${what}.signals`, fail);
     requireOptionalBoolean(record.retired, `${what}.retired`, fail);
     requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
+    requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
     if (record.siblingCount !== undefined) {
         requireIntegerAtLeast(record.siblingCount, `${what}.siblingCount`, fail, 1);
     }

package/slot-pool-types.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Hand-mirrored wire types for the slot-pool surface
+ * (`POST /api/v1/schemes/pools`, operation `slot_pools`, MG-1301). Like the rest
+ * of the SDK these interfaces carry NO runtime dependency on any
+ * `@materialgraph/*` package — they mirror the `SlotPoolsRequest` /
+ * `SlotPoolsResponse` shapes in `apps/web/public/openapi.yaml`.
+ *
+ * THE QUESTION IT ANSWERS: "for each of these slots, what should I be choosing
+ * between?" One call, up to 24 slots, one ranked and gated pool each. There is
+ * no project and no run — the request is self-contained and the ownership of the
+ * work stays with you.
+ *
+ * THREE THINGS TO READ CORRECTLY, because getting them wrong turns a careful
+ * answer into a false one:
+ *  1. A pool with a `shortfall` of kind `search-failed` was NOT answered. The
+ *     other pools in the same response were. Never read that empty pool as
+ *     "nothing matched".
+ *  2. `not_evaluated` and `missing` are not `failed`. The first means the engine
+ *     did not check the criterion at the tier that ran; the second means the
+ *     material holds no accepted value for it. Only `failed` means a value
+ *     exists and does not satisfy the ask.
+ *  3. `eligible: false` does not mean "bad". It means this candidate cannot be
+ *     placed automatically — read `flags` for which of the reasons applies.
+ *
+ * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
+ * so a new server value still type-checks; objects are read structurally.
+ */
+import type { VariantId } from "./identifiers.js";
+import type { OpenEnum } from "./types.js";
+/**
+ * One requirement or preference. Request-side, so this is a STRICT union.
+ * `attribute` asks for a canonical term, `attribute-presence` merely that the
+ * attribute is recorded, `attribute-numeric` a one-sided bound. `unresolved`
+ * carries brief language nothing bound to — it is never a filter and never
+ * blamed for a coverage shortfall.
+ */
+export type SlotPoolCriterion = {
+    kind: "attribute";
+    attributeId: string;
+    term: string;
+    raw: string;
+} | {
+    kind: "attribute-presence";
+    attributeId: string;
+    raw: string;
+} | {
+    kind: "attribute-numeric";
+    attributeId: string;
+    comparator: "at-least" | "at-most";
+    value: number;
+    unit?: string;
+    raw: string;
+} | {
+    kind: "unresolved";
+    raw: string;
+    suggestion?: {
+        attributeId: string;
+        term?: string;
+    };
+    coverageNote?: string;
+};
+/** A colour cue for a slot. Colours rerank within the retrieved set; they never admit. */
+export interface SlotPoolColourCue {
+    /** `#rrggbb`. */
+    hex: string;
+    name?: string;
+}
+/**
+ * What to do with a candidate the catalogue no longer lists. Neither value ever
+ * marks such a candidate eligible — the policy decides only whether it is
+ * returned at all.
+ */
+export type SlotPoolAvailabilityPolicy = "flag-unavailable" | "exclude-unavailable";
+/** One slot of work. Self-contained: nothing in it identifies a project. */
+export interface SlotPoolTask {
+    /**
+     * YOUR key for this task, opaque to MaterialGraph and returned verbatim on the
+     * matching pool. This is how you correlate 24 results; it is never parsed,
+     * normalised or reused as a server id. Must be unique within a request.
+     */
+    taskKey: string;
+    /**
+     * The catalog category. OMITTING IT yields an empty pool with a `no-category`
+     * shortfall — category is the only cross-kind gate, and retrieval will not
+     * rank an ungated corpus.
+     */
+    category?: string;
+    /** A short VISUAL description of the material wanted — not a keyword list. */
+    intent?: string;
+    required?: SlotPoolCriterion[];
+    preferred?: SlotPoolCriterion[];
+    colours?: SlotPoolColourCue[];
+    /** Rank this task around an already-chosen variant. Ids are opaque tokens. */
+    anchorSeed?: {
+        variantId: VariantId;
+    };
+    exclude?: {
+        variantIds?: VariantId[];
+        brandSlugs?: string[];
+    };
+    availability?: SlotPoolAvailabilityPolicy;
+    /** Candidates returned for this task. Max 48, default 12. */
+    limit?: number;
+}
+/** Body for `POST /api/v1/schemes/pools` ({@link MaterialGraphClient.slotPools}). */
+export interface SlotPoolsRequest {
+    /** Up to 24 tasks. Each is independent: one failing costs that one. */
+    tasks: SlotPoolTask[];
+    /**
+     * Include the co-specification evidence among the returned candidates
+     * (default true). One bounded read — never one request per candidate.
+     */
+    coSpecification?: boolean;
+}
+/** The six live verdict states, plus the two legacy tokens older rows carry. */
+export type SlotPoolVerdictState = OpenEnum<"matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated">;
+/** One cell of a candidate's report card against one criterion. */
+export interface SlotPoolVerdictCell {
+    attributeId: string;
+    state: SlotPoolVerdictState;
+    strength: OpenEnum<"required" | "preferred">;
+    baseline: {
+        kind: "term";
+        term: string;
+    } | {
+        kind: "presence";
+    } | {
+        kind: "seed";
+        variantId: VariantId;
+    } | {
+        kind: "image";
+        source: OpenEnum<"variant" | "vector">;
+        variantId: VariantId | null;
+    };
+    /** The candidate's OWN accepted value, or null when it holds none. */
+    value: string | null;
+    deviation: {
+        direction: OpenEnum<"above" | "below" | "other">;
+        delta: number | null;
+        unit: string | null;
+        label: string;
+    } | null;
+    confidence: number | null;
+    /**
+     * WHERE the value came from — it ranks the SOURCE, not the accuracy. It says
+     * nothing about whether the value is right.
+     */
+    sourceBasis: string | null;
+    trustGap: OpenEnum<"below_confidence" | "basis_unmet" | "proposed"> | null;
+}
+/** Why a candidate is labelled. An eligible candidate carries none of these. */
+export type SlotPoolFlag = OpenEnum<"below-floor" | "required-not-applied" | "discontinued" | "superseded" | "unverified-value">;
+export type SlotPoolAvailability = OpenEnum<"available" | "discontinued" | "superseded" | "unknown">;
+/** The declared successor of a withdrawn material, one hop only. */
+export interface SlotPoolSuccessor {
+    variantId: VariantId;
+    brandSlug: string;
+    productId: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    availability: SlotPoolAvailability;
+}
+/**
+ * The features a composer scores on. Colours are EXTRACTED FROM PRODUCT IMAGERY
+ * — visual likeness, never a declared colour specification. An empty `palette`
+ * or `attributes` means nothing is on record, never that the material has none.
+ */
+export interface SlotPoolCandidateFeatures {
+    colour: {
+        dominantHex: string | null;
+        hsl: {
+            h: number;
+            s: number;
+            l: number;
+        } | null;
+        oklab: {
+            l: number;
+            a: number;
+            b: number;
+        } | null;
+        chroma: number | null;
+        vibrancy: number | null;
+        sourceBasis?: string;
+    };
+    palette: {
+        hex: string;
+        proportion: number;
+        name?: string | null;
+        oklab?: {
+            l: number;
+            a: number;
+            b: number;
+        };
+    }[];
+    attributes: {
+        attributeId: string;
+        term: string;
+    }[];
+    dimensions: Record<string, unknown>[] | null;
+}
+export interface SlotPoolCandidate {
+    variantId: VariantId;
+    productId: string;
+    brandSlug: string;
+    brand: string;
+    product: string;
+    variant: string;
+    category: string | null;
+    materialBankId: string | null;
+    imageUrl: string | null;
+    availability: SlotPoolAvailability;
+    supersededBy: SlotPoolSuccessor | null;
+    /**
+     * True only when every required criterion was applied, the catalogue still
+     * lists the material, and no exclusion touched it. Anything else needs a
+     * human decision — read `flags` for which reason.
+     */
+    eligible: boolean;
+    flags: SlotPoolFlag[];
+    score: {
+        /** Normalised to [0,1] against the best score on THIS pool's page. */
+        retrieval: number;
+        /** `unverified` + `not_evaluated` cells. A soft penalty, not a failure count. */
+        unknownCount: number;
+        verdictCounts: {
+            matched: number;
+            deviated: number;
+            failed: number;
+            unverified: number;
+            missing: number;
+            notEvaluated: number;
+        };
+    };
+    verdict: {
+        cells: SlotPoolVerdictCell[];
+        grade: OpenEnum<"meets_all" | "close" | "hard_no">;
+        minConfidence: number | null;
+    };
+    features: SlotPoolCandidateFeatures;
+}
+/**
+ * Why a pool is short. Four different facts, and none of them is "nothing in
+ * the catalogue matches your brief".
+ */
+export type SlotPoolShortfall = {
+    kind: "no-category";
+} | {
+    kind: "category-coverage";
+    category: string;
+    attributeIds: string[];
+    gaps?: ({
+        level: "attribute";
+        attributeId: string;
+    } | {
+        level: "value";
+        attributeId: string;
+        term: string;
+    })[];
+} | {
+    kind: "search-failed";
+    detail: string;
+} | {
+    kind: "no-match";
+    tier: string;
+    consideredCount: number;
+};
+export interface SlotPool {
+    /** Your own key, verbatim. */
+    taskKey: string;
+    category: string | null;
+    /** The relaxation rung the returned candidates were drawn at. */
+    retrievalTier: OpenEnum<"strict" | "presence" | "category-only">;
+    /**
+     * HOW the candidates were retrieved. DERIVED from the retrieval plan and the
+     * pool's receipt — MaterialGraph does not report an arm per candidate.
+     *
+     * It is constant across the relaxation rungs, so it cannot tell you how far
+     * the ladder went. `retrievalTier` beside it names the rung the pool settled
+     * on: the arm says how, the tier says how strictly.
+     */
+    arm: OpenEnum<"visual-text" | "image-similarity" | "none">;
+    candidates: SlotPoolCandidate[];
+    /** How much retrieval scored before this task's own `limit` trimmed the page. */
+    consideredCount: number;
+    returnedCount: number;
+    excludedCount: number;
+    unavailableDroppedCount: number;
+    /**
+     * The criteria nothing on this page could be graded on — a statement about
+     * catalogue COVERAGE, never about the candidates.
+     */
+    unknownCoverage: {
+        evaluatedCriteria: number;
+        /** Every returned candidate graded `not_evaluated` on these. */
+        uncheckedCriteria: string[];
+        /** Every returned candidate graded `missing` on these. */
+        unheldCriteria: string[];
+    };
+    shortfall: SlotPoolShortfall | null;
+    seededFrom: {
+        variantId: VariantId;
+    } | null;
+    warnings: string[];
+}
+/**
+ * The sparse pairing graph among the returned candidates. Each unordered pair
+ * appears ONCE and the relation is symmetric. An empty `edges` under a null
+ * `datasetSessionId` means the dataset is absent, NOT that these materials are
+ * never specified together.
+ */
+export interface SlotPoolCoSpecification {
+    edges: {
+        from: VariantId;
+        to: VariantId;
+        projectCount: number;
+    }[];
+    coverage: {
+        candidateCount: number;
+        coveredCount: number;
+        truncated: boolean;
+        datasetSessionId: string | null;
+        window: string;
+        signal: string;
+    };
+}
+/** The `200` body from `POST /api/v1/schemes/pools`. */
+export interface SlotPoolsResponse {
+    versions: {
+        contract: string;
+        retrieval: string;
+        evaluator: string;
+        dataset: {
+            coSpecificationSessionId: string | null;
+        };
+    };
+    /** One pool per task, in request order. Correlate by `taskKey`, not by index. */
+    pools: SlotPool[];
+    coSpecification: SlotPoolCoSpecification | null;
+    summary: {
+        tasks: number;
+        eligibleCandidates: number;
+        flaggedCandidates: number;
+        tasksWithEligibleCandidates: number;
+        tasksWithoutEligibleCandidates: number;
+        /** Non-zero means some tasks were NOT answered; their pools say so. */
+        searchFailed: number;
+        noCategory: number;
+        categoryCoverage: number;
+        noMatch: number;
+    };
+    /**
+     * CALL VOLUME — how many of each bounded operation the request performed.
+     *
+     * Never a cost or token figure. Slot retrieval is database and embedding work
+     * and does not go through the model-call path that carries token and spend
+     * accounting, so no such figure exists for it. Do not render these as usage
+     * or spend.
+     */
+    calls: {
+        searchesRun: number;
+        searchesFailed: number;
+        candidatesConsidered: number;
+        candidatesReturned: number;
+        hydrationBatches: number;
+        coSpecificationQueries: number;
+    };
+    warnings: string[];
+}

package/slot-pool-types.js

@@ -0,0 +1 @@
+export {};

package/source-material-validation.d.ts

@@ -1,3 +1,7 @@
-import type { SourceMaterialBatchDetail } from "./run-types.js";
+import type { PostSourceMaterialCommentResult, SourceMaterialBatchDetail, SourceMaterialCommentThread } from "./run-types.js";
 /** Validate a batch-detail body, returning it typed, or throw explaining why. */
 export declare function checkSourceMaterialBatchDetail(value: unknown, batchId: string): SourceMaterialBatchDetail;
+/** Validate a comment-thread body, returning it typed, or throw explaining why. */
+export declare function checkSourceMaterialCommentThread(value: unknown, sourceId: string): SourceMaterialCommentThread;
+/** Validate a posted-comment body, returning it typed, or throw explaining why. */
+export declare function checkPostSourceMaterialCommentResult(value: unknown, sourceId: string): PostSourceMaterialCommentResult;