@instruments/materialgraph 0.5.0 → 0.6.1

package/demand-types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Wire types for the SINGLE-SEED demand reads — `GET /api/v1/demand` and
+ * `POST /api/v1/pairings/coordinate`.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `material-types.ts` and `demand-batch-types.ts` sit beside it; both are
+ * re-exported from `types.ts`, so importers see no difference.
+ *
+ * THE LENS: demand answers "how much is this specified, and what travels with
+ * it?" from real order behaviour. It is not a search and not a recommendation
+ * engine — every number is bounded by the `trailing_36mo` window and by the
+ * {@link DemandSignal} it was read under, and a missing number means UNREAD, not
+ * zero.
+ */
+import type { ProductId, VariantId } from "./identifiers.js";
+import type { CompanionDemand, DemandMomentum, DemandQuarter, OpenEnum } from "./types.js";
+/** A resolved seed material (identity block shared by the demand reads). */
+export interface DemandSeed {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    brandSlug: string;
+    productId: ProductId;
+}
+/** Headline demand stats for a seed: counts, quarterly series, momentum. */
+export interface MaterialDemandStats {
+    specCount: number;
+    projectCount: number;
+    customerCount: number;
+    /** Sparse — a quarter with no activity is ABSENT, not a zero row. */
+    byQuarter: DemandQuarter[];
+    momentum: DemandMomentum;
+}
+/**
+ * `getMaterialDemand` result, passed through verbatim by the `/demand` route.
+ *
+ * `demand: null` means NO READING — the seed did not resolve, or nothing cleared
+ * the publication floor. It is never a reading of zero, and never licenses
+ * "nobody specifies this".
+ */
+export interface MaterialDemandResult {
+    found: boolean;
+    query: string;
+    seed: DemandSeed | null;
+    /** The only window v1 serves. Activity outside it is unread, not absent. */
+    window: "trailing_36mo";
+    demand: MaterialDemandStats | null;
+}
+/**
+ * `getCoSpecifiedMaterials` result, passed through verbatim. The `companions`
+ * list (materials specified alongside the seed) is included but left loosely
+ * typed — there is no captured fixture to pin its full shape.
+ *
+ * `resolution` is the honest report on the free-text seed: `ambiguous` means the
+ * phrase matched several materials and `seedAlternatives` holds them — pick one
+ * and re-ask by `variantId` rather than treating the first as the answer.
+ */
+export interface CoSpecifiedResult {
+    found: boolean;
+    resolution: OpenEnum<"resolved" | "ambiguous" | "not_found">;
+    query: string;
+    seed: DemandSeed | null;
+    seedCategory: string | null;
+    seedAlternatives: DemandSeed[];
+    companions?: unknown[];
+}
+/** The `/api/v1/demand` envelope — both domain reads side by side, verbatim. */
+export interface DemandResponse {
+    query: string;
+    demand: MaterialDemandResult;
+    cospec: CoSpecifiedResult;
+}
+/** Seed a demand read by EXACTLY ONE of `variantId` or `material`. */
+export interface DemandParams {
+    /** An exact variant id. Opaque — pass through verbatim. */
+    variantId?: VariantId;
+    /** Free text ("Brand Product Colour"), resolved server-side. May be ambiguous. */
+    material?: string;
+}
+export interface CoordinateSeed extends DemandSeed {
+    /** The input reference this seed resolved from. */
+    resolvedFrom: string;
+}
+export interface CoordinateCompanion {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    brandSlug: string;
+    productId: ProductId;
+    totalLift: number;
+    liftLabel: string;
+    seedMatchCount: number;
+    seedContributions: Array<{
+        seedVariantId: VariantId;
+        lift: number;
+    }>;
+    demand: CompanionDemand | null;
+    swatches: Array<{
+        hex: string;
+        proportion: number;
+    }>;
+    /** Annotate-only appearance similarity — never reorders companions in v1. */
+    colourFit: number | null;
+}
+/**
+ * The `POST /api/v1/pairings/coordinate` envelope. `unresolved` lists the input
+ * references that matched nothing — read it before presenting `companions` as
+ * "what goes with your palette", because a companion set derived from two of
+ * four seeds is a different claim.
+ */
+export interface CoordinateResponse {
+    seeds: CoordinateSeed[];
+    /** Input references that resolved to no material. Never silently dropped. */
+    unresolved: string[];
+    window: "trailing_36mo";
+    companions: CoordinateCompanion[];
+}
+/** Body for `POST /api/v1/pairings/coordinate`. */
+export interface CoordinateInput {
+    /** Free-text material references, resolved server-side; misses land in `unresolved`. */
+    materials?: string[];
+    /** Exact variant ids. Opaque — pass through verbatim. */
+    variantIds?: VariantId[];
+    projectType?: string;
+    limit?: number;
+}

