@adobe/data-ai 0.9.91 → 0.9.93

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

@@ -15,9 +15,10 @@ discriminated unions.
 ## Example
 
 ```ts
-// types/http-method/schema.ts
-export const schema = { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] }
-    as const satisfies Schema;
+// types/http-method/http-method.ts — the hand-authored type owns the member identity
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+// (a schema.ts, if/when a runtime boundary needs one, is written to match this
+//  type and pinned to it — see global/namespace.md and features/data/index.md)
 
 // In an unrelated request-counter plugin:
 

package/.claude/rules/ecs.md

@@ -143,7 +143,7 @@ Synchronous, deterministic atomic mutations. Receive `store` and a payload.
 
 ### actions
 
-UI components that call actions must never consume returned values — see `.claude/rules/binding-element.md` (Actions are fire-and-forget).
+UI components that call actions must never consume returned values — see `features/ui/binding-element.md` (Actions are fire-and-forget).
 
 **At most one transaction per action.** Multiple transactions in a single action corrupt the undo/redo stack.
 

package/.claude/rules/element.md

@@ -125,7 +125,7 @@ exists *only* for locator inputs — never for state, never for derived
 values, never for parent-forwarded flags. The `P` in `DatabaseElement<P>` (and
 the `get plugin()` it returns) is the surface the element *consumes* — never the
 varying topmost-layer name (see `features/services/main-service/index.md`): `typeof
-FeatureDatabase.plugin` for a self-contained feature. **Exception:** an element
+MainService.plugin` for a self-contained feature. **Exception:** an element
 meant to be *extended* — injected with various databases that build on this
 feature (a peer app that adds an agent, a p2p/presence build) — types on the
 minimal base layer it consumes (e.g. `ComputedDatabase.plugin`) so every

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

@@ -5,30 +5,75 @@ paths:
 
 # data/ — the data model
 
-The foundation layer: the feature's **data types**. A data type is a
-readonly, JSON-serializable value suitable for persistence and for
-communication over the wire — no functions, no handles, just plain data.
-It depends on nothing but `@adobe/data` and other `data/` declarations, and
-needs no knowledge of anything built on top of it.
+The foundation layer: the feature's **data types** and the pure declarations
+over them. A data type is a readonly, JSON-serializable value suitable for
+persistence and for communication over the wire — no functions, no handles, just
+plain data. A `data/` **type** depends on nothing but `@adobe/data` and other
+`data/` types, and needs no knowledge of anything built on top of it. The
+**transitions** over those types are less restricted: when one injects a service
+it may import freely from `services/` — the service type and any utilities its
+namespace exposes (see `state.md`). What it must **never** touch is `ui/`:
+`data/` never depends on presentation — that isolation is strict and inviolable.
+Only *services themselves* are never authored here; that is what makes this the
+value-type layer.
 
 Each data type is its own namespace folder (see `global/namespace.md`), holding
-its schema, its derived type, and its pure synchronous helpers together:
+its hand-authored type, its (optional, matching) schema, and its pure
+synchronous helpers together:
 
 ```
 data/player-mark/
-  player-mark.ts   # type alias + `export * as PlayerMark from "./public.js"`
-  schema.ts        # `export const schema = { … } as const satisfies Schema`
+  player-mark.ts   # HAND-AUTHORED type + `export * as PlayerMark from "./public.js"`
+  schema.ts        # (optional / later) schema matching the type, pinned via Assert<Equal<…>>
   public.ts        # re-exports schema + helpers
   is.ts  values.ts  opponent.ts  …   # one pure helper per file
 ```
 
