@instruments/materialgraph 0.10.0 → 0.11.0

package/slot-pool-types.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Hand-mirrored wire types for the slot-pool surface
+ * (`POST /api/v1/schemes/pools`, operation `slot_pools`, MG-1301). Like the rest
+ * of the SDK these interfaces carry NO runtime dependency on any
+ * `@materialgraph/*` package — they mirror the `SlotPoolsRequest` /
+ * `SlotPoolsResponse` shapes in `apps/web/public/openapi.yaml`.
+ *
+ * THE QUESTION IT ANSWERS: "for each of these slots, what should I be choosing
+ * between?" One call, up to 24 slots, one ranked and gated pool each. There is
+ * no project and no run — the request is self-contained and the ownership of the
+ * work stays with you.
+ *
+ * THREE THINGS TO READ CORRECTLY, because getting them wrong turns a careful
+ * answer into a false one:
+ *  1. A pool with a `shortfall` of kind `search-failed` was NOT answered. The
+ *     other pools in the same response were. Never read that empty pool as
+ *     "nothing matched".
+ *  2. `not_evaluated` and `missing` are not `failed`. The first means the engine
+ *     did not check the criterion at the tier that ran; the second means the
+ *     material holds no accepted value for it. Only `failed` means a value
+ *     exists and does not satisfy the ask.
+ *  3. `eligible: false` does not mean "bad". It means this candidate cannot be
+ *     placed automatically — read `flags` for which of the reasons applies.
+ *
+ * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
+ * so a new server value still type-checks; objects are read structurally.
+ */
+import type { VariantId } from "./identifiers.js";
+import type { OpenEnum } from "./types.js";
+/**
+ * One requirement or preference. Request-side, so this is a STRICT union.
+ * `attribute` asks for a canonical term, `attribute-presence` merely that the
+ * attribute is recorded, `attribute-numeric` a one-sided bound. `unresolved`
+ * carries brief language nothing bound to — it is never a filter and never
+ * blamed for a coverage shortfall.
+ */
+export type SlotPoolCriterion = {
+    kind: "attribute";
+    attributeId: string;
+    term: string;
+    raw: string;
+} | {
+    kind: "attribute-presence";
+    attributeId: string;
+    raw: string;
+} | {
+    kind: "attribute-numeric";
+    attributeId: string;
+    comparator: "at-least" | "at-most";
+    value: number;
+    unit?: string;
+    raw: string;
+} | {
+    kind: "unresolved";
+    raw: string;
+    suggestion?: {
+        attributeId: string;
+        term?: string;
+    };
+    coverageNote?: string;
+};
+/** A colour cue for a slot. Colours rerank within the retrieved set; they never admit. */
+export interface SlotPoolColourCue {
+    /** `#rrggbb`. */
+    hex: string;
+    name?: string;
+}
+/**
+ * What to do with a candidate the catalogue no longer lists. Neither value ever
+ * marks such a candidate eligible — the policy decides only whether it is
+ * returned at all.
+ */
+export type SlotPoolAvailabilityPolicy = "flag-unavailable" | "exclude-unavailable";
+/** One slot of work. Self-contained: nothing in it identifies a project. */
+export interface SlotPoolTask {
+    /**
+     * YOUR key for this task, opaque to MaterialGraph and returned verbatim on the
+     * matching pool. This is how you correlate 24 results; it is never parsed,
+     * normalised or reused as a server id. Must be unique within a request.
+     */
+    taskKey: string;
+    /**
+     * The catalog category. OMITTING IT yields an empty pool with a `no-category`
+     * shortfall — category is the only cross-kind gate, and retrieval will not
+     * rank an ungated corpus.
+     */
+    category?: string;
+    /** A short VISUAL description of the material wanted — not a keyword list. */
+    intent?: string;
+    required?: SlotPoolCriterion[];
+    preferred?: SlotPoolCriterion[];
+    colours?: SlotPoolColourCue[];
+    /** Rank this task around an already-chosen variant. Ids are opaque tokens. */
+    anchorSeed?: {
+        variantId: VariantId;
+    };
+    exclude?: {
+        variantIds?: VariantId[];
+        brandSlugs?: string[];
+    };
+    availability?: SlotPoolAvailabilityPolicy;
+    /** Candidates returned for this task. Max 48, default 12. */
+    limit?: number;
+}
+/** Body for `POST /api/v1/schemes/pools` ({@link MaterialGraphClient.slotPools}). */
+export interface SlotPoolsRequest {
+    /** Up to 24 tasks. Each is independent: one failing costs that one. */
+    tasks: SlotPoolTask[];
+    /**
+     * Include the co-specification evidence among the returned candidates
+     * (default true). One bounded read — never one request per candidate.
+     */
+    coSpecification?: boolean;
+}
+/** The six live verdict states, plus the two legacy tokens older rows carry. */
+export type SlotPoolVerdictState = OpenEnum<"matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated">;
+/** One cell of a candidate's report card against one criterion. */
+export interface SlotPoolVerdictCell {
+    attributeId: string;
+    state: SlotPoolVerdictState;
+    strength: OpenEnum<"required" | "preferred">;
+    baseline: {
+        kind: "term";
+        term: string;
+    } | {
+        kind: "presence";
+    } | {
+        kind: "seed";
+        variantId: VariantId;
+    } | {
+        kind: "image";
+        source: OpenEnum<"variant" | "vector">;
+        variantId: VariantId | null;
+    };
+    /** The candidate's OWN accepted value, or null when it holds none. */
+    value: string | null;
+    deviation: {
+        direction: OpenEnum<"above" | "below" | "other">;
+        delta: number | null;
+        unit: string | null;
+        label: string;
+    } | null;
+    confidence: number | null;
+    /**
+     * WHERE the value came from — it ranks the SOURCE, not the accuracy. It says
+     * nothing about whether the value is right.
+     */
+    sourceBasis: string | null;
+    trustGap: OpenEnum<"below_confidence" | "basis_unmet" | "proposed"> | null;
+}
+/** Why a candidate is labelled. An eligible candidate carries none of these. */
+export type SlotPoolFlag = OpenEnum<"below-floor" | "required-not-applied" | "discontinued" | "superseded" | "unverified-value">;
+export type SlotPoolAvailability = OpenEnum<"available" | "discontinued" | "superseded" | "unknown">;
+/** The declared successor of a withdrawn material, one hop only. */
+export interface SlotPoolSuccessor {
+    variantId: VariantId;
+    brandSlug: string;
+    productId: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    availability: SlotPoolAvailability;
+}
+/**
+ * The features a composer scores on. Colours are EXTRACTED FROM PRODUCT IMAGERY
+ * — visual likeness, never a declared colour specification. An empty `palette`
+ * or `attributes` means nothing is on record, never that the material has none.
+ */
+export interface SlotPoolCandidateFeatures {
+    colour: {
+        dominantHex: string | null;
+        hsl: {
+            h: number;
+            s: number;
+            l: number;
+        } | null;
+        oklab: {
+            l: number;
+            a: number;
+            b: number;
+        } | null;
+        chroma: number | null;
+        vibrancy: number | null;
+        sourceBasis?: string;
+    };
+    palette: {
+        hex: string;
+        proportion: number;
+        name?: string | null;
+        oklab?: {
+            l: number;
+            a: number;
+            b: number;
+        };
+    }[];
+    attributes: {
+        attributeId: string;
+        term: string;
+    }[];
+    dimensions: Record<string, unknown>[] | null;
+}
+export interface SlotPoolCandidate {
+    variantId: VariantId;
+    productId: string;
+    brandSlug: string;
+    brand: string;
+    product: string;
+    variant: string;
+    category: string | null;
+    materialBankId: string | null;
+    imageUrl: string | null;
+    availability: SlotPoolAvailability;
+    supersededBy: SlotPoolSuccessor | null;
+    /**
+     * True only when every required criterion was applied, the catalogue still
+     * lists the material, and no exclusion touched it. Anything else needs a
+     * human decision — read `flags` for which reason.
+     */
+    eligible: boolean;
+    flags: SlotPoolFlag[];
+    score: {
+        /** Normalised to [0,1] against the best score on THIS pool's page. */
+        retrieval: number;
+        /** `unverified` + `not_evaluated` cells. A soft penalty, not a failure count. */
+        unknownCount: number;
+        verdictCounts: {
+            matched: number;
+            deviated: number;
+            failed: number;
+            unverified: number;
+            missing: number;
+            notEvaluated: number;
+        };
+    };
+    verdict: {
+        cells: SlotPoolVerdictCell[];
+        grade: OpenEnum<"meets_all" | "close" | "hard_no">;
+        minConfidence: number | null;
+    };
+    features: SlotPoolCandidateFeatures;
+}
+/**
+ * Why a pool is short. Four different facts, and none of them is "nothing in
+ * the catalogue matches your brief".
+ */
+export type SlotPoolShortfall = {
+    kind: "no-category";
+} | {
+    kind: "category-coverage";
+    category: string;
+    attributeIds: string[];
+    gaps?: ({
+        level: "attribute";
+        attributeId: string;
+    } | {
+        level: "value";
+        attributeId: string;
+        term: string;
+    })[];
+} | {
+    kind: "search-failed";
+    detail: string;
+} | {
+    kind: "no-match";
+    tier: string;
+    consideredCount: number;
+};
+export interface SlotPool {
+    /** Your own key, verbatim. */
+    taskKey: string;
+    category: string | null;
+    /** The relaxation rung the returned candidates were drawn at. */
+    retrievalTier: OpenEnum<"strict" | "presence" | "category-only">;
+    /**
+     * HOW the candidates were retrieved. DERIVED from the retrieval plan and the
+     * pool's receipt — MaterialGraph does not report an arm per candidate.
+     *
+     * It is constant across the relaxation rungs, so it cannot tell you how far
+     * the ladder went. `retrievalTier` beside it names the rung the pool settled
+     * on: the arm says how, the tier says how strictly.
+     */
+    arm: OpenEnum<"visual-text" | "image-similarity" | "none">;
+    candidates: SlotPoolCandidate[];
+    /** How much retrieval scored before this task's own `limit` trimmed the page. */
+    consideredCount: number;
+    returnedCount: number;
+    excludedCount: number;
+    unavailableDroppedCount: number;
+    /**
+     * The criteria nothing on this page could be graded on — a statement about
+     * catalogue COVERAGE, never about the candidates.
+     */
+    unknownCoverage: {
+        evaluatedCriteria: number;
+        /** Every returned candidate graded `not_evaluated` on these. */
+        uncheckedCriteria: string[];
+        /** Every returned candidate graded `missing` on these. */
+        unheldCriteria: string[];
+    };
+    shortfall: SlotPoolShortfall | null;
+    seededFrom: {
+        variantId: VariantId;
+    } | null;
+    warnings: string[];
+}
+/**
+ * The sparse pairing graph among the returned candidates. Each unordered pair
+ * appears ONCE and the relation is symmetric. An empty `edges` under a null
+ * `datasetSessionId` means the dataset is absent, NOT that these materials are
+ * never specified together.
+ */
+export interface SlotPoolCoSpecification {
+    edges: {
+        from: VariantId;
+        to: VariantId;
+        projectCount: number;
+    }[];
+    coverage: {
+        candidateCount: number;
+        coveredCount: number;
+        truncated: boolean;
+        datasetSessionId: string | null;
+        window: string;
+        signal: string;
+    };
+}
+/** The `200` body from `POST /api/v1/schemes/pools`. */
+export interface SlotPoolsResponse {
+    versions: {
+        contract: string;
+        retrieval: string;
+        evaluator: string;
+        dataset: {
+            coSpecificationSessionId: string | null;
+        };
+    };
+    /** One pool per task, in request order. Correlate by `taskKey`, not by index. */
+    pools: SlotPool[];
+    coSpecification: SlotPoolCoSpecification | null;
+    summary: {
+        tasks: number;
+        eligibleCandidates: number;
+        flaggedCandidates: number;
+        tasksWithEligibleCandidates: number;
+        tasksWithoutEligibleCandidates: number;
+        /** Non-zero means some tasks were NOT answered; their pools say so. */
+        searchFailed: number;
+        noCategory: number;
+        categoryCoverage: number;
+        noMatch: number;
+    };
+    /**
+     * CALL VOLUME — how many of each bounded operation the request performed.
+     *
+     * Never a cost or token figure. Slot retrieval is database and embedding work
+     * and does not go through the model-call path that carries token and spend
+     * accounting, so no such figure exists for it. Do not render these as usage
+     * or spend.
+     */
+    calls: {
+        searchesRun: number;
+        searchesFailed: number;
+        candidatesConsidered: number;
+        candidatesReturned: number;
+        hydrationBatches: number;
+        coSpecificationQueries: number;
+    };
+    warnings: string[];
+}

