@instruments/materialgraph 0.10.0 → 0.11.0

package/run-types.d.ts

@@ -105,6 +105,113 @@ export interface SourceImageAnalysis {
     /** ISO-8601 timestamp of the most recent analysis. */
     analysedAt: string;
 }
+/** Who a comment is from, as you SUBMIT it. Not the API principal posting it. */
+export interface SourceMaterialCommentAuthorInput {
+    /** Trimmed, 1–160 characters. Longer or blank is refused by the server. */
+    name: string;
+    /**
+     * Their practice or team; `null` for a note carrying no organisation.
+     * Trimmed, 1–160 characters when present. Nullable, not optional.
+     */
+    organisation: string | null;
+}
+/**
+ * Who a comment is from, as you READ IT BACK.
+ *
+ * `attribution` is the honesty field: nothing verified this name. Render it as
+ * "recorded as from X", never as a statement X signed — the identity that IS
+ * verified is {@link SourceMaterialCommentReply.recordedBy}.
+ */
+export interface SourceMaterialCommentAuthor extends SourceMaterialCommentAuthorInput {
+    /**
+     * How the name got here. `reported` means a caller typed it. {@link OpenEnum}
+     * keeps a newer server value type-checking; treat anything unfamiliar as
+     * unverified.
+     */
+    attribution: OpenEnum<"reported">;
+}
+/** The authenticated principal that recorded a comment. */
+export interface SourceMaterialCommentRecorder {
+    /**
+     * The principal that wrote the row. Comments can only be posted against a
+     * batch the poster owns, so on every comment you can read this is your own.
+     */
+    principalId: string;
+}
+/**
+ * One reply on a source-material file. A reply carries no replies of its own:
+ * threads are one level deep because the database makes a reply-to-reply
+ * unstorable, and this type says so rather than implying a tree.
+ */
+export interface SourceMaterialCommentReply {
+    /** The stored comment id (`smc_…`). Opaque. */
+    commentId: string;
+    author: SourceMaterialCommentAuthor;
+    /** Who recorded it — the audit answer behind the reported name. */
+    recordedBy: SourceMaterialCommentRecorder;
+    body: string;
+    /** ISO-8601 timestamp of the posting. */
+    createdAt: string;
+}
+/** One root remark with the replies that answer it. */
+export interface SourceMaterialComment extends SourceMaterialCommentReply {
+    /** ALWAYS an array. `[]` means nobody answered — never a missing field. */
+    replies: SourceMaterialCommentReply[];
+}
+/** The `200` body of `GET …/sources/{sourceId}/comments`. */
+export interface SourceMaterialCommentThread {
+    /** The file the thread hangs off (`smf_…`). Opaque. */
+    sourceId: string;
+    /**
+     * The thread, oldest root first. ALWAYS an array; `[]` means the file is
+     * yours and nobody has commented on it.
+     */
+    comments: SourceMaterialComment[];
+    /**
+     * `true` when the file holds more comment rows than one read inlines (500),
+     * so `comments` is the oldest of them rather than all of them.
+     */
+    truncated: boolean;
+}
+/** The body of `POST …/sources/{sourceId}/comments`. */
+export interface PostSourceMaterialCommentInput {
+    author: SourceMaterialCommentAuthorInput;
+    /** Trimmed, 1–4000 characters. */
+    body: string;
+    /**
+     * The root comment being answered, or absent for a new remark. Must be a ROOT
+     * comment on the same file: replying to a reply is a 400.
+     */
+    parentCommentId?: string | null;
+    /**
+     * Your own token for this one intended remark, 1–200 characters. Send it and
+     * a retry after a network timeout returns the comment you already posted
+     * rather than a permanent duplicate. Scoped to the file.
+     */
+    idempotencyKey?: string | null;
+}
+/** A comment the server just stored, as a root. */
+export interface StoredSourceMaterialRootComment extends SourceMaterialComment {
+    kind: "root";
+}
+/** A comment the server just stored, as a reply to a root. */
+export interface StoredSourceMaterialReplyComment extends SourceMaterialCommentReply {
+    kind: "reply";
+    /** The root this answers. Present because a reply always has one. */
+    parentCommentId: string;
+}
+/**
+ * What a POST returns, discriminated on `kind`. Switch on it: a `root` carries
+ * an empty `replies`, a `reply` carries `parentCommentId` and no `replies` at
+ * all, because it can never have any.
+ */
+export type StoredSourceMaterialComment = StoredSourceMaterialRootComment | StoredSourceMaterialReplyComment;
+/** The `201` body of `POST …/sources/{sourceId}/comments`. */
+export interface PostSourceMaterialCommentResult {
+    /** The file the comment hangs off (`smf_…`). Opaque. */
+    sourceId: string;
+    comment: StoredSourceMaterialComment;
+}
 /** One file as `GET /api/v1/source-material/{batchId}` returns it. */
 export interface SourceMaterialBatchFile extends SourceMaterialReceiptFile {
     /** Fetchable URL for the stored bytes. */
@@ -115,6 +222,18 @@ export interface SourceMaterialBatchFile extends SourceMaterialReceiptFile {
      * only the trigger changes and this contract does not.
      */
     analyses: SourceImageAnalysis[];
+    /**
+     * The argument about this file, oldest root first. ALWAYS an array; `[]` means
+     * nobody has commented, which is a state to draw rather than an absence to
+     * guess at.
+     */
+    comments: SourceMaterialComment[];
+    /**
+     * `true` when this file holds more comment rows than one read inlines (500),
+     * so `comments` is the oldest of them. `false` on a file whose whole thread
+     * you have, including one nobody has commented on.
+     */
+    commentsTruncated: boolean;
 }
 /**
  * The `200` body of `GET /api/v1/source-material/{batchId}` — the batch, every
@@ -139,6 +258,12 @@ export interface CapabilityInvokeLink {
     href: string;
     method: OpenEnum<"GET" | "POST">;
 }
+/** One human-input checkpoint exposed by a workflow capability. */
+export interface PublicCapabilitySuspension {
+    stepId: string;
+    suspend: Record<string, unknown>;
+    resume: Record<string, unknown>;
+}
 /** One invocable capability from the governed public manifest. */
 export interface PublicCapabilityMetadata {
     publicId: string;
@@ -150,6 +275,7 @@ export interface PublicCapabilityMetadata {
     schemas: {
         input: Record<string, unknown>;
         output: Record<string, unknown>;
+        suspensions?: PublicCapabilitySuspension[];
     };
     sideEffectClass: CapabilitySideEffectClass;
     scopes: CapabilityScope[];
@@ -193,10 +319,16 @@ export interface PublicRun {
     usageJson: Record<string, unknown> | null;
     artifactRefs: PublicRunArtifactRef[] | null;
     failureJson: PublicRunFailure | null;
+    /** The current typed question payload while this Run is suspended. */
+    suspensionPayload: Record<string, unknown> | null;
     /**
      * The step awaiting input while `status` is `suspended`. Pass it as
      * {@link ResumeRunOptions.stepId} so a stale client cannot resume a step the
      * Run has already moved past.
+     *
+     * Read `suspensionPayload` for the current typed question. The same payload is
+     * also retained on the `suspended` ledger event; composition-specific events
+     * remain available as historical progress records.
      */
     suspensionStepId: string | null;
     eventCursor: number;

package/runs.d.ts

@@ -1,5 +1,5 @@
 import { HttpTransport } from "./http-transport.js";
-import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type ListRunsOptions, type PublicRunListResponse, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type ListRunsOptions, type PostSourceMaterialCommentInput, type PostSourceMaterialCommentResult, type PublicRunListResponse, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type SourceMaterialCommentThread, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
@@ -21,6 +21,40 @@ export declare function uploadSourceMaterial(transport: HttpTransport, input: Up
  * the payload rather than as an undefined three frames away in caller code.
  */
 export declare function getSourceMaterialBatch(transport: HttpTransport, batchId: string, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
+/**
+ * Read one file's comment thread
+ * (`GET /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
+ *
+ * The remarks people left on one uploaded file, oldest root first, each root
+ * carrying the replies that answer it. `comments` is always an array — `[]`
+ * means the file is yours and nobody has said anything about it.
+ *
+ * Author names are REPORTED, never verified: each carries
+ * `author.attribution: "reported"` plus the principal that recorded it in
+ * `recordedBy`. Render "recorded as from X", not "X said".
+ *
+ * `truncated` is `true` when the file holds more rows than one read inlines.
+ *
+ * A file that is not in that batch, or a batch you do not own, raises the same
+ * 404 as a file that never existed.
+ */
+export declare function listSourceMaterialComments(transport: HttpTransport, batchId: string, sourceId: string, signal?: AbortSignal): Promise<SourceMaterialCommentThread>;
+/**
+ * Add one remark to a file's thread
+ * (`POST /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
+ *
+ * `author` is who the comment is FROM — usually the client or a colleague, not
+ * the key posting it — so it is stored and read back as reported attribution.
+ * Pass `parentCommentId` to answer a ROOT comment on the same file; anything
+ * deeper is a 400, because threads are one level deep.
+ *
+ * Pass `idempotencyKey` and a retry after a network timeout returns the comment
+ * you already posted rather than a permanent duplicate.
+ *
+ * The result is discriminated on `kind`: switch on it rather than reaching for
+ * `replies`, which a `reply` does not have.
+ */
+export declare function postSourceMaterialComment(transport: HttpTransport, batchId: string, sourceId: string, input: PostSourceMaterialCommentInput, signal?: AbortSignal): Promise<PostSourceMaterialCommentResult>;
 /** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
 export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */

package/runs.js

@@ -9,7 +9,7 @@ import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 import { findSdkOperation, operationPath, } from "./operations.js";
 import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
-import { checkSourceMaterialBatchDetail } from "./source-material-validation.js";
+import { checkPostSourceMaterialCommentResult, checkSourceMaterialBatchDetail, checkSourceMaterialCommentThread, } from "./source-material-validation.js";
 import { readSseFrames } from "./sse.js";
 function runOperation(operationId) {
     const match = findSdkOperation(operationId);
@@ -86,6 +86,66 @@ export async function getSourceMaterialBatch(transport, batchId, signal) {
     });
     return checkSourceMaterialBatchDetail(body, batchId);
 }
+/**
+ * Read one file's comment thread
+ * (`GET /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
+ *
+ * The remarks people left on one uploaded file, oldest root first, each root
+ * carrying the replies that answer it. `comments` is always an array — `[]`
+ * means the file is yours and nobody has said anything about it.
+ *
+ * Author names are REPORTED, never verified: each carries
+ * `author.attribution: "reported"` plus the principal that recorded it in
+ * `recordedBy`. Render "recorded as from X", not "X said".
+ *
+ * `truncated` is `true` when the file holds more rows than one read inlines.
+ *
+ * A file that is not in that batch, or a batch you do not own, raises the same
+ * 404 as a file that never existed.
+ */
+export async function listSourceMaterialComments(transport, batchId, sourceId, signal) {
+    const body = await transport.requestJson(runOperation("list_source_material_comments"), {
+        pathParams: { batchId, sourceId },
+        signal,
+    });
+    return checkSourceMaterialCommentThread(body, sourceId);
+}
+/**
+ * Add one remark to a file's thread
+ * (`POST /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
+ *
+ * `author` is who the comment is FROM — usually the client or a colleague, not
+ * the key posting it — so it is stored and read back as reported attribution.
+ * Pass `parentCommentId` to answer a ROOT comment on the same file; anything
+ * deeper is a 400, because threads are one level deep.
+ *
+ * Pass `idempotencyKey` and a retry after a network timeout returns the comment
+ * you already posted rather than a permanent duplicate.
+ *
+ * The result is discriminated on `kind`: switch on it rather than reaching for
+ * `replies`, which a `reply` does not have.
+ */
+export async function postSourceMaterialComment(transport, batchId, sourceId, input, signal) {
+    const body = await transport.requestJson(runOperation("post_source_material_comment"), {
+        // Built key by key rather than spread: `parentCommentId` and
+        // `idempotencyKey` are forwarded only when PRESENT, so a caller that
+        // omits them sends a body byte-identical to one that never knew about
+        // them.
+        body: {
+            author: input.author,
+            body: input.body,
+            ...(input.parentCommentId === undefined
+                ? {}
+                : { parentCommentId: input.parentCommentId }),
+            ...(input.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: input.idempotencyKey }),
+        },
+        pathParams: { batchId, sourceId },
+        signal,
+    });
+    return checkPostSourceMaterialCommentResult(body, sourceId);
+}
 /** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
 export function capabilities(transport, signal) {
     return transport.requestJson(runOperation("list_public_capabilities"), {

package/schedule-types.d.ts

@@ -12,6 +12,14 @@
  * ABSENT IS NOT FALSE, enforced structurally: because the column set is fixed,
  * "we do not know" has to be SAID rather than omitted. Read
  * {@link FinishScheduleCell.state} before printing `value`.
+ *
+ * MG-1351 added the schedule's organising principle: every row carries an
+ * {@link FinishScheduleRow.code} L-code under a numbered section, rows arrive in
+ * READING order, slots with nothing specified are served as
+ * {@link FinishSchedule.openSlots}, and a row may carry or-equal
+ * {@link FinishScheduleAlternate}s. Read `alternates` with
+ * {@link FinishSchedule.alternatesResolved}: an empty list means either "we did
+ * not ask" or "there is none", and those are different claims.
  */
 import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
 /** One schedule column: the attribute and its header text. */
@@ -51,8 +59,106 @@ export interface FinishScheduleCell {
  * `hard_no` means a required cell failed on a real value.
  */
 export type FinishScheduleGrade = "meets_all" | "close" | "hard_no";
+/** One numbered section of the schedule, and the heading it prints. */
+export interface FinishScheduleSection {
+    /** The hundreds block, e.g. `100`. Also the base of every line number in it. */
+    code: number;
+    name: string;
+}
+/**
+ * What MaterialGraph claims about an alternate — and never more than it can
+ * support. None of the three means "interchangeable": accepting an alternate is
+ * a specification decision, and this API does not make it.
+ *
+ * `or_equal` matched the specified material's equivalence signature with every
+ * supporting value above its confidence floor. `or_equal_unverified` matched the
+ * same signature on values that did not clear it. `successor` is the brand's own
+ * declared replacement, from a reviewed relationship rather than a spec match —
+ * its verdict cells are `not_evaluated` by construction.
+ */
+export type FinishScheduleAlternateStance = "or_equal" | "or_equal_unverified" | "successor";
+/** One criterion of the equivalence signature an alternate was matched on. */
+export interface FinishScheduleAlternateCriterion {
+    role: "primary_material" | "performance";
+    attributeId: string;
+    term: string;
+}
+/**
+ * Why an alternate is on the row. Every field is evidence, not adjective — a
+ * substitute presented without its basis looks like a decision when it is a
+ * lookup, so this is never absent from an alternate.
+ */
+export interface FinishScheduleAlternateBasis {
+    /** The SPECIFIED variant this alternate was graded against. Opaque. */
+    specifiedVariantId: VariantId;
+    /** The product-type form the signature was projected in; null for a successor. */
+    form: string | null;
+    /** The criteria that matched. Empty for a successor: nothing was matched. */
+    signature: FinishScheduleAlternateCriterion[];
+    /** The seed-relative report card, projected exactly as row cells are. */
+    verdict: {
+        cells: FinishScheduleCell[];
+        grade: FinishScheduleGrade;
+        minConfidence: number | null;
+    };
+}
+/** One or-equal line sitting beneath the specified line it answers. */
+export interface FinishScheduleAlternate {
+    stance: FinishScheduleAlternateStance;
+    /** Opaque — round-trip verbatim into the material lenses. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    variant: string;
+    /**
+     * The colourway, when the catalogue names one. Carried separately because a
+     * substitute's `variant` is frequently the product name repeated, and a line
+     * that cannot name the colour has not named a material.
+     */
+    colour: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    recordUrl: string;
+    /**
+     * Further colourways of this same product that also cleared the signature and
+     * were collapsed into this line. A COUNTED collapse: `0` means this product
+     * offered exactly one match, never that the count is unknown.
+     */
+    otherColourways: number;
+    basis: FinishScheduleAlternateBasis;
+}
+/** A slot holding a code with nothing specified against it yet. */
+export interface FinishScheduleOpenSlot {
+    code: string;
+    sectionCode: number;
+    sectionName: string;
+    line: number;
+    slotId: SlotId;
+    slotName: string;
+    space: string | null;
+    /**
+     * Why this line is blank, in words — or `null` when nothing measured a reason.
+     *
+     * `null` is NOT "nothing was found". It means no diagnosis was recorded for
+     * this slot, most often because it was never searched, and it must not be
+     * rendered as a search that came back empty.
+     */
+    reason: string | null;
+}
 /** One row: one slot, one specified material, fully graded. */
 export interface FinishScheduleRow {
+    /**
+     * The printed line reference, e.g. `L-101` — how a drawing, an RFI or a
+     * substitution request names this line. Allocated from the Run's PROGRAMME
+     * rather than its picks, so recomposing the scheme, varying it, or accepting a
+     * substitution renumbers nothing.
+     */
+    code: string;
+    /** The hundreds block this line sits in, e.g. `100`. */
+    sectionCode: number;
+    sectionName: string;
+    /** The 1-based line within its (space, section) group. */
+    line: number;
     slotId: SlotId;
     slotName: string;
     /** The space NAME, or null for a spaceless slot. */
@@ -73,6 +179,11 @@ export interface FinishScheduleRow {
     attributes: FinishScheduleCell[];
     fitNotes: string[];
     grade: FinishScheduleGrade;
+    /**
+     * Or-equal alternates for this line. An empty array is AMBIGUOUS on its own —
+     * read it with {@link FinishSchedule.alternatesResolved}.
+     */
+    alternates: FinishScheduleAlternate[];
 }
 /** A whole composed scheme as an issuable finish schedule. */
 export interface FinishSchedule {
@@ -85,7 +196,24 @@ export interface FinishSchedule {
     generatedAt: string;
     /** The stable column order every row's `attributes` array follows. */
     columns: FinishScheduleColumn[];
+    /**
+     * The section table to group by, in schedule order. A section may carry no
+     * rows: three are reserved so their conventional numbers are held rather than
+     * reused, and any section can simply be unspecified in this scheme.
+     */
+    sections: FinishScheduleSection[];
+    /** In READING order — space, then section, then line. Not pick order. */
     rows: FinishScheduleRow[];
+    /**
+     * Slots holding a code with nothing specified against them. Served explicitly
+     * because a schedule that omitted them would read as complete.
+     */
+    openSlots: FinishScheduleOpenSlot[];
+    /**
+     * Whether the or-equal lookup RAN. When false, no row's empty `alternates`
+     * may be read as "no alternate exists".
+     */
+    alternatesResolved: boolean;
 }
 /** `GET /api/v1/runs/{runId}/schedule`. */
 export interface FinishScheduleResponse {

package/schema-resource-types.d.ts

@@ -130,7 +130,7 @@ export interface SchemaSourceRequirementItem {
     minConfidence: number;
     reviewRequired: boolean;
     freshnessDays?: number;
-    sourceBasis?: OpenEnum<"declared" | "derived" | "tested">;
+    sourceBasis?: OpenEnum<"declared" | "derived" | "declared">;
     semanticId: string;
     lifecycle: SchemaLifecycle;
 }

package/search-refinement-types.d.ts

@@ -35,7 +35,7 @@ export interface SearchFilterTrust {
      *  - `derived` — MaterialGraph inferred it. Ours, not the manufacturer's — never
      *    present a `derived` value as something the brand claims.
      */
-    sourceBasis?: "catalog_feed" | "declared" | "derived" | "tested";
+    sourceBasis?: "catalog_feed" | "declared" | "derived" | "declared";
     /** Fold the attribute's own registry confidence requirement in, server-side. */
     meetsRequirement?: true;
 }
@@ -67,3 +67,30 @@ export interface SearchSuggestion {
     /** Complete replacement request, not a partial patch. */
     request: SearchInput;
 }
+/** One of the two readings a {@link SearchDisambiguation} offers. */
+export interface SearchInterpretation {
+    id: string;
+    label: string;
+    kind: string;
+    /** True for the reading that ACTUALLY RAN and produced this page. */
+    isDefault: boolean;
+    /** The colour this reading resolved to, when the ambiguity was a colour one. */
+    hex?: string;
+    /** Complete replacement request, not a partial patch. */
+    request: SearchInput;
+}
+/**
+ * The server saying a query had TWO defensible readings, and which one it took.
+ *
+ * `interpretations` always holds exactly two, the one that ran flagged
+ * `isDefault`. Each carries a complete executable request, so offering the
+ * other reading is a re-issue rather than a patch. Ignoring this block does not
+ * make the ambiguity go away — it makes it invisible to the person who asked.
+ */
+export interface SearchDisambiguation {
+    /** Which ambiguity this is: "compliance-phrase", "colour-material", "paint-colour". */
+    kind: string;
+    /** The ambiguous term or phrase. */
+    term: string;
+    interpretations: SearchInterpretation[];
+}

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 {};