@instruments/materialgraph 0.33.0 → 0.36.0

package/query-understanding-types.d.ts

@@ -1,254 +0,0 @@
-import type { MatchTarget } from "@instruments/colorscope/match";
-import type { ColorResolution } from "@instruments/colorscope/naming";
-import type { SearchFilter } from "./search-refinement-types.js";
-import type { OpenEnum } from "./types.js";
-export type QuerySenseKind = OpenEnum<"brand" | "product" | "paint_identity" | "category" | "material" | "colour" | "attribute" | "attribute_value" | "certification">;
-export type QuerySense = {
-    id: string;
-    kind: QuerySenseKind;
-    label: string;
-    outcome: OpenEnum<"applied" | "ambiguous" | "recognized" | "refused">;
-    effect: OpenEnum<"restrict" | "prioritize" | "rerank" | "offer" | "none">;
-    confidence: number;
-    evidence: {
-        source: string;
-        matchedText: string;
-        span?: {
-            start: number;
-            end: number;
-        };
-    };
-    entity?: {
-        brandSlug?: string;
-        productId?: string;
-        variantId?: string;
-        materialBankId?: string;
-        productTypeId?: string;
-        paintCode?: string;
-        hex?: string;
-    };
-    reason?: string;
-};
-export type CanonicalLexicalAuthorityReceipt = {
-    authority: OpenEnum<"taxonomy" | "colorscope">;
-    version: string;
-    revision: string;
-    digest?: string;
-};
-export type CanonicalLexicalReading = {
-    matchTarget?: MatchTarget;
-    colorResolution?: ColorResolution;
-    authority: OpenEnum<"taxonomy" | "colorscope">;
-    identity: string;
-    outcome: OpenEnum<"equivalent" | "ambiguous" | "declined">;
-    executionStatus: OpenEnum<"applied" | "suppressed" | "executable" | "recognized-but-unexecutable" | "declined">;
-    role: OpenEnum<"primary" | "secondary"> | null;
-    kind?: OpenEnum<"domain" | "core-colour" | "paint">;
-    label?: string;
-    libraryId?: string;
-    code?: string;
-    aliasCount?: number;
-    matchForm?: OpenEnum<"name" | "code" | "authoritative-term">;
-    collisionCount?: number;
-    familyId?: string;
-    hex?: string;
-    level?: OpenEnum<"family" | "tone-band" | "branch" | "concept">;
-    lifecycle?: {
-        introducedAt: string;
-        reviewedAt?: string;
-        status: string;
-    };
-    provenance?: {
-        basis: string;
-        snapshot?: string;
-        source: string;
-    };
-};
-export type CanonicalLexicalMatch = {
-    original: string;
-    canonical: string;
-    rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
-    span: {
-        start: number;
-        end: number;
-    };
-    coverage: number;
-    readings: CanonicalLexicalReading[];
-    receipt: {
-        original: string;
-        canonical: string;
-        rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
-        authorities: CanonicalLexicalAuthorityReceipt[];
-    };
-};
-export type CanonicalLexicalReceipt = {
-    original: string;
-    outcome: OpenEnum<"resolved" | "ambiguous" | "declined" | "partial" | "unresolved">;
-    matches: CanonicalLexicalMatch[];
-    unresolved: CanonicalLexicalMatch[];
-};
-export type QueryResidualReceipt = {
-    kind: OpenEnum<"compound" | "descriptive" | "ambiguous" | "empty">;
-    tokens: string[];
-    resolvedTokens: string[];
-    unresolvedTokens: string[];
-    resolvedRatio: number;
-    comparisonFrame: boolean;
-};
-/** Deterministic criteria compiled from the query before retrieval. */
-export type QueryCriteriaReceipt = {
-    applied: {
-        criterion: SearchFilter;
-        lane: OpenEnum<"filter" | "preference">;
-        lexicalSignal?: {
-            attributeId: string;
-            canonical: string;
-            identity: string;
-            original: string;
-            relation: OpenEnum<"equivalent" | "broader-storage-term">;
-            span: {
-                start: number;
-                end: number;
-            };
-            storedTerm: string;
-        };
-        source: OpenEnum<"compiled" | "taxonomy-adapter">;
-        span: string;
-    }[];
-    conflicts: {
-        attributeId: string;
-        caller: SearchFilter;
-        compiled: SearchFilter;
-        reason: string;
-    }[];
-    exclusions: {
-        criterion: SearchFilter;
-        execution: OpenEnum<"blocked-positive-only-contract">;
-        lane: OpenEnum<"hard" | "soft">;
-        missingValuePolicy: OpenEnum<"retain-unknown">;
-        span: string;
-    }[];
-    preferences: SearchFilter[];
-    residualText: string | null;
-    unresolved: {
-        code: OpenEnum<"missing-searchable-attribute" | "missing-dimension-pair-contract" | "missing-explicit-comparator" | "negative-criterion-contract-blocked" | "registry-contract-drift" | "unsupported-numeric-format" | "unsupported-unit" | "unsupported-strict-comparator">;
-        reason: string;
-        span: string;
-    }[];
-};
-/** How the query named or inferred a product type before retrieval. */
-export type QueryProductTypeReceipt = {
-    kind: OpenEnum<"leaf" | "group" | "vector" | "ambiguous" | "none">;
-    gate: OpenEnum<"hard" | "constrain" | "none">;
-    pass: OpenEnum<"taxonomy" | "synonym" | "display-name" | "group" | "head-noun" | "vector" | "none">;
-    reason: string;
-    displayName: string | null;
-    productTypeId: string | null;
-    groupKey: string | null;
-    productTypeIds: string[];
-    similarity: number | null;
-    margin: number | null;
-    residualText: string;
-    vectorPassRan: boolean;
-    registryVersion: string;
-    durationMs: number;
-    candidates: {
-        productTypeId: string;
-        displayName: string;
-        similarity: number;
-    }[];
-};
-/** The selected retrieval arm; null when the path is browse or criteria-only. */
-export type 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">;
-    productTypeIds: string[];
-    residual: QueryResidualReceipt;
-    registryVersion: string;
-};
-export type QueryAmbiguityReceipt = {
-    outcome: OpenEnum<"applied" | "abstained" | "refused" | "timeout">;
-    modelId: string | null;
-    providerRan: boolean;
-    durationMs: number;
-    timeoutMs: number;
-    validation: OpenEnum<"valid" | "invalid" | "not-run">;
-    refusalCode: string | null;
-    confidence: number | null;
-    routing: OpenEnum<"compound" | "descriptive"> | null;
-    productTypeIds: string[];
-    changedArm: boolean;
-};
-export type QueryCategoryScopeReceipt = {
-    source: OpenEnum<"caller" | "anchor">;
-    mechanism: OpenEnum<"sql-predicate" | "provider-filter" | "allowlist" | "prune">;
-    variantCount: number | null;
-    ceiling: number;
-    specScanBounded?: boolean;
-    [key: string]: unknown;
-};
-export type QuerySpecAllowlistReceipt = {
-    limit: number;
-    returned: number;
-    retrieved?: number;
-    truncated: boolean;
-    emptyMeansScarcity: boolean;
-    outcome?: OpenEnum<"corpus-scarcity" | "retrieval-miss" | "unknown">;
-};
-/**
- * Whether the phrase-reading step turned the query's descriptive words into
- * filters and preferences. Present only on the workflow lane.
- */
-export type QueryPhraseReadingReceipt = {
-    outcome: OpenEnum<"skipped">;
-    reason: string;
-} | {
-    outcome: OpenEnum<"read">;
-    /** Which model read the phrase: `jev`, or `second` behind it. */
-    reader: OpenEnum<"jev" | "second">;
-    elapsedMs: number;
-    leftAsText: string[];
-    rows: {
-        kind: OpenEnum<"want" | "avoid">;
-        attributeId: string;
-        values: string[];
-        confidence: number;
-        applied: boolean;
-    }[];
-};
-export type QueryUnsatisfiableNarrowing = {
-    narrowing: OpenEnum<"product-type">;
-    gate: OpenEnum<"hard">;
-    productTypeId: string;
-    displayName: string;
-    productTypeIds: string[];
-    pass: string;
-    evidence: OpenEnum<"zero-accepted-variants">;
-    relaxedDisplayName?: string;
-    relaxedProductTypeId?: string;
-    relaxedProductTypeIds?: string[];
-    relaxedTo: OpenEnum<"head-noun" | "none">;
-};
-/** Inspectable interpretation of the raw query by ordinary MaterialGraph search. */
-export type QueryUnderstanding = {
-    version: OpenEnum<"1">;
-    rawQuery: string;
-    normalisedQuery: string;
-    residualText: string;
-    status: OpenEnum<"resolved" | "ambiguous" | "partial" | "unresolved">;
-    mode: OpenEnum<"image" | "colour" | "text" | "lexical" | "entity-browse" | "attribute">;
-    senses: QuerySense[];
-    canonicalLexical?: CanonicalLexicalReceipt;
-    criteria?: QueryCriteriaReceipt;
-    productType?: QueryProductTypeReceipt;
-    arm?: QueryArmReceipt;
-    ambiguity?: QueryAmbiguityReceipt;
-    categoryScope?: QueryCategoryScopeReceipt;
-    specAllowlist?: QuerySpecAllowlistReceipt;
-    unsatisfiableNarrowing?: QueryUnsatisfiableNarrowing;
-    phraseReading?: QueryPhraseReadingReceipt;
-};

