@adobe/data-ai 0.10.21 → 0.10.22

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

@@ -1,161 +1,115 @@
 ---
 paths:
-  - '**/features/*/data/**/*.ts'
-  - '**/features/*/services/**/*.ts'
-  - '**/features/*/ui/**/*.ts'
+  - '**/features/*/**/*.ts'
+  - '**/features/*/**/*.tsx'
 ---
 
-# 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.
-- **`services/main-service/` is the implementation.** The same model physically
-  arranged for mutation efficiency — a reactive Entity-Component-System, an
-  implementation detail behind the service. 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 `main-service` 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.
-
-## Two modes: state-based vs. ECS-based
-
-The "built twice" structure above is the **state-based** mode. Every feature is in
-one of two modes, discriminated by **the presence of `data/state/`**:
-
-- **State-based** — a **Functional State Specification (FSS)** is the source of
-  truth: the pure `data/State` aggregate with its transitions and derivations, and
-  the ECS is a conformance-verified implementation of it. Adds `data/state/` (State,
-  the pure transforms with sibling `*.cases.ts`, the `transforms.ts` barrel, the `spec.ts`
-  manifest, `spec.test.ts`), `services/main-service/conformance/`, and the `state`
-  projection computed. **This is how every new feature is authored.**
-- **ECS-based** — the **ECS is the source of truth**, authored directly:
-  **no `data/state/`**, no FSS, no conformance. This is a **legacy** shape — features
-  written before the state-based approach existed. New features are **never** authored
-  this way; ECS-based exists only to describe and maintain those older features.
-
-**Discriminator:** `data/state/` present → state-based; absent → ECS-based. The
-`data/<type>` value folders (the serializable types backing components/resources,
-the wire, and persistence) exist in **both** modes — only the aggregate `State`
-spec and the conformance layer are mode-specific. `data/` never disappears; the
-*aggregate spec* does.
-
-**Testing follows the mode.** A state-based feature is verified by conformance: the
-shared `cases` drive both the pure spec and the ECS, so a transaction or action with
-a same-named transition needs no test of its own. An **ECS-based feature has no
-conformance cases, so every transaction and every action carries its own unit
-test** — the direct substitute for the conformance oracle (see `services/main-service/transactions.md`
-and `actions.md`).
-
-## The layers
-
-**The layers organize by the *kind of type* each folder holds, not by a strict
-dependency wall.** `data/` holds **value types** (pure, serializable data) and
-the pure declarations over them; `services/` holds **service types** (interfaces
-**and** implementations); `ui/` holds presentation. The rule is about *what
-lives where*: a service is never authored under `data/`, a value type is never
-authored under `services/`.
-
-**`ui/` isolation is strict and inviolable.** `ui/` sits at the top: neither
-`data/` nor `services/` may ever import from `ui/`, no exceptions. Presentation
-depends on the model; the model never depends on presentation.
-
-Beneath that hard line, `data/` and `services/` are **not** strictly ordered.
-Value types are fundamental — a `data/` **type** depends on nothing but
-`@adobe/data` and other `data/` types. But the **transition functions** over
-them may depend on `services/` **without restriction**: they import whatever they
-need — service interfaces they inject, and any associated utilities the service
-namespace exposes — as ordinary imports, not type-only. So the strict wall is
-`ui/` above `data/` + `services/`; the `data/ ↔ services/` boundary is the loose
-one. A feature creates only the layers it uses.
-
-| Layer | Role |
-|-------|------|
-| `data/` | The spec: `State`, pure transforms & derivations, entity sub-types. Pure, tested. |
-| `services/main-service/` | The implementation: the ECS materialisation + reactive reads/writes. The **sole entrypoint** — the only service the `ui/` binds to. |
-| `services/<name>-service/` | Async capability contracts (ports to the outside world). Reached only *through* `main-service` (its actions/services wire them in), never by the UI. Optional. |
-| `ui/` | Presentation. |
-
-`services/` holds two kinds of service: the one `main-service/` (ECS-backed
-state, its own subtree of rules) and any async capability contracts. The UI, and
-every external consumer, sees only `main-service`.
+# Feature architecture — layered, specified, implemented
+
+Each feature is built up in layers, each simple and testable on its own:
+
+- **`data/`** declares the feature's pure Data: value types, components, resources,
+  and entities (component tuples).
+- **`services/`** declares and implements the async services the feature talks to.
+- **`spec/`** is the feature's **specification**: one immutable `State` and pure
+  functions over it. It is test tier only.
+- **`ecs/`** is the **implementation**: a reactive Entity-Component-System, proven
+  equivalent to the spec by conformance.
+- **`ui/`** is presentation.
+
+Write the slow, obviously-correct spec first; the ECS is then largely mechanical, and
+conformance keeps it honest.
+
+## Layout
+
+```
+src/
+  features/<feature>/
+    data/        runtime   values/  components/  resources/  entities/
+    services/    runtime   <name>-service/ namespaces, services.ts
+    spec/        TEST TIER State, actions, derivations, cases, spec.ts
+    ecs/         runtime   core/ indexes/ transactions/ services/ computed/ actions/ systems/
+                           main-service.ts, conformance/ (TEST TIER)
+    ui/<x>/      runtime   <x>-presentation.ts, <x>-element.ts
+  app/           runtime   schema.ts, versioning/, main.ts
+```
+
+A feature creates only the layers and folders it uses.
+
+## Dependencies
+
+```
+runtime:  data → services → ecs → ui → app
+spec:     data + services → spec          (test tier)
+tests:    ecs/conformance → spec + ecs
+```
+
+- **Each layer imports only from the layers before it.** A higher feature's layer
+  may import the same or a lower layer of a feature it builds on.
+- **No runtime file imports `spec/`.** The spec is consumed only by tests. Logic the
+  spec and the implementation share (ordering math, name formatting) lives in
+  `data/values/` helpers, which both import.
+- **Presentations import only `data/` and sibling `ui/` lazy wrappers** (a
+  convention); elements bind to `ecs/main-service`.
+- **A base feature never imports a feature built on it.** The one exception is a
+  presentation calling a higher feature's lazy wrapper (`lazy-element.md`), which
+  loads that feature's element and plugin on first render.
+
+## Building a feature, one layer at a time
+
+Each step has a gate that must pass before the next:
+
+| # | Step | Gate |
+|---|---|---|
+| 1 | `data/values` | pins compile; helper tests |
+| 2 | `data/components`, `resources`, `entities` | compiles |
+| 3 | `services/` | per-service unit tests |
+| 4 | `spec/`: State, `create`, `samples`, then one action or derivation + cases at a time | `checkSpec` |
+| 5 | `ecs/core` + `ecs/conformance/projection.ts` | samples round-trip |
+| 6 | `ecs` indexes, transactions, services, computed, actions — one op at a time | `checkFeature` |
+| 7 | `ecs/systems` (real-time only) | per-system and frame conformance |
+| 8 | `ui/` presentations, then elements | presentation tests |
+| 9 | `app/` | versioning and persistence tests; the app builds |
 
 ## One app, many features
 
