@instruments/materialgraph 0.25.0 → 0.27.0

package/composition-types.d.ts

@@ -1,455 +0,0 @@
-/**
- * Hand-mirrored wire types for the synchronous composition-variation surface
- * (`POST /api/v1/schemes/vary`, operation `vary_schemes`, MG-438). Like the rest
- * of the SDK these interfaces carry NO runtime dependency on any
- * `@materialgraph/*` package — they mirror the `VarySchemesRequest` /
- * `VarySchemesResponse` shapes in `apps/web/public/openapi.yaml`.
- *
- * Vary is deterministic and synchronous: it re-derives an "option B" from a
- * succeeded `compose-material-schemes` Run along one constraint axis, so unlike
- * the async Run surface the response IS the scheme — no run envelope, no events.
- *
- * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
- * so a new server value still type-checks; objects are read structurally.
- */
-import type { VerdictCitation } from "./citation-types.js";
-import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
-import type { OpenEnum } from "./types.js";
-/**
- * The four v1 variation axes. Request-side, so this is a STRICT union (the
- * caller picks exactly one). `uniqueness` is deferred server-side (MG-445).
- */
-export type VaryAxis = "palette" | "sustainability" | "brandDiversity" | "priceTier";
-/**
- * The variation axes as a runtime array, for consumers that render an axis
- * picker. Order is the canonical presentation order.
- */
-export declare const VARY_AXES: readonly VaryAxis[];
-/** Pin one slot to a specific variant so vary re-derives only the rest. */
-export interface SchemeLock {
-    slotId: SlotId;
-    /** Must equal that slot's CURRENT pick in the source scheme. Opaque. */
-    variantId: VariantId;
-}
-/** Candidate exclusions applied on top of the automatic source-pick exclusion. */
-export interface SchemeExclusions {
-    /** Opaque variant ids to keep out of every slot. */
-    variantIds?: VariantId[];
-    brandSlugs?: string[];
-}
-/** Body for `POST /api/v1/schemes/vary` ({@link MaterialGraphClient.varyScheme}). */
-export interface VarySchemesRequest {
-    /** The succeeded `compose-material-schemes` Run to vary from. Opaque. */
-    runId: RunId;
-    /** Which scheme in the Run is option A. Defaults to the Run's FIRST scheme. */
-    schemeId?: SchemeId;
-    axis: VaryAxis;
-    /** Slots kept pinned to their source pick; only unlocked slots re-derive. */
-    locks?: SchemeLock[];
-    exclusions?: SchemeExclusions;
-}
-/**
- * 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. Opaque. Mutually exclusive with `query`. */
-    variantId?: VariantId;
-    /** 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[];
-}
-/** Exact project regulatory axes used to attach bounded code citations. */
-export interface ProgrammeRegulatoryAxes {
-    jurisdictionId: string;
-    occupancyGroup: string;
-    sprinklered: boolean;
-}
-/** One caller-declared Programme space. `spaceType` remains open descriptive text. */
-export interface ComposeDeclaredSpace {
-    name: string;
-    spaceType?: string;
-    /** Exact active canonical `room` id used for bounded code evaluation. */
-    regulatoryRoomType?: string;
-}
-/** The spaces this run is explicitly for; omit to retain brief inference. */
-export interface ComposeDeclaredScope {
-    spaces: ComposeDeclaredSpace[];
-}
-/**
- * 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 {
-    /** The uploaded source-material batch to compose from. Opaque. */
-    batchId: string;
-    count?: number;
-    seed?: number;
-    exclusions?: SchemeExclusions;
-    anchors?: ComposeAnchorInput[];
-    compliancePreset?: CompliancePreset;
-    /** Omit to leave Programme code coverage explicitly unevaluated. */
-    regulatoryAxes?: ProgrammeRegulatoryAxes;
-    /** Explicit caller-held space facts; regulatoryRoomType is never inferred. */
-    scope?: ComposeDeclaredScope;
-}
-/**
- * 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;
-    citation?: VerdictCitation;
-}
-/** One slot's chosen material plus the reason it was picked. */
-export interface CompositionPick {
-    slotId: SlotId;
-    slotName: string;
-    spaceId?: string | null;
-    element?: string | null;
-    material: {
-        /** Opaque — round-trip verbatim into the material lenses. */
-        variantId: VariantId;
-        brand: string;
-        product: string;
-        variant: string;
-        imageUrl: string | null;
-        hex: string | null;
-    };
-    reason: {
-        score: number;
-        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 {
-    total: number;
-    briefFit: number;
-    coverage: number;
-    coherence: number;
-    novelty: number;
-}
-/** A hydrated scheme: one pick per slot, plus its objective breakdown. */
-export interface CompositionScheme {
-    schemeId: SchemeId;
-    title: string;
-    picks: CompositionPick[];
-    objective: CompositionObjective;
-}
-/**
- * How far short of the request the derivation fell, with honest reasons.
- * `produced < requested` is a real answer, not an error — `reasons` says why,
- * and a null shortfall means nothing fell short.
- */
-export interface CompositionShortfall {
-    requested: number;
-    produced: number;
-    reasons: string[];
-}
-/** The axis + source provenance stamped onto every varied scheme. */
-export interface VaryProvenance {
-    axis: VaryAxis;
-    sourceRunId: RunId;
-    sourceSchemeId: SchemeId;
-    lockedSlotIds: SlotId[];
-    /**
-     * Human-readable notes recording exactly what the axis did — counts, not
-     * adjectives (e.g. "brandDiversity: hard-excluded 2 brand(s) appearing ≥2×").
-     * These are the variation's receipts.
-     */
-    notes: string[];
-}
-/** The `200` body from `POST /api/v1/schemes/vary`. */
-export interface VarySchemesResponse {
-    /** The composition version the scheme was stamped with. */
-    version: string;
-    scheme: CompositionScheme;
-    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[];
-}
-/**
- * WHERE a slot's `category` came from (MG-954, extended MG-978): `resolved` —
- * derived from the slot's own words against the catalog's category vectors;
- * `resolved-coverage` — the words ended in a close race and the runner-up won it
- * because the text winner held no value for one of the slot's required
- * attributes; `model` — the interpreter's own draw stood because nothing
- * resolved; `none` — neither produced one, so the slot has NO category and
- * retrieval cannot gate it; `corrected` — a designer set it with a
- * `set-slot-category` correction. Widened with {@link OpenEnum} so a newer
- * server term still type-checks.
- */
-export type SlotCategorySource = OpenEnum<"resolved" | "resolved-coverage" | "model" | "none" | "corrected">;
-/**
- * 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.
- *
- * Each slot also discloses the catalog `category` it will shop in and the
- * `categorySource` that won it (MG-954). Both are OPTIONAL and additive: an
- * ABSENT `category` means the slot has none — not that it has an empty one — and
- * a slot in that state cannot be gated at retrieval, so it is skipped there with
- * a counted shortfall unless a `set-slot-category` correction supplies one.
- */
-export interface ReviewProgrammeSuspendPayload {
-    spaces: Array<{
-        spaceId: string;
-        name: string;
-        spaceType?: string;
-        provenance: ProgrammeProvenance;
-    }>;
-    slots: Array<{
-        slotId: string;
-        name: string;
-        spaceId?: string;
-        element?: SlotElement;
-        category?: string;
-        categorySource?: SlotCategorySource;
-        /** Criteria grounding exhausted its one bounded retry; absent otherwise. */
-        groundingFailure?: {
-            reason: "criteria-resolution-failed";
-        };
-        provenance: ProgrammeProvenance;
-    }>;
-    /**
-     * Lines this room usually carries that the brief never named.
-     *
-     * Offered, never imposed: a programme that proceeds without them is a legal
-     * answer. `essential` marks the ones whose absence makes the room unbuildable
-     * as specified; `ffe` marks furniture and lighting the catalogue does not
-     * serve yet, carried because a bedroom with no bed on the schedule is a gap
-     * worth seeing coming. Add one with an `add-slot` correction.
-     */
-    unstated?: Array<{
-        spaceId: string;
-        key: string;
-        name: string;
-        element: SlotElement;
-        /**
-         * Absent and `null` both mean the graph has no category for this line, and a
-         * reader must treat them as one answer.
-         *
-         * The distinction does not survive the wire. A `null` set server-side
-         * arrives as an absent key on the far side of the workflow runtime, so a
-         * client that branched on which one it received would be reading transport
-         * noise as meaning. An FF&E line the catalogue does not serve — a table
-         * lamp, bed linen, ironmongery — has no category under either reading.
-         */
-        category?: string | null;
-        weight: "essential" | "optional";
-        ffe?: boolean;
-    }>;
-}
-/**
- * Resume grammar for the `review-programme` step: drop a slot, drop a space
- * (cascade-dropping its slots), rename a space, or set a slot's category.
- *
- * `set-slot-category` (MG-954) is an action INSIDE this same corrections array;
- * its `category` must be one of the server's catalog category GROUP names (the
- * same vocabulary the payload's `category` is drawn from) or the resume is
- * refused. An empty `corrections` array stays legal however the step came to
- * suspend — the suspension discloses, it does not coerce.
- */
-export interface ReviewProgrammeResumeData {
-    corrections: Array<{
-        action: "drop-slot";
-        slotId: string;
-    } | {
-        action: "drop-space";
-        spaceId: string;
-    } | {
-        action: "rename-space";
-        spaceId: string;
-        name: string;
-    } | {
-        action: "set-slot-category";
-        slotId: string;
-        category: string;
-    }
-    /**
-     * ADD a line the brief never named — usually one the payload offered under
-     * `unstated`, though any line is legal. Every other verb here subtracts,
-     * which made the programme a ceiling: whatever the brief happened to
-     * mention was the most a schedule could ever contain.
-     *
-     * `category` may be null or absent, because some real lines — grout,
-     * ironmongery, sanitaryware — have no catalog category yet. Such a slot is
-     * skipped at retrieval with a counted `no-category` shortfall, which is the
-     * honest treatment of a line we can hold but not yet fill.
-     */
-     | {
-        action: "add-slot";
-        spaceId: string;
-        name: string;
-        element: SlotElement;
-        category?: string | null;
-    }>;
-}
-/**
- * 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: SlotId;
-    slotName: string;
-    /** How many candidates were WEIGHED, not how many qualified. */
-    considered: number;
-    top: Array<{
-        variantId: VariantId;
-        brand: string;
-        product: string;
-        imageUrl: string | null;
-        score: number;
-    }>;
-}

package/composition-types.js

@@ -1,10 +0,0 @@
-/**
- * The variation axes as a runtime array, for consumers that render an axis
- * picker. Order is the canonical presentation order.
- */
-export const VARY_AXES = Object.freeze([
-    "palette",
-    "sustainability",
-    "brandDiversity",
-    "priceTier",
-]);

package/correction-types.d.ts

@@ -1,88 +0,0 @@
-export type CorrectionJson = null | boolean | number | string | CorrectionJson[] | {
-    [key: string]: CorrectionJson;
-};
-export type CorrectionSubject = {
-    kind: "brand" | "product" | "variant";
-    id: string;
-};
-export type CorrectionTarget = {
-    kind: "identity";
-    subject: CorrectionSubject;
-} | {
-    kind: "attribute";
-    subject: CorrectionSubject;
-    blockId: string;
-    attributeId: string;
-} | {
-    kind: "relationship";
-    subject: CorrectionSubject;
-    relationship: string;
-    relatedSubject: CorrectionSubject;
-} | {
-    kind: "source_interpretation";
-    sourceMaterialId: string;
-    subject?: CorrectionSubject;
-} | {
-    kind: "missing_record";
-    url: string;
-};
-/** Caller-supplied evidence is not an independently verified graph reading. */
-export interface CorrectionEvidence {
-    state: "known" | "unknown" | "conflicting" | "not_applicable";
-    value?: CorrectionJson;
-    sourceUrl?: string;
-    note?: string;
-}
-export interface CreateCorrectionInput {
-    target: CorrectionTarget;
-    pageEvidence: CorrectionEvidence;
-    graphEvidence: CorrectionEvidence;
-    proposedChange: CorrectionJson;
-    rationale: string;
-}
-export interface Correction {
-    id: string;
-    submission: CreateCorrectionInput;
-    status: "submitted" | "in_review" | "resolved" | "withdrawn";
-    resolution: "substantiated" | "not_substantiated" | "duplicate" | "superseded" | "cannot_determine" | null;
-    createdAt: string;
-    updatedAt: string;
-    acceptedTruthChanged: false;
-}
-export interface CorrectionResponse {
-    data: Correction;
-    meta: {
-        operationId: "corrections.create";
-        requestId: string;
-        idempotency: {
-            replayed: boolean;
-        };
-    } | {
-        operationId: "corrections.get";
-        requestId: string;
-    };
-    links: {
-        self: string;
-    };
-    warnings: never[];
-}
-export interface CorrectionsListResponse {
-    data: Correction[];
-    meta: {
-        operationId: "corrections.list";
-        requestId: string;
-        page: {
-            returned: number;
-            total: {
-                value: null;
-                basis: "unavailable";
-            };
-            nextCursor: string | null;
-        };
-    };
-    links: {
-        self: string;
-        next: string | null;
-    };
-    warnings: never[];
-}

package/exploration-types.d.ts

@@ -1,118 +0,0 @@
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
-import type { VariantId } from "./identifiers.js";
-export type GraphOperator = "colourways" | "same_category" | "still_listed" | "looks_like" | "same_colour" | "pairs_with" | "often_specified_with" | "substitutes_for" | "more_durable" | "outdoor_suitable" | "lower_cost" | "more_sustainable";
-export interface GraphOperatorAvailability {
-    operator: GraphOperator;
-    operatorClass: "identity" | "perceptual" | "relational" | "spec";
-    label: string;
-    available: boolean;
-    basis: string;
-    discoverable: boolean;
-    discoveryBasis: string;
-    count?: number;
-}
-export interface GraphOperatorEvidence {
-    variantId: VariantId;
-    operators: GraphOperatorAvailability[];
-}
-export interface CandidateReadInput {
-    operator: "looks_like";
-    corpusScope?: CorpusScope;
-    /** Return up to 24 ranked candidates (default 8), from one bounded retrieval. */
-    limit?: number;
-    excludeVariantIds?: VariantId[];
-}
-export interface CandidateReadImage {
-    url: string;
-    source: "r2" | "origin";
-    /** Null means this image has not been analysed for a uniform light background. */
-    isIsolated: boolean | null;
-}
-export interface CandidateReadPaletteSwatch {
-    hex: string;
-    proportion: number;
-    name?: string | null;
-}
-export interface CandidateReadCard {
-    variantId: VariantId;
-    productId: string;
-    brandSlug: string;
-    materialBankId: string | null;
-    brand: string;
-    product: string;
-    variantName: string | null;
-    color: string | null;
-    image: CandidateReadImage | null;
-    palette: CandidateReadPaletteSwatch[];
-}
-export interface CandidateRankEvidence {
-    rank: number;
-    distance: number;
-    similarity: number;
-    basis: "active_main_image_embedding";
-    provenanceGrade: "measured";
-    displayImageMatchedEvidence: boolean | null;
-}
-export interface CandidateReadCandidate extends CandidateReadCard {
-    evidence: CandidateRankEvidence;
-    reason: string;
-}
-export interface CandidateSeedEvidence {
-    evidenceImageSha256: string;
-    displayImageSha256: string | null;
-    basis: "active_main_image_embedding";
-    provenanceGrade: "measured";
-    displayImageMatchedEvidence: boolean | null;
-}
-export interface CandidateReadReceipt {
-    operator: "looks_like";
-    corpusScope: CorpusScopeReceipt | null;
-    requestedLimit: number;
-    returnedCount: number;
-    exclusions: {
-        requested: number;
-        unique: number;
-        applied: number;
-    };
-    dedupe: {
-        retrieved: number;
-        removed: number;
-        /**
-         * How many of `removed` went because an earlier row showed the SAME
-         * PICTURE, counted apart from the id rules (MG-1917). Distinct products
-         * routinely share one photograph, so an id-only collapse returned the same
-         * image several times on one page.
-         */
-        removedBySharedImage: number;
-        truncated: number;
-        projectionMisses: number;
-    };
-    timing: {
-        /** Internal seed projection completion; not a consumer response milestone. */
-        seedProjectionMs: number;
-        retrievalMs: number;
-        projectionMs: number;
-        completeMs: number;
-    };
-}
-interface CandidateReadResponseBase {
-    seed: CandidateReadCard;
-    receipt: CandidateReadReceipt;
-}
-export type CandidateReadResponse = (CandidateReadResponseBase & {
-    status: "ready";
-    seedEvidence: CandidateSeedEvidence;
-    candidates: CandidateReadCandidate[];
-    reason: null;
-}) | (CandidateReadResponseBase & {
-    status: "no_candidates" | "no_unseen_candidates" | "bounded_retrieval_unavailable";
-    seedEvidence: CandidateSeedEvidence;
-    candidates: [];
-    reason: string;
-}) | (CandidateReadResponseBase & {
-    status: "operator_unavailable";
-    seedEvidence: null;
-    candidates: [];
-    reason: string;
-});
-export {};

package/exploration-types.js

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