package/query-understanding-types.js

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

package/resolve-colour-types.js

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

package/search-card-types.d.ts

@@ -1,86 +0,0 @@
-/**
- * @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, SearchData, SearchResponse } from "./types.js";
-/**
- * The lean `view:"card"` result item — identity + name + code + 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 `getVariant()` before claiming anything the
- * card does not carry.
- */
-export type 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;
-    /**
-     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest. Key a
-     * cache or dedupe on it rather than the URL. ABSENT means no hash is on
-     * record, never that there is no image.
-     */
-    imageSha256?: string;
-    /**
-     * How many eligible variants the row's product has, the same set
-     * `listVariants` pages, so a follow-up list returns this many: the card's
-     * "12 colourways". ABSENT means the product is unknown or has no eligible
-     * variant.
-     */
-    variantCount?: number;
-    /**
-     * The manufacturer's own item code, the same key the full item carries.
-     * Reach for it when two cards read alike: `name` is the PRODUCT name, and a
-     * paint product is a whole collection, so brand, product name and variant
-     * name together are shared by most of the catalogue. ABSENT means no code is
-     * recorded, never that the variant cannot be ordered.
-     */
-    manufacturerCode?: string;
-    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 type SearchCardResponse = {
-    data: Omit<SearchData, "view" | "results"> & {
-        view: OpenEnum<"card">;
-        results: SearchCardItem[];
-    };
-} & Omit<SearchResponse, "data">;
-/**
- * The request forms the server answers with {@link SearchCardResponse}:
- * `view: "card"`, or `intent: "typeahead"`, which forces the card view.
- */
-export type CardProjectionRequest = {
-    view: "card";
-} | {
-    intent: "typeahead";
-};

