@instruments/materialgraph 0.29.0 → 0.30.0

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 {};

package/substitute-types.d.ts

@@ -1,102 +0,0 @@
-import type { BySpecVerdict } from "./by-spec-types.js";
-import type { VariantId } from "./identifiers.js";
-import type { MaterialSuccessor } from "./material-types.js";
-export type SubstituteSignatureFamily = "textile" | "tile" | "coating" | "lighting_electrical" | "acoustic" | "surface" | "furniture" | "sanitaryware" | "fittings" | "architectural_hardware";
-export type SubstituteSignatureCriterion = {
-    role: "primary_material" | "performance";
-    attributeId: string;
-    term: string;
-};
-export type AvailableSubstituteSignature = {
-    family: SubstituteSignatureFamily;
-    form: string;
-    criteria: [SubstituteSignatureCriterion, SubstituteSignatureCriterion];
-};
-export type UnsupportedSubstituteSignature = {
-    family: SubstituteSignatureFamily;
-    form: string;
-    reason: string;
-};
-export type InsufficientSubstituteSignature = {
-    family: SubstituteSignatureFamily;
-    form: string;
-    missingRoles: ("primary_material" | "performance")[];
-};
-export type FindSubstitutesOptions = {
-    excludeBrands?: string[];
-    diversityBoost?: number;
-    limit?: number;
-    cursor?: string;
-    includeSamplingArtifacts?: boolean;
-    includeUnavailable?: boolean;
-};
-export type SubstituteMatchedCriterion = {
-    attributeId: string;
-    confidence: number | null;
-    sourceBasis: string | null;
-};
-export type SubstituteResultItem = {
-    variantId: VariantId;
-    brandSlug: string;
-    brand: string;
-    product: string;
-    variant: string;
-    color: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    matched: SubstituteMatchedCriterion[];
-    minConfidence: number | null;
-    baseScore: number;
-    diversityAdjustment: number;
-    score: number;
-    verdict: BySpecVerdict;
-};
-export type AvailableSubstitutesResponse = {
-    status: "available";
-    signatureUsed: AvailableSubstituteSignature;
-    items: SubstituteResultItem[];
-    candidatePoolSize: number;
-    droppedUnavailable: number;
-    /**
-     * MG-1686, MG-1783. True when the candidate read hit the bounded pool ceiling,
-     * so more materials match the signature than were ranked. A cut pool is an
-     * even SAMPLE across the id keyspace rather than its lowest window, so the
-     * ranked set is representative of the match set without being all of it —
-     * treat the items as the best of a sample, never as the best that exist. A cut
-     * pool that produced NO items answers `inconclusive` instead, so `available`
-     * with an empty `items` always means a complete search that found nothing.
-     */
-    poolTruncated: boolean;
-    supersededBy: MaterialSuccessor | null;
-    nextCursor?: string;
-};
-/**
- * MG-1686. The search read a bounded window of the matches and nothing in it
- * reached the page, while more matches existed past the window. It is not an
- * answer of "nothing can replace this" — that answer is `available` with an
- * empty `items`. `reason` names what happened and the next move; follow
- * `nextCursor` when it is present.
- */
-export type InconclusiveSubstitutesResponse = {
-    status: "inconclusive";
-    signatureUsed: AvailableSubstituteSignature;
-    items: [];
-    candidatePoolSize: number;
-    droppedUnavailable: number;
-    reason: string;
-    supersededBy: MaterialSuccessor | null;
-    nextCursor?: string;
-};
-export type UnsupportedSubstitutesResponse = {
-    status: "unsupported";
-    signature: UnsupportedSubstituteSignature;
-    items: [];
-    supersededBy: MaterialSuccessor | null;
-};
-export type InsufficientSubstitutesResponse = {
-    status: "insufficient_signature";
-    signature: InsufficientSubstituteSignature;
-    items: [];
-    supersededBy: MaterialSuccessor | null;
-};
-export type FindSubstitutesResponse = AvailableSubstitutesResponse | InconclusiveSubstitutesResponse | UnsupportedSubstitutesResponse | InsufficientSubstitutesResponse;

package/substitute-types.js

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

package/suggest-types.d.ts

