@instruments/materialgraph 0.6.1 → 0.7.1

package/by-spec-types.d.ts

@@ -1,3 +1,4 @@
+import type { ValueResolution } from "./catalog-discovery-types.js";
 import type { VariantId } from "./identifiers.js";
 /**
  * One criterion a match satisfied, with the trust behind it.
@@ -107,6 +108,32 @@ export interface BySpecMatch {
     minConfidence: number | null;
     verdict: BySpecVerdict;
 }
+/**
+ * One criterion the server could not resolve to canonical vocabulary, with the
+ * resolver's ranked suggestions for it.
+ *
+ * `attributeId` and `value` echo the parsed criterion, both of them, so a failed
+ * query can be restated without losing either half. (The HTTP route trims the
+ * attribute and value around the first `:` before validation.) Which HALF failed
+ * is read off `resolution.query`, the token actually resolved:
+ *
+ * - `resolution.query === attributeId` — the attribute id is unknown, and
+ *   `resolution.candidates` are ATTRIBUTE ids.
+ * - `resolution.query === value` — the attribute is known but its value is no
+ *   canonical term, and `resolution.candidates` are TERM ids, each carrying the
+ *   `dictionaryId` it came from.
+ *
+ * EVERY miss is reported, not just the first, so one round trip is enough to fix
+ * a whole spec.
+ */
+export interface BySpecUnresolvedCriterion {
+    /** The parsed attribute id, after the route's surrounding-whitespace trim. */
+    attributeId: string;
+    /** The parsed value — never overwritten by the attribute id when that id is unknown. */
+    value: string;
+    /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
+    resolution: ValueResolution;
+}
 /**
  * The find-by-spec envelope — A PAGE, AND NOTHING BUT A PAGE.
  *
@@ -116,6 +143,9 @@ export interface BySpecMatch {
  * states NO corpus total, so "N materials meet this specification" is not a
  * claim you can make from one response. Raise `limit`, or say "at least N".
  * `brandsSpanned` is likewise the brand count OF THIS SAMPLE.
+ *
+ * And check `unresolvedCriteria` BEFORE reading any of that: when it is present
+ * the numbers beside it describe a query that never ran.
  */
 export interface BySpecResponse {
     /** The criteria as parsed — check them before trusting a surprising result. */
@@ -129,4 +159,19 @@ export interface BySpecResponse {
     brandsSpanned: number;
     /** The sample, photo-first, capped by `limit`. */
     matches: BySpecMatch[];
+    /**
+     * Present ONLY when a criterion failed exact canonical-vocabulary membership —
+     * and its presence means THE QUERY WAS NEVER RUN. A pre-flight gate short-circuits
+     * before the search, so the rest of the envelope is a placeholder rather than
+     * a finding: `matches` is `[]` and `totalMatches` is `0` because nothing was
+     * searched, not because nothing qualifies. Reporting that zero as "no material
+     * meets this specification" states a fact about the corpus on the strength of
+     * a question nobody asked it.
+     *
+     * Treat these criteria as UNAPPLIED and surface them: retry with a
+     * `resolution.candidates` id (subject to `recommendedAction` — `ambiguous`
+     * means ask, not pick), or say the value could not be resolved. Absent means
+     * every criterion resolved and the query did run.
+     */
+    unresolvedCriteria?: BySpecUnresolvedCriterion[];
 }

package/catalog-discovery-types.d.ts

@@ -24,6 +24,34 @@ export interface ResolveValueCandidate {
     /** Present only for a colour_family candidate resolved via the colorscope fallback. */
     via?: OpenEnum<"colorscope">;
 }
+/**
+ * The resolver's verdict on ONE free-text token — the single shape every
+ * resolving surface speaks, so a caller learns to read it once. Returned whole
+ * by {@link MaterialGraphClient.resolveAttributeValue}, and carried per bad
+ * criterion by `bySpec`'s `unresolvedCriteria`.
+ *
+ * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
+ * `candidates` list means the phrase genuinely matched several terms — taking
+ * `best` silently there is how a query ends up answering a question nobody
+ * asked. `unresolved` means no candidate cleared the resolver's confidence
+ * threshold (and may still carry weak candidates); it says nothing about how
+ * many materials would match a corrected criterion.
+ *
+ * The resolver ranks, classifies and reports; it never substitutes the nearest
+ * token for the one you asked for. `best` is populated whenever ANY candidate
+ * exists — including under an `ambiguous` or `unresolved` status — so it is a
+ * leader, not a licence.
+ *
+ * `query` is the trimmed token that was actually resolved, which is how you tell
+ * WHICH half of a failed `attribute:value` pair was the problem.
+ */
+export interface ValueResolution {
+    status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
+    query: string;
+    best: ResolveValueCandidate | null;
+    candidates: ResolveValueCandidate[];
+    recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
+}
 /** Response from resolving a free-text value against one attribute's dictionary. */
 export interface ResolveAttributeValueResponse {
     attribute: {
@@ -31,20 +59,8 @@ export interface ResolveAttributeValueResponse {
         name: string;
         dictionaryId: string;
     };
-    /**
-     * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
-     * `candidates` list means the phrase genuinely matched several terms — taking
-     * `best` silently there is how a query ends up answering a question nobody
-     * asked. `unresolved` means the vocabulary holds nothing like it, which is not
-     * the same as the corpus holding no such materials.
-     */
-    resolution: {
-        status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
-        query: string;
-        best: ResolveValueCandidate | null;
-        candidates: ResolveValueCandidate[];
-        recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
-    };
+    /** The verdict on `q`. Read `recommendedAction` — see {@link ValueResolution}. */
+    resolution: ValueResolution;
 }
 /** Options for searching registry attributes and value-dictionary terms together. */
 export interface VocabularySearchOptions {

package/client.d.ts

@@ -333,7 +333,10 @@ export declare class MaterialGraphClient {
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
      * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens — guessing one returns an honest, empty answer.
+     * the canonical tokens. Guessing one no longer returns a silently empty
+     * answer: an unresolvable criterion means the query NEVER RAN, and the
+     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
+     * treating an empty `matches` as "nothing qualifies".
      *
      * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
      * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.

package/client.js

@@ -294,7 +294,9 @@ export class MaterialGraphClient {
      * you how much of the rail is real order evidence.
      */
     pairings(variantId, options, signal) {
-        return this.#get("get_material_pairings", { categories: options?.categories, limit: options?.limit }, signal, { variantId });
+        return this.#get("get_material_pairings", { ...options }, signal, {
+            variantId,
+        });
     }
     materials(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {
@@ -396,7 +398,10 @@ export class MaterialGraphClient {
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
      * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens — guessing one returns an honest, empty answer.
+     * the canonical tokens. Guessing one no longer returns a silently empty
+     * answer: an unresolvable criterion means the query NEVER RAN, and the
+     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
+     * treating an empty `matches` as "nothing qualifies".
      *
      * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
      * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "type": "module",
   "exports": {
     ".": {

package/types.d.ts

@@ -395,6 +395,8 @@ export interface CospecPairing {
     liftLabel: string;
     demand: CompanionDemand | null;
     topProjectTypes: ProjectTypeShare[];
+    /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
+    ranking?: PairingRanking;
 }
 /**
  * A pairing item topped up from colour palette-similarity — a LOOK-ALIKE, not
@@ -405,6 +407,30 @@ export interface CospecPairing {
 export interface ColourPairing extends MaterialTile {
     source: "colour";
     score: number;
+    /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
+    ranking?: PairingRanking;
+}
+export type PairingOrderMode = "relevance" | "lightness_asc" | "lightness_desc";
+export type PairingCorpus = "all" | "material_bank";
+export interface PairingRanking {
+    anchorColourSimilarity: number | null;
+    lightness: number | null;
+    anchorColourSimilarityMeasurable: boolean;
+    lightnessMeasurable: boolean;
+    basis: OpenEnum<"dominant_colour_oklab">;
+}
+export interface PairingOrdering {
+    requested: OpenEnum<PairingOrderMode>;
+    applied: OpenEnum<PairingOrderMode>;
+    direction: OpenEnum<"ascending" | "descending">;
+    anchorColourBasis: OpenEnum<"one_minus_oklab_euclidean_distance">;
+    colourSpace: OpenEnum<"oklab">;
+    lightnessRange: {
+        min: 0;
+        max: 1;
+    };
+    missingValues: OpenEnum<"last">;
+    tieBreak: OpenEnum<"variantId_asc">;
 }
 /**
  * One pairing, discriminated by `source` into three tiers of very different
@@ -422,6 +448,10 @@ export interface PairingsResponse {
      * check it before presenting the rail as demand evidence.
      */
     cospecCount: number;
+    /** Present only when `order` was requested. Evidence tiers remain independent. */
+    ordering?: PairingOrdering;
+    /** Opaque continuation bound to the seed, filters, corpus, and order. */
+    nextCursor?: Cursor;
 }
 export interface MaterialResponse {
     material: MaterialDetail;
@@ -665,7 +695,14 @@ export interface MaterialsBatchOptions {
 export interface PairingsOptions {
     /** Comma-separated coarse category display names; filters both arms. */
     categories?: string;
+    /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
     limit?: number;
+    /** Graph-owned order applied within fixed cospec → considered → colour tiers. */
+    order?: PairingOrderMode;
+    /** Optional Material Bank/orderable gate; requires an explicit `order`. */
+    corpus?: PairingCorpus;
+    /** The previous response's `nextCursor`, passed back verbatim. */
+    cursor?: Cursor;
 }
 /** Options for `catalog/attributes/resolve`. */
 export interface ResolveAttributeOptions {