package/search-card-types.js

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

package/search-index-plan-types.d.ts

@@ -1,74 +0,0 @@
-/**
- * @module search-index-plan-types
- * @description The plan the one search ran on, as `/search` reports it under
- * `explain.plan` (ADR 0031). Mirrors `searchIndexPlanReceiptSchema` in
- * `@materialgraph/products/search-index/plan-schema`; `key-parity.test.ts`
- * holds the two to the same fields.
- */
-import type { ColourRegionRange } from "./colour-region-types.js";
-import type { CorpusScope } from "./corpus-scope-types.js";
-/** One attribute the plan wants: its terms, or any value when `presence`. */
-type SearchIndexPlanWant = {
-    attributeId: string;
-    /** Share of the category's materials stating the attribute, 0 to 1. */
-    fill: number;
-    /** The words it was read from, or `"(filter)"` for a caller's filter. */
-    phrase: string;
-    /** Any stated value satisfies it; `terms` is then empty. */
-    presence?: true;
-    /** A hard want removes rows; a soft one only counts toward the order. */
-    strength: "hard" | "soft";
-    terms: string[];
-};
-/**
- * The query's plan: the category, brands, wanted and excluded attribute terms,
- * the colour, the words left for text, and the caller's corpus scope.
- */
-export type SearchIndexPlan = {
-    brands: {
-        ids: string[];
-        names: string[];
-        phrase: string;
-    } | null;
-    category: {
-        label: string;
-        phrase: string;
-        productTypeIds: string[];
-    } | null;
-    colour: {
-        family12: string[];
-        familyId: string;
-        hex: string;
-        oklab: [number, number, number];
-        phrase: string;
-        /** The colour's region, when the plan holds one rather than a point. */
-        range?: ColourRegionRange;
-    } | null;
-    /** Present only when the caller sent a scope narrower than the whole graph. */
-    corpusScope?: Exclude<CorpusScope, "all">;
-    excludeBrands: string[];
-    excludes: {
-        attributeId: string;
-        phrase: string;
-        term: string;
-    }[];
-    /** Words the reading did not place, left for the text match. */
-    leftover: string[];
-    normalised: string;
-    softAlone: boolean;
-    vendorColourNames: string[];
-    wants: SearchIndexPlanWant[];
-};
-/**
- * Which reading a search ran on (`version`, `source`), whether it came from
- * the cache, the plan itself, and its signature, so two runs of one request
- * can be compared plan for plan.
- */
-export type SearchPlanReceipt = {
-    cached: boolean;
-    plan: SearchIndexPlan;
-    signature: string;
-    source: "dictionary" | "jev";
-    version: string;
-};
-export {};

package/search-index-plan-types.js

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

package/search-refinement-types.d.ts