package/slot-pool-types.js

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

package/source-material-validation.d.ts

@@ -1,3 +1,7 @@
-import type { SourceMaterialBatchDetail } from "./run-types.js";
+import type { PostSourceMaterialCommentResult, SourceMaterialBatchDetail, SourceMaterialCommentThread } from "./run-types.js";
 /** Validate a batch-detail body, returning it typed, or throw explaining why. */
 export declare function checkSourceMaterialBatchDetail(value: unknown, batchId: string): SourceMaterialBatchDetail;
+/** Validate a comment-thread body, returning it typed, or throw explaining why. */
+export declare function checkSourceMaterialCommentThread(value: unknown, sourceId: string): SourceMaterialCommentThread;
+/** Validate a posted-comment body, returning it typed, or throw explaining why. */
+export declare function checkPostSourceMaterialCommentResult(value: unknown, sourceId: string): PostSourceMaterialCommentResult;

package/source-material-validation.js

@@ -11,12 +11,16 @@
  * nothing at run time. This is the run-time half, and it must ACCEPT and REJECT
  * exactly what the schema does — pinned by `source-material-parity.test.ts`.
  *
- * TWO CONTRACT PROPERTIES IT ENFORCES, both easy to lose in a refactor:
+ * THREE CONTRACT PROPERTIES IT ENFORCES, each easy to lose in a refactor:
  *   1. `analyses` is REQUIRED and an array on every file. `[]` means "nothing
  *      computed yet"; an absent field is a broken response, not an empty one.
  *      Preprocessing is manual today and automatic later — only the trigger
  *      changes, never this contract.
