@instruments/materialgraph 0.29.0 → 0.31.0

package/codes-client.d.ts

@@ -1,118 +0,0 @@
-/**
- * The advisory building-code surface, namespaced as `mg.codes`.
- *
- * Three calls that are one workflow — discover the vocabulary, state the space,
- * then badge candidates against it — so they live together rather than as three
- * flat methods on an already-large client facade. `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 bound
- * `get`/`post` callbacks, so auth, rate-limit accounting and error shaping stay
- * in exactly one place.
- *
- * ADVISORY ONLY: every verdict and every envelope carries the AHJ caveat — this
- * is model code as adopted, never a legal determination.
- *
- * ROUTING. Codes answers "is this material allowed in THIS SPACE?" — a question
- * about a jurisdiction, an occupancy group and a finish location, not about a
- * material alone.
- * - "which materials carry Class A?" → `mg.bySpec("fire_classifications:...")`.
- *   That is a property question; this namespace is what tells you the space
- *   demands Class A in the first place.
- * - "what does this one material hold?" → `mg.materialBlocks(variantId)`.
- * - "find me something like this, but compliant" → `mg.search({ filters })`
- *   once `requirements()` has told you which filter to apply.
- */
-import type { CodeAdvisoryInput, CodeAdvisoryResponse, CodeContextRequest, CodeContextResponse, CodeRequirementsResponse } from "./codes-types.js";
-import type { QueryParams } from "./http-transport.js";
-import type { SdkOperationId } from "./operations.js";
-/** The client's own request primitives, handed down so this file owns no transport. */
-export type CodesTransport = {
-    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
-    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
-};
-export declare class CodesClient {
-    #private;
-    constructor(transport: CodesTransport);
-    /**
-     * THE QUESTION: "what may I even say about a space?" — the vocabulary for
-     * stating a code context, and the first call of the three.
-     *
-     * Everything {@link CodesClient.requirements} and {@link CodesClient.advisory}
-     * accept is listed here, so nothing need be hardcoded and a 400 for an unknown
-     * jurisdiction / occupancy / space is always avoidable.
-     *
-     * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
-     * seeded jurisdictions and their coverage tier, the occupancy groups the
-     * registry keys on, finish locations, dimensions, classification scales with
-     * classes ordered best-first, and which `room` term correlates to which
-     * regulatory axes.
-     *
-     * Start here — every value the other two calls accept is listed in this one
-     * response, so nothing need be hardcoded. A correlation the registry refuses to
-     * make comes back `null`, never a guess.
-     *
-     * @example
-     * const vocab = await mg.codes.context();
-     * const texas = vocab.jurisdictions.find((j) => j.id === "us-tx");
-     * // `model_baseline` means unamended model IBC stood in for this AHJ's own table.
-     * console.log(texas?.coverage, texas?.adoptionNote);
-     */
-    context(signal?: AbortSignal): Promise<CodeContextResponse>;
-    /**
-     * THE QUESTION: "what does this space DEMAND?" — before any candidate exists.
-     *
-     * Run it before shortlisting, not after: it tells you which specification to
-     * filter on, which you then spend on `mg.bySpec()` or `mg.search({ filters })`.
-     * Use {@link CodesClient.advisory} once you hold candidates to badge.
-     *
-     * What a space demands, before any candidate exists (GET
-     * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
-     * `roomType` the axes are correlated from.
-     *
-     * An empty `requirements` array means nothing in the registry applies to this
-     * context. It is NOT a pass.
-     *
-     * @example
-     * const { requirements } = await mg.codes.requirements({
-     *   jurisdictionId: "us-tx",
-     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
-     *   spaceType: "corridors",
-     *   sprinklered: true,
-     * });
-     * requirements.map((r) => `${r.dimension}: ${r.label} (${r.section})`);
-     */
-    requirements(input: CodeContextRequest, signal?: AbortSignal): Promise<CodeRequirementsResponse>;
-    /**
-     * THE QUESTION: "do THESE candidates satisfy what this space demands?" — the
-     * third call, once you hold materials.
-     *
-     * Context is CONDITIONAL: supply `occupancyGroup` + `spaceType`, or a
-     * `roomType` for them to correlate from, or a mix — an explicit axis always
-     * wins, and an axis that resolves to nothing is a 400 naming it. The full rule,
-     * with the validator's own messages, is on {@link CodeContextRequest}.
-     *
-     * Read `summary.status` honestly: `unverified` means no comparable rating is on
-     * file. It is not a pass, and it is common. Use {@link CodesClient.requirements}
-     * when you have no candidates yet, and `mg.materialBlocks()` to see whether a
-     * material's fire/slip facts are missing or merely unverified.
-     *
-     * Badge materials against the advisory building-code registry for one context
-     * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
-     * badged `meets` / `shortfall` / `unknown` from the material's accepted fire
-     * and slip facts, in input order; each material also carries a rolled-up
-     * `summary`, and `resolvedContext` reports the axes actually used.
-     *
-     * @example
-     * const advisory = await mg.codes.advisory({
-     *   variantIds: scheme.picks.map((p) => p.variantId),
-     *   jurisdictionId: "us-tx",
-     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
-     *   spaceType: "corridors", // corridors | exit_stairs_passageways | rooms_enclosed_spaces
-     *   sprinklered: true,
-     * });
-     * // `unverified` means no comparable rating is on file — common, never a pass.
-     * const blocked = advisory.results.filter((r) => r.summary?.status === "shortfall");
-     */
-    advisory(input: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
-}

package/codes-client.js

@@ -1,99 +0,0 @@
-export class CodesClient {
-    #transport;
-    constructor(transport) {
-        this.#transport = transport;
-    }
-    /**
-     * THE QUESTION: "what may I even say about a space?" — the vocabulary for
-     * stating a code context, and the first call of the three.
-     *
-     * Everything {@link CodesClient.requirements} and {@link CodesClient.advisory}
-     * accept is listed here, so nothing need be hardcoded and a 400 for an unknown
-     * jurisdiction / occupancy / space is always avoidable.
-     *
-     * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
-     * seeded jurisdictions and their coverage tier, the occupancy groups the
-     * registry keys on, finish locations, dimensions, classification scales with
-     * classes ordered best-first, and which `room` term correlates to which
-     * regulatory axes.
-     *
-     * Start here — every value the other two calls accept is listed in this one
-     * response, so nothing need be hardcoded. A correlation the registry refuses to
-     * make comes back `null`, never a guess.
-     *
-     * @example
-     * const vocab = await mg.codes.context();
-     * const texas = vocab.jurisdictions.find((j) => j.id === "us-tx");
-     * // `model_baseline` means unamended model IBC stood in for this AHJ's own table.
-     * console.log(texas?.coverage, texas?.adoptionNote);
-     */
-    async context(signal) {
-        return await this.#transport.get("list_code_context", undefined, signal);
-    }
-    /**
-     * THE QUESTION: "what does this space DEMAND?" — before any candidate exists.
-     *
-     * Run it before shortlisting, not after: it tells you which specification to
-     * filter on, which you then spend on `mg.bySpec()` or `mg.search({ filters })`.
-     * Use {@link CodesClient.advisory} once you hold candidates to badge.
-     *
-     * What a space demands, before any candidate exists (GET
-     * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
-     * `roomType` the axes are correlated from.
-     *
-     * An empty `requirements` array means nothing in the registry applies to this
-     * context. It is NOT a pass.
-     *
-     * @example
-     * const { requirements } = await mg.codes.requirements({
-     *   jurisdictionId: "us-tx",
-     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
-     *   spaceType: "corridors",
-     *   sprinklered: true,
-     * });
-     * requirements.map((r) => `${r.dimension}: ${r.label} (${r.section})`);
-     */
-    async requirements(input, signal) {
-        return await this.#transport.get("list_code_requirements", {
-            jurisdiction: input.jurisdictionId,
-            occupancy: input.occupancyGroup,
-            room: input.roomType,
-            space: input.spaceType,
-            sprinklered: input.sprinklered,
-        }, signal);
-    }
-    /**
-     * THE QUESTION: "do THESE candidates satisfy what this space demands?" — the
-     * third call, once you hold materials.
-     *
-     * Context is CONDITIONAL: supply `occupancyGroup` + `spaceType`, or a
-     * `roomType` for them to correlate from, or a mix — an explicit axis always
-     * wins, and an axis that resolves to nothing is a 400 naming it. The full rule,
-     * with the validator's own messages, is on {@link CodeContextRequest}.
-     *
-     * Read `summary.status` honestly: `unverified` means no comparable rating is on
-     * file. It is not a pass, and it is common. Use {@link CodesClient.requirements}
-     * when you have no candidates yet, and `mg.materialBlocks()` to see whether a
-     * material's fire/slip facts are missing or merely unverified.
-     *
-     * Badge materials against the advisory building-code registry for one context
-     * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
-     * badged `meets` / `shortfall` / `unknown` from the material's accepted fire
-     * and slip facts, in input order; each material also carries a rolled-up
-     * `summary`, and `resolvedContext` reports the axes actually used.
-     *
-     * @example
-     * const advisory = await mg.codes.advisory({
-     *   variantIds: scheme.picks.map((p) => p.variantId),
-     *   jurisdictionId: "us-tx",
-     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
-     *   spaceType: "corridors", // corridors | exit_stairs_passageways | rooms_enclosed_spaces
-     *   sprinklered: true,
-     * });
-     * // `unverified` means no comparable rating is on file — common, never a pass.
-     * const blocked = advisory.results.filter((r) => r.summary?.status === "shortfall");
-     */
-    async advisory(input, signal) {
-        return await this.#transport.post("resolveCodeAdvisory", input, signal);
-    }
-}

