@instruments/materialgraph 0.24.0 → 0.25.0

package/exploration-types.d.ts

@@ -77,6 +77,13 @@ export interface CandidateReadReceipt {
     dedupe: {
         retrieved: number;
         removed: number;
+        /**
+         * How many of `removed` went because an earlier row showed the SAME
+         * PICTURE, counted apart from the id rules (MG-1917). Distinct products
+         * routinely share one photograph, so an id-only collapse returned the same
+         * image several times on one page.
+         */
+        removedBySharedImage: number;
         truncated: number;
         projectionMisses: number;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "exports": {
     ".": {
@@ -17,7 +17,7 @@
     }
   },
   "dependencies": {
-    "@instruments/colorscope": "7.6.0"
+    "@instruments/colorscope": "9.0.1"
   },
   "license": "Proprietary",
   "engines": {

package/query-understanding-types.d.ts

@@ -1,3 +1,5 @@
+import type { MatchTarget } from "@instruments/colorscope/match";
+import type { ColorResolution } from "@instruments/colorscope/naming";
 import type { SearchFilter } from "./search-refinement-types.js";
 import type { OpenEnum } from "./types.js";
 export type QuerySenseKind = OpenEnum<"brand" | "product" | "paint_identity" | "category" | "material" | "colour" | "attribute" | "attribute_value" | "certification">;
@@ -34,6 +36,8 @@ export interface CanonicalLexicalAuthorityReceipt {
     digest?: string;
 }
 export interface CanonicalLexicalReading {
+    matchTarget?: MatchTarget;
+    colorResolution?: ColorResolution;
     authority: OpenEnum<"taxonomy" | "colorscope">;
     identity: string;
     outcome: OpenEnum<"equivalent" | "ambiguous" | "declined">;
@@ -181,7 +185,7 @@ export interface QueryAmbiguityReceipt {
 }
 export interface QueryCategoryScopeReceipt {
     source: OpenEnum<"caller" | "anchor">;
-    mechanism: OpenEnum<"sql-predicate" | "allowlist" | "prune">;
+    mechanism: OpenEnum<"sql-predicate" | "provider-filter" | "allowlist" | "prune">;
     variantCount: number | null;
     ceiling: number;
     specScanBounded?: boolean;

package/resolve-colour-types.d.ts

@@ -1,7 +1,9 @@
+import type { MatchTarget } from "@instruments/colorscope/match";
 /**
  * Colour-name resolution (GET `/api/v1/search/colours/resolve`): the resolved
  * colour, and whether the named paint is a variant in the catalogue.
  */
+import type { ColorResolution } from "@instruments/colorscope/naming";
 import type { CorpusScope } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
@@ -49,7 +51,21 @@ export type ResolveColourVariant = ({
     reason: OpenEnum<"reference-colour" | "descriptive-colour" | "no-paint-identity" | "generic-colour" | "several-paints">;
 };
 export interface ResolveColourResponse {
+    /** Examples within the governed range. They do not replace its representative or bounds. */
+    rangeSamples?: string[];
+    /** Explicit manufacturer choices for an ambiguous paint name. Never selected automatically. */
+    alternatives?: Array<{
+        query: string;
+        name: string;
+        hex: string;
+        libraryId: string;
+        libraryName: string;
+        code?: string;
+    }>;
+    /** Generic meaning; maker-specific paint identity is carried by match. */
+    genericResolution: ColorResolution;
     match: {
+        matchTarget: MatchTarget;
         hex: string;
         name: string;
         code?: string;

package/search-card-types.d.ts

@@ -11,7 +11,8 @@
 import type { ProductId, VariantId } from "./identifiers.js";
 import type { OpenEnum, SearchData, SearchResponse } from "./types.js";
 /**
- * The lean `view:"card"` result item — identity + name + thumbnail + score.
+ * The lean `view:"card"` result item — identity + name + code + thumbnail +
+ * score.
  *
  * A PROJECTION, not a smaller answer: a field the card omits (palette, verdict,
  * signals, availability) is unread here, never known-absent. Re-read the same
@@ -30,6 +31,14 @@ export interface SearchCardItem {
     name: string;
     variantName: string | null;
     imageUrl: string | null;
+    /**
+     * 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
+     * paint product is a whole collection, so brand, product name and variant
+     * name together are shared by most of the catalogue. ABSENT means no code is
+     * recorded, never that the variant cannot be ordered.
+     */
+    manufacturerCode?: string;
     projectSaveCapability?: "allowed";
     sourceStatus?: "provisional";
     score: number;

package/search-request-types.d.ts

@@ -122,7 +122,7 @@ export interface SearchInput {
      * 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. */
+    /** Results per page (default 60, max 60), never a bound on the match set. */
     limit?: number;
     /** The previous response's `cursor`, passed back verbatim. Never synthesise one. */
     cursor?: Cursor;

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

@@ -24,16 +24,42 @@ export interface SearchRerankReport {
     colourWeight?: number;
     colourLabel?: string;
 }
-/** Stage counts retained when an explain-enabled search returns no results. */
+/**
+ * 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 interface SearchDegraded {
+    parts: SearchDegradedPart[];
+}
+/** Stage counts retained when a search returns no results. */
 export interface 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,6 +72,12 @@ 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 {
@@ -53,10 +85,63 @@ export interface SearchTermCoverageReceipt {
     terms: string[];
     note?: string;
 }
-/** Explain-only outcome receipts shared by full and card search responses. */
+/** The Search workflow run a ledger receipt belongs to. */
+export interface SearchRunRef {
+    contextId: string;
+    runId: string;
+    schemaVersion: 1;
+}
+/** One artifact a Search workflow step read or wrote. */
+export interface 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 interface 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 interface 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` and
+ * `emptyOutcome` are on every response; `termCoverage` and `explain` are
+ * explain-only.
+ */
 export interface SearchResponseExplainReceipts {
+    degraded?: SearchDegraded;
     emptyOutcome?: SearchEmptyOutcome;
     termCoverage?: SearchTermCoverageReceipt;
+    /**
+     * 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 = {