@instruments/materialgraph 0.26.0 → 0.27.1

package/response-schemas.js

@@ -0,0 +1,113 @@
+/**
+ * Runtime response contracts: the JSON Schema of each operation's success body.
+ *
+ * The schemas are the producer's own. They are projected from the served
+ * OpenAPI document, whose response bodies are generated from the Zod contracts
+ * the routes validate against, so a consumer never has to re-describe a large,
+ * partly open payload and watch it drift. Hand one to anything that takes a
+ * JSON Schema, such as a Mastra tool's `outputSchema`:
+ *
+ * ```ts
+ * import { responseSchema } from "@instruments/materialgraph/response-schemas";
+ *
+ * createTool({ outputSchema: responseSchema("search_materials_post"), … });
+ * ```
+ *
+ * Keyed by OpenAPI `operationId`, the same id `SDK_OPERATIONS` pairs with each
+ * client method. Schemas are JSON Schema 2020-12 and describe the parsed body
+ * the client method returns. `list_public_run_events` is absent: it streams
+ * Server-Sent Events rather than returning one JSON body.
+ *
+ * Objects accept properties the schema does not declare, so a field the API
+ * adds later never makes a pinned consumer reject a live response; enums and
+ * constants stay closed. That is why these are more lenient than the WebMCP
+ * `outputSchema`s, which describe what the API sends rather than what a
+ * consumer should tolerate.
+ *
+ * This is its own entry point because the catalogue is large; importing the
+ * client does not load it, and it is parsed on the first `responseSchema()`
+ * call rather than on import.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { RESPONSE_SCHEMA_CATALOGUE_JSON } from "./response-schemas.generated.js";
+export { RESPONSE_SCHEMA_API_VERSION, RESPONSE_SCHEMA_OPERATION_IDS, } from "./response-schemas.generated.js";
+const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const DEFINITION_PREFIX = "#/$defs/";
+const isJsonSchemaMap = (value) => typeof value === "object" &&
+    value !== null &&
+    Object.values(value).every((schema) => typeof schema === "object" && schema !== null && !Array.isArray(schema));
+const isCatalogue = (value) => typeof value === "object" &&
+    value !== null &&
+    "definitions" in value &&
+    isJsonSchemaMap(value.definitions) &&
+    "operations" in value &&
+    isJsonSchemaMap(value.operations);
+let parsedCatalogue;
+const loadCatalogue = () => {
+    if (parsedCatalogue === undefined) {
+        const parsed = JSON.parse(RESPONSE_SCHEMA_CATALOGUE_JSON);
+        if (!isCatalogue(parsed)) {
+            throw MaterialGraphError.unexpected("The response schema catalogue is malformed");
+        }
+        parsedCatalogue = parsed;
+    }
+    return parsedCatalogue;
+};
+/** Add every definition `value` reaches, transitively, to `into`. */
+const collectReferences = (catalogue, value, into) => {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectReferences(catalogue, item, into);
+        }
+        return;
+    }
+    if (typeof value !== "object" || value === null) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "$ref" &&
+            typeof child === "string" &&
+            child.startsWith(DEFINITION_PREFIX)) {
+            const name = child
+                .slice(DEFINITION_PREFIX.length)
+                .replaceAll("~1", "/")
+                .replaceAll("~0", "~");
+            if (!into.has(name)) {
+                into.add(name);
+                collectReferences(catalogue, catalogue.definitions[name], into);
+            }
+        }
+        else {
+            collectReferences(catalogue, child, into);
+        }
+    }
+};
+/**
+ * The success-response schema for one operation, self-contained and carrying
+ * only the definitions it reaches. Each call returns a fresh copy, so a caller
+ * that annotates or mutates it cannot change what the next caller gets.
+ */
+export const responseSchema = (operationId) => {
+    const catalogue = loadCatalogue();
+    const root = Object.hasOwn(catalogue.operations, operationId)
+        ? catalogue.operations[operationId]
+        : undefined;
+    if (root === undefined) {
+        throw MaterialGraphError.unexpected(`No response schema for operation: ${operationId}`);
+    }
+    const names = new Set();
+    collectReferences(catalogue, root, names);
+    const definitions = {};
+    for (const name of [...names].toSorted()) {
+        const definition = catalogue.definitions[name];
+        if (definition !== undefined) {
+            definitions[name] = definition;
+        }
+    }
+    const schema = {
+        $schema: JSON_SCHEMA_DIALECT,
+        ...root,
+        ...(names.size > 0 ? { $defs: definitions } : {}),
+    };
+    return structuredClone(schema);
+};