- *   2. `result` is a JSON record all the way down (`z.json()`), not `unknown`.
+ *   2. `comments` is REQUIRED and an array on every file, and every root comment
+ *      carries a REQUIRED `replies` array. Same distinction: "nobody said
+ *      anything about this file" is a state the client draws, and an absent
+ *      field is a malformed response.
+ *   3. `result` is a JSON record all the way down (`z.json()`), not `unknown`.
  *      See `requireJsonValue` for why the schema is that strict and why this
  *      mirror cannot actually fire over the wire.
  *
@@ -30,7 +34,7 @@
  * permanent contract, and promoting it later is additive.
  */
 import { MaterialGraphError } from "./errors.js";
-import { requireArray, requireEnum, requireSafeInteger, requireJsonRecord, requireNonEmptyString, requireRecord, requireString, } from "./validation.js";
+import { requireArray, requireBoolean, requireEnum, requireSafeInteger, requireJsonRecord, requireNonEmptyString, requireNullableTrimmedBoundedString, requireRecord, requireString, requireTrimmedBoundedString, } from "./validation.js";
 /** `sourceImageAnalysisKindSchema` members, verbatim. */
 const ANALYSIS_KINDS = ["scene_match"];
 /** `sourceImageAnalysisStatusSchema` members, verbatim. */
