@adobe/data-ai 0.10.21 → 0.10.23

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).

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

@@ -1,187 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/main-service.ts'
-  - '**/features/*/services/main-service/*-database/*-database.ts'
----
-
-# services/main-service/ — the feature service (ECS implementation)
-
-`main-service/` is the feature's single entrypoint service (see `../index.md`),
-implemented as a reactive Entity-Component-System — an implementation detail
-behind the service. Everything ECS-specific lives here: the schema that stores `data/` types as
-entity state (`core-database/`), the derived and mutating logic over it
-(`indexes/`, `transactions/`, `computed/`), the database-bound service factories
-(`services/`), the async orchestrators (`actions/`), and the layered plugins
-that compose it all.
-
-The distinction from `data/`: a `data/` type is ECS-agnostic (a plain
-serializable value); an ECS construct is *how that type is stored and operated
-on* inside a database. `mark: PlayerMark.schema` is not a data-model fact — it
-is "the ECS keeps a PlayerMark here".
-
-## The core schema — `core-database/`
-
-A feature's whole schema — every component, resource, and archetype — lives in
-one `core-database/` folder: `core-database.ts` plus one file per facet the
-feature uses (all three facets are optional on `Database.Plugin.create`):
-
-```
-core-database/
-  core-database.ts   # Database.Plugin.create({ components?, resources?, archetypes? }) → CoreDatabase
-  components.ts      # export const components = Database.components({ … })
-  resources.ts       # export const resources  = Database.resources({ … })
-  archetypes.ts      # export const archetypes = Database.archetypes(components, { … })
-```
-
-`core-database.ts` is a thin assembler; each facet file exports one typed object
-built by a `Database.*` helper. No per-item files, no barrels. Create only the
-facet files the feature needs — a singleton feature with no entities is just
-`resources.ts` + `core-database.ts` (no empty `components({})` boilerplate).
-
-### Schema scopes
-
-State divides on two orthogonal axes — **scope** (shared with peers vs. local to
-this client) and **lifetime** (durable across reloads vs. ephemeral) — giving
-four scopes, each stamping a flag pair:
-
-| scope | shared? | durable? | flags |
-|-------|:--:|:--:|-------|
-| **document** | yes | yes | — |
-| **settings** | no | yes | `nonShared` |
-| **presence** | yes | no | `nonPersistent` |
-| **session** | no | no | `nonPersistent` + `nonShared` |
-
-`Database.components` / `Database.resources` group declarations by scope and
-stamp the flags. Every scope key is optional — declare only the ones you use
-(most features are document-only):
-
-```ts
-// components.ts
-export const components = Database.components({
-  document: { todo: True.schema, name: Name.schema, complete: Boolean.schema },
-  session:  { dragPosition: DragPosition.schema },   // omit settings / presence
-});
-
-// resources.ts — entries must carry a `default` (enforced at the call)
-export const resources = Database.resources({
-  settings: { displayCompleted: Boolean.schema },
-});
-```
-
-A component/resource *value* is a plain `data/`-schema re-export (or a small
-inline literal); its scope — and therefore its flags — is stated only by which
-group it sits in. Hover a scope key for its meaning. The database does not yet
-act on these flags (see the `nonShared` schema note); they model
-shared/local × durable/ephemeral now, and the durable-shared subset
-(`document`) is the set a bare store could be rebuilt from for reconciliation.
-
-**Shared columns live in `data/`.** A column two features share (e.g. a `name`
-on both todos and users) is a `data/` type both reference by identity
-(`Name.schema`), so `combinePlugins` dedupes it. Only the `document` scope
-preserves schema identity (it applies no flags) — never share a
-settings/presence/session column across features by identity.
-
-### Archetypes
-
-`archetypes.ts` declares the feature's entity shapes with
-`Database.archetypes(components, { … })`, which validates every key against the
-component map and preserves each archetype's literal tuple — no per-archetype
-`as const`. Archetypes are a packing convenience, not serialized data; one may
-span scopes (a document entity with an ephemeral `dragPosition` slot). An
-archetype mirroring a `data/` row type carries a private compile-time
-drift-guard (see `archetypes.md`).
-
-## Layered composition (behaviour)
-
-Above the schema, behaviour is a chain of `Database.Plugin`s, each its own
-**namespace folder** — `<layer>-database/` holding the eponymous
-`<layer>-database.ts` (the plugin, which `extends` the previous layer) plus the
-facet folder it adds. **Name each layer for the facet it adds — never for the
-feature or app.** A feature creates only the layers it uses:
-
-```
-main-service/
-  core-database/            # the schema (above)
-  index-database/           # extends core;        indexes/
-  transaction-database/     # extends index;       transactions/
-  service-database/         # extends transaction; services/
-  computed-database/        # extends service;     computed/
-  action-database/          # extends computed;     actions/
-```
-
-Each exports a namespace mirroring the plugin — the composed object is a
-`Database` (the `@adobe/data` term) even though the folder is `services/main-service/`:
-
-```ts
-export type IndexDatabase = Database.Plugin.ToDatabase<typeof indexDatabasePlugin>;
-export namespace IndexDatabase {
-  export const plugin = indexDatabasePlugin;
-  export type Store = Database.Plugin.ToStore<typeof indexDatabasePlugin>;
-}
-```
-
-### The assembled database — `MainService`
-
-*Which* layer is topmost varies with the facets a feature uses (service /
-computed / action / system). Consumers — `ui/`, the app entry, `services/main-service/conformance/`
-— need the *whole* feature database but must not name that layer, or adding or
-dropping a layer rewrites them all. Alias it once from the **folder-eponymous
-`main-service.ts`** (per `global/namespace.md`, a folder's primary export lives in
-its same-named file), as a namespace so consumers reach `MainService.plugin` /
-`MainService.Store`:
-
-```ts
-// services/main-service/main-service.ts
-export { SystemDatabase as MainService } from "./system-database/system-database.js";
-```
-
-Every consumer references **`MainService`** (`.plugin`, `.Store`) — never the
-topmost layer. Add or drop a layer → change only this one line.
-
-**Cross-feature naming.** Inside a feature the core and assembled databases are
-the bare `CoreDatabase` / `MainService`. When *another* feature or package
-imports one — a peer built on it, the base `imports` a peer's `core-database`, a
-downstream package — reference it **feature-qualified**: `<Feature>CoreDatabase`
-/ `<Feature>MainService`, re-exported so from the feature's barrel
-(`export { CoreDatabase as TodoCoreDatabase } from "…/core-database.js"`) — so
-two features' `CoreDatabase`s never collide.
-
-## What each layer takes as input
-
-- **`plugin`** — every layer `extends` the previous layer's `plugin`; that is
-  the one universal thread up the chain.
-- **`Store`** (via `ToStore`) — used *only* by **transactions** (`t:
-  <Layer>.Store`). A store carries the index handles and the initiating
-  `userId`, so a store *is* the transaction context; there is no separate
-  transaction-context type. Use **`CoreDatabase.Store`** for a transaction that
-  reads/writes entities, resources, or archetypes; **`IndexDatabase.Store`** the
-  moment it reads an index.
-- **the whole `Database`** — **services**, **computed**, and **actions** each
-  take `service: <Layer>` (the lowest layer whose database exposes what they
-  read/call): services read observables and call transactions; computed reads
-  `service.observe.*` and, once it needs a service's own reactive surface,
-  `service.services.*`; actions call `service.services.*` then
-  `service.transactions.*`.
-
-Each subfolder has its own rule. Modelling a plugin's authored vs. derived
-surface is covered by `plugin-modelling.md`.
-
-## Facets are flat until they aren't
-
-A **behavioural** facet folder (`indexes/`, `transactions/`, `computed/`,
-`actions/`) holds one file per item plus an `index.ts` barrel — flat while that
-reads well, roughly up to half a dozen items. When a cohesive cluster grows past
-that, promoting it into a themed subfolder with its own `index.ts` (re-exported
-by the facet barrel) is a standard move — only once the folder actually feels
-crowded:
-
-```
-transactions/
-  order/                 # a cohesive cluster: fractional-ordering helpers
-    index.ts  next-order.ts  normalize-order.ts  select-ordered-todos.ts
-  create-todo.ts  drag-todo.ts  …
-```
-
-The **schema** facets (components / resources / archetypes) are *single files*
-in `core-database/`, not folders. A whole feature should stay small enough that
-subfoldering rarely bites — grow by adding features, not by bloating one.

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

