@adobe/data-ai 0.10.19 → 0.10.20

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

@@ -7,380 +7,203 @@ paths:
 
 `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/`.
+derivation a pure selector. The ECS implementation is proven equivalent to it by
+conformance (`../services/main-service/conformance.md`). Reference:
+`data-lit-todo`'s `data/state/`.
 
-The presence of this folder makes the feature **state-based** — its Functional
-State Specification is authoritative and the ECS conforms to it. A feature without
-`data/state/` is **ECS-based** (the ECS is the source of truth, no conformance) and
-this rule does not apply — see `../index.md`, Two modes.
+The presence of this folder makes the feature **state-based**. A feature without
+`data/state/` is **ECS-based** (no spec, no conformance) — see `../index.md`.
 
-```ts
-// data/todo/todo.ts — an entity value type: plain readonly data, NO id.
-export type Todo = { readonly name: string; readonly complete: boolean; readonly order: number };
-export * as Todo from "./public.js";
-
-// data/todo/is.ts — a structural type guard, re-exported so it reads as `Todo.is`.
-// `"k" in v` narrows `v` so each field reads without a cast.
-export const is = (v: unknown): v is Todo =>
-  typeof v === "object" && v !== null &&
-  "name" in v && typeof v.name === "string" &&
-  "complete" in v && typeof v.complete === "boolean" &&
-  "order" in v && typeof v.order === "number";
+## The `State` shape
 
-// data/state/state.ts — singletons + one identity-keyed entity map.
+```ts
+// data/state/state.ts
 export type State = {
   readonly displayCompleted: boolean;            // a SINGLETON → an ECS resource of the same name
   readonly entities: ReadonlyMap<number, Todo>;  // ALL entities, keyed by id; the value has no id
+  readonly selectedTodo: Entity;                 // a reference singleton (Entity is a branded number)
 };
 export * as State from "./public.js";
 ```
 
-Every **state-based** feature owns a `State`. An ECS-based feature has none.
-
-## The standard `State` shape
+- **Singletons** — every non-`entities` field → an ECS **resource** of the same name.
+- **`entities`** — one `ReadonlyMap<number, EntityValue>` holding every entity, keyed
+  by a numeric id; the value type is the union of the feature's entity value types and
+  carries **no `id`** (identity is the key). Omit `entities` for a feature with no
+  entities (all singletons).
 
-A `State` has two kinds of field:
+`State` may reuse plain ECS value types (the `Entity` id type, a `{ parent, order }`
+bundle) but never ECS machinery (a store, a transaction, an index). Entity value types
+are their own `data/<type>/` namespaces with a structural `is` guard (`../index.md`).
 
-- **Singletons** — every non-`entities` field (`displayCompleted`, a `score`, a
-  `board`). Each becomes an ECS **resource** of the same name (see
-  `../services/main-service/resources.md`).
-- **`entities`** — a single `ReadonlyMap<number, EntityValue>` holding *every* entity,
-  keyed by a numeric id, where `EntityValue` is the union of the feature's entity value
-  types (`Todo`, or `Bullet | Asteroid`). Omit `entities` entirely for a feature with
-  no entities (`tictactoe`, `dashboard`) — it is then all singletons.
+Two conventional exports drive conformance, re-exported through `public.js`:
+- **`create(): State`** (`create.ts`) — the default; every case's `before`/`input` is a
+  delta over it.
+- **`samples: readonly State[]`** (`samples.ts`) — representative full states the ecs
+  projection round-trips (`toState ∘ fromState ≡ identity`).
 
-This maps 1:1 to the ECS. `State` must not depend on ECS *machinery* (a store, a
-transaction, an index) — but it **may reuse ECS-related value types**: the key can be
-the `Entity` type (it is just a branded `number`), and a reference/hierarchy bundle can
-reuse a shared value type like `CoeditingRelations.OrderedChild` (`{ parent, order }`).
-Those are plain serializable data, not ECS behaviour, and reusing them keeps the spec
-and the ECS in lockstep — the same `Entity.schema` that types an id here is what
-conformance walks to compare the two up to an id-bijection (see `conformance.md`).
-Singletons ↔ resources; each `entities` value ↔ one entity whose **component set is the
-value's own keys**, so `fromState` inserts a value into the archetype named by
-`Object.keys(value)` and `toState` reads every entity back into the map. Identity lives
-in the key, never a field — see `../../data-modelling.md` (Entities are keyed, never
-id-bearing values).
+## Files: the pure function and its cases are SEPARATE
 
-### Entity value types — structural, id-less, one `is` guard each
+Each conformed function is two files:
 
-Each entity type is its own `data/<type>/` namespace (`data/index.md`): a plain
-readonly type with **no `id`** plus a structural `is` guard (`is.ts`, re-exported so it
-reads `Todo.is`). A **sub-archetype** is an intersection — `Bar = Foo & { baz }` — and
-its guard **composes the base guard**: `Bar.is` calls `Foo.is(v)` first, then checks the
-added fields (`"baz" in v && typeof v.baz === "boolean"`). So `Bar.is ⟹ Foo.is` by
-construction.
+- **`<name>.ts`** — the pure function, a **single export**, with **zero test-tier
+  imports** (no `@adobe/data-testing`, no fakes). It depends only on `@adobe/data`,
+  other `data/` types, and — for a transition — the service interfaces it injects.
+- **`<name>.cases.ts`** — the spec-owned cases as **inert data**, imported by the
+  manifest. It imports the case type with `import type` and never constructs a live
+  service.
 
-**Model structurally, like the ECS — no tags by default.** ECS systems match purely on
-structure (a mover runs on anything with `position` + `velocity`, regardless of
-"kind"), and `State` mirrors that:
+This split is enforced by the package's project-reference wall (`tsconfig.build.json`
+excludes `*.cases.ts`): a runtime file importing test-tier code is a **compile error**.
 
-- **A property name means one thing feature-wide.** No two entity types may declare the
-  same property name with a different type/semantics — that is what lets every property
-  collapse to exactly one ECS component and keeps structural matching sound.
-- **No marker / `kind` / tag field unless a genuine modelling need demands it.** Prefer
-  discriminating on the presence of real components; add a tag only when structure alone
-  cannot express the distinction.
-
-### Querying entities — `State.getXEntities`, returning ids
-
-Entity queries are `state/` derivations that return entity **ids** (look the value up
-with `state.entities.get(id)`), mirroring the ECS `select`. Perf is irrelevant here
-(full-map scan + guard); the ECS realises them as archetype queries.
-
-- **Unordered** → `ReadonlySet<number>`: keys whose value passes the guard. It is a
-  **superset** match — `getFooEntities` (via `Foo.is`) also includes `Bar` entities,
-  just as `queryArchetypes(["…Foo's cols"])` returns the `Foo` *and* `Bar` archetypes.
-- **Ordered** → `ReadonlyArray<number>`: the matching ids sorted by an explicit `order`
-  component, exactly like an ECS `select(cols, { order })`. Order is **never** carried
-  by the `entities` map (it is identity-keyed / unordered); a meaningful order is a
-  component on the value and the derivation returns the sorted ids.
+### The transform — `<name>.ts`
 
 ```ts
