@adobe/data-ai 0.10.21 → 0.10.23

package/skills/build-spec/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: build-spec
+description: Build a feature's spec/ — the State, its actions and derivations, and their cases. Test tier.
+input: feature
+output: feature
+---
+
+Create the feature's `spec/` folder, the specification the ECS will be conformed to:
+
+- `state.ts` — `State` built from `data/` types (singletons named for resources,
+  `ReadonlyMap` entity collections), pinned with `Conformance.StateMatches`; `create.ts`,
+  `samples.ts`, `public.ts`.
+- One file per **action** (each operation the app performs) and per **derivation**
+  (each derived value it shows), each with its inert `*.cases.ts`. A real-time feature
+  adds `systems.ts`: one pure function per ECS system it will have, named the same,
+  each with cases, plus `noOp` states every system leaves unchanged.
+- `transforms.ts` (the barrel of every action and derivation), `spec.ts`
+  (`Conformance.spec`) and `spec.test.ts` (`Conformance.checkSpec`).
+
+Build one action or derivation plus its cases at a time. Logic the ECS will share goes
+into `data/values/` helpers, never here. Gate: `checkSpec` passes.
+
+The how is in the auto-loading `features/spec/index.md` rule.

package/skills/build-systems/SKILL.md

@@ -1,27 +1,21 @@
 ---
 name: build-systems
-description: Build a feature's system-database — the real-time tick loop (systems the scheduler runs each frame). For real-time features only.
+description: Build a real-time feature's ecs/systems layer — the per-frame tick loop. Optional.
 input: feature
 output: feature
 ---
 
-Skip if this feature doesn't contain or require systems.
-Most games that use a canvas will use systems but most applications will not.
+Skip unless the feature is real-time (games, simulations).
 
-Create `services/main-service/system-database/system-database.ts`: `Database.Plugin.create({ extends:
-Database.Plugin.combine(<currentTop>.plugin, scheduler), systems })` — combine `scheduler` with the
-feature's **current top** main-service layer (`ActionDatabase` / `ServiceDatabase` / `ComputedDatabase`,
-whichever it built), never a hardcoded `ComputedDatabase`, so systems *and* any services/actions
-compose into the one `MainService`. The `systems`
-map is declared **inline** (see `features/services/main-service/systems.md` — inline is required for `db` to be
-typed and for system-name inference; a `systems/` folder is optional, only for extracted
-per-frame body helpers).
+Create `ecs/systems/system-database.ts`: `Database.Plugin.create({ extends:
+Database.Plugin.combine(<currentTop>.plugin, scheduler), systems: { … } })`, with the
+`systems` map declared **inline** so `db` and the system names are inferred. Hot
+per-row work writes columns in place; discrete events dispatch transactions. Order
+systems under `schedule`; it is the only statement of order.
 
-- A system is a `SystemDeclaration`: `{ create, schedule?: { before?, after?, during? } }`.
-  `create(db)` runs once (capture queries / index handles / closures); the returned function
-  advances the world one tick. Return `void` for an init-only system (seeding entities).
-- Order under `schedule` (mirror the `data/` step's internal sequence); drive the loop by
-  combining `scheduler` (rAF), gated by the `schedulerState` resource.
+Add `frame: { args, unmodelled?, cases? }` to the implementation: a writer per frame
+arg, each system the spec can't model (wasm, init-only) with its reason, and
+whole-frame cases in `ecs/conformance/frame.cases.ts`. Gate: every
+system's own cases and the frame cases pass.
 
-**Only for real-time features** (games, sims) — turn-based features skip this phase entirely.
-Comes after `build-computed`. The how is in the auto-loading `features/services/main-service/systems.md` rule.
+The how is in the auto-loading `features/ecs/systems.md` rule.

package/skills/build-transactions/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: build-transactions
-description: Build a feature's transaction-database — atomic mutations over the store.
+description: Build a feature's ecs/transactions layer.
 input: feature
 output: feature
 ---
 
-Create `services/main-service/transaction-database/`: `transaction-database.ts` (extends the
-preceding layer — `IndexDatabase` if the feature built indexes, else `CoreDatabase` — adds
-`transactions` from `./transactions/index.js`) plus a `transactions/` folder — one mutation per
-file + barrel. Type the store param `CoreDatabase.Store` (entities/resources/archetypes) or
-`IndexDatabase.Store` (reads an index).
+Create `ecs/transactions/`: `transaction-database.ts` (extends the previous layer, adds
+`transactions` from `./index.js`), one mutation per file, and a barrel. Type the store
+`CoreDatabase.Store`, or `IndexDatabase.Store` once it reads an index. Guard by entity
+kind, and apply `data/values/` helpers; never import `spec/`.
 
-Comes after `index-database` (or `core-database` if no indexes).
+Build the transactions the spec actions will need. They are conformed through the
+actions that call them, so their gate is `build-actions`; add any missing one there.
 
-The how is in the auto-loading `features/services/main-service/transactions.md` rule.
+The how is in the auto-loading `features/ecs/transactions.md` rule.

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.