@@ -1,28 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/**/core-database/resources.ts'
----
-
-# core-database/resources.ts — the feature's resources
-
-A resource is a singleton component — one instance held on a single entity. One
-file, one export: `resources`, built with `Database.resources(...)`. It is
-identical to `Database.components` except **every entry must carry a `default`**
-— a missing `default` is a compile error here, at the declaration site.
-
-```ts
-import { Database } from "@adobe/data/ecs";
-import { Boolean } from "@adobe/data/schema";
-
-export const resources = Database.resources({
-  settings: { displayCompleted: Boolean.schema },   // per-device view toggle
-});
-```
-
-- Give each resource a `default` — spread the data-type's schema and add one, or
-  bind a `data/` / primitive schema that already carries a sensible default.
-- **Scope = which group it sits in** (see `services/main-service/index.md`). A per-device
-  preference is `settings` (durable, `nonShared`); a synced-but-unsaved value is
-  `presence`; a saved shared value is `document`.
-- Because there is only ever one instance, linear-memory packing buys nothing —
-  never choose a struct schema for efficiency here.

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

@@ -1,25 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/service-database/services/**/*.ts'
----
-
-# database/services/ — database-bound service factories
-
-One factory per file: `create<Name>Service(service, …)` that binds a service
-implementation to a live database — reading its observables and invoking
-its transactions. This is where the async `services/` contracts (or
-framework services like `AgenticService`) are wired to ECS state.
-
-```ts
-export const createAgentService = (service: TransactionDatabase, mark: PlayerMark): AgenticService =>
-    /* … reads service.observe.*, calls service.transactions.* … */;
-```
-
-Type `service` on the lowest layer exposing what the factory reads/calls (never
-the `service-database` itself — that would be a cycle).
-
-An `index.ts` barrel re-exports the factories; `service-database.ts`
-registers them under the `services` facet, each keyed by the name
-consumers read it as (`service.services.agent`). Defining a standalone
-service contract (not yet bound to a database) belongs in the feature
-`services/` layer.

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

