@adobe/data-ai 0.10.20 → 0.10.22

package/skills/build-ui/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: build-ui
-description: Build a feature's ui/ layer — presentation bound to the main-service database. The final, top layer.
+description: Build a feature's ui/ layer.
 input: feature
 output: feature
 ---
 
 Create `ui/`: one folder per UI unit —
 `<name>/{<name>.ts (lazy wrapper), <name>-element.ts (container), <name>-presentation.ts (pure render), <name>.css.ts}`.
-The element subscribes to state and delegates to the pure presentation; no business logic here.
+The element subscribes to `MainService` state and calls `service.actions.*`; the
+presentation imports only `data/` and sibling `ui/` lazy wrappers. No business logic here.
 
-Comes last. The how is in the auto-loading `features/ui/index.md` rule (and `element.md`,
-`lazy-element.md`, `presentation.md`).
+Comes last. Gate: presentation tests. The how is in the auto-loading
+`features/ui/index.md` rule (and `element.md`, `lazy-element.md`, `presentation.md`).

package/skills/review/SKILL.md

@@ -11,9 +11,9 @@ rules (each layer's rule and the cross-cutting rules — `namespace`, `data-mode
 `type-casts`, `cohesion`, …):
 
 - **Correctness** — does it typecheck and follow the layer's required shape?
-- **Adherence** — single public export per file, naming, the scope helpers
-  (`Database.components` / `resources` / `archetypes`), `satisfies` targets, barrels,
-  store-layer typing, etc.
+- **Adherence** — single public export per file, naming, per-file scope flags
+  (`Scope`), `satisfies` targets, barrels, the layer dependency order (no runtime
+  import of `spec/`), store-layer typing, etc.
 - **Generality** — no leaked type identities; follows the cross-cutting patterns.
 
 Report either **OPTIMAL**, or a short list of issues. Tag each issue with where the

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

@@ -1,209 +0,0 @@
----
-paths:
-  - '**/features/*/data/state/**/*.ts'
----
-
-# data/state/ — the State specification
-
-`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. 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**. A feature without
-`data/state/` is **ECS-based** (no spec, no conformance) — see `../index.md`.
-
-## The `State` shape
-
-```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";
-```
-
-- **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).
-
-`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`).
-
-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`).
-
-## Files: the pure function and its cases are SEPARATE
-
-Each conformed function is two files:
-
-- **`<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.
-
-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**.
-
-### The transform — `<name>.ts`
-
-```ts
-// toggle-complete.ts
-import type { Services } from "../../services/services.js";
-import type { State } from "./state.js";
-
-// 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 }) };
-};
-```
-
-- **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
-// toggle-complete.cases.ts
-import { Entity } from "@adobe/data/ecs";
-import type { Conformance } from "@adobe/data-testing";
-import type { State } from "./state.js";
-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
-  ],
-};
-```
-
-- 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
-
-```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";
-// …
-```
-
-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`.
-
-## `spec.ts` — the conformance manifest
-
-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
-// 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 */ },
-});
-```
-
-`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.
-
-## `spec.test.ts` — the pure spec
-
-```ts
-// spec.test.ts
-import { Conformance } from "@adobe/data-testing";
-import { spec } from "./spec.js";
-Conformance.checkSpec(spec);
-```
-
-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/services/main-service/actions.md

@@ -1,70 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/action-database/actions/**/*.ts'
----
-
-# services/main-service/actions/ — async orchestration
-
-One action per file: a function taking the **whole database** as its first
-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 `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).
-
-```ts
-import type { ServiceDatabase } from "../../service-database/service-database.js";
-
-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 `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. `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.
-- **ECS-based feature (no `data/state/`):** no conformance cases exist, so **every
-  action carries its own unit test** — build a db, run the action with fake
-  `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.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 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 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 set `ops` (see `conformance.md`).
-- An `index.ts` barrel feeds the `actions` plugin facet.

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