-An application is a set of **features**, each its own `features/<name>/` folder
-with the same 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 `services/main-service/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
-  `services/main-service/core-database.ts` plugin (schema only) — under its
-  feature-qualified name `<Peer>CoreDatabase` (see the cross-feature naming rule
-  in `services/main-service/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 main-service stay in the
-  child's own chunk.
-
-## Spec and implementation, kept honest
-
-The tie between `data/` (spec) and `main-service` (implementation) is
-**conformance**, one property —
-`toState(apply(fromState(before), args)) ≡ transform(before, args)`: each
-main-service mutation, seeded and read back through a test-only store↔`State`
-projection, equals the pure `data/` transform it stands for. The spec-owned cases
-are authored as inert `data/state/*.cases.ts` and gathered by the `data/state/spec.ts`
-**manifest**, which both the pure `spec.test.ts` (`Conformance.checkSpec(spec)`) and the
-ecs `services/main-service/conformance/conformance.test.ts`
-(`Conformance.checkFeature(spec)`) import. `checkFeature` pairs each ECS op to its
-same-named transition, replays the shared cases, and round-trips the projection (see
-`services/main-service/conformance.md`); the manifest's compile-time guards keep the two
-calls the whole conformance surface. So conforming the implementation is "substitute the
-implementation, reuse the expectations" — `main-service` is largely mechanical and
-agent-generated, with the spec as oracle. *How* to author each layer lives in the
-per-folder rules below.
+An app is a set of features under `features/<name>/`. One base feature
+(`features/main/`) hosts; the rest build on it and load lazily.
+
+- **Keep each feature small; grow by adding features.**
+- **One owner per component and resource name.** The lowest feature that needs a
+  name declares it in its `data/`; features built on it import that schema object
+  (identity is what the ECS compares) and spread the owner's barrel into their own.
+- **`app/` composes the features** (`../app.md`): its schema combines each feature's
+  plugins, it owns versioning, and it injects services that must be provided at
+  runtime.
+- **Features built on the base load lazily**: a feature's element extends the shared
+  live database with its plugin the first time it connects. Gate that first render
+  behind a user action.
+
+## Enforcement
+
+One TS project per layer (see `data-lit-todo`'s tsconfigs):
+
+- **`tsconfig.data.json`** — `data/` + `services/`, composite.
+- **`tsconfig.spec.json`** — `spec/`, references data.
+- **`tsconfig.ecs.json`** — `ecs/` minus `conformance/`, references data.
+- **`tsconfig.test.json`** — everything else, non-emitting: `ui/`, `app/`,
+  `ecs/conformance/`, and every `*.test.ts`. It references ecs + spec.
+
+So `spec/` importing `ecs/`, or `ecs/` importing `spec/`, is a compile error (TS6307).
+`ui/` and `app/` sit in the test project, so for them "never import `spec/`" is a
+convention, not a compile error. The package's `typecheck` script is
+`tsc -b tsconfig.test.json`, which builds all of them.
 
 ## Reference implementations
 
 Working samples ship inside `@adobe/data` at
-`node_modules/@adobe/data/references/<sample>/src/` — read them for concrete,
-current examples of this structure. `data-lit-todo` is the most complete
-(multi-feature, capability services, indexes, conformance tests);
-`data-lit-tictactoe` is the minimal turn-based reference.
-
-## Per-layer detail
-
-See the rules under each folder: `data/`, `services/` — the `main-service/`
-subtree (components, resources, archetypes, computed, indexes, transactions,
-systems, conformance) and capability-contract services — and `ui/`.
-Always-on conventions live in `global/` (`namespace.md`, `cohesion.md`,
-`type-casts.md`, `function-references.md`, `react.md` — deliberately repo-wide);
-other cross-cutting patterns at the rules root — `data-modelling.md`,
-`archetypes.md` (row iteration).
+`node_modules/@adobe/data/references/<sample>/src/`:
+
+- **`data-lit-todo`** — the most complete: two features, services, indexes, cross-feature composition, and persistence.
+- **`data-lit-tictactoe`** — the minimal turn-based reference.
+- **`data-lit-space-rock-game`** and **`data-gpu-hopper`** — real-time, with per-system and frame conformance.
+
+The per-folder rules live beside this file (`data/`, `services/`, `spec/`, `ecs/`,
+`ui/`). Always-on conventions are in `global/`.

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

@@ -1,103 +1,71 @@
 ---
 paths:
-  - '**/features/*/services/services.ts'
-  - '**/features/*/services/*-service/**/*.ts'
+  - '**/features/*/services/**/*.ts'
 ---
 
 # services/ — the feature's services
 
-Everything a feature exposes as a service lives here. Two kinds:
+A service is the boundary between the feature and the outside world (generation,
+analytics, networking). Each is a namespace folder (`global/namespace.md`) holding its
+interface, its implementation and a fake. Services depend only on `data/`.
 
-- **`main-service/`** — the one entrypoint. The ECS-backed reactive state
-  service (materialisation + reads/writes over it); the only service the `ui/`
-  and external consumers bind to. It has its own subtree of rules
-  (`main-service/index.md` and the layer files under it). Every feature with
-  state has exactly one.
-- **`<name>-service/`** — async **capability contracts**: ports to the outside
-  world (processing, persistence, observation, generation). Reached only
-  *through* `main-service` (its service/action layers wire them in), never by the
-  UI. A feature has zero or more.
+```
+services/
+  analytics-service/
+    analytics-service.ts   # the interface + `export * as AnalyticsService from "./public.js"`
+    create.ts              # the implementation
+    create-fake.ts         # the fake
+    public.ts              # export { create }; export { createFake };
+  services.ts              # type Services = { … }
+```
 
-The rest of this rule governs the capability contracts; `main-service` follows
-its own subtree.
+## The interface — an async data service
 
-## `services/services.ts` — the injectable service map
+```ts
+export interface AnalyticsService extends Service {
+  todoCreated: (args: { readonly name: string }) => void;
+  randomTodoRequested: () => Promise<Timing>;
+}
+type _Valid = Assert<AsyncDataService.IsValid<AnalyticsService>>;
+export * as AnalyticsService from "./public.js";
+```
 
-The folder root exports one `Services` type: the feature's capability services
-keyed by short name (the `-service` suffix dropped), the single source of truth for
-service injection.
+- Members are async only: `void | Promise<T> | AsyncGenerator<T> | Observe<T>`. They
+  send and receive Data, or async callbacks and observers of Data, which keeps a
+  service portable across processes and lazily loadable.
+- The interface is the only place `interface` is used. Validate it with
+  `AsyncDataService.IsValid`.
+- A service that carries non-Data configuration the app injects (a host plugin, a
+  callback) cannot pass `IsValid`; skip the assert for it, and keep such services rare.
+- A type only one service uses lives in its interface file (`Timing` beside
+  `AnalyticsService`).
+
+## `create` and `createFake`
+
+- **`create`** is the implementation. When it can't be built without runtime input
+  (a transport, a host-provided plugin), make `create` throw, telling the reader
+  which input is missing; the app injects the real one with
+  `Database.create(plugin, { services })`.
+- **`createFake`** returns the service with every method present and inert. It is an
+  ordinary export (the bundler drops it when unused). Conformance calls it only to
+  list the service's methods; each case supplies the returns (`spec/index.md`).
+- Access them statically (`AnalyticsService.createFake`) so tree-shaking works.
+
+## `services.ts` — the injectable map
 
 ```ts
-// services/services.ts
-import type { AnalyticsService } from "./analytics-service/analytics-service.js";
-import type { NameGeneratorService } from "./name-generator-service/name-generator-service.js";
 export type Services = {
   readonly analytics: AnalyticsService;
   readonly nameGenerator: NameGeneratorService;
 };
 ```
 
-- **Transitions inject with `Pick<Services, …>`** (`data/state.md`), never a
-  re-declared inline `{ analytics: AnalyticsService }` — so the key/type live in one
-  place.
-- **The ecs `service-database` is pinned to it.** After its `ServiceDatabase` type,
-  a drift-guard asserts the resolved services match the map, so `db.services` (what
-  actions call) and `Services` (what transitions inject) can't diverge:
-  `type _Pin = Assert<Equal<ServiceDatabase["services"], Services>>`.
-- **Inherited services**, when a peer feature builds on another, intersect the
-  parent map: `export type Services = MainServices & { readonly baz: BazService }`.
-- A feature with no capability services needs no `services.ts`.
-
-## Capability contracts
-
-Each is a namespace folder (`global/namespace.md`); the export and folder both carry the
-`-service` suffix. A service is the boundary between pure feature code and the
-outside world, which is why its members are async — enabling cross-process
-portability and lazy loading (`AsyncDataService.createLazy`).
-
-- The contract is an `interface` — the only place `interface` is used in the
-  codebase — validated immediately with
-  `Assert<AsyncDataService.IsValid<typeof MyService>>`.
-- Members are async only: `void | Promise<T> | AsyncGenerator<T> | Observe<T>`.
-- Provide `create*` factories.
-
-## Test doubles are a test-tier `*.fake.ts` — never in the production barrel
-
-A service is the seam consumers swap out under test. Ship a **shape-only recording
-template** alongside the interface, in the same namespace folder: `<name>.fake.ts`, a
-**single export** `createFake` that returns the service with each method present but
-inert (void methods do nothing; value methods return a placeholder). It is **NOT**
-re-exported through `public.ts` — so `MyService.createFake` is never reachable from
-runtime code — and it imports the contract with `import type` only. The conformance
-manifest (`data/state.md`) imports it directly; nothing else does.
-
-```ts
-// analytics-service/analytics.fake.ts — test tier, not on the namespace
-import type { AnalyticsService } from "./analytics-service.js";
-export const createFake = (): AnalyticsService => ({
-  serviceName: "analytics",
-  todoToggled: () => {},                                   // void method: inert
-  randomTodoRequested: () => Promise.resolve({ startedAt: 0 }), // value method: placeholder
-  // …one entry per method
-});
-```
-
-The template supplies only the service's **shape** (the runner calls it once to
-enumerate methods — no Proxy). It invents **no return values**: a conformance case
-schedules each value-returning method's returns in its `responses` and asserts the
-calls in its `effects` (`data/state.md`), so the case owns both the input and the
-expectation. A `*.fake.ts` therefore takes no response parameter and hardcodes nothing
-a case asserts.
-
-## Where the I/O types live
-
-Most input/output types belong to a single service — declare them **on that
-service's namespace** (`MyService.SomeInput`) and expose them only when something
-external actually references them; not everything does.
-
-A **service type** may be non-serializable (callbacks, function signatures) —
-that's what distinguishes it from a `data/` type. If an I/O value is a plain
-serializable value, prefer a `data/` type instead.
+- Spec actions inject with `Pick<Services, …>`.
+- `ecs/services/` registers the same keys, pinned with
+  `Assert<Equal<ServiceDatabase["services"], Services>>`.
+- A feature built on another intersects the lower map:
+  `type Services = MainServices & { readonly baz: BazService }`.
+- A feature with no services has no `services/` folder.
 
