@instruments/materialgraph 0.17.0 → 0.19.0

package/operations.js

@@ -1,7 +1,31 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "scheduleReferences.list",
+        "GET",
+        "/api/v1/schedules/{scheduleId}/references",
+        "list_schedule_reference_feedback",
+    ],
+    [
+        "scheduleReferences.put",
+        "PUT",
+        "/api/v1/schedules/{scheduleId}/references/{referenceId}",
+        "put_schedule_reference_feedback",
+    ],
     ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
+    [
+        "catalogPages",
+        "GET",
+        "/api/v1/catalogs/{catalogId}/pages",
+        "list_catalog_pages",
+    ],
+    [
+        "catalogPageRepresentation",
+        "GET",
+        "/api/v1/catalog-pages/{pageId}/representation",
+        "get_catalog_page_representation",
+    ],
     [
         "catalogReferences",
         "GET",
@@ -10,6 +34,12 @@ const OPERATION_DEFINITIONS = [
     ],
     ["search", "POST", "/api/v1/search", "search_materials_post"],
     ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
+    [
+        "samplizeCatalogue",
+        "GET",
+        "/api/v1/catalogues/samplize/products",
+        "samplize_catalogue_products",
+    ],
     ["searchGet", "GET", "/api/v1/search", "search_materials_get"],
     ["match", "POST", "/api/v1/search/match", "match_material"],
     ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],
@@ -20,6 +50,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/catalogues/references",
         "get_catalogue_references_batch",
     ],
+    [
+        "catalogueCollections",
+        "GET",
+        "/api/v1/catalogues/collections",
+        "list_catalogue_channel_collections",
+    ],
     [
         "catalogueDocumentAccess",
         "GET",
@@ -44,6 +80,18 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/assets",
         "list_material_assets",
     ],
+    [
+        "materialRenderAssets",
+        "GET",
+        "/api/v1/materials/{variantId}/render-assets",
+        "get_material_render_assets",
+    ],
+    [
+        "materialDocuments",
+        "GET",
+        "/api/v1/materials/{variantId}/documents",
+        "list_material_documents",
+    ],
     [
         "exploration.operators",
         "GET",
@@ -91,6 +139,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/pairings",
         "get_material_pairings",
     ],
+    [
+        "findSubstitutes",
+        "POST",
+        "/api/v1/materials/{variantId}/substitutes",
+        "find_material_substitutes",
+    ],
     [
         "associatedFinishes",
         "GET",
@@ -103,6 +157,7 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/associated/products",
         "list_associated_products",
     ],
