@adobe/data-ai 0.10.21 → 0.10.23

package/.claude/rules/README.md

@@ -7,43 +7,38 @@ frontmatter glob, injects them only when a matching file is in context.
 
 ## Layout mirrors the feature-folder structure
 
-The `features/` subtree mirrors the four feature layers one-to-one, so the
-guidance for a folder lives at the same path shape as the code it governs. A
-folder's own `index.md` holds just enough to understand that folder; each
-child gets its own file (recursing wherever the source tree does):
+The `features/` subtree mirrors a feature's layers one-to-one, so the guidance for a
+folder lives at the same path shape as the code it governs. A folder's `index.md`
+holds just enough to understand that folder; each child gets its own file:
 
 ```
 global/               # always-on conventions — deliberately repo-wide globs
   namespace.md  cohesion.md  type-casts.md  function-references.md  react.md
 features/
-  index.md            # the feature layering as a whole (ui → services → data)
+  index.md            # the layering as a whole: data → services → spec | ecs → ui → app
   data/
-    index.md          # data-type namespaces (foundation)
-    state.md          # the State aggregate: pure transforms & derivations
-  services/
-    index.md          # the services layer: main-service + capability contracts
-    main-service/     # the feature service (ECS implementation)
-      index.md        # the service + its layered database plugins
-      components.md  resources.md  archetypes.md
-      computed.md  indexes.md  transactions.md  services.md  actions.md
-      systems.md  conformance.md
-  ui/index.md         # UI (points to element / presentation / lazy-element file rules)
+    index.md          # pure Data declarations
+    values.md  components.md  resources.md  entities.md
+  services/index.md   # service namespaces: interface, create, createFake
+  spec/index.md       # the State spec: actions, derivations, cases (test tier)
+  ecs/
+    index.md          # the layered database plugins + MainService
+    core.md  indexes.md  transactions.md  computed.md  services.md  actions.md
+    systems.md  conformance.md
+  ui/                 # element / presentation / lazy-wrapper rules
+app.md                # src/app/: the composition root
 ```
 
-The `global/` rules (`namespace.md`, `cohesion.md`, `type-casts.md`,
-`function-references.md`, `react.md`) are **intentionally repo-wide** — their
-`paths:` globs (`**/*.ts` etc.) apply everywhere, by design, so the folder name
-makes that explicit. Alongside `features/`, the remaining rules-root `.md` files
-hold the other **cross-cutting** patterns the feature rules reference —
-`data-modelling.md`, `archetypes.md` (row iteration), `plugin-modelling.md`,
-`versioning.md` (schema history & upgrade-on-load), and
-the UI file rules (`element.md`, `lazy-element.md`, `presentation.md`). They live
-here so the bundle is self-contained; this repo symlinks them into its own
-`.claude/rules/` (as it does `features/`).
+The `global/` rules are **intentionally repo-wide** — their `paths:` globs (`**/*.ts`
+etc.) apply everywhere, by design. Alongside `features/`, the remaining rules-root
+`.md` files hold **cross-cutting** patterns the feature rules reference —
+`app.md`, `data-modelling.md`, `archetypes.md` (the query and iteration model),
+`plugin-modelling.md`, `versioning.md`, and the UI rules `element.md` and
+`lazy-element.md` (`features/ui/` holds `presentation.md` and the binding-element and
+lazy-wrapper rules). They live here so the bundle is
+self-contained; this repo symlinks them into its own `.claude/rules/`.
 
-Each rule's `paths:` glob is scoped to `**/features/*/<layer>/…`, so these
-rules apply only once an application opts into the feature-folder pattern
-(source organized under `features/<name>/`). Editing
-`features/<name>/services/main-service/core-database/components.ts` pulls in both
-`main-service/index.md` (the layer overview) and `main-service/components.md`
-(the specifics) — at creation and at every later edit.
+Each feature rule's `paths:` glob is scoped to `**/features/*/<layer>/…`, so these
+rules apply once an application organizes its source under `features/<name>/`.
+Editing `features/<name>/data/components/name.ts` pulls in both `data/index.md` and
+`data/components.md` — at creation and at every later edit.

package/.claude/rules/app.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - '**/src/app/**/*.ts'
+  - '**/src/app/**/*.tsx'
+---
+
+# src/app/ — the composition root
+
+The app root composes the features. It is the only place that knows every feature,
+and no feature imports it.
+
+```
+src/app/
+  schema.ts            the app's composed plugin (when there are several features)
+  versioning/          versions.ts + versions.test.ts (versioning.md)
+  persistence.test.ts  a save/load round-trip, when the app persists
+  *.test.ts            cross-feature tests (e.g. a todo op ignores a user id)
+  main.ts              the entry: create the database, inject services, render
+```
+
+```ts
+// schema.ts — main's full behavior, plus the schema of features that load lazily
+const appSchemaPlugin = Database.Plugin.create({
+  imports: AssignCoreDatabase.plugin,
+  extends: MainService.plugin,
+});
+export namespace AppSchema {
+  export const plugin = appSchemaPlugin;
+}
+
+// main.ts
+const service = Database.create(AppSchema.plugin, {
+  versioning: createVersionUpgrader(versions),
+  services: { game },   // a service whose `create` throws until the app injects it
+});
+```
+
+- **`imports`, not `extends`, for a lazily loaded feature**: the store knows its
+  columns up front (its data persists and loads), while its behavior, types and code
+  stay out until one of its elements connects and extends the database.
+- **Inject every service whose `create` throws** at `Database.create`. Services can't
+  be injected by a later `extend`.
+- **Versioning** folds the whole persisted schema, so it lives here, built from
+  `AppSchema.plugin`.
+- A single-feature app needs no `schema.ts`; `main.ts` uses the feature's
+  `MainService.plugin`.

package/.claude/rules/archetypes.md

@@ -4,13 +4,15 @@ paths:
   - '**/*-plugin/**/*.ts'
   - '**/*-database.ts'
   - '**/*-database/**/*.ts'
+  - '**/features/*/data/entities/**/*.ts'
+  - '**/features/*/ecs/core/**/*.ts'
 ---
 
 # Archetypes — the ECS query & iteration model
 
