@instruments/materialgraph 0.25.0 → 0.27.0

package/schedule-references-client.js

@@ -1,26 +0,0 @@
-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,261 +0,0 @@
-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
- * rather than `types.ts`, which sits at its source-size baseline.
- *
- * A finish schedule is a completed compose scheme rendered as ONE ROW PER SLOT:
- * the shape a specifier issues. The contract that makes it trustworthy is that
- * every row carries the IDENTICAL, fixed column set, and every attribute cell
- * states its own verification alongside its value. An unknown is an explicit
- * `missing` cell with a null value — never a blank that reads as complete.
- *
- * ABSENT IS NOT FALSE, enforced structurally: because the column set is fixed,
- * "we do not know" has to be SAID rather than omitted. Read
- * {@link FinishScheduleCell.state} before printing `value`.
- *
- * MG-1351 added the schedule's organising principle: every row carries an
- * {@link FinishScheduleRow.code} L-code under a numbered section, rows arrive in
- * READING order, slots with nothing specified are served as
- * {@link FinishSchedule.openSlots}, and a row may carry or-equal
- * {@link FinishScheduleAlternate}s. Read `alternates` with
- * {@link FinishSchedule.alternatesResolved}: an empty list means either "we did
- * not ask" or "there is none", and those are different claims.
- */
-import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
-/** One schedule column: the attribute and its header text. */
-export interface FinishScheduleColumn {
-    attributeId: string;
-    /** The registry presentation label. */
-    label: string;
-}
-/**
- * The six verification states a schedule cell can report, mirroring the shared
- * verdict contract. On this public surface a `proposed` (pending-review) value
- * is projected to `missing`, so it can never be told apart from a value that
- * never existed.
- */
-export type FinishScheduleCellState = "matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated";
-/**
- * One attribute cell of one row: the value AND how far it can be trusted.
- *
- * Columns the Run's criteria evaluated carry the real verdict state. Columns
- * backfilled from the catalogue (nothing in the brief asked about them) only
- * ever read `matched` or `missing`: they assert presence-with-trust, not that
- * the brief was met.
- */
-export interface FinishScheduleCell {
-    attributeId: string;
-    label: string;
-    /** The display value, or null when unknown. */
-    value: string | null;
-    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.
- * `meets_all` is all-green on the required cells; `close` means something
- * deviated, went unverified or was missing — never round it up to a pass;
- * `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. */
-    code: number;
-    name: string;
-}
-/**
- * What MaterialGraph claims about an alternate — and never more than it can
- * support. None of the three means "interchangeable": accepting an alternate is
- * a specification decision, and this API does not make it.
- *
- * `or_equal` matched the specified material's equivalence signature with every
- * supporting value above its confidence floor. `or_equal_unverified` matched the
- * same signature on values that did not clear it. `successor` is the brand's own
- * declared replacement, from a reviewed relationship rather than a spec match —
- * its verdict cells are `not_evaluated` by construction.
- */
-export type FinishScheduleAlternateStance = "or_equal" | "or_equal_unverified" | "successor";
-/** One criterion of the equivalence signature an alternate was matched on. */
-export interface FinishScheduleAlternateCriterion {
-    role: "primary_material" | "performance";
-    attributeId: string;
-    term: string;
-}
-/**
- * Why an alternate is on the row. Every field is evidence, not adjective — a
- * substitute presented without its basis looks like a decision when it is a
- * lookup, so this is never absent from an alternate.
- */
-export interface FinishScheduleAlternateBasis {
-    /** The SPECIFIED variant this alternate was graded against. Opaque. */
-    specifiedVariantId: VariantId;
-    /** The product-type form the signature was projected in; null for a successor. */
-    form: string | null;
-    /** The criteria that matched. Empty for a successor: nothing was matched. */
-    signature: FinishScheduleAlternateCriterion[];
-    /** The seed-relative report card, projected exactly as row cells are. */
-    verdict: {
-        cells: FinishScheduleCell[];
-        grade: FinishScheduleGrade;
-        minConfidence: number | null;
-    };
-}
-/** One or-equal line sitting beneath the specified line it answers. */
-export interface FinishScheduleAlternate {
-    stance: FinishScheduleAlternateStance;
-    /** Opaque — round-trip verbatim into the material lenses. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    variant: string;
-    /**
-     * The colourway, when the catalogue names one. Carried separately because a
-     * substitute's `variant` is frequently the product name repeated, and a line
-     * that cannot name the colour has not named a material.
-     */
-    colour: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    recordUrl: string;
-    /**
-     * Further colourways of this same product that also cleared the signature and
-     * were collapsed into this line. A COUNTED collapse: `0` means this product
-     * offered exactly one match, never that the count is unknown.
-     */
-    otherColourways: number;
-    basis: FinishScheduleAlternateBasis;
-}
-/** A slot holding a code with nothing specified against it yet. */
-export interface FinishScheduleOpenSlot {
-    code: string;
-    sectionCode: number;
-    sectionName: string;
-    line: number;
-    slotId: SlotId;
-    slotName: string;
-    space: string | null;
-    /**
-     * Why this line is blank, in words — or `null` when nothing measured a reason.
-     *
-     * `null` is NOT "nothing was found". It means no diagnosis was recorded for
-     * this slot, most often because it was never searched, and it must not be
-     * rendered as a search that came back empty.
-     */
-    reason: string | null;
-}
-/** 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
-     * rather than its picks, so recomposing the scheme, varying it, or accepting a
-     * substitution renumbers nothing.
-     */
-    code: string;
-    /** The hundreds block this line sits in, e.g. `100`. */
-    sectionCode: number;
-    sectionName: string;
-    /** The 1-based line within its (space, section) group. */
-    line: number;
-    slotId: SlotId;
-    slotName: string;
-    /** The space NAME, or null for a spaceless slot. */
-    space: string | null;
-    element: string | null;
-    /** True when the designer pinned this pick rather than the engine choosing it. */
-    anchored: boolean;
-    brand: string;
-    product: string;
-    variant: string;
-    /** Opaque — round-trip verbatim into the material lenses. */
-    variantId: VariantId;
-    /** Relative path to the public material record (`/materials/{variantId}`). */
-    recordUrl: string;
-    imageUrl: string | null;
-    hex: string | null;
-    /** Always the full, identically-ordered column set. */
-    attributes: FinishScheduleCell[];
-    fitNotes: string[];
-    grade: FinishScheduleGrade;
-    /**
-     * Or-equal alternates for this line. An empty array is AMBIGUOUS on its own —
-     * read it with {@link FinishSchedule.alternatesResolved}.
-     */
-    alternates: FinishScheduleAlternate[];
-}
-/** A whole composed scheme as an issuable finish schedule. */
-export interface FinishSchedule {
-    runId: RunId;
-    schemeId: SchemeId;
-    title: string;
-    /** The compose contract version stamped on the Run, or `"unknown"`. */
-    composeVersion: string;
-    /** ISO timestamp the export was compiled at. */
-    generatedAt: string;
-    /** The stable column order every row's `attributes` array follows. */
-    columns: FinishScheduleColumn[];
-    /**
-     * The section table to group by, in schedule order. A section may carry no
-     * rows: three are reserved so their conventional numbers are held rather than
-     * reused, and any section can simply be unspecified in this scheme.
-     */
-    sections: FinishScheduleSection[];
-    /** In READING order — space, then section, then line. Not pick order. */
-    rows: FinishScheduleRow[];
-    /**
-     * Slots holding a code with nothing specified against them. Served explicitly
-     * because a schedule that omitted them would read as complete.
-     */
-    openSlots: FinishScheduleOpenSlot[];
-    /**
-     * Whether the or-equal lookup RAN. When false, no row's empty `alternates`
-     * may be read as "no alternate exists".
-     */
-    alternatesResolved: boolean;
-}
-/** `GET /api/v1/runs/{runId}/schedule`. */
-export interface FinishScheduleResponse {
-    schedule: FinishSchedule;
-}
-/** Options for {@link getRunSchedule}. */
-export interface GetRunScheduleOptions {
-    /** Which composed scheme to export; defaults to the Run's first scheme. Opaque. */
-    schemeId?: SchemeId;
-    signal?: AbortSignal;
-}

package/schedule-types.js

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

package/search-collapse-types.d.ts

@@ -1,69 +0,0 @@
-/**
- * The product-collapsed view of a search result — what `collapse: "product"`
- * hands back beside each card. Kept out of `types.ts` for the same reason
- * `palette-search-types.ts` and `by-colour-types.ts` are: that file is at its
- * source-size ceiling, and this is a self-contained corner of the contract.
- *
- * READ THIS FIRST, because the default is the opposite of what "duplicates"
- * intuition suggests. MaterialGraph search is VARIANT-based: without `collapse`,
- * every matching variant comes back as its own result, and that is correct —
- * twelve SKUs of one tile are twelve separately orderable products, not twelve
- * copies of one. Product grouping is an optional VIEW over that, not a fix for
- * it.
- *
- * When you do ask for the view, the product arrives CARRYING its variants
- * (`SearchResultItem.variants`) rather than a bare count, so a colourway strip
- * renders from the same response as the card. That array is CAPPED at 12, while
- * `SearchResultItem.siblingCount` stays the complete tally — so a truncated list
- * is decidable from the response alone: `(siblingCount ?? 0) + 1 >
- * variants.length`. A full-length array is never on its own evidence that the
- * product holds no further variants.
- */
-import type { VariantId } from "./identifiers.js";
-import type { SearchResultSignals } from "./types.js";
-/**
- * One variant of a product-collapsed result.
- *
- * A slim shape, deliberately: the fields a colourway strip renders, projected
- * from the row the engine already held in memory, so the array costs no extra
- * query. It is NOT a nested search result — no `attributes`, `palette`,
- * `verdict` or `productType` — because those come from per-result reads the
- * engine issues for the card only. Fetch the variant by `variantId` when you
- * need its full record.
- */
-export interface CollapsedVariant {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    /** The variant's own label; for paint, the colourway name. Null when unnamed. */
-    variantName: string | null;
-    /** The variant's coarse colour family. */
-    color: string | null;
-    /**
-     * `#rrggbb` dominant colour EXTRACTED FROM the variant's image — a visual
-     * likeness, never a manufacturer-declared colour specification. ABSENT means
-     * no palette is on record: unknown, never "this variant has no colour".
-     */
-    hex?: string;
-    imageUrl: string | null;
-    /**
-     * The variant's Material Bank SKU, on the same contract as the result item's:
-     * ABSENT means no MB identity is on record, never that it cannot be ordered.
-     */
-    materialBankId?: string;
-    /** This variant's own mode-primary score — the value the array is ordered by. */
-    score: number;
-}
-/**
- * One member of a collapsed result's `SearchResultItem.anatomy` — the
- * EXPLAIN-only readout of the same grouping {@link CollapsedVariant} publishes.
- * Where a collapsed variant is what a surface renders, this is what an operator
- * inspects: it carries the per-arm `signals` that made the variant a candidate.
- */
-export interface SearchAnatomyMember {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    variantName: string | null;
-    color: string | null;
-    score: number;
-    signals: SearchResultSignals;
-}

