@instruments/materialgraph 0.18.0 → 0.19.0

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-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;

package/search-request-types.d.ts

@@ -1,3 +1,4 @@
+/** samplizeCatalogue admits published US Samplize paint colours, regardless of stock. */
 /**
  * @module search-request-types
  * The two request shapes for the `/search` surface — the POST JSON body and the
@@ -148,6 +149,8 @@ export interface SearchInput {
     refinementToken?: string;
     /** Only return materials with at least one catalog image. Default false (full catalog). */
     hasImages?: boolean;
+    /** Require a recorded accepted sampleable=true fact; unknown and false are excluded. */
+    sampleableOnly?: boolean;
     /**
      * Opt-in seed-relative verdict cells (MG-629). Only meaningful with
      * `similarTo: { variantId }`: each hit's `verdict` gains `preferred` cells
@@ -227,6 +230,8 @@ export interface SearchGetParams {
     count?: OpenEnum<"true">;
     /** "true" — only return materials with at least one catalog image. */
     hasImages?: OpenEnum<"true">;
+    /** Require a recorded accepted sampleable=true fact. */
+    sampleableOnly?: OpenEnum<"true" | "false">;
     /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
     /**

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

@@ -4,6 +4,14 @@
  * receipts emitted by ordinary Search responses.
  */
 import type { OpenEnum } from "./types.js";
+/** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
+export interface 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">;
 /**

package/search-result-validation.js

@@ -143,6 +143,15 @@ function checkAttributeVerdict(value, what, fail) {
     requireNullableString(record.value, `${what}.value`, fail);
     requireNullableBoundedNumber(record.confidence, `${what}.confidence`, fail, 0, 1);
     requireNullableString(record.sourceBasis, `${what}.sourceBasis`, fail);
+    if (record.citation !== undefined) {
+        const citation = requireRecord(record.citation, `${what}.citation`, fail);
+        requireNonEmptyString(citation.citationId, `${what}.citation.citationId`, fail);
+        requireNonEmptyString(citation.sourceType, `${what}.citation.sourceType`, fail);
+        const count = requireNumber(citation.count, `${what}.citation.count`, fail);
+        if (!Number.isInteger(count) || count <= 0) {
+            throw fail(`${what}.citation.count must be a positive integer`);
+        }
+    }
     const deviation = record.deviation;
     if (deviation !== null)
         checkVerdictDeviation(deviation, `${what}.deviation`, fail);
@@ -207,6 +216,7 @@ export function checkSearchResultItem(value, what, fail) {
     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);
     requireOptionalBoolean(record.admittedOnColour, `${what}.admittedOnColour`, fail);
     if (record.siblingCount !== undefined) {

package/slot-pool-types.d.ts

@@ -25,6 +25,7 @@
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
  * so a new server value still type-checks; objects are read structurally.
  */
+import type { VerdictCitation } from "./citation-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
@@ -147,6 +148,7 @@ export interface SlotPoolVerdictCell {
      */
     sourceBasis: string | null;
     trustGap: OpenEnum<"below_confidence" | "basis_unmet" | "proposed"> | null;
+    citation?: VerdictCitation;
 }
 /** Why a candidate is labelled. An eligible candidate carries none of these. */
 export type SlotPoolFlag = OpenEnum<"below-floor" | "required-not-applied" | "discontinued" | "superseded" | "unverified-value">;

package/spec-types.d.ts

@@ -64,6 +64,11 @@ export interface SpecTermFilter {
     attributeId: string;
     term: string;
 }
+/** A negative spec criterion; absence of a value remains unproven. */
+export interface SpecExclusionFilter {
+    attributeId: string;
+    excludesTerm: string;
+}
 /**
  * A presence spec criterion: the attribute must have ANY accepted value —
  * "has an EPD on record", "has a measured slip figure at all". Not supported for
@@ -94,4 +99,4 @@ export interface CertificationProgrammeFilter {
  * presence check. The union the search engine applies as a restriction BEFORE
  * ranking. Identical in shape to the SDK's `SearchFilter`.
  */
-export type SpecFilter = SpecTermFilter | SpecPresenceFilter;
+export type SpecFilter = SpecTermFilter | SpecExclusionFilter | SpecPresenceFilter;

package/specifications.d.ts

@@ -14,7 +14,9 @@
  * hand-format the `attribute:value` string the `bySpec` route splits on its
  * first `:`.
  */
-import { type CertificationProgrammeFilter, type SpecPresenceFilter, type SpecTermFilter } from "./spec-types.js";
+import { type CertificationProgrammeFilter, type SpecExclusionFilter, type SpecPresenceFilter, type SpecTermFilter } from "./spec-types.js";
+/** A hard criterion excluding one known canonical value while retaining only variants with known values. */
+export declare function excludeSpec(attributeId: string, excludesTerm: string): SpecExclusionFilter;
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.

