@instruments/materialgraph 0.32.0 → 0.35.0

package/colours-client.d.ts

@@ -1,70 +0,0 @@
-import type { QueryParams } from "./http-transport.js";
-import type { SdkOperationId } from "./operations.js";
-/**
- * The colour surface, namespaced as `mg.colours` — MULTI-COLOUR search
- * (`palette`).
- *
- * A namespace rather than a flat method on an already-large client facade:
- * "what goes with these colours" (`palette`). `mg.codes` set the precedent for
- * a namespace when a capability is a family rather than a single verb.
- *
- * The namespace holds no transport of its own: the client hands it a bound
- * `get`/`post`, so auth, rate-limit accounting and error shaping stay in one
- * place.
- *
- * `palette`'s response is live and uncached.
- *
- * ROUTING OUT OF THIS NAMESPACE. Colour is a lens, and this is not the only
- * door into it:
- * - ONE colour → `mg.byColour({ hex })`. This namespace's `palette` is for N
- *   colours at stated proportions, which is a different ranking, not a
- *   convenience wrapper.
- * - A colour NAME rather than a hex → `mg.resolveColour(name)` first.
- * - Colour WORDS (families, moods, undertones) → `mg.colourFacets()`.
- * - Walking the corpus by lightness/vividness → `mg.listVariants({ orderBy })`.
- * - Colour as one signal among words and a seed → `mg.search(...)`.
- *
- * And the honesty rule the whole lens rests on: every colour here is DERIVED
- * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
- * likeness, never a stated colour specification.
- */
-import type { SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
-/** The client's own request primitives, handed down so this file owns no transport. */
-export type ColoursTransport = {
-    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
-    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
-};
-export declare class ColoursClient {
-    #private;
-    constructor(transport: ColoursTransport);
-    /**
-     * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
-     * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).
-     *
-     * Use `mg.byColour()` for a single colour.
-     *
-     * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
-     * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
-     * swatch SHARE sits near the `proportion` you asked for. So the same colours
-     * at different proportions come back in a different order — a colour at 60%
-     * of the surface is a different query from one at 5%. `logic: "all"` (the
-     * default) applies a per-colour eligibility floor and returns the weighted
-     * geometric mean, so a candidate missing one colour is rejected rather than
-     * merely ranked low; `logic: "any"` is a noisy-OR that accepts partial
-     * answers but saturates once several colours score well, so prefer `all`
-     * when the ORDER is what matters.
-     *
-     * Every match carries the candidate's full `palette` plus a per-colour
-     * receipt naming the swatch that answered each queried colour.
-     *
-     * @example
-     * const { matches } = await mg.colours.palette({
-     *   colours: [
-     *     { hex: "F5EFE0", proportion: 0.6 },
-     *     { hex: "9CAF88", proportion: 0.2 },
-     *     { hex: "3E3B36", proportion: 0.2 },
-     *   ],
-     * });
-     */
-    palette(input: SearchPaletteInput, signal?: AbortSignal): Promise<SearchPaletteResponse>;
-}

package/colours-client.js

@@ -1,38 +0,0 @@
-export class ColoursClient {
-    #transport;
-    constructor(transport) {
-        this.#transport = transport;
-    }
-    /**
-     * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
-     * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).
-     *
-     * Use `mg.byColour()` for a single colour.
-     *
-     * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
-     * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
-     * swatch SHARE sits near the `proportion` you asked for. So the same colours
-     * at different proportions come back in a different order — a colour at 60%
-     * of the surface is a different query from one at 5%. `logic: "all"` (the
-     * default) applies a per-colour eligibility floor and returns the weighted
-     * geometric mean, so a candidate missing one colour is rejected rather than
-     * merely ranked low; `logic: "any"` is a noisy-OR that accepts partial
-     * answers but saturates once several colours score well, so prefer `all`
-     * when the ORDER is what matters.
-     *
-     * Every match carries the candidate's full `palette` plus a per-colour
-     * receipt naming the swatch that answered each queried colour.
-     *
-     * @example
-     * const { matches } = await mg.colours.palette({
-     *   colours: [
-     *     { hex: "F5EFE0", proportion: 0.6 },
-     *     { hex: "9CAF88", proportion: 0.2 },
-     *     { hex: "3E3B36", proportion: 0.2 },
-     *   ],
-     * });
-     */
-    async palette(input, signal) {
-        return await this.#transport.post("search_by_palette", input, signal);
-    }
-}

package/material-query-plan-types.d.ts

@@ -1,70 +0,0 @@
-/** Hand-mirrored wire types for `POST /api/v1/search/plan`. */
-import type { OpenEnum } from "./types.js";
-/** One wanted value: hard filters the page, soft only orders it. */
-export type MaterialQueryWant = {
-    attributeId: string;
-    terms: string[];
-    phrase: string;
-    strength: OpenEnum<"hard" | "soft">;
-    fill: number;
-};
-export type MaterialQueryExclusion = {
-    attributeId: string;
-    term: string;
-    phrase: string;
-};
-/** The dictionary reading of one query, as the index search runs it. */
-export type MaterialQueryReading = {
-    normalised: string;
-    category: {
-        productTypeIds: string[];
-        label: string;
-        phrase: string;
-    } | null;
-    brands: {
-        ids: string[];
-        names: string[];
-        phrase: string;
-    } | null;
-    wants: MaterialQueryWant[];
-    excludes: MaterialQueryExclusion[];
-    excludeBrands: string[];
-    colour: {
-        phrase: string;
-        familyId: string;
-        hex: string;
-        oklab: [number, number, number];
-        family12: string[];
-    } | null;
-    vendorColourNames: string[];
-    leftover: string[];
-    softAlone: boolean;
-};
-/** Present when a word no material carries was corrected: showing results for `to`. */
-export type MaterialQueryCorrection = {
-    from: string;
-    to: string;
-    words: {
-        word: string;
-        correction: string;
-    }[];
-};
-/** One search over the index. */
-export type MaterialSearchRequest = {
-    text: string;
-    view?: OpenEnum<"card" | "full">;
-    limit?: number;
-    cursor?: string;
-};
-export type MaterialQueryPlan = {
-    version: OpenEnum<"2">;
-    rawQuery: string;
-    normalisedQuery: string;
-    readingVersion: string;
-    source: OpenEnum<"dictionary" | "jev">;
-    cached: boolean;
-    plan: MaterialQueryReading;
-    correction: MaterialQueryCorrection | null;
-    /** The one search to run, in the phrasing that was read. */
-    requests: MaterialSearchRequest[];
-};

package/palette-search-types.d.ts

@@ -1,171 +0,0 @@
-import type { ColourCategoryGate } from "./by-colour-types.js";
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
-/**
- * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes`.
- *
- * Kept out of `types.ts` for the repository's source-file size budget. Same
- * tolerant-parsing contract as the rest of the mirror — response enums are
- * widened so a new server value still type-checks.
- *
- * The MATCH SEMANTICS these types carry are the server's, stated on
- * {@link SearchPaletteInput.logic} rather than left to the endpoint docs.
- */
-import type { VariantId } from "./identifiers.js";
-import type { OklabTriple, OpenEnum } from "./types.js";
-/** How the per-colour scores are combined across a palette. */
-export type PaletteLogic = OpenEnum<"all" | "any">;
-/** One queried palette colour — exactly one of `hex` or `oklab`. */
-export type PaletteQueryColour = {
-    hex?: string;
-    oklab?: OklabTriple;
-    /**
-     * Share of the surface this colour should occupy, in (0,1]. A colour stated
-     * below 5% is dropped; otherwise not applied, since a palette is ordered by
-     * its first colour alone.
-     */
-    proportion?: number;
-    /** Relative importance. Not applied: a palette is ordered by its first colour. */
-    weight?: number;
-};
-export type SearchPaletteInput = {
-    /**
-     * HARD category filter: category-group or product-type names or keys.
-     * Absent, the page holds surface materials only, so lights, taps and
-     * furniture are left out.
-     */
-    category?: string[];
-    corpusScope?: CorpusScope;
-    /**
-     * The palette to match, 1–8 colours. The page is ordered by the FIRST colour;
-     * the rest come back in `query.droppedColours`.
-     */
-    colours: PaletteQueryColour[];
-    /**
-     * Kept so existing callers still parse: the one search orders the page by
-     * the first colour with no eligibility floor, so `all` and `any` return the
-     * same page.
-     */
-    logic?: PaletteLogic;
-    /** Results to return; defaults to 24, capped at 48. */
-    limit?: number;
-};
-/**
- * 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 type CandidateSwatch = {
-    hex: string;
-    proportion: number;
-    name: string | null;
-};
-/** Why a queried colour (or gradient sample) scored what it scored. */
-export type ColourMatchReceipt = {
-    queryHex: string;
-    /** `colourScore × proportionScore`, so `colourScore` on the one search. */
-    score: number;
-    /**
-     * Closeness in [0,1] of the matched swatch to the queried colour, from plain
-     * OKLab distance with lightness counted in full. Not a confidence.
-     */
-    colourScore: number;
-    /** Proportion agreement; always 1, since no proportion is applied. */
-    proportionScore: number;
-    /** The swatch that produced the score, or null when nothing matched. */
-    matched: CandidateSwatch | null;
-    /**
-     * Whether `matched` has a hue compatible with the queried colour, at the
-     * response's `hueGate` thresholds. A flag, never a gate: an incompatible
-     * swatch still scores and ranks. Absent when there is no `matched` swatch.
-     */
-    hueCompatible?: boolean;
-};
-/** Identity and evidence shared by both multi-colour match shapes. */
-export type MultiColourMatchBase = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    brandSlug: string | null;
-    productId: string | null;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    /**
-     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest.
-     * ABSENT means no hash is on record, never that there is no image.
-     */
-    imageSha256?: string;
-    /** MB has retired or hidden this SKU. */
-    retired: boolean;
-    /**
-     * The catalog GROUP — "Flooring", "Textile Materials", "Coatings" — or null
-     * when the material has no accepted primary product type.
-     *
-     * A palette query is cross-category BY INTENT: a designer building a scheme,
-     * not browsing one aisle. So this is the field that says whether a result
-     * answers the question — one real palette returned 30 of 40 results in a
-     * single category while every one of the fourteen groups held something
-     * closer on the same colours (MG-1245). Group by it, and keep null as its own
-     * bucket: null means UNKNOWN, not uncategorised, and it is not rare.
-     */
-    category: string | null;
-    /** The candidate's full extracted palette — the evidence scored against. */
-    palette: CandidateSwatch[];
-    /**
-     * Closeness in [0,1] of the material's own colour to the searched colour,
-     * the page's order. Not a confidence or a percentage.
-     */
-    score: number;
-};
-export type PaletteMatch = {
-    /** One receipt per queried colour, in query order. */
-    colours: ColourMatchReceipt[];
-} & MultiColourMatchBase;
-/**
- * The thresholds behind every receipt's `hueCompatible`: the exact values
- * passed to colorscope's `isHueCompatible`, fixed server-side with no request
- * knob. A FLAG, never admission or ranking: every swatch still scores, and the
- * page and its order are the same with or without it.
- */
-export type HueGateReceipt = {
-    /** Below this query chroma the colour is achromatic and any hue is admitted. */
-    achromaticQueryChroma: number;
-    /** A swatch must carry at least this share of the query colour's chroma. */
-    minChromaRatio: number;
-    /** Floor on the cosine agreement between the two hue vectors. */
-    minHueCosine: number;
-};
-/**
- * A PAGE, NOT A CORPUS. `count` is `matches.length` under `limit` (24 default,
- * 48 max) — this surface states no corpus total and has no cursor, so "N
- * materials match this palette" is not a claim you can make from it.
- */
-export type 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: {
-            hex: string;
-            proportion?: number;
-            weight?: number;
-        }[];
-        /** Colours not searched because their stated share was below 5%. */
-        droppedColours: {
-            hex: string;
-            proportion?: number;
-            weight?: number;
-        }[];
-        logic: PaletteLogic;
-        /** `no_effective_colours` means no material query ran. */
-        outcome: OpenEnum<"matches" | "no_effective_colours">;
-    };
-    /** The category gate the page ran under. */
-    categoryGate?: ColourCategoryGate;
-    /** The thresholds behind each receipt's `hueCompatible`. Absent only on responses stored before it existed. */
-    hueGate?: HueGateReceipt;
-    /** `matches.length`, capped by `limit`. Never a corpus total. */
-    count: number;
-    matches: PaletteMatch[];
-};

package/palette-search-types.js

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

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