package/run-types.d.ts

@@ -2,9 +2,8 @@
  * Hand-mirrored wire types for the MaterialGraph public Run + source-material
  * surface (spec 0.7.0). Like {@link ./types.ts}, these interfaces carry NO
  * runtime dependency on any `@materialgraph/*` package — they mirror the shapes
- * in `apps/web/public/openapi.yaml` (`list_public_capabilities`,
- * `create_public_run`, `get_public_run`, `list_public_run_events`,
- * `resume_public_run`, `cancel_public_run`, `upload_source_material`).
+ * in `apps/web/public/openapi.yaml` (`create_public_run`, `get_public_run`,
+ * `list_public_run_events`, `upload_source_material`).
  *
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
  * so a new server value still type-checks, and objects are read structurally —
@@ -246,50 +245,14 @@ export type SourceMaterialBatchDetail = {
     createdAt: string;
     sources: SourceMaterialBatchFile[];
 };
+/**
+ * Still carried on {@link PublicRun.capabilityKind}, so a Run created before
+ * MG-2252 reads back as `"agent"`. The rest of the public capability manifest
+ * shape retired with `GET /api/v1/capabilities`.
+ */
 export type CapabilityKind = OpenEnum<"agent" | "tool" | "workflow">;
-export type CapabilityExposure = OpenEnum<"public" | "partner" | "internal">;
-export type CapabilityScope = OpenEnum<"mg:read" | "mg:write" | "mg:ingest" | "mg:admin">;
-export type CapabilitySideEffectClass = OpenEnum<"read_only" | "browser_local" | "external_read" | "writes_proposed" | "writes_persisted" | "planned_only">;
-export type CapabilityRetryPolicy = {
-    maxAttempts: number;
-    backoff: OpenEnum<"none" | "fixed" | "exponential">;
-};
-export type CapabilityInvokeLink = {
-    href: string;
-    method: OpenEnum<"GET" | "POST">;
-};
-/** One human-input checkpoint exposed by a workflow capability. */
-export type PublicCapabilitySuspension = {
-    stepId: string;
-    suspend: Record<string, unknown>;
-    resume: Record<string, unknown>;
-};
-/** One invocable capability from the governed public manifest. */
-export type PublicCapabilityMetadata = {
-    publicId: string;
-    runtimeId: string;
-    kind: CapabilityKind;
-    exposure: CapabilityExposure;
-    name: string;
-    description: string;
-    schemas: {
-        input: Record<string, unknown>;
-        output: Record<string, unknown>;
-        suspensions?: PublicCapabilitySuspension[];
-    };
-    sideEffectClass: CapabilitySideEffectClass;
-    scopes: CapabilityScope[];
-    timeoutMs: number;
-    retryPolicy: CapabilityRetryPolicy;
-    tags: string[];
-    links: {
-        invoke: CapabilityInvokeLink;
-    };
-};
-/** The `GET /api/v1/capabilities` response envelope. */
-export type CapabilityManifestResponse = {
-    capabilities: PublicCapabilityMetadata[];
-};
+/** What `POST /api/v1/runs` admits: never an agent since MG-2252. */
+export type CreatableCapabilityKind = "tool" | "workflow";
 export type PublicRunStatus = OpenEnum<"queued" | "claimed" | "running" | "suspended" | "succeeded" | "failed" | "canceled">;
 export type PublicRunFailure = {
     code: string;
@@ -322,9 +285,7 @@ export type PublicRun = {
     /** 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.
+     * The step awaiting input while `status` is `suspended`.
      *
      * Read `suspensionPayload` for the current typed question. The same payload is
      * also retained on the `suspended` ledger event; composition-specific events
@@ -341,7 +302,7 @@ export type PublicRun = {
 };
 /** Body for `POST /api/v1/runs` ({@link MaterialGraphClient.createRun}). */
 export type CreatePublicRunRequest = {
-    capabilityKind: CapabilityKind;
+    capabilityKind: CreatableCapabilityKind;
     capabilityId: string;
     /** The capability input, validated server-side against its live input schema. */
     inputJson: unknown;
@@ -361,40 +322,10 @@ export type CreatePublicRunResponse = {
     workflowRunId: string;
     run: PublicRun;
 };
-/** The `GET /api/v1/runs/{runId}` and resume/cancel response envelope. */
+/** The `GET /api/v1/runs/{runId}` response envelope. */
 export type PublicRunResponse = {
     run: PublicRun;
 };
-/** Query for `GET /api/v1/runs` ({@link MaterialGraphClient.listRuns}). */
-export type ListRunsOptions = {
-    /**
-     * Return only Runs in this status. `"suspended"` is the recovery question:
-     * which of my Runs is still waiting on an answer?
-     */
-    status?: PublicRunStatus;
-    /** Page size, 1–100. Defaults to 20 server-side. */
-    limit?: number;
-    /**
-     * The previous page's {@link PublicRunListResponse.nextCursor}, round-tripped
-     * VERBATIM. It is opaque — never parse or construct one.
-     */
-    cursor?: string;
-    signal?: AbortSignal;
-};
-/** The `GET /api/v1/runs` response envelope — one page, newest first. */
-export type PublicRunListResponse = {
-    runs: PublicRun[];
-    /**
-     * Pass as {@link ListRunsOptions.cursor} for the next page. ABSENT — not
-     * empty-string, not null — once the last page has been served.
-     */
-    nextCursor?: string;
-};
-/** Body for `POST /api/v1/runs/{runId}/resume`. */
-export type ResumePublicRunRequest = {
-    /** The resume payload, validated against the suspended step's resume schema. */
-    resumeData: unknown;
-};
 /**
  * One redacted Run event, decoded from an SSE `data:` frame. The stream yields
  * these in ascending {@link RunEvent.sequence} order. `payloadJson` is read
@@ -421,15 +352,3 @@ export type DrainRunEventsOptions = {
     /** Stop collecting after this many milliseconds even without a terminal event. */
     deadlineMs: number;
 };
-/** Options for {@link MaterialGraphClient.resumeRun}. */
-export type ResumeRunOptions = {
-    /**
-     * The step the caller believes is suspended. When it mismatches the run
-     * doc's live `suspensionStepId` the API answers RFC-7807 409 (MG-608) —
-     * which is what stops a stale client resuming a step the run has already
-     * moved past. Omitted, the resume is unguarded, exactly as before.
-     */
-    stepId?: string;
-    /** Abort the request. */
-    signal?: AbortSignal;
-};

package/runs.d.ts

@@ -1,5 +1,5 @@
 import type { HttpTransport } from "./http-transport.js";
-import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, SourceMaterialCommentThread, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, PublicRunResponse, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, SourceMaterialCommentThread, StreamRunEventsOptions, 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
@@ -54,46 +54,10 @@ export declare const listSourceMaterialComments: (transport: HttpTransport, batc
  * `replies`, which a `reply` does not have.
  */
 export declare const 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 const capabilities: (transport: HttpTransport, signal?: AbortSignal) => Promise<CapabilityManifestResponse>;
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
 export declare const createRun: (transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal) => Promise<CreatePublicRunResponse>;
-/**
- * List your own Runs, newest first (`GET /api/v1/runs`).
- *
- * The recovery path for a client that still holds its API key but has lost a Run
- * id — a reinstalled app, or a crash before the id from {@link createRun} was
- * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
- *
- * Only the calling principal's own Runs are ever returned; there is no
- * cross-principal listing.
- *
- * Page by following `nextCursor` until it is ABSENT — a full page is not the
- * signal to stop, and an absent cursor is the only one.
- */
-export declare const listRuns: (transport: HttpTransport, options?: ListRunsOptions) => Promise<PublicRunListResponse>;
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export declare const getRun: (transport: HttpTransport, runId: string, signal?: AbortSignal) => Promise<PublicRunResponse>;
-/**
- * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
- *
- * The third argument takes either an `AbortSignal` (legacy) or
- * {@link ResumeRunOptions}.
- *
- * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
- * An empty string is a present-but-malformed value and must reach the server
- * so its schema rejects it; treating it as absent would silently downgrade a
- * guarded resume into an unguarded one, which is the exact failure this guard
- * exists to prevent.
- *
- * Omitting it sends a body byte-identical to what this sent before. Note the
- * wire cannot distinguish `{ stepId: undefined }` from no key at all —
- * `JSON.stringify` drops both — so the distinction here is construction
- * intent, kept so the serialised body is provably unchanged for old callers.
- */
-export declare const resumeRun: (transport: HttpTransport, runId: string, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions) => Promise<PublicRunResponse>;
-/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
-export declare const cancelRun: (transport: HttpTransport, runId: string, signal?: AbortSignal) => Promise<PublicRunResponse>;
 /**
  * Stream ordered Run events as an async iterator (`GET
  * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or

package/runs.js

@@ -1,9 +1,8 @@
 /**
  * The Run + source-material namespace — the agentic half of the SDK. These
  * functions take the shared {@link HttpTransport} and speak the hosted Run
- * lifecycle: upload source material, list capabilities, create/read/resume/
- * cancel Runs, and stream (or drain) their events. Box's proxy routes are thin
- * wrappers over exactly these calls.
+ * lifecycle: upload source material, create/read Runs, and stream (or drain)
+ * their events. Box's proxy routes are thin wrappers over exactly these calls.
  */
 import { MaterialGraphError } from "./errors.js";
 import { findSdkOperation, operationPath } from "./operations.js";
@@ -151,92 +150,16 @@ export const postSourceMaterialComment = async (transport, batchId, sourceId, in
     });
     return checkPostSourceMaterialCommentResult(body, sourceId);
 };
-/** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
-export const capabilities = async (transport, signal) => await transport.requestJson(runOperation("list_public_capabilities"), {
-    signal,
-});
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
 export const createRun = async (transport, body, signal) => await transport.requestJson(runOperation("create_public_run"), {
     body,
     signal,
 });
-/**
- * List your own Runs, newest first (`GET /api/v1/runs`).
- *
- * The recovery path for a client that still holds its API key but has lost a Run
- * id — a reinstalled app, or a crash before the id from {@link createRun} was
- * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
- *
- * Only the calling principal's own Runs are ever returned; there is no
- * cross-principal listing.
- *
- * Page by following `nextCursor` until it is ABSENT — a full page is not the
- * signal to stop, and an absent cursor is the only one.
- */
-export const listRuns = async (transport, options = {}) => {
-    const query = {
-        ...(options.status === undefined ? {} : { status: options.status }),
-        ...(options.limit === undefined ? {} : { limit: options.limit }),
-        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
-    };
-    return await transport.requestJson(runOperation("list_public_runs"), {
-        ...(Object.keys(query).length > 0 ? { query } : {}),
-        ...(options.signal ? { signal: options.signal } : {}),
-    });
-};
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export const getRun = async (transport, runId, signal) => await transport.requestJson(runOperation("get_public_run"), {
     pathParams: { runId },
     signal,
 });
-/**
- * Normalise `resumeRun`'s overloaded third argument.
- *
- * A bare `AbortSignal` stays supported because it is the published shape:
- * reordering that parameter would break any consumer passing it positionally,
- * and this ships with no version bump.
- *
- * Discriminated on `instanceof AbortSignal`, NOT on the presence of `stepId`.
- * `{ signal }` with no `stepId` is a perfectly valid options object, and a
- * key-presence test would misread it as a signal and silently drop the abort.
- */
-const resumeOptions = (value) => {
-    if (value === undefined) {
-        return {};
-    }
-    return value instanceof AbortSignal ? { signal: value } : value;
-};
-/**
- * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
- *
- * The third argument takes either an `AbortSignal` (legacy) or
- * {@link ResumeRunOptions}.
- *
- * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
- * An empty string is a present-but-malformed value and must reach the server
- * so its schema rejects it; treating it as absent would silently downgrade a
- * guarded resume into an unguarded one, which is the exact failure this guard
- * exists to prevent.
- *
- * Omitting it sends a body byte-identical to what this sent before. Note the
- * wire cannot distinguish `{ stepId: undefined }` from no key at all —
- * `JSON.stringify` drops both — so the distinction here is construction
- * intent, kept so the serialised body is provably unchanged for old callers.
- */
-export const resumeRun = async (transport, runId, resumeData, signalOrOptions) => {
-    const { stepId, signal } = resumeOptions(signalOrOptions);
-    return await transport.requestJson(runOperation("resume_public_run"), {
-        body: { resumeData, ...(stepId === undefined ? {} : { stepId }) },
-        pathParams: { runId },
-        signal,
-    });
-};
-/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
-export const cancelRun = async (transport, runId, signal) => await transport.requestJson(runOperation("cancel_public_run"), {
-    body: {},
-    pathParams: { runId },
-    signal,
-});
 /** Decode one SSE `data:` frame into a {@link RunEvent}, or `null` when unusable. */
 const decodeRunEvent = (data) => {
     if (data.length === 0) {

package/schema-resource-types.d.ts

@@ -29,8 +29,14 @@ export type SchemaExternalMapping = {
     target: OpenEnum<"schema_org" | "ifc_pset" | "bsdd" | "iso_23387" | "eclass" | "gs1_gdm" | "gdsn" | "etim" | "uniclass">;
     targetPath: string;
     mappingType: OpenEnum<"direct" | "transform" | "derived" | "classification" | "semantic">;
+    /**
+     * SKOS mapping strength, read from the MaterialGraph side. Only `exact`
+     * licenses substituting one concept for the other.
+     */
+    matchStrength?: SchemaMatchStrength;
     notes?: string;
 };
+export type SchemaMatchStrength = OpenEnum<"exact" | "close" | "broad" | "narrow" | "related">;
 export type SchemaBlockItem = {
     id: string;
     semanticId: string;
@@ -39,7 +45,7 @@ export type SchemaBlockItem = {
     description: string;
     attributeIds: string[];
 };
-export type KnownSchemaQuantityKind = "length" | "area" | "volume" | "mass" | "time" | "temperature" | "currency" | "ratio" | "density" | "coverage" | "emissions" | "force" | "power" | "voltage" | "current" | "frequency" | "luminous_flux" | "color_temperature" | "count" | "unitless";
+export type KnownSchemaQuantityKind = "length" | "area" | "volume" | "mass" | "time" | "temperature" | "currency" | "ratio" | "density" | "coverage" | "emissions" | "force" | "thermal_conductivity" | "power" | "voltage" | "current" | "frequency" | "luminous_flux" | "color_temperature" | "count" | "unitless";
 export type SchemaQuantityKind = OpenEnum<KnownSchemaQuantityKind>;
 export type SchemaAttributeItem = {
     id: string;
@@ -79,6 +85,8 @@ export type SchemaProductTypeItem = {
     id: string;
     name: string;
     description?: string;
+    /** Display names this type carried before a rename, kept so they still find it. */
+    formerNames?: string[];
     verticalId: string;
     parentProductTypeGroupId?: string;
     blocks: SchemaProductTypeBlock[];
@@ -97,6 +105,10 @@ export type SchemaUnitItem = {
         offset?: number;
     };
     notes?: string;
+    /** UN/CEFACT Rec 20 common code (schema.org `unitCode`); absent when Rec 20 has none. */
+    uncefactCode?: string;
+    /** QUDT unit IRI, where exactly one QUDT unit matches. */
+    qudtUnit?: string;
     semanticId: string;
     lifecycle: SchemaLifecycle;
 };
@@ -160,6 +172,7 @@ export type SchemaMappingItem = {
     canonicalPath: string;
     targetPath: string;
     mappingType: SchemaExternalMapping["mappingType"];
+    matchStrength?: SchemaMatchStrength;
     notes?: string;
 };
 export type SchemaResourceItemMap = {

package/search-card-types.d.ts

@@ -31,6 +31,19 @@ export type SearchCardItem = {
     name: string;
     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;
+    /**
+     * 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;
     /**
      * The manufacturer's own item code, the same key the full item carries.
      * Reach for it when two cards read alike: `name` is the PRODUCT name, and a
@@ -62,3 +75,12 @@ export type SearchCardResponse = {
         results: SearchCardItem[];
     };
 } & Omit<SearchResponse, "data">;
+/**
+ * The request forms the server answers with {@link SearchCardResponse}:
+ * `view: "card"`, or `intent: "typeahead"`, which forces the card view.
+ */
+export type CardProjectionRequest = {
+    view: "card";
+} | {
+    intent: "typeahead";
+};

package/search-index-plan-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module search-index-plan-types
+ * @description The plan the one search ran on, as `/search` reports it under
+ * `explain.plan` (ADR 0031). Mirrors `searchIndexPlanReceiptSchema` in
+ * `@materialgraph/products/search-index/plan-schema`; `key-parity.test.ts`
+ * holds the two to the same fields.
+ */
+import type { CorpusScope } from "./corpus-scope-types.js";
+/** One attribute the plan wants: its terms, or any value when `presence`. */
+export type SearchIndexPlanWant = {
+    attributeId: string;
+    /** Share of the category's materials stating the attribute, 0 to 1. */
+    fill: number;
+    /** The words it was read from, or `"(filter)"` for a caller's filter. */
+    phrase: string;
+    /** Any stated value satisfies it; `terms` is then empty. */
+    presence?: true;
+    /** A hard want removes rows; a soft one only counts toward the order. */
+    strength: "hard" | "soft";
+    terms: string[];
+};
+/**
+ * The query's plan: the category, makers, wanted and excluded attribute terms,
+ * the colour, the words left for text, and the caller's corpus scope.
+ */
+export type SearchIndexPlan = {
+    brands: {
+        ids: string[];
+        names: string[];
+        phrase: string;
+    } | null;
+    category: {
+        label: string;
+        phrase: string;
+        productTypeIds: string[];
+    } | null;
+    colour: {
+        family12: string[];
+        familyId: string;
+        hex: string;
+        oklab: [number, number, number];
+        phrase: string;
+    } | null;
+    /** Present only when the caller sent a scope narrower than the whole graph. */
+    corpusScope?: Exclude<CorpusScope, "all">;
+    excludeBrands: string[];
+    excludes: {
+        attributeId: string;
+        phrase: string;
+        term: string;
+    }[];
+    /** Words the reading did not place, left for the text match. */
+    leftover: string[];
+    normalised: string;
+    softAlone: boolean;
+    vendorColourNames: string[];
+    wants: SearchIndexPlanWant[];
+};
+/**
+ * Which reading a search ran on (`version`, `source`), whether it came from
+ * the cache, the plan itself, and its signature, so two runs of one request
+ * can be compared plan for plan.
+ */
+export type SearchPlanReceipt = {
+    cached: boolean;
+    plan: SearchIndexPlan;
+    signature: string;
+    source: "dictionary" | "jev";
+    version: string;
+};

package/search-refinement-types.d.ts

@@ -1,5 +1,4 @@
-/** Types for structured refinements returned by MaterialGraph search. */
-import type { SearchInput } from "./types.js";
+/** The spec-filter vocabulary MaterialGraph's filter and preference inputs share. */
 /**
  * A hard canonical-attribute filter accepted by the search engine — a term match
  * (`{ attributeId, term }`), a presence check (`{ attributeId, hasValue: true }`)
@@ -57,10 +56,16 @@ export type SearchFilter = {
     term: string;
     trust?: SearchFilterTrust;
 } | {
-    /** Known effective values are required, and this term must be absent. */
     attributeId: string;
     excludesTerm: string;
     trust?: SearchFilterTrust;
+    /**
+     * What an UNKNOWN effective value does. Absent or `"drop"` (default)
+     * requires a known effective value — a variant that never states the
+     * attribute does not pass. `"pass"` admits it — a variant only fails by
+     * STATING the excluded term.
+     */
+    whenUnstated?: "drop" | "pass";
 }
 /**
  * TERM SET — the attribute must equal any ONE of these. OR within the entry;
@@ -96,38 +101,3 @@ export type SearchFilter = {
     max?: number;
     trust?: SearchFilterTrust;
 };
-/** One structured refinement returned with a search response. */
-export type SearchSuggestion = {
-    label: string;
-    /** Complete replacement request, not a partial patch. */
-    request: SearchInput;
-};
-/** One reading a {@link SearchDisambiguation} offers. */
-export type SearchInterpretation = {
-    id: string;
-    label: string;
-    kind: string;
-    /** True for the reading that ran; all false means the engine chose none. */
-    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 governed ambiguity classes emitted by MaterialGraph search. */
-export type SearchDisambiguationKind = "compliance-phrase" | "colour-material" | "paint-colour" | "paint-identity";
-/**
- * The server saying a query had multiple defensible readings.
- *
- * The reading that ran is flagged `isDefault`; every reading is false when the
- * engine deliberately chose none. Each carries a complete executable request,
- * so choosing a 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 type SearchDisambiguation = {
-    /** Compliance, colour-material, paint-colour, or paint-identity ambiguity. */
-    kind: SearchDisambiguationKind;
-    /** The ambiguous term or phrase. */
-    term: string;
-    interpretations: SearchInterpretation[];
-};

package/search-refinement-types.js

@@ -1 +1,2 @@
+/** The spec-filter vocabulary MaterialGraph's filter and preference inputs share. */
 export {};