@adobe/data-ai 0.9.83 → 0.9.86

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

@@ -0,0 +1,71 @@
+---
+paths:
+  - '**/features/*/ecs/**/conformance/**/*.ts'
+---
+
+# ecs/conformance/ — spec↔implementation projection (test-only)
+
+The bridge that keeps the ecs implementation honest against the `data/` spec.
+**Test-only**: imported solely by `*.test.ts` and in no facet barrel, so it never
+enters the runtime bundle (test-support may import the test framework — it is not
+a runtime declaration). **Never call `fromState` / `toState` (or a shared
+clear-all + reinsert helper used only for that projection) from systems,
+transactions, or UI** — that is a full-store rewrite, not an O(1) ECS update.
+**Feature-level**: one projection per feature, reused by every transaction test
+and the system tick-loop test — don't nest it under `transaction-database/`.
+
+The property, per `{ before, args, after }` case:
+`toState(apply(fromState(before), args)) ≡ spec(before, args)`.
+
+Conformance test-support splits by concern along the layer boundary:
+
+- **Store-side, here in `ecs/conformance/`:**
+  - `from-state.ts` → `fromState(store: CoreDatabase.Store, state: State): void`
+    seeds the store (clear tail→head → insert entities → set resources) to a `State`.
+  - `to-state.ts` → `toState(store): State` reads the store back — each kind via
+    its full named-archetype component set, so the shapes never alias.
+  - `expect-conforms.ts` → **one export, `expectConforms({ cases, spec, apply })`**.
+    Per case it asserts `spec(before, args) ≡ after` (keeps the case honest), then
+    `fromState(before)` → `apply(store, args)` → `toState ≡ after`.
+- **Spec-side, in `data/state/`** (State values, no store — so both the `data/`
+  transform tests and this runner import them without a layer violation):
+  `conformance-case.ts` (`ConformanceCase<Args>`), the `<transform>.cases.ts`
+  cases, and `expect-state-matches.ts` (State equality).
+
+## No cast — build on `Store.create`, not a `Database`
+
+A **transaction is `(store, args) => void`**, so transaction conformance needs no
+`Database`: `Store.create(<schema-layer>.plugin)` returns a cast-free writable
+`CoreDatabase.Store` — pass the plugin directly, `Store.create` reads its schema
+facets. Source it from the **lowest layer that declares all the schema** —
+`IndexDatabase`, or `CoreDatabase` if the feature has no indexes — **not**
+`FeatureDatabase`: the store needs only schema, and the behaviour layers
+(transactions / computed / systems) add none.
+`fromState`/`toState`/`apply` all operate on it, and `apply` calls the **raw
+transaction function** directly:
+
+```ts
+expectConforms({ cases, spec: State.hitTarget, apply: (store, args) => hitTarget(store, args) });
+```
+
+A mutation addressed by **entity id** resolves its entities from the seeded store
+inside `apply` (the shared cases stay spec-shaped). Reads never need a cast —
+`Database extends ReadonlyStore`.
+
+**Systems** are the one exception: they run via `db.system.functions` and reach
+the store through the db. Get that writable view with the library lens —
+`Database.toSystemDatabase(Database.create(plugin))` (the widening twin of
+`UIService.restrict`, cast-free) — then `fromState(db.store, before)` → drive one
+frame → `toState(db.store)`. Test **selection/detection** logic (which entities
+interact) separately, with seeded edge-case geometries.
+
+## State equality — ordering vs precision, kept separate
+
+`expect-state-matches.ts` compares with **`equalsUnordered`** from `@adobe/data`
+(arrays as multisets — archetype hole-fill reorders rows — objects key-order
+independent). Absorb float noise — F32↔f64 storage rounding **and** trig epsilon
+(a quadrant `cos`/`sin` yields ~3e-15 where a case authors `0`) — by quantizing
+every number on both sides onto a small grid (`Math.round(Math.fround(n)*k)/k`)
+before comparing. Ordering and precision stay separate concerns. **Guard the
+projection itself** with one `fromState → toState` identity test on
+representative states.

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

