@instruments/materialgraph 0.18.0 → 0.20.0

package/samplize-colorvec.js

@@ -0,0 +1,167 @@
+import { EMBEDDING_VERSION, EMBEDDING_VECTOR_SIZE, embeddingCosineSimilarity, paletteToEmbedding, } from "@instruments/colorscope/embedding";
+export const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
+export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
+const decodeVector = (encoded) => {
+    const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
+    if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4)
+        throw new Error("Invalid colour vector size.");
+    const view = new DataView(bytes.buffer);
+    return Array.from({ length: EMBEDDING_VECTOR_SIZE }, (_, i) => view.getFloat32(i * 4, true));
+};
+const facets = ["brand", "family", "lightness", "intensity"];
+const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const samplizeSolidColorVector = (hex) => {
+    if (!/^#[0-9a-f]{6}$/i.test(hex))
+        throw new Error("A six-digit published colour is required.");
+    return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
+};
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export function selectSamplizeEligiblePaints(paints, input) {
+    const reference = input.reference
+        ? paints.find((p) => p.variantId === input.reference)
+        : undefined;
+    if (input.reference && !reference)
+        throw new Error("The reference is absent from this catalogue version.");
+    const low = input.lightnessMin ?? 0, high = input.lightnessMax ?? 1;
+    const cool = input.temperatureMin ?? -0.4, warm = input.temperatureMax ?? 0.4;
+    if (![low, high, cool, warm].every(Number.isFinite) ||
+        low > high ||
+        cool > warm)
+        throw new Error("Appearance ranges must be finite and ordered.");
+    const candidates = paints.filter((p) => {
+        if (!reference)
+            return true;
+        if (p.variantId === reference.variantId)
+            return false;
+        if (input.direction === "lighter")
+            return p.oklab.L > reference.oklab.L;
+        if (input.direction === "darker")
+            return p.oklab.L < reference.oklab.L;
+        if (input.direction === "muted")
+            return (Math.hypot(p.oklab.a, p.oklab.b) <
+                Math.hypot(reference.oklab.a, reference.oklab.b));
+        return true;
+    });
+    const matches = (p, omit) => p.oklab.L >= low &&
+        p.oklab.L <= high &&
+        p.oklab.b >= cool &&
+        p.oklab.b <= warm &&
+        facets.every((f) => f === omit || !input[f]?.length || input[f].includes(p[f]));
+    const counts = {
+        brand: {},
+        family: {},
+        lightness: {},
+        intensity: {},
+    };
+    for (const p of candidates)
+        for (const f of facets)
+            if (matches(p, f))
+                counts[f][p[f]] = (counts[f][p[f]] ?? 0) + 1;
+    const eligible = candidates.filter((p) => matches(p));
+    return { reference, eligible, counts };
+}
+/** Official portable MG ranking over its complete versioned sampling-channel projection. */
+export function createSamplizeColorVecIndex(cache) {
+    if (cache.embeddingVersion !== EMBEDDING_VERSION ||
+        cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION)
+        throw new Error("The colour cache uses an incompatible embedding or ranking version. Refresh it before searching.");
+    if (!cache.sourceVersion ||
+        !cache.dictionaryVersion ||
+        !Number.isFinite(Date.parse(cache.generatedAt)))
+        throw new Error("The colour cache is missing its provenance.");
+    const paints = cache.paints.map((p) => ({
+        ...p,
+        vector: typeof p.vector === "string" ? decodeVector(p.vector) : p.vector,
+    }));
+    const identities = new Set();
+    for (const paint of paints) {
+        if (identities.has(paint.variantId) ||
+            paint.vector.length !== EMBEDDING_VECTOR_SIZE ||
+            !paint.vector.every(Number.isFinite) ||
+            ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite))
+            throw new Error("The colour cache contains invalid or duplicate paint records.");
+        identities.add(paint.variantId);
+    }
+    const vectors = new Map();
+    const vectorFor = (hex) => {
+        const key = hex.toLowerCase();
+        let value = vectors.get(key);
+        if (!value) {
+            value = samplizeSolidColorVector(hex);
+            if (vectors.size >= 512)
+                vectors.delete(vectors.keys().next().value);
+            vectors.set(key, value);
+        }
+        return value;
+    };
+    return {
+        search(input) {
+            const limit = input.limit ?? 48;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                throw new Error("Choose between 1 and 100 suggestions.");
+            const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
+            const palette = (input.palette?.length
+                ? input.palette
+                : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
+                .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
+                .sort((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
+            if (palette.length > 12 ||
+                palette.some((p) => !Number.isFinite(p.proportion) ||
+                    p.proportion <= 0 ||
+                    p.proportion > 1))
+                throw new Error("Supply up to twelve positive image colour shares.");
+            const total = palette.reduce((sum, p) => sum + p.proportion, 0);
+            const buckets = palette.map((p, position) => ({
+                ...p,
+                position,
+                vector: vectorFor(p.hex),
+                quota: Math.floor((limit * p.proportion) / total),
+                remainder: ((limit * p.proportion) / total) % 1,
+                paints: [],
+            }));
+            let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
+            for (const p of [...buckets].sort((a, b) => b.remainder - a.remainder || a.position - b.position))
+                if (remaining-- > 0)
+                    p.quota++;
+            for (const paint of eligible) {
+                let best = buckets[0], score = embeddingCosineSimilarity(paint.vector, best.vector);
+                for (let i = 1; i < buckets.length; i++) {
+                    const candidate = buckets[i], next = embeddingCosineSimilarity(paint.vector, candidate.vector);
+                    if (next > score) {
+                        best = candidate;
+                        score = next;
+                    }
+                }
+                best.paints.push({ id: paint.variantId, score });
+            }
+            const groups = buckets
+                .sort((a, b) => b.proportion - a.proportion || a.position - b.position)
+                .map((p) => {
+                const ids = p.paints
+                    .sort((a, b) => b.score - a.score || identityOrder(a.id, b.id))
+                    .slice(0, p.quota)
+                    .map((paint) => paint.id);
+                return {
+                    hex: p.hex,
+                    proportion: p.proportion,
+                    quota: p.quota,
+                    ids,
+                    shortfall: p.quota - ids.length,
+                };
+            });
+            const ids = groups.flatMap((p) => p.ids);
+            return {
+                ids,
+                groups,
+                limited: eligible.length > ids.length,
+                eligibleCount: eligible.length,
+                counts,
+                sourceVersion: cache.sourceVersion,
+                dictionaryVersion: cache.dictionaryVersion,
+                embeddingVersion: cache.embeddingVersion,
+                rankingVersion: cache.rankingVersion,
+                countBasis: "complete-catalogue",
+            };
+        },
+    };
+}

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-card-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module sdk/search-card-types
+ * @description The `view:"card"` search projection — the lean grid item and the
+ * envelope that carries it.
+ *
+ * Split out of `types.ts` — which is over the repository's source-size limit —
+ * along the same seam `match-types.ts` took: one view of one surface, and
+ * nothing else. The full-view item and the shared envelope stay in `types.ts`,
+ * which this module reads `SearchResponse` from.
+ */
+import type { ProductId, VariantId } from "./identifiers.js";
+import type { OpenEnum, SearchResponse } from "./types.js";
+/**
+ * The lean `view:"card"` result item — identity + name + 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
+ * `variantId` at `view: "full"` or via `material()` before claiming anything the
+ * card does not carry.
+ */
+export interface SearchCardItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    productId: ProductId | null;
+    brandSlug: string | null;
+    brand: string;
+    /** Product name (the full item's `product`). */
+    name: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    projectSaveCapability?: "allowed";
+    sourceStatus?: "provisional";
+    score: number;
+    /**
+     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
+     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
+     *
+     * Three states, all different, and reading them as two is the mistake this
+     * shape exists to prevent: no `attributes` key means you did not ask; a key
+     * whose value is `null` means this material carries no accepted value for that
+     * attribute; anything else is what the graph holds. Values resolve with the
+     * normal variant-over-product precedence, and an array is a multi-valued
+     * attribute rather than a list of candidates.
+     */
+    attributes?: Record<string, string | string[] | null>;
+}
+/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
+export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
+    view: OpenEnum<"card">;
+    results: SearchCardItem[];
+}

package/search-card-types.js

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

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,102 @@
+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;
+    /**
+     * MG-1686, MG-1783. True when the candidate read hit the bounded pool ceiling,
+     * so more materials match the signature than were ranked. A cut pool is an
+     * even SAMPLE across the id keyspace rather than its lowest window, so the
+     * ranked set is representative of the match set without being all of it —
+     * treat the items as the best of a sample, never as the best that exist. A cut
+     * pool that produced NO items answers `inconclusive` instead, so `available`
+     * with an empty `items` always means a complete search that found nothing.
+     */
+    poolTruncated: boolean;
+    supersededBy: MaterialSuccessor | null;
+    nextCursor?: string;
+}
+/**
+ * MG-1686. The search read a bounded window of the matches and nothing in it
+ * reached the page, while more matches existed past the window. It is not an
+ * answer of "nothing can replace this" — that answer is `available` with an
+ * empty `items`. `reason` names what happened and the next move; follow
+ * `nextCursor` when it is present.
+ */
+export interface InconclusiveSubstitutesResponse {
+    status: "inconclusive";
+    signatureUsed: AvailableSubstituteSignature;
+    items: [];
+    candidatePoolSize: number;
+    droppedUnavailable: number;
+    reason: string;
+    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 | InconclusiveSubstitutesResponse | 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 {};