@instruments/materialgraph 0.38.0 → 0.40.0

package/runs.d.ts

@@ -15,8 +15,9 @@ export declare const getWorkflowRun: (transport: HttpTransport, workflowId: stri
  * /api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until the stream ends or
  * `signal` aborts. One connection is bounded server-side (~25s or a terminal
  * event); pass `after` to resume from the last observed sequence.
+ * @yields {RunEvent} Each usable Run event from the stream.
  */
-export declare function streamRunEvents(transport: HttpTransport, workflowId: string, runId: string, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent, void, unknown>;
+export declare const streamRunEvents: (transport: HttpTransport, workflowId: string, runId: string, options?: StreamRunEventsOptions) => AsyncGenerator<RunEvent, void, unknown>;
 /**
  * Collect Run events until a terminal event, the deadline, or the stream ends —
  * the bounded events-log pattern the console uses. A single pass over

package/runs.js

@@ -9,16 +9,52 @@ import { MaterialGraphError } from "./errors.js";
 import { findSdkOperation, operationPath } from "./operations.js";
 import { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 import { readSseFrames } from "./sse.js";
+const hasSourceIdentity = (source) => typeof source === "object" &&
+    source !== null &&
+    "sourceId" in source &&
+    typeof source.sourceId === "string" &&
+    "role" in source &&
+    typeof source.role === "string" &&
+    "filename" in source &&
+    typeof source.filename === "string" &&
+    "mediaType" in source &&
+    typeof source.mediaType === "string";
+const hasSourceMeasurements = (source) => typeof source === "object" &&
+    source !== null &&
+    "sha256" in source &&
+    typeof source.sha256 === "string" &&
+    "bytes" in source &&
+    typeof source.bytes === "number" &&
+    "pages" in source &&
+    (source.pages === null || typeof source.pages === "number");
+const isSourceReceipt = (value) => typeof value === "object" &&
+    value !== null &&
+    "batchId" in value &&
+    typeof value.batchId === "string" &&
+    "sources" in value &&
+    Array.isArray(value.sources) &&
+    value.sources.every((source) => typeof source === "object" &&
+        source !== null &&
+        hasSourceIdentity(source) &&
+        hasSourceMeasurements(source));
+const isRunEvent = (value) => typeof value === "object" &&
+    value !== null &&
+    "sequence" in value &&
+    typeof value.sequence === "number" &&
+    "type" in value &&
+    typeof value.type === "string";
 const runOperation = (operationId) => {
     const match = findSdkOperation(operationId);
     if (!match) {
         throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
     }
-    return match;
+    return { ...match, operationId };
 };
 /** Build a `Blob` from raw bytes, normalising to an ArrayBuffer-backed view. */
 const bytesToBlob = (input) => {
-    const type = input.contentType ? { type: input.contentType } : {};
+    const type = input.contentType !== undefined && input.contentType !== ""
+        ? { type: input.contentType }
+        : {};
     if (input.data instanceof ArrayBuffer) {
         return new Blob([input.data], type);
     }
@@ -60,6 +96,9 @@ export const uploadSourceMaterial = async (transport, input, signal) => {
         signal,
         url,
     });
+    if (!isSourceReceipt(parsed)) {
+        throw MaterialGraphError.unexpected("MaterialGraph source-material upload returned an invalid receipt");
+    }
     return parsed;
 };
 /** Start an asynchronous Run of one workflow (`POST /api/v1/workflows/{workflowId}/runs`). */
@@ -85,22 +124,16 @@ const decodeRunEvent = (data) => {
     catch (cause) {
         throw MaterialGraphError.unexpected(`MaterialGraph run-event stream sent an unparseable data frame: ${String(cause)}`);
     }
-    if (typeof parsed !== "object" || parsed === null) {
-        return null;
-    }
-    const record = parsed;
-    if (typeof record.sequence !== "number" || typeof record.type !== "string") {
-        return null;
-    }
-    return parsed;
+    return isRunEvent(parsed) ? parsed : null;
 };
 /**
  * Stream ordered Run events as an async iterator (`GET
  * /api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until the stream ends or
  * `signal` aborts. One connection is bounded server-side (~25s or a terminal
  * event); pass `after` to resume from the last observed sequence.
+ * @yields {RunEvent} Each usable Run event from the stream.
  */
-export async function* streamRunEvents(transport, workflowId, runId, options = {}) {
+export const streamRunEvents = async function* streamRunEvents(transport, workflowId, runId, options = {}) {
     const body = await transport.openStream(runOperation("list_public_run_events"), {
         pathParams: { runId, workflowId },
         ...(options.after === undefined
@@ -116,7 +149,7 @@ export async function* streamRunEvents(transport, workflowId, runId, options = {
             yield event;
         }
     }
-}
+};
 /**
  * Collect Run events until a terminal event, the deadline, or the stream ends —
  * the bounded events-log pattern the console uses. A single pass over

package/samplize-catalogue-types.d.ts

@@ -4,8 +4,6 @@ export type SamplizeCatalogueOptions = {
     after?: string;
     /** Exact canonical identities, at most 100. Unknown/ineligible IDs are omitted; no substitution. Combined filters intersect. */
     variantIds?: string[];
-    /** Exact source collection handle; publisher remains Samplize. */
-    collectionHandle?: string;
     /** Pin every subsequent page to the version returned by the first page. */
     sourceVersion?: string;
 };
@@ -20,9 +18,10 @@ export type SamplizeCatalogueProduct = {
     };
     hex: string;
     hexSource: {
-        publisher: "Samplize";
-        url: string;
-        source: "snowflake_product_tags";
+        publisher: string;
+        url: string | null;
+        source: "resolved_variant";
+        valueSource: string | null;
     };
     lrv: number | null;
     lrvSource: SamplizeLrvObservation | null;
@@ -36,8 +35,8 @@ export type SamplizeCatalogueProduct = {
         a: number;
         b: number;
     };
-    sourceProductId: string;
-    url: string;
+    sourceProductId: string | null;
+    url: string | null;
     sizeVariants: {
         sourceVariantId: string;
         sku: string | null;
@@ -56,6 +55,7 @@ export type SamplizeCataloguePage = {
     source: Record<string, unknown>;
     /** Number of eligible records matching the supplied filters. */
     total: number;
+    unavailableFields: string[];
     items: SamplizeCatalogueProduct[];
     nextCursor: string | null;
     /** True on the final page; completeness requires collecting total unique IDs. */
@@ -66,7 +66,7 @@ export type SamplizeHexObservation = {
     publisher: string;
     source: string;
     sourceUrl: string | null;
-    valueOrigin: string;
+    valueSource: string;
     observedAt: string | null;
     differsFromSelected: boolean;
 };

package/samplize-colorvec.js

@@ -2,7 +2,13 @@ import { EMBEDDING_VERSION, EMBEDDING_VECTOR_SIZE, embeddingCosineSimilarity, pa
 export const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
 export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
 const decodeVector = (encoded) => {
-    const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
+    const bytes = Uint8Array.from(atob(encoded), (c) => {
+        const codePoint = c.codePointAt(0);
+        if (codePoint === undefined) {
+            throw new Error("Missing encoded vector byte.");
+        }
+        return codePoint;
+    });
     if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4) {
         throw new Error("Invalid color vector size.");
     }
@@ -12,19 +18,23 @@ const decodeVector = (encoded) => {
 const facets = ["brand", "family", "lightness", "intensity"];
 const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 export const samplizeSolidColorVector = (hex) => {
-    if (!/^#[0-9a-f]{6}$/i.test(hex)) {
+    if (!/^#[0-9a-f]{6}$/iu.test(hex)) {
         throw new Error("A six-digit published color is required.");
     }
     return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
 };
-/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
-export const selectSamplizeEligiblePaints = (paints, input) => {
-    const reference = input.reference
+const findReferencePaint = (paints, input) => {
+    const reference = input.reference !== undefined && input.reference !== ""
         ? paints.find((p) => p.variantId === input.reference)
         : undefined;
-    if (input.reference && !reference) {
+    if (input.reference !== undefined && input.reference !== "" && !reference) {
         throw new Error("The reference is absent from this catalogue version.");
     }
+    return reference;
+};
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export const selectSamplizeEligiblePaints = (paints, input) => {
+    const reference = findReferencePaint(paints, input);
     const low = input.lightnessMin ?? 0;
     const high = input.lightnessMax ?? 1;
     const cool = input.temperatureMin ?? -0.4;
@@ -57,7 +67,10 @@ export const selectSamplizeEligiblePaints = (paints, input) => {
         p.oklab.L <= high &&
         p.oklab.b >= cool &&
         p.oklab.b <= warm &&
-        facets.every((f) => f === omit || !input[f]?.length || input[f].includes(p[f]));
+        facets.every((f) => f === omit ||
+            input[f] === undefined ||
+            input[f].length === 0 ||
+            input[f].includes(p[f]));
     const counts = {
         brand: {},
         family: {},
@@ -74,6 +87,91 @@ export const selectSamplizeEligiblePaints = (paints, input) => {
     const eligible = candidates.filter((p) => matches(p));
     return { counts, eligible, reference };
 };
+const searchPalette = (input, reference) => {
+    const palette = (input.palette !== undefined && input.palette.length > 0
+        ? input.palette
+        : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
+        .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
+        .toSorted((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
+    if (palette.length > 12 ||
+        palette.some((p) => !Number.isFinite(p.proportion) || p.proportion <= 0 || p.proportion > 1)) {
+        throw new Error("Supply up to twelve positive image color shares.");
+    }
+    return palette;
+};
+const searchSamplizePaints = (cache, paints, input, vectorFor) => {
+    const limit = input.limit ?? 48;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        throw new Error("Choose between 1 and 100 suggestions.");
+    }
+    const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
+    const palette = searchPalette(input, reference);
+    const total = palette.reduce((sum, p) => sum + p.proportion, 0);
+    const buckets = palette.map((p, position) => {
+        const bucketPaints = [];
+        return {
+            ...p,
+            paints: bucketPaints,
+            position,
+            quota: Math.floor((limit * p.proportion) / total),
+            remainder: ((limit * p.proportion) / total) % 1,
+            vector: vectorFor(p.hex),
+        };
+    });
+    let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
+    for (const p of [...buckets].toSorted((a, b) => b.remainder - a.remainder || a.position - b.position)) {
+        if (remaining-- > 0) {
+            p.quota++;
+        }
+    }
+    for (const paint of eligible) {
+        let best = buckets[0];
+        if (best === undefined) {
+            throw new Error("Missing first palette bucket.");
+        }
+        let score = embeddingCosineSimilarity(paint.vector, best.vector);
+        for (let i = 1; i < buckets.length; i++) {
+            const candidate = buckets[i];
+            if (candidate === undefined) {
+                throw new Error("Missing palette bucket.");
+            }
+            const next = embeddingCosineSimilarity(paint.vector, candidate.vector);
+            if (next > score) {
+                best = candidate;
+                score = next;
+            }
+        }
+        best.paints.push({ id: paint.variantId, score });
+    }
+    const groups = buckets
+        .toSorted((a, b) => b.proportion - a.proportion || a.position - b.position)
+        .map((p) => {
+        const ids = p.paints
+            .toSorted((a, b) => b.score - a.score || identityOrder(a.id, b.id))
+            .slice(0, p.quota)
+            .map((paint) => paint.id);
+        return {
+            hex: p.hex,
+            ids,
+            proportion: p.proportion,
+            quota: p.quota,
+            shortfall: p.quota - ids.length,
+        };
+    });
+    const ids = groups.flatMap((p) => p.ids);
+    return {
+        countBasis: "complete-catalogue",
+        counts,
+        dictionaryVersion: cache.dictionaryVersion,
+        eligibleCount: eligible.length,
+        embeddingVersion: cache.embeddingVersion,
+        groups,
+        ids,
+        limited: eligible.length > ids.length,
+        rankingVersion: cache.rankingVersion,
+        sourceVersion: cache.sourceVersion,
+    };
+};
 /** Official portable MG ranking over its complete versioned sampling-channel projection. */
 export const createSamplizeColorVecIndex = (cache) => {
     if (cache.embeddingVersion !== EMBEDDING_VERSION ||
@@ -106,7 +204,11 @@ export const createSamplizeColorVecIndex = (cache) => {
         if (!value) {
             value = samplizeSolidColorVector(hex);
             if (vectors.size >= 512) {
-                vectors.delete(vectors.keys().next().value);
+                const oldest = vectors.keys().next().value;
+                if (oldest === undefined) {
+                    throw new Error("Missing oldest cached color vector.");
+                }
+                vectors.delete(oldest);
             }
             vectors.set(key, value);
         }
@@ -114,78 +216,7 @@ export const createSamplizeColorVecIndex = (cache) => {
     };
     return {
         search(input) {
-            const limit = input.limit ?? 48;
-            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
-                throw new Error("Choose between 1 and 100 suggestions.");
-            }
-            const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
-            const palette = (input.palette?.length
-                ? input.palette
-                : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
-                .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
-                .toSorted((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
-            if (palette.length > 12 ||
-                palette.some((p) => !Number.isFinite(p.proportion) ||
-                    p.proportion <= 0 ||
-                    p.proportion > 1)) {
-                throw new Error("Supply up to twelve positive image color shares.");
-            }
-            const total = palette.reduce((sum, p) => sum + p.proportion, 0);
-            const buckets = palette.map((p, position) => ({
-                ...p,
-                paints: [],
-                position,
-                quota: Math.floor((limit * p.proportion) / total),
-                remainder: ((limit * p.proportion) / total) % 1,
-                vector: vectorFor(p.hex),
-            }));
-            let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
-            for (const p of [...buckets].toSorted((a, b) => b.remainder - a.remainder || a.position - b.position)) {
-                if (remaining-- > 0) {
-                    p.quota++;
-                }
-            }
-            for (const paint of eligible) {
-                let best = buckets[0];
-                let score = embeddingCosineSimilarity(paint.vector, best.vector);
-                for (let i = 1; i < buckets.length; i++) {
-                    const candidate = buckets[i];
-                    const next = embeddingCosineSimilarity(paint.vector, candidate.vector);
-                    if (next > score) {
-                        best = candidate;
-                        score = next;
-                    }
-                }
-                best.paints.push({ id: paint.variantId, score });
-            }
-            const groups = buckets
-                .toSorted((a, b) => b.proportion - a.proportion || a.position - b.position)
-                .map((p) => {
-                const ids = p.paints
-                    .toSorted((a, b) => b.score - a.score || identityOrder(a.id, b.id))
-                    .slice(0, p.quota)
-                    .map((paint) => paint.id);
-                return {
-                    hex: p.hex,
-                    ids,
-                    proportion: p.proportion,
-                    quota: p.quota,
-                    shortfall: p.quota - ids.length,
-                };
-            });
-            const ids = groups.flatMap((p) => p.ids);
-            return {
-                countBasis: "complete-catalogue",
-                counts,
-                dictionaryVersion: cache.dictionaryVersion,
-                eligibleCount: eligible.length,
-                embeddingVersion: cache.embeddingVersion,
-                groups,
-                ids,
-                limited: eligible.length > ids.length,
-                rankingVersion: cache.rankingVersion,
-                sourceVersion: cache.sourceVersion,
-            };
+            return searchSamplizePaints(cache, paints, input, vectorFor);
         },
     };
 };

package/sse.d.ts

@@ -31,5 +31,6 @@ export declare class SseDecoder {
  * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
  * or `signal` aborts (mid-read abort rejections are swallowed once the signal
  * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
+ * @yields {SseFrame} Each completed frame containing fields.
  */
-export declare function readSseFrames(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseFrame, void, unknown>;
+export declare const readSseFrames: (body: ReadableStream<Uint8Array>, signal?: AbortSignal) => AsyncGenerator<SseFrame, void, unknown>;

package/sse.js

@@ -121,14 +121,16 @@ export class SseDecoder {
  * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
  * or `signal` aborts (mid-read abort rejections are swallowed once the signal
  * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
+ * @yields {SseFrame} Each completed frame containing fields.
  */
-export async function* readSseFrames(body, signal) {
+export const readSseFrames = async function* readSseFrames(body, signal) {
+    const isAborted = () => signal?.aborted === true;
     const reader = body.getReader();
     const decoder = new TextDecoder();
     const sse = new SseDecoder();
     try {
         for (;;) {
-            if (signal?.aborted) {
+            if (isAborted()) {
                 return;
             }
             let result;
@@ -136,7 +138,7 @@ export async function* readSseFrames(body, signal) {
                 result = await reader.read();
             }
             catch (error) {
-                if (signal?.aborted) {
+                if (isAborted()) {
                     return;
                 }
                 throw error;
@@ -152,7 +154,7 @@ export async function* readSseFrames(body, signal) {
             }
             const text = decoder.decode(result.value, { stream: true });
             for (const frame of sse.push(text)) {
-                if (signal?.aborted) {
+                if (isAborted()) {
                     return;
                 }
                 yield frame;
@@ -162,4 +164,4 @@ export async function* readSseFrames(body, signal) {
     finally {
         reader.releaseLock();
     }
-}
+};

package/types.d.ts

@@ -10,7 +10,7 @@ import type { MaterialTile } from "./material-types.js";
  * against the real Zod schemas so the mirror cannot silently drift.
  * TOLERANT-PARSING CONTRACT: the public surface declares open response enums —
  * "clients must tolerate unknown enum values and unknown fields". Every union
- * that mirrors a server enum is therefore widened with `(string & {})` so a new
+ * that mirrors a server enum is therefore widened with `(string & Record<never, never>)` so a new
  * server value still type-checks, and objects that may grow fields are read
  * structurally (unknown keys pass through untouched — the client never strips).
  *
@@ -21,12 +21,12 @@ import type { MaterialTile } from "./material-types.js";
  *     are canonical vocabulary you discover.
  *  2. **Absent is not false.** An optional field that is missing means UNKNOWN,
  *     not "known to be absent in reality" — most dangerously for booleans.
- *     Values carry `confidence` and `valueOrigin`; report them as claims.
+ *     Values carry `confidence` and `valueSource`; report them as claims.
  *  3. **A page is not a corpus.** A list is this page. Follow the cursor for
  *     the rest, and never report a page size as a total.
  */
 import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
-export type OpenEnum<T extends string> = T | (string & {});
+export type OpenEnum<T extends string> = T | (string & Record<never, never>);
 export type { JsonValue } from "./json-value-types.js";
 /** OKLab triple. */
 export type OklabTriple = {
@@ -247,9 +247,9 @@ export type ListAttributesResult = {
         hasNextPage: boolean;
     };
 };
-export type * from "./catalog-discovery-types.js";
-export type * from "./resolve-color-types.js";
-export type * from "./by-spec-types.js";
+export type { ResolveValueCandidate, ValueResolution, } from "./catalog-discovery-types.js";
+export type { ResolveColorOptions, ResolveColorCatalogueVariant, ResolveColorVariant, ResolveColorResponse, } from "./resolve-color-types.js";
+export type { BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./by-spec-types.js";
 export type WhoamiResponse = {
     principal: string;
     scopes: string[];