@@ -0,0 +1,179 @@
+---
+paths:
+  - '**/features/*/ecs/**/*.ts'
+---
+
+# ecs/ — the Entity-Component-System layer
+
+Everything ECS-specific lives here: the schema that stores `data/` types as
+entity state (`core-database/`), the derived and mutating logic over it
+(`indexes/`, `transactions/`, `computed/`), the database-bound service factories
+(`services/`), the async orchestrators (`actions/`), and the layered plugins
+that compose it all.
+
+The distinction from `data/`: a `data/` type is ECS-agnostic (a plain
+serializable value); an ECS construct is *how that type is stored and operated
+on* inside a database. `mark: PlayerMark.schema` is not a data-model fact — it
+is "the ECS keeps a PlayerMark here".
+
+## The core schema — `core-database/`
+
+A feature's whole schema — every component, resource, and archetype — lives in
+one `core-database/` folder: `core-database.ts` plus one file per facet the
+feature uses (all three facets are optional on `Database.Plugin.create`):
+
+```
+ecs/core-database/
+  core-database.ts   # Database.Plugin.create({ components?, resources?, archetypes? }) → CoreDatabase
+  components.ts      # export const components = Database.components({ … })
+  resources.ts       # export const resources  = Database.resources({ … })
+  archetypes.ts      # export const archetypes = Database.archetypes(components, { … })
+```
+
+`core-database.ts` is a thin assembler; each facet file exports one typed object
+built by a `Database.*` helper. No per-item files, no barrels. Create only the
+facet files the feature needs — a singleton feature with no entities is just
+`resources.ts` + `core-database.ts` (no empty `components({})` boilerplate).
+
+### Schema scopes
+
+State divides on two orthogonal axes — **scope** (shared with peers vs. local to
+this client) and **lifetime** (durable across reloads vs. ephemeral) — giving
+four scopes, each stamping a flag pair:
+
+| scope | shared? | durable? | flags |
+|-------|:--:|:--:|-------|
+| **document** | yes | yes | — |
+| **settings** | no | yes | `nonShared` |
+| **presence** | yes | no | `nonPersistent` |
+| **session** | no | no | `nonPersistent` + `nonShared` |
+
+`Database.components` / `Database.resources` group declarations by scope and
+stamp the flags. Every scope key is optional — declare only the ones you use
+(most features are document-only):
+
+```ts
+// components.ts
+export const components = Database.components({
+  document: { todo: True.schema, name: Name.schema, complete: Boolean.schema },
+  session:  { dragPosition: DragPosition.schema },   // omit settings / presence
+});
+
+// resources.ts — entries must carry a `default` (enforced at the call)
+export const resources = Database.resources({
+  settings: { displayCompleted: Boolean.schema },
+});
+```
+
+A component/resource *value* is a plain `data/`-schema re-export (or a small
+inline literal); its scope — and therefore its flags — is stated only by which
+group it sits in. Hover a scope key for its meaning. The database does not yet
+act on these flags (see the `nonShared` schema note); they model
+shared/local × durable/ephemeral now, and the durable-shared subset
+(`document`) is the set a bare store could be rebuilt from for reconciliation.
+
+**Shared columns live in `data/`.** A column two features share (e.g. a `name`
+on both todos and users) is a `data/` type both reference by identity
+(`Name.schema`), so `combinePlugins` dedupes it. Only the `document` scope
+preserves schema identity (it applies no flags) — never share a
+settings/presence/session column across features by identity.
+
+### Archetypes
+
+`archetypes.ts` declares the feature's entity shapes with
+`Database.archetypes(components, { … })`, which validates every key against the
+component map and preserves each archetype's literal tuple — no per-archetype
+`as const`. Archetypes are a packing convenience, not serialized data; one may
+span scopes (a document entity with an ephemeral `dragPosition` slot). An
+archetype mirroring a `data/` row type carries a private compile-time
+drift-guard (see `archetypes.md`).
+
+## Layered composition (behaviour)
+
+Above the schema, behaviour is a chain of `Database.Plugin`s, each its own
+**namespace folder** — `<layer>-database/` holding the eponymous
+`<layer>-database.ts` (the plugin, which `extends` the previous layer) plus the
+facet folder it adds. **Name each layer for the facet it adds — never for the
+feature or app.** A feature creates only the layers it uses:
+
+```
+ecs/
+  core-database/            # the schema (above)
+  index-database/           # extends core;        indexes/
+  transaction-database/     # extends index;       transactions/
+  computed-database/        # extends transaction; computed/
+  service-database/         # extends computed;     services/
+  action-database/          # extends service;      actions/
+```
+
+Each exports a namespace mirroring the plugin — the composed object is a
+`Database` (the `@adobe/data` term) even though the folder is `ecs/`:
+
+```ts
+export type IndexDatabase = Database.Plugin.ToDatabase<typeof indexDatabasePlugin>;
+export namespace IndexDatabase {
+  export const plugin = indexDatabasePlugin;
+  export type Store = Database.Plugin.ToStore<typeof indexDatabasePlugin>;
+}
+```
+
+### The assembled database — `FeatureDatabase`
+
+*Which* layer is topmost varies with the facets a feature uses (computed /
+service / action / system). Consumers — `ui/`, the app entry, `ecs/conformance/`
+— need the *whole* feature database but must not name that layer, or adding or
+dropping a layer rewrites them all. Alias it once:
+
+```ts
+// ecs/feature-database.ts
+export { SystemDatabase as FeatureDatabase } from "./system-database/system-database.js";
+```
+
+Every consumer references **`FeatureDatabase`** (`.plugin`, `.Store`) — never the
+topmost layer. Add or drop a layer → change only this one line.
+
+**Cross-feature naming.** Inside a feature the core and assembled databases are
+the bare `CoreDatabase` / `FeatureDatabase`. When *another* feature or package
+imports one — a peer built on it, the base `imports` a peer's `core-database`, a
+downstream package — reference it **feature-qualified**: `<Feature>CoreDatabase`
+/ `<Feature>Database`, re-exported so from the feature's barrel
+(`export { CoreDatabase as TodoCoreDatabase } from "…/core-database.js"`) — so
+two features' `CoreDatabase`s never collide.
+
+## What each layer takes as input
+
+- **`plugin`** — every layer `extends` the previous layer's `plugin`; that is
+  the one universal thread up the chain.
+- **`Store`** (via `ToStore`) — used *only* by **transactions** (`t:
+  <Layer>.Store`). A store carries the index handles and the initiating
+  `userId`, so a store *is* the transaction context; there is no separate
+  transaction-context type. Use **`CoreDatabase.Store`** for a transaction that
+  reads/writes entities, resources, or archetypes; **`IndexDatabase.Store`** the
+  moment it reads an index.
+- **the whole `Database`** — **computed**, **services**, and **actions** each
+  take `db: <Layer>` (the lowest layer whose database exposes what they
+  read/call): computed reads `db.observe.*`; services read observables and call
+  transactions; actions call `db.services.*` then `db.transactions.*`.
+
+Each subfolder has its own rule. Modelling a plugin's authored vs. derived
+surface is covered by `plugin-modelling.md`.
+
+## Facets are flat until they aren't
+
+A **behavioural** facet folder (`indexes/`, `transactions/`, `computed/`,
+`actions/`) holds one file per item plus an `index.ts` barrel — flat while that
+reads well, roughly up to half a dozen items. When a cohesive cluster grows past
+that, promoting it into a themed subfolder with its own `index.ts` (re-exported
+by the facet barrel) is a standard move — only once the folder actually feels
+crowded:
+
+```
+transactions/
+  order/                 # a cohesive cluster: fractional-ordering helpers
+    index.ts  next-order.ts  normalize-order.ts  select-ordered-todos.ts
+  create-todo.ts  drag-todo.ts  …
+```
+
+The **schema** facets (components / resources / archetypes) are *single files*
+in `core-database/`, not folders. A whole feature should stay small enough that
+subfoldering rarely bites — grow by adding features, not by bloating one.

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

