@instruments/materialgraph 0.15.0 → 0.16.0

package/by-colour-types.d.ts

@@ -100,6 +100,15 @@ export interface ColourFamilyGate {
      */
     dropped: number;
 }
+/** Receipt for the hard category gate and its treatment of unknown typing. */
+export interface ColourCategoryGate {
+    /** Category names or keys the caller asked the gate to keep. */
+    requested: string[];
+    /** Only accepted primary product types can establish membership. */
+    requiresAcceptedPrimaryProductType: true;
+    /** Unknown/unclassified variants were ineligible, not proven non-members. */
+    unclassifiedVariantsExcluded: true;
+}
 /**
  * Receipt for the colour-identity collapse that turns a variant-grain ranking
  * into a page of TILES — one per (brand, product, dominant hex), one per stored
@@ -177,6 +186,12 @@ export interface ByColourResponse {
      * what says so in counts rather than adjectives.
      */
     familyGate?: ColourFamilyGate;
+    /**
+     * Present only when `category` was asked for. It states that variants without
+     * an accepted primary product type were excluded by the hard gate; absence
+     * means no category gate ran.
+     */
+    categoryGate?: ColourCategoryGate;
     /**
      * What the colour-identity collapse cost this page. Matches are TILES: a page
      * can be SHORTER than `limit` when the pool collapsed harder than the

package/codes-client.d.ts

@@ -45,7 +45,7 @@ export declare class CodesClient {
      * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
      * seeded jurisdictions and their coverage tier, the occupancy groups the
      * registry keys on, finish locations, dimensions, classification scales with
-     * classes ordered best-first, and which `ms_room` term correlates to which
+     * classes ordered best-first, and which `room` term correlates to which
      * regulatory axes.
      *
      * Start here — every value the other two calls accept is listed in this one

package/codes-client.js

@@ -14,7 +14,7 @@ export class CodesClient {
      * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
      * seeded jurisdictions and their coverage tier, the occupancy groups the
      * registry keys on, finish locations, dimensions, classification scales with
-     * classes ordered best-first, and which `ms_room` term correlates to which
+     * classes ordered best-first, and which `room` term correlates to which
      * regulatory axes.
      *
      * Start here — every value the other two calls accept is listed in this one

package/codes-types.d.ts

@@ -62,7 +62,7 @@ export interface CodeContextRequest {
      */
     spaceType?: string;
     /**
-     * An `ms_room` term id (e.g. `"hotel_room"`) to correlate the regulatory axes
+     * A `room` term id (e.g. `"hotel_room"`) to correlate the regulatory axes
      * from. Explicit `occupancyGroup` / `spaceType` always win. A room that
      * correlates to neither axis is a 400 naming the axis — never a guess.
      */
@@ -224,7 +224,7 @@ export interface ResolvedCodeContext {
     spaceType: string;
     sprinklered: boolean;
     basis: OpenEnum<"explicit" | "derived_from_room">;
-    /** The `ms_room` term the axes were correlated from, or null. */
+    /** The `room` term the axes were correlated from, or null. */
     roomType: string | null;
 }
 /**
@@ -271,7 +271,7 @@ export interface CodeContextResponse {
         /** Ordered BEST FIRST: index 0 outranks index 1. */
         classes: string[];
     }[];