-// data/state/get-todos.ts — an ordered membership derivation returning ids
-export const getTodos = (state: State): readonly number[] =>
-  [...state.entities]
-    .filter(([, v]) => Todo.is(v))
-    .sort(([, a], [, b]) => a.order - b.order)
-    .map(([id]) => id);
-```
-
-**`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:
+// toggle-complete.ts
+import type { Services } from "../../services/services.js";
+import type { State } from "./state.js";
 
-```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 },
-);
+// Reads entities, writes entities — an `{ entities }` patch — and logs `todoToggled`.
+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 }) };
+};
 ```
 
-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.cases(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 separate
-**`@adobe/data-testing`** package (two namespaces, `Match` and `Conformance`) —
-kept out of `@adobe/data` itself so installing `@adobe/data` never pulls in a
-`vitest` peer dependency; add `@adobe/data-testing` as a devDependency alongside
-`vitest`, its optional peer dependency. 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:
+- **Transition signature** `(state: Pick<State, …reads>, args) => Pick<State, …writes>` —
+  a read→write patch. The parameter is the smallest `Pick<State,…>` it reads; the return
+  is only the fields it writes. No `<T> => T` generic, no `...state` spread — return the
+  patch and let the runner merge it. All non-state inputs go in the single `args` object;
+  a transition that takes neither args nor services takes only `(state)`.
+- **Inject services with `Pick<Services, …>`** — never an inline `{ analytics: … }`. Data
+  args sit alongside via intersection: `{ readonly count: number } & Pick<Services, "a">`.
+- **Guard no-ops by returning an empty/unchanged patch**, never by throwing. Reserve
+  `throw` for a genuine precondition violation a case names with `throws`.
+- **Derivation signature** `(state) => value` — a pure selector over **two or more**
+  `State` fields. An entity query returns entity **ids** (`readonly number[]` /
+  `ReadonlySet<number>`); look values up in `entities`. Value math over a **single**
+  `data/<type>` lives on that type's namespace, not here.
+
+### The cases — `<name>.cases.ts`
 
 ```ts
-// data/state/conformance-case.ts — the only per-feature conformance declaration
-import { Conformance as ConformanceApi } from "@adobe/data-testing";
+// toggle-complete.cases.ts
+import { Entity } from "@adobe/data/ecs";
+import type { Conformance } from "@adobe/data-testing";
 import type { State } from "./state.js";
-// `Conformance.cases(fn, [options,] ...cases)` declares a transform's cases — the
-// case types (args, before/after) come from `fn`. A derivation authors `Derivation<typeof fn>`.
-export const Conformance = { cases: ConformanceApi.casesBuilder<State>() };
-export type Derivation<F extends (...args: never[]) => unknown> = ConformanceApi.DerivationCases<F>;
-export type Effects<Args> = ConformanceApi.Effects<Args>;
+import type { toggleComplete } from "./toggle-complete.js";
+
+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 },                                  // DATA only — services are never here
+      after: { entities: new Map([[1, { name: "a", complete: true, order: 0 }]]) },
+      effects: { analytics: [["todoToggled"]] } },      // service calls to assert
+  ],
+};
 ```
 
-```ts
-// create-todo.ts
-import { Conformance } from "./conformance-case.js";           // the thin per-feature alias above
-import type { Services } from "../../services/services.js";    // the feature's service map
-export const createTodo = (
-    state: Pick<State, "entities">,
-    { name, analytics }: { name: string } & Pick<Services, "analytics">,
-): Pick<State, "entities"> => {
-    analytics.todoCreated({ name });
-    // The spec mints the id (the map key) and the order; the value carries neither an id
-    // nor anything the ECS allocates — identity is the key.
-    const id = Math.max(0, ...state.entities.keys()) + 1;
-    const order = state.entities.size;
-    return { entities: new Map(state.entities).set(id, { name, complete: false, order }) };
-};
+- Annotate `Conformance.SpecCases<State, typeof fn>` for a transition,
+  `Conformance.SpecDerivations<typeof fn>` for a derivation. That annotation is the
+  transition/derivation discriminator — nothing is inferred from the signature.
+- **`before` is a delta over `State.create()`**; **`after` is the writes patch** (only
+  the fields the transition changes). A derivation case is `{ name, input, value }`.
+- **`args` is data only.** Injected services are stripped from the case's `args` type;
+  the runner synthesizes each service's recording double from the manifest's `services`
+  templates. A transition with only services takes no `args`.
+- **Service returns are scheduled as data in `responses`**, keyed by service then method;
+  only value-returning methods take a schedule (a per-call FIFO — exhausting it throws).
+  **Service calls to assert go in `effects`** as `[method, ...args]` tuples (`Array` =
+  ordered, `Set` = any order); a value-returning read you don't assert is simply omitted.
+  The case thus **owns both the input and the expectation** — the double invents nothing.
+  ```ts
+  // create-random-todo.cases.ts (a value-returning service)
+  responses: { nameGenerator: { generateName: ["random task"] },
+               analytics: { randomTodoRequested: [{ startedAt: 0 }] } },
+  effects:   { analytics: [["randomTodoRequested"],
+                           ["randomTodoAdded", { timing: { startedAt: 0 }, name: "random task" }]] },
+  ```
+- **Entity ids are plain spec-id numbers everywhere** — map keys in `before`/`after`/
+  `input`, and reference fields hold the id they point at (`{ selectedTodo: 2 }`). The
+  ecs mints its own ids, so conformance compares up to an id-bijection. An
+  entity-addressed transition adds the `args` schema (above) marking each `Entity.schema`
+  field; the case then writes the id plain (`args: { id: 2 }`). For a minted scalar a
+  case won't pin (a timestamp), use `Match.anyNumber` / `Match.anyString`.
+- **A `throws` case** declares `throws: true` (any error) or `throws: "substring"`
+  instead of `after`/`effects`/`responses` — the two are mutually exclusive.
+
+## `transforms.ts` — the conformed-function barrel
 
-export const cases = /*@__PURE__*/ Conformance.cases(createTodo,
-    { name: "adds the first todo",
-      before: {},                       // empty delta — the default State.create() (empty entities)
-      args: { name: "a", analytics: AnalyticsService.createFake() },
-      // The map key is a PLAIN spec-id you choose (1). The ECS mints its own id, so
-      // conformance compares up to an id-bijection — the key need only be distinct.
-      // The value is id-less so content compares directly. (Maps compare entry-wise /
-      // order-independently — see conformance.md.)
-      after: { entities: new Map([[1, { name: "a", complete: false, order: 0 }]]) },
-      effects: { analytics: [["todoCreated", { name: "a" }]] } },
-);
+```ts
+// transforms.ts — exactly the conformed transforms and derivations, nothing else
+export { createTodo } from "./create-todo.js";
+export { toggleComplete } from "./toggle-complete.js";
+export { visibleTodos } from "./visible-todos.js";
+// …
 ```
 
-- **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**
-  (the case's `args` type is read from `fn`'s `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 for an ordinary "nothing to do here"
-  condition. Reserve `throw` for a genuine precondition violation the case wants
-  to name (see "A case that expects a throw" below) — the rare exception, not the
-  default guard style.
-- **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.
-- **Always write the call as `/*@__PURE__*/ Conformance.cases(fn, …)`** (same for
-  `Conformance.derivations`) — the annotation is not optional style, it is what
-  makes the co-location safe. `@adobe/data-testing`'s `sideEffects: false` only
-  lets a bundler drop an unused *import* of the package; `Conformance.cases(fn,
-  …)` is still an ordinary function call happening in *this* file, and an
-  unannotated call is conservatively kept even when the `cases` export it
-  initializes is never read — because the transition function `fn` is legitimately
-  used elsewhere, this module is very much reachable, so the unused `cases` const
-  is the only thing tree-shaking has to remove, and it can't without the hint.
-  Verified against this repo's actual Vite/Rollup production build: a transition
-  whose `cases` call lacked the annotation shipped the full case-fixture data
-  (and the builder's inlined logic) into the bundle; adding `/*@__PURE__*/`
-  removed it completely while leaving the transition function itself intact. A
-  linter/codemod catching a bare `Conformance.cases(`/`Conformance.derivations(`
-  call (missing the leading comment) in a `data/state/*.ts` file would catch this
-  by construction — worth adding if these calls keep getting hand-authored.
-- **`Conformance.cases(fn, ...cases)`** (the builder above) derives each case's
-  types from `fn`'s own signature — pass the transition function and cases can't drift
-  from what it 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` uses PLAIN spec-ids everywhere — no hand-authored key matchers.** An
-  entity's identity is the `entities` map **key**, not a value field, so entity content
-  compares directly. The ECS mints its **own** ids (a different set from the spec's), so
-  conformance compares the two **up to an id-bijection**: the runner reads the store's
-  schemas, finds every entity reference (a map key, and any field whose schema is
-  `Entity.schema` — recursing into a bundle like `{ parent, order }`), and matches the
-  case's spec-ids to the ECS's ids one-to-one. So a case author writes ordinary numbers
-  — `[[1, value], [2, value]]` — and **a reference field just holds the id it points at**
-  (`{ asset: 2 }`, `placement: { parent: 1, … }`). The bijection makes a key and every
-  field that names it line up on one actual id automatically — this is what killed the
-  old `Match.ref` / `Match.refMap` key-labelling (no more distinct-label bookkeeping,
-  and cross-references between entities finally compare correctly). For a **minted scalar**
-  a case does not want to pin — a generated timestamp, a random value — still use
-  `Match.anyNumber` / `Match.anyString` (imported from `@adobe/data-testing`); `Match` is
-  framework-agnostic, so vitest's `expect.stringContaining(...)` interops on the expected
-  side too. (The id-correspondence solver is now internal — the runner generates it from
-  the schema-marked spec-ids; there is no case-facing `ref`/`refMap` matcher anymore.)
-- **Entity-addressed cases pass an `args` schema in the builder options.** State
-  references are detected from the store's schemas; an **arg** has none, so a transition
-  that addresses an entity by id gives `Conformance.cases` a leading options object whose
-  `args` schema marks the reference fields:
-  `Conformance.cases(fn, { args: { type: "object", properties: { id: Entity.schema } } }, …cases)`.
-  The case then writes the id **plain** — `args: { id: 2 }` — and the runner resolves each
-  `Entity.schema`-marked field to the seeded entity (via the `fromState` seed map) on the
-  ECS side, while the pure side reads the plain spec-id directly. Describe **only** the
-  reference fields (services and non-id args are omitted); the args type must be assignable
-  to the schema's `Schema.ToType`, so the schema can't drift from the signature (the builder
-  fails to type-check otherwise). This is the args-side analog of the `Entity.schema` mark
-  the runner reads on state.
-- **The `entities` map key convention across a case, in one place:**
-  - **`before`** (the seed): **plain spec-id numbers** (`new Map([[1, …], [2, …]])`).
-    `fromState` seeds from these and returns the `spec-id → entity` map, so a case's
-    `args: { id: 1 }` resolves to the entity seeded for `1`.
-  - **`after`** (the expectation, compared against the ECS): **plain spec-id numbers**,
-    distinct per entry, and reference fields hold the spec-id they point at. The runner
-    refifies them and compares up to an id-bijection, so the ECS's own ids need not match.
-    You may reuse the same spec-ids as `before` for entities that persist (it reads
-    clearly), but any distinct numbers work — the comparison is by content + reference
-    structure, never by the literal id.
-  - **`samples`** (round-tripped `toState ∘ fromState`): same as `after` — plain spec-id
-    keys, compared up to a bijection against the ECS-minted ids.
-- 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` (see
-  `conformance.md`); unordered collections are modeled as `ReadonlySet` /
-  `ReadonlyMap` on `State` (below), not declared as a match option.
-  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.
+Its keys are the conformance surface. A genuine **non-transition helper** (`appendTodo`,
+`create`, `samples`) is *not* listed here and carries no cases; it keeps its own
+`*.test.ts`.
 
-### A case that expects a throw
+## `spec.ts` — the conformance manifest
 
-A case is normally `{ name, before, args?, after, effects? }`. When a transition
-must reject its input outright — not the "guard no-op, return `{}`" case above,
-but a genuine precondition violation the spec wants to name — declare `throws`
-instead of `after`/`effects`:
+The single object both `spec.test.ts` and the ecs `conformance.test.ts` import. It is a
+**test-tier** file (excluded from the runtime build) — the one place the feature touches
+`@adobe/data-testing`.
 
 ```ts
-export const cases = Conformance.cases(withdrawFunds,
-    { name: "rejects a withdrawal over the balance",
-      before: { balance: 10 },
-      args: { amount: 11 },
-      throws: "insufficient funds" },   // substring the thrown Error.message must contain
-);
+// spec.ts
+import { Conformance } from "@adobe/data-testing";
+import { State } from "./state.js";
+import * as transforms from "./transforms.js";
+import { MainService } from "../../services/main-service/main-service.js";
+import { ComputedDatabase } from "../../services/main-service/computed-database/computed-database.js";
+import { projection } from "../../services/main-service/conformance/projection.js";
+import { createFake as analytics } from "../../services/analytics-service/analytics.fake.js";
+import { cases as createTodo } from "./create-todo.cases.js";
+import { cases as toggleComplete } from "./toggle-complete.cases.js";
+import { cases as visibleTodos } from "./visible-todos.cases.js";
+// …one import per conformed fn
+
+export const spec = Conformance.feature({
+  state: State,
+  fns: transforms,
+  plugin: MainService.plugin,
+  computedPlugin: ComputedDatabase.plugin,   // required iff the feature has a derivation
+  projection,
+  hydrate: ["visibleTodos"],                 // EXACTLY the entity-id-list derivations
+  services: { analytics, nameGenerator },    // required iff a transition injects a service
+  cases: { createTodo, toggleComplete, visibleTodos, /* …one per fn */ },
+});
 ```
 
-`throws: true` accepts any thrown error; a string narrows to one whose message
-**contains** it. A case can declare `after`/`effects` **or** `throws`, never
-both — the shared `Case` type makes them mutually exclusive, and there is
-nothing to compare against `after` once a call never returns a patch. The same
-case runs against the pure transform (`runSpec`) **and** the paired ecs
-transaction/action (`runFeature`/`runTransactions`/`runActions`), so a `throws`
-case proves both sides reject the same input the same way. Reach for this only
-when throwing is the transition's actual contract — most invalid input should
-still no-op per the rule above.
-
-## Injected services and side effects
-
-A transform that needs an outside capability injects it with **`Pick<Services,
-…>`** — never an ad-hoc inline type. `Services` is the feature's service map
-(`services/services.ts`, see `../services/index.md`), keyed by the service name
-minus its `-service` suffix (`analytics`, `nameGenerator`), so the key and its type
-come from **one** place and can't drift per-transition. Plain data args sit
-alongside via intersection: `{ readonly count: number } & Pick<Services, "analytics">`
-(or `Pick<Services, "a" | "b">` when a transition takes only services). The **same
-services appear on `db.services` for the matching action** — pinned to `Services` in
-the ecs `service-database` — so the transition is the complete spec of *both* the
-state change and the service calls.
+`Conformance.feature` enforces four guards at **compile time**:
+- **`cases` coverage** — exactly one case module per `fns` entry (missing or extra → error).
+- **`hydrate` exactness** — exactly the derivations that return a collection of the
+  projection's entity value (its ecs computed emits ids); miss one or add a non-hydrating
+  name → error.
+- **`services` completeness** — exactly the injected-service keys the transitions declare,
+  each a `() => Service` template; absent for a service-free feature.
+- **`computedPlugin` presence** — required when any case module is a derivation.
 
-- 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`).
+## `spec.test.ts` — the pure spec
 
-## Derivations — `(state) => value`, cases `{ input, value }`
-
-Pure selectors that **compose the aggregate** — a value drawn from **two or more
-`State` fields** (`visibleTodos` from `entities` + `displayCompleted`;
-`currentPlayer` from `board` + `firstPlayer`). An entity query like `visibleTodos`
-returns entity **ids** (`ReadonlyArray<number>` / `ReadonlySet<number>`), never the
-values (look those up in `entities`). 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.
+```ts
+// spec.test.ts
+import { Conformance } from "@adobe/data-testing";
+import { spec } from "./spec.js";
+Conformance.checkSpec(spec);
+```
 
-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.
+One call verifies every transform and derivation against its cases (seeding `before`
+over `State.create()`, synthesizing service doubles from `services` + `responses`,
+asserting `after`/`value`/`effects`/`throws`). The ecs side is one matching call in
+`conformance.test.ts` (`../services/main-service/conformance.md`).

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

@@ -32,8 +32,9 @@ 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,
-  transitions, co-located `cases`, `spec.test.ts`), `services/main-service/conformance/`,
-  and the `state` projection computed. **This is how every new feature is authored.**
+  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
@@ -129,16 +130,17 @@ 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 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.
+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.
 
 ## Reference implementations
 

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

@@ -61,24 +61,33 @@ 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.
+## 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
 

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

@@ -20,7 +20,7 @@ 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
+action surface of `checkFeature`. 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).
 
@@ -53,18 +53,18 @@ export const addRandomTodo = async (service: ServiceDatabase) => {
   `services`, and assert the committed state and the recorded service calls. The
   bullet below applies only to **state-based** features (see `../../index.md`, Two modes).
 - **Conformance** is the action surface of the feature's single
-  `conformance/conformance.test.ts` `Conformance.runFeature({...})` call. It pulls
+  `conformance/conformance.test.ts` `Conformance.checkFeature(spec)` 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
+  `db.services`, so the runner synthesizes each recording double from the manifest's
+  `services` templates + the case's `responses` and builds
+  `Database.toSystemDatabase(Database.create(plugin, { services }))`; it runs the action
+  with the case's data `args`, then `Match.assert`s `toState ≡ after` **and** checks the
+  recorded calls against the case's `effects`. No per-op wiring, 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 —
+  plugin's type) is supplied via the manifest'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`).
+  (p2p negotiation). That is the *only* reason to set `ops` (see `conformance.md`).
 - An `index.ts` barrel feeds the `actions` plugin facet.

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

@@ -23,13 +23,11 @@ not a hot per-entity or large-N path. Reusing a tested derivation is good — th
 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.
+reads instead). A derivation takes **no services**, so its sibling `*.cases.ts` is
+inert `{ input, value }` data (no test-doubles); like every `*.cases.ts` it is
+test-tier and excluded from the runtime build by the project-reference wall, so it
+never reaches the app bundle. **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";
@@ -53,10 +51,11 @@ only when the count changes, allocating no entity array. Prefer it over
 `db.observe.select(...)` mapped through `.length`.
 
 **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
