@instruments/materialgraph 0.1.0 → 0.3.0

package/codes-types.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Hand-mirrored wire types for the advisory building-code surface
+ * (`GET /api/v1/codes/context`, `GET /api/v1/codes/requirements`,
+ * `POST /api/v1/codes/advisory` — MG-433, MG-674).
+ *
+ * Like the rest of the SDK these interfaces have NO runtime dependency on any
+ * `@materialgraph/*` package — they mirror the `codeAdvisoryInputSchema` /
+ * `codeAdvisoryResultSchema` Zod contracts the route is built from. Response
+ * enums follow the SDK's TOLERANT-PARSING contract (widened with `OpenEnum` so a
+ * new server value still type-checks); `requirement.scale` is an open IBC-scale
+ * id and `caveat` is the AHJ advisory sentence, both read as plain strings.
+ *
+ * ADVISORY ONLY: every verdict and the envelope carry the AHJ caveat — this is
+ * model code as adopted, never a legal determination.
+ */
+import type { OpenEnum } from "./types.js";
+/**
+ * Badge a bounded set of materials against the code-requirement registry for one
+ * (jurisdiction, occupancy, space, sprinklered) context. `results` preserve
+ * input order and cardinality (duplicate ids are echoed).
+ */
+export interface CodeContextRequest {
+    /** A seeded jurisdiction id (e.g. `"us-tx"`); an unknown id is a 400. */
+    jurisdictionId: string;
+    /**
+     * The IBC occupancy group for the space (e.g. `"I-2"` hospital, `"A-2"`
+     * restaurant). Required unless `roomType` correlates to one.
+     */
+    occupancyGroup?: string;
+    /**
+     * The finish location: `"corridors"`, `"exit_stairs_passageways"`, or
+     * `"rooms_enclosed_spaces"`. Required unless `roomType` correlates to one.
+     */
+    spaceType?: string;
+    /**
+     * An `ms_room` term id (e.g. `"hotel_room"`) to correlate the regulatory axes
+     * from. Explicit `occupancyGroup` / `spaceType` always win. A room that
+     * correlates to neither axis is a 400 naming the axis — never a guess.
+     */
+    roomType?: string;
+    /** Whether the space is sprinklered — relaxes several fire-finish floors. No default. */
+    sprinklered: boolean;
+}
+export interface CodeAdvisoryInput extends CodeContextRequest {
+    /** 1–100 opaque variant ids to badge, echoed back in `results` in this exact order. */
+    variantIds: string[];
+}
+/** The resolved jurisdiction the verdicts were evaluated against. */
+export interface CodeAdvisoryJurisdiction {
+    id: string;
+    name: string;
+    codeFamily: string;
+    edition: string;
+    adoptionNote: string;
+}
+/** The echoed evaluation context (the space the badges apply to). */
+export interface CodeAdvisoryContext {
+    occupancyGroup: string;
+    spaceType: string;
+    sprinklered: boolean;
+}
+/**
+ * What one material is, and therefore what it was held to. `dimensions` are the
+ * regulatory dimensions the material can be scored on; `basis` names which
+ * source(s) produced them: a mapped `productTypeId`, `applicationIds`, both, or
+ * `unresolved` when neither yielded anything. `unresolved` does NOT mean the
+ * material is answerable for nothing — it means we could not tell what the
+ * material is, so every requirement the space imposes was scored against it and
+ * `notApplicable` on the result is empty. That is a coverage gap in the
+ * product-type/application map, not a narrow material. A short `requirements`
+ * list under `product_type` / `application` / `both` is a genuine intersection;
+ * a full list under `unresolved` is the map falling short.
+ */
+export interface MaterialCodeProfile {
+    /** The variant's accepted primary product type, or null if it has none. */
+    productTypeId: string | null;
+    /** The variant's accepted `applications` terms, as stored. */
+    applicationIds: string[];
+    /** Regulatory dimensions this material can be held to. Empty ONLY when `basis` is `unresolved`. */
+    dimensions: OpenEnum<"fire" | "floor" | "slip" | "decorative">[];
+    basis: OpenEnum<"product_type" | "application" | "both" | "unresolved">;
+}
+/** Why one requirement the space imposes was excluded from this material's `requirements`. */
+export interface CodeRequirementExclusion {
+    requirementId: string;
+    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
+    reason: OpenEnum<"not_a_material_dimension">;
+    /** One readable line, e.g. `"Slip resistance is not a dimension wallcovering answers for."`. */
+    detail: string;
+}
+/** The threshold one requirement imposes: a class floor and/or a numeric floor. */
+export interface CodeRequirementThreshold {
+    /** The IBC classification scale this requirement is measured on (open id). */
+    scale: string;
+    /** The minimum acceptable class on `scale`, or null when only a numeric floor applies. */
+    minClass: string | null;
+    /** A numeric floor (e.g. a DCOF minimum), or null when only a class floor applies. */
+    numericFloor: {
+        metric: string;
+        value: number;
+        unit: string;
+    } | null;
+}
+/** The accepted fact a verdict was decided from (null when the material carried none). */
+export interface CodeRequirementEvidence {
+    attributeId: OpenEnum<"fire_classifications" | "slip_resistance_dcof">;
+    value: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+/** One requirement badged against one material. */
+export interface CodeRequirementVerdict {
+    requirementId: string;
+    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
+    section: string;
+    requirement: CodeRequirementThreshold;
+    /** `meets` / `shortfall` / `unknown` — `unknown` when no defensible fact maps onto `scale`. */
+    verdict: OpenEnum<"meets" | "shortfall" | "unknown">;
+    evidence: CodeRequirementEvidence | null;
+    /** The AHJ advisory caveat — model code as adopted, never a legal determination. */
+    caveat: string;
+}
+/**
+ * One candidate's requirement verdicts folded into a single status and sentence.
+ * A shortfall outranks an unknown, and an unknown NEVER rolls up to a pass:
+ * `not_applicable` (nothing applied) is deliberately distinct from `meets`.
+ */
+export interface CodeAdvisorySummary {
+    status: OpenEnum<"meets" | "shortfall" | "unverified" | "not_applicable">;
+    /** One deterministic sentence naming what failed, e.g. `"Falls short on fire for A-2 corridors."`. */
+    headline: string;
+    shortfallDimensions: OpenEnum<"fire" | "floor" | "slip" | "decorative">[];
+    unverifiedDimensions: OpenEnum<"fire" | "floor" | "slip" | "decorative">[];
+}
+/** Per-variant advisory outcome, in input order. */
+export interface CodeAdvisoryVariantResult {
+    variantId: string;
+    /** `evaluated` when the id resolved; `unknown_variant` (with `requirements: []`) when it did not. */
+    state: OpenEnum<"evaluated" | "unknown_variant">;
+    /** What this material is and what it was scored against. Null only for `state: "unknown_variant"`. */
+    material: MaterialCodeProfile | null;
+    /** Verdicts for the requirements this material is answerable for — the answerable subset only. */
+    requirements: CodeRequirementVerdict[];
+    /** Requirements the space imposes that this material cannot answer. Empty when nothing was excluded. */
+    notApplicable: CodeRequirementExclusion[];
+    /** The rolled-up card, or null for an id that resolved to nothing. */
+    summary: CodeAdvisorySummary | null;
+}
+/** The `POST /api/v1/codes/advisory` envelope — per-variant, per-requirement verdicts. */
+export interface CodeAdvisoryResponse {
+    jurisdiction: CodeAdvisoryJurisdiction;
+    /** The context AS SUPPLIED, echoed verbatim. */
+    context: CodeAdvisoryContext;
+    /** The canonical axes the registry was queried with, and where they came from. */
+    resolvedContext: ResolvedCodeContext;
+    /** The AHJ advisory caveat, at the envelope level too. */
+    caveat: string;
+    results: CodeAdvisoryVariantResult[];
+}
+/** Where a resolved axis came from: stated outright, or correlated from a room type. */
+export interface ResolvedCodeContext {
+    jurisdictionId: string;
+    occupancyGroup: string;
+    /** The canonical finish-location term id the registry was queried with. */
+    spaceType: string;
+    sprinklered: boolean;
+    basis: OpenEnum<"explicit" | "derived_from_room">;
+    /** The `ms_room` term the axes were correlated from, or null. */
+    roomType: string | null;
+}
+/** How far a jurisdiction's rows have been reviewed against that AHJ's own tables. */
+export type CodeCoverageTier = OpenEnum<"thorough" | "model_baseline">;
+export interface CodeJurisdictionSummary {
+    id: string;
+    name: string;
+    codeFamily: string;
+    edition: string;
+    coverage: CodeCoverageTier;
+    /** One honest line on how the model code actually applies in this jurisdiction. */
+    adoptionNote: string;
+}
+/** The `GET /api/v1/codes/context` envelope — the vocabulary for stating a context. */
+export interface CodeContextResponse {
+    jurisdictions: CodeJurisdictionSummary[];
+    occupancyGroups: {
+        id: string;
+        label: string;
+    }[];
+    finishLocations: {
+        id: string;
+        label: string;
+        shortLabel: string;
+    }[];
+    dimensions: {
+        id: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
+        label: string;
+        description: string;
+        /** The MaterialGraph attribute this dimension is scored against. */
+        attributeId: string;
+    }[];
+    scales: {
+        id: string;
+        label: string;
+        detail: string;
+        /** Ordered BEST FIRST: index 0 outranks index 1. */
+        classes: string[];
+    }[];
+    /** `ms_room` → regulatory axes. `null` where the registry refuses to correlate. */
+    roomCorrelations: {
+        roomType: string;
+        label: string;
+        occupancyGroup: string | null;
+        finishLocation: string | null;
+    }[];
+    /** The AHJ advisory caveat. */
+    caveat: string;
+}
+/** One requirement a context imposes, independent of any candidate material. */
+export interface CodeRequirementListing {
+    requirementId: string;
+    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
+    /** The code section this demand is cited from. */
+    section: string;
+    attributeId: string;
+    requirement: CodeRequirementThreshold;
+    /** One readable line, e.g. `"Class A or better · ASTM E84 / UL 723"`. */
+    label: string;
+}
+/**
+ * The `GET /api/v1/codes/requirements` envelope. An empty `requirements` array
+ * means the registry holds nothing for this context — it is not a pass.
+ */
+export interface CodeRequirementsResponse {
+    jurisdiction: CodeJurisdictionSummary;
+    context: ResolvedCodeContext;
+    requirements: CodeRequirementListing[];
+    caveat: string;
+}

package/codes-types.js

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

package/colour-aggregate-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Wire types for the colour AGGREGATE surface — `GET /api/v1/colours/profiles`
+ * and `GET /api/v1/colours/stats`.
+ *
+ * Kept out of `types.ts` for the same reason `material-types.ts` and
+ * `codes-types.ts` are: the shared mirror is at its source-size budget. Same
+ * tolerant-parsing contract as the rest of the mirror — response enums are
+ * widened so a new server value still type-checks.
+ */
+import type { OpenEnum } from "./types.js";
+/** Which taxonomy tier a colour profile's `categoryKey` names. */
+export type CategoryTier = OpenEnum<"group" | "type">;
+/** How the endpoint picks which colours to keep. */
+export type ColourProfileSelect = OpenEnum<"frequency" | "diverse">;
+/** One representative colour bucket of a category. */
+export interface CategoryColour {
+    hex: string;
+    oklab: {
+        l: number;
+        a: number;
+        b: number;
+    };
+    variantCount: number;
+    /** This bucket's share of the category's coloured variants, 0–1. */
+    proportion: number;
+}
+export interface CategoryColourProfile {
+    categoryKey: string;
+    level: CategoryTier;
+    name: string;
+    path: string;
+    variantCount: number;
+    avgLightness: number;
+    avgChroma: number;
+    colours: CategoryColour[];
+}
+/**
+ * The snapshot a profile response was computed from. Compare `variantCount`
+ * against `colours/stats`' `corpus.withColour` to see how complete the
+ * underlying materialized view currently is, and `refreshedAt` for its age.
+ */
+export interface CategoryColourProfilesBasis {
+    variantCount: number;
+    refreshedAt: string | null;
+}
+export interface CategoryColourProfilesResponse {
+    profiles: CategoryColourProfile[];
+    basis: CategoryColourProfilesBasis;
+}
+/** Request parameters for `colours.profiles()`. */
+export interface ColourProfilesParams {
+    /** 1–8 category keys, at the tier named by `groupBy`. */
+    productTypeIds: readonly string[];
+    /** `"group"` merges each group's leaf product types into one palette. */
+    groupBy?: "group" | "type";
+    /** Representative colours per category, 1–64. */
+    topN?: number;
+    /** `"diverse"` maximises visual distinctness instead of frequency. */
+    select?: "frequency" | "diverse";
+}
+export interface ColourStatsCorpus {
+    variants: number;
+    withColour: number;
+    /** `withColour / variants`, 0–1. */
+    coverage: number;
+}
+export interface ColourStatsFamily {
+    id: string;
+    label: string;
+    variants: number;
+    brands: number;
+}
+export interface ColourStatsGroup {
+    key: string;
+    name: string;
+    productTypes: number;
+    variants: number;
+}
+/** Where each section came from, how fresh it is, and what it does NOT answer. */
+export interface ColourStatsBasis {
+    corpus: string;
+    families: string;
+    groups: string;
+    groupsRefreshedAt: string | null;
+    groupsVariantCount: number;
+    omissions: string[];
+}
+export interface ColourStatsResponse {
+    corpus: ColourStatsCorpus;
+    families: ColourStatsFamily[];
+    groups: ColourStatsGroup[];
+    basis: ColourStatsBasis;
+}

package/colour-aggregate-types.js

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

package/colours-client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The colour AGGREGATE surface, namespaced as `mg.colours`.
+ *
+ * Two reads that answer the same question at two altitudes — "how much colour
+ * does the graph hold at all" (`stats`) and "what colours does this category
+ * come in" (`profiles`) — so they live together rather than as two more flat
+ * methods on an already-large client facade. `mg.codes` and `mg.browse` set the
+ * precedent for a namespace when a capability is a small family rather than a
+ * single verb.
+ *
+ * The namespace holds no transport of its own: the client hands it a bound
+ * `get`, so auth, rate-limit accounting and error shaping stay in one place.
+ *
+ * Both responses carry a `basis`. These are reads of a materialized view that is
+ * refreshed on a schedule, not on write, so a caller can and should check how
+ * much of the corpus the answer actually covers before treating it as complete.
+ */
+import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsResponse } from "./colour-aggregate-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
+/** The client's own request primitive, handed down so this file owns no transport. */
+export interface ColoursTransport {
+    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+}
+export declare class ColoursClient {
+    #private;
+    constructor(transport: ColoursTransport);
+    /**
+     * The representative colour palette of 1–8 categories in ONE call
+     * (GET `/api/v1/colours/profiles`).
+     *
+     * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
+     * under a group into one histogram BEFORE ranking — a group's palette, not the
+     * union of its leaves' heads. `select: "diverse"` returns visually spread
+     * swatches (greedy max-min over OKLab, 0.02 minimum separation, backfilled by
+     * frequency if fewer survive) instead of the most frequent ones; a client
+     * cannot recover that spread from a truncated frequency list, which is why it
+     * is a server mode rather than a local sort.
+     *
+     * A selected category with no colour data comes back as a zero-count profile,
+     * not a missing key.
+     */
+    profiles(params: ColourProfilesParams, signal?: AbortSignal): Promise<CategoryColourProfilesResponse>;
+    /**
+     * Corpus colour coverage (GET `/api/v1/colours/stats`): how much of the graph
+     * carries colour at all, the split across the canonical colour families, and
+     * coverage per product-type group. `basis` states the source and freshness of
+     * each section plus `basis.omissions` — what this call deliberately does not
+     * answer, listed rather than silently absent.
+     */
+    stats(signal?: AbortSignal): Promise<ColourStatsResponse>;
+}