@@ -61,12 +65,67 @@ function checkAnalysis(value, what, fail) {
         analysedAt: requireNonEmptyString(record.analysedAt, `${what}.analysedAt`, fail),
     };
 }
+/** `sourceMaterialCommentAuthorSchema`'s `attribution` members, verbatim. */
+const COMMENT_ATTRIBUTIONS = ["reported"];
+/** The canonical cap on both author fields: `.trim().min(1).max(160)`. */
+const AUTHOR_FIELD_MAX = 160;
+/**
+ * A reply, and the shared half of a root comment.
+ *
+ * `body`, `commentId` and `createdAt` are `.min(1)` canonically — fields this
+ * endpoint introduces, where an empty value carries nothing a client could
+ * render. `author.organisation` is nullable, NOT optional: `null` is the answer
+ * for a note with no organisation, and an absent key is a malformed body.
+ *
+ * The author fields are `.trim().min(1).max(160)` canonically and are mirrored
+ * as exactly that. A plain non-empty check — which is what this used to do —
+ * disagreed with the schema in both directions: it accepted `"   "`, which the
+ * schema rejects once trimmed, and accepted a name of any length, which the
+ * schema caps. A validator that is looser than the contract is a validator that
+ * lets the two drift without anything failing.
+ */
+function checkCommentBase(record, what, fail) {
+    const author = requireRecord(record.author, `${what}.author`, fail);
+    const recordedBy = requireRecord(record.recordedBy, `${what}.recordedBy`, fail);
+    return {
+        commentId: requireNonEmptyString(record.commentId, `${what}.commentId`, fail),
+        author: {
+            name: requireTrimmedBoundedString(author.name, `${what}.author.name`, AUTHOR_FIELD_MAX, fail),
+            organisation: requireNullableTrimmedBoundedString(author.organisation, `${what}.author.organisation`, AUTHOR_FIELD_MAX, fail),
+            // Closed here, matching the canonical `z.literal("reported")`, while the
+            // published type is `OpenEnum` so a newer server value keeps
+            // type-checking — the same split the analysis enums make.
+            attribution: requireEnum(author.attribution, COMMENT_ATTRIBUTIONS, `${what}.author.attribution`, fail),
+        },
+        recordedBy: {
+            principalId: requireNonEmptyString(recordedBy.principalId, `${what}.recordedBy.principalId`, fail),
+        },
+        body: requireNonEmptyString(record.body, `${what}.body`, fail),
+        createdAt: requireNonEmptyString(record.createdAt, `${what}.createdAt`, fail),
+    };
+}
+function checkComment(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    // Same reasoning as `analyses`: no `.default([])` canonically, so an absent
+    // `replies` is malformed rather than empty.
+    const replies = requireArray(record.replies, `${what}.replies`, fail);
+    return {
+        ...checkCommentBase(record, what, fail),
+        replies: replies.map((reply, index) => checkCommentBase(requireRecord(reply, `${what}.replies[${index}]`, fail), `${what}.replies[${index}]`, fail)),
+    };
+}
 function checkFile(value, what, fail) {
     const record = requireRecord(value, what, fail);
     // NOT `requireDefaultedArray`: the schema has no `.default([])`, so an absent
     // `analyses` is a malformed body rather than an empty one. Keeping that
-    // distinction is the whole point of the always-an-array contract.
+    // distinction is the whole point of the always-an-array contract. `comments`
+    // is required for the same reason: "nobody has said anything" and "the server
+    // forgot to tell you" are different answers.
     const analyses = requireArray(record.analyses, `${what}.analyses`, fail);
+    const comments = requireArray(record.comments, `${what}.comments`, fail);
+    // Required, not defaulted: "you are seeing the whole thread" is a claim the
+    // server makes or does not, never one a client should infer from a length.
+    const commentsTruncated = requireBoolean(record.commentsTruncated, `${what}.commentsTruncated`, fail);
     // `requireString`, NOT `requireNonEmptyString`, for the fields this endpoint
     // INHERITS from the shared source-material contract (`sourceId`, `sha256`,
     // `url` — plus `batchId`/`createdAt` below). Those are plain `z.string()`
@@ -96,6 +155,8 @@ function checkFile(value, what, fail) {
             : requireSafeInteger(record.pages, `${what}.pages`, fail),
         url: requireString(record.url, `${what}.url`, fail),
         analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
+        comments: comments.map((comment, index) => checkComment(comment, `${what}.comments[${index}]`, fail)),
+        commentsTruncated,
     };
 }
 /** Validate a batch-detail body, returning it typed, or throw explaining why. */