package/specifications.js

@@ -15,6 +15,10 @@
  * first `:`.
  */
 import { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, } from "./spec-types.js";
+/** A hard criterion excluding one known canonical value while retaining only variants with known values. */
+export function excludeSpec(attributeId, excludesTerm) {
+    return { attributeId, excludesTerm };
+}
 /**
  * A term-equality criterion for `search({ filters })` — the attribute must
  * carry this canonical value.

package/substitute-types.d.ts

@@ -0,0 +1,75 @@
+import type { BySpecVerdict } from "./by-spec-types.js";
+import type { VariantId } from "./identifiers.js";
+import type { MaterialSuccessor } from "./material-types.js";
+export type SubstituteSignatureFamily = "textile" | "tile" | "coating" | "lighting_electrical" | "acoustic" | "surface" | "furniture" | "sanitaryware" | "fittings" | "architectural_hardware";
+export interface SubstituteSignatureCriterion {
+    role: "primary_material" | "performance";
+    attributeId: string;
+    term: string;
+}
+export interface AvailableSubstituteSignature {
+    family: SubstituteSignatureFamily;
+    form: string;
+    criteria: [SubstituteSignatureCriterion, SubstituteSignatureCriterion];
+}
+export interface UnsupportedSubstituteSignature {
+    family: SubstituteSignatureFamily;
+    form: string;
+    reason: string;
+}
+export interface InsufficientSubstituteSignature {
+    family: SubstituteSignatureFamily;
+    form: string;
+    missingRoles: ("primary_material" | "performance")[];
+}
+export interface FindSubstitutesOptions {
+    excludeBrands?: string[];
+    diversityBoost?: number;
+    limit?: number;
+    cursor?: string;
+    includeSamplingArtifacts?: boolean;
+    includeUnavailable?: boolean;
+}
+export interface SubstituteMatchedCriterion {
+    attributeId: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+export interface SubstituteResultItem {
+    variantId: VariantId;
+    brandSlug: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    matched: SubstituteMatchedCriterion[];
+    minConfidence: number | null;
+    baseScore: number;
+    diversityAdjustment: number;
+    score: number;
+    verdict: BySpecVerdict;
+}
+export interface AvailableSubstitutesResponse {
+    status: "available";
+    signatureUsed: AvailableSubstituteSignature;
+    items: SubstituteResultItem[];
+    candidatePoolSize: number;
+    droppedUnavailable: number;
+    supersededBy: MaterialSuccessor | null;
+    nextCursor?: string;
+}
+export interface UnsupportedSubstitutesResponse {
+    status: "unsupported";
+    signature: UnsupportedSubstituteSignature;
+    items: [];
+    supersededBy: MaterialSuccessor | null;
+}
+export interface InsufficientSubstitutesResponse {
+    status: "insufficient_signature";
+    signature: InsufficientSubstituteSignature;
+    items: [];
+    supersededBy: MaterialSuccessor | null;
+}
+export type FindSubstitutesResponse = AvailableSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;

package/substitute-types.js

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

package/taxonomy-coverage-types.d.ts

@@ -0,0 +1,34 @@
+/** Exact, source-path-grained status coverage for primary product typing. */
+export interface ProductTypeStatusCoverageCounts {
+    variants: number;
+    accepted: number;
+    proposed: number;
+    proposedBelowThreshold: number;
+    /** Proposed rows with no confidence remain explicit rather than thresholded. */
+    proposedUnknownConfidence: number;
+    otherStatus: number;
+    missingPrimary: number;
+}
+export interface ProductTypeStatusCoverageSourcePath extends ProductTypeStatusCoverageCounts {
+    /** Complete stored source path; null means the product retained no path. */
+    sourcePath: string | null;
+}
+/** Current primary-assignment coverage, never an inferred acceptance decision. */
+export interface ProductTypeStatusCoverage {
+    computedAt: string;
+    basis: {
+        count: "exact";
+        universe: "non_superseded_variants";
+        assignment: "variant_primary_only";
+        sourcePath: "products.source_category_path";
+        /** Reporting cutoff only: higher-confidence proposals remain proposed. */
+        comparisonThreshold: number;
+    };
+    totals: ProductTypeStatusCoverageCounts;
+    sourcePaths: ProductTypeStatusCoverageSourcePath[];
+}
+export interface ProductTypeCoverageOptions {
+    [key: string]: number | undefined;
+    /** Reporting cutoff in [0,1], default 0.85; it never accepts a proposal. */
+    comparisonThreshold?: number;
+}

package/taxonomy-coverage-types.js

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