package/demand-types.js

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

package/identifiers.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The identifier vocabulary — WHICH strings you may look inside, and which you
+ * may not.
+ *
+ * MaterialGraph hands back two very different kinds of string, and the whole
+ * class of caller bugs this file exists to prevent comes from confusing them:
+ *
+ * - **Opaque tokens** ({@link VariantId}, {@link ProductId}, {@link RunId},
+ *   {@link BatchId}, {@link ProjectId}, {@link SchemeId}, {@link SlotId},
+ *   {@link Cursor}). Round-trip them BYTE-FOR-BYTE. Never parse one, never
+ *   construct one, never pattern-match one, never sort by one, and never read
+ *   meaning out of its length, prefix or character set. `62f8qmqb62nib58qnhf50`
+ *   has no structure, and the prefixes that do exist today (`smb_…`, `smf_…`)
+ *   are a convenience for humans reading logs, not a contract.
+ * - **Canonical vocabulary** — `attributeId`, `term`, `productTypeId`,
+ *   `categoryKey`, `jurisdictionId`, `brandSlug`. These ARE meaningful, stable,
+ *   and yours to compose queries from — but you DISCOVER them rather than
+ *   invent them (`specificationFacets()`, `attributeValues()`,
+ *   `searchVocabulary()`, `taxonomy()`, `colourFacets()`, `codes.context()`).
+ *   A hand-guessed canonical token is the second-most-common caller bug.
+ *
+ * Every alias below is exactly `string`. They carry no runtime weight and no
+ * nominal typing — they are documentation you can hover, and a signpost at the
+ * point of use.
+ */
+/**
+ * An OPAQUE identifier token. Preserve it verbatim; never parse, construct, or
+ * pattern-match one. See the module docblock for the full rule.
+ */
+export type OpaqueId = string;
+/**
+ * A variant id — the identity of ONE buyable material (this product in this
+ * colourway/finish). The unit almost every read is keyed on.
+ *
+ * Opaque: preserve verbatim, never parse or construct one.
+ */
+export type VariantId = OpaqueId;
+/**
+ * A product id — the family a {@link VariantId} belongs to. Sibling variants
+ * share it.
+ *
+ * Opaque: preserve verbatim, never parse or construct one.
+ */
+export type ProductId = OpaqueId;
+/**
+ * A Run id from the hosted agentic surface. Opaque: preserve verbatim, never
+ * parse or construct one.
+ */
+export type RunId = OpaqueId;
+/**
+ * A source-material batch id (`smb_…`). The prefix is a reading convenience,
+ * not a contract — treat the whole string as opaque.
+ */
+export type BatchId = OpaqueId;
+/** A stored source-material file id (`smf_…`). Opaque, prefix notwithstanding. */
+export type SourceFileId = OpaqueId;
+/** A persistent Material Box project id. Opaque. */
+export type ProjectId = OpaqueId;
+/** A composition scheme id, unique within its Run. Opaque. */
+export type SchemeId = OpaqueId;
+/** A composition slot id, unique within its scheme. Opaque. */
+export type SlotId = OpaqueId;
+/**
+ * A pagination cursor. Opaque keyset state, not an offset and not a page
+ * number: pass the value you were handed back unchanged to continue, and never
+ * synthesise one. A response with no cursor is the end of the walk.
+ *
+ * A cursor is only valid for the query that produced it — changing sort,
+ * filters or limit invalidates it.
+ */
+export type Cursor = string;