+derivation's sibling `*.cases.ts` holds `{ input, value }` cases
+(`Conformance.SpecDerivations<typeof fn>`), and the feature's single
+`conformance/conformance.test.ts` `Conformance.checkFeature(spec)` 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

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

@@ -5,240 +5,91 @@ paths:
 
 # services/main-service/conformance/ — keeping the ECS honest against the spec
 
-**State-based features only.** This folder exists only when the feature has a
-`data/state/` spec to conform to. An **ECS-based** feature (no `data/state/`) omits
-this folder entirely and unit-tests its transactions/actions directly instead (see
-`../../index.md`, Two modes, and `transactions.md` / `actions.md`).
-
-Test-only (imported only by `*.test.ts`, in no facet barrel). The `data/state`
-cases are the shared truth; the shared **`@adobe/data-testing`** runner replays
-them against the ECS. This folder holds only the *feature-specific projection*
-(`projection.ts`) plus one `conformance.test.ts` that makes a **single**
-`Conformance.runFeature({...})` call. Reference: `data-lit-tictactoe`'s
-`conformance/` (the zero-config example) and `data-lit-todo` (entity markers +
-`hydrate`); `data-lit-space-rock-game` for the entity-bag / real-time variant.
-
-**The projection helpers (`fromState`, `toState`, `toData(store, entity)`) and
-`Match.matches` / `Match.assert` are test-only — never a production/runtime branch.**
+**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. (The conformance
-`toData(store, entity)` reader is unrelated to the library's runtime `db.toData()`
-store-serialization method — same name only.)
-
-## What `@adobe/data-testing` gives you
-
-Two namespaces, imported only from `*.test.ts` (the module is
-`sideEffects: false`; add it as a devDependency alongside `vitest`, its
-optional peer dependency — kept as a separate package from `@adobe/data` so
-installing `@adobe/data` never pulls in a `vitest` peer dependency):
-
-- **`Match`** — the tolerant, matcher-aware value comparison: `matches(actual,
-  expected, options?)` and its throwing wrapper `assert(...)`, plus the matchers
-  `Match.anyNumber` / `Match.anyString` for minted scalars a case does not pin.
-  **Entity ids need no matcher**: a case writes plain spec-ids for map keys and
-  reference fields, and the runner compares up to an id-bijection (below), so `samples`
-  and `after` are ordinary `new Map([[1, value], …])` — no key labelling. Options are
-  `{ tolerance?: number }` — numbers snap to `tolerance` (default `0.01`) to absorb
-  F32↔f64 / trig noise. **Ordering is carried by the value's type**: a
-  `ReadonlyArray` compares **in order**, a `ReadonlySet` / `ReadonlyMap`
-  **order-independently** — there is no `unordered` option. Entity identity is the
-  key of `State.entities` (a `ReadonlyMap<number, …>`), resolved to the allocated ECS
-  entity via `resolver` (below); entity *values* carry no `id`, so there is no id to
-  ignore when comparing content. Framework-agnostic: it honors any asymmetric matcher,
-  so vitest's `expect.any(...)` interops.
-- **`Conformance`** — the case types (`Case`, `Cases`, `DerivationCase`,
-  `DerivationCases`, `Effects`, `ServiceCall`), the `casesBuilder` (a feature's
-  `Conformance.cases`), `assertState` for custom harnesses, the whole-feature driver **`runFeature`**, the
-  pure-spec driver **`runSpec`**, and the lower-level per-surface drivers
-  `runTransactions` / `runActions` / `runComputeds` (internals of `runFeature`,
-  exported for the escape hatch below). Auto-pairing (transition ⇄ op by name),
-  effect recording, and id resolution are built **into** the drivers — no
-  per-feature helper writes them. The `Effects` type-test also lives here (once),
-  so there is no per-feature `conformance-case.type-test.ts` to author.
-
-## Projection (store ⇄ State) — the one per-feature piece
-
-`projection.ts` is the only feature-specific file, and it is a **single
-aggregated export** — the three test-only helpers in one file, one `export`:
+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
-// conformance/projection.ts
 export const projection = { fromState, toState, toData };
 ```
 
-- `fromState(store, state)` seeds a store to a `State` (clear tail→head, insert
-  entities, set resources). It **returns the `id → entity` map**
-  (`ReadonlyMap<Id, Entity>`) it built while seeding — the ECS assigns ids from
-  its own id-space, so the runner turns this map into a `resolve` via
-  `Conformance.resolver`; **no feature writes id resolution by hand**. A feature
-  whose transactions are index-addressed or singleton returns `void`, and any id
-  then resolves to `Entity.none`.
+- `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; the runner reuses it to hydrate id-list
-  computed outputs. **Present only when the feature has entities** (omit for a
-  scalar / resource-only feature).
-
-This replaces the old separate `create-store.ts` / `from-state.ts` /
-`to-state.ts` / `to-data.ts`. **`create-store` is gone** — `runFeature` builds
-every store/db itself with `Store.create(plugin)` / `Database.create(plugin)`.
-
-## ECS conformance is ONE call — `Conformance.runFeature`
+- `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/conformance.test.ts` is a single call that conforms the whole
-feature — transaction + action + computed conformance **plus** the projection
-round-trip. No per-surface test file, no `define` callback, no `conforms(...)`
-adapters, no coverage guard.
+## `conformance.test.ts` — one call
 
 ```ts
-import { State } from "../../../data/state/state.js";
-import { transitions } from "../../../data/state/transitions.js";
-
-Conformance.runFeature({
-  state: State,
-  transitions,
-  plugin: MainService.plugin,
-  computedPlugin: ComputedDatabase.plugin,   // omit if no state/ derivations
-  projection,
-  hydrate: ["visibleTodos"],                 // entity-id-list computeds; omit if none
-  match: { tolerance: 0.1 },                  // float grid only; omit if 0.01 is fine
-  ops: { actions: import.meta.glob([...]) }, // ONLY when ops aren't in the plugin facet
-});
+import { Conformance } from "@adobe/data-testing";
+import { spec } from "../../../data/state/spec.js";
+Conformance.checkFeature(spec);
 ```
 