@@ -1,49 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/**/core-database/archetypes.ts'
----
-
-# core-database/archetypes.ts — the feature's archetypes
-
-One file, one export: `archetypes`, built with `Database.archetypes(components, …)`,
-which validates every key against the component map and preserves each archetype's
-literal tuple (so no per-archetype `as const satisfies`). The archetype **model** —
-query/superset semantics, base archetypes for logical supertypes, row iteration — is
-the rules-root `archetypes.md`; this file is the declaration convention.
-
-```ts
-import { Database } from "@adobe/data/ecs";
-import { components } from "./components.js";
-
-export const archetypes = Database.archetypes(components, {
-  Todo: ["todo", "name", "complete", "order", "dragPosition", "assignees"],
-});
-```
-
-- `UpperCase` names — an archetype names a *shape*, like a class.
-- Archetypes may **span scopes**: a document entity can include an ephemeral
-  `session` column — `components` merges every scope, so any-scope key validates.
-
-## satisfies CoreDatabase.Archetype
-
-Type-check a shared base tuple against `CoreDatabase.Archetype` (= `readonly Component[]`;
-see `core-database.md`) — the same type checks every `count` / `select` query key downstream:
-
-```ts
-const layer = ["placement", "name", "visible", "opacity"] as const satisfies CoreDatabase.Archetype;
-```
-
-## Drift guard against the data-type
-
-An archetype that mirrors a `data/` row type carries a **non-exported** compile-time
-check — infer the row shape from the archetype and assert it equals the data-type, so
-the two can't drift:
-
-```ts
-import { Schema } from "@adobe/data/schema";
-import type { Assert, Equal } from "@adobe/data/types";
-import type { PlacedMark } from "../../data/placed-mark/placed-mark.js";
-
-const _schema = Schema.fromArchetype(components, archetypes.PlacedMark);
-type _Check = Assert<Equal<Schema.ToType<typeof _schema>, PlacedMark>>;
-```

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

@@ -1,41 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/**/core-database/components.ts'
----
-
-# core-database/components.ts — the feature's components
-
-One file, one export: `components`, built with `Database.components(...)`. A
-component binds a `data/` type into ECS column storage, grouped by schema scope.
-The scope groups are optional — declare only the ones you use.
-
-Bind each schema straight from its `data/` type (or a primitive schema); don't
-author shapes here. Component entries are any `Schema` — no `default` required
-(that's resources):
-
-```ts
-import { Database } from "@adobe/data/ecs";
-import { Boolean, True } from "@adobe/data/schema";
-import { PlayerMark } from "../../data/player-mark/player-mark.js";
-import { DragPosition } from "../../data/drag-position/drag-position.js";
-
-export const components = Database.components({
-  document: { mark: PlayerMark.schema, complete: Boolean.schema },
-  session:  { dragPosition: DragPosition.schema },
-});
-```
-
-- A component name may differ from the type it stores (`position` of a `Vec3`,
-  `mark` of a `PlayerMark`) — the field name describes the role, the schema the
-  shape.
-- **Scope = which group it sits in** (see `services/main-service/index.md` for the four scopes and
-  their flags). `document` is the common case; hover a scope key for its
-  meaning. Never write `nonShared` / `nonPersistent` by hand — the group applies
-  them.
-- **Shared cross-feature columns live in `data/`** and go in `document` (which
-  preserves schema identity) so `combinePlugins` dedupes them.
-- Struct vs. object storage and schema selection are properties of the `data/`
-  type, decided there.
-- Don't infer entity type based upon component membership.
-  Consider using a const: true "tag" component or a type/kind enumerated value if needed.
-  Note that *many* good ecs designs don't care the type of the entity and only act on components.

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

@@ -1,82 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/computed-database/computed/**/*.ts'
----
-
-# database/computed/ — derived observable values
-
-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 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 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";
-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((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.
-
-For a computed that only needs *how many* entities match an archetype (an
-empty-state flag, a badge count), read `db.observe.count(archetype.components,
-{ where })` — an `Observe<number>` that sums archetype row counts and re-emits
-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'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
-`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.

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

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

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

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