@adobe/data-ai 0.10.23 → 0.10.24

package/.claude/rules/features/services/main-service/conformance.md

@@ -0,0 +1,97 @@
+---
+paths:
+  - '**/features/*/services/main-service/conformance/**/*.ts'
+---
+
+# services/main-service/conformance/ — keeping the ECS honest against the spec
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+**State-based features only** (a feature with a `data/state/` spec). Test-only: imported
+only by `*.test.ts`, in no facet barrel. The `data/state` cases (authored per
+`../../../data/state.md`, gathered by the `spec.ts` manifest) are the shared truth; the
+`@adobe/data-testing` runner replays them against the ECS. This folder holds only the
+**feature-specific projection** (`projection.ts`) plus one `conformance.test.ts`.
+Reference: `data-lit-tictactoe` (minimal), `data-lit-todo` (entities + `hydrate`).
+
+**The projection helpers and `Match` are test-only — never a runtime branch.**
+`fromState`/`toState` rewrite the whole store out-of-band; runtime code reads through
+observables/indexes and writes through transactions.
+
+## `projection.ts` — the store ⇄ State mapping (the one per-feature piece)
+
+A single aggregated export — three test-only helpers, one `export`:
+
+```ts
+export const projection = { fromState, toState, toData };
+```
+
+- `fromState(store, state)` seeds a store to a `State` (clear, insert entities, set
+  resources) and **returns the `id → entity` map** it built (`ReadonlyMap<Id, Entity>`).
+  The ecs mints its own ids, so the runner turns this map into the resolver that maps a
+  case's spec-id to the seeded entity — no feature writes id resolution by hand. Return
+  `void` for an index-addressed / singleton feature (ids then resolve to `Entity.none`).
+- `toState(store)` reads the whole store back, built on `toData`.
+- `toData(store, entity)` reads one entity as its `data/` value — the single place the
+  ecs↔data mapping lives. Its **return type** is what tells conformance which derivations
+  are entity-list computeds. Present only when the feature has entities.
+
+## `conformance.test.ts` — one call
+
+```ts
+import { Conformance } from "@adobe/data-testing";
+import { spec } from "../../../data/state/spec.js";
+Conformance.checkFeature(spec);
+```
+
+`checkFeature` replays the manifest's shared cases against the ECS: it pulls the
+transactions/actions off `spec.plugin`, the computeds off `spec.computedPlugin`, seeds
+each case's `before` over `State.create()`, synthesizes each service's recording double
+from `spec.services` + the case's `responses`, round-trips `State.samples` through
+`spec.projection`, and hydrates the id-emitting computeds named in `spec.hydrate` through
+`toData`. It shares `spec` with `spec.test.ts` — same cases, substituted implementation.
+
+Everything `checkFeature` needs lives on the manifest (`../../../data/state.md`):
+`plugin`, `computedPlugin`, `projection`, `hydrate`, `services`, `state`, `fns`, `cases`.
+The manifest's compile-time guards mean the two calls (`checkSpec` + `checkFeature`) are
+the whole conformance surface — no per-op wiring, no coverage guard to hand-maintain.
+
+- **Name-pairing.** Each ecs op conforms to its **same-named** transition/derivation. An
+  op with no same-named transition (infrastructure like `setInput`, a streaming action,
+  a richer UI op) is skipped — so when the real op is renamed (`dragTodo`), add a thin
+  **same-named** op (`reorderTodo`) for the transition to pair with; never a per-item
+  adapter.
+- **Projection round-trip.** When `State.samples` is non-empty the runner adds a
+  `toState ∘ fromState ≡ identity` test per sample.
+- **Comparison.** Ordering is carried by the value's type — `ReadonlyArray` positional,
+  `ReadonlySet`/`ReadonlyMap` order-independent. Entity ids compare up to an id-bijection
+  from the schema-marked spec-ids (no matcher). Float noise is absorbed by
+  `match?: { tolerance }` (default `0.01`). A minted scalar uses `Match.anyNumber` /
+  `Match.anyString`.
+
+## The escape hatch — per-surface `seedContext` / custom concurrency
+
+A feature that needs **ambient per-case context differing per surface** — a user-scoped
+`userId` seeded before the raw transaction *and* independently before the action dispatch
+(**p2p presence**) — cannot use `checkFeature` (it has no place to thread two different
+`seedContext`s or a custom concurrency). It drives the lower-level runners directly,
+feeding them the manifest's cases via `Conformance.adaptCases`:
+
+```ts
+import { Conformance } from "@adobe/data-testing";
+import { spec } from "../../../data/state/spec.js";
+
+Conformance.runTransactions({
+  createStore, fromState, toState,
+  transitions: Conformance.adaptCases(spec.fns, spec.cases, spec.services, false),
+  transactions,
+  seedContext: (store, _before, args) => seedUserId(store, (args as { mark: string }).mark),
+});
+```
+
+`adaptCases(fns, cases, services, injectServices)` turns the manifest into the discovery
+map the runners consume — `injectServices: false` for the transaction store (a
+transaction never receives services), `true` for the action db. `runActions` /
+`runComputeds` take the same shape and their own `makeDb` / `seedContext` / concurrency.
+This is the **only** sanctioned use of the lower runners; ordinary features use
+`checkFeature`.