package/identifiers.js

@@ -0,0 +1,26 @@
+/**
+ * The identifier vocabulary — WHICH strings you may look inside, and which you
+ * may not.
+ *
+ * MaterialGraph hands back two very different kinds of string, and the whole
+ * class of caller bugs this file exists to prevent comes from confusing them:
+ *
+ * - **Opaque tokens** ({@link VariantId}, {@link ProductId}, {@link RunId},
+ *   {@link BatchId}, {@link ProjectId}, {@link SchemeId}, {@link SlotId},
+ *   {@link Cursor}). Round-trip them BYTE-FOR-BYTE. Never parse one, never
+ *   construct one, never pattern-match one, never sort by one, and never read
+ *   meaning out of its length, prefix or character set. `62f8qmqb62nib58qnhf50`
+ *   has no structure, and the prefixes that do exist today (`smb_…`, `smf_…`)
+ *   are a convenience for humans reading logs, not a contract.
+ * - **Canonical vocabulary** — `attributeId`, `term`, `productTypeId`,
+ *   `categoryKey`, `jurisdictionId`, `brandSlug`. These ARE meaningful, stable,
+ *   and yours to compose queries from — but you DISCOVER them rather than
+ *   invent them (`specificationFacets()`, `attributeValues()`,
+ *   `searchVocabulary()`, `taxonomy()`, `colourFacets()`, `codes.context()`).
+ *   A hand-guessed canonical token is the second-most-common caller bug.
+ *
+ * Every alias below is exactly `string`. They carry no runtime weight and no
+ * nominal typing — they are documentation you can hover, and a signpost at the
+ * point of use.
+ */
+export {};

package/index.d.ts

@@ -2,6 +2,7 @@ export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.j
 export type { MaterialGraphClientOptions, BrowseNamespace } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
+export type * from "./identifiers.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
 export type * from "./schedule-types.js";

package/material-asset-types.d.ts