-A non-service type sits *directly* in `services/` **only** when it is genuinely
-shared across more than one service — rare, but it happens.
+A service that reads the database or calls its transactions is not a `services/`
+service. It is a database-bound factory in `ecs/services/`.

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

@@ -0,0 +1,161 @@
+---
+paths:
+  - '**/features/*/spec/**/*.ts'
+---
+
+# spec/ — the feature's specification
+
+The whole feature as **one immutable `State`** plus pure functions over it: an
+**action** spec for every operation the app performs, and a **derivation** for every
+derived value it shows. It is slow, obvious and fully tested, and it is the oracle the
+ECS is conformed against (`../ecs/conformance.md`).
+
+`spec/` is **test tier**: no runtime file imports it. It depends on `data/`,
+`services/` (types and fakes) and `@adobe/data-testing`.
+
+```
+spec/
+  state.ts   create.ts   samples.ts   public.ts        # State namespace: create + samples
+  toggle-complete.ts   toggle-complete.cases.ts        # one action or derivation + its cases
+  visible-todos.ts     visible-todos.cases.ts
+  transforms.ts                                        # barrel of every action + derivation
+  systems.ts   <system>.cases.ts                       # real-time only: one function per ECS system
+  spec.ts   spec.test.ts                               # the manifest + Conformance.checkSpec
+```
+
+## `State`
+
+```ts
+export type State = {
+  readonly displayCompleted: boolean;              // singleton → resource `displayCompleted`
+  readonly selectedTodo: Entity;                   // a reference singleton
+  readonly entities: ReadonlyMap<number, Todo>;    // an entity collection, keyed by id
+};
+type _Pin = Assert<Conformance.StateMatches<State, typeof resources, typeof components>>;
+export * as State from "./public.js";
+```
+
+- **Every non-`Map` field is a singleton, named for its resource.** A single game
+  object (a ship, a frog) is a resource too.
+- **Every `ReadonlyMap` field is an entity collection**, keyed by numeric id. Its
+  value is an `data/entities` type with no `id` (identity is the key), and its field
+  names are component names. All collections share one id space, so cases use
+  distinct ids across maps.
+- **Pin it** with `Conformance.StateMatches`. Conformance finds schemas by these names,
+  so the pin is what makes a mismatch a compile error. A feature with no components
+  passes `{}`.
+- A value computed from other state (a board picture folded from placed marks) is a
+  **derivation**, not a `State` field.
+- `create()` is the default each case deltas over; `samples` are full states the
+  projection round-trips.
+
+## Actions and derivations — `<name>.ts`
+
+```ts
+export const toggleComplete = (
+  state: Pick<State, "entities">,
+  { id, analytics }: { readonly id: number } & Pick<Services, "analytics">,
+): Pick<State, "entities"> => {
+  analytics.todoToggled();
+  const target = state.entities.get(id);
+  if (target === undefined) return { entities: state.entities };
+  return { entities: new Map(state.entities).set(id, { ...target, complete: !target.complete }) };
+};
+```
+
+- **An action** is `(state: Pick<State, …reads>, args) => Pick<State, …writes>`, sync
+  or async. It specs one `MainService` action of the same name. Return only the
+  fields it writes; no `...state` spread.
+- **Inject services with `Pick<Services, …>`** alongside the data args, and call their
+  methods. A spec never needs a service's helpers.
+- **Guard a no-op by returning an unchanged patch**, never by throwing. Reserve
+  `throw` for a precondition a case names with `throws`.
+- **A derivation** is `(state) => value`. It specs one computed of the same name.
+- **Per-frame work** in a real-time feature is a `systems.ts` barrel: one pure
+  function per ECS system, named the same, with the ordinary transition signature
+  (below). There is no hand-written `step`: the frame order comes from the systems'
+  `schedule`.
+- Share logic with the ECS through `data/values/` helpers, never by the ECS importing
+  the spec.
+
+## Cases — `<name>.cases.ts`
+
+Inert data, annotated `Conformance.SpecCases<State, typeof fn>` for an action or
+`Conformance.SpecDerivations<typeof fn>` for a derivation (the annotation is what
+tells them apart).
+
+```ts
+export const cases: Conformance.SpecCases<State, typeof toggleComplete> = {
+  args: { type: "object", properties: { id: Entity.schema } },   // marks entity-reference args
+  cases: [{
+    name: "marks an incomplete todo complete",
+    before: { entities: new Map([[1, { name: "a", complete: false, order: 0 }]]) },
+    args: { id: 1 },
+    after: { entities: new Map([[1, { name: "a", complete: true, order: 0 }]]) },
+    effects: { analytics: [["todoToggled"]] },
+  }],
+};
+```
+
+- **`before`** is a delta over `State.create()`; **`after`** is the writes patch; a
+  derivation case is `{ name, input, value }`.
+- **`args` is data only.** Services never appear in cases. A value-returning service
+  method's results are scheduled in **`responses`** — calling one with nothing
+  scheduled, or more times than scheduled, fails the case — and calls to assert go in
+  **`effects`** (`Array` = ordered, `Set` = any order).
+- **Ids are plain numbers** everywhere; conformance compares them up to an id
+  bijection. Mark entity-reference args in the `args` schema.
+- **`throws: true | "substring"`** replaces `after` for a precondition failure.
+- A spec-only fixture helper (`marksOf("XX  O    ")`) may build case values.
+
+## `transforms.ts`, `spec.ts`, `spec.test.ts`
+
+```ts
+// transforms.ts — exactly the conformed actions and derivations
+export { toggleComplete } from "./toggle-complete.js";
+export { visibleTodos } from "./visible-todos.js";
+
+// spec.ts
+export const spec = Conformance.spec({
+  state: State,
+  fns: transforms,
+  schemas: { ...components, ...resources },   // when State holds entity references
+  services: { analytics: AnalyticsService.createFake },   // when an action injects one
+  cases: { toggleComplete, visibleTodos },
+});
+
+// spec.test.ts
+Conformance.checkSpec(spec);
+```
+
+`Conformance.spec` checks at compile time that every fn has exactly one case module,
+and that `services` lists exactly the services the actions and systems inject.
+
+## Systems (real-time features)
+
+```ts
+// systems.ts — one pure function per ECS system, each guarding itself
+export const movement = whilePlaying((s, { dt }) => ({ asteroids: stepAsteroids(s, { dt }) }));
+export const collision = whilePlaying((s) => ({ ...resolveHits(s) }));
+
+// spec.ts
+export const spec = Conformance.spec({ …,
+  systems: {
+    fns: systems,
+    cases: { movement, collision },
+    noOp: [{ name: "frozen once the game is over", before: { status: "over" }, args: { dt: 1 } }],
+  },
+});
+```
+
+- **Mirror the ECS systems one to one.** When a system fuses two logical steps, its
+  function composes both; when two systems split one step, split the function too
+  (the handoff must be a `State` field).
+- **One `SpecCases` module per system**; `checkSpec` runs them against the functions.
+- **`noOp`** lists states every system must leave unchanged (game over, paused). Each
+  is checked against every system, so a shared guard needs one case, not one per
+  system.
+- **Whole-frame cases** depend on the ECS's schedule, so they live with the
+  implementation (`../ecs/conformance.md`), not here.
+- A system the spec can't model (wasm physics, init-only seeding) has no function;
+  the implementation declares it unmodelled (`../ecs/conformance.md`).

package/.claude/rules/features/ui/binding-element.md

@@ -1,8 +1,8 @@
 ---
 paths:
-  - 'src/**/*element*.ts'
-  - 'src/**/elements/**/*.ts'
-  - 'src/**/ui/**/*-element.ts'
+  - '**/src/**/*element*.ts'
+  - '**/src/**/elements/**/*.ts'
+  - '**/src/**/ui/**/*-element.ts'
 ---
 
 # Binding elements
@@ -101,7 +101,7 @@ render() {
     // UI action call with simple ternary — good
     jump: (heroMode: boolean) => this.service.actions.move(heroMode ? 100 : 10),
     // transaction call - good
-    play: this.service.transactions.playTrack
+    play: this.service.actions.playTrack
   });
 }
 ```
@@ -218,7 +218,7 @@ export class BadControlElement extends FooElement {
       // violation: logic in callback + onX name
       const normalized = Math.round(v * 100) / 100;
       if (!Number.isFinite(normalized)) return;
-      this.service.transactions.updateThing({ value: normalized });
+      this.service.actions.updateThing({ value: normalized });
     };
     return presentation.render({ total: clamped, onSave });
   }