package/.claude/rules/features/services/main-service/core-database.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - '**/features/*/services/main-service/**/core-database/core-database.ts'
+---
+
+# core-database/core-database.ts — the assembled schema + its namespace
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+A thin assembler: `Database.Plugin.create({ components?, resources?, archetypes? })`
+over the facet files, exposed through the `CoreDatabase` namespace. This is the
+single-file namespace form (one value export — `plugin` — everything else a type;
+see `global/namespace.md`).
+
+```ts
+import { Database, type Store } from "@adobe/data/ecs";
+import { components } from "./components.js";
+import { resources } from "./resources.js";
+import { archetypes } from "./archetypes.js";
+
+const coreDatabasePlugin = Database.Plugin.create({ components, resources, archetypes });
+
+export type CoreDatabase = Database.Plugin.ToDatabase<typeof coreDatabasePlugin>;
+// Resolved component map, at module scope so the imported `Store` namespace isn't
+// shadowed by `CoreDatabase.Store` below.
+type CoreComponents = Store.Components<Database.Plugin.ToStore<typeof coreDatabasePlugin>>;
+
+export namespace CoreDatabase {
+  export const plugin = coreDatabasePlugin;
+  /** The store transactions operate on — a store *is* the transaction context. */
+  export type Store = Database.Plugin.ToStore<typeof coreDatabasePlugin>;
+  /** Index-declaration type bound to this database's components. */
+  export type Index = Database.Index<CoreComponents>;
+  /** A component name, and a component-key tuple — an archetype's defining shape, or the key
+   *  list of a `count` / `select` query. */
+  export type Component = Extract<keyof typeof components, string>;
+  export type Archetype = readonly Component[];
+}
+```
+
+## Derive `Component` / `Archetype` from `components`, never the plugin
+
+Read the keys straight from the leaf `components` module
+(`Extract<keyof typeof components, string>`). Do **not** derive them from the
+plugin (`Store.Components<ToStore<plugin>>`, i.e. `CoreComponents`): the plugin is
+built *from* `archetypes`, so a plugin-derived `Archetype` is **circular** the
+moment it is used to `satisfies`-check an archetype tuple — and the cycle
+collapses the entire database type to `{}`. The leaf derivation is cycle-free and
+usable both in `archetypes.ts` (to check shared bases) and downstream (to check
+`count` / `select` query keys).

package/.claude/rules/features/services/main-service/index.md

