Skip to content

Domain schemas

Generated from openspec/specs/domain-schemas/spec.md — edit that file, not this page.

@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.

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.

  • WHEN a domain entity such as Wall or Asset is 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 Corner or SceneItem position
  • THEN x/y (or xMm/yMm) map to scene X/Z and zMm maps 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 a SceneItem’s per-instance dimsMm override) 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.

  • WHEN a field is added to an existing entity in floorplan.ts (e.g. a new Wall property)
  • 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
  • WHEN a new top-level entity collection is added to the Floorplan document (e.g. a new array alongside sceneItems, 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.

  • WHEN deserializeFloorplan receives a document with meta.schemaVersion equal to the supported literal (1)
  • THEN it validates the document against the Floorplan schema and returns the parsed result
  • WHEN deserializeFloorplan receives a document whose meta.schemaVersion does 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 Floorplan schema (e.g. a required field is missing or a superRefine invariant fails)
  • THEN serializeFloorplan throws, 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 Pipe or Wiring MEP 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.

  • WHEN a Wall with material: 'glass' and glassPanels is validated
  • THEN the schema’s superRefine rejects the wall if any panel’s sill height plus panel height exceeds the wall’s overall height
  • WHEN a parametric carpentry cladding’s cells array is validated by the engine model layer
  • THEN it is rejected unless cells.length equals rows × 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_CATEGORIES in @ideight/domain
  • THEN the corresponding literal union in packages/api-client/src/types.ts does not automatically pick up the new value — it must be edited to match, or api-client silently 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 composition reaches status: 'ready'
  • THEN its gltfUrl is still null by 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.

  • 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