@@ -0,0 +1,63 @@
+---
+paths:
+  - '**/features/*/ecs/**/indexes/**/*.ts'
+---
+
+# database/indexes/ — ECS indexes
+
+One index descriptor per file: an object `satisfies CoreDatabase.Index` that
+tells the store to maintain a lookup keyed on a component, so queries and
+computed values can find entities without scanning.
+
+```ts
+import type { CoreDatabase } from "../../core-database/core-database.js";
+
+export const byComplete = {
+    key: "complete",
+} as const satisfies CoreDatabase.Index;
+```
+
+`CoreDatabase.Index` is bound to every component (all scopes live in the one
+`core-database`). Archetype-scoped indexes carry an extra `archetype` field the
+`Index` helper can't express, so declare those with a bare `as const` (no
+`satisfies`) and let `index-database.ts`'s `create()` validate them.
+
+Name the export for what it indexes (`byComplete`, `byOwner`). An
+`index.ts` barrel re-exports every index; it feeds the `indexes` facet on
+`index-database.ts`.
+
+## Discrete keys only — derive a bucket for spatial / range queries
+
+An index matches keys by **equality on a discrete value**, so a continuous or
+range-valued column (a `position`, a timestamp, a score) can't be indexed as-is
+— `{ key: "position" }` buckets by exact value and finds nothing near a point.
+Derive a discrete **bucket key** — but prefer a **computed-key extractor**
+(`key: { cell: (c) => cellKey(c.position!) }`, naming the read columns in
+`components`) over storing the derived key as its own component. The extractor
+recomputes the key from its source columns, so the index stays correct with no
+maintenance; a stored bucket column must instead be recomputed at every
+insertion/update site (or by a system) and silently drifts if one is missed. The
+derivation itself is a pure `data/` helper.
+
+Bucketed broad-phase only pays off at scale (hundreds+ candidates per query);
+below that a linear scan over an archetype wins. Index when the scan is a
+**proven** cost, not preemptively.
+
+## Scoping, arrays, and many-to-many
+
+- **Coverage is by columns.** An index applies to every archetype whose
+  components are a superset of the key's columns. Two archetypes that share a
+  column are both indexed — so a unique index keyed on a shared column (e.g.
+  `name`, held by both users and todos) would collide.
+- **Scope with `archetype`.** `{ key: "name", archetype: "User", unique: true }`
+  restricts the index to one archetype, excluding others that share the column.
+  `archetype` is **not** on the `Database.Index<C>` `satisfies` helper (it carries
+  no archetype map), so declare such an index with `as const` (no `satisfies`)
+  and let `index-database.ts`'s `create()` validate it against the real facet.
+- **Array columns fan out automatically.** Keying on a `string[]` column makes a
+  multi-value index — one bucket entry per element — and `find({ col: element })`
+  takes the element, not the array.
+- **Model a many-to-many as a denormalized array + two indexes.** A
+  `todo.assignees: string[]` (owned/displayed by one feature) plus a unique
+  `usersByName` (name → user) and a multi-value `todosByAssignee` (assignee →
+  todos) gives efficient navigation in both directions from one join key.

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