+    ["applicability", "GET", "/api/v1/applicability", "get_applicability"],
     ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"],
     [
         "materialsCached",
@@ -153,6 +208,12 @@ const OPERATION_DEFINITIONS = [
     ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"],
     ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"],
     ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"],
+    [
+        "productTypeCoverage",
+        "GET",
+        "/api/v1/taxonomy/coverage",
+        "get_product_type_status_coverage",
+    ],
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
     ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
     ["demand", "GET", "/api/v1/demand", "get_material_demand"],
@@ -230,6 +291,7 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/runs/{runId}/schedule",
         "get_run_finish_schedule",
     ],
+    ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"],
     [
         "streamRunEvents",
         "GET",

package/package.json

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

package/palette-search-types.d.ts

@@ -1,3 +1,4 @@
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /**
  * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes` and
  * `POST /api/v1/search/gradients`.
@@ -34,6 +35,7 @@ export interface GradientStop {
     oklab?: OklabTriple;
 }
 export interface SearchPaletteInput {
+    corpusScope?: CorpusScope;
     /** The palette to match, 1–8 colours. */
     colours: PaletteQueryColour[];
     /**
@@ -46,14 +48,15 @@ export interface SearchPaletteInput {
     limit?: number;
 }
 export interface SearchGradientInput {
+    corpusScope?: CorpusScope;
     /** The ordered colour transition, 2–6 stops. */
     stops: GradientStop[];
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
 }
 /**
- * One swatch of a candidate's colorscope-EXTRACTED palette. Derived from product
- * imagery, never a manufacturer's declared colour. `name` is null when no human
+ * One swatch used for scoring. Samplize paint uses its selected published hex;
+ * other materials use colorscope palettes extracted from imagery. `name` is null when no human
  * name was resolved — unnamed, not colourless.
  */
 export interface CandidateSwatch {
@@ -140,14 +143,24 @@ export interface HueGateReceipt {
  * materials match this palette" is not a claim you can make from it.
  */
 export interface SearchPaletteResponse {
+    corpusScope?: CorpusScopeReceipt;
     /** The query as interpreted — check it before trusting a surprising order. */
     query: {
+        /** Colours that actually ran after minor stated shares were omitted. */
         colours: Array<{
             hex: string;
             proportion?: number;
             weight?: number;
         }>;
+        /** Colours not searched because their stated share was below 5%. */
+        droppedColours: Array<{
+            hex: string;
+            proportion?: number;
+            weight?: number;
+        }>;
         logic: PaletteLogic;
+        /** `no_effective_colours` means no material query ran. */
+        outcome: OpenEnum<"matches" | "no_effective_colours">;
     };
     /** The hue-family admission gate this page was scored under. */
     hueGate: HueGateReceipt;
@@ -157,6 +170,7 @@ export interface SearchPaletteResponse {
 }
 /** A PAGE, NOT A CORPUS — see {@link SearchPaletteResponse}. */
 export interface SearchGradientResponse {
+    corpusScope?: CorpusScopeReceipt;
     query: {
         stops: string[];
         /** The sampled path points the search actually ran against. */

package/query-understanding-types.d.ts

@@ -63,7 +63,7 @@ export interface CanonicalLexicalReading {
 export interface CanonicalLexicalMatch {
     original: string;
     canonical: string;
-    rule: OpenEnum<"exact" | "plural-to-singular">;
+    rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
     span: {
         start: number;
         end: number;
@@ -73,7 +73,7 @@ export interface CanonicalLexicalMatch {
     receipt: {
         original: string;
         canonical: string;
-        rule: OpenEnum<"exact" | "plural-to-singular">;
+        rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
         authorities: CanonicalLexicalAuthorityReceipt[];
     };
 }
@@ -158,6 +158,7 @@ export interface QueryProductTypeReceipt {
 export interface QueryArmReceipt {
     arm: OpenEnum<"dense" | "lexical" | "colour"> | null;
     reason: string;
+    reasonDetail?: OpenEnum<"derived-colour-veto" | "typo-recovery" | "literal-compound-without-type">;
     outcome: OpenEnum<"dense" | "lexical" | "colour" | "browse" | "criteria-only" | "ambiguous">;
     decidedBy: OpenEnum<"deterministic" | "model">;
     productTypeGate: OpenEnum<"hard" | "constrain" | "none">;
@@ -189,8 +190,10 @@ export interface QueryCategoryScopeReceipt {
 export interface QuerySpecAllowlistReceipt {
     limit: number;
     returned: number;
+    retrieved?: number;
     truncated: boolean;
     emptyMeansScarcity: boolean;
+    outcome?: OpenEnum<"corpus-scarcity" | "retrieval-miss" | "unknown">;
 }
 export interface QueryUnsatisfiableNarrowing {
     narrowing: OpenEnum<"product-type">;

package/render-assets-types.d.ts

@@ -0,0 +1,65 @@
+import type { VariantId } from "./identifiers.js";
+export type RenderAssetChannelRole = "base-color" | "normal" | "roughness" | "metalness" | "height" | "ambient-occlusion";
+export type RenderAssetSourceBasis = "catalog_feed" | "declared" | "derived";
+export type RenderAssetUnavailableReason = "no_accepted_appearance" | "pending" | "withheld" | "rejected" | "superseded" | "variant_inactive" | "delivery_unverified" | "integrity_error";
+export interface RenderAssetFreshness {
+    revision: string;
+    updatedAt: string | null;
+    checkedAt: string | null;
+}
+export interface RenderAssetChannel {
+    role: RenderAssetChannelRole;
+    url: string;
+    sha256: string;
+    byteSize: number;
+    mimeType: "image/png";
+    width: number;
+    height: number;
+    bitDepth: 8 | 16;
+    colorSpace: "srgb" | "linear";
+}
+export interface MaterialRenderAssetsAvailable {
+    schemaVersion: "pbr-render-assets/v1";
+    variantId: VariantId;
+    status: "available";
+    setId: string;
+    state: "accepted";
+    sourceBasis: "derived";
+    fidelity: "unassessed";
+    acceptance: {
+        id: string;
+        verificationDecisionId: string;
+        acceptedAt: string;
+        checkVersion: string;
+        qa: {
+            status: "passed";
+            checkCount: number;
+        };
+        checkCount: number;
+    };
+    physicalRepeat: {
+        uMm: number;
+        vMm: number;
+        basis: "declared" | "measured";
+    };
+    tiling: {
+        u: boolean;
+        v: boolean;
+    };
+    normalConvention: "opengl" | "directx";
+    heightAmplitudeMm?: number;
+    channels: RenderAssetChannel[];
+    supersedesSetIds: string[];
+    freshness: RenderAssetFreshness;
+}
+export interface MaterialRenderAssetsUnavailable {
+    schemaVersion: "pbr-render-assets/v1";
+    variantId: VariantId;
+    status: "unavailable";
+    setId: string | null;
+    state: "pending" | "withheld" | "rejected" | "superseded" | "accepted" | null;
+    sourceBasis: RenderAssetSourceBasis | null;
+    reasonCodes: RenderAssetUnavailableReason[];
+    freshness: RenderAssetFreshness;
+}
+export type MaterialRenderAssets = MaterialRenderAssetsAvailable | MaterialRenderAssetsUnavailable;

package/render-assets-types.js

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

package/run-events.d.ts

@@ -47,9 +47,22 @@ export interface CompositionReviewCriteriaSuggestion {
     term?: string;
     score: number;
 }
+/** Exact UTF-16 passage retained from the brief; no page coordinate is implied. */
+export interface CompositionBriefCriterionSourceRef {
+    sourceId: string;
+    quote: string;
+    textRange: {
+        start: number;
+        end: number;
+        unit: "utf16";
+    };
+}
 export interface CompositionReviewCriteriaUnresolved {
     slotId: string;
+    /** Unresolved negative language requires an explicit review decision. */
+    polarity?: "exclusion";
     raw: string;
+    sourceRefs?: CompositionBriefCriterionSourceRef[];
     /**
      * Ranked corrections, best first. MG-994: every one of these is an attribute
      * the slot's own category holds accepted values for, so accepting the top

package/samplize-catalogue-types.d.ts

@@ -0,0 +1,92 @@
+export interface SamplizeCatalogueOptions {
+    limit?: number;
+    after?: string;
+    /** Pin every subsequent page to the version returned by the first page. */
+    sourceVersion?: string;
+}
+export interface SamplizeCatalogueProduct {
+    variantId: string;
+    productId: string;
+    name: string;
+    code: string;
+    brand: {
+        slug: string;
+        name: string;
+    };
+    hex: string;
+    hexSource: {
+        publisher: "Samplize";
+        url: string;
+        source: "snowflake_product_tags";
+    };
+    lrv: number | null;
+    lrvSource: SamplizeLrvObservation | null;
+    lrvObservations: SamplizeLrvObservation[];
+    /** The primary sample variant count, never an aggregate of product orders. */
+    demand: SamplizeDemand | null;
+    collectionMemberships: SamplizeCollectionMembership[];
+    colourAnalysis: Record<string, unknown>;
+    oklab: {
+        L: number;
+        a: number;
+        b: number;
+    };
+    sourceProductId: string;
+    url: string;
+    sizeVariants: Array<{
+        sourceVariantId: string;
+        sku: string | null;
+        title: string | null;
+        price: number | null;
+        inventoryAvailable: boolean;
+        demand: SamplizeDemand | null;
+    }>;
+    publishedHexes: SamplizeHexObservation[];
+    hexObservations: SamplizeHexObservation[];
+}
+export interface SamplizeCataloguePage {
+    schemaVersion: 2;
+    corpusScope: "samplizeCatalogue";
+    sourceVersion: string;
+    source: Record<string, unknown>;
+    total: number;
+    items: SamplizeCatalogueProduct[];
+    nextCursor: string | null;
+    /** True on the final page; completeness requires collecting total unique IDs. */
+    complete: boolean;
+}
+export interface SamplizeHexObservation {
+    hex: string;
+    publisher: string;
+    source: string;
+    sourceUrl: string | null;
+    sourceBasis: string;
+    observedAt: string | null;
+    differsFromSelected: boolean;
+}
+export interface SamplizePublicationSource {
+    publisher: "Samplize";
+    source: "algolia_shopify_products";
+    sourceUrl: string;
+    observedAt: string | null;
+}
+export interface SamplizeLrvObservation extends SamplizePublicationSource {
+    field: string;
+    value: number;
+}
+export interface SamplizeDemand extends SamplizePublicationSource {
+    field: "recently_ordered_count";
+    sourceVariantId: string;
+    grain: "shopify_variant";
+    recentlyOrderedCount: number;
+    /** The publisher does not supply the time window. */
+    window: null;
+}
+export interface SamplizeCollectionMembership {
+    sourceCollectionId: string;
+    handle: string;
+    url: string;
+    publisher: "Samplize";
+    source: "algolia_shopify_products";
+    observedAt: string | null;
+}

package/samplize-catalogue-types.js

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

package/schedule-reference-types.d.ts

@@ -0,0 +1,46 @@
+/** A personal preference; diminished references stay on the research board. */
+export type ScheduleReferenceInfluence = "kept" | "diminished";
+export interface PutScheduleReferenceFeedback {
+    /** Reuse unchanged after an uncertain response; a different command needs a new id. */
+    requestId: string;
+    /** The version last read for this reference, or zero before its first decision. */
+    expectedFeedbackVersion: number;
+    sourceRunId: string;
+    influence: ScheduleReferenceInfluence;
+}
+export type ScheduleReferenceSource = {
+    kind: "image";
+    laneId: string;
+    imageRef: string;
+    sourceName: string;
+    sourceDomain: string;
+    url: string | null;
+    caption: string;
+} | {
+    kind: "web";
+    domain: string;
+    url: string;
+    statement: string;
+    implication: string;
+};
+/** Immutable receipt for one decision, including the exact research frame it came from. */
+export interface ScheduleReferenceFeedback {
+    eventId: string;
+    scheduleId: string;
+    referenceId: string;
+    version: number;
+    requestId: string;
+    sourceRunId: string;
+    sourceEventSequence: number;
+    source: ScheduleReferenceSource;
+    scope: {
+        kind: "project";
+    };
+    originalVerdict: "kept" | "set-aside";
+    influence: ScheduleReferenceInfluence;
+    decidedByPrincipalId: string;
+    decidedAt: string;
+}
+export interface ScheduleReferenceFeedbackList {
+    items: ScheduleReferenceFeedback[];
+}

package/schedule-reference-types.js

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

package/schedule-references-client.d.ts

@@ -0,0 +1,14 @@
+import type { HttpTransport } from "./http-transport.js";
+import type { PutScheduleReferenceFeedback, ScheduleReferenceFeedback, ScheduleReferenceFeedbackList } from "./schedule-reference-types.js";
+/** Schedule-owned preferences, independent of an issued document's revision. */
+export declare class ScheduleReferencesClient {
+    #private;
+    constructor(transport: HttpTransport);
+    /** Read the latest saved preference for each reference. Empty means no decisions yet. */
+    list(scheduleId: string, signal?: AbortSignal): Promise<ScheduleReferenceFeedbackList>;
+    /**
+     * Save or reverse a preference. An exact request replay returns its original receipt;
+     * it does not undo newer decisions. A stale reference version raises a 409.
+     */
+    put(scheduleId: string, referenceId: string, input: PutScheduleReferenceFeedback, signal?: AbortSignal): Promise<ScheduleReferenceFeedback>;
+}

package/schedule-references-client.js

@@ -0,0 +1,26 @@
+import { resolveOperation } from "./operations.js";
+/** Schedule-owned preferences, independent of an issued document's revision. */
+export class ScheduleReferencesClient {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /** Read the latest saved preference for each reference. Empty means no decisions yet. */
+    list(scheduleId, signal) {
+        return this.#transport.requestJson(resolveOperation("list_schedule_reference_feedback"), {
+            pathParams: { scheduleId },
+            signal,
+        });
+    }
+    /**
+     * Save or reverse a preference. An exact request replay returns its original receipt;
+     * it does not undo newer decisions. A stale reference version raises a 409.
+     */
+    put(scheduleId, referenceId, input, signal) {
+        return this.#transport.requestJson(resolveOperation("put_schedule_reference_feedback"), {
+            pathParams: { scheduleId, referenceId },
+            body: input,
+            signal,
+        });
+    }
+}

package/schedule-types.d.ts

@@ -1,3 +1,4 @@
+import type { VerdictCitation } from "./citation-types.js";
 /**
  * Finish-schedule wire types (MG-616) — the hand-mirror of
  * `@materialgraph/products/schemes/finish-schedule`. Kept in their own module
@@ -51,6 +52,8 @@ export interface FinishScheduleCell {
     state: FinishScheduleCellState;
     confidence: number | null;
     sourceBasis: string | null;
+    /** Omitted when the exact current claim has no supporting source. */
+    citation?: VerdictCitation;
 }
 /**
  * The rolled-up grade for one row, from its EVALUATED criterion cells only.
@@ -59,6 +62,33 @@ export interface FinishScheduleCell {
  * `hard_no` means a required cell failed on a real value.
  */
 export type FinishScheduleGrade = "meets_all" | "close" | "hard_no";
+/** Exact retained brief passage behind a schedule criterion. */
+export interface FinishScheduleCriterionSourceRef {
+    sourceId: string;
+    quote: string;
+    textRange: {
+        start: number;
+        end: number;
+        unit: "utf16";
+    };
+}
+/** Brief criterion carried into the issued row, including explicit exclusions. */
+export type FinishScheduleCriterion = {
+    kind: "attribute" | "attribute-presence" | "attribute-exclusion" | "attribute-numeric" | "unresolved";
+    raw: string;
+    attributeId?: string;
+    term?: string;
+    comparator?: "at-least" | "at-most";
+    value?: number;
+    unit?: string;
+    polarity?: "exclusion";
+    coverageNote?: string;
+    suggestion?: {
+        attributeId: string;
+        term?: string;
+    };
+    sourceRefs?: FinishScheduleCriterionSourceRef[];
+};
 /** One numbered section of the schedule, and the heading it prints. */
 export interface FinishScheduleSection {
     /** The hundreds block, e.g. `100`. Also the base of every line number in it. */
@@ -147,6 +177,10 @@ export interface FinishScheduleOpenSlot {
 }
 /** One row: one slot, one specified material, fully graded. */
 export interface FinishScheduleRow {
+    /** Criteria carried from the programme; absent on older schedule artifacts. */
+    criteria?: FinishScheduleCriterion[];
+    requiredCriteria?: FinishScheduleCriterion[];
+    preferredCriteria?: FinishScheduleCriterion[];
     /**
      * The printed line reference, e.g. `L-101` — how a drawing, an RFI or a
      * substitution request names this line. Allocated from the Run's PROGRAMME

package/search-collapse-types.d.ts

@@ -50,7 +50,7 @@ export interface CollapsedVariant {
      * ABSENT means no MB identity is on record, never that it cannot be ordered.
      */
     materialBankId?: string;
-    /** This variant's own fused score — the value the array is ordered by. */
+    /** This variant's own mode-primary score — the value the array is ordered by. */
     score: number;
 }
 /**

package/search-mood-types.d.ts

@@ -0,0 +1,6 @@
+/** What a standard search did, and did not, recognize as a governed mood. */
+export interface MoodInterpretation {
+    query: string | null;
+    moodId: string | null;
+    supersededMoodId: string | null;
+}

package/search-mood-types.js

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

package/search-refinement-types.d.ts

@@ -56,6 +56,11 @@ export type SearchFilter = {
     attributeId: string;
     term: string;
     trust?: SearchFilterTrust;
+} | {
+    /** Known effective values are required, and this term must be absent. */
+    attributeId: string;
+    excludesTerm: string;
+    trust?: SearchFilterTrust;
 }
 /**
  * TERM SET — the attribute must equal any ONE of these. OR within the entry;