@adobe/data-ai 0.10.22 → 0.10.24

package/.claude/rules/README.md

@@ -26,6 +26,11 @@ features/
     core.md  indexes.md  transactions.md  computed.md  services.md  actions.md
     systems.md  conformance.md
   ui/                 # element / presentation / lazy-wrapper rules
+  data/state.md       # LEGACY state-based layout (existing features only)
+  services/main-service/
+    index.md  core-database.md  components.md  resources.md  archetypes.md
+    indexes.md  transactions.md  computed.md  services.md  actions.md
+    systems.md  conformance.md
 app.md                # src/app/: the composition root
 ```
 
@@ -34,9 +39,9 @@ etc.) apply everywhere, by design. Alongside `features/`, the remaining rules-ro
 `.md` files hold **cross-cutting** patterns the feature rules reference —
 `app.md`, `data-modelling.md`, `archetypes.md` (the query and iteration model),
 `plugin-modelling.md`, `versioning.md`, and the UI rules `element.md` and
-`lazy-element.md` (`features/ui/` holds `presentation.md` and the binding-element and
-lazy-wrapper rules). They live here so the bundle is
-self-contained; this repo symlinks them into its own `.claude/rules/`.
+`lazy-element.md` (`features/ui/` holds `presentation.md` and the lazy-wrapper rule).
+They live here so the bundle is self-contained; this repo symlinks them into its own
+`.claude/rules/`.
 
 Each feature rule's `paths:` glob is scoped to `**/features/*/<layer>/…`, so these
 rules apply once an application organizes its source under `features/<name>/`.

package/.claude/rules/ecs.md

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

package/.claude/rules/element.md

@@ -106,6 +106,15 @@ Actions are fire-and-forget. If a caller needs a result, that's a
 transaction the binding invokes directly, *or* a new observable to
 subscribe to — never a return value awaited in render.
 
+## Presentation contract
+
+- The element imports its sibling `*-presentation.ts`, which exports exactly `render`
+  (consumers derive props with `Parameters<typeof render>[0]`).
+- Callback props are named as a verb or verbNoun (`toggleComplete`), never `on*`; the
+  element's variable matches the prop name.
+- Cleanup on unmount goes through a hook (`useEffect(() => () => …, [])`), not a
+  lifecycle override.
+
 ## Deletion test
 
 Strip the file to its essentials. What remains should be: optional

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

@@ -23,7 +23,7 @@ export const todo = True.schema;
 export const components = { todo, name, complete, order, dragPosition };
 ```
 
-- **Scope** is declared per file with `Scope` from `@adobe/data/ecs`:
+- **Scope** is declared per file with `Scope` from `@adobe/data/schema`:
 
   | scope | shared | durable | spread |
   |---|:-:|:-:|---|
@@ -32,6 +32,8 @@ export const components = { todo, name, complete, order, dragPosition };
   | presence | yes | no | `...Scope.presence` |
   | session | no | no | `...Scope.session` |
 
+  `presence` is not synced yet: `@adobe/data-sync` does not replicate
+  `nonPersistent` data, so a presence value behaves like `session` until it does.
   On a component, the flags scope the **column**. An entity's own scope comes from
   its marker components (`entities.md`).
 - **Every column lives here**, including implementation-only ones (a tag, a drag
@@ -39,8 +41,9 @@ export const components = { todo, name, complete, order, dragPosition };
 - **A tag** is a component with `True.schema`. Add one only when an entity's
   component set would otherwise be contained in another's (`entities.md`).
 - **The name describes the role**, the schema the shape (`position` of a `Vec3`).
-- **Reserved names:** `id`, `nonPersistent`, `nonShared` (built into the ECS), and
-  `index` (it would collide with the `index.ts` barrel).
+- **Reserved names:** `id`, `nonPersistent`, `nonShared` are built into the ECS
+  (`Database.Plugin.create` rejects them at compile time); `index` would collide with
+  the `index.ts` barrel.
 - **A feature built on another** spreads the lower barrel first and pins that its own
   names don't shadow it (a spread would overwrite silently):
   ```ts

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

@@ -5,6 +5,8 @@ paths:
 
 # data/ — the feature's pure Data declarations
 
+> **Legacy feature** (has `data/state/` or `services/main-service/`)? Follow `data/state.md` instead.
+
 The foundation layer. Everything here is a declaration about plain, serializable
 Data: JSON primitives/arrays/objects plus `ReadonlySet`, `ReadonlyMap`, and `Blob`
 (serialize with `Data.stringify` / `Data.parse`). No functions in values, no services,
@@ -26,4 +28,5 @@ fields, it takes them structurally
 (`Iterable<{ readonly mark: PlayerMark; readonly cellIndex: CellIndex }>`).
 
 Components and resources share **one namespace** across every feature in an app:
-a name is one column or one resource, never both, and has one owning feature.
+a name is one column or one resource, never both (the store warns on a clash, and the resource's schema replaces the component's), and
+has one owning feature.

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

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

@@ -76,10 +76,16 @@ calls actions, so conforming actions covers the path the app runs.
 - **Extra ECS tests** (collision selection, a refill after the field clears) live here
   too, since they need the spec or the projection.
 
-## Escape hatch: per-case ambient context
+## Per-case ambient context
 
-A feature whose action reads ambient per-peer context (a `userId` seeded under a
-custom concurrency, as in p2p presence) can't use `checkFeature`. It drives
-`Conformance.runActions` directly, feeding it
-`Conformance.adaptCases(spec.fns, spec.cases, spec.services, true)` with its own
-`makeDb` and `seedContext`. This is the only sanctioned use of the lower-level runners.
+An action that reads context the spec can't carry (the acting peer's `userId`,
+stamped by the db's concurrency at dispatch, as in p2p presence) still uses
+`checkFeature`. Pass a test `concurrency` and a `seedContext(db, before, args)` that
+primes it from each case:
+
+```ts
+Conformance.implementation(spec, { plugin, projection,
+  concurrency: peerConcurrency,
+  seedContext: (_db, _before, args) => { peerUserId = (args as { mark: string }).mark; },
+});
+```

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

@@ -36,6 +36,10 @@ src/
 
 A feature creates only the layers and folders it uses.
 
+A feature that has `data/state/` or `services/main-service/` uses the **legacy
+state-based layout**: follow `data/state.md` and `services/main-service/` for it, and
+don't migrate it unless asked.
+
 ## Dependencies
 
 ```

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

@@ -5,6 +5,8 @@ paths:
 
 # services/ — the feature's services
 
+> **Legacy feature** (has `data/state/` or `services/main-service/`)? Follow `services/main-service/` instead.
+
 A service is the boundary between the feature and the outside world (generation,
 analytics, networking). Each is a namespace folder (`global/namespace.md`) holding its
 interface, its implementation and a fake. Services depend only on `data/`.

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

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

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

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

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