package/colours-client.js

@@ -0,0 +1,39 @@
+export class ColoursClient {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /**
+     * The representative colour palette of 1–8 categories in ONE call
+     * (GET `/api/v1/colours/profiles`).
+     *
+     * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
+     * under a group into one histogram BEFORE ranking — a group's palette, not the
+     * union of its leaves' heads. `select: "diverse"` returns visually spread
+     * swatches (greedy max-min over OKLab, 0.02 minimum separation, backfilled by
+     * frequency if fewer survive) instead of the most frequent ones; a client
+     * cannot recover that spread from a truncated frequency list, which is why it
+     * is a server mode rather than a local sort.
+     *
+     * A selected category with no colour data comes back as a zero-count profile,
+     * not a missing key.
+     */
+    profiles(params, signal) {
+        return this.#transport.get("get_category_colour_profiles", {
+            productTypeIds: params.productTypeIds.join(","),
+            groupBy: params.groupBy,
+            topN: params.topN,
+            select: params.select,
+        }, signal);
+    }
+    /**
+     * Corpus colour coverage (GET `/api/v1/colours/stats`): how much of the graph
+     * carries colour at all, the split across the canonical colour families, and
+     * coverage per product-type group. `basis` states the source and freshness of
+     * each section plus `basis.omissions` — what this call deliberately does not
+     * answer, listed rather than silently absent.
+     */
+    stats(signal) {
+        return this.#transport.get("get_colour_stats", undefined, signal);
+    }
+}