-- The **type is derived from the schema** (`Schema.ToType<typeof schema>`),
-  never hand-written alongside it.
-- The **schema is the single source of truth** for the shape; the derived
-  type and every consumer flow from it.
+- The **type is authored by hand** in `<type>.ts` — the readable source of
+  truth. Write it with the richest types available (`F32`, `Vec3`, unions,
+  branded aliases) so members carry their semantic meaning and get strong
+  IntelliSense / hover docs.
+- The **schema is derived from the type, not the reverse.** It is written to
+  match the type and **pinned** to it with a compile-time assertion so the two
+  cannot drift (see below). A field typed as a branded primitive reuses that
+  type's schema — `F32` → `F32.schema`, `Vec3` → `Vec3.schema`.
+- **Schemas are optional until a runtime boundary needs one.** A pure `data/`
+  type is complete with `<type>.ts` alone. The schema is added only when
+  persistence, the wire, or an ECS component/resource requires it — and is
+  typically written by the agent in a later phase (e.g. when implementing the
+  ECS), not by the human up front.
 - Helpers are synchronous and pure; each has a sibling `*.test.ts`.
-- Objects with only numeric 32 bit values/sub-structs should use Schema.fromStructProperties
-  It guarantees a valid struct schema which will be stored in linear memory.
+- Objects of only 32-bit numeric values / sub-structs: the schema uses
+  `Schema.fromStructProperties` (guarantees a valid struct schema, stored in
+  linear memory).
+
+## Pinning the schema to the type
+
+The type is written first and by hand; the schema is written to match it and
+is locked to it at compile time, so schema authoring (whenever it happens)
+cannot silently drift from the type readers rely on.
+
+```ts
+// player-mark/player-mark.ts — HAND-AUTHORED, the source of truth
+export type PlayerMark = 'X' | 'O';
+export * as PlayerMark from './public.js';
+
+// player-mark/schema.ts — written to MATCH the type (often later, by the agent)
+import { Schema } from '@adobe/data/schema';
+import type { Assert, Equal } from '@adobe/data/types';
+import type { PlayerMark } from './player-mark.js';
+
+export const schema = { type: 'string', enum: ['X', 'O'] } as const satisfies Schema;
+
+// Compile-time pin: fails to build if schema and type diverge.
+type _Pin = Assert<Equal<Schema.ToType<typeof schema>, PlayerMark>>;
+```
+
+The `Assert<Equal<…>>` line is the whole safety net: `Schema.ToType<typeof
+schema>` must be exactly the hand-authored type (including readonly/optional),
+or the file does not compile. `Schema.ToType` is used **only** inside the
+assertion — never as the exported type. Consumers always import the
+hand-authored `PlayerMark`.
 
 One folder is special: **`data/state/`** holds the feature's single `State`
 aggregate and its pure transforms/derivations (its own rule, `state.md`);

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

@@ -5,52 +5,212 @@ paths:
 
 # data/state/ — the State specification
 
-`State` is the whole feature modelled as **one immutable object** — the
-pure, fully-tested source of truth for the feature. Modelling everything as
-a single value keeps each transform a small, trivially-testable function of
-state: collections of entity sub-types plus scalar fields.
+`State` is the whole feature as **one immutable object** — the pure, fully-tested
+source of truth. Each transition is a read→write **patch** over state; each
+derivation a pure selector. Reference: `data-lit-todo`'s `data/state/`.
 
-Every feature that has ECS resources or transactions owns a `State` — including
-a host whose aggregate is a single scalar (`{ playing: boolean }`) or even when there is no state in which case use `{}`. 
 ```ts
-// state.ts — the aggregate, plus the namespace of transforms/derivations.
-export type State = {
-    readonly todos: readonly Todo[];        // a collection of entity sub-types
-    readonly displayCompleted: boolean;     // a scalar field
-};
+// state.ts — the aggregate + the transition/derivation namespace.
+export type State = { readonly todos: readonly Todo[]; readonly displayCompleted: boolean };
 export * as State from "./public.js";
 ```
 