@@ -1,103 +0,0 @@
-/** The spec-filter vocabulary MaterialGraph's filter and preference inputs share. */
-/**
- * A hard canonical-attribute filter accepted by the search engine — a term match
- * (`{ attributeId, term }`), a presence check (`{ attributeId, hasValue: true }`)
- * or a NUMERIC RANGE (`{ attributeId, min, max }`, bounds inclusive, at least one
- * stated). Applied as a restriction BEFORE ranking.
- *
- * The `attributeId` may be a real registry id (`"fire_classifications"`,
- * `"environmental_product_declaration"`) OR the virtual
- * `"certification_programme"` (see `CERTIFICATION_PROGRAMME_ATTRIBUTE_ID`),
- * which matches a programme — GREENGUARD, FloorScore, LEED, an EPD — wherever it
- * landed across the four certification buckets. Presence (`hasValue`) is NOT
- * supported for the virtual programme attribute. The typed `spec-types` mirror
- * and the `specifications` builders produce values assignable to this type.
- */
-/**
- * Optional per-filter TRUST bar the matching value must clear.
- *
- * Raising the bar shrinks the result set for a reason worth stating: the
- * materials it removes are not materials that fail the spec, they are materials
- * whose claim is weaker than you demanded. That distinction is the whole point
- * of this object — without it, "no GREENGUARD results" reads as "nobody is
- * certified" when it means "nobody is certified TO THIS EVIDENTIAL STANDARD".
- */
-export type SearchFilterTrust = {
-    /** Confidence floor, 0–1. A value below it is excluded, not marked failed. */
-    minConfidence?: number;
-    /**
-     * Demand an EXACT source basis (closed enum — an unknown basis is rejected).
-     * Strongest to weakest as evidence:
-     *  - `declared` — the manufacturer stated it. Attributable, not independent.
-     *  - `catalog_feed` — it arrived in a catalog feed. Trusted at ingest, unreviewed.
-     *  - `derived` — MaterialGraph inferred it. Ours, not the manufacturer's — never
-     *    present a `derived` value as something the brand claims.
-     *
-     * There is NO `tested` basis. This docblock advertised one as "the strongest
-     * claim available" through 0.12.0, and the union listed `declared` twice in
-     * its place — so a caller reading the documentation would write a value the
-     * server rejects with a 400, and the type would not stop them because the
-     * fourth arm was a duplicate rather than the value described.
-     * `packages/schema/src/source-basis.test.ts` asserts `tested` parses false;
-     * its absence is deliberate, not an omission.
-     */
-    sourceBasis?: "catalog_feed" | "declared" | "derived";
-    /** Fold the attribute's own registry confidence requirement in, server-side. */
-    meetsRequirement?: true;
-};
-/**
- * One HARD criterion. Applied as a restriction BEFORE ranking, so a filtered
- * search's empty result means "nothing on record satisfies this", never "nothing
- * exists" — the corpus's silence and the world's are different things. Use
- * `preferences` instead when a miss should demote rather than remove.
- */
-export type SearchFilter = {
-    attributeId: string;
-    term: string;
-    trust?: SearchFilterTrust;
-} | {
-    attributeId: string;
-    excludesTerm: string;
-    trust?: SearchFilterTrust;
-    /**
-     * What an UNKNOWN effective value does. Absent or `"drop"` (default)
-     * requires a known effective value — a variant that never states the
-     * attribute does not pass. `"pass"` admits it — a variant only fails by
-     * STATING the excluded term.
-     */
-    whenUnstated?: "drop" | "pass";
-}
-/**
- * TERM SET — the attribute must equal any ONE of these. OR within the entry;
- * AND still holds between entries, so a filter rail composes the same way
- * whatever it is filtering on.
- *
- * The server has accepted this since the term-set arm shipped, and a consumer
- * has been sending it successfully on the wire — but it was missing from this
- * union through 0.12.0, so multi-value filtering type-checked nowhere while
- * working everywhere. Brand multi-select is the common case:
- * `{attributeId: "brand", terms: ["kvadrat", "interface"]}`.
- */
- | {
-    attributeId: string;
-    terms: string[];
-    trust?: SearchFilterTrust;
-} | {
-    attributeId: string;
-    hasValue: true;
-    trust?: SearchFilterTrust;
-}
-/** Date-sensitive presence is currently executable only for EPD expiration. */
- | {
-    attributeId: "epd_expiration_date";
-    hasValue: true;
-    asOf: string;
-    trust?: SearchFilterTrust;
-} | {
-    attributeId: string;
-    /** Inclusive lower bound. Omit for a ceiling-only range. */
-    min?: number;
-    /** Inclusive upper bound. Omit for a floor-only range. */
-    max?: number;
-    trust?: SearchFilterTrust;
-};

package/search-refinement-types.js

@@ -1,2 +0,0 @@
-/** The spec-filter vocabulary MaterialGraph's filter and preference inputs share. */
-export {};