@instruments/materialgraph 0.29.0 → 0.31.0

package/material-composition-types.d.ts

@@ -1,403 +0,0 @@
-/**
- * Hand-mirrored wire types for MATERIAL composition — what a product is made
- * of (`GET /api/v1/materials/{variantId}/composition`, operation
- * `get_material_composition`, and `GET /api/v1/composition/report`, operation
- * `get_composition_report`; MG-1969).
- *
- * Composition means only this. It is unrelated to `./slot-pool-types.ts`,
- * the candidate pools a scheme composer outside MaterialGraph reads.
- *
- * Like the rest of the SDK these interfaces carry NO runtime dependency on any
- * `@materialgraph/*` package; they mirror the `VariantComposition` and
- * `CompositionCorpusSummary` shapes in `apps/web/public/openapi.yaml`.
- *
- * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
- * so a new server value still type-checks; objects are read structurally. The
- * one exception is {@link VariantCompositionAbsence}, which is closed —
- * see below.
- */
-import type { VariantId } from "./identifiers.js";
-import type { OpenEnum } from "./types.js";
-/**
- * Why no parse stands behind a material. CLOSED on purpose: a consumer must
- * branch on every arm, and widening it would let a new reason fall through a
- * branch that reads "one of these two, so it must be the other".
- *
- * - `no_material_bank_sku` — the variant was never a Material Bank SKU, so
- *   there is no catalogue row anyone could have parsed.
- * - `not_linked` — it has a SKU and the corpus has not reached it. A statement
- *   about MaterialGraph's coverage, never about the material.
- *
- * Neither is the same as a present parse whose `status` is `empty`: that is the
- * catalogue row saying it declared nothing, which is knowledge.
- */
-export type VariantCompositionAbsence = "no_material_bank_sku" | "not_linked";
-/** `failed_closed` means the parser refused rather than guessed. */
-export type CompositionParseStatus = OpenEnum<"parsed" | "empty" | "failed_closed">;
-/** One document or catalogue column the record's facts are taken from. */
-export type CompositionSource = {
-    id: string;
-    kind: OpenEnum<"epd" | "hpd" | "technical_document" | "manufacturer" | "reseller" | "test_report" | "catalogue_field" | "inference" | "other">;
-    /** A URL, a document name, or the catalogue column name. */
-    locator: string;
-    retrievedAt?: string;
-    /** The source's wording, verbatim. Never corrected or completed. */
-    statement?: string;
-    title?: string;
-};
-/**
- * A percentage as the source gives it, or one of the four ways a source can
- * name a node and still withhold the number. `undisclosed` holds its place in
- * the sum; `alternate` sits outside it.
- */
-export type CompositionAmount = {
-    kind: "exact";
-    value: number;
-} | {
-    kind: "range";
-    max: number;
-    min: number;
-} | {
-    kind: "bound";
-    operator: OpenEnum<"at_most" | "at_least" | "less_than" | "greater_than">;
-    value: number;
-} | {
-    kind: "unknown";
-} | {
-    kind: "undisclosed";
-    reason: OpenEnum<"trade_secret" | "not_provided">;
-} | {
-    kind: "conditionally_present";
-    max: number;
-} | {
-    kind: "band";
-    band: string;
-    version: string;
-    vocabulary: string;
-} | {
-    kind: "alternate";
-} | {
-    kind: string;
-};
-/** How much of its parent, or of the whole product, a node is. */
-export type CompositionShare = {
-    amount: CompositionAmount;
-    /** What the percentage measures, only as the source says it. Never converted. */
-    basis: OpenEnum<"mass" | "volume" | "fibre_mass" | "area" | "count" | "thickness" | "unspecified">;
-    of: OpenEnum<"parent" | "product">;
-    source: string;
-};
-/** An absolute figure the source states, in its own unit. Never in the sum. */
-export type CompositionQuantity = {
-    amount: {
-        kind: "exact";
-        value: number;
-    } | {
-        kind: "range";
-        max: number;
-        min: number;
-    } | {
-        kind: "bound";
-        operator: OpenEnum<"at_most" | "at_least" | "less_than" | "greater_than">;
-        value: number;
-    } | {
-        kind: string;
-    };
-    /** The figure and unit as the source writes them. */
-    raw: string;
-    unit: OpenEnum<"mm" | "in" | "mil" | "gauge" | "oz_yd2" | "g_m2" | "kg" | "kg_m3" | "pcf" | "dtex" | "denier" | "ply">;
-};
-/**
- * Which substance a component is. `resolution` is the field to read before
- * trusting `term`: `identified` is the only arm carrying a dictionary id that
- * means what the source said.
- */
-export type CompositionTermRef = {
-    /** The source's own words, verbatim. */
-    raw: string;
-    resolution: OpenEnum<"identified" | "proprietary" | "withheld" | "unresolved">;
-    source?: string;
-    term?: string;
-};
-/** Dictionary ids qualifying a term without changing it. */
-export type CompositionModifiers = {
-    brand?: string;
-    cut?: string;
-    grade?: string;
-    origin?: string;
-    process?: string[];
-    provenance?: string;
-    treatment?: string[];
-};
-/** A statement about a node that is not a share. Claims never enter the sum. */
-export type CompositionClaim = {
-    amount?: CompositionAmount;
-    kind: OpenEnum<"free_of" | "contains" | "recyclable" | "renewable" | "bio_based" | "biodegradable" | "compostable" | "certified" | "other">;
-    /** The claim's wording, verbatim. */
-    raw: string;
-    source: string;
-    term?: string;
-};
-/** The level above which the source says every substance is listed. */
-export type CompositionThreshold = {
-    raw: string;
-    regime: OpenEnum<"100_ppm" | "1000_ppm" | "ghs_sds" | "other">;
-    scope: OpenEnum<"product" | "material">;
-    source: string;
-};
-/**
- * Whether the source presents a node's children as exhaustive. `partial` and
- * `unspecified` are both statements about the SOURCE; neither licenses adding
- * a child to make a list add up.
- */
-export type CompositionCoverage = {
-    claim: OpenEnum<"complete" | "partial" | "unspecified">;
-    source?: string;
-    threshold?: CompositionThreshold;
-};
-/** Why the unstated part of a composition is unstated. */
-export type CompositionRemainder = {
-    kind: "legally_omitted";
-    regime: OpenEnum<"eu_1007_2011" | "us_16_cfr_303">;
-    rule: string;
-    source: string;
-} | {
-    kind: "undisclosed";
-    reason: OpenEnum<"trade_secret" | "not_provided">;
-    source: string;
-} | {
-    kind: string;
-};
-/** One named substance with its share. Never an unstated remainder. */
-export type CompositionComponent = {
-    claims: CompositionClaim[];
-    /** "Of which" subsets of this component; their shares are of it. */
-    components?: CompositionComponent[];
-    id: string;
-    identity: CompositionTermRef;
-    modifiers: CompositionModifiers;
-    quantity?: CompositionQuantity;
-    /** What the substance does inside its part, only where the source says. */
-    role?: string;
-    share: CompositionShare;
-    source: string;
-};
-/** A layer or piece of the product. Sibling parts are co-present and sum. */
-export type CompositionPart = {
-    claims: CompositionClaim[];
-    components: CompositionComponent[];
-    construction: string[];
-    coverage: CompositionCoverage;
-    id: string;
-    /** The part's name as the source writes it. */
-    label?: string;
-    /** Alternatives the buyer chooses between; options never sum with siblings. */
-    options?: CompositionPart[];
-    parts?: CompositionPart[];
-    /** Stacking order among siblings: 0 is the top or outer face. */
-    position: number;
-    quantity?: CompositionQuantity;
-    remainder?: CompositionRemainder;
-    role?: string;
-    share: CompositionShare;
-    source: string;
-};
-/** The composition of one product, as the cited sources state it. */
-export type CompositionRecord = {
-    claims: CompositionClaim[];
-    /** The whole product's own inventory; never summed with `parts`. */
-    components: CompositionComponent[];
-    construction: string[];
-    coverage: CompositionCoverage;
-    id: string;
-    name: string;
-    /** Alternatives the buyer chooses between, each a full record. */
-    options?: CompositionRecord[];
-    parts: CompositionPart[];
-    primarySource?: string;
-    remainder?: CompositionRemainder;
-    sources: CompositionSource[];
-};
-/**
- * The record flattened to the `composition_weighted` attribute value.
- *
- * `basis: "tokens_only"` says the PROPORTIONS are unknown, never that the
- * components are, and every entry then carries a component with no `fraction`.
- * An absent `fraction` is an unknown share; `0` is a declared none.
- */
-export type CompositionWeightedValue = {
-    basis: OpenEnum<"declared_percent" | "single_material" | "tokens_only">;
-    components: {
-        /** A `composition_component` dictionary term id. */
-        component: string;
-        /** 0 to 1, never a percentage. */
-        fraction?: number;
-        tolerance?: number;
-    }[];
-    [key: string]: unknown;
-};
-/** What meeting a need lets a reader do with the record. */
-export type CompositionUnlock = OpenEnum<"specify" | "substitute" | "compare">;
-/**
- * Why a record was not measured against a bar. Null exactly when
- * `completeness` is present. CLOSED, like {@link VariantCompositionAbsence}:
- * a consumer must branch on every arm.
- *
- * - `no_record` — nothing was parsed, so there is nothing to measure.
- * - `no_product_type` — a record exists, but the tuple resolved to no product
- *   type, so there is no bar to pick.
- * - `no_bar_set` — both exist and MaterialGraph has authored no requirement
- *   for that product type. A gap in OUR registry. Rendering it as an unscored
- *   record reads as a fault in the maker's data.
- */
-export type CompositionCompletenessAbsence = "no_record" | "no_product_type" | "no_bar_set";
-/**
- * A record measured against its product type's authored bar, AT READ TIME.
- * Absent (rather than zeroed) when it could not be measured; read
- * `completenessAbsent` for which of the three reasons applies.
- */
-export type CompositionCompleteness = {
-    met: number;
-    needs: {
-        id: string;
-        label: string;
-        met: boolean;
-        unlocks: CompositionUnlock[];
-    }[];
-    productTypeId: string;
-    /** met / total, 0 to 1, to three decimal places. */
-    share: number;
-    total: number;
-    /** Open when every need tagged with it is met. */
-    unlocks: {
-        compare: boolean;
-        specify: boolean;
-        substitute: boolean;
-    };
-};
-/** The stored parse, with the contract it was written under. */
-export type VariantCompositionParse = {
-    parseKey: string;
-    status: CompositionParseStatus;
-    /** Null when the parse stored none; `empty` and `failed_closed` always do. */
-    record: CompositionRecord | null;
-    projection: CompositionWeightedValue | null;
-    /** Unresolved wording, or the error text when the parse failed closed. */
-    unresolved: {
-        raw: string;
-        source: string;
-    }[];
-    modelId: string;
-    schemaVersion: string;
-    dictionaryVersion: string;
-    parsedAt: string;
-};
-/**
- * What a material is made of, traced to the catalogue columns it came from.
- *
- * READ `absent` FIRST. When it is set there is no parse, and its value says
- * why. When it is null there is a parse, and `parse.status` may still be
- * `empty` — the catalogue row was read and declared nothing.
- *
- * `productType` is inferred for the TUPLE, which many products share, so it is
- * never a statement about this variant's own category.
- */
-export type VariantComposition = {
-    variantId: VariantId;
-    materialBankSku: string | null;
-    /** The verbatim catalogue cells, keyed by column name. */
-    catalogue: {
-        tuple: Record<string, string>;
-    } | null;
-    parse: VariantCompositionParse | null;
-    productType: {
-        id: string;
-        share: number | null;
-    } | null;
-    completeness: CompositionCompleteness | null;
-    /** Null exactly when `completeness` is present. */
-    completenessAbsent: CompositionCompletenessAbsence | null;
-    absent: VariantCompositionAbsence | null;
-};
-/** A count in both currencies. The Live SKU figure is the answer. */
-export type CompositionCorpusWeight = {
-    tuples: number;
-    liveSkus: number;
-};
-export type CompositionCorpusShare = CompositionCorpusWeight & {
-    liveSkuShare: number | null;
-    tupleShare: number | null;
-};
-export type CompositionCorpusNeedCoverage = {
-    id: string;
-    label: string;
-    unlocks: CompositionUnlock[];
-    /** Share of the type's measured Live SKUs whose record meets this need. */
-    liveSkuShare: number | null;
-    tupleShare: number | null;
-};
-export type CompositionCorpusTypeCoverage = {
-    productTypeId: string;
-    measured: CompositionCorpusWeight;
-    failedClosed: CompositionCorpusWeight;
-    empty: CompositionCorpusWeight;
-    needs: CompositionCorpusNeedCoverage[];
-    /**
-     * Share of the type's measured rows meeting EVERY need — the whole bar.
-     * Not the same as an unlock being open, which only requires the needs
-     * tagged with that unlock. Draw a completeness bar from this.
-     */
-    complete: {
-        liveSkuShare: number | null;
-        tupleShare: number | null;
-    };
-    unlocks: {
-        compare: number | null;
-        specify: number | null;
-        substitute: number | null;
-    };
-    /** The need the most Live SKUs are missing, or null when every need is met. */
-    mostMissedNeed: {
-        id: string;
-        label: string;
-        liveSkus: number;
-    } | null;
-};
-/**
- * How far the material composition corpus has got.
- *
- * `authoringQueue` lists product types SKUs were assigned to but no
- * requirement has been written for. They have NO BAR SET, which is why they
- * are listed apart rather than scored zero.
- */
-export type CompositionCorpusSummary = {
-    completeness: {
-        authoringQueue: (CompositionCorpusWeight & {
-            productTypeId: string;
-        })[];
-        byProductType: CompositionCorpusTypeCoverage[];
-        unknownProductType: CompositionCorpusWeight;
-    };
-    coverage: {
-        failedClosed: CompositionCorpusWeight;
-        /** Tuples with no text to parse at all; not a parser failure. */
-        noValue: CompositionCorpusWeight;
-        resolvable: CompositionCorpusShare;
-        validity: CompositionCorpusShare;
-        withValue: CompositionCorpusWeight;
-    };
-    dictionaryVersion: string;
-    /** The corpus's own list-price spend, never a per-request figure. */
-    tokens: {
-        costUsd: {
-            input: number;
-            output: number;
-            total: number;
-        };
-        inputTokens: number;
-        outputTokens: number;
-    };
-    parses: number;
-    linkedSkus: number;
-    generatedAt: string;
-};