@@ -1,5 +1,22 @@
+/**
+ * Wire types for the material ASSET projection
+ * (`GET /api/v1/materials/{variantId}/assets`).
+ *
+ * THE LENS: "what may I show for this material?" — the redistribution-safe
+ * images and downloads, not every file on record. An asset absent here is not
+ * an asset that does not exist; it is one this surface does not hand out.
+ */
+import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 export type MaterialAssetVisualRole = OpenEnum<"grid" | "detail" | "scene" | "swatch" | "technical" | "unknown">;
+/**
+ * Whether we hold the bytes.
+ *  - `downloaded` — held and served by us.
+ *  - `linked_not_downloaded` — the source names it; we have not fetched it. Not
+ *    a broken asset.
+ *  - `failed` — we tried and could not. Says nothing about the source.
+ *  - `retired_placeholder` — a stand-in for a withdrawn asset.
+ */
 export type MaterialAssetStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "failed" | "retired_placeholder">;
 export interface MaterialAssetProjectionImage {
     key: string;
@@ -22,13 +39,15 @@ export interface MaterialAssetProjectionDownload {
     fileExtension: string | null;
     filename: string | null;
 }
+/** Tallies over what this projection returned — never a claim about the brand's own library. */
 export interface MaterialAssetProjectionSummary {
     imageCount: number;
     downloadCount: number;
     downloadedImageCount: number;
 }
 export interface MaterialAssetProjection {
-    variantId: string;
+    /** Opaque — echoed from the request. */
+    variantId: VariantId;
     images: MaterialAssetProjectionImage[];
     downloads: MaterialAssetProjectionDownload[];
     summary: MaterialAssetProjectionSummary;

package/material-block-types.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Wire types for the block-coverage projection
+ * (`GET /api/v1/materials/{variantId}/blocks`).
+ *
+ * THE AUTHORITY ON "ABSENT IS NOT FALSE". Everywhere else in the SDK an absent
+ * value is ambiguous — you cannot tell "we looked and there is none" from
+ * "nobody has looked". This projection is the one read that says WHICH, per
+ * field, in {@link MaterialCoverageStatus}. When a caller needs to render a
+ * negative ("this material carries no fire rating") rather than an unknown, this
+ * is the only surface entitled to back it: a `verified` field with a `false` /
+ * `0` / `[]` value. Never derive a negative from a value's absence elsewhere.
+ */
+import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
  * Coverage status, shared by blocks and fields.
@@ -22,8 +35,18 @@ import type { OpenEnum } from "./types.js";
 export type MaterialCoverageStatus = OpenEnum<"verified" | "partial" | "missing" | "not_applicable">;
 export type MaterialBlockStatus = MaterialCoverageStatus;
 export type MaterialBlockFieldStatus = MaterialCoverageStatus;
+/**
+ * A field's value. `null` is AMBIGUOUS on its own — pair it with `status`:
+ * `verified` + `null` is a determined absence, `missing` + `null` is unread.
+ */
 export type MaterialBlockFieldValue = string | number | boolean | unknown[] | Record<string, unknown> | null;
+/**
+ * One field of a block. READ `status` BEFORE `value` — a `false` under
+ * `status: "verified"` is a real negative you may publish; the same `false`
+ * under `missing` is a placeholder for an unanswered question.
+ */
 export interface MaterialBlockProjectionField {
+    /** Canonical vocabulary, not an opaque id — the same token `bySpec` accepts. */
     attributeId: string;
     label: string;
     value: MaterialBlockFieldValue;
@@ -35,9 +58,15 @@ export interface MaterialBlockProjectionItem {
     canonicalBlockName: string;
     status: MaterialBlockStatus;
     fields: MaterialBlockProjectionField[];
+    /** The work queue: attributes with `status: "missing"`. UNKNOWN, never "none". */
     missingAttributeIds: string[];
 }
+/**
+ * Every canonical block for one material, each field carrying whether it is
+ * determined. The whole surface, not a page — there is no cursor here.
+ */
 export interface MaterialBlockProjection {
-    variantId: string;
+    /** Opaque — echoed from the request. */
+    variantId: VariantId;
     blocks: MaterialBlockProjectionItem[];
 }

package/material-types.d.ts

@@ -6,8 +6,23 @@
  * stays within the repository's source-size budget. Same contract, same
  * tolerant-parsing rules: response enums are OPEN, so `MaterialAvailability` is
  * widened — a new server state still type-checks.
+ *
+ * ABSENT IS NOT FALSE, and it is the rule this whole file hangs on. A material
+ * record reports what the graph HOLDS, never what is true of the object in the
+ * world. `null` and a missing key both mean UNKNOWN:
+ *  - `dimensions: null` does not mean the material has no dimensions.
+ *  - `supersededBy: null` does not mean the product is current.
+ *  - a `facets` array without an attribute does not mean the material lacks that
+ *    property — it means nobody has recorded one.
+ *  - most dangerously, no boolean here may be inverted from an absence. Never
+ *    render "not certified" / "no fire rating" from a missing entry; render
+ *    "not on record".
+ * Read {@link MaterialBlockProjection} when you need to tell "we looked and
+ * there is none" apart from "nobody has looked" — that is the only projection
+ * that says which.
  */
 import type { ImageSource, MaterialColour, OpenEnum, PaletteSwatch } from "./types.js";
+import type { ProductId, VariantId } from "./identifiers.js";
 /**
  * Whether a material can still be bought.
  *
@@ -27,9 +42,10 @@ export type MaterialAvailability = OpenEnum<"available" | "discontinued" | "supe
  * here; follow `variantId` for the next link in the chain.
  */
 export interface MaterialSuccessor {
-    variantId: string;
+    /** Opaque — round-trip verbatim to read the successor. */
+    variantId: VariantId;
     brandSlug: string;
-    productId: string;
+    productId: ProductId;
     brand: string;
     product: string;
     variant: string;
@@ -41,7 +57,8 @@ export interface MaterialSuccessor {
  * successor record — read the detail projection for that.
  */
 export interface MaterialTile {
-    variantId: string;
+    /** Opaque — round-trip verbatim into every other material read. */
+    variantId: VariantId;
     brand: string;
     product: string;
     variantName: string | null;
@@ -51,7 +68,14 @@ export interface MaterialTile {
     colour: MaterialColour;
     availability: MaterialAvailability;
 }
-/** A canonical attribute/term pair carried on a detail record. */
+/**
+ * A canonical attribute/term pair carried on a detail record.
+ *
+ * `attributeId` and `term` are canonical VOCABULARY, not opaque ids — the same
+ * tokens `bySpec` / `search({ filters })` accept, discoverable through
+ * `specificationFacets()` and `attributeValues()`. An attribute absent from
+ * `facets` is unrecorded, never known-false.
+ */
 export interface MaterialFacet {
     attributeId: string;
     term: string;
@@ -75,18 +99,32 @@ export interface DimensionEntry {
     weight_kg?: number;
     [key: string]: unknown;
 }
-/** The record projection of a material — the tile plus detail-only fields. */
+/**
+ * The record projection of a material — the tile plus detail-only fields.
+ *
+ * The deepest read of ONE material, and still not an assertion about the object:
+ * every `| null` below is UNKNOWN, not "none". See the module docblock.
+ */
 export interface MaterialDetail extends MaterialTile {
     brandSlug: string;
-    productId: string;
+    /** Opaque — the product family; siblings share it. */
+    productId: ProductId;
     color: string | null;
+    /** Material Bank's own opaque id, when one is mapped. Null = unmapped, not absent. */
     materialBankId: string | null;
     installationImageUrl: string | null;
     displayCategory: string | null;
     categoryPath: string[];
+    /** Extracted from imagery — visual likeness, never a declared colour spec. */
     palette: PaletteSwatch[];
+    /** What is ON RECORD. An absent attribute is unrecorded, never known-false. */
     facets: MaterialFacet[];
+    /** `null` = no dimensions recorded, NOT a dimensionless material. */
     dimensions: DimensionEntry[] | null;
-    /** The declared successor, or null when no reviewed relationship names one. */
+    /**
+     * The declared successor, or null when NO REVIEWED RELATIONSHIP NAMES ONE —
+     * which is not the same as "this product is current". Read `availability` for
+     * that, and even then `unknown` is a real answer.
+     */
     supersededBy: MaterialSuccessor | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "exports": {
     ".": {

package/palette-search-types.d.ts

@@ -11,6 +11,7 @@
  * {@link SearchPaletteInput.logic} and {@link GradientMatch.coverage} 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">;
@@ -50,7 +51,11 @@ export interface SearchGradientInput {
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
 }
-/** One swatch of a candidate's colorscope-extracted palette. */
+/**
+ * One swatch of a candidate's colorscope-EXTRACTED palette. Derived from product
+ * imagery, never a manufacturer's declared colour. `name` is null when no human
+ * name was resolved — unnamed, not colourless.
+ */
 export interface CandidateSwatch {
     hex: string;
     proportion: number;
@@ -70,7 +75,8 @@ export interface ColourMatchReceipt {
 }
 /** Identity and evidence shared by both multi-colour match shapes. */
 export interface MultiColourMatchBase {
-    variantId: string;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
     brand: string;
     product: string;
     brandSlug: string | null;
@@ -99,7 +105,13 @@ export interface GradientMatch extends MultiColourMatchBase {
     /** One receipt per sampled point along the path, in path order. */
     samples: ColourMatchReceipt[];
 }
+/**
+ * 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 interface SearchPaletteResponse {
+    /** The query as interpreted — check it before trusting a surprising order. */
     query: {
         colours: Array<{
             hex: string;
@@ -108,15 +120,18 @@ export interface SearchPaletteResponse {
         }>;
         logic: PaletteLogic;
     };
+    /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: PaletteMatch[];
 }
+/** A PAGE, NOT A CORPUS — see {@link SearchPaletteResponse}. */
 export interface SearchGradientResponse {
     query: {
         stops: string[];
         /** The sampled path points the search actually ran against. */
         samples: string[];
     };
+    /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: GradientMatch[];
 }

package/project-types.d.ts

@@ -4,7 +4,16 @@
  * has zero runtime dependency on `@materialgraph/*`. Kept shape-identical to the
  * server contract; the OpenAPI parity test gates method/path/operationId, and the
  * server route schemas gate the body shapes.
+ *
+ * THE LENS: a project is the DESIGNER'S OWN record — an append-only trail of
+ * what they attached, asked, preferred and adopted. It holds no material data of
+ * its own; every `variantId`, `batchId` and `runId` in it is a reference into
+ * the other lenses. Read the folded collections on {@link ProjectState}; the raw
+ * `events` log is there for audit, not for reconstruction.
+ *
+ * Every id here is OPAQUE — round-trip verbatim, never parse or construct one.
  */
+import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
 /** The six governed project-event kinds. */
 export type ProjectEventKind = "batch-attached" | "run-started" | "clarifying-answer" | "pairwise-preference" | "reference-chosen" | "scheme-adopted";
 /** The frozen tuple of every project-event kind, for enumeration. */
@@ -14,11 +23,11 @@ export interface ClarifyingAnswer {
     question: string;
     answer: string;
 }
-/** One pairwise preference; `chosenId` is `leftId` or `rightId`. */
+/** One pairwise preference; `chosenId` is `leftId` or `rightId`. All three opaque. */
 export interface PairwisePreference {
-    leftId: string;
-    rightId: string;
-    chosenId: string;
+    leftId: VariantId;
+    rightId: VariantId;
+    chosenId: VariantId;
 }
 /** One stored event; `payload` is validated to the shape of `kind`. */
 export interface ProjectEvent {
@@ -29,7 +38,8 @@ export interface ProjectEvent {
 }
 /** A lightweight project row for list views (no event fold). */
 export interface ProjectSummary {
-    projectId: string;
+    /** Opaque — round-trip verbatim. */
+    projectId: ProjectId;
     principalId: string;
     name: string;
     createdAt: string;
@@ -37,8 +47,10 @@ export interface ProjectSummary {
 }
 /** A project's assembled read model — identity plus the folded event collections. */
 export interface ProjectState extends ProjectSummary {
-    batchIds: string[];
-    runIds: string[];
+    /** Source-material batches attached, oldest first. Opaque. */
+    batchIds: BatchId[];
+    /** Runs started from this project, oldest first. Opaque. */
+    runIds: RunId[];
     answers: ClarifyingAnswer[];
     preferences: PairwisePreference[];
     chosenReferences: string[];
@@ -61,7 +73,7 @@ export interface AppendProjectEventRequest {
 /** `POST /api/v1/projects/{projectId}/events` response — the appended event receipt. */
 export interface ProjectEventReceipt {
     eventId: string;
-    projectId: string;
+    projectId: ProjectId;
     kind: ProjectEventKind;
     createdAt: string;
 }

package/project-types.js

@@ -1,10 +1,3 @@
-/**
- * Wire types for the persistent Material Box project surface (`/api/v1/projects`).
- * Hand-mirrored from `@materialgraph/products/projects`' Zod contract — the SDK
- * has zero runtime dependency on `@materialgraph/*`. Kept shape-identical to the
- * server contract; the OpenAPI parity test gates method/path/operationId, and the
- * server route schemas gate the body shapes.
- */
 /** The frozen tuple of every project-event kind, for enumeration. */
 export const PROJECT_EVENT_KINDS = Object.freeze([
     "batch-attached",

package/run-types.d.ts

@@ -10,6 +10,7 @@
  * so a new server value still type-checks, and objects are read structurally —
  * unknown keys pass through untouched.
  */
+import type { BatchId, RunId, SourceFileId } from "./identifiers.js";
 import type { JsonValue, OpenEnum } from "./types.js";
 /**
  * A file to upload. Two forms so the SDK is ergonomic on BOTH Node route
@@ -52,8 +53,8 @@ export interface UploadSourceMaterialLegacyInput {
 export type UploadSourceMaterialInput = UploadSourceMaterialFilesInput | UploadSourceMaterialLegacyInput;
 /** One stored file in an upload receipt. */
 export interface SourceMaterialReceiptFile {
-    /** The stored file id (`smf_…`). */
-    sourceId: string;
+    /** The stored file id (`smf_…`). Opaque — the prefix is a reading aid, not a contract. */
+    sourceId: SourceFileId;
     /**
      * The pipeline-assigned role. The vocabulary grows over time; {@link OpenEnum}
      * keeps a newer server value type-checking. `unclassified` is a legitimate
@@ -70,8 +71,8 @@ export interface SourceMaterialReceiptFile {
 }
 /** The `201` receipt from `POST /api/v1/source-material`. */
 export interface SourceMaterialBatchReceipt {
-    /** The stored batch id (`smb_…`). */
-    batchId: string;
+    /** The stored batch id (`smb_…`). Opaque — hand it straight to a compose Run. */
+    batchId: BatchId;
     sources: SourceMaterialReceiptFile[];
 }
 /**
@@ -120,8 +121,8 @@ export interface SourceMaterialBatchFile extends SourceMaterialReceiptFile {
  * file it holds, and the analyses computed over each file's bytes.
  */
 export interface SourceMaterialBatchDetail {
-    /** The stored batch id (`smb_…`). */
-    batchId: string;
+    /** The stored batch id (`smb_…`). Opaque. */
+    batchId: BatchId;
     /** ISO-8601 timestamp of the upload. */
     createdAt: string;
     sources: SourceMaterialBatchFile[];
@@ -180,16 +181,23 @@ export interface PublicRunArtifactRef {
  * never returned — inputs and outputs are the `redacted*Json` projections.
  */
 export interface PublicRun {
-    id: string;
+    /** Opaque — round-trip verbatim into every other Run call. */
+    id: RunId;
     capabilityKind: CapabilityKind;
     capabilityId: string;
     clientReference: string | null;
+    /** `suspended` is a QUESTION, not a failure — see `suspensionStepId`. */
     status: PublicRunStatus;
     redactedInputJson: Record<string, unknown>;
     redactedOutputJson: Record<string, unknown> | null;
     usageJson: Record<string, unknown> | null;
     artifactRefs: PublicRunArtifactRef[] | null;
     failureJson: PublicRunFailure | null;
+    /**
+     * The step awaiting input while `status` is `suspended`. Pass it as
+     * {@link ResumeRunOptions.stepId} so a stale client cannot resume a step the
+     * Run has already moved past.
+     */
     suspensionStepId: string | null;
     eventCursor: number;
     attempts: number;
@@ -205,7 +213,11 @@ export interface CreatePublicRunRequest {
     capabilityId: string;
     /** The capability input, validated server-side against its live input schema. */
     inputJson: unknown;
-    /** Stable caller key making Run creation idempotent across retries. */
+    /**
+     * Stable caller key making Run creation idempotent across retries. Supply it:
+     * without one, a retried POST starts a SECOND Run rather than replaying the
+     * first (`replayed` on the response tells you which happened).
+     */
     idempotencyKey?: string;
     /** Free-form caller correlation reference, echoed back on the Run. */
     clientReference?: string;