@@ -1,67 +0,0 @@
-/**
- * Entity typeahead (MG-654) — the hand-mirrored wire types for
- * `GET /api/v1/search/suggest`, plus the one query-shaping rule the endpoint
- * imposes.
- *
- * Split out of `types.ts` for the repository's source-file size budget, the same
- * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
- * `types.ts`, so importers see no difference.
- *
- * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
- * what answers a committed query; `mg.suggestColour()` covers colour names and
- * `mg.listAttributes({ query })` covers attributes. Suggestions are a page
- * of the best matches, never a census of matching entities.
- */
-/** Which kind of entity a suggestion is — and therefore what `refId` means. */
-export type SuggestKind = "product" | "brand" | "category";
-/** How the query met the suggestion's label. Strongest first. */
-export type SuggestMatch = "prefix" | "word" | "fuzzy";
-/** One ranked typeahead suggestion, carrying the identity it resolves to. */
-export type Suggestion = {
-    kind: SuggestKind;
-    /** The entity's name as written, for display. */
-    label: string;
-    /**
-     * The resolvable identity: a product id, a brand slug, or a product-type key.
-     * Selecting a suggestion should navigate to this, not re-search `label`.
-     */
-    refId: string;
-    match: SuggestMatch;
-    brandSlug: string | null;
-    brandName: string | null;
-    categoryKey: string | null;
-    /**
-     * A representative variant, so a client can open a material record directly.
-     * Opaque, and null when none was picked — not a product without variants.
-     */
-    variantId: string | null;
-    /** How many of this entity's variants the search index holds: a coverage figure. */
-    variantCount: number;
-};
-/** The suggest response: the query as interpreted, plus the ranked suggestions. */
-export type SuggestResponse = {
-    /** The typed words the search index was matched against. */
-    query: string;
-    /** Ranked best-match-first. Empty when nothing came close: a miss, not an error. */
-    suggestions: Suggestion[];
-};
-/** Options for {@link MaterialGraphClient.suggest}. */
-export type SuggestOptions = {
-    /** How many suggestions to return (1–20, default 8). */
-    limit?: number;
-    /** Restrict to these kinds. Omit for all of them. */
-    kind?: SuggestKind | SuggestKind[];
-};
-/**
- * Shape the query string for a suggest call.
- *
- * The only non-obvious rule: `kind` is a COMMA LIST on the wire (`product,brand`),
- * which is the house convention for multi-value v1 params, so an array is joined
- * here rather than being sent as repeated `?kind=` pairs the route would ignore.
- * Undefined members are dropped by the transport.
- */
-export declare const suggestQuery: (q: string, options?: SuggestOptions) => {
-    q: string;
-    limit?: number;
-    kind?: string;
-};

package/suggest-types.js

@@ -1,28 +0,0 @@
-/**
- * Entity typeahead (MG-654) — the hand-mirrored wire types for
- * `GET /api/v1/search/suggest`, plus the one query-shaping rule the endpoint
- * imposes.
- *
- * Split out of `types.ts` for the repository's source-file size budget, the same
- * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
- * `types.ts`, so importers see no difference.
- *
- * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
- * what answers a committed query; `mg.suggestColour()` covers colour names and
- * `mg.listAttributes({ query })` covers attributes. Suggestions are a page
- * of the best matches, never a census of matching entities.
- */
-/**
- * Shape the query string for a suggest call.
- *
- * The only non-obvious rule: `kind` is a COMMA LIST on the wire (`product,brand`),
- * which is the house convention for multi-value v1 params, so an array is joined
- * here rather than being sent as repeated `?kind=` pairs the route would ignore.
- * Undefined members are dropped by the transport.
- */
-export const suggestQuery = (q, options) => {
-    const kind = Array.isArray(options?.kind)
-        ? options.kind.join(",")
-        : options?.kind;
-    return { kind, limit: options?.limit, q };
-};

package/taxonomy-coverage-types.d.ts

@@ -1,34 +0,0 @@
-/** Exact, source-path-grained status coverage for primary product typing. */
-export type ProductTypeStatusCoverageCounts = {
-    variants: number;
-    accepted: number;
-    proposed: number;
-    proposedBelowThreshold: number;
-    /** Proposed rows with no confidence remain explicit rather than thresholded. */
-    proposedUnknownConfidence: number;
-    otherStatus: number;
-    missingPrimary: number;
-};
-export type ProductTypeStatusCoverageSourcePath = {
-    /** Complete stored source path; null means the product retained no path. */
-    sourcePath: string | null;
-} & ProductTypeStatusCoverageCounts;
-/** Current primary-assignment coverage, never an inferred acceptance decision. */
-export type ProductTypeStatusCoverage = {
-    computedAt: string;
-    basis: {
-        count: "exact";
-        universe: "non_superseded_variants";
-        assignment: "variant_primary_only";
-        sourcePath: "products.source_category_path";
-        /** Reporting cutoff only: higher-confidence proposals remain proposed. */
-        comparisonThreshold: number;
-    };
-    totals: ProductTypeStatusCoverageCounts;
-    sourcePaths: ProductTypeStatusCoverageSourcePath[];
-};
-export type ProductTypeCoverageOptions = {
-    [key: string]: number | undefined;
-    /** Reporting cutoff in [0,1], default 0.85; it never accepts a proposal. */
-    comparisonThreshold?: number;
-};

package/taxonomy-coverage-types.js

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