package/material-composition-types.js

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

package/source-material-validation.d.ts

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

package/source-material-validation.js

@@ -1,214 +0,0 @@
-/**
- * The runtime validator for `GET /api/v1/source-material/{batchId}` — the
- * hand-rolled, zero-runtime-dependency mirror of
- * `sourceMaterialBatchDetailSchema` and its transitive closure
- * (`sourceMaterialBatchDetailFileSchema`, `sourceImageAnalysisSchema`,
- * `sourceImageAnalysisResultSchema`) in
- * `packages/sources/src/source-material/contract.ts`.
- *
- * WHY IT EXISTS. `contract-parity.test.ts` proves the SDK's STATIC types match
- * the canonical schemas; that is a compile-time proof about shapes and validates
- * 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`.
- *
- * 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. `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.
- *
- * ENUMS ARE CLOSED here, matching the canonical `z.enum(…)` members, while the
- * published types are `OpenEnum` so a newer server value keeps type-checking.
- * The validator follows the SCHEMA: the type stays wider than what is proven,
- * which is imprecise but never a lie — the same choice
- * `search-result-validation.ts` makes for `basis`.
- *
- * Package-internal (not re-exported from `index.ts`): a published symbol is a
- * permanent contract, and promoting it later is additive.
- */
-import { MaterialGraphError } from "./errors.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. */
-const ANALYSIS_STATUSES = ["ok", "failed"];
-/** `sourceMaterialRoleSchema` members, verbatim. */
-const SOURCE_ROLES = [
-    "brief",
-    "reference_image",
-    "document",
-    "document_image",
-    "inspiration_image",
-    "unclassified",
-];
-const detailFailure = (batchId) => (reason) => MaterialGraphError.unexpected(`GET /api/v1/source-material/${batchId} returned a malformed body: ${reason}`);
-const checkAnalysis = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    // `model` and `analysedAt` ARE `.min(1)` canonically — fields this endpoint
-    // introduces, where an empty value is meaningless and `model` already cannot
-    // be written empty. Parity here is achieved by the schema being strict, never
-    // by this mirror freelancing past it.
-    return {
-        analysedAt: requireNonEmptyString(record.analysedAt, `${what}.analysedAt`, fail),
-        kind: requireEnum(record.kind, ANALYSIS_KINDS, `${what}.kind`, fail),
-        model: requireNonEmptyString(record.model, `${what}.model`, fail),
-        result: requireJsonRecord(record.result, `${what}.result`, fail),
-        status: requireEnum(record.status, ANALYSIS_STATUSES, `${what}.status`, 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.
- */
-const checkCommentBase = (record, what, fail) => {
-    const author = requireRecord(record.author, `${what}.author`, fail);
-    const recordedBy = requireRecord(record.recordedBy, `${what}.recordedBy`, fail);
-    return {
-        author: {
-            // 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),
-            name: requireTrimmedBoundedString(author.name, `${what}.author.name`, AUTHOR_FIELD_MAX, fail),
-            organisation: requireNullableTrimmedBoundedString(author.organisation, `${what}.author.organisation`, AUTHOR_FIELD_MAX, fail),
-        },
-        body: requireNonEmptyString(record.body, `${what}.body`, fail),
-        commentId: requireNonEmptyString(record.commentId, `${what}.commentId`, fail),
-        createdAt: requireNonEmptyString(record.createdAt, `${what}.createdAt`, fail),
-        recordedBy: {
-            principalId: requireNonEmptyString(recordedBy.principalId, `${what}.recordedBy.principalId`, fail),
-        },
-    };
-};
-const 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)),
-    };
-};
-const 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. `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()`
-    // there and shared with the upload path; a client that rejected `""` would
-    // refuse a response the server can legitimately produce, and tightening them
-    // is a change to a contract this endpoint does not own.
-    return {
-        analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
-        // `requireSafeInteger`, NOT `requireIntegerAtLeast(…, 0)`. Canonically these
-        // are a bare `z.number().int()` on the INHERITED
-        // `sourceMaterialFileReceiptSchema`, which carries no lower bound — so a
-        // negative is accepted there and must be accepted here.
-        //
-        // A negative `bytes` is nonsense and a negative `pages` more so, and this is
-        // still not the place to say so: a client validator holding an opinion the
-        // contract does not is how the two drift, and how a response the server may
-        // legitimately produce starts throwing at the boundary. Tightening those
-        // fields is a canonical change to a schema shared with the upload path, and
-        // belongs in its own ticket with this mirror following after.
-        bytes: requireSafeInteger(record.bytes, `${what}.bytes`, fail),
-        comments: comments.map((comment, index) => checkComment(comment, `${what}.comments[${index}]`, fail)),
-        commentsTruncated,
-        filename: requireString(record.filename, `${what}.filename`, fail),
-        mediaType: requireString(record.mediaType, `${what}.mediaType`, fail),
-        pages: record.pages === null
-            ? null
-            : requireSafeInteger(record.pages, `${what}.pages`, fail),
-        role: requireEnum(record.role, SOURCE_ROLES, `${what}.role`, fail),
-        sha256: requireString(record.sha256, `${what}.sha256`, fail),
-        sourceId: requireString(record.sourceId, `${what}.sourceId`, fail),
-        url: requireString(record.url, `${what}.url`, fail),
-    };
-};
-/** Validate a batch-detail body, returning it typed, or throw explaining why. */
-export const checkSourceMaterialBatchDetail = (value, batchId) => {
-    const fail = detailFailure(batchId);
-    const record = requireRecord(value, "body", fail);
-    const sources = requireArray(record.sources, "body.sources", fail);
-    return {
-        batchId: requireString(record.batchId, "body.batchId", fail),
-        createdAt: requireString(record.createdAt, "body.createdAt", fail),
-        sources: sources.map((file, index) => checkFile(file, `body.sources[${index}]`, fail)),
-    };
-};
-const commentsFailure = (verb, sourceId) => (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 const checkSourceMaterialCommentThread = (value, sourceId) => {
-    const fail = commentsFailure("GET", sourceId);
-    const record = requireRecord(value, "body", fail);
-    const comments = requireArray(record.comments, "body.comments", fail);
-    return {
-        comments: comments.map((comment, index) => checkComment(comment, `body.comments[${index}]`, fail)),
-        sourceId: requireString(record.sourceId, "body.sourceId", 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.
- */
-const 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 const checkPostSourceMaterialCommentResult = (value, sourceId) => {
-    const fail = commentsFailure("POST", sourceId);
-    const record = requireRecord(value, "body", fail);
-    return {
-        comment: checkStoredComment(record.comment, "body.comment", fail),
-        sourceId: requireString(record.sourceId, "body.sourceId", fail),
-    };
-};

package/spec-facet-types.d.ts

@@ -1,48 +0,0 @@
-export type SpecFacetValue = {
-    value: string;
-    variants: number;
-    brands: number;
-    label?: string;
-};
-/**
- * A NUMERIC facet's observed span and the coverage behind it.
- *
- * A range, not buckets — no bucketing scheme has been decided, and one invented
- * on the wire would be treated as canonical by everyone who read it. Both bounds
- * are INCLUSIVE, matching `specRange`.
- *
- * READ `variants` BEFORE TRUSTING A FILTER. It is how many variants carry a
- * value that parses as a number, i.e. how much of the corpus a range can reach;
- * a facet that exists says the attribute is queryable, not that it is populated.
- * `unparseableVariants` is the honesty companion: values recorded here that are
- * not numbers, which a range EXCLUDES rather than reading as zero.
- */
-export type SpecFacetRange = {
-    min: number;
-    max: number;
-    variants: number;
-    unparseableVariants: number;
-};
-export type SpecFacet = {
-    attributeId: string;
-    name: string;
-    isArray: boolean;
-    /**
-     * How this facet is queried. `token` — pick a value from `values` and send it
-     * as a `{field: attributeId, op: "in", values: [...]}` filter leaf.
-     * `numeric` — `values` is EMPTY and `range` carries the span; send inclusive
-     * bounds as `{field: attributeId, op: "gte"/"lte", value}` leaves instead.
-     */
-    kind: "token" | "numeric" | (string & {});
-    brands: number;
-    /** EMPTY for a `numeric` facet, which has no token vocabulary. */
-    values: SpecFacetValue[];
-    /** Present ONLY on a `numeric` facet. */
-    range?: SpecFacetRange;
-    description?: string;
-};
-export type SpecFacetsListResponse = {
-    mode: "facets";
-    count: number;
-    facets: SpecFacet[];
-};

package/spec-facet-types.js

@@ -1,7 +0,0 @@
-// ── Specification facets + attribute values ─────────────────────────────────
-//
-// Hand-maintained mirror of the `SpecificationFacet` OpenAPI schema (the source
-// of truth on the wire); the `sdk-openapi-parity` test gates this against the
-// generated spec. Split out of `types.ts` to keep that file under its growth
-// baseline; re-exported from `types.ts` so importers see no change.
-export {};