-- **`state`** is the `State` namespace itself — the runner calls `State.create()`
-  for the default each case's `before` deltas over, and round-trips `State.samples`
-  through the projection.
-- **`transitions`** is imported from the feature's test-only
-  `data/state/transitions.ts` (the single `import.meta.glob` of the `{ fn, cases }`
-  source, shared with `spec.test.ts` — see `data/state.md`). Never re-glob it here.
-- **Ops come off the plugin facets.** The runner reads
-  `plugin.transactions` / `plugin.actions` / `computedPlugin.computed` and builds
-  the stores/dbs itself (`Store.create(plugin)` for transactions,
-  `Database.create(plugin)` for actions, `Database.create(computedPlugin)` for
-  computeds). Each op pairs to its **same-named** transition/derivation; auto-pairing
-  can't forget an item, so there is **no coverage guard** — an op with **no
-  same-named transition** is infrastructure or system-dispatched and is simply
-  **skipped** (a streaming action with no transition is skipped too).
-- **`ops`** overrides the facet-discovered ops per surface — use it **only** when
-  an op isn't registered in the plugin facet: a per-transition action kept out of
-  the facet (to bound the plugin's type) is discovered via an
-  `ops.actions: import.meta.glob([".../actions/*.ts", "!.../actions/index.ts"], { eager: true })`
-  glob (p2p negotiation). Ordinary features omit `ops` entirely.
-- **`computedPlugin`** is the `ComputedDatabase` **layer** plugin — build computed
-  conformance from this layer, **not** the assembled `MainService`: a behaviour
-  layer above may `withCache` a pre-seed value that a direct `fromState` seed emits
-  no transaction to invalidate; the computed layer keeps the seed authoritative.
-  Omit it when the feature has no `state/` derivations (a computed with no
-  derivation is skipped anyway, and single-`data/<type>` math is covered by that
-  helper's own test).
-- **`hydrate`** names the computeds that emit an **entity-id list** (todo's
-  `visibleTodos`) so the runner maps each id through `toData` into the value shape
-  the derivation yields. Comparison is identity otherwise. Omit if none.
-- **`match`** threads `MatchOptions` through every comparison (see below). Omit if
-  none.
-- **Projection round-trip.** When `State.samples` is non-empty, the runner adds a
-  `toState ∘ fromState ≡ identity` test per sample — proving the pair round-trips
-  faithfully so a symmetric bug in `fromState`/`toState` can't cancel out and mask
-  a real ECS defect. No separate `projection.test.ts`.
-
-`data-lit-tictactoe` is the zero-config call (no `computedPlugin`, no `hydrate`,
-no `match`, no `ops` — moves are board-index addressed, so no `entity()`
-markers). `data-lit-todo` adds `hydrate: ["visibleTodos"]` and `entity()` markers.
-`data-lit-space-rock-game` holds its `bullet` / `asteroid` entities in the single
-`entities: ReadonlyMap<number, Bullet | Asteroid>`, keyed by id, so they compare
-order-independently by the map — no `match` option (its per-frame transitions are
-conformed by the systems tick loop, not here — see `systems.md`).
-
-## The pure spec — `data/state/spec.test.ts`
-
-Lives in `data/state/`, not here. One call, importing the same `transitions`:
+`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 { State } from "./state.js";
-import { transitions } from "./transitions.js";
-
-Conformance.runSpec({ state: State, transitions });
+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),
+});
 ```
 
-It discovers every file exporting `cases`, enforces the two-exports rule, and
-dispatches on case shape (transition → state + effects, derivation →
-`fn(input) ≡ value`), seeding each case's `before`/`input` as a delta over
-`State.create()`. On the ECS side it resolves the reference args a case's `args`
-schema marks; the pure side reads them plain. A transition case may declare
-`throws` instead of `after`/`effects` to assert the call rejects its input —
-see `../../data/state.md` ("A case that expects a throw"). `runSpec`,
-`runTransactions`, and `runActions` all honor it identically, so the same case
-proves the pure transform and its paired ecs op fail the same way.
-
-## The exception — a per-surface `userId`, via the lower-level runners
-
-A feature that needs **ambient per-case context differing per surface** — a
-user-scoped `userId` that must be seeded before the raw transaction *and*
-independently before the action dispatch (**p2p presence**) — does **not** use
-`runFeature`. It calls `Conformance.runTransactions` / `runActions` (still
-exported) directly, each with its own `seedContext` (and any per-surface
-concurrency), because the seam differs between the transaction store and the
-action db. `runFeature` has no place to thread two different `seedContext`s, so
-this feature drops to the lower level. This is the escape hatch — ordinary
-features never touch these drivers directly.
-
-## Identity — the `args` schema
-
-An entity-addressed transition declares an `args` schema in the builder options and
-writes the id **plain**: `Conformance.cases(fn, { args: { type: "object", properties:
-{ id: Entity.schema } } }, { …, args: { id: 2 }, … })`. The runner
-finds each `Entity.schema`-marked arg field and resolves the plain spec-id to the
-**seeded entity** via the id→entity map `fromState` returns (turned into a `resolve`
-by `Conformance.resolver` — no feature writes `resolve` by hand); the pure side reads
-the spec-id as-is. Two conventions make the wiring vanish: the ECS op takes the entity
-**under the transition's own arg key** (`{ id }`, same-shape args, no reshape), and
-`fromState` returns the `ReadonlyMap<Id, Entity>` id→entity map (or `void` for an
-index-addressed / singleton feature, whose ids then resolve to `Entity.none`).
-`data-lit-todo` is the reference. Describe only the reference fields — services and
-non-id args are omitted, and the args type must be assignable to the schema's
-`Schema.ToType` so it cannot drift from the signature.
-
-## Name-parity — add a same-named op, never a per-item adapter
-
-Every app transition is realized by a **same-named** transaction and/or action. When
-the real UI op is richer or renamed — todo's `dragTodo`, space-rock's `newGame` — that
-op is infra, and a thin **same-named** op (todo's `reorderTodo` action, space-rock's
-`createInitial` transaction) gives the transition something to pair with. Do **not**
-reintroduce a per-item adapter to bridge a name mismatch — add the same-named op.
-
-## Ordering, tolerance, the id-bijection
-
-Ordering is carried by the value's **type**, not a match option — `ReadonlyArray`
-positional, `ReadonlySet` / `ReadonlyMap` order-independent (the rule and its
-rationale live in `../../../data-modelling.md`). What's specific to writing
-conformance cases:
-
-- **The spec and the ECS mint different id sets, so comparison is up to an
-  id-bijection — automatically.** The runner reads the store's `componentSchemas`
-  (which also carry the resource schemas) and finds every entity reference: an
-  `entities` map **key** (an id by construction) and any field whose schema is
-  `Entity.schema` (`schema.entity === true`), recursing into bundled object schemas so
-  a `placement: { parent, order }` reference is found. It replaces each spec-id there
-  with a correspondence variable and solves a one-to-one matching against the ECS's
-  ids. So a case **writes plain spec-ids** for keys and reference fields, and a key and
-  every field naming it line up on one actual id with no author bookkeeping — this is
-  what retired `Match.ref` / `Match.refMap` for keys, and it is what makes a
-  cross-reference between entities (an `asset`, a `parent`) compare correctly at all.
-- **Entity values carry no `id`** — identity is the key — so entity content compares
-  directly, with nothing to omit.
-- **Float noise** is absorbed by the default `tolerance` (`0.01`), threaded through
-  `match?: { tolerance }`; raise it only when a case needs a looser grid.
-- **A minted scalar** a case does not pin — a timestamp, a random draw — uses
-  `Match.anyNumber` / `Match.anyString`. Entity-id correspondence needs no matcher: the
-  runner derives it from the schema-marked spec-ids (the solver is internal).
-
-## Recording side effects — built in, no Proxy
-
-Effect recording lives in the drivers: they enumerate a plain-object service's own
-methods and closure-wrap each to record `[method, ...args]` calls, then delegate
-(no `Proxy`, per the repo rule). `runSpec` records the case's injected service
-`args`; the action surface records the `db.services` overrides. A case's `effects`
-asserts each **declared** service's calls exactly (`Array` = ordered, `Set` = any
-order); undeclared services (value-returning reads like `generateName`) are
-ignored.
+`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/transactions.md

@@ -38,7 +38,7 @@ export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
   direct substitute for the conformance oracle (see `../../index.md`, Two modes). The
   bullet below applies only to **state-based** features.
 - **Conformance is wired once, centrally, and auto-paired** — not per-file. The
-  feature's single `conformance/conformance.test.ts` `Conformance.runFeature({...})`
+  feature's single `conformance/conformance.test.ts` `Conformance.checkFeature(spec)`
   call conforms transactions: it pulls them off **`plugin.transactions`** (the
   registered facet), pairs each to the **same-named** `data/state` transition, and
   conforms it — seed `fromState(before)`, apply, `Match.assert` `toState ≡ after`

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adobe-data-ai",
-  "version": "0.10.19",
+  "version": "0.10.20",
   "description": "Architecture skills for @adobe/data — data-oriented modelling, archetype iteration, hot-path performance, and related conventions.",
   "author": {
     "name": "Adobe"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.10.19",
+  "version": "0.10.20",
   "description": "Cross-agent architecture skills for @adobe/data — installable as a Claude Code plugin or copied into any Agent-Skills-compatible agent (Cursor, Codex).",
   "type": "module",
   "private": false,
@@ -29,12 +29,12 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.10.19"
+    "@adobe/data": "0.10.20"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.10.19"
+    "@adobe/data": "0.10.20"
   },
   "license": "MIT",
   "scripts": {