@@ -0,0 +1,189 @@
+---
+paths:
+  - '**/features/*/services/main-service/main-service.ts'
+  - '**/features/*/services/main-service/*-database/*-database.ts'
+---
+
+# services/main-service/ — the feature service (ECS implementation)
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+`main-service/` is the feature's single entrypoint service (see `../index.md`),
+implemented as a reactive Entity-Component-System — an implementation detail
+behind the service. 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`):
+
+```
+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:
+
+```
+main-service/
+  core-database/            # the schema (above)
+  index-database/           # extends core;        indexes/
+  transaction-database/     # extends index;       transactions/
+  service-database/         # extends transaction; services/
+  computed-database/        # extends service;     computed/
+  action-database/          # extends computed;     actions/
+```
+
+Each exports a namespace mirroring the plugin — the composed object is a
+`Database` (the `@adobe/data` term) even though the folder is `services/main-service/`:
+
+```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 — `MainService`
+
+*Which* layer is topmost varies with the facets a feature uses (service /
+computed / action / system). Consumers — `ui/`, the app entry, `services/main-service/conformance/`
+— need the *whole* feature database but must not name that layer, or adding or
+dropping a layer rewrites them all. Alias it once from the **folder-eponymous
+`main-service.ts`** (per `global/namespace.md`, a folder's primary export lives in
+its same-named file), as a namespace so consumers reach `MainService.plugin` /
+`MainService.Store`:
+
+```ts
+// services/main-service/main-service.ts
+export { SystemDatabase as MainService } from "./system-database/system-database.js";
+```
+
+Every consumer references **`MainService`** (`.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` / `MainService`. 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>MainService`, 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`** — **services**, **computed**, and **actions** each
+  take `service: <Layer>` (the lowest layer whose database exposes what they
+  read/call): services read observables and call transactions; computed reads
+  `service.observe.*` and, once it needs a service's own reactive surface,
+  `service.services.*`; actions call `service.services.*` then
+  `service.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/services/main-service/indexes.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - '**/features/*/services/main-service/index-database/indexes/**/*.ts'
+---
+
+# database/indexes/ — ECS indexes
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+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/services/main-service/resources.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - '**/features/*/services/main-service/**/core-database/resources.ts'
+---
+
+# core-database/resources.ts — the feature's resources
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+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 `services/main-service/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/services/main-service/services.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - '**/features/*/services/main-service/service-database/services/**/*.ts'
+---
+
+# database/services/ — database-bound service factories
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+One factory per file: `create<Name>Service(service, …)` 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 = (service: TransactionDatabase, mark: PlayerMark): AgenticService =>
+    /* … reads service.observe.*, calls service.transactions.* … */;
+```
+
+Type `service` 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 (`service.services.agent`). Defining a standalone
+service contract (not yet bound to a database) belongs in the feature
+`services/` layer.

package/.claude/rules/features/services/main-service/systems.md

@@ -0,0 +1,145 @@
+---
+paths:
+  - '**/features/*/services/main-service/system-database/**/*.ts'
+---
+
+# database/systems/ — the real-time tick loop
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+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({
+    // combine scheduler with the CURRENT TOP layer — ComputedDatabase here, but
+    // ActionDatabase / ServiceDatabase if the feature built those (systems come last).
+    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 hot paths for speed.** With many entities, query with efficient
+  `queryArchetypes` and read/write minimal columns directly; avoid intermediate
+  allocations. On a hot path treat `data/` step functions as **spec only** — use
+  them when the path isn't hot or you can't beat them by writing the store
+  directly; off hot paths, reuse them freely. (Only transactions are observable —
+  direct store writes fire no observers.)
+- **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.
+- Immediate-mode rendering: store the canvas in a session resource and render to
+  it inside a system (see @adobe/data-gpu for patterns).
+
+## 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 feature's **current top** main-service layer (`ActionDatabase` /
+`ServiceDatabase` / `ComputedDatabase` — whichever it built; systems come last in the pipeline, so
+they must sit atop any service/action layers, not a hardcoded `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** (`services/main-service/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.
+
+## Iterating archetype rows
+
+A per-frame system reads/writes archetype columns directly. The row-iteration
+rules — declarative `queryArchetypes` selection, tail → head migration, snapshot
+avoidance — are general ECS concerns in the rules-root `archetypes.md`.