@instruments/materialgraph 0.2.0 → 0.3.0

package/codes-types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Hand-mirrored wire types for the advisory building-code surface
- * (`POST /api/v1/codes/advisory`, MG-433).
+ * (`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` /
@@ -18,18 +19,32 @@ import type { OpenEnum } from "./types.js";
  * (jurisdiction, occupancy, space, sprinklered) context. `results` preserve
  * input order and cardinality (duplicate ids are echoed).
  */
-export interface CodeAdvisoryInput {
-    /** 1–48 opaque variant ids to badge, echoed back in `results` in this exact order. */
-    variantIds: string[];
+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). */
-    occupancyGroup: string;
-    /** The finish-location / space type (e.g. `"corridor"`, `"exit_enclosure"`). */
-    spaceType: string;
-    /** Whether the space is sprinklered — relaxes several fire-finish floors. */
+    /**
+     * 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;
@@ -44,6 +59,35 @@ export interface CodeAdvisoryContext {
     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). */
@@ -76,18 +120,119 @@ export interface CodeRequirementVerdict {
     /** 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/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);
+    }
+}

package/composition-types.d.ts

@@ -45,13 +45,95 @@ export interface VarySchemesRequest {
     locks?: SchemeLock[];
     exclusions?: SchemeExclusions;
 }
-export type CompositionMatchState = OpenEnum<"matched" | "mismatched" | "unknown">;
-/** One resolved criterion → material match, as scored during composition. */
+/**
+ * One anchor (MG-613): a variant the designer has already pinned to a place in
+ * the programme, supplied on the `compose-material-schemes` run input's
+ * `anchors[]`. Exactly ONE of `variantId` (an exact catalog variant) or `query`
+ * (free-text "Brand Product Colour", resolved server-side) is required. An
+ * anchored slot is LOCKED — composition completes the OPEN slots in relation to
+ * it. Anchors that cannot be resolved leave the slot open and surface a run
+ * warning (never a failure).
+ */
+export interface ComposeAnchorInput {
+    /** The building element the anchor fills (flooring, wall, textile, …). */
+    element: SlotElement;
+    /** Optional named space to scope the anchor to (matched by name/slug). */
+    spaceName?: string;
+    /** An exact catalog variant id. Mutually exclusive with `query`. */
+    variantId?: string;
+    /** Free-text "Brand Product Colour". Mutually exclusive with `variantId`. */
+    query?: string;
+    /** Display name for slot naming and warnings. */
+    label?: string;
+}
+/**
+ * One standing rule in a project's compliance preset (MG-615): free-text
+ * `criteria` phrases that apply to a `scope` of slots. `scope: "all"` reaches
+ * every slot (including slots with no element and slots classified `other`); a
+ * named element reaches only slots carrying exactly that element, so an
+ * unclassified slot receives `"all"` rules only. Phrases are resolved
+ * server-side through the same vocabulary as brief criteria — sustainability
+ * wording ("LEED", "GREENGUARD Gold") resolves to a named certification
+ * programme. A phrase that grounds to nothing is dropped with a run warning.
+ */
+export interface CompliancePresetRule {
+    scope: "all" | SlotElement;
+    criteria: string[];
+}
+/** A project's standing rules, declared once on the compose run (max 12 rules). */
+export interface CompliancePreset {
+    rules: CompliancePresetRule[];
+}
+/**
+ * The `inputJson` for a `compose-material-schemes` run. `batchId` is required;
+ * everything else has a server default. `anchors` (max 24) carry externally
+ * decided picks (MG-613); `compliancePreset` carries the project's standing
+ * rules (MG-615), which cascade into slots as PREFERRED criteria — they grade
+ * every candidate but never exclude one.
+ */
+export interface ComposeMaterialSchemesInput {
+    batchId: string;
+    count?: number;
+    seed?: number;
+    exclusions?: SchemeExclusions;
+    anchors?: ComposeAnchorInput[];
+    compliancePreset?: CompliancePreset;
+}
+/**
+ * The state of one criterion verdict cell (MG-627: the shared MaterialGraph
+ * verdict states). The six LIVE states are `matched` (accepted value satisfies
+ * the criterion), `deviated` (directionally off but named), `failed` (an
+ * accepted value exists and does not satisfy it), `unverified` (a real value
+ * that did not clear the trust bar), `missing` (no accepted value to evaluate),
+ * and `not_evaluated` (the engine did not check it). `mismatched`/`unknown` are
+ * the two LEGACY tokens old persisted runs still carry (never emitted again).
+ * Open per the response-enum policy: treat unknown states forward-compatibly.
+ */
+export type CompositionMatchState = OpenEnum<"matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated" | "mismatched" | "unknown">;
+/** How a criterion cell was baselined — what the candidate was compared against. */
+export type CompositionMatchBaseline = {
+    kind: "term";
+    term: string;
+} | {
+    kind: "presence";
+} | {
+    kind: "seed";
+    variantId: string;
+};
+/** One resolved criterion → material verdict cell, as graded during composition. */
 export interface CompositionMatch {
     attributeId: string;
     state: CompositionMatchState;
     confidence: number | null;
     sourceBasis: string | null;
+    /** Required vs preferred criterion (MG-627). Absent on legacy persisted runs. */
+    strength?: "required" | "preferred";
+    /** What the cell was evaluated against (MG-627). Absent on legacy persisted runs. */
+    baseline?: CompositionMatchBaseline;
+    /** The candidate's own accepted value label, when the cell carries one (MG-627). */
+    value?: string | null;
+    /** Why an `unverified` cell missed the trust bar (MG-627), else null. */
+    trustGap?: "below_confidence" | "basis_unmet" | "proposed" | null;
 }
 /** One slot's chosen material plus the reason it was picked. */
 export interface CompositionPick {
@@ -72,6 +154,12 @@ export interface CompositionPick {
         matched: CompositionMatch[];
         notes: string[];
     };
+    /**
+     * True when this pick is an ANCHOR the designer pinned to the slot (MG-613):
+     * composition never replaced it and vary keeps it fixed. Absent for ordinary
+     * composed picks.
+     */
+    locked?: boolean;
 }
 /** The multi-objective score for one scheme (each component in [0, 1]). */
 export interface CompositionObjective {
@@ -115,3 +203,141 @@ export interface VarySchemesResponse {
     provenance: VaryProvenance;
     shortfall: CompositionShortfall | null;
 }
+/**
+ * Whether a programme element (space, slot, or palette) was `stated` in a text
+ * source or `inferred` from imagery/mood. Only inferred elements raise a review
+ * question. Absent → treated as `stated`.
+ */
+export type ProgrammeProvenance = "stated" | "inferred";
+/**
+ * The broad building element a slot fills — a pragmatically-extended Uniclass EF
+ * vocabulary. Widened with {@link OpenEnum} so a newer server term still
+ * type-checks.
+ */
+export type SlotElement = OpenEnum<"flooring" | "wall" | "ceiling" | "textile" | "surface" | "furniture" | "lighting" | "other">;
+/** One colour cue: a hex swatch with an optional human name. */
+export interface BriefColourCue {
+    hex: string;
+    name?: string;
+}
+/** A source anchor (document id + optional page) attributing derived content. */
+export interface CompositionSourceRef {
+    sourceId: string;
+    page: number | null;
+}
+/**
+ * One candidate colour direction the pile's colour evidence implies when no
+ * palette was explicitly committed. `directionId` is a stable kebab-case handle;
+ * `sourceRefs` attribute the direction to the palette source(s) it was drawn
+ * from (empty when unattributable).
+ */
+export interface PaletteDirection {
+    directionId: string;
+    name: string;
+    colours: BriefColourCue[];
+    sourceRefs: CompositionSourceRef[];
+}
+/**
+ * Suspend payload for the compose `review-programme` step: the FULL programme
+ * picture — every space and slot tagged with its provenance — so the card can
+ * show the whole thing and highlight what was inferred.
+ */
+export interface ReviewProgrammeSuspendPayload {
+    spaces: Array<{
+        spaceId: string;
+        name: string;
+        spaceType?: string;
+        provenance: ProgrammeProvenance;
+    }>;
+    slots: Array<{
+        slotId: string;
+        name: string;
+        spaceId?: string;
+        element?: SlotElement;
+        provenance: ProgrammeProvenance;
+    }>;
+}
+/**
+ * Resume grammar for the `review-programme` step: drop a slot, drop a space
+ * (cascade-dropping its slots), or rename a space.
+ */
+export interface ReviewProgrammeResumeData {
+    corrections: Array<{
+        action: "drop-slot";
+        slotId: string;
+    } | {
+        action: "drop-space";
+        spaceId: string;
+    } | {
+        action: "rename-space";
+        spaceId: string;
+        name: string;
+    }>;
+}
+/**
+ * Suspend payload for the compose `commit-palette` step. Today only the
+ * `directions` mode ships; the shape carries `mode` so a later `ab-images` mode
+ * is an additive member, not a migration.
+ */
+export interface CommitPaletteSuspendPayload {
+    mode: OpenEnum<"directions">;
+    directions: PaletteDirection[];
+}
+/**
+ * Resume grammar for the `commit-palette` step: commit to one direction (by id)
+ * or adopt the union of every direction's colours.
+ */
+export type CommitPaletteResumeData = {
+    choice: "direction";
+    directionId: string;
+} | {
+    choice: "all";
+};
+/**
+ * Resume grammar for the `review-material-criteria` step: accept a resolved
+ * attribute/term for an unresolved phrase, or drop it.
+ */
+export interface ReviewCriteriaResumeData {
+    corrections: Array<{
+        action: "accept";
+        slotId: string;
+        raw: string;
+        attributeId: string;
+        term?: string;
+    } | {
+        action: "drop";
+        slotId: string;
+        raw: string;
+    }>;
+}
+/** The union of every socratic-step resume payload, keyed by the suspended step. */
+export type InterviewResumeData = ReviewCriteriaResumeData | ReviewProgrammeResumeData | CommitPaletteResumeData;
+/** The three socratic interview steps, in procedure order. */
+export type InterviewStepId = "review-programme" | "commit-palette" | "review-material-criteria";
+/**
+ * Payload of a `composition.answered` event — the pile answered a question with
+ * no human turn, or a suspension resolved. `answer` is a stable slug; `citation`
+ * attributes an answer to its source when the brief stated it.
+ */
+export interface CompositionAnsweredPayload {
+    step: InterviewStepId;
+    answer: string;
+    citation: CompositionSourceRef | null;
+    counts?: Record<string, number>;
+}
+/**
+ * Payload of a `composition.slot-pool` event — the candidate theater for one
+ * slot: how many were considered and the top picks (≤5) hydrated for identity.
+ */
+export interface SlotPoolEventPayload {
+    slotId: string;
+    slotName: string;
+    considered: number;
+    top: Array<{
+        variantId: string;
+        brand: string;
+        product: string;
+        imageUrl: string | null;
+        score: number;
+    }>;
+}