@instruments/materialgraph 0.9.1 → 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,6 +1,6 @@
 import { HttpTransport } from "./http-transport.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";
-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";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
@@ -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

@@ -7,10 +7,10 @@
  */
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
-import { findSdkOperation, operationPath } from "./operations.js";
-import { checkSourceMaterialBatchDetail } from "./source-material-validation.js";
-import { readSseFrames } from "./sse.js";
+import { findSdkOperation, operationPath, } from "./operations.js";
 import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
+import { checkPostSourceMaterialCommentResult, checkSourceMaterialBatchDetail, checkSourceMaterialCommentThread, } from "./source-material-validation.js";
+import { readSseFrames } from "./sse.js";
 function runOperation(operationId) {
     const match = findSdkOperation(operationId);
     if (!match)
@@ -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"), {
@@ -224,7 +284,9 @@ function decodeRunEvent(data) {
 export async function* streamRunEvents(transport, runId, options = {}) {
     const body = await transport.openStream(runOperation("list_public_run_events"), {
         pathParams: { runId },
-        ...(options.after === undefined ? {} : { query: { after: options.after } }),
+        ...(options.after === undefined
+            ? {}
+            : { query: { after: options.after } }),
         ...(options.signal ? { signal: options.signal } : {}),
         accept: "text/event-stream",
         subject: "run-event stream",
@@ -265,7 +327,9 @@ export async function drainRunEvents(transport, runId, options) {
         }
     }
     catch (error) {
-        const causedByDeadline = controller.signal.aborted && error instanceof MaterialGraphError && error.kind === "aborted";
+        const causedByDeadline = controller.signal.aborted &&
+            error instanceof MaterialGraphError &&
+            error.kind === "aborted";
         if (!causedByDeadline)
             throw error;
     }

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

@@ -1,9 +1,10 @@
 /** Types for structured refinements returned by MaterialGraph search. */
 import type { SearchInput } from "./types.js";
 /**
- * A hard canonical-attribute filter accepted by the search engine — either a
- * term match (`{ attributeId, term }`) or a presence check
- * (`{ attributeId, hasValue: true }`). Applied as a restriction BEFORE ranking.
+ * A hard canonical-attribute filter accepted by the search engine — a term match
+ * (`{ attributeId, term }`), a presence check (`{ attributeId, hasValue: true }`)
+ * or a NUMERIC RANGE (`{ attributeId, min, max }`, bounds inclusive, at least one
+ * stated). Applied as a restriction BEFORE ranking.
  *
  * The `attributeId` may be a real registry id (`"fire_classifications"`,
  * `"environmental_product_declaration"`) OR the virtual
@@ -34,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;
 }
@@ -52,6 +53,13 @@ export type SearchFilter = {
     attributeId: string;
     hasValue: true;
     trust?: SearchFilterTrust;
+} | {
+    attributeId: string;
+    /** Inclusive lower bound. Omit for a ceiling-only range. */
+    min?: number;
+    /** Inclusive upper bound. Omit for a floor-only range. */
+    max?: number;
+    trust?: SearchFilterTrust;
 };
 /** One structured refinement returned with a search response. */
 export interface SearchSuggestion {
@@ -59,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[];
+}