@@ -1,59 +0,0 @@
----
-paths:
-  - '**/features/*/services/main-service/transaction-database/transactions/**/*.ts'
----
-
-# database/transactions/ — atomic mutations
-
-One mutation per file: a function taking the transaction store as its
-first argument and pure `data/` args, returning `void`. It reads and
-writes `t.resources` / entities; all its writes commit or roll back
-together.
-
-```ts
-import { PlayMoveArgs } from "../../../data/play-move-args/play-move-args.js";
-import type { CoreDatabase } from "../../core-database/core-database.js";
-
-export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
-    // guard, then mutate t.resources / entities / archetypes
-};
-```
-
-- Type the store parameter as `<Layer>.Store`: **`CoreDatabase.Store`** for a
-  transaction that reads/writes entities, resources, or archetypes (the common
-  case — all schema lives in `core-database`); **`IndexDatabase.Store`** the
-  moment it reads an index. A store *is* the transaction context: it carries the
-  index handles and the initiating `t.userId`. There is no separate
-  transaction-context type.
-- Keep transactions idempotent under replay where sync/P2P applies —
-  validate and silently return on illegal or out-of-turn input rather
-  than throwing.
-- Decisions come from pure `data/` helpers; the transaction only applies the
-  result — read the touched slice, call the `data/` transform, write the diff.
-- Keep transaction files **single-export** (the `transactions/` barrel is
-  `export *`-ed into the plugin facet, so a second export would pollute it).
-- **ECS-based feature (no `data/state/`):** there are no conformance cases, so
-  **every transaction carries its own unit test** — `Store.create(plugin)`, run the
-  transaction, assert the resulting resources/entities/archetypes. That test is the
-  direct substitute for the conformance oracle (see `../../index.md`, Two modes). The
-  bullet below applies only to **state-based** features.
-- **Conformance is wired once, centrally, and auto-paired** — not per-file. The
-  feature's single `conformance/conformance.test.ts` `Conformance.checkFeature(spec)`
-  call conforms transactions: it pulls them off **`plugin.transactions`** (the
-  registered facet), pairs each to the **same-named** `data/state` transition, and
-  conforms it — seed `fromState(before)`, apply, `Match.assert` `toState ≡ after`
-  (state only; service effects are asserted through the action). There is **no**
-  `define`/`conforms` adapter and **no** `covers` guard. A transaction taking
-  **entity ids** takes them under the transition's own arg key (`{ id }`); the runner
-  resolves each id the case's `args` schema marks via the id→entity map `fromState` returns. A
-  transaction with **no same-named transition** is infrastructure (`setInput`,
-  `setBounds`) or the drag UI op (`dragTodo`) or system-dispatched — it is simply
-  **skipped**, no guard needed. Don't add a per-item adapter for a renamed op; add a
-  thin same-named transaction instead (see `conformance.md`).
-- An `index.ts` barrel feeds the `transactions` plugin facet — so it must
-  re-export **only** the mutations. A read/query helper shared by several
-  transactions (`readShip`, `readBoard` — a `(t) => value` function) may live
-  beside them in `transactions/`, but keep it **out of the barrel**, or it gets
-  registered as a dispatchable transaction. (These are related helpers, so they
-  belong here, not in a separate folder — `global/cohesion.md`'s peer-level caution
-  doesn't apply.)