@@ -0,0 +1,28 @@
+---
+paths:
+  - '**/features/*/ecs/**/core-database/resources.ts'
+---
+
+# core-database/resources.ts — the feature's resources
+
+A resource is a singleton component — one instance held on a single entity. One
+file, one export: `resources`, built with `Database.resources(...)`. It is
+identical to `Database.components` except **every entry must carry a `default`**
+— a missing `default` is a compile error here, at the declaration site.
+
+```ts
+import { Database } from "@adobe/data/ecs";
+import { Boolean } from "@adobe/data/schema";
+
+export const resources = Database.resources({
+  settings: { displayCompleted: Boolean.schema },   // per-device view toggle
+});
+```
+
+- Give each resource a `default` — spread the data-type's schema and add one, or
+  bind a `data/` / primitive schema that already carries a sensible default.
+- **Scope = which group it sits in** (see `ecs/index.md`). A per-device
+  preference is `settings` (durable, `nonShared`); a synced-but-unsaved value is
+  `presence`; a saved shared value is `document`.
+- Because there is only ever one instance, linear-memory packing buys nothing —
+  never choose a struct schema for efficiency here.

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

@@ -0,0 +1,24 @@
+---
+paths:
+  - '**/features/*/ecs/**/services/**/*.ts'
+---
+
+# database/services/ — database-bound service factories
+
+One factory per file: `create<Name>Service(db, …)` that binds a service
+implementation to a live database — reading its observables and invoking
+its transactions. This is where the async `services/` contracts (or
+framework services like `AgenticService`) are wired to ECS state.
+
+```ts
+export const createAgentService = (db: ComputedDatabase, mark: PlayerMark): AgenticService =>
+    /* … reads db.observe.*, calls db.transactions.* … */;
+```
+
+Type `db` on the lowest layer exposing what the factory reads/calls (never the
+`service-database` itself — that would be a cycle).
+
+An `index.ts` barrel re-exports the factories; `service-database.ts`
+registers them under the `services` facet, each keyed by the name
+consumers read it as (`db.services.agent`). Defining a standalone service
+contract (not yet bound to a db) belongs in the feature `services/` layer.

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

