@instruments/materialgraph 0.5.0 → 0.6.1

package/schedule-types.d.ts

@@ -8,7 +8,12 @@
  * 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`.
  */
+import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
 /** One schedule column: the attribute and its header text. */
 export interface FinishScheduleColumn {
     attributeId: string;
@@ -39,11 +44,16 @@ export interface FinishScheduleCell {
     confidence: number | null;
     sourceBasis: string | null;
 }
-/** The rolled-up grade for one row, from its evaluated criterion cells only. */
+/**
+ * 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";
 /** One row: one slot, one specified material, fully graded. */
 export interface FinishScheduleRow {
-    slotId: string;
+    slotId: SlotId;
     slotName: string;
     /** The space NAME, or null for a spaceless slot. */
     space: string | null;
@@ -53,7 +63,8 @@ export interface FinishScheduleRow {
     brand: string;
     product: string;
     variant: string;
-    variantId: 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;
@@ -65,8 +76,8 @@ export interface FinishScheduleRow {
 }
 /** A whole composed scheme as an issuable finish schedule. */
 export interface FinishSchedule {
-    runId: string;
-    schemeId: string;
+    runId: RunId;
+    schemeId: SchemeId;
     title: string;
     /** The compose contract version stamped on the Run, or `"unknown"`. */
     composeVersion: string;
@@ -82,7 +93,7 @@ export interface FinishScheduleResponse {
 }
 /** Options for {@link getRunSchedule}. */
 export interface GetRunScheduleOptions {
-    /** Which composed scheme to export; defaults to the Run's first scheme. */
-    schemeId?: string;
+    /** Which composed scheme to export; defaults to the Run's first scheme. Opaque. */
+    schemeId?: SchemeId;
     signal?: AbortSignal;
 }

package/schedule-types.js

@@ -1,12 +1 @@
-/**
- * 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.
- */
 export {};

package/schema-resource-types.d.ts

@@ -1,4 +1,19 @@
+/**
+ * Wire types for the governed STATIC schema (`GET /api/v1/schema/*`).
+ *
+ * THE LENS: "what does the registry DEFINE?" — blocks, attributes, units, value
+ * dictionaries, product types and their external mappings. Definitions, not
+ * data: nothing here says how many materials carry an attribute or which values
+ * the corpus holds. For that, use `mg.specificationFacets()` and
+ * `mg.attributeValues()`; for one term explained in prose, `mg.glossary()`; for
+ * what one material has been determined on, `mg.materialBlocks()`.
+ *
+ * Every id here (`attributeId`, `blockId`, product-type keys) is canonical
+ * VOCABULARY, not an opaque token — this is where you discover it rather than
+ * invent it.
+ */
 import type { OpenEnum } from "./types.js";
+/** The nine governed static resources. */
 export type SchemaResource = "blocks" | "attributes" | "verticals" | "productTypes" | "units" | "valueDictionaries" | "sourceRequirements" | "productTypeTemplates" | "mappings";
 export type SchemaResourceRequest = SchemaResource;
 export interface SchemaLifecycle {

package/search-refinement-types.d.ts

@@ -14,16 +14,36 @@ import type { SearchInput } from "./types.js";
  * and the `specifications` builders produce values assignable to this type.
  */
 /**
- * Optional per-filter TRUST bar the matching value must clear. `minConfidence` is
- * an explicit confidence floor; `sourceBasis` demands an EXACT source basis (closed
- * enum — an unknown basis is rejected); `meetsRequirement` folds the attribute's
- * registry confidence requirement server-side.
+ * 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 interface 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).
+     * Roughly strongest to weakest as evidence:
+     *  - `tested` — a measured result. The strongest claim available.
+     *  - `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.
+     */
     sourceBasis?: "catalog_feed" | "declared" | "derived" | "tested";
+    /** 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;

package/spec-types.d.ts

@@ -11,12 +11,21 @@
  * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
  * of hand-assembling a magic `attribute:value` string.
  *
- * These criteria drive two operations equally:
- * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
- *   (colour / visual / lexical) search.
- * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ * These criteria drive two operations equally, and choosing between them IS the
+ * routing decision:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
+ *   (colour / visual / lexical) search. Reach for it when relevance still
+ *   matters: "something like this seed, but Class A".
+ * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
  *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`).
+ *   in `./specifications`). Reach for it when the spec is the whole question and
+ *   ranking would be noise.
+ *
+ * Discover the tokens before you spend them: `client.specificationFacets()` for
+ * what is facetable at all, `client.attributeValues()` for one attribute's
+ * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
+ * a phrase into a canonical pair. A hand-guessed token returns an honest empty
+ * answer, which is the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/spec-types.js

@@ -11,12 +11,21 @@
  * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
  * of hand-assembling a magic `attribute:value` string.
  *
- * These criteria drive two operations equally:
- * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
- *   (colour / visual / lexical) search.
- * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ * These criteria drive two operations equally, and choosing between them IS the
+ * routing decision:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
+ *   (colour / visual / lexical) search. Reach for it when relevance still
+ *   matters: "something like this seed, but Class A".
+ * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
  *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`).
+ *   in `./specifications`). Reach for it when the spec is the whole question and
+ *   ranking would be noise.
+ *
+ * Discover the tokens before you spend them: `client.specificationFacets()` for
+ * what is facetable at all, `client.attributeValues()` for one attribute's
+ * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
+ * a phrase into a canonical pair. A hand-guessed token returns an honest empty
+ * answer, which is the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/suggest-types.d.ts

@@ -6,6 +6,11 @@
  * Split out of `types.ts` for the repository's source-file size budget, the same
  * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
  * `types.ts`, so importers see no difference.
+ *
+ * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
+ * what answers a committed query; `mg.suggestColour()` covers colour names and
+ * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
+ * of the best matches, never a census of matching entities.
  */
 /** Which kind of entity a suggestion is — and therefore what `refId` means. */
 export type SuggestKind = "product" | "brand" | "category";
@@ -25,8 +30,12 @@ export interface Suggestion {
     brandSlug: string | null;
     brandName: string | null;
     categoryKey: string | null;
-    /** A representative variant, so a client can open a material record directly. */
+    /**
+     * A representative variant, so a client can open a material record directly.
+     * Opaque, and null when none was picked — not a product without variants.
+     */
     variantId: string | null;
+    /** Variants behind this entity IN MATERIALGRAPH — a coverage figure. */
     variantCount: number;
 }
 /** The suggest response: the query as interpreted, plus the ranked suggestions. */

package/suggest-types.js

@@ -6,6 +6,11 @@
  * Split out of `types.ts` for the repository's source-file size budget, the same
  * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
  * `types.ts`, so importers see no difference.
+ *
+ * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
+ * what answers a committed query; `mg.suggestColour()` covers colour names and
+ * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
+ * of the best matches, never a census of matching entities.
  */
 /**
  * Shape the query string for a suggest call.