-    /** `ms_room` → regulatory axes. `null` where the registry refuses to correlate. */
+    /** `room` → regulatory axes. `null` where the registry refuses to correlate. */
     roomCorrelations: {
         roomType: string;
         label: string;

package/composition-types.d.ts

@@ -86,6 +86,23 @@ export interface CompliancePresetRule {
 export interface CompliancePreset {
     rules: CompliancePresetRule[];
 }
+/** Exact project regulatory axes used to attach bounded code citations. */
+export interface ProgrammeRegulatoryAxes {
+    jurisdictionId: string;
+    occupancyGroup: string;
+    sprinklered: boolean;
+}
+/** One caller-declared Programme space. `spaceType` remains open descriptive text. */
+export interface ComposeDeclaredSpace {
+    name: string;
+    spaceType?: string;
+    /** Exact active canonical `room` id used for bounded code evaluation. */
+    regulatoryRoomType?: string;
+}
+/** The spaces this run is explicitly for; omit to retain brief inference. */
+export interface ComposeDeclaredScope {
+    spaces: ComposeDeclaredSpace[];
+}
 /**
  * The `inputJson` for a `compose-material-schemes` run. `batchId` is required;
  * everything else has a server default. `anchors` (max 24) carry externally
@@ -101,6 +118,10 @@ export interface ComposeMaterialSchemesInput {
     exclusions?: SchemeExclusions;
     anchors?: ComposeAnchorInput[];
     compliancePreset?: CompliancePreset;
+    /** Omit to leave Programme code coverage explicitly unevaluated. */
+    regulatoryAxes?: ProgrammeRegulatoryAxes;
+    /** Explicit caller-held space facts; regulatoryRoomType is never inferred. */
+    scope?: ComposeDeclaredScope;
 }
 /**
  * The state of one criterion verdict cell (MG-627: the shared MaterialGraph

package/exploration-types.d.ts

@@ -7,6 +7,8 @@ export interface GraphOperatorAvailability {
     label: string;
     available: boolean;
     basis: string;
+    discoverable: boolean;
+    discoveryBasis: string;
     count?: number;
 }
 export interface GraphOperatorEvidence {

package/index.d.ts

@@ -38,6 +38,7 @@ export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./search-refinement-types.js";
+export type * from "./search-window-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
 export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";

package/package.json

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

package/resolve-types.d.ts

@@ -25,7 +25,7 @@
  * - `category` — a product-category taxonomy node key.
  * - `attribute` — a registry attribute id: the LEFT half of an `attribute:value`
  *   pair, for `mg.bySpec()` or `search({ filters })`.
- * - `attribute_value` — a value-dictionary term, namespaced (`ms_sheen.matte`):
+ * - `attribute_value` — a value-dictionary term, namespaced (`sheen.matte`):
  *   the RIGHT half.
  * - `jurisdiction` — a code jurisdiction id (`us-tx`), for `mg.codeAdvisory()`.
  * - `occupancy_group` — an IBC occupancy group (`R-1`), the other axis the code

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

@@ -0,0 +1,90 @@
+/**
+ * @module sdk/search-response-receipt-types
+ * @description Inspectable routing, rerank, and compound-constraint receipts
+ * emitted by ordinary Search responses.
+ */
+import type { OpenEnum } from "./types.js";
+/** The single candidate source a query resolved to. */
+export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
+/** Rerank-term report (absent in colour mode — there colour IS the source). */
+export interface SearchRerankReport {
+    colour?: OpenEnum<"ok" | "failed" | "skipped">;
+    colourWeight?: number;
+    colourLabel?: string;
+}
+/** One stage in the explain-only ledger of transformations that actually ran. */
+export type SearchQueryTransformStage = {
+    stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
+    applied: true;
+} | {
+    stage: OpenEnum<"normalise" | "resolve-spec" | "resolve-paint" | "resolve-brand">;
+    applied: false;
+    reason: string;
+};
+/** Explain-only category gate selected by query understanding. */
+export interface SearchCategoryAnchor {
+    productTypeId: string;
+    displayName: string;
+    similarity: number;
+    margin: number | null;
+    source: OpenEnum<"synonym" | "display-name" | "vector">;
+    applied: boolean;
+}
+/** Explain-only brand gate selected by query understanding. */
+export interface SearchBrandAnchor {
+    brandSlug: string;
+    brandName: string;
+    confidence: number;
+    margin: number | null;
+    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 {
+    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 {
+    grain: OpenEnum<"variant" | "product">;
+    weights: {
+        image: number;
+        category: number;
+        colour: number;
+        lexical: number;
+        text: number;
+    };
+    queryTransform: SearchQueryTransformStage[];
+    categoryAnchor?: SearchCategoryAnchor;
+    brandAnchor?: SearchBrandAnchor;
+    brandSkipped?: SearchBrandSkip;
+}
+/** Why a compound colour constraint returned a full or short page. */
+export interface 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 {
+    provenance: OpenEnum<"explicit" | "detected-strong">;
+    family: string;
+    queryHexes: string[];
+    considered: number;
+    kept: number;
+    dropped: number;
+    unknown: number;
+    adjacent: number;
+    abundance?: CompoundColourAbundanceReceipt;
+}

package/search-response-receipt-types.js

@@ -0,0 +1 @@
+export {};

package/search-window-types.d.ts

@@ -0,0 +1,17 @@
+/** The bounded candidate window that produced a search page. */
+export interface SearchWindowReceipt {
+    /** Versioned budget profile; interpret the remaining fields under this version. */
+    profile: "interactive-r1" | (string & {});
+    /** Candidate depth used by the final retrieval. */
+    candidateTier: number;
+    /** Every candidate retrieval, including required fallbacks and optional recovery. */
+    retrievalRounds: number;
+    /** Candidate-retrieval wall time only, in milliseconds. */
+    retrievalMs: number;
+    /** True when the serving source proved there were no more candidates. */
+    exhaustive: boolean;
+    /** True when product-grain scarcity caused one jump to the deep ceiling. */
+    deepened: boolean;
+    /** True when a still-short page exhausted its bounded recovery allowance. */
+    budgetExhausted: boolean;
+}

package/search-window-types.js

@@ -0,0 +1 @@
+export {};

package/types.d.ts

@@ -5,7 +5,7 @@ import type { BySpecVerdict } from "./by-spec-types.js";
  * These interfaces intentionally have NO runtime dependency on any
  * `@materialgraph/*` package — they are a standalone, publishable mirror of the
  * shapes in `apps/web/public/openapi.yaml` and the captured fixtures under
- * `docs/surface/fixtures/v0.5.0/`. The `contract-parity` test re-checks them
+ * `src/__tests__/fixtures/v0.5.0/`. The `contract-parity` test re-checks them
  * against the real Zod schemas so the mirror cannot silently drift.
  * TOLERANT-PARSING CONTRACT: the public surface declares open response enums —
  * "clients must tolerate unknown enum values and unknown fields". Every union
@@ -31,7 +31,9 @@ import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { QueryUnderstanding } from "./query-understanding-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
-/** A widened string-literal union: known members autocomplete, unknown values still type-check. */
+import type { CompoundColourConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport } from "./search-response-receipt-types.js";
+import type { SearchWindowReceipt } from "./search-window-types.js";
+export type * from "./search-response-receipt-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
 /**
  * A JSON value, recursively — exactly what survives a `jsonb` round-trip
@@ -389,14 +391,6 @@ export interface SearchRefinementReceipt {
     schemaVersion: string;
     projectionVersion: number;
 }
-/** The single candidate source a query resolved to. */
-export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse">;
-/** Rerank-term report (absent in colour mode — there colour IS the source). */
-export interface SearchRerankReport {
-    colour?: OpenEnum<"ok" | "failed" | "skipped">;
-    colourWeight?: number;
-    colourLabel?: string;
-}
 /**
  * The search response envelope. `view` discriminates the `results` union:
  * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
@@ -418,7 +412,13 @@ export interface SearchResponse {
     maxScore: number;
     /** Opaque keyset for the next page. Absent = end of the walk, not an error. */
     cursor?: Cursor;
+    /** Boundedness and retrieval-cost receipt on current Search responses. */
+    window?: SearchWindowReceipt;
     rerank?: SearchRerankReport;
+    /** Hard compound-colour eligibility and abundance receipt, when applied. */
+    colourConstraint?: CompoundColourConstraintReceipt;
+    /** Explain-only receipt of the query shape and transform ledger that ran. */
+    plan?: SearchExecutionPlan;
     counts?: SearchCounts;
     /**
      * The `#rrggbb` colours the colour signal ACTUALLY ran on, after