@instruments/materialgraph 0.9.1 → 0.11.0

package/brands-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The BRAND lens: the catalogue collection, one brand's profile, and one
+ * brand's whole colour range, as thin wrappers over the shared
+ * {@link HttpTransport}. `MaterialGraphClient.brands` / `.brand` /
+ * `.brandColourDeck` delegate here; the contract lives in this file.
+ *
+ * A brand is a COMPANY, not a catalogue. Every count these reads return is
+ * coverage — what MaterialGraph has ingested — and never a claim about how
+ * many products the maker sells.
+ */
+import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
+import type { BrandFanDeck } from "./fan-deck-types.js";
+import { HttpTransport } from "./http-transport.js";
+import type { BrandOptions, BrandProfileResponse } from "./types.js";
+/**
+ * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
+ * one OFFSET-paginated surface: read `meta.total` for the collection size and
+ * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
+ * brand's profile and trade signals.
+ */
+export declare function listBrands(transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
+/**
+ * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
+ * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
+ * key means no value is held — never infer `false`. Instead use `search()` to
+ * find their materials; this describes the company, not the catalog.
+ */
+export declare function brandProfile(transport: HttpTransport, brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+/**
+ * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
+ * Colours grouped by family — creams together, then greys, then browns — and
+ * ordered light to dark within each. No stored scalar produces that order: a
+ * lightness sort interleaves the whites and the creams, and a reader loses the
+ * sense that they are looking at two different families.
+ *
+ * Deliberately unpaginated, so there is no cursor to walk and no all-brands
+ * form: family order is only correct over a COMPLETE range, because the greys
+ * cannot be placed against the browns while holding one page of each. A range
+ * past the server ceiling reports `truncatedAt` rather than being quietly cut,
+ * and an absent `truncatedAt` means the deck is whole.
+ *
+ * Every swatch carries the maker's PUBLISHED hex — this read never returns a
+ * colour derived from imagery. For "what is near this colour, across makers"
+ * use `byColour()` instead.
+ *
+ * @param brandSlug The brand's slug, as `listBrands()` reports it.
+ */
+export declare function brandColourDeck(transport: HttpTransport, brandSlug: string, signal?: AbortSignal): Promise<BrandFanDeck>;

package/brands-client.js

@@ -0,0 +1,45 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
+ * one OFFSET-paginated surface: read `meta.total` for the collection size and
+ * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
+ * brand's profile and trade signals.
+ */
+export function listBrands(transport, options = {}, signal) {
+    return transport.requestJson(resolveOperation("list_brands"), {
+        query: { q: options.q, limit: options.limit, offset: options.offset },
+        signal,
+    });
+}
+/**
+ * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
+ * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
+ * key means no value is held — never infer `false`. Instead use `search()` to
+ * find their materials; this describes the company, not the catalog.
+ */
+export function brandProfile(transport, brandSlug, options, signal) {
+    return transport.requestJson(resolveOperation("get_brand_profile"), { query: { q: options?.q }, pathParams: { brandSlug }, signal });
+}
+/**
+ * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
+ * Colours grouped by family — creams together, then greys, then browns — and
+ * ordered light to dark within each. No stored scalar produces that order: a
+ * lightness sort interleaves the whites and the creams, and a reader loses the
+ * sense that they are looking at two different families.
+ *
+ * Deliberately unpaginated, so there is no cursor to walk and no all-brands
+ * form: family order is only correct over a COMPLETE range, because the greys
+ * cannot be placed against the browns while holding one page of each. A range
+ * past the server ceiling reports `truncatedAt` rather than being quietly cut,
+ * and an absent `truncatedAt` means the deck is whole.
+ *
+ * Every swatch carries the maker's PUBLISHED hex — this read never returns a
+ * colour derived from imagery. For "what is near this colour, across makers"
+ * use `byColour()` instead.
+ *
+ * @param brandSlug The brand's slug, as `listBrands()` reports it.
+ */
+export function brandColourDeck(transport, brandSlug, signal) {
+    return transport.requestJson(resolveOperation("brand_colour_deck"), { pathParams: { brandSlug }, signal });
+}

package/browse-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Wire types for the browse lane — GET `/api/v1/search/browse`.
+ *
+ * The SDK's one genuinely cursor-paginated surface, and the only lane with no
+ * query, no relevance and no ranking: the corpus in a stated order. That is what
+ * a category listing or a brand fan deck actually needs, and it is why `count`
+ * matters here more than anywhere else — a listing that cannot state its own
+ * size has to either walk every page or report a page size as a total.
+ *
+ * Lifted out of `types.ts` for the repository's source-file size budget when the
+ * lane gained its non-colour sorts and its feed count (MG-1483 / MG-1542).
+ * Nothing about the client's surface changed: `index.ts` re-exports these
+ * exactly as before.
+ */
+import type { ByColourSwatch } from "./by-colour-types.js";
+import type { Cursor, ProductId, VariantId } from "./identifiers.js";
+import type { CountedTotal, OpenEnum } from "./types.js";
+/** One item from the pure colour-scalar browse. */
+export interface BrowseResultItem {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    brandSlug: string | null;
+    productId: ProductId | null;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    scalars: {
+        l: number | null;
+        chroma: number | null;
+        vibrancy: number | null;
+    };
+    retired?: boolean;
+    /**
+     * The row's own image palette — the FULL stored palette of the SAME image
+     * `imageUrl` serves, uncapped and in stored order, each swatch with `oklab`
+     * (see {@link ByColourSwatch}), so a card can render, sort or group colours
+     * without a second call. A one-swatch palette means the extractor found one
+     * colour (solid-colour materials are genuinely monochrome), not that the list
+     * was trimmed. ABSENT when no palette is on record for that image: absent
+     * means unknown, NOT that the material has no colours. These swatches come
+     * from product imagery, not from the manufacturer.
+     */
+    palette?: ByColourSwatch[];
+}
+/** The browse orders. `name` (A→Z) is the default; `recent` is newest first. */
+export type BrowseSort = OpenEnum<"name" | "recent" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+/**
+ * The browse feed's total — how many materials the browse DESCRIBES, which is
+ * never `results.length`.
+ *
+ * Uncapped, unlike {@link SearchCounts}: `basis:"exact"` is the true figure
+ * whatever its size, and `basis:"lowerBound"` means the count query timed out
+ * and the value is a floor. Counted over the SAME filters the page was drawn
+ * from, so a `types=`, `brands=` or `corpusScope=` narrowed browse reports the
+ * narrowed total — you will never get a whole-graph number beside a filtered
+ * page.
+ */
+export interface BrowseCounts {
+    variants: CountedTotal;
+}
+/**
+ * A single page of the browse — the SDK's one genuinely cursor-paginated
+ * surface. `results.length` is this page. Ask for `count: true` and `counts`
+ * states the total; without it the browse states no total at all, and a corpus
+ * claim can only come from walking every page (`client.browse.pages(...)` does
+ * the loop).
+ */
+export interface BrowseResponse {
+    /** THIS PAGE. */
+    results: BrowseResultItem[];
+    /** Opaque keyset for the next page. Absent = the walk is finished. */
+    cursor?: Cursor;
+    /**
+     * The order this page was built in — echoed, because `sort` is optional and
+     * defaulted, so a caller that omitted it need not know the server's default
+     * to label its own listing.
+     */
+    sort: BrowseSort;
+    /**
+     * The total, present ONLY when `count: true` was passed. Absent means it was
+     * not asked for — never that the set is empty.
+     */
+    counts?: BrowseCounts;
+    /**
+     * The corpus this page was drawn from — present ONLY when the request
+     * narrowed it. ABSENT means the whole graph: every material MaterialGraph
+     * knows, orderable or not.
+     */
+    corpusScope?: {
+        scope: OpenEnum<"all" | "materialBankOrderable">;
+        /** What the scope admits, in one sentence, for a human reader. */
+        description: string;
+    };
+}
+/** Params for the pure colour `search/browse` surface. */
+export interface BrowseParams {
+    /**
+     * OPTIONAL. Defaults to `name` (A→Z); `recent` is newest first.
+     *
+     * The five colour ramps (`light`/`dark`/`vivid`/`muted`/`colourful`) order by
+     * an EXTRACTED colour scalar and therefore see only colour-extracted
+     * materials — a genuinely smaller set than `name` and `recent` walk. That is
+     * not a bug to route around; ask for `count` and each sort reports the size of
+     * the set it actually describes.
+     */
+    sort?: BrowseSort;
+    /**
+     * The previous page's `cursor`, verbatim. Opaque keyset state — not an offset.
+     * Changing `sort`, `limit`, `types`, `brands` or `corpusScope` invalidates it.
+     */
+    cursor?: Cursor;
+    /** Page size. */
+    limit?: number;
+    /**
+     * Return `counts.variants` — the total size of the set this browse walks,
+     * counted over the same filters the page came from.
+     *
+     * Opt-in, because it is a second query. A category listing that cannot state
+     * how many things it is listing has to either walk every page or report the
+     * page size as a total; this is the third option.
+     */
+    count?: boolean;
+    /**
+     * Comma-separated taxonomy keys to restrict the browse to, at EITHER tier of
+     * `/api/v1/taxonomy/categories`. A GROUP key (`tile_surfaces`) expands to
+     * every product type under it, a TYPE key (`ceramic_porcelain_tile`) stands
+     * for itself, and a mixed list is their deduplicated union. A key in neither
+     * tier is a 400 listing the valid keys — never an empty page.
+     */
+    types?: string;
+    /**
+     * Comma-separated brand slugs (`farrow-ball`) or display names
+     * (`Farrow & Ball`), case-insensitive. One brand plus a colour `sort` is that
+     * brand's fan deck. An unknown brand is a 400 naming it, never an empty page.
+     */
+    brands?: string;
+    /**
+     * Which corpus to walk. ABSENT means the whole graph — every material
+     * MaterialGraph knows, orderable or not. `materialBankOrderable` restricts to
+     * materials carrying a Material Bank identity, applied inside the scan, so a
+     * scoped page is still a full page and `cursor` still means another eligible
+     * row exists.
+     */
+    corpusScope?: OpenEnum<"all" | "materialBankOrderable">;
+}

package/browse-types.js

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

package/by-colour-types.d.ts

@@ -7,7 +7,7 @@
  * enums are widened so a new server value still type-checks.
  */
 import type { VariantId } from "./identifiers.js";
-import type { OklabTriple, PaletteSwatch } from "./types.js";
+import type { OklabTriple, OpenEnum, PaletteSwatch } from "./types.js";
 /** Coarse group + fine type of a colour match's primary product type. */
 export interface MatchCategory {
     group: string | null;
@@ -16,10 +16,10 @@ export interface MatchCategory {
 /**
  * One colour-palette match.
  *
- * `hex`, `distance` and `closeness` are OKLab geometry over colour EXTRACTED
- * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report it as visual
- * likeness ("reads close to this colour"), never as a stated colour
- * specification.
+ * `distance` and `closeness` are OKLab geometry over colour EXTRACTED FROM
+ * PRODUCT IMAGERY. Report the ORDER as visual likeness ("reads close to this
+ * colour"), never as a stated colour specification. `hex` itself may be the
+ * manufacturer's published colour — read `sourceBasis` before repeating it.
  */
 export interface ByColourMatch {
     /** Opaque — round-trip verbatim. */
@@ -34,6 +34,31 @@ export interface ByColourMatch {
     closeness: number;
     category: MatchCategory | null;
     oklab: OklabTriple | null;
+    /**
+     * Where `hex` came from — PER MATCH, never per response. `"declared"`: the
+     * manufacturer published it (a paint's own colour system), so it may be
+     * repeated as their stated colour. `"derived"`: extracted from product
+     * imagery — visual likeness only. Widened to `string` so a new server value
+     * still type-checks. ABSENT when `hex` is null, or on a response captured
+     * before the field existed.
+     */
+    sourceBasis?: OpenEnum<"declared" | "derived">;
+    /**
+     * OKLab distance from the QUERY colour to this match's `hex` — two single
+     * colours. NOT `distance`, which is the imagery ranking's geometry over whole
+     * PALETTES. The two disagree routinely: a match ranked 4th by imagery is often
+     * the closest by hex. ABSENT when the match has no hex, or when the query was
+     * a palette rather than one colour.
+     */
+    colourDistance?: number;
+    /**
+     * `colourDistance` as a named band, so nobody thresholds a float. Not a
+     * confidence and not a percentage — `very-close` still covers differences a
+     * client would reject in a paint order, so read `sourceBasis` before quoting
+     * any of it as a specification. Widened to `string` so a new server band still
+     * type-checks. ABSENT exactly when `colourDistance` is.
+     */
+    proximity?: OpenEnum<"indistinguishable" | "very-close" | "close" | "related" | "unrelated">;
     /**
      * The match's own image palette — the FULL stored palette, uncapped and in
      * stored order, each swatch with `oklab` (see {@link ByColourSwatch}), so a
@@ -81,11 +106,54 @@ export interface ColourCollapse {
     /** Rows dropped for resolving to a better-ranked row's stored photograph. */
     droppedBySharedImage: number;
 }
+/**
+ * Receipt naming which retrieval lane answered, and the colours it actually ran
+ * on. The live endpoint always sends it.
+ *
+ * Two lanes answer two different questions. A ONE-COLOUR query is a CONTAINMENT
+ * question — which materials hold a swatch near this colour — and is answered as
+ * a bounded OKLab ball over stored palette swatches. A multi-colour query is a
+ * SIMILARITY question — which palettes as a whole resemble this palette — and is
+ * answered by nearest-neighbour over the palette embedding. The two rank on
+ * different geometries, so `colourDistance` on a match means a different thing
+ * in each and is NOT comparable across them.
+ */
+export interface ColourLaneReceipt {
+    /** Which lane answered. Widened so a new server lane still type-checks. */
+    lane: OpenEnum<"containment" | "palette">;
+    /** Why this lane, in one sentence, for a human reader. */
+    reason: string;
+    /**
+     * How the page was ordered. `representative` — the containment default —
+     * draws the page in the contained set's own proportions of solid and
+     * multi-swatch materials, nearest-first within each, because ordering
+     * containment by proximity alone returns a page of solid-colour materials.
+     */
+    order: OpenEnum<"representative" | "nearest" | "similarity">;
+    /**
+     * The colours the search ACTUALLY ran on, after minor-proportion accents were
+     * dropped. Compare against `query.colours`: a difference means the search that
+     * ran is not the search you asked for.
+     */
+    effectiveColours: string[];
+    /**
+     * Colours removed from your query for carrying a proportion below the accent
+     * threshold. EMPTY is the normal case. Non-empty and those colours were absent
+     * from retrieval entirely — they did not merely rank low, so an empty-looking
+     * result is not evidence that nothing holds them.
+     */
+    droppedColours: string[];
+}
 /** The `search/colours` response. */
 export interface ByColourResponse {
     query: {
         colours: string[];
         categories?: string[];
+        /**
+         * Echoed brand filter as resolved SLUGS — what the names you passed
+         * resolved to. Present only when a brand scope applied.
+         */
+        brands?: string[];
         /** Echoed `family` filter, normalised. Present only when one was applied. */
         family?: string;
         oklab?: OklabTriple;
@@ -105,6 +173,24 @@ export interface ByColourResponse {
      * overfetch allowed, and this says so in counts rather than adjectives.
      */
     collapse?: ColourCollapse;
+    /**
+     * Which retrieval lane answered and the colours it ran on. The live endpoint
+     * always sends it; optional here only so responses captured before the lane
+     * split still type-check.
+     */
+    lane?: ColourLaneReceipt;
+    /**
+     * The corpus this page was drawn from — present ONLY when the request
+     * narrowed it. ABSENT means the whole graph: every material MaterialGraph
+     * knows, orderable or not. Under a scope the `familyGate` and `collapse` pool
+     * counts describe the SCOPED corpus too, because the scope was applied inside
+     * retrieval rather than over the page it produced.
+     */
+    corpusScope?: {
+        scope: OpenEnum<"all" | "materialBankOrderable">;
+        /** What the scope admits, in one sentence, for a human reader. */
+        description: string;
+    };
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {
@@ -118,6 +204,20 @@ export interface ByColourParams {
     b?: number;
     /** HARD category filter — display names or taxonomy ids (repeatable). */
     category?: string | string[];
+    /**
+     * HARD brand filter (repeatable) — a brand SLUG (`sherwin-williams`) or its
+     * display name (`Sherwin-Williams`), case-insensitive.
+     *
+     * This is how the CROSS-BRAND question is asked: pass one brand's colour as
+     * `hex` and scope to another to get that brand's nearest colours to it. It is
+     * applied inside retrieval, so `limit` still fills from the scoped brands —
+     * filtering a returned page instead comes back short, because a
+     * nearest-neighbour scan does not know to look further.
+     *
+     * An unknown brand is a 400 naming it, never an empty page. Omitting it (or
+     * passing an empty list) searches every brand.
+     */
+    brand?: string | string[];
     /**
      * HARD colour-family filter — ONE colorscope taxonomy family id, from the
      * closed 15-value vocabulary colorscope itself publishes (`white`, `cream`,

package/client-browse.d.ts

@@ -9,7 +9,7 @@
  * the pagination LOOP, which is the only real logic here and the only part worth
  * testing on its own.
  */
-import type { BrowseParams, BrowseResponse } from "./types.js";
+import type { BrowseParams, BrowseResponse } from "./browse-types.js";
 /**
  * `client.browse(...)` — callable for ONE PAGE, `.pages()` for the whole walk.
  *
@@ -24,14 +24,24 @@ export interface BrowseNamespace {
 /** Fetch one page. The client supplies this, so the transport stays private. */
 export type BrowsePageFetcher = (params: BrowseParams, signal?: AbortSignal) => Promise<BrowseResponse>;
 /**
- * The query string for one browse page — the four params the route reads, named
- * here so the client method and the pagination loop cannot disagree about them.
+ * The query string for one browse page — EVERY param the route reads, named here
+ * so the client method and the pagination loop cannot disagree about them.
+ *
+ * "Every" is load-bearing. This is an allow-list wrapper, and an allow-list
+ * wrapper that rebuilds a query from named fields is precisely the shape that
+ * silently drops a param the server already honours: `brands` shipped on the
+ * route and never reached it from here, so the fan deck was unreachable through
+ * the published client while the server had supported it all along. When the
+ * route gains a param, it gains a line HERE too, or it is not shipped.
  */
 export declare function browseQuery(params: BrowseParams): {
     sort: BrowseParams["sort"];
     cursor: BrowseParams["cursor"];
     limit: BrowseParams["limit"];
+    count: BrowseParams["count"];
     types: BrowseParams["types"];
+    brands: BrowseParams["brands"];
+    corpusScope: BrowseParams["corpusScope"];
 };
 /**
  * Walk every page from `params.cursor` onward.

package/client-browse.js

@@ -1,13 +1,23 @@
 /**
- * The query string for one browse page — the four params the route reads, named
- * here so the client method and the pagination loop cannot disagree about them.
+ * The query string for one browse page — EVERY param the route reads, named here
+ * so the client method and the pagination loop cannot disagree about them.
+ *
+ * "Every" is load-bearing. This is an allow-list wrapper, and an allow-list
+ * wrapper that rebuilds a query from named fields is precisely the shape that
+ * silently drops a param the server already honours: `brands` shipped on the
+ * route and never reached it from here, so the fan deck was unreachable through
+ * the published client while the server had supported it all along. When the
+ * route gains a param, it gains a line HERE too, or it is not shipped.
  */
 export function browseQuery(params) {
     return {
         sort: params.sort,
         cursor: params.cursor,
         limit: params.limit,
+        count: params.count,
         types: params.types,
+        brands: params.brands,
+        corpusScope: params.corpusScope,
     };
 }
 /**

package/client-exploration.d.ts

@@ -0,0 +1,9 @@
+import type { CandidateReadInput, CandidateReadResponse, GraphOperatorEvidence } from "./exploration-types.js";
+import type { HttpTransport } from "./http-transport.js";
+import type { VariantId } from "./identifiers.js";
+/** Discovery and traversal share one namespace so availability precedes use. */
+export interface ExplorationNamespace {
+    operators(variantId: VariantId, signal?: AbortSignal): Promise<GraphOperatorEvidence>;
+    candidates(variantId: VariantId, input: CandidateReadInput, signal?: AbortSignal): Promise<CandidateReadResponse>;
+}
+export declare function createExplorationNamespace(transport: HttpTransport): ExplorationNamespace;

package/client-exploration.js

@@ -0,0 +1,7 @@
+import { resolveOperation } from "./operations.js";
+export function createExplorationNamespace(transport) {
+    return {
+        operators: (variantId, signal) => transport.requestJson(resolveOperation("list_material_operators"), { pathParams: { variantId }, signal }),
+        candidates: (variantId, input, signal) => transport.requestJson(resolveOperation("read_material_candidates"), { body: input, pathParams: { variantId }, signal }),
+    };
+}

package/client-source-material-comments.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The per-file comment surface, namespaced as `mg.sourceMaterialComments` — the
+ * argument people leave on one uploaded file (MG-1345).
+ *
+ * A namespace rather than two more flat methods on an already-large facade,
+ * following `mg.codes` and `mg.colours`: reading a thread and adding to it are
+ * one family, they share a `(batchId, sourceId)` referent, and neither makes
+ * sense without the other. The namespace holds no transport of its own — the
+ * client hands it the shared one, so auth, rate-limit accounting and error
+ * shaping stay in one place.
+ *
+ * TWO RULES A CONSUMER MUST NOT GET WRONG.
+ *
+ * **The author name is REPORTED, never verified.** Every comment carries
+ * `author.attribution: "reported"` — a name somebody typed — plus `recordedBy`,
+ * the authenticated principal that actually wrote the row. Render "recorded as
+ * from Ruth Fielding", never "Ruth Fielding said". The API takes a machine key,
+ * and the person whose argument a remark carries is usually not the person at
+ * the keyboard; presenting the one as the other is the failure this field
+ * exists to prevent.
+ *
+ * **A reply is not a root.** {@link SourceMaterialCommentsNamespace.post}
+ * returns a result discriminated on `kind`: switch on it rather than reaching
+ * for `replies`, which a `reply` does not have. Threads are one level deep and
+ * the database enforces it, so a reply can never grow replies of its own.
+ *
+ * ROUTING OUT OF THIS NAMESPACE. `mg.sourceMaterialBatch(batchId)` already
+ * inlines every file's thread, so opening a batch is ONE call — do not loop this
+ * namespace over a batch's files to rebuild what that read returns. Reach for
+ * `list` when you are watching a single file.
+ */
+import { HttpTransport } from "./http-transport.js";
+import type { PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, SourceMaterialCommentThread } from "./run-types.js";
+export interface SourceMaterialCommentsNamespace {
+    /**
+     * One file's thread, oldest root first, each root carrying its replies.
+     * `comments` is always an array; `truncated` says whether you are holding the
+     * whole thread. A file that is not in that batch, or a batch you do not own,
+     * raises the same 404 as a file that never existed.
+     */
+    list(batchId: string, sourceId: string, signal?: AbortSignal): Promise<SourceMaterialCommentThread>;
+    /**
+     * Add one remark. Pass `parentCommentId` to answer a ROOT comment on the same
+     * file; nesting deeper is a 400. Pass `idempotencyKey` so a retry after a
+     * network timeout returns the comment you already posted rather than a
+     * permanent duplicate.
+     */
+    post(batchId: string, sourceId: string, input: PostSourceMaterialCommentInput, signal?: AbortSignal): Promise<PostSourceMaterialCommentResult>;
+}
+/** Bind the comment operations to the client's shared transport. */
+export declare function createSourceMaterialCommentsNamespace(transport: HttpTransport): SourceMaterialCommentsNamespace;

package/client-source-material-comments.js

@@ -0,0 +1,40 @@
+/**
+ * The per-file comment surface, namespaced as `mg.sourceMaterialComments` — the
+ * argument people leave on one uploaded file (MG-1345).
+ *
+ * A namespace rather than two more flat methods on an already-large facade,
+ * following `mg.codes` and `mg.colours`: reading a thread and adding to it are
+ * one family, they share a `(batchId, sourceId)` referent, and neither makes
+ * sense without the other. The namespace holds no transport of its own — the
+ * client hands it the shared one, so auth, rate-limit accounting and error
+ * shaping stay in one place.
+ *
+ * TWO RULES A CONSUMER MUST NOT GET WRONG.
+ *
+ * **The author name is REPORTED, never verified.** Every comment carries
+ * `author.attribution: "reported"` — a name somebody typed — plus `recordedBy`,
+ * the authenticated principal that actually wrote the row. Render "recorded as
+ * from Ruth Fielding", never "Ruth Fielding said". The API takes a machine key,
+ * and the person whose argument a remark carries is usually not the person at
+ * the keyboard; presenting the one as the other is the failure this field
+ * exists to prevent.
+ *
+ * **A reply is not a root.** {@link SourceMaterialCommentsNamespace.post}
+ * returns a result discriminated on `kind`: switch on it rather than reaching
+ * for `replies`, which a `reply` does not have. Threads are one level deep and
+ * the database enforces it, so a reply can never grow replies of its own.
+ *
+ * ROUTING OUT OF THIS NAMESPACE. `mg.sourceMaterialBatch(batchId)` already
+ * inlines every file's thread, so opening a batch is ONE call — do not loop this
+ * namespace over a batch's files to rebuild what that read returns. Reach for
+ * `list` when you are watching a single file.
+ */
+import { HttpTransport } from "./http-transport.js";
+import { listSourceMaterialComments, postSourceMaterialComment, } from "./runs.js";
+/** Bind the comment operations to the client's shared transport. */
+export function createSourceMaterialCommentsNamespace(transport) {
+    return {
+        list: (batchId, sourceId, signal) => listSourceMaterialComments(transport, batchId, sourceId, signal),
+        post: (batchId, sourceId, input, signal) => postSourceMaterialComment(transport, batchId, sourceId, input, signal),
+    };
+}