Domain schemas
Generated from
openspec/specs/domain-schemas/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”@ideight/domain is the single source of truth for every persisted data shape in Tinkerspace: the floorplan document (walls, openings, placed furniture, cladding, MEP) and the catalog asset row. It guarantees that one zod schema per entity is both the runtime validator and the compile-time type, and that this schema is what every downstream layer (engine Y.Doc, API JSONB columns, web editor) ultimately validates against or is type-checked from.
Requirements
Section titled “Requirements”Requirement: Schema-derived types
Section titled “Requirement: Schema-derived types”The system SHALL derive the TypeScript type for every domain entity from its zod schema (z.infer), so validator and type can never drift apart.
Scenario: Type follows schema
Section titled “Scenario: Type follows schema”- WHEN a domain entity such as
WallorAssetis exported from@ideight/domain - THEN its TypeScript type is
z.infer<typeof Wall>(or equivalent), not an independently hand-written interface
Requirement: Millimetre units and Y-up coordinates
Section titled “Requirement: Millimetre units and Y-up coordinates”The system SHALL express every persisted length, position, and dimension in millimetres, and SHALL treat the floor plane as (x, y) with height on a separate axis, consistent with the engine’s Y-up Three.js scene.
Scenario: Plan coordinates map to scene axes
Section titled “Scenario: Plan coordinates map to scene axes”- WHEN the engine builds a Three.js mesh from a
CornerorSceneItemposition - THEN
x/y(orxMm/yMm) map to scene X/Z andzMmmaps to scene Y (height above floor), and all values are read as millimetres with no unit conversion needed before that mesh-build step
Scenario: Asset scale is authoritative over GLB units
Section titled “Scenario: Asset scale is authoritative over GLB units”- WHEN a catalog asset’s GLB is loaded (Meshy output is unitless)
- THEN the renderer re-fits the geometry to
Asset.dims(or aSceneItem’s per-instancedimsMmoverride) rather than trusting any scale baked into the GLB file
Requirement: Additive-only schema evolution
Section titled “Requirement: Additive-only schema evolution”The system SHALL evolve the Floorplan schema only by adding optional fields or optional collections, and SHALL NOT make a previously-optional field required or remove a field that persisted data may still contain.
Scenario: New field on an existing entity
Section titled “Scenario: New field on an existing entity”- WHEN a field is added to an existing entity in
floorplan.ts(e.g. a newWallproperty) - THEN it is declared optional with a documented default, so a Y.Doc or DB JSONB blob serialized before the field existed still parses successfully
Scenario: New collection on Floorplan
Section titled “Scenario: New collection on Floorplan”- WHEN a new top-level entity collection is added to the
Floorplandocument (e.g. a new array alongsidesceneItems,rooms,claddings) - THEN it is declared as an optional array on
Floorplan, so documents saved before the collection existed remain valid
Requirement: Locked schema version with rejection of unknown versions
Section titled “Requirement: Locked schema version with rejection of unknown versions”The system SHALL stamp every Floorplan document with meta.schemaVersion and SHALL refuse to deserialize a document whose schemaVersion does not match the version the running code understands.
Scenario: Current version parses
Section titled “Scenario: Current version parses”- WHEN
deserializeFloorplanreceives a document withmeta.schemaVersionequal to the supported literal (1) - THEN it validates the document against the
Floorplanschema and returns the parsed result
Scenario: Unknown version is rejected
Section titled “Scenario: Unknown version is rejected”- WHEN
deserializeFloorplanreceives a document whosemeta.schemaVersiondoes not equal the supported literal - THEN it throws rather than attempting to parse or coerce the document
Requirement: Serialization boundary enforces schema validity
Section titled “Requirement: Serialization boundary enforces schema validity”The system SHALL validate a floorplan against the Floorplan schema whenever it crosses the engine’s Y.Doc ⇄ persisted-document boundary, throwing on any violation rather than silently persisting or loading invalid state.
Scenario: Save-time validation failure surfaces
Section titled “Scenario: Save-time validation failure surfaces”- WHEN the engine’s live Y.Doc model is serialized for save/publish and the resulting snapshot does not satisfy the
Floorplanschema (e.g. a required field is missing or asuperRefineinvariant fails) - THEN
serializeFloorplanthrows, and the invalid state is not persisted
Requirement: Schema-derived defaults on parse
Section titled “Requirement: Schema-derived defaults on parse”The system SHALL apply zod .default(...) values during parsing for fields that declare them, so that parsed output can carry fields not present in the original persisted input.
Scenario: MEP item gains defaulted fields on parse
Section titled “Scenario: MEP item gains defaulted fields on parse”- WHEN a
PipeorWiringMEP item is parsed from a persisted document that omits a field with a.default(...) - THEN the parsed result includes that field populated with its default value, even though the raw input did not contain it
Requirement: Structural invariants beyond shape validation
Section titled “Requirement: Structural invariants beyond shape validation”The system SHALL enforce cross-field structural invariants that a plain shape check cannot express, at both the schema layer (via superRefine) and the engine model layer where the invariant depends on runtime state.
Scenario: Glass panel geometry invariant
Section titled “Scenario: Glass panel geometry invariant”- WHEN a
Wallwithmaterial: 'glass'andglassPanelsis validated - THEN the schema’s
superRefinerejects the wall if any panel’s sill height plus panel height exceeds the wall’s overall height
Scenario: Carpentry grid invariant
Section titled “Scenario: Carpentry grid invariant”- WHEN a parametric
carpentrycladding’scellsarray is validated by the engine model layer - THEN it is rejected unless
cells.lengthequalsrows × columns, an invariant the domain schema alone does not check
Requirement: Enum single-sourcing with explicit client mirroring
Section titled “Requirement: Enum single-sourcing with explicit client mirroring”The system SHALL define category/status/visibility enums for catalog assets in @ideight/domain as the sole source of truth, while packages/api-client (a leaf package that intentionally does not depend on @ideight/domain) mirrors the enum values as string-literal unions that must be updated by hand when the source enum changes.
Scenario: New asset category requires client mirror update
Section titled “Scenario: New asset category requires client mirror update”- WHEN a new value is added to
ASSET_CATEGORIESin@ideight/domain - THEN the corresponding literal union in
packages/api-client/src/types.tsdoes not automatically pick up the new value — it must be edited to match, orapi-clientsilently drifts from the domain enum
Requirement: Composition assets omit ready geometry
Section titled “Requirement: Composition assets omit ready geometry”The system SHALL represent composite catalog assets (a non-null Asset.composition, built from CraftChild children) with gltfUrl: null, regardless of the asset’s status, because the renderer composes them from their children’s GLBs at render time rather than from geometry of their own.
Scenario: Renderer must not assume geometry from status alone
Section titled “Scenario: Renderer must not assume geometry from status alone”- WHEN an asset with a non-null
compositionreachesstatus: 'ready' - THEN its
gltfUrlis stillnullby design, and any renderer or consumer must not assume a ready asset carries directly loadable geometry
Requirement: A furnishing station either builds its piece or buys it
Section titled “Requirement: A furnishing station either builds its piece or buys it”A furnishing station SHALL declare exactly one source for its piece: a catalogue query, or a build specification naming a carpentry preset and the run’s sizing bounds. A station declaring both, or neither, SHALL be rejected at the schema boundary rather than resolved by precedence at runtime.
A build specification MAY express its length as a share of the clear wall it is given in addition to absolute bounds. Where both are present the absolute bounds are the guards: the share decides how much of the wall the run is meant to occupy, and the minimum and maximum keep it from becoming a stub or overrunning what the preset can build. Expressing intent as a share is what lets one predesign serve unit types of different sizes; an absolute length tuned against one wall silently means something else against another.
Scenario: A build station validates without a catalogue query
Section titled “Scenario: A build station validates without a catalogue query”- WHEN a recipe declares a station whose piece is built, with a preset id and sizing bounds and no catalogue query
- THEN the recipe validates
Scenario: A station declaring both sources is rejected
Section titled “Scenario: A station declaring both sources is rejected”- WHEN a recipe declares a station carrying both a catalogue query and a build specification
- THEN validation fails, rather than one source silently winning
Scenario: Existing catalogue stations are unaffected
Section titled “Scenario: Existing catalogue stations are unaffected”- WHEN a recipe authored before this change — every station carrying a catalogue query and no build specification — is validated
- THEN it validates unchanged, because the build field is optional
Requirement: A build declares which standard shape it takes
Section titled “Requirement: A build declares which standard shape it takes”A build specification MAY declare the shape its run takes across the room’s walls, from a closed set of standard layouts: a single wall, an L across two adjoining walls, a U across three, or a galley across two opposite walls. The set SHALL be closed, and a value outside it SHALL be rejected at the schema boundary.
A shape is a standard arrangement chosen from a list, not a path drawn by hand. Admitting arbitrary shapes here would put a drawing tool in a data file, and the product already has a drawing tool for the case a designer wants something else.
The declaration SHALL be optional, and its absence SHALL mean a single wall — so a recipe set written before shapes existed keeps its behaviour exactly.
Scenario: The standard shapes validate
Section titled “Scenario: The standard shapes validate”- WHEN a build declares a single, L, U or galley shape
- THEN the recipe validates
Scenario: A shape outside the set is refused
Section titled “Scenario: A shape outside the set is refused”- WHEN a build declares a shape the product has no layout for
- THEN validation fails, rather than the shape being ignored at runtime and the recipe quietly producing a single run
Scenario: A build with no shape is unchanged
Section titled “Scenario: A build with no shape is unchanged”- WHEN a build written before shapes existed is validated and run
- THEN it validates, and produces the one run against one wall that it always did
Scenario: A build without a wall share is still valid
Section titled “Scenario: A build without a wall share is still valid”- WHEN a published recipe set written before the share existed is read
- THEN it validates and behaves exactly as it did, because the share is optional and its absence means “take what the wall allows, up to the maximum”
Scenario: A wall share outside a sensible range is rejected
Section titled “Scenario: A wall share outside a sensible range is rejected”- WHEN a build declares a share that is not greater than zero, or greater than the whole wall
- THEN validation fails, rather than producing a run of zero bays or one that cannot fit
Requirement: A scene item records whether the system placed it
Section titled “Requirement: A scene item records whether the system placed it”A placed scene item SHALL be able to record that a furnishing generation created it, and which recipe and station it served. The field SHALL be optional: its absence means the item was placed by hand, which is also the correct reading of every item stored before this field existed.
This records origin only. It SHALL NOT carry the item’s position, its slot, or any other layout decision — those live in the plan and in the item’s own pose, and a second copy of them would be a second answer to the same question.
Scenario: A generated item names the station it came from
Section titled “Scenario: A generated item names the station it came from”- WHEN a furnishing generation places an item
- THEN the stored item records the recipe and station that produced it
Scenario: A hand-placed item carries no origin
Section titled “Scenario: A hand-placed item carries no origin”- WHEN a designer places or drags an item themselves
- THEN the item records no generating station, and a later re-plan therefore treats it as the designer’s to keep
Scenario: Items stored before the field existed still parse
Section titled “Scenario: Items stored before the field existed still parse”- WHEN a floorplan saved before this change is loaded
- THEN every scene item in it validates, and each is read as hand-placed
Scenario: Moving a generated item by hand makes it the designer’s
Section titled “Scenario: Moving a generated item by hand makes it the designer’s”- WHEN a designer moves an item that a generation had placed
- THEN it no longer counts as the system’s to re-place, so a later arrangement will not move it back