@instruments/materialgraph 0.24.0 → 0.26.0

package/search-response-receipt-types.d.ts

@@ -5,35 +5,61 @@
  */
 import type { OpenEnum } from "./types.js";
 /** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
-export interface SearchRefinementReceipt {
+export type SearchRefinementReceipt = {
     token: string;
     expiresAt: string;
     poolSize: number;
     schemaVersion: string;
     projectionVersion: number;
-}
+};
 /** The primary ranking source a query resolved to and reports as its mode. */
-export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
+export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse" | "agent">;
 /**
  * Compatibility receipt for non-mode colour handling. Current one-signal
  * ordering reports it skipped at weight 0; colour may still be diagnostic or a
  * hard displayed-image constraint, but does not blend into score.
  */
-export interface SearchRerankReport {
+export type SearchRerankReport = {
     colour?: OpenEnum<"ok" | "failed" | "skipped">;
     colourWeight?: number;
     colourLabel?: string;
-}
-/** Stage counts retained when an explain-enabled search returns no results. */
-export interface SearchEmptyOutcomeCounts {
+};
+/**
+ * A part of the search that can fail without stopping it.
+ *
+ * Coarse on purpose: a caller needs to know that something did not answer, not
+ * which provider it was. OPEN, and it will grow — read it with a default
+ * branch.
+ */
+export type SearchDegradedPart = OpenEnum<"filter-coverage" | "term-coverage">;
+/**
+ * Which parts of the search did not answer, on EVERY response (MG-1913).
+ *
+ * `parts: []` says no part reported a failure. It does NOT promise every check
+ * ran: a check the request never needed is skipped rather than failed. ABSENT
+ * means the response came from a server that does not report this, never that
+ * nothing was degraded.
+ */
+export type SearchDegraded = {
+    parts: SearchDegradedPart[];
+};
+/** Stage counts retained when a search returns no results. */
+export type SearchEmptyOutcomeCounts = {
     retrieved: number;
     afterPrune: number;
     final: number;
-}
+};
 /**
- * Explain-only evidence for why a completed search returned no results.
- * `proven-corpus-empty` is exhaustive; every other empty remains explicitly
- * unproven rather than being presented as catalogue absence.
+ * Why a search returned no results, on EVERY empty response (MG-1911).
+ *
+ * `proven-corpus-empty` is exhaustive and is the only member that supports
+ * telling someone the catalogue holds nothing. `unproven-empty` is an honest
+ * end to a search that ran without establishing that. `search-degraded` means
+ * part of the search did not answer, so the empty page describes the runtime
+ * rather than the catalogue, and the right response is to retry.
+ *
+ * Read it by `kind` with a default branch: this union has grown once and the
+ * reason and basis enums are open.
  */
 export type SearchEmptyOutcome = {
     kind: "proven-corpus-empty";
@@ -46,18 +72,93 @@ export type SearchEmptyOutcome = {
     reason: OpenEnum<"allowlist-truncated" | "retrieval-window-not-exhaustive" | "source-empty" | "post-retrieval-rejected" | "pagination-empty" | "no-authoritative-empty-proof">;
     sourceEmpty?: boolean | null;
     counts?: SearchEmptyOutcomeCounts;
+} | {
+    kind: "search-degraded";
+    /** Which parts did not answer. Coarse: never a provider's name. */
+    parts: SearchDegradedPart[];
+    sourceEmpty?: boolean | null;
+    counts?: SearchEmptyOutcomeCounts;
 };
 /** Explain-only coverage of substantive query terms in the lexical projection. */
-export interface SearchTermCoverageReceipt {
+/**
+ * Which of the query's substantive words the catalogue holds at all
+ * (MG-1858), on every text-family response. `terms` names the words found in
+ * no document; `checkedTerms` is how many were asked about; `noneMatched` is
+ * true when no checked word is attested anywhere. `unavailable` means the read
+ * failed and never means everything matched; `skipped` means this mode never
+ * claimed to match words.
+ */
+export type SearchTermCoverageReceipt = {
     status: OpenEnum<"covered" | "uncovered" | "unavailable" | "skipped">;
     terms: string[];
+    checkedTerms: number;
+    noneMatched: boolean;
     note?: string;
-}
-/** Explain-only outcome receipts shared by full and card search responses. */
-export interface SearchResponseExplainReceipts {
+};
+/** The Search workflow run a ledger receipt belongs to. */
+export type SearchRunRef = {
+    contextId: string;
+    runId: string;
+    schemaVersion: 1;
+};
+/** One artifact a Search workflow step read or wrote. */
+export type SearchRunArtifactRef = {
+    artifactId: string;
+    kind: string;
+    producedBy: string;
+    runRef: SearchRunRef;
+    schemaVersion: 1;
+};
+/** What one Search workflow step did: its reads, its write and its time. */
+export type SearchStageReceipt = {
+    stageId: string;
+    status: "succeeded";
+    /** The step's own work, excluding reading and writing its artifacts. */
+    durationMs: number;
+    inputArtifacts: SearchRunArtifactRef[];
+    outputArtifact: SearchRunArtifactRef;
+    inputCount: number | null;
+    outputCount: number | null;
+    runRef: SearchRunRef;
+    /** The outcome the step chose, when it chooses one. */
+    outcome?: string;
+    /** The arm a fork took and why. */
+    branch?: {
+        decision: string;
+        reason: string;
+    };
+};
+/** One ledger line: a step's receipt and its span since the run opened. */
+export type SearchRunLedgerEntry = {
+    receipt: SearchStageReceipt;
+    /** The nested workflows the step ran under, outermost first. */
+    workflowPath: string[];
+    startedAtMs: number;
+    endedAtMs: number;
+};
+/**
+ * Outcome receipts shared by full and card search responses. `degraded`,
+ * `emptyOutcome` and `termCoverage` are on every response; `diagnostics` and
+ * `explain` are explain-only.
+ */
+export type SearchResponseExplainReceipts = {
+    degraded?: SearchDegraded;
     emptyOutcome?: SearchEmptyOutcome;
     termCoverage?: SearchTermCoverageReceipt;
-}
+    /**
+     * The engine's notes written for an engineer (tier timings, cache states,
+     * index names), under `explain` only. `note` carries the reader's sentences
+     * alone (MG-1919).
+     */
+    diagnostics?: string[];
+    /**
+     * Present under `explain` when the Search workflow answered the request:
+     * every step receipt, in completion order. Absent when the engine answered.
+     */
+    explain?: {
+        ledger: readonly SearchRunLedgerEntry[];
+    };
+};
 /** One stage in the explain-only ledger of transformations that actually ran. */
 export type SearchQueryTransformStage = {
     stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
@@ -68,7 +169,7 @@ export type SearchQueryTransformStage = {
     reason: string;
 };
 /** Explain-only category gate selected by query understanding. */
-export interface SearchCategoryAnchor {
+export type SearchCategoryAnchor = {
     /**
      * A leaf type id; the group key when `source` is `"group"`; or the canonical
      * category noun when `source` is `"head-noun"`. Gate on `productTypeIds`.
@@ -86,9 +187,9 @@ export interface SearchCategoryAnchor {
     /** Hard category eligibility is applied inside lexical candidate selection. */
     candidateSource?: OpenEnum<"lexical">;
     applied: boolean;
-}
+};
 /** Explain-only brand gate selected by query understanding. */
-export interface SearchBrandAnchor {
+export type SearchBrandAnchor = {
     brandSlug: string;
     brandName: string;
     confidence: number;
@@ -96,18 +197,18 @@ export interface SearchBrandAnchor {
     tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
     variantCount: number;
     applied: boolean;
-}
+};
 /** A real brand candidate the engine deliberately declined to gate on. */
-export interface SearchBrandSkip {
+export type SearchBrandSkip = {
     reason: OpenEnum<"ambiguous" | "weak-tier" | "too-broad">;
     candidates?: string[];
-}
+};
 /**
  * EXPLAIN-only receipt of the query shape that executed. This is distinct from
  * the separate Search Plan compiler operation: it reports execution and never
  * causes it.
  */
-export interface SearchExecutionPlan {
+export type SearchExecutionPlan = {
     grain: OpenEnum<"variant" | "product">;
     /** Which 2048D Voyage projection served a text-mode request. */
     textLane?: OpenEnum<"image-text" | "variant-text">;
@@ -121,30 +222,30 @@ export interface SearchExecutionPlan {
     };
     queryTransform: SearchQueryTransformStage[];
     /** Ordered, explain-only request-understanding execution trace. */
-    steps?: Array<{
+    steps?: {
         key: string;
         status: OpenEnum<"executed" | "skipped">;
         reason: string;
         durationMs: number;
-    }>;
+    }[];
     categoryAnchor?: SearchCategoryAnchor;
     brandAnchor?: SearchBrandAnchor;
     brandSkipped?: SearchBrandSkip;
-}
+};
 /** Why a compound colour constraint returned a full or short page. */
-export interface CompoundColourAbundanceReceipt {
+export type CompoundColourAbundanceReceipt = {
     grain: OpenEnum<"variant" | "product">;
     requested: number;
     eligible: number;
     candidateWindow: number;
     sourceExhausted: boolean;
     state: OpenEnum<"filled" | "corpus_scarcity" | "evidence_unavailable" | "retrieval_window_exhausted">;
-}
+};
 /**
  * Eligibility proof for an explicit or taxonomy-backed colour inside a compound
  * text query. Counts describe the bounded candidate pool, not the whole corpus.
  */
-export interface CompoundColourConstraintReceipt {
+export type CompoundColourConstraintReceipt = {
     basis: OpenEnum<"explicit" | "detected-strong">;
     family: string;
     queryHexes: string[];
@@ -154,21 +255,21 @@ export interface CompoundColourConstraintReceipt {
     unknown: number;
     adjacent: number;
     abundance?: CompoundColourAbundanceReceipt;
-}
+};
 /** Why a hard form constraint returned a full or short page. */
-export interface CompoundFormAbundanceReceipt {
+export type CompoundFormAbundanceReceipt = {
     grain: OpenEnum<"variant" | "product">;
     requested: number;
     eligible: number;
     candidateWindow: number;
     sourceExhausted: boolean;
     state: OpenEnum<"filled" | "corpus_scarcity" | "evidence_unavailable" | "retrieval_window_exhausted">;
-}
+};
 /**
  * Hard form eligibility for a compound text query. Product and variant names
  * may retrieve a candidate but never prove that it satisfies the form.
  */
-export interface CompoundFormConstraintReceipt {
+export type CompoundFormConstraintReceipt = {
     instruction: OpenEnum<"subway" | "plank" | "square" | "hexagon" | "penny-round">;
     considered: number;
     kept: number;
@@ -176,4 +277,4 @@ export interface CompoundFormConstraintReceipt {
     contradicted: number;
     unknown: number;
     abundance: CompoundFormAbundanceReceipt;
-}
+};

package/search-response-types.d.ts

@@ -1,6 +1,6 @@
 import type { SearchData } from "./types.js";
 /** Canonical Search wire response. Raw SDK methods preserve this envelope. */
-export interface SearchResponse {
+export type SearchResponse = {
     data: SearchData;
     meta: {
         operationId: "search_materials_post" | "search_materials_get";
@@ -8,4 +8,4 @@ export interface SearchResponse {
     };
     links: Record<string, never>;
     warnings: never[];
-}
+};

package/search-result-validation.d.ts

@@ -1,4 +1,4 @@
-import { type ValidationFailure } from "./validation.js";
+import type { ValidationFailure } from "./validation.js";
 /** `verdictStateSchema` — the six live cell states. */
 export declare const VERDICT_STATES: readonly ["matched", "deviated", "failed", "unverified", "missing", "not_evaluated"];
 /** `attributeVerdictSchema.strength`. */
@@ -22,6 +22,6 @@ export declare const VISUAL_MEANING_BASES: readonly ["canonical_attribute", "ima
  * contract (nothing on the emit path parses, so stripping would invent a
  * normalisation the wire never had).
  */
-export declare function checkSearchResultItem(value: unknown, what: string, fail: ValidationFailure): void;
+export declare const checkSearchResultItem: (value: unknown, what: string, fail: ValidationFailure) => void;
 /** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
-export declare function checkSearchResultItems(items: readonly unknown[], what: string, fail: ValidationFailure): void;
+export declare const checkSearchResultItems: (items: readonly unknown[], what: string, fail: ValidationFailure) => void;

package/search-result-validation.js

@@ -41,20 +41,21 @@ export const VISUAL_MEANING_BASES = [
 ];
 // ── Leaf checks ──────────────────────────────────────────────────────────────
 /** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
-function checkPaletteSwatch(value, what, fail) {
+const checkPaletteSwatch = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireString(record.hex, `${what}.hex`, fail);
     requireNumber(record.proportion, `${what}.proportion`, fail);
     // `.nullable().optional()` — absent OR null OR a string.
-    if (record.name !== undefined)
+    if (record.name !== undefined) {
         requireNullableString(record.name, `${what}.name`, fail);
-}
+    }
+};
 /**
  * `variants[]` — one entry of a product-collapsed result's ranked variant list
  * (`collapsedVariantSchema`). A SLIM projection, not a nested result item: the
  * checks here are the whole shape.
  */
-function checkCollapsedVariant(value, what, fail) {
+const checkCollapsedVariant = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireString(record.variantId, `${what}.variantId`, fail);
     requireNullableString(record.variantName, `${what}.variantName`, fail);
@@ -65,16 +66,16 @@ function checkCollapsedVariant(value, what, fail) {
     requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
     requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
     requireNumber(record.score, `${what}.score`, fail);
-}
+};
 /** `colourMeta` — three independently optional strings. */
-function checkColourMeta(value, what, fail) {
+const checkColourMeta = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireOptionalString(record.mood, `${what}.mood`, fail);
     requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
     requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
-}
+};
 /** `searchResultSignalsSchema` — five required scores plus additive portrait. */
-function checkSignals(value, what, fail) {
+const checkSignals = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     if (record.portrait !== undefined) {
         requireNullableNumber(record.portrait, `${what}.portrait`, fail);
@@ -82,9 +83,9 @@ function checkSignals(value, what, fail) {
     for (const signal of ["image", "category", "colour", "lexical", "text"]) {
         requireNullableNumber(record[signal], `${what}.${signal}`, fail);
     }
-}
+};
 /** `visualMeaningSchema` — note the NON-EMPTY `values` array and the closed `basis`. */
-function checkVisualMeaning(value, what, fail) {
+const checkVisualMeaning = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireString(record.id, `${what}.id`, fail);
     requireString(record.label, `${what}.label`, fail);
@@ -94,39 +95,43 @@ function checkVisualMeaning(value, what, fail) {
     requireOptionalString(record.sourceBasis, `${what}.sourceBasis`, fail);
     requireOptionalString(record.version, `${what}.version`, fail);
     requireOptionalString(record.appliedAt, `${what}.appliedAt`, fail);
-}
+};
 // ── Verdict subtree ──────────────────────────────────────────────────────────
 /**
  * `verdictBaselineSchema` — a discriminated union on `kind`. An unknown
  * discriminant is rejected, exactly as `z.discriminatedUnion` rejects it, and
  * each arm carries only the fields it needs.
  */
-function checkVerdictBaseline(value, what, fail) {
+const checkVerdictBaseline = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     const kind = requireEnum(record.kind, VERDICT_BASELINE_KINDS, `${what}.kind`, fail);
     switch (kind) {
-        case "term":
+        case "term": {
             requireNonEmptyString(record.term, `${what}.term`, fail);
+            break;
+        }
+        case "presence": {
             return;
-        case "presence":
-            return;
-        case "seed":
+        }
+        case "seed": {
             requireNonEmptyString(record.variantId, `${what}.variantId`, fail);
             return;
-        default:
+        }
+        default: {
             // `image` — the like-this-picture arm.
             requireEnum(record.source, VERDICT_IMAGE_SOURCES, `${what}.source`, fail);
             requireNullableNonEmptyString(record.variantId, `${what}.variantId`, fail);
+        }
     }
-}
+};
 /** `verdictDeviationSchema` — a named near-miss. */
-function checkVerdictDeviation(value, what, fail) {
+const checkVerdictDeviation = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireEnum(record.direction, VERDICT_DEVIATION_DIRECTIONS, `${what}.direction`, fail);
     requireNullableNumber(record.delta, `${what}.delta`, fail);
     requireNullableString(record.unit, `${what}.unit`, fail);
     requireNonEmptyString(record.label, `${what}.label`, fail);
-}
+};
 /**
  * `attributeVerdictSchema` — nine fields plus the TWO cross-field invariants its
  * `.superRefine()` enforces. Those are relational rather than field-wise, which
@@ -134,7 +139,7 @@ function checkVerdictDeviation(value, what, fail) {
  * schema's own doc calls them out as the reason a malformed cell can never reach
  * a consumer.
  */
-function checkAttributeVerdict(value, what, fail) {
+const checkAttributeVerdict = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireNonEmptyString(record.attributeId, `${what}.attributeId`, fail);
     const state = requireEnum(record.state, VERDICT_STATES, `${what}.state`, fail);
@@ -152,9 +157,10 @@ function checkAttributeVerdict(value, what, fail) {
             throw fail(`${what}.citation.count must be a positive integer`);
         }
     }
-    const deviation = record.deviation;
-    if (deviation !== null)
+    const { deviation } = record;
+    if (deviation !== null) {
         checkVerdictDeviation(deviation, `${what}.deviation`, fail);
+    }
     const trustGap = requireNullableEnum(record.trustGap, VERDICT_TRUST_GAPS, `${what}.trustGap`, fail);
     // superRefine invariant 1 — a deviation only describes a `deviated` cell.
     if (deviation !== null && state !== "deviated") {
@@ -164,15 +170,17 @@ function checkAttributeVerdict(value, what, fail) {
     if (trustGap !== null && state !== "unverified") {
         throw fail(`${what}.trustGap is set on a cell whose state is "${state}", not "unverified"`);
     }
-}
+};
 /** `candidateVerdictSchema` — the whole report card. */
-function checkCandidateVerdict(value, what, fail) {
+const checkCandidateVerdict = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     const cells = requireArray(record.cells, `${what}.cells`, fail);
-    cells.forEach((cell, index) => checkAttributeVerdict(cell, `${what}.cells[${index}]`, fail));
+    cells.forEach((cell, index) => {
+        checkAttributeVerdict(cell, `${what}.cells[${index}]`, fail);
+    });
     requireEnum(record.grade, VERDICT_GRADES, `${what}.grade`, fail);
     requireNullableBoundedNumber(record.minConfidence, `${what}.minConfidence`, fail, 0, 1);
-}
+};
 // ── The item ─────────────────────────────────────────────────────────────────
 /**
  * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
@@ -181,7 +189,7 @@ function checkCandidateVerdict(value, what, fail) {
  * contract (nothing on the emit path parses, so stripping would invent a
  * normalisation the wire never had).
  */
-export function checkSearchResultItem(value, what, fail) {
+export const checkSearchResultItem = (value, what, fail) => {
     const record = requireRecord(value, what, fail);
     requireString(record.variantId, `${what}.variantId`, fail);
     requireString(record.brand, `${what}.brand`, fail);
@@ -209,12 +217,15 @@ export function checkSearchResultItem(value, what, fail) {
     requireBoolean(record.hasImage, `${what}.hasImage`, fail);
     requireNumber(record.score, `${what}.score`, fail);
     const palette = requireArray(record.palette, `${what}.palette`, fail);
-    palette.forEach((swatch, index) => checkPaletteSwatch(swatch, `${what}.palette[${index}]`, fail));
+    palette.forEach((swatch, index) => {
+        checkPaletteSwatch(swatch, `${what}.palette[${index}]`, fail);
+    });
     if (record.colourMeta !== undefined) {
         checkColourMeta(record.colourMeta, `${what}.colourMeta`, fail);
     }
-    if (record.signals !== undefined)
+    if (record.signals !== undefined) {
         checkSignals(record.signals, `${what}.signals`, fail);
+    }
     requireOptionalBoolean(record.retired, `${what}.retired`, fail);
     requireOptionalBoolean(record.sampleable, `${what}.sampleable`, fail);
     requireOptionalBoolean(record.belowFloor, `${what}.belowFloor`, fail);
@@ -224,17 +235,23 @@ export function checkSearchResultItem(value, what, fail) {
     }
     if (record.variants !== undefined) {
         const variants = requireArray(record.variants, `${what}.variants`, fail);
-        variants.forEach((variant, index) => checkCollapsedVariant(variant, `${what}.variants[${index}]`, fail));
+        variants.forEach((variant, index) => {
+            checkCollapsedVariant(variant, `${what}.variants[${index}]`, fail);
+        });
     }
     if (record.visualMeanings !== undefined) {
         const meanings = requireArray(record.visualMeanings, `${what}.visualMeanings`, fail);
-        meanings.forEach((meaning, index) => checkVisualMeaning(meaning, `${what}.visualMeanings[${index}]`, fail));
+        meanings.forEach((meaning, index) => {
+            checkVisualMeaning(meaning, `${what}.visualMeanings[${index}]`, fail);
+        });
     }
     if (record.verdict !== undefined) {
         checkCandidateVerdict(record.verdict, `${what}.verdict`, fail);
     }
-}
+};
 /** Prove every entry of a `results[]` array is a {@link SearchResultItem}. */
-export function checkSearchResultItems(items, what, fail) {
-    items.forEach((item, index) => checkSearchResultItem(item, `${what}[${index}]`, fail));
-}
+export const checkSearchResultItems = (items, what, fail) => {
+    items.forEach((item, index) => {
+        checkSearchResultItem(item, `${what}[${index}]`, fail);
+    });
+};

package/search-window-types.d.ts

@@ -1,5 +1,5 @@
 /** The bounded candidate window that produced a search page. */
-export interface SearchWindowReceipt {
+export type SearchWindowReceipt = {
     /** Versioned budget profile; interpret the remaining fields under this version. */
     profile: "interactive-r1" | (string & {});
     /** Candidate depth used by the final retrieval. */
@@ -22,4 +22,4 @@ export interface SearchWindowReceipt {
         /** Canonical candidates returned by the selected retrieval arm. */
         hydratedCanonicalCandidates: number;
     };
-}
+};