@adobe/data-ai 0.9.82 → 0.9.84

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

@@ -0,0 +1,69 @@
+---
+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). **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,133 @@
+---
+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.
+- **The step math lives in `data/`.** A system is the ecs wiring: it reads store
+  rows, calls a pure `data/` step/derive function, writes the result back — same
+  spec↔implementation discipline as transactions. No physics/game math inline.
+- **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 or simulation systems should be optimized for performance.
+  Avoid allocatin intermediate objects if possible, read directly from store.
+
+## 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`.