-## Transforms — one per file, `(state, …args) => state`
-
-- **Pure.** No I/O, no framework, no mutation — return a new value.
-- **Narrow in, same shape out.** Write on the smallest slice the transform
-  needs and keep the input generic over that slice so it lifts to
-  full-state-in / full-state-out:
-
-  ```ts
-  export const playMove = <T extends Pick<State, "board" | "firstPlayer">>(
-      state: T,
-      input: PlayMoveArgs,
-  ): T => { /* … return { ...state, board: … } */ };
-  ```
-
-  A whole-`State` transform (`restartGame(state: State): State`) is fine when
-  it genuinely touches everything.
-- Args may be **narrowed or omitted** (`toggleDisplayCompleted(state)`).
-- Guard and **return `state` unchanged** on a no-op / illegal input rather
-  than throwing — this keeps transforms idempotent under repeated application.
-- Each transform has a sibling `*.test.ts`; performance is irrelevant here,
-  correctness is everything. Keep its cases in a sibling `<transform>.cases.ts`
-  typed `ConformanceCase<Args>[]` (the shared `conformance-case.ts` type) —
-  spec-owned truth the matching main-service conformance test imports unchanged (see
-  `services/main-service/conformance.md`). Author `before`/`after` as full `State`
-  (`{ ...State.create(), …overrides }`); the generic-slice signature lets them
-  flow through. Tolerant full-`State` equality is the shared
-  `expect-state-matches.ts`, alongside the cases here.
-
-## Derivations — `(state) => value`
-
-Pure selectors (`visibleTodos(state)`). Sub-type math (a winner, a status)
-lives on the relevant `data/<type>` namespace; `state/` only composes over
-the whole aggregate.
+Every feature with ECS resources/transactions owns a `State` (a scalar
+`{ playing: boolean }`, or `{}` when there is none).
+
+**`State` has a standard shape.** Two exports are conventional and drive
+conformance:
+
+- **`create(): State`** (`data/state/create.ts`) — the default state. Every
+  conformance case's `before` is a **delta over `State.create()`**, and both the
+  pure `spec.test.ts` and the ecs `runFeature` seed from it.
+- **`samples: readonly State[]`** (`data/state/samples.ts`) — representative
+  **full** states `runFeature` round-trips through the projection
+  (`toState ∘ fromState ≡ identity`, see `conformance.md`).
+
+Both are re-exported through `public.js`, so `State.create()` / `State.samples`
+are namespace members. (A `cases` literal must still not touch `public.js` at
+load — import `create` from `./create.js` directly there; see below.)
+
+**The discovered transitions are a test-only sibling, NOT on the namespace.**
+`data/state/transitions.ts` exports one `import.meta.glob` of the folder — the
+`{ fn, cases }` modules — imported by *both* `spec.test.ts` and the ecs
+`conformance.test.ts` so the glob is authored once per feature:
+
+```ts
+// data/state/transitions.ts — test-only; both test entry points import it
+export const transitions = import.meta.glob<Record<string, unknown>>(
+  ["./*.ts", "!./*.test.ts", "!./*.type-test.ts", "!./transitions.ts"],
+  { eager: true },
+);
+```
+
+It stays **out of `public.js`** deliberately: unlike `create`/`samples` (plain
+prod-safe values), `transitions` is the test-case graph — hanging it on `State`
+would drag `import.meta.glob` (a Vite-only construct) and every `cases` fixture
+(fake services, matchers, the whole `@adobe/data/testing` module) into every
+production import of `State`, none of which tree-shakes off a live namespace
+re-export. So `create`/`samples` earn a namespace slot; `transitions` is a test
+concern the tests import directly.
+
+## One file per transform: the function **and** its cases
+
+A transform file exports **exactly two things** — the function and its
+`cases` — nothing else (a private helper is fine; a second export is not, and the
+spec aggregator throws if it finds one). The cases are the spec-owned truth every
+conformance runner reuses; co-locating them removes the per-transform `.cases.ts`
+and `.test.ts`.
+
+**Why co-locate `cases` (not a sibling `*.test.ts`)?** They are spec-owned
+fixtures the pure `spec.test.ts` **and** the ecs `runFeature` call both reuse
+(driving transaction / action / computed conformance) — the transform's contract
+expressed as data, not a per-file test — so they belong
+beside the thing they specify, and `Conformance<typeof fn>` binds them to the
+signature so they can't drift. Kept inert (no `describe`; one aggregator runs
+them) they also sidestep the double execution vitest triggers when a single file
+both exports cases and runs its own `describe`. Coverage is then enforced
+centrally by the shared driver's barrel-driven guard rather than by eyeballing
+one test file per transform — and genuine non-transition helpers still keep
+their own `*.test.ts` (see below).
+
+The case types, matchers, and runners all live in the shared
+**`@adobe/data/testing`** module (two namespaces, `Match` and `Conformance`;
+`vitest` is an *optional* peer dependency, already satisfied here). Only one
+tiny per-feature file remains — a ~10-line alias, `conformance-case.ts`, that
+binds `State` once so transform/derivation files can write a one-parameter type:
+
+```ts
+// data/state/conformance-case.ts — the only per-feature conformance declaration
+import { Conformance as ConformanceApi } from "@adobe/data/testing";
+import type { State } from "./state.js";
+export type Conformance<F extends (...args: never[]) => unknown> = ConformanceApi.Cases<State, F>;
+export type Derivation<F extends (...args: never[]) => unknown> = ConformanceApi.DerivationCases<F>;
+export type Effects<Args> = ConformanceApi.Effects<Args>;
+// The entity-reference marker for identity-addressed case args, re-exported so
+// cases import it beside `Conformance`: `args: { id: entity(2) }`.
+export const entity = ConformanceApi.entity;
+```
+
+```ts
+// create-todo.ts
+import { Match } from "@adobe/data/testing";
+import type { Conformance } from "./conformance-case.js"; // the thin per-feature alias above
+export const createTodo = (
+    state: Pick<State, "todos">,
+    { name, complete, analytics }: { name: string; complete?: boolean; analytics: AnalyticsService },
+): Pick<State, "todos"> => {
+    analytics.todoCreated({ name });
+    return { todos: [...state.todos, { name, complete: complete ?? false }] }; // writes patch only
+};
+
+export const cases: Conformance<typeof createTodo> = [
+    { name: "appends the first todo",
+      before: {},                       // empty delta — the default State.create()
+      args: { name: "a", analytics: AnalyticsService.createFake() },
+      after: { todos: [{ id: Match.anyNumber, name: "a", complete: false }] }, // only the changed field
+      effects: { analytics: [["todoCreated", { name: "a" }]] } },
+];
+```
+
+- **Signature** `(state: Pick<State, …reads>, args) => Pick<State, …writes>` — a
+  **read→write patch**. The parameter is the smallest `Pick<State,…>` the
+  transition **reads**; the return is *only the fields it **writes***. **No
+  `<T> => T` generic, no `...state` spread** in the return — return the patch and
+  let the runner merge it. **All non-state inputs go in the single `args` object**
+  (`Conformance<typeof fn>` reads `Parameters[1]`) — bundle a `dt`, an injected
+  service, etc. into it, never as a third positional. A transition that takes
+  **no** args omits `args` from each case entirely (the shared `Case` type makes
+  `args` optional exactly then). **Guard no-ops by returning an empty patch `{}`**
+  (or the unchanged slice), never throw.
+- **A composer merges sub-patches explicitly.** A transition built from smaller
+  ones spreads them — `return { ...s, ...sub(s) }` — so each sub-patch's writes
+  layer in; a transition that merely **delegates** to one sub-transition returns
+  that delegate's patch directly (no spread needed).
+- **Co-located `cases` must not touch the feature's `public.js` barrel at module
+  load** — that barrel re-exports this very file, so calling `State.create()` (or
+  any barrel member) in a top-level `cases` literal dead-locks the import cycle.
+  Import the concrete helper directly (`import { create } from "./create.js"`) or
+  inline full-`State` literals.
+- **`Conformance<typeof fn>`** (the alias above) derives the case `args` type from
+  the function's own signature — author it once, and cases can't drift from what
+  the function accepts. **`before` is a delta over `State.create()`** — list only
+  the fields this case sets differently from the default; **`after` is the writes
+  patch** — only the fields the transition changes. The runner seeds
+  `{ ...State.create(), ...before }` and compares against
+  `{ ...State.create(), ...before, ...after }`, so any field a case doesn't mention
+  is the default and stays unchanged. (A full `before`/`after` still works — it just
+  overrides the default wholesale.)
+- **`after` leaves minted values open** with the shared matchers `Match.anyNumber`
+  / `Match.anyString`, imported from `@adobe/data/testing` — there is **no**
+  per-feature `matchers.ts` anymore. An id the ECS assigns from its own id-space is
+  `id: Match.anyNumber`, so the pure spec and the ECS satisfy the same case — match
+  by content, not by the value you don't control. `Match` is framework-agnostic and
+  honors any asymmetric matcher, so vitest's `expect.stringContaining(...)` interops
+  on the expected side too. When an id must **line up in two places** within one
+  comparison — a `selectedId` that points at a specific todo, say — use
+  `Match.ref(label)`: it asserts id *correspondence* (a bijection up to renaming),
+  not a pinned value, so the two occurrences of the label must resolve to the same
+  actual id and two labels can't collide. `anyNumber`/`anyString` are for an id a
+  case does not pin at all; `ref` for one that must be consistent across the case.
+- **Entity-addressed cases use `entity(specId)`.** A transition that addresses an
+  entity by id writes it as `args: { id: entity(2) }` — `entity` imported from the
+  feature's `conformance-case.ts` (re-exported from `@adobe/data/testing`). It types
+  as the id it stands for (like `Match.anyNumber`), so it slots into the transform's
+  own arg type. `runSpec` unwraps it to the plain data-id for the pure side; the ECS
+  runners resolve it to the seeded entity (see `conformance.md`).
+- No per-transform test. The single **`spec.test.ts`** is one call —
+  `Conformance.runSpec({ state: State, transitions })` importing `transitions`
+  from the test-only `./transitions.js` (above) — that auto-discovers every module
+  exporting `cases`, enforces the two-exports rule, and dispatches on case shape (a
+  `value` case → derivation; otherwise a transition whose declared `effects` are
+  also asserted). Passing `{ state: State }` (the same `state` shape `runFeature`
+  takes) is what makes each case's `before`/`input` a delta over `State.create()`.
+  Add `match` alongside it only when
+  the feature needs float tolerance or unordered collections (see `conformance.md`).
+  There is no per-feature `expect-state-matches.ts`, `record-effects.ts`,
+  `expect-conforms.ts`, or `conformance-case.type-test.ts` — those are gone; the
+  shared driver owns comparison, effect recording, and name-based auto-pairing, and
+  the `Effects` type-test now lives once in `@adobe/data/testing`. A genuine **non-transition helper** in
+  `state/` — a `create()` constructor, a single-field predicate — has no `cases`
+  and isn't a `(state,args)=>state` transform, so `runSpec` skips it: **keep its own
+  sibling `*.test.ts`** rather than deleting it and losing coverage.
+
+## Injected services and side effects
+
+A transform that needs an outside capability receives it as a **named parameter**
+in the args object, keyed by the service name minus its `-service` suffix
+(`AnalyticsService` → `analytics`, `NameGeneratorService` → `nameGenerator`);
+plain data args sit alongside. Import the service straight from `services/` (an
+ordinary import — layers split by kind of type, not dependency). The **same
+services appear on `db.services` for the matching action**, so the transition is
+the complete spec of *both* the state change and the service calls.
+
+- A transition **is deterministic given its dependencies** — inject a fixed
+  double and the output (and its calls) are fixed. An **async** dependency makes
+  the transition `Promise<State>`; keep sync the default.
+- **Side effects are declared in the case's `effects`**, keyed by the service
+  arg, as `[methodName, ...args]` tuples — an `Array` asserts these calls in
+  order, a `Set` in any order. Only listed services are checked (a value-returning
+  read like `generateName` you don't list is ignored). See `conformance.md` for
+  how the recording double captures them.
+- Tests inject **deterministic doubles** (never production) whose published
+  responses the case's `after`/`effects` are authored against — doubles live
+  adjacent to the interface (`features/services/index.md`).
+
+## Derivations — `(state) => value`, cases `{ input, value }`
+
+Pure selectors that **compose the aggregate** — a value drawn from **two or more
+`State` fields** (`visibleTodos` from `todos` + `displayCompleted`;
+`currentPlayer` from `board` + `firstPlayer`). A value computed from a **single**
+`State` field is that field's own type math and lives on its `data/<type>`
+namespace (`winner`/`status` from `board` → `data/board-state`), tested there —
+**not** in `state/`. A feature may therefore have zero `state/` derivations.
+
+A `state/` derivation co-locates cases shaped `{ input, value }`, typed
+`Derivation<typeof fn>` (input + value read from the signature). Take the **full
+`State`** as the parameter (not a `Pick` slice like a transform) — so the case
+`input` type is the full `State` and computed conformance can seed it via
+`fromState`; `value` may use matchers. The same `spec.test.ts` runs them (dispatching on case shape),
+and each ECS computed backing one is conformance-tested from the same cases
+(`conformance.md`). Sub-type math (a winner, a status) lives on the
+relevant `data/<type>` namespace; `state/` only composes over the aggregate.

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

@@ -26,9 +26,25 @@ derive a fast one that provably behaves the same.
 
 ## The layers
 
-`ui → 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.
+**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 |
 |-------|------|
@@ -85,13 +101,16 @@ 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 projection and
-its runner live in `services/main-service/conformance/` (see
-`services/main-service/conformance.md`); the shared `{ before, args, after }`
-cases are spec-owned (`data/state/<transform>.cases.ts`), so conforming the
-implementation is "substitute the implementation, reuse the expectations." This
-lets `main-service` be largely mechanical and agent-generated, with the spec as
-oracle. *How* to author each layer lives in the per-folder rules below.
+projection, equals the pure `data/` transform it stands for. The per-feature
+projection lives in `services/main-service/conformance/`, and a **single
+`Conformance.runFeature({...})` call** replays the shared cases against the ecs —
+pairing each ECS op to its same-named transition automatically and round-tripping
+the projection (see `services/main-service/conformance.md`);
+the shared `{ before, args, after }` cases are spec-owned — co-located in each
+`data/state/<transform>.ts`, which exports its function plus `cases` — so
+conforming the implementation is "substitute the implementation, reuse the
+expectations." This lets `main-service` be largely mechanical and agent-generated,
+with the spec as oracle. *How* to author each layer lives in the per-folder rules below.
 
 ## Reference implementations
 

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

@@ -33,6 +33,25 @@ portability and lazy loading (`AsyncDataService.createLazy`).
 - Members are async only: `void | Promise<T> | AsyncGenerator<T> | Observe<T>`.
 - Provide `create*` factories.
 
+## Deterministic test doubles, adjacent to the contract
+
+A service is the seam consumers swap out under test — `data/` transitions that
+take it as an injected dependency (`data/state.md`), actions, systems. Ship a
+**deterministic test double** alongside the interface, in the same namespace
+folder and under the same `global/namespace.md` standard: `create-fake.ts` is a
+**single export**, `createFake`, re-exported through `public.ts` so callers reach
+it as `MyService.createFake` (mirroring the `create` / `factory` pair).
+
+Because tests assert on exact `after` values, the double must be **deterministic
+and its responses caller-controlled**: `createFake` takes the exact response — the
+fixed value, or the ordered sequence each method returns — as a parameter, with a
+small inline default. A conformance case then **injects the responses it needs**
+(`createFake(["random task"])`, `createFake([4])`) and authors its `after` /
+`effects` against those values it supplied — nothing is read from a shared
+published constant (that would be a second export, and it makes the assertion
+guess at a value it doesn't own). The injected schedule is exactly what makes the
+double a dependable oracle: the test controls both the input and the expectation.
+
 ## Where the I/O types live
 
 Most input/output types belong to a single service — declare them **on that

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

@@ -10,23 +10,57 @@ argument and pure `data/` args. Actions orchestrate anything *outside* a
 single transaction — awaiting a `services/` port, sequencing calls, deriving
 timing — and then commit the result through a transaction.
 
+**Every *app-facing, transaction-backed* transition has a corresponding
+same-named action** — the async realization the UI drives. It reads the same
+services the transition injects from `db.services`, so it reproduces both the
+transition's state change (through a transaction) and its side effects. It may
+reuse another transition's transaction (`createRandomTodo` reuses `createTodo`) —
+there need not be a same-named transaction; transactions are the looser layer.
+
+**Per-frame / system transitions are exempt.** In a real-time feature the `step*`
+/ physics / collision transitions are realized by the **systems** tick loop, not
+by an action, and are conformed by the tick-loop test (`systems.md`), not the
+action surface of `runFeature`. Give an action only to transitions a user/UI invokes directly
+(and skip it too when the realization needs more than one transaction — e.g. a
+`newGame` that both sets bounds and resets is conformed via its transaction).
+
 ```ts
 import type { ServiceDatabase } from "../../service-database/service-database.js";
 
-export const addRandomTodo = async (db: ServiceDatabase) => {
-    const name = await db.services.nameGenerator.generateName(); // await a services/ port
-    db.transactions.createTodo({ name });                        // then exactly one commit
+export const addRandomTodo = async (service: ServiceDatabase) => {
+    const name = await service.services.nameGenerator.generateName(); // await a services/ port
+    service.transactions.createTodo({ name });                        // then exactly one commit
 };
 ```
 
-- Type the `db` parameter on the lowest database layer exposing what the
+- Type the `service` parameter on the lowest database layer exposing what the
   action touches — usually `ServiceDatabase` (services **and**
   transactions). Never the action layer itself (that would be a cycle).
 - **Call at most one transaction** per action, so undo/redo stays one step
   per operation.
 - **Fire-and-forget.** An action's return value is not consumed; results flow
-  back through observables. `db.services.*` calls are `void` or
+  back through observables. `service.services.*` calls are `void` or
   awaited-internally, never surfaced to the caller.
 - Do the outside-world work here: await/sequence `services/` calls, and if a
   slow call needs timing, compute it here around the call.
+- **Read current state synchronously from the store** (`db.resources` / `db.read`
+  / `db.select`, then a pure `data/` helper) — never from a cached `computed`.
+  Reactive computeds refresh only on a committed transaction, so an imperative
+  read of one can hand back a stale shared cache (and it's the UI's layer, not
+  the action's). This also keeps the action correct under the conformance seed.
+- **Conformance** is the action surface of the feature's single
+  `conformance/conformance.test.ts` `Conformance.runFeature({...})` call. It pulls
+  actions off **`plugin.actions`** and pairs each to the **same-named** `data/state`
+  transition. **The action is the primary seam** — it reads injected services from
+  `db.services`, so the case's service args become recording overrides (the runner
+  builds `Database.toSystemDatabase(Database.create(plugin, { services }))`); it
+  splits the case `args` into services and plain input, runs the action, then
+  `Match.assert`s `toState ≡ after` **and** checks the recorded calls against the
+  case's `effects`. There is no `define`/`conforms` and no coverage guard. A thin
+  **same-named** action gives a transaction-only or renamed transition something to
+  pair with (todo's `reorderTodo`). A streaming/capability action with no transition
+  is skipped. **A per-transition action kept out of the facet** (to bound the
+  plugin's type) is discovered via `runFeature`'s `ops.actions` glob —
+  `ops: { actions: import.meta.glob([".../actions/*.ts", "!.../actions/index.ts"], { eager: true }) }`
+  (p2p negotiation). That is the *only* reason to pass `ops` (see `conformance.md`).
 - An `index.ts` barrel feeds the `actions` plugin facet.

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

@@ -7,20 +7,71 @@ paths:
 
 One derived value per file: a `cached` function of a database layer that
 returns an `Observe` of state projected through pure `data/` helpers.
-Derivation logic itself lives in `data/`; a computed only wires a db
+Derivation logic itself lives in `data/`; a computed only wires a service
 observable to it.
 
+**Reuse tested pure logic; let performance pick the wiring.** Prefer wiring the
+pure **`data/<type>` helper** (or composing indexes) directly — the tictactoe
+computeds delegate their observable straight to
+`BoardState.deriveStatus`/`getWinner`/`currentPlayer` — because a helper reads
+exactly the resource/entities it needs, and both the computed and the matching
+`state/` derivation call it, so they agree by construction.
+
+You **may** also import a pure `state/` derivation `(state) => value` into a
+computed where performance is adequate: a small-N or resource/scalar composition,
+not a hot per-entity or large-N path. Reusing a tested derivation is good — the
+only cost is that it takes the **whole `State`**, so the computed must observe the
+full-state projection and re-runs on *any* field change (fine for a small feature,
+wasteful on a large or hot one, where you hand-wire the minimal resource/index
+reads instead). A derivation takes **no services**, so its co-located `cases` are
+inert `{ input, value }` data (no test-doubles) that tree-shake out of the app
+build (they reference the `@adobe/data/testing` matchers only, and that module is
+`sideEffects: false`) — the one hazard is a `cases` literal touching the
+`public.js` barrel at load, which `state.md` already forbids. **Performance is the
+first-class constraint**: reuse freely where it doesn't matter, hand-wire minimal
+reads where it does.
+
 ```ts
 import { cached } from "@adobe/data/cache";
 import { Observe } from "@adobe/data/observe";
 import { BoardState } from "../../../data/board-state/board-state.js";
 import type { IndexDatabase } from "../../index-database/index-database.js";
 
-export const status = cached((db: IndexDatabase) =>
-    Observe.withFilter(db.observe.resources.board, BoardState.deriveStatus),
+export const status = cached((service: IndexDatabase) =>
+    Observe.withFilter(service.observe.resources.board, BoardState.deriveStatus),
 );
 ```
 
 Type the parameter on the lowest database layer that exposes what it
 reads. An `index.ts` barrel re-exports every computed; `computed-database.ts`
 registers it under the `computed` facet.
+
+**Conform a computed to its `data/state` derivation** whenever one exists. The
+derivation co-locates `{ input, value }` cases (`Derivation<typeof fn>`), and the
+feature's single `conformance/conformance.test.ts` `Conformance.runFeature({...})`
+call conforms computeds: it pulls them off **`computedPlugin.computed`**, pairs each
+to its **same-named** derivation, seeds the store from `input`, reads the computed's
+synchronous emission, and `Match.assert`s it against `value` (see `conformance.md`).
+There is no `define`/`conforms` wiring. **`computedPlugin` is the `ComputedDatabase`
+layer** — the runner builds computed conformance from that layer, not the assembled
+`MainService`, so a `withCache` above can't hand back a stale pre-seed value (a
+direct `fromState` seed emits no transaction to invalidate it). Comparison is
+identity by default; a computed that emits an **entity-id list** names itself in
+`hydrate: [...]` (todo's `visibleTodos`) so the runner projects each id through
+`toData`. A computed with **no `state/` derivation is skipped** —
+single-`data/<type>` math is covered by that helper's own test. A feature with no
+`state/` derivation omits `computedPlugin` entirely.
+
+**What needs conformance is proportional to wiring logic.** A computed that
+composes/branches over the aggregate *is* a `state/` derivation (composes ≥2
+fields) and is conformed here. A computed that **trivially applies one
+`data/<type>` helper to one field** (`winner` ← `BoardState.getWinner(board)`) is
+already covered by its parts — the field by `toState` conformance, the math by
+that helper's unit test — so an added conformance would just re-invoke the same
+helper on both sides (tautological); the helper's unit test is sufficient. Two
+exceptions: (1) to pin a particular non-obvious wiring, promote it to a thin
+`state/` derivation `(state) => Type.helper(state.field)` and the runner conforms
+it — no new mechanism; (2) if a computed folds **entities into a value with no
+intermediate `State` field**, that projection *is* unconformed — promote the
+intermediate to a `State` field so `toState` covers it, making it a normal
+`state/` derivation.