@@ -109,3 +170,49 @@ export function checkSourceMaterialBatchDetail(value, batchId) {
         sources: sources.map((file, index) => checkFile(file, `body.sources[${index}]`, fail)),
     };
 }
+function commentsFailure(verb, sourceId) {
+    return (reason) => MaterialGraphError.unexpected(`${verb} .../sources/${sourceId}/comments returned a malformed body: ${reason}`);
+}
+/** Validate a comment-thread body, returning it typed, or throw explaining why. */
+export function checkSourceMaterialCommentThread(value, sourceId) {
+    const fail = commentsFailure("GET", sourceId);
+    const record = requireRecord(value, "body", fail);
+    const comments = requireArray(record.comments, "body.comments", fail);
+    return {
+        sourceId: requireString(record.sourceId, "body.sourceId", fail),
+        comments: comments.map((comment, index) => checkComment(comment, `body.comments[${index}]`, fail)),
+        truncated: requireBoolean(record.truncated, "body.truncated", fail),
+    };
+}
+/** `storedSourceMaterialCommentSchema`'s discriminator members, verbatim. */
+const STORED_COMMENT_KINDS = ["root", "reply"];
+/**
+ * Validate a stored comment, following its `kind` discriminator.
+ *
+ * The two branches are checked as the two DIFFERENT shapes they are: a root must
+ * carry `replies`, a reply must carry `parentCommentId` and must not be assumed
+ * to carry `replies` at all. Validating both as the root shape is exactly the
+ * defect this discriminated union was added to fix, and a mirror that did it
+ * would put the lie back on the client side.
+ */
+function checkStoredComment(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    const kind = requireEnum(record.kind, STORED_COMMENT_KINDS, `${what}.kind`, fail);
+    if (kind === "reply") {
+        return {
+            kind: "reply",
+            ...checkCommentBase(record, what, fail),
+            parentCommentId: requireNonEmptyString(record.parentCommentId, `${what}.parentCommentId`, fail),
+        };
+    }
+    return { kind: "root", ...checkComment(record, what, fail) };
+}
+/** Validate a posted-comment body, returning it typed, or throw explaining why. */
+export function checkPostSourceMaterialCommentResult(value, sourceId) {
+    const fail = commentsFailure("POST", sourceId);
+    const record = requireRecord(value, "body", fail);
+    return {
+        sourceId: requireString(record.sourceId, "body.sourceId", fail),
+        comment: checkStoredComment(record.comment, "body.comment", fail),
+    };
+}