package/search-collapse-types.js

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

package/search-mood-types.d.ts

@@ -1,6 +0,0 @@
-/** 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

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

package/search-window-types.d.ts

@@ -1,25 +0,0 @@
-/** The bounded candidate window that produced a search page. */
-export interface SearchWindowReceipt {
-    /** Versioned budget profile; interpret the remaining fields under this version. */
-    profile: "interactive-r1" | (string & {});
-    /** Candidate depth used by the final retrieval. */
-    candidateTier: number;
-    /** Candidate retrieval count; `searchMaterials` reports exactly one selected retrieval. */
-    retrievalRounds: number;
-    /** Candidate-retrieval wall time only, in milliseconds. */
-    retrievalMs: number;
-    /** True when the serving source proved there were no more candidates. */
-    exhaustive: boolean;
-    /**
-     * Candidate attrition through the selected retrieval source. Absent when the
-     * response path did not perform ordinary retrieval (for example typeahead).
-     */
-    candidateCounts?: {
-        /** Provider-returned matches before bounded selection; null for SQL/exact arms. */
-        rawProviderMatches: number | null;
-        /** Matches selected from that provider response; null for SQL/exact arms. */
-        selectedMatches: number | null;
-        /** Canonical candidates returned by the selected retrieval arm. */
-        hydratedCanonicalCandidates: number;
-    };
-}

package/search-window-types.js

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