package/codes-types.d.ts

@@ -1,325 +0,0 @@
-/**
- * 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 { VariantId } from "./identifiers.js";
-import type { FilterGroups } from "./list-variants-types.js";
-import type { OpenEnum } from "./types.js";
-/**
- * A code context: the space the registry is queried for.
- *
- * CONDITIONAL REQUIREMENT — two axes must END UP resolved, and each may be
- * stated OR correlated. Every field below is optional in the type because the
- * validator resolves them per axis independently; the rule it enforces at
- * runtime is:
- *
- * > occupancyGroup, resolved = `input.occupancyGroup` ?? correlate(roomType)
- * > spaceType,      resolved = `input.spaceType`      ?? correlate(roomType)
- *
- * and either resolving to nothing is a 400, verbatim:
- *
- * - `"An occupancy group is required — state occupancyGroup, or a roomType that
- *   correlates to one."`
- * - `"A space type is required — state spaceType, or a roomType that correlates
- *   to one."`
- * - `"Room type \"{roomType}\" does not correlate to an IBC occupancy group —
- *   state occupancyGroup explicitly."`
- * - `"Room type \"{roomType}\" does not correlate to a Table 803.13 finish
- *   location — state spaceType explicitly."`
- *
- * So: give `occupancyGroup` + `spaceType`, or give `roomType` and let both
- * correlate, or mix them — an explicit axis always wins over a correlated one,
- * and a room is only consulted for an axis you did not state. Correlation never
- * guesses: a room that maps to neither is an error naming the axis, and the
- * response's `resolvedContext` is where you audit what was inferred for you.
- *
- * Discover every accepted value — jurisdictions, occupancy groups, finish
- * locations, and the room correlations themselves — from
- * {@link CodesClient.context}. Nothing here should be hardcoded.
- */
-export type CodeContextRequest = {
-    /** A seeded jurisdiction id (e.g. `"us-tx"`); an unknown id is a 400 listing the seeded set. */
-    jurisdictionId: string;
-    /**
-     * The IBC occupancy group for the space (e.g. `"I-2"` hospital, `"A-2"`
-     * restaurant). Required unless `roomType` correlates to one. An uncovered
-     * group is a 400 listing the covered ones.
-     */
-    occupancyGroup?: string;
-    /**
-     * The finish location: `"corridors"`, `"exit_stairs_passageways"`, or
-     * `"rooms_enclosed_spaces"`. Required unless `roomType` correlates to one.
-     */
-    spaceType?: string;
-    /**
-     * A `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 type CodeAdvisoryInput = {
-    /**
-     * 1–100 opaque variant ids to badge, echoed back in `results` in this exact
-     * order and cardinality (duplicates are echoed, never collapsed). Preserve
-     * them verbatim — never parse or construct one.
-     */
-    variantIds: VariantId[];
-} & CodeContextRequest;
-/** The resolved jurisdiction the verdicts were evaluated against. */
-export type CodeAdvisoryJurisdiction = {
-    id: string;
-    name: string;
-    codeFamily: string;
-    edition: string;
-    adoptionNote: string;
-};
-/** The echoed evaluation context (the space the badges apply to). */
-export type 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 type 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 type 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 type 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, which is exactly the case that produces `verdict: "unknown"`.
- *
- * `confidence` and `sourceBasis` are the strength of the fact, not of the code
- * reading. Quote them whenever you quote the badge: a `meets` resting on a
- * `derived` value at low confidence is a materially different statement from one
- * resting on a `tested` figure.
- */
-export type CodeRequirementEvidence = {
-    attributeId: OpenEnum<"fire_classifications" | "slip_resistance_dcof">;
-    value: string;
-    confidence: number | null;
-    sourceBasis: string | null;
-};
-/** One requirement badged against one material. */
-export type CodeRequirementVerdict = {
-    requirementId: string;
-    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
-    section: string;
-    requirement: CodeRequirementThreshold;
-    /**
-     * What may be said about this material against this requirement:
-     *  - `meets` — a defensible fact clears the threshold. Advisory, still not a
-     *    determination.
-     *  - `shortfall` — a defensible fact FAILS to clear it. A real negative.
-     *  - `unknown` — no defensible fact maps onto `scale`. NOT a failure and NOT a
-     *    pass: "no comparable rating on file". Never present it as either.
-     */
-    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 type CodeAdvisorySummary = {
-    /**
-     * The rolled-up card, and what each token licenses:
-     *  - `meets` — every applicable requirement was `meets`. Advisory pass.
-     *  - `shortfall` — at least one requirement failed on real evidence. Blocking.
-     *  - `unverified` — nothing failed, but something is `unknown`. COMMON, and
-     *    never a pass: it means "no comparable rating is on file". Show it as an
-     *    open question, not a green tick.
-     *  - `not_applicable` — the space imposes nothing this material answers for.
-     *    Deliberately distinct from `meets`: it is silence, not approval.
-     */
-    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 type CodeAdvisoryVariantResult = {
-    /** Opaque — echoed verbatim from `variantIds`, in that position. */
-    variantId: VariantId;
-    /** `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 type 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 type 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 `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.
- *
- *  - `thorough` — reviewed against this jurisdiction's own adopted tables.
- *  - `model_baseline` — UNAMENDED model IBC stood in, because that AHJ's own
- *    amendments have not been reviewed. Local amendments may be stricter, so
- *    say "per model IBC" rather than naming the jurisdiction as the authority.
- */
-export type CodeCoverageTier = OpenEnum<"thorough" | "model_baseline">;
-export type 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 type 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[];
-    }[];
-    /** `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 type 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;
-};
-/** Why one requirement the context imposes could not become a `list_variants` filter predicate. */
-export type CodeSpecFilterUnexpressible = {
-    requirementId: string;
-    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
-    reason: OpenEnum<"no_matchable_tokens" | "unsupported_scale" | "no_floor">;
-    /** One readable line naming why, e.g. `"Scale ... has no ordinal definition..."`. */
-    detail: 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 type CodeRequirementsResponse = {
-    jurisdiction: CodeJurisdictionSummary;
-    context: ResolvedCodeContext;
-    requirements: CodeRequirementListing[];
-    /**
-     * The same requirements as a ready-to-use `list_variants` `filters` group
-     * (MG-2222, `{terms, numbers, presence}`) — pass it straight through as
-     * `listVariants({ filters })`.
-     * `null` when nothing here is filterable; read `specFilterUnexpressible`
-     * for why, not an empty `requirements` list.
-     */
-    specFilter: FilterGroups | null;
-    /** The dimensions `specFilter` actually narrows on — a subset of `requirements`' dimensions. */
-    specFilterApplied: OpenEnum<"fire" | "floor" | "slip" | "decorative">[];
-    /** Requirements that could not be turned into a filter predicate, and why. */
-    specFilterUnexpressible: CodeSpecFilterUnexpressible[];
-    caveat: string;
-};