-General to all `@adobe/data` ECS use, feature-organized or not. The
-`core-database/archetypes.ts` *file* conventions live in
-`features/services/main-service/archetypes.md`.
+General to all `@adobe/data` ECS use, feature-organized or not. The feature file
+conventions live in `features/data/entities.md` (entity tuples) and
+`features/ecs/core.md` (archetype packing).
 
 An archetype is a named set of component keys — a kind of entity — and also a
 **query**: `queryArchetypes(include, { exclude })` (and the `select` / `count`

package/.claude/rules/data-modelling.md

@@ -1,6 +1,7 @@
 ---
 paths:
-  - '**/data/*.ts'
+  - '**/features/*/data/**/*.ts'
+  - '**/features/*/spec/**/*.ts'
 ---
 
 # Data modelling — locality of knowledge
@@ -54,15 +55,15 @@ single source of truth, not a downstream comparison flag:
   may be a plain `number` or the ECS `Entity` type (a branded `number`) — reusing
   `Entity`, and reference bundles like `CoeditingRelations.OrderedChild`, is allowed:
   they are plain value types, not ECS machinery, and keep the spec aligned with the ECS
-  (see `features/data/state.md`). Also used for deterministic-key lookups (an enum, a
-  name, a stable string).
+  (see `features/spec/index.md`). In a `State`, every `ReadonlyMap` field is an entity
+  collection; a lookup keyed by an enum or name belongs inside a value type.
 
 **Entities are keyed, never id-bearing values.** An entity's identity is its map
 key, so entity value types (`Todo`, `Bullet`) have no `id` field, and there is no
-`ReadonlySet<T>`/`ReadonlyArray<T>` *of entity values* — the single
-`ReadonlyMap<number, …>` store is the only home for entities, and queries return
-their **ids** (`ReadonlySet<number>` unordered, `ReadonlyArray<number>` ordered).
-See `features/data/state.md` for the full `State` shape.
+`ReadonlySet<T>`/`ReadonlyArray<T>` *of entity values* in `State` — a
+`ReadonlyMap<number, …>` per entity kind is the only home for entities. A derivation
+may return entity values for display (the ECS computed then emits ids, hydrated by
+conformance). See `features/spec/index.md` for the full `State` shape.
 
 These are first-class `Data` (see `features/data/index.md`) — serialize a
 Set/Map-bearing value with `Data.stringify` / `Data.parse` (plain `JSON.stringify`

package/.claude/rules/ecs.md

@@ -7,6 +7,8 @@ paths:
 
 # Database.Plugin authoring
 
+> Inside a feature (`features/<name>/ecs/`), the `features/ecs/` rules govern file layout and naming: layer files are `<layer>-database.ts` exporting an `XDatabase` namespace, and systems are camelCase. This file covers general plugin mechanics.
+
 Plugins are created with `Database.Plugin.create()` from `@adobe/data/ecs`.
 
 ## Property order (enforced at runtime)
@@ -19,7 +21,7 @@ Properties **must** appear in this exact order. All are optional.
 | 2   | `extends`      | `Plugin`                               | Base plugin to extend (types re-exported) |
 | 3   | `services`     | `(db) => ServiceInstance`              | Singleton service factories               |
 | 4   | `components`   | schema object                          | ECS component schemas                     |
-| 5   | `resources`    | `{ default: value as Type }`           | Global resource schemas                   |
+| 5   | `resources`    | schema with a `default`                | Global resource schemas                   |
 | 6   | `archetypes`   | `['comp1', 'comp2']`                   | Standard ECS archetypes                   |
 | 7   | `indexes`      | `{ key, order?, unique?, archetype? }` | Sorted/filtered entity indexes            |
 | 8   | `computed`     | `(db) => Observe<T>`                   | Computed observables                      |
@@ -99,7 +101,7 @@ const particleDataPlugin = Database.Plugin.create({
 ```
 
 - **Components**: per-entity data. Use schema imports (`Vec3`, `Vec4`, `F32` from `@adobe/data/math`) or type namespaces for custom shapes.
-- **Resources**: global state. Use **only** `{ default: value as Type }`.
+- **Resources**: global state. Every resource carries a `default` (`{ ...Boolean.schema }`, or `{ default: 'dark' as ThemeColor }` to widen a literal).
 - **Archetypes**: one per entity kind. List all components that kind requires.
 
 ---
@@ -108,23 +110,25 @@ const particleDataPlugin = Database.Plugin.create({
 
 ### components
 
-Non-persistable values (e.g. HTML elements, DOM refs) must use `ephemeral: true` on the schema.
+Non-persistable values (e.g. HTML elements, DOM refs) are session scope — spread
+`Scope.session` (`nonPersistent` + `nonShared`) into the schema.
 
 ```ts
 components: {
   layout: Layout.schema,
-  layoutElement: { default: null as unknown as HTMLElement, ephemeral: true },
+  layoutElement: { default: null as HTMLElement | null, ...Scope.session },
 },
 ```
 
 ### resources
 
-Use `as Type` to provide the compile-time type. Use `null as unknown as Type` for resources initialized later in a system initializer.
+Use `as Type` to widen a literal default to its type. A resource initialized later
+(in a system initializer) defaults to `null` widened to `Type | null`.
 
 ```ts
 resources: {
   themeColor: { default: 'dark' as ThemeColor },
-  connection: { default: null as unknown as WebSocket },
+  connection: { default: null as WebSocket | null, ...Scope.session },
 },
 ```
 
@@ -156,7 +160,7 @@ UI components that call actions must never consume returned values — see `feat
 
 ---
 
-## Naming conventions
+## Naming conventions (standalone plugins)
 
 | Item        | Convention                                            | Example                      |
 | ----------- | ----------------------------------------------------- | ---------------------------- |

package/.claude/rules/element.md

@@ -3,6 +3,7 @@ paths:
   - '**/*-element.ts'
   - '**/elements/**/*.ts'
   - '**/ui/**/*.ts'
+  - '**/ui/**/*.tsx'
 ---
 
 # Container element authoring
@@ -84,9 +85,9 @@ function **by reference**, don't wrap it in an identity arrow:
 
 ```ts
 // ❌ identity wrapper — adds nothing
-setOperation: (op) => this.service.transactions.setOperation(op),
+setOperation: (op) => this.service.actions.setOperation(op),
 // ✅ same signature, pass it through
-setOperation: this.service.transactions.setOperation,
+setOperation: this.service.actions.setOperation,
 ```
 
 Only write an arrow when you genuinely adapt the call (drop an event
@@ -117,14 +118,14 @@ transaction, or hook.
 | Framework | Container is             | Subscription hook     | Locator inputs       | Render delegation                                |
 | --------- | ------------------------ | --------------------- | -------------------- | ------------------------------------------------ |
 | Lit       | `DatabaseElement<P>`     | `useObservableValues` | `@property` only     | `presentation.render({ ...values, ...callbacks })` |
-| React     | function component       | `useObservableValues` | function arguments   | `<Presentation {...values} {...callbacks} />`    |
-| Solid     | component function       | framework-specific    | function arguments   | `<Presentation {...values} {...callbacks} />`    |
+| React     | function component       | `useObservableValues` | function arguments   | `presentation.render({ ...values, ...callbacks })` |
+| Solid     | component function       | framework-specific    | function arguments   | `presentation.render({ ...values, ...callbacks })` |
 
 Lit-only: `static styles = styles` from a sibling `*.css.ts`. `@property`
 exists *only* for locator inputs — never for state, never for derived
 values, never for parent-forwarded flags. The `P` in `DatabaseElement<P>` (and
 the `get plugin()` it returns) is the surface the element *consumes* — never the
-varying topmost-layer name (see `features/services/main-service/index.md`): `typeof
+varying topmost-layer name (see `features/ecs/index.md`): `typeof
 MainService.plugin` for a self-contained feature. **Exception:** an element
 meant to be *extended* — injected with various databases that build on this
 feature (a peer app that adds an agent, a p2p/presence build) — types on the

package/.claude/rules/features/data/components.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - '**/features/*/data/components/**/*.ts'
+---
+
+# data/components/ — one component schema per file
+
+A component is a named column of entity state. Each lives in its own file, with a
+single export: its schema. The file owns that schema object, and every other feature
+reuses it by importing the object, since the ECS compares schemas by identity.
+
+```ts
+// components/name.ts — document scope: a value type's schema, re-exported by identity
+export const name = Name.schema;
+
+// components/drag-position.ts — session scope: flags spread in the file
+export const dragPosition = { ...DragPosition.schema, ...Scope.session } satisfies Schema;
+
+// components/todo.ts — a tag
+export const todo = True.schema;
+
+// components/index.ts — the feature's vocabulary
+export const components = { todo, name, complete, order, dragPosition };
+```
+
+- **Scope** is declared per file with `Scope` from `@adobe/data/ecs`:
+
+  | scope | shared | durable | spread |
+  |---|:-:|:-:|---|
+  | document | yes | yes | nothing (the default) |
+  | settings | no | yes | `...Scope.settings` |
+  | presence | yes | no | `...Scope.presence` |
+  | session | no | no | `...Scope.session` |
+
+  On a component, the flags scope the **column**. An entity's own scope comes from
+  its marker components (`entities.md`).
+- **Every column lives here**, including implementation-only ones (a tag, a drag
+  offset). `ecs/core/` only chooses how they are packed.
+- **A tag** is a component with `True.schema`. Add one only when an entity's
+  component set would otherwise be contained in another's (`entities.md`).
+- **The name describes the role**, the schema the shape (`position` of a `Vec3`).
+- **Reserved names:** `id`, `nonPersistent`, `nonShared` (built into the ECS), and
+  `index` (it would collide with the `index.ts` barrel).
+- **A feature built on another** spreads the lower barrel first and pins that its own
+  names don't shadow it (a spread would overwrite silently):
+  ```ts
+  export const components = { ...mainComponents, user, assignees };
+  type _NoShadow = Assert<Equal<Extract<"user" | "assignees", keyof typeof mainComponents>, never>>;
+  ```
+- The barrel never includes the built-in `nonPersistent` / `nonShared` markers; the
+  ECS reserves those names and throws.

package/.claude/rules/features/data/entities.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - '**/features/*/data/entities/**/*.ts'
+---
+
+# data/entities/ — entities as component tuples
+
+An entity is declared by the components it has. Its value type is the aggregate of
+those components' types, derived rather than written:
+
+```ts
+// entities/todo.ts
+export const Todo = ["name", "complete", "order"] as const satisfies Database.EntityComponents<typeof components>;
+export type Todo = Database.EntityType<typeof components, typeof Todo>;
+// → { readonly name: string; readonly complete: boolean; readonly order: number }
+
+// entities/index.ts
+export const entities = { Todo };
+```
+
+The same-named `const` and `type` pair counts as one export.
+
+- **Declare the spec-visible entity.** Implementation-only columns (a tag, a drag
+  offset) are added when `ecs/core/` packs the archetype.
+- **An entity's kind is its component set.** Queries match every entity that has *at
+  least* the listed components. So when one entity's set is contained in another's
+  (`User = [name]` inside `Todo = [name, complete, order]`), give one of them a tag
+  (`User = ["user", "name"]`) or query with `exclude`.
+- **Entity scope** comes from the built-in marker components in the tuple:
+  `["cursor", "position", "nonPersistent", "nonShared"]` is a session entity. Markers
+  are omitted from the value type; tags are kept.
+- **A feature built on another** may declare an entity over the lower feature's
+  components, e.g. `AssignedTodo = ["name", "complete", "order", "assignees"]`.
+- **The entity takes the name.** When a value type has the same shape, don't declare
+  both: helpers on its fields go on the field types' `values/` namespaces.
+- The archetype model (supersets, base archetypes, row iteration) is in the
+  rules-root `archetypes.md`.

package/.claude/rules/features/data/index.md

@@ -3,79 +3,27 @@ paths:
   - '**/features/*/data/**/*.ts'
 ---
 
-# data/ — the data model
+# data/ — the feature's pure Data declarations
 
-The foundation layer: the feature's **data types** and the pure declarations
-over them. A data type is a readonly, serializable value suitable for persistence
-and for communication over the wire — no functions, no handles, just plain data:
-JSON primitives/arrays/objects plus `ReadonlySet`, `ReadonlyMap`, and `Blob`
-(serialize a Set/Map-bearing value with `Data.stringify` / `Data.parse`). A `data/` **type** depends on nothing but `@adobe/data` and other
-`data/` types, and needs no knowledge of anything built on top of it. The
-**transitions** over those types are less restricted: when one injects a service
-it may import freely from `services/` — the service type and any utilities its
-namespace exposes (see `state.md`). What it must **never** touch is `ui/`:
-`data/` never depends on presentation — that isolation is strict and inviolable.
-Only *services themselves* are never authored here; that is what makes this the
-value-type layer.
+The foundation layer. Everything here is a declaration about plain, serializable
+Data: JSON primitives/arrays/objects plus `ReadonlySet`, `ReadonlyMap`, and `Blob`
+(serialize with `Data.stringify` / `Data.parse`). No functions in values, no services,
+no ECS machinery. The one exception is a session-scoped resource holding a runtime
+handle (a canvas, a live database): `{ default: null as Handle | null, ...Scope.session }`.
+It depends only on `@adobe/data` and the `data/` of features this one builds on.
 
-Each data type is its own namespace folder (see `global/namespace.md`), holding
-its hand-authored type, its (optional, matching) schema, and its pure
-synchronous helpers together:
-
-```
-data/player-mark/
-  player-mark.ts   # HAND-AUTHORED type + `export * as PlayerMark from "./public.js"`
-  schema.ts        # (optional / later) schema matching the type, pinned via Assert<Equal<…>>
-  public.ts        # re-exports schema + helpers
-  is.ts  values.ts  opponent.ts  …   # one pure helper per file
 ```
-
-- The **type is authored by hand** in `<type>.ts` — the readable source of
-  truth. Write it with the richest types available (`F32`, `Vec3`, unions,
-  branded aliases) so members carry their semantic meaning and get strong
-  IntelliSense / hover docs.
-- The **schema is derived from the type, not the reverse.** It is written to
-  match the type and **pinned** to it with a compile-time assertion so the two
-  cannot drift (see below). A field typed as a branded primitive reuses that
-  type's schema — `F32` → `F32.schema`, `Vec3` → `Vec3.schema`.
-- **Schemas are optional until a runtime boundary needs one.** A pure `data/`
-  type is complete with `<type>.ts` alone. The schema is added only when
-  persistence, the wire, or an ECS component/resource requires it — and is
-  typically written by the agent in a later phase (e.g. when implementing the
-  ECS), not by the human up front.
-- Helpers are synchronous and pure; each has a sibling `*.test.ts`.
-- Objects of only 32-bit numeric values / sub-structs: the schema uses
-  `Schema.fromStructProperties` (guarantees a valid struct schema, stored in
-  linear memory).
-
-## Pinning the schema to the type
-
-The type is written first and by hand; the schema is written to match it and
-is locked to it at compile time, so schema authoring (whenever it happens)
-cannot silently drift from the type readers rely on.
-
-```ts
-// player-mark/player-mark.ts — HAND-AUTHORED, the source of truth
-export type PlayerMark = 'X' | 'O';
-export * as PlayerMark from './public.js';
-
-// player-mark/schema.ts — written to MATCH the type (often later, by the agent)
-import { Schema } from '@adobe/data/schema';
-import type { Assert, Equal } from '@adobe/data/types';
-import type { PlayerMark } from './player-mark.js';
-
-export const schema = { type: 'string', enum: ['X', 'O'] } as const satisfies Schema;
-
-// Compile-time pin: fails to build if schema and type diverge.
-type _Pin = Assert<Equal<Schema.ToType<typeof schema>, PlayerMark>>;
+data/
+  values/<type>/        Data types + pure helpers   (values.md)
+  components/<name>.ts  one component schema each   (components.md)
+  resources/<name>.ts   one resource schema each    (resources.md)
+  entities/<entity>.ts  component-name tuples       (entities.md)
 ```
 
-The `Assert<Equal<…>>` line is the whole safety net: `Schema.ToType<typeof
-schema>` must be exactly the hand-authored type (including readonly/optional),
-or the file does not compile. `Schema.ToType` is used **only** inside the
-assertion — never as the exported type. Consumers always import the
-hand-authored `PlayerMark`.
+Order within `data/`: `values → components / resources → entities`. A value never
+imports a component, resource or entity. Where a value helper needs an entity's
+fields, it takes them structurally
+(`Iterable<{ readonly mark: PlayerMark; readonly cellIndex: CellIndex }>`).
 
-One folder is special: **`data/state/`** holds the feature's single `State`
-aggregate and its pure transforms/derivations (its own rule, `state.md`);
-the individual type folders here are its building blocks.
+Components and resources share **one namespace** across every feature in an app:
+a name is one column or one resource, never both, and has one owning feature.

package/.claude/rules/features/data/resources.md

@@ -0,0 +1,34 @@
+---
+paths:
+  - '**/features/*/data/resources/**/*.ts'
+---
+
+# data/resources/ — one resource schema per file
+
+A resource is a singleton value: one per database. Each lives in its own file, with a
+single export: its schema, which must carry a `default`.
+
+```ts
+// resources/display-completed.ts
+export const displayCompleted = { ...Boolean.schema, ...Scope.settings } satisfies ResourceSchema;
+
+// resources/selected-todo.ts — an entity reference
+export const selectedTodo = { ...Entity.schema, default: Entity.none, ...Scope.session } satisfies ResourceSchema;
+
+// resources/count.ts — a primitive needs no values/ type
+export const count = { type: "number", default: 0 } as const satisfies ResourceSchema;
+
+// resources/index.ts
+export const resources = { displayCompleted, selectedTodo };
+```
+
+- **`satisfies ResourceSchema`** checks the `default` at the declaration.
+- **Scope** is spread from `Scope`, as for components (`components.md`). On a resource
+  the flags also place its singleton entity in that quadrant, so a `session` resource
+  resets on reload and a `settings` one stays on the device.
+- **An entity reference** spreads `Entity.schema`. The `entity` mark is how
+  conformance knows the value is an id.
+- Every singleton in the spec's `State` is a resource of the same name
+  (`spec/index.md`), including a single game object like a ship or player.
+- A resource and a component never share a name (`index.md`).
+- There is only one instance, so never choose a struct schema for efficiency here.

package/.claude/rules/features/data/values.md

@@ -0,0 +1,36 @@
+---
+paths:
+  - '**/features/*/data/values/**/*.ts'
+---
+
+# data/values/ — Data types and pure helpers
+
+Each Data type is its own namespace folder (`global/namespace.md`): its hand-written
+type, its schema pinned to it, and its pure synchronous helpers.
+
+```
+data/values/player-mark/
+  player-mark.ts   # HAND-WRITTEN type + `export * as PlayerMark from "./public.js"`
+  schema.ts        # schema matching the type, pinned with Assert<Equal<…>>
+  public.ts        # re-exports schema + helpers
+  opponent.ts  opponent.test.ts  …   # one pure helper per file, each tested
+```
+
+- **Write the type by hand** in `<type>.ts`. It is the readable source of truth; use
+  the richest types available (`F32`, `Vec3`, unions, branded aliases).
+- **Write the schema to match, and pin it**, so the two can't drift:
+  ```ts
+  // schema.ts
+  export const schema = { type: "string", enum: ["X", "O"] } as const satisfies Schema;
+  type _Pin = Assert<Equal<Schema.ToType<typeof schema>, PlayerMark>>;
+  ```
+  `Schema.ToType` yields `readonly` properties and arrays, so write the type
+  `readonly` too. `Schema.ToType` appears only in the pin, never as the exported type.
+- **Add a schema when something needs one**: a component, a resource, persistence, or
+  the wire. A type used only by the spec may have none.
+- **Helpers are synchronous and pure**, each with a sibling `*.test.ts`. They are the
+  home for logic the spec and the ECS share.
+- **A helper-only namespace** (`motion`, `collision`) with no type of its own also
+  lives here.
+- Objects of only 32-bit numeric values or sub-structs use
+  `Schema.fromStructProperties` (linear-memory storage).

package/.claude/rules/features/ecs/actions.md

@@ -0,0 +1,31 @@
+---
+paths:
+  - '**/features/*/ecs/actions/**/*.ts'
+---
+
+# ecs/actions/ — the operations the app performs
+
+One action per file: a function taking the whole database and Data args. Actions are
+the app-facing operations: the UI calls `service.actions.*`, and each spec action
+conforms against the action of the same name.
+
+```ts
+export const createRandomTodo = async (db: ServiceDatabase) => {
+  const timing = await db.services.analytics.randomTodoRequested();
+  const name = await db.services.nameGenerator.generateName();
+  db.transactions.createTodo({ name });
+  db.services.analytics.randomTodoAdded({ timing, name });
+};
+```
+
+- **Every spec action has a same-named action**, even when it only forwards to one
+  transaction. When the UI drives a richer op (a streamed drag), add a thin action for
+  the spec op as well (`reorderTodo` beside `dragTodo`).
+- **Type `db` on the lowest layer** exposing what it calls, usually `ServiceDatabase`.
+  Never the action layer itself.
+- **Call services here**: await ports, sequence calls, time a slow call. Then commit
+  through **at most one transaction**, so undo/redo stays one step per operation.
+- **Fire-and-forget.** Results flow back through observables, never return values.
+- **Read current state synchronously** from the store (`db.resources`, `db.read`,
+  `db.select`), never from a cached computed, which refreshes only on commit.
+- The `index.ts` barrel feeds the `actions` facet.

package/.claude/rules/features/ecs/computed.md

@@ -0,0 +1,31 @@
+---
+paths:
+  - '**/features/*/ecs/computed/**/*.ts'
+---
+
+# ecs/computed/ — derived observable values
+
+One derived value per file: a `cached` function of a database layer returning an
+`Observe`. Each spec derivation conforms against the computed of the same name.
+
+```ts
+export const status = cached((db: IndexDatabase) =>
+  Observe.withFilter(db.observe.resources.board, BoardState.deriveStatus),
+);
+```
+
+- **Wire `data/values/` helpers** to the minimal observables they read. The spec
+  derivation calls the same helper, so the two agree by construction. Never import
+  from `spec/`.
+- **Observe every input.** A computed that reads two resources must observe both, or
+  it goes stale when only one changes.
+- **Performance picks the wiring.** Hand-wire minimal resource or index reads on hot
+  or large paths. For "how many" use `db.observe.count(components, { where })`, not a
+  selected array's `.length`.
+- **An entity-list computed emits ids.** Name it in the implementation's `hydrate`, so
+  conformance maps each id through `toData`.
+- A computed with no spec derivation (one helper applied to one field) is covered by
+  that helper's unit test.
+- **Type `db` on the lowest layer** that exposes what it reads. A computed may read
+  service observables (`db.services.*`), since services sit below it.
+- The `index.ts` barrel feeds the `computed` facet.