@@ -0,0 +1,132 @@
+---
+paths:
+  - '**/features/*/ecs/**/systems/**/*.ts'
+---
+
+# database/systems/ — the real-time tick loop
+
+Systems are the framework's real-time backbone: functions the scheduler runs
+**every frame**, in dependency order, to advance a simulation. A feature only
+has a `systems/` folder when it is real-time (a game, a physics/particle sim).
+Turn-based features never need one — they mutate through transactions on user
+input and stop.
+
+A system is a `SystemDeclaration` — `{ create, schedule?: { before?, after?, during? } }`.
+`create` runs ONCE at construction (capture closures / query args); it returns the
+per-frame function (or `void` for an init-only system, e.g. seeding the first
+entities). Ordering lives under **`schedule`** (not top-level).
+
+**Declare the `systems` map inline in `system-database.ts`.** The `create: (db) => …`
+arrow must be written inline in `Plugin.create` for two reasons: only there is `db`
+strongly typed (to the assembled plugin's database, with a **writable `store`**), and
+a pre-typed standalone `create` reference breaks the scheduler's system-name inference
+(the name union collapses to `never`, which then rejects every `schedule` entry). Keep
+each `create` thin by delegating the real per-frame work to a pure `data/` step
+function; if an ecs-specific body is substantial, extract it to a `systems/<name>.ts`
+helper `(db) => () => void` (annotate its `db`) and call it from the inline `create`.
+
+```ts
+// in system-database.ts
+import { Database, scheduler } from "@adobe/data/ecs";
+import { Motion } from "../../data/motion/motion.js";
+
+const plugin = Database.Plugin.create({
+    extends: Database.Plugin.combine(ComputedDatabase.plugin, scheduler),
+    systems: {
+        control: { create: (db) => () => { /* input → ship; db.transactions.fireBullet() */ } },
+        movement: {
+            schedule: { after: ["control"], before: ["collision"] },
+            create: (db) => () => {
+                const dt = db.store.resources.frameDelta;
+                for (const arch of db.store.queryArchetypes(["position", "velocity"])) {
+                    const pos = arch.columns.position, vel = arch.columns.velocity;
+                    for (let i = 0; i < arch.rowCount; i++) {
+                        pos.set(i, Motion.advance(pos.get(i), vel.get(i), dt)); // in-place, no migration
+                    }
+                }
+            },
+        },
+        collision: { schedule: { after: ["movement"] }, create: (db) => () => { /* … */ } },
+    },
+});
+```
+
+- **Systems mutate `db.store` directly** — that is the writable surface a system
+  receives (unlike the readonly `.store` consumers get). In-place column writes
+  (`col.set(i, …)`) for hot per-row work that stays in the same archetype;
+  `db.store.update / insert / delete` for lifecycle (spawning, dying) that changes
+  archetype membership. Resources: `db.store.resources.x = …`.
+- **Dispatch a transaction for a discrete atomic event** — when the effect is a
+  self-contained event that already has a conformant transaction (score a hit,
+  lose a life, spawn a wave, fire a bullet), call `db.transactions.*` instead of
+  re-implementing it: you reuse the `data/`-verified logic and observers (a reactive
+  HUD) are notified. Reserve direct `db.store` writes for the hot per-row paths
+  (movement, aging) that run on every entity every frame and shouldn't pay
+  per-entity transaction overhead.
+- **Optimize for execution speed in systems** if there are multiple items, then make sure we are using efficient store queries and reading/writing minimal data columns. If this is not hot path, then the simplified data functions can be used, but in hot paths we only consider data functions to be specification. (ie: only use them if it's clearly not a hot path or you cannot write anything more performant by directly using ecs store) 
+- **The step math may live in `data/`.** but only for non-hot path
+- **Iterate archetypes per `archetypes.md`.** Express selection with
+  `queryArchetypes(include, { exclude })`; when a system destroys/migrates rows
+  (bullets expiring, entities dying) iterate **tail → head** so hole-fills don't
+  invalidate the cursor. A per-frame system touching many rows is exactly where
+  those rules pay off. **A `db.transactions.*` call mid-scan migrates rows too** —
+  a transaction that inserts/deletes invalidates any live archetype cursor, so
+  snapshot the ids you'll act on (or reverse-iterate) *before* dispatching
+  transactions inside a per-frame loop.
+- **Replicate the oracle's top-level guard in every system.** If the `data/`
+  `step` opens with `if (isGameOver(state)) return state`, each split system must
+  early-return on the same condition — a frozen frame is only a true no-op if
+  *every* system honors the guard.
+- **Index reads go through `db.indexes`** (plural) — the writable `db.store` a
+  system receives is typed *without* its index handles, so a broad-phase query is
+  `db.indexes.byCell.find({ cell })`, not `db.store.indexes.…`.
+- **Ordering is declared under `schedule`, not implied.** `schedule.before` /
+  `schedule.after` are hard constraints (name sibling systems); `schedule.during`
+  is a soft same-tier hint. Systems with no ordering relation share a tier
+  (conceptually parallel) — never rely on declaration order. When you split a
+  monolithic `data/` `step` into several ordered systems, the schedule **must
+  mirror the step's internal sequence** (advance → fire → age → collide → refill)
+  — otherwise the tick diverges from the oracle even though each system is
+  individually correct. Watch the subtle case: if a spawn step (fire) is followed
+  by a step that also processes the just-spawned entity (the new bullet is aged
+  and advanced this same tick), you can't advance *all* bodies in one system
+  before the spawn — split that entity's advance out so it runs *after* the spawn,
+  alongside the step that owns it.
+- Games or simulations with immediate mode rendering may want to store a session
+  resource of the canvas and render to it within a system. @adobe/data-gpu provides
+  example patterns for doing this.
+- All simulation systems should be optimized for performance.
+  Avoid allocating intermediate objects if possible; read/write columns directly if hot-path. You can use transactions if needed, for instance if we are writing non hot path things which we have other things observing. (Only transactions are observable, not direct writes)
+
+## Driving the loop — the scheduler
+
+Systems don't run themselves. Combine the built-in scheduler so they run on
+`requestAnimationFrame`:
+
+```ts
+import { Database, scheduler } from "@adobe/data/ecs";
+// in system-database.ts:
+Database.Plugin.create({ extends: Database.Plugin.combine(ComputedDatabase.plugin, scheduler), systems });
+```
+
+The scheduler adds a `schedulerState` resource (`"running" | "paused" |
+"disposed"`) — gate start/pause/resume through it (start `"paused"` if the game
+begins on a user action). A headless host (tests, server sim) omits the
+scheduler and drives frames itself by calling `db.system.functions[name]()` for
+each `name` in `db.system.order` — so a simulation is fully runnable and testable
+with no rAF and no rendering attached.
+
+## Layer
+
+`system-database.ts` extends the previous ecs layer (usually `ComputedDatabase`),
+combined with `scheduler`, and declares the `systems` map **inline** (see above —
+this is the one facet not split one-per-file, because `create`'s `db` is only typed
+inline and standalone declarations break name inference). A `systems/` folder is
+optional: it holds extracted per-frame body helpers (`(db) => () => void`) only when
+an inline body grows too large — the schedule and registration still live inline in
+`system-database.ts`. The headless conformance test drives one frame via
+`db.system.order` / `db.system.functions` and compares to the `data/` `step` oracle,
+**reusing the feature projection** (`ecs/conformance.md`); it lives at
+`system-database/tick-loop.test.ts`. Test **selection/detection** logic (which
+entities collide, which pair resolves) separately, with seeded edge-case geometries
+— it's a system concern, not a transaction, and where subtle bugs hide.

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

@@ -0,0 +1,45 @@
+---
+paths:
+  - '**/features/*/ecs/**/transactions/**/*.ts'
+---
+
+# database/transactions/ — atomic mutations
+
+One mutation per file: a function taking the transaction store as its
+first argument and pure `data/` args, returning `void`. It reads and
+writes `t.resources` / entities; all its writes commit or roll back
+together.
+
+```ts
+import { PlayMoveArgs } from "../../../data/play-move-args/play-move-args.js";
+import type { CoreDatabase } from "../../core-database/core-database.js";
+
+export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
+    // guard, then mutate t.resources / entities / archetypes
+};
+```
+
+- Type the store parameter as `<Layer>.Store`: **`CoreDatabase.Store`** for a
+  transaction that reads/writes entities, resources, or archetypes (the common
+  case — all schema lives in `core-database`); **`IndexDatabase.Store`** the
+  moment it reads an index. A store *is* the transaction context: it carries the
+  index handles and the initiating `t.userId`. There is no separate
+  transaction-context type.
+- Keep transactions idempotent under replay where sync/P2P applies —
+  validate and silently return on illegal or out-of-turn input rather
+  than throwing.
+- Decisions come from pure `data/` helpers; the transaction only applies the
+  result — read the touched slice, call the `data/` transform, write the diff.
+- **Conform every transaction to its `data/` transform** in its sibling
+  `*.test.ts`, via `expectConforms` over the spec's shared cases (see
+  `ecs/conformance.md`): seed `fromState(before)`, dispatch, assert `toState ≡
+  after`, covering every branch and edge case. A transaction taking **entity
+  ids** resolves them from the seeded store in the `apply` closure; one with no
+  `data/` analogue (`setBounds`, `setInput`) gets a direct resource assertion.
+- An `index.ts` barrel feeds the `transactions` plugin facet — so it must
+  re-export **only** the mutations. A read/query helper shared by several
+  transactions (`readShip`, `readBoard` — a `(t) => value` function) may live
+  beside them in `transactions/`, but keep it **out of the barrel**, or it gets
+  registered as a dispatchable transaction. (These are related helpers, so they
+  belong here, not in a separate folder — `cohesion.md`'s peer-level caution
+  doesn't apply.)

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

@@ -0,0 +1,95 @@
+---
+paths:
+  - '**/features/*/data/**/*.ts'
+  - '**/features/*/services/**/*.ts'
+  - '**/features/*/ecs/**/*.ts'
+  - '**/features/*/ui/**/*.ts'
+---
+
+# Feature architecture — a verifiable spec and an optimized implementation
+
+Each feature is built twice in one codebase: a **pure specification** you can
+trust, and an **efficient implementation** proven equivalent to it.
+
+- **`data/` is the specification.** The whole feature modelled as one immutable
+  `State` with pure transformations over it — correct by construction, fully
+  unit-tested, performance irrelevant. This is the source of truth.
+- **`ecs/` is the implementation.** The same model physically arranged for
+  mutation efficiency (a reactive Entity-Component-System). Its reads and writes
+  wrap the `data/` functions where practical; where they must be hand-optimized,
+  unit tests verify they still agree with the `data/` precedent.
+
+Because the optimized `ecs/` layer is largely mechanical given the `data/` spec,
+it can be generated and kept honest by AI rules, with the conformance tests as
+the safety net. Net result: write a slow-but-verifiable app, then derive a fast
+one that provably behaves the same.
+
+## The four layers
+
+`ui → ecs → services → data` — higher imports lower, never the reverse. `data/`
+depends on nothing but `@adobe/data` and other `data/` declarations. A feature
+creates only the layers it uses.
+
+| Layer | Role |
+|-------|------|
+| `data/` | The spec: `State`, pure transforms & derivations, entity sub-types. Pure, tested. |
+| `services/` | Async capability contracts (ports to the outside world). Optional. |
+| `ecs/` | The implementation: the ECS materialisation + reactive reads/writes over it. |
+| `ui/` | Presentation. |
+
+## One app, many features
+
+An application is a set of **features**, each its own `features/<name>/` folder
+with the same four layers. One base feature (`features/main/`) is the host; the
+rest are peers that load lazily.
+
+**Keep each feature small; grow by adding features, not by bloating one.** A
+feature is meant to fit in the head — a handful of files per layer. When a
+part of a feature keeps growing, that is usually the signal to split it into
+its own peer feature rather than let one feature's folders balloon.
+
+- **Dependencies point toward the base, never out of it.** A peer feature may
+  build on another feature's `data/` types and declarations (kept acyclic). The
+  base must not depend on its children — with one sanctioned exception below.
+- **The base `imports` every peer's *schema* plugin** —
+  `Database.Plugin.create({ imports })`, not `extends`. `imports` merges the
+  peer's `core-database` (components / resources / archetypes) into the shared
+  store at runtime **without** pulling its types or behavior into the base's type
+  or bundle (`extends` would do both, and cost quadratically). So one store knows
+  every feature's schema — data coexists, persists, and syncs — while the base
+  stays decoupled. Import the peer's `core-database.ts` plugin (schema only) —
+  under its feature-qualified name `<Peer>CoreDatabase` (see the cross-feature
+  naming rule in `ecs/index.md`): its indexes, transactions, computed, services,
+  and UI stay out until the feature loads. A column two features share (e.g.
+  `name`) lives in `data/` and is referenced by identity, so `combinePlugins`
+  dedupes it.
+- **Peers load lazily by being used.** `DatabaseElement`, on connect, walks up to
+  the nearest ancestor database and `extend`s it with its own plugin — so the
+  first time a feature element renders, its full plugin (indexes, transactions,
+  computed, services) is added to the shared live database and its code chunk is
+  fetched. Gate that first render behind a user action (a button, a tab) so the
+  load is genuinely on-demand.
+- **The base reaches a child only through a lazy element wrapper** — a tiny
+  `Foo()` that `void import()`s the child element. That dynamic import is the one
+  allowed core→child seam; the heavy element and its service database stay in the
+  child's own chunk.
+
+## Spec and implementation, kept honest
+
+The tie between `data/` (spec) and `ecs/` (implementation) is **conformance**,
+one property — `toState(apply(fromState(before), args)) ≡ transform(before, args)`:
+each ecs mutation, seeded and read back through a test-only `ecs ↔ State`
+projection, equals the pure `data/` transform it stands for. The projection and
+its runner live in `ecs/conformance/` (see `ecs/conformance.md`); the shared
+`{ before, args, after }` cases are spec-owned (`data/state/<transform>.cases.ts`),
+so conforming the ecs path is "substitute the implementation, reuse the
+expectations." This lets the ecs layer be largely mechanical and agent-generated,
+with the spec as oracle. *How* to author each layer lives in the per-folder rules
+below.
+
+## Per-layer detail
+
+See the rules under each folder: `data/`, `services/`, `ecs/` (components,
+resources, archetypes, computed, indexes, transactions), `ui/`. Cross-cutting
+patterns live at the rules root — `namespace.md`, `data-modelling.md`,
+`archetypes.md` (row iteration), `type-casts.md`, `cohesion.md`.