@adobe/data-ai 0.9.89 → 0.9.91

package/.claude/rules/README.md

@@ -13,30 +13,36 @@ folder's own `index.md` holds just enough to understand that folder; each
 child gets its own file (recursing wherever the source tree does):
 
 ```
+global/               # always-on conventions — deliberately repo-wide globs
+  namespace.md  cohesion.md  type-casts.md  function-references.md  react.md
 features/
-  index.md            # the feature layering as a whole (ui → ecs → services → data)
+  index.md            # the feature layering as a whole (ui → services → data)
   data/
     index.md          # data-type namespaces (foundation)
     state.md          # the State aggregate: pure transforms & derivations
-  services/index.md   # service interfaces + service types
-  ecs/
-    index.md          # the ECS layer + layered database plugins
-    components.md  resources.md  archetypes.md
-    computed.md  indexes.md  transactions.md  services.md  actions.md
-    systems.md  conformance.md
+  services/
+    index.md          # the services layer: main-service + capability contracts
+    main-service/     # the feature service (ECS implementation)
+      index.md        # the service + its layered database plugins
+      components.md  resources.md  archetypes.md
+      computed.md  indexes.md  transactions.md  services.md  actions.md
+      systems.md  conformance.md
   ui/index.md         # UI (points to element / presentation / lazy-element file rules)
 ```
 
-Alongside `features/`, the rules-root `.md` files hold the **cross-cutting**
-patterns the feature rules reference — `namespace.md`, `data-modelling.md`,
-`type-casts.md`, `function-references.md`, `cohesion.md`, `archetypes.md` (row
-iteration), `plugin-modelling.md`, and the UI file rules (`element.md`,
-`lazy-element.md`, `presentation.md`). They live here so the bundle is self-contained; this repo
-symlinks them into its own `.claude/rules/` (as it does `features/`).
+The `global/` rules (`namespace.md`, `cohesion.md`, `type-casts.md`,
+`function-references.md`, `react.md`) are **intentionally repo-wide** — their
+`paths:` globs (`**/*.ts` etc.) apply everywhere, by design, so the folder name
+makes that explicit. Alongside `features/`, the remaining rules-root `.md` files
+hold the other **cross-cutting** patterns the feature rules reference —
+`data-modelling.md`, `archetypes.md` (row iteration), `plugin-modelling.md`, and
+the UI file rules (`element.md`, `lazy-element.md`, `presentation.md`). They live
+here so the bundle is self-contained; this repo symlinks them into its own
+`.claude/rules/` (as it does `features/`).
 
 Each rule's `paths:` glob is scoped to `**/features/*/<layer>/…`, so these
 rules apply only once an application opts into the feature-folder pattern
 (source organized under `features/<name>/`). Editing
-`features/<name>/ecs/<layer>-database/components/foo.ts` pulls in both
-`ecs/index.md` (the layer overview) and `ecs/components.md` (the specifics) —
-at creation and at every later edit.
+`features/<name>/services/main-service/core-database/components.ts` pulls in both
+`main-service/index.md` (the layer overview) and `main-service/components.md`
+(the specifics) — at creation and at every later edit.

package/.claude/rules/element.md

@@ -124,7 +124,7 @@ Lit-only: `static styles = styles` from a sibling `*.css.ts`. `@property`
 exists *only* for locator inputs — never for state, never for derived
 values, never for parent-forwarded flags. The `P` in `DatabaseElement<P>` (and
 the `get plugin()` it returns) is the surface the element *consumes* — never the
-varying topmost-layer name (see `features/ecs/index.md`): `typeof
+varying topmost-layer name (see `features/services/main-service/index.md`): `typeof
 FeatureDatabase.plugin` for a self-contained feature. **Exception:** an element
 meant to be *extended* — injected with various databases that build on this
 feature (a peer app that adds an agent, a p2p/presence build) — types on the

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

@@ -11,7 +11,7 @@ communication over the wire — no functions, no handles, just plain data.
 It depends on nothing but `@adobe/data` and other `data/` declarations, and
 needs no knowledge of anything built on top of it.
 
-Each data type is its own namespace folder (see `namespace.md`), holding
+Each data type is its own namespace folder (see `global/namespace.md`), holding
 its schema, its derived type, and its pure synchronous helpers together:
 
 ```

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

@@ -43,8 +43,8 @@ export * as State from "./public.js";
 - Each transform has a sibling `*.test.ts`; performance is irrelevant here,
   correctness is everything. Keep its cases in a sibling `<transform>.cases.ts`
   typed `ConformanceCase<Args>[]` (the shared `conformance-case.ts` type) —
-  spec-owned truth the matching ecs conformance test imports unchanged (see
-  `ecs/conformance.md`). Author `before`/`after` as full `State`
+  spec-owned truth the matching main-service conformance test imports unchanged (see
+  `services/main-service/conformance.md`). Author `before`/`after` as full `State`
   (`{ ...State.create(), …overrides }`); the generic-slice signature lets them
   flow through. Tolerant full-`State` equality is the shared
   `expect-state-matches.ts`, alongside the cases here.

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

@@ -2,7 +2,6 @@
 paths:
   - '**/features/*/data/**/*.ts'
   - '**/features/*/services/**/*.ts'
-  - '**/features/*/ecs/**/*.ts'
   - '**/features/*/ui/**/*.ts'
 ---
 
@@ -14,34 +13,39 @@ trust, and an **efficient implementation** proven equivalent to it.
 - **`data/` is the specification.** The whole feature modelled as one immutable
   `State` with pure transformations over it — correct by construction, fully
   unit-tested, performance irrelevant. This is the source of truth.
-- **`ecs/` is the implementation.** The same model physically arranged for
-  mutation efficiency (a reactive Entity-Component-System). Its reads and writes
-  wrap the `data/` functions where practical; where they must be hand-optimized,
-  unit tests verify they still agree with the `data/` precedent.
+- **`services/main-service/` is the implementation.** The same model physically
+  arranged for mutation efficiency — a reactive Entity-Component-System, an
+  implementation detail behind the service. Its reads and writes wrap the
+  `data/` functions where practical; where they must be hand-optimized, unit
+  tests verify they still agree with the `data/` precedent.
 
-Because the optimized `ecs/` layer is largely mechanical given the `data/` spec,
-it can be generated and kept honest by AI rules, with the conformance tests as
-the safety net. Net result: write a slow-but-verifiable app, then derive a fast
-one that provably behaves the same.
+Because the optimized `main-service` is largely mechanical given the `data/`
+spec, it can be generated and kept honest by AI rules, with the conformance
+tests as the safety net. Net result: write a slow-but-verifiable app, then
+derive a fast one that provably behaves the same.
 
-## The four layers
+## The layers
 
-`ui → ecs → services → data` — higher imports lower, never the reverse. `data/`
+`ui → services → data` — higher imports lower, never the reverse. `data/`
 depends on nothing but `@adobe/data` and other `data/` declarations. A feature
 creates only the layers it uses.
 
 | Layer | Role |
 |-------|------|
 | `data/` | The spec: `State`, pure transforms & derivations, entity sub-types. Pure, tested. |
-| `services/` | Async capability contracts (ports to the outside world). Optional. |
-| `ecs/` | The implementation: the ECS materialisation + reactive reads/writes over it. |
+| `services/main-service/` | The implementation: the ECS materialisation + reactive reads/writes. The **sole entrypoint** — the only service the `ui/` binds to. |
+| `services/<name>-service/` | Async capability contracts (ports to the outside world). Reached only *through* `main-service` (its actions/services wire them in), never by the UI. Optional. |
 | `ui/` | Presentation. |
 
+`services/` holds two kinds of service: the one `main-service/` (ECS-backed
+state, its own subtree of rules) and any async capability contracts. The UI, and
+every external consumer, sees only `main-service`.
+
 ## One app, many features
 
 An application is a set of **features**, each its own `features/<name>/` folder
-with the same four layers. One base feature (`features/main/`) is the host; the
-rest are peers that load lazily.
+with the same layers. One base feature (`features/main/`) is the host; the rest
+are peers that load lazily.
 
 **Keep each feature small; grow by adding features, not by bloating one.** A
 feature is meant to fit in the head — a handful of files per layer. When a
@@ -53,16 +57,17 @@ its own peer feature rather than let one feature's folders balloon.
   base must not depend on its children — with one sanctioned exception below.
 - **The base `imports` every peer's *schema* plugin** —
   `Database.Plugin.create({ imports })`, not `extends`. `imports` merges the
-  peer's `core-database` (components / resources / archetypes) into the shared
-  store at runtime **without** pulling its types or behavior into the base's type
-  or bundle (`extends` would do both, and cost quadratically). So one store knows
-  every feature's schema — data coexists, persists, and syncs — while the base
-  stays decoupled. Import the peer's `core-database.ts` plugin (schema only) —
-  under its feature-qualified name `<Peer>CoreDatabase` (see the cross-feature
-  naming rule in `ecs/index.md`): its indexes, transactions, computed, services,
-  and UI stay out until the feature loads. A column two features share (e.g.
-  `name`) lives in `data/` and is referenced by identity, so `combinePlugins`
-  dedupes it.
+  peer's `services/main-service/core-database` (components / resources /
+  archetypes) into the shared store at runtime **without** pulling its types or
+  behavior into the base's type or bundle (`extends` would do both, and cost
+  quadratically). So one store knows every feature's schema — data coexists,
+  persists, and syncs — while the base stays decoupled. Import the peer's
+  `services/main-service/core-database.ts` plugin (schema only) — under its
+  feature-qualified name `<Peer>CoreDatabase` (see the cross-feature naming rule
+  in `services/main-service/index.md`): its indexes, transactions, computed,
+  services, and UI stay out until the feature loads. A column two features share
+  (e.g. `name`) lives in `data/` and is referenced by identity, so
+  `combinePlugins` dedupes it.
 - **Peers load lazily by being used.** `DatabaseElement`, on connect, walks up to
   the nearest ancestor database and `extend`s it with its own plugin — so the
   first time a feature element renders, its full plugin (indexes, transactions,
@@ -71,25 +76,37 @@ its own peer feature rather than let one feature's folders balloon.
   load is genuinely on-demand.
 - **The base reaches a child only through a lazy element wrapper** — a tiny
   `Foo()` that `void import()`s the child element. That dynamic import is the one
-  allowed core→child seam; the heavy element and its service database stay in the
+  allowed core→child seam; the heavy element and its main-service stay in the
   child's own chunk.
 
 ## Spec and implementation, kept honest
 
-The tie between `data/` (spec) and `ecs/` (implementation) is **conformance**,
-one property — `toState(apply(fromState(before), args)) ≡ transform(before, args)`:
-each ecs mutation, seeded and read back through a test-only `ecs ↔ State`
+The tie between `data/` (spec) and `main-service` (implementation) is
+**conformance**, one property —
+`toState(apply(fromState(before), args)) ≡ transform(before, args)`: each
+main-service mutation, seeded and read back through a test-only store↔`State`
 projection, equals the pure `data/` transform it stands for. The projection and
-its runner live in `ecs/conformance/` (see `ecs/conformance.md`); the shared
-`{ before, args, after }` cases are spec-owned (`data/state/<transform>.cases.ts`),
-so conforming the ecs path is "substitute the implementation, reuse the
-expectations." This lets the ecs layer be largely mechanical and agent-generated,
-with the spec as oracle. *How* to author each layer lives in the per-folder rules
-below.
+its runner live in `services/main-service/conformance/` (see
+`services/main-service/conformance.md`); the shared `{ before, args, after }`
+cases are spec-owned (`data/state/<transform>.cases.ts`), so conforming the
+implementation is "substitute the implementation, reuse the expectations." This
+lets `main-service` be largely mechanical and agent-generated, with the spec as
+oracle. *How* to author each layer lives in the per-folder rules below.
+
+## Reference implementations
+
+Working samples ship inside `@adobe/data` at
+`node_modules/@adobe/data/references/<sample>/src/` — read them for concrete,
+current examples of this structure. `data-lit-todo` is the most complete
+(multi-feature, capability services, indexes, conformance tests);
+`data-lit-tictactoe` is the minimal turn-based reference.
 
 ## Per-layer detail
 
-See the rules under each folder: `data/`, `services/`, `ecs/` (components,
-resources, archetypes, computed, indexes, transactions), `ui/`. Cross-cutting
-patterns live at the rules root — `namespace.md`, `data-modelling.md`,
-`archetypes.md` (row iteration), `type-casts.md`, `cohesion.md`.
+See the rules under each folder: `data/`, `services/` — the `main-service/`
+subtree (components, resources, archetypes, computed, indexes, transactions,
+systems, conformance) and capability-contract services — and `ui/`.
+Always-on conventions live in `global/` (`namespace.md`, `cohesion.md`,
+`type-casts.md`, `function-references.md`, `react.md` — deliberately repo-wide);
+other cross-cutting patterns at the rules root — `data-modelling.md`,
+`archetypes.md` (row iteration).

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

@@ -3,32 +3,45 @@ paths:
   - '**/features/*/services/**/*.ts'
 ---
 
-# services/ — async capability contracts
+# services/ — the feature's services
 
-Async ports: processing, persistence, observation, generation. A service
-is the boundary between pure feature code and the outside world, which is
-why its members are async — enabling cross-process portability and lazy
-loading (`AsyncDataService.createLazy`).
+Everything a feature exposes as a service lives here. Two kinds:
 
-This layer holds **service interfaces**, one per `<name>-service/` folder;
-the export and folder both carry the `-service` suffix. Each is a
-namespace folder (`namespace.md`).
+- **`main-service/`** — the one entrypoint. The ECS-backed reactive state
+  service (materialisation + reads/writes over it); the only service the `ui/`
+  and external consumers bind to. It has its own subtree of rules
+  (`main-service/index.md` and the layer files under it). Every feature with
+  state has exactly one.
+- **`<name>-service/`** — async **capability contracts**: ports to the outside
+  world (processing, persistence, observation, generation). Reached only
+  *through* `main-service` (its service/action layers wire them in), never by the
+  UI. A feature has zero or more.
 
-- The contract is an `interface` — the only place `interface` is used in
-  the codebase — validated immediately with
+The rest of this rule governs the capability contracts; `main-service` follows
+its own subtree.
+
+## Capability contracts
+
+Each is a namespace folder (`global/namespace.md`); the export and folder both carry the
+`-service` suffix. A service is the boundary between pure feature code and the
+outside world, which is why its members are async — enabling cross-process
+portability and lazy loading (`AsyncDataService.createLazy`).
+
+- The contract is an `interface` — the only place `interface` is used in the
+  codebase — validated immediately with
   `Assert<AsyncDataService.IsValid<typeof MyService>>`.
 - Members are async only: `void | Promise<T> | AsyncGenerator<T> | Observe<T>`.
 - Provide `create*` factories.
 
 ## Where the I/O types live
 
-Most input/output types belong to a single service — declare them **on
-that service's namespace** (`MyService.SomeInput`) and expose them only
-when something external actually references them; not everything does.
+Most input/output types belong to a single service — declare them **on that
+service's namespace** (`MyService.SomeInput`) and expose them only when something
+external actually references them; not everything does.
 
-A **service type** may be non-serializable (callbacks, function
-signatures) — that's what distinguishes it from a `data/` type. If an I/O
-value is a plain serializable value, prefer a `data/` type instead.
+A **service type** may be non-serializable (callbacks, function signatures) —
+that's what distinguishes it from a `data/` type. If an I/O value is a plain
+serializable value, prefer a `data/` type instead.
 
-A non-service type sits *directly* in `services/` **only** when it is
-genuinely shared across more than one service — rare, but it happens.
+A non-service type sits *directly* in `services/` **only** when it is genuinely
+shared across more than one service — rare, but it happens.

package/.claude/rules/features/{ecs → services/main-service}/actions.md

@@ -1,9 +1,9 @@
 ---
 paths:
-  - '**/features/*/ecs/**/actions/**/*.ts'
+  - '**/features/*/services/main-service/**/actions/**/*.ts'
 ---
 
-# ecs/actions/ — async orchestration
+# 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

package/.claude/rules/features/{ecs → services/main-service}/archetypes.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/core-database/archetypes.ts'
+  - '**/features/*/services/main-service/**/core-database/archetypes.ts'
 ---
 
 # core-database/archetypes.ts — the feature's archetypes

package/.claude/rules/features/{ecs → services/main-service}/components.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/core-database/components.ts'
+  - '**/features/*/services/main-service/**/core-database/components.ts'
 ---
 
 # core-database/components.ts — the feature's components
@@ -28,7 +28,7 @@ export const components = Database.components({
 - 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 `ecs/index.md` for the four scopes and
+- **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.

package/.claude/rules/features/{ecs → services/main-service}/computed.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/computed/**/*.ts'
+  - '**/features/*/services/main-service/**/computed/**/*.ts'
 ---
 
 # database/computed/ — derived observable values

package/.claude/rules/features/{ecs → services/main-service}/conformance.md

@@ -1,9 +1,9 @@
 ---
 paths:
-  - '**/features/*/ecs/**/conformance/**/*.ts'
+  - '**/features/*/services/main-service/**/conformance/**/*.ts'
 ---
 
-# ecs/conformance/ — spec↔implementation projection (test-only)
+# services/main-service/conformance/ — spec↔implementation projection (test-only)
 
 The bridge that keeps the ecs implementation honest against the `data/` spec.
 **Test-only**: imported solely by `*.test.ts` and in no facet barrel, so it never
@@ -19,7 +19,7 @@ The property, per `{ before, args, after }` case:
 
 Conformance test-support splits by concern along the layer boundary:
 
-- **Store-side, here in `ecs/conformance/`:**
+- **Store-side, here in `services/main-service/conformance/`:**
   - `from-state.ts` → `fromState(store: CoreDatabase.Store, state: State): void`
     seeds the store (clear tail→head → insert entities → set resources) to a `State`.
   - `to-state.ts` → `toState(store): State` reads the store back — each kind via

package/.claude/rules/features/{ecs → services/main-service}/index.md

@@ -1,11 +1,13 @@
 ---
 paths:
-  - '**/features/*/ecs/**/*.ts'
+  - '**/features/*/services/main-service/**/*.ts'
 ---
 
-# ecs/ — the Entity-Component-System layer
+# services/main-service/ — the feature service (ECS implementation)
 
-Everything ECS-specific lives here: the schema that stores `data/` types as
+`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
@@ -23,7 +25,7 @@ one `core-database/` folder: `core-database.ts` plus one file per facet the
 feature uses (all three facets are optional on `Database.Plugin.create`):
 
 ```
-ecs/core-database/
+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({ … })
@@ -97,7 +99,7 @@ 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:
 
 ```
-ecs/
+main-service/
   core-database/            # the schema (above)
   index-database/           # extends core;        indexes/
   transaction-database/     # extends index;       transactions/
@@ -107,7 +109,7 @@ ecs/
 ```
 
 Each exports a namespace mirroring the plugin — the composed object is a
-`Database` (the `@adobe/data` term) even though the folder is `ecs/`:
+`Database` (the `@adobe/data` term) even though the folder is `services/main-service/`:
 
 ```ts
 export type IndexDatabase = Database.Plugin.ToDatabase<typeof indexDatabasePlugin>;
@@ -120,12 +122,12 @@ export namespace IndexDatabase {
 ### The assembled database — `FeatureDatabase`
 
 *Which* layer is topmost varies with the facets a feature uses (computed /
-service / action / system). Consumers — `ui/`, the app entry, `ecs/conformance/`
+service / 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:
 
 ```ts
-// ecs/feature-database.ts
+// services/main-service/feature-database.ts
 export { SystemDatabase as FeatureDatabase } from "./system-database/system-database.js";
 ```
 

package/.claude/rules/features/{ecs → services/main-service}/indexes.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/indexes/**/*.ts'
+  - '**/features/*/services/main-service/**/indexes/**/*.ts'
 ---
 
 # database/indexes/ — ECS indexes

package/.claude/rules/features/{ecs → services/main-service}/resources.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/core-database/resources.ts'
+  - '**/features/*/services/main-service/**/core-database/resources.ts'
 ---
 
 # core-database/resources.ts — the feature's resources
@@ -21,7 +21,7 @@ export const resources = Database.resources({
 
 - 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 `ecs/index.md`). A per-device
+- **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 —

package/.claude/rules/features/{ecs → services/main-service}/services.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/services/**/*.ts'
+  - '**/features/*/services/main-service/**/services/**/*.ts'
 ---
 
 # database/services/ — database-bound service factories

package/.claude/rules/features/{ecs → services/main-service}/systems.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/systems/**/*.ts'
+  - '**/features/*/services/main-service/**/systems/**/*.ts'
   - '**/systems/*.ts'
 ---
 
@@ -32,6 +32,8 @@ import { Database, scheduler } from "@adobe/data/ecs";
 import { Motion } from "../../data/motion/motion.js";
 
 const plugin = Database.Plugin.create({
+    // combine scheduler with the CURRENT TOP layer — ComputedDatabase here, but
+    // ActionDatabase / ServiceDatabase if the feature built those (systems come last).
     extends: Database.Plugin.combine(ComputedDatabase.plugin, scheduler),
     systems: {
         control: { create: (db) => () => { /* input → ship; db.transactions.fireBullet() */ } },
@@ -119,15 +121,17 @@ with no rAF and no rendering attached.
 
 ## Layer
 
-`system-database.ts` extends the previous ecs layer (usually `ComputedDatabase`),
-combined with `scheduler`, and declares the `systems` map **inline** (see above —
+`system-database.ts` extends the feature's **current top** main-service layer (`ActionDatabase` /
+`ServiceDatabase` / `ComputedDatabase` — whichever it built; systems come last in the pipeline, so
+they must sit atop any service/action layers, not a hardcoded `ComputedDatabase`), combined with
+`scheduler`, and declares the `systems` map **inline** (see above —
 this is the one facet not split one-per-file, because `create`'s `db` is only typed
 inline and standalone declarations break name inference). A `systems/` folder is
 optional: it holds extracted per-frame body helpers (`(db) => () => void`) only when
 an inline body grows too large — the schedule and registration still live inline in
 `system-database.ts`. The headless conformance test drives one frame via
 `db.system.order` / `db.system.functions` and compares to the `data/` `step` oracle,
-**reusing the feature projection** (`ecs/conformance.md`); it lives at
+**reusing the feature projection** (`services/main-service/conformance.md`); it lives at
 `system-database/tick-loop.test.ts`. Test **selection/detection** logic (which
 entities collide, which pair resolves) separately, with seeded edge-case geometries
 — it's a system concern, not a transaction, and where subtle bugs hide.

package/.claude/rules/features/{ecs → services/main-service}/transactions.md

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/ecs/**/transactions/**/*.ts'
+  - '**/features/*/services/main-service/**/transactions/**/*.ts'
 ---
 
 # database/transactions/ — atomic mutations
@@ -32,7 +32,7 @@ export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
   result — read the touched slice, call the `data/` transform, write the diff.
 - **Conform every transaction to its `data/` transform** in its sibling
   `*.test.ts`, via `expectConforms` over the spec's shared cases (see
-  `ecs/conformance.md`): seed `fromState(before)`, dispatch, assert `toState ≡
+  `services/main-service/conformance.md`): seed `fromState(before)`, dispatch, assert `toState ≡
   after`, covering every branch and edge case. A transaction taking **entity
   ids** resolves them from the seeded store in the `apply` closure; one with no
   `data/` analogue (`setBounds`, `setInput`) gets a direct resource assertion.
@@ -41,5 +41,5 @@ export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
   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 — `cohesion.md`'s peer-level caution
+  belong here, not in a separate folder — `global/cohesion.md`'s peer-level caution
   doesn't apply.)

package/.claude/rules/features/ui/binding-element.md

@@ -32,7 +32,7 @@ Presentation files (`*-presentation.ts`), CSS files (`*.css.ts`), tests (`*.test
 A binding element is a thin wire between a service and a presentation. The class body contains:
 
 1. Optional static `styles` property definition
-2. Zero or more `@property` declarations (whitelisted below).
+2. Zero or more `@property` declarations (allowed below).
 3. One `render()` method whose body is: one `useObservableValues(...)` call, another lifecycle hook call (in rare cases), a null-guard, and
    `return presentation.render({ ...values, ...callbacks })`.
 
@@ -40,7 +40,7 @@ No other members. No `@state`. No private handler fields. No lifecycle methods (
 `disconnectedCallback`) except on app-entrypoint classes where the lifecycle concern is app-boot shaped but cannot be expressed as a hook
 (see `.claude/rules/hooks.md` for hook-first lifecycle).
 
-## `@property` whitelist
+## `@property` allowlist
 
 The allowed set depends on **class role**:
 

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

@@ -5,7 +5,7 @@ paths:
 
 # ui/ — user interface
 
-The top layer: UI that binds the `ecs/` database to what the user sees. It
+The top layer: UI that binds the `services/main-service/` database to what the user sees. It
 owns no business logic — it subscribes to state, hands it to a pure
 presentation, and wires actions back to transactions.
 

package/.claude-plugin/plugin.json

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

package/README.md

@@ -2,7 +2,7 @@
 
 AI architecture skills + rules for building applications with
 [`@adobe/data`](https://www.npmjs.com/package/@adobe/data) — a layered,
-spec-first feature structure (`data → ecs → ui`) kept honest by conformance
+spec-first feature structure (`data → services → ui`) kept honest by conformance
 tests. Versioned in lockstep with the library: `@adobe/data-ai@x.y.z` targets
 `@adobe/data@x.y.z`.
 

package/bin/cli.mjs

@@ -50,8 +50,8 @@ function notice(extra) {
 
 The files in this folder are installed and managed by the \`${PKG_NAME}\`
 package. This entire directory is **deleted and rebuilt** on every
-\`npx ${PKG_NAME} install\`, so any local edit here is silently discarded on the
-next reinstall or version upgrade.
+\`npx ${PKG_NAME}@${VERSION} install\`, so any local edit here is silently discarded on
+the next reinstall or version upgrade.
 
 To change them, edit upstream in the \`${PKG_NAME}\` package and publish a new
 version, then reinstall — do not modify these files in place.
@@ -66,10 +66,21 @@ function writeMeta(bundleDir, noticeBody, extraMeta) {
     );
 }
 
+// Skills that author/evolve the bundle itself (the self-improvement loop and its
+// rule review). They mutate or critique the managed files, so they belong only to
+// the source repo — never a consumer install, where those files are read-only
+// managed copies. Both also carry `disable-model-invocation: true`.
+const MAINTAINER_ONLY = new Set(["meta-build", "review"]);
+
 function discoverSkills() {
     if (!existsSync(skillsSrc)) return [];
     return readdirSync(skillsSrc, { withFileTypes: true })
-        .filter((d) => d.isDirectory() && existsSync(join(skillsSrc, d.name, "SKILL.md")))
+        .filter(
+            (d) =>
+                d.isDirectory() &&
+                !MAINTAINER_ONLY.has(d.name) &&
+                existsSync(join(skillsSrc, d.name, "SKILL.md")),
+        )
         .map((d) => d.name)
         .sort();
 }
@@ -111,6 +122,41 @@ function installRules(base) {
     return bundleDir;
 }
 
+// A single managed rule (namespaced by its `adobe-data-ai-` filename prefix) telling
+// an agent to (re)install the bundle when the skills are absent — pinned to THIS
+// reviewed version, never `@latest`, so a drifted or compromised release cannot execute
+// during install. Rewritten with the matching version on every install. It sits beside
+// (not inside) the wiped bundle dir, so it survives and is simply overwritten.
+function installBootstrap(base) {
+    const file = join(base, ".claude", "rules", `${BUNDLE}-bootstrap.md`);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(
+        file,
+        `---
+paths:
+  - '**/features/*/data/**/*.ts'
+  - '**/features/*/services/**/*.ts'
+  - '**/features/*/ui/**/*.ts'
+---
+
+# ${PKG_NAME} skills — ensure installed
+
+Before using an \`@adobe/data\` build workflow, confirm the skills are present: look for
+a skill named \`build-feature\` (or \`build-application\`). If it is missing, install the
+pinned, reviewed bundle, then re-check:
+
+\`\`\`sh
+npx ${PKG_NAME}@${VERSION} install
+\`\`\`
+
+Pin the version to the reviewed bundle (never \`@latest\`) so a compromised or drifted
+release cannot execute during install. This file is regenerated with the matching
+version on every install. Package: <https://www.npmjs.com/package/${PKG_NAME}>
+`,
+    );
+    return file;
+}
+
 function parseArgs(argv) {
     const positional = [];
     const flags = new Set();
@@ -176,11 +222,13 @@ function main() {
     const base = flags.has("global") ? homedir() : dir ? resolve(dir) : process.cwd();
     const skillsDir = installSkills(base, skills);
     const rulesDir = installRules(base);
+    const bootstrapFile = installBootstrap(base);
     const ruleCount = countRules(rulesSrc);
 
     process.stdout.write(`Installed ${PKG_NAME} v${VERSION}\n`);
     process.stdout.write(`  ${skills.length} skills → ${skillsDir}\n`);
     process.stdout.write(`  ${ruleCount} rules  → ${rulesDir}\n`);
+    process.stdout.write(`  bootstrap → ${bootstrapFile}\n`);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.89",
+  "version": "0.9.91",
   "description": "Cross-agent architecture skills for @adobe/data — installable as a Claude Code plugin or copied into any Agent-Skills-compatible agent (Cursor, Codex).",
   "type": "module",
   "private": false,
@@ -29,18 +29,17 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.9.89"
+    "@adobe/data": "0.9.91"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.89"
+    "@adobe/data": "0.9.91"
   },
   "license": "MIT",
   "scripts": {
     "build": "cp ../../LICENSE .",
     "typecheck": "true",
-    "test": "vitest --run --passWithNoTests",
-    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public"
+    "test": "vitest --run --passWithNoTests"
   }
 }

package/skills/build-actions/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: build-actions
-description: Build a feature's ecs action-database — async orchestration over services and transactions. If the feature has async flows or side effects outside of the main store.
+description: Build a feature's action-database — async orchestration over services and transactions. If the feature has async flows or side effects outside of the main store.
 input: feature
 output: feature
 ---
 
 Skip if this feature doesn't contain or require actions.
 
-Create `ecs/action-database/`: `action-database.ts` (extends `ServiceDatabase`, adds `actions`
+Create `services/main-service/action-database/`: `action-database.ts` (extends `ServiceDatabase`, adds `actions`
 from `./actions/index.js`) plus an `actions/` folder — one async orchestrator per file. An action
 takes `db: ServiceDatabase`, awaits `services/` ports, then commits **exactly one** transaction.
 
-The top ecs layer; comes after `service-database`.
+The top main-service layer; comes after `service-database`.
 
-The how is in the auto-loading `features/ecs/actions.md` rule.
+The how is in the auto-loading `features/services/main-service/actions.md` rule.

package/skills/build-app-entry/SKILL.md

@@ -10,6 +10,6 @@ output: app
 - The base reaches a peer only through a lazy element wrapper (dynamic import), so peers
   load on demand.
 - The entry point creates the live database from `FeatureDatabase.plugin` (the base
-  feature's assembled database — see `features/ecs/index.md`) and mounts the root UI.
+  feature's assembled database — see `features/services/main-service/index.md`) and mounts the root UI.
 
 See `features/index.md` (one-app-many-features) for the wiring rules.

package/skills/build-computed/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: build-computed
-description: Build a feature's ecs computed-database — derived observable values.
+description: Build a feature's computed-database — derived observable values.
 input: feature
 output: feature
 ---
 
 Skip if this feature doesn't contain or require computed values.
 
-Create `ecs/computed-database/`: `computed-database.ts` (extends the previous layer, adds
+Create `services/main-service/computed-database/`: `computed-database.ts` (extends the previous layer, adds
 `computed` from `./computed/index.js`) plus a `computed/` folder — one `cached` derived value
 per file + barrel. Derivation logic lives in `data/`; a computed only wires a db observable to it.
 
 Comes after `transaction-database`.
 
-The how is in the auto-loading `features/ecs/computed.md` rule.
+The how is in the auto-loading `features/services/main-service/computed.md` rule.

package/skills/build-core-database/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: build-core-database
-description: Build a feature's ecs schema — the core-database (components, resources, archetypes). The first ecs layer.
+description: Build a feature's schema — the core-database (components, resources, archetypes). The first main-service layer.
 input: feature
 output: feature
 ---
 
-Create `ecs/core-database/` — `core-database.ts` plus one single-export file per facet
+Create `services/main-service/core-database/` — `core-database.ts` plus one single-export file per facet
 the feature actually uses (`components`, `resources`, `archetypes` are each optional on
 `Database.Plugin.create`). Create only the facet files you need; omit the rest rather than
 shipping empty `Database.components({})` boilerplate. A feature with **no entities** (a
@@ -20,5 +20,5 @@ The schema root; comes after `data/` (and `services/`). Bind each schema from it
 type — don't author shapes here. Components use JSON schemas; resources use the
 `{ default }` convention (a schemaless aggregate binds via `{ default: State.create() }`).
 
-The how is in the auto-loading `features/ecs/index.md` + `components.md` / `resources.md` /
+The how is in the auto-loading `features/services/main-service/index.md` + `components.md` / `resources.md` /
 `archetypes.md` rules.

package/skills/build-data/SKILL.md

@@ -19,4 +19,4 @@ The schema is the single source of truth; the type derives from it (`Schema.ToTy
 Helpers are pure and unit-tested. Run this first — every other layer imports `data/`.
 
 The how is in the auto-loading rules: `features/data/index.md`, `features/data/state.md`, and
-`namespace.md`.
+`global/namespace.md`.

package/skills/build-game/SKILL.md

@@ -16,6 +16,6 @@ transactions = moves/spawns, computed = score/status/winner, ui = view + input.
 - **Real-time** adds the `build-systems` phase: a per-frame tick loop (movement,
   collision, lifetime) driven by the scheduler, over many entities in distinct
   archetypes. Systems must stay O(1) per touched entity — never project the whole
-  `State` into/out of the store each frame (see `features/ecs/systems.md`).
+  `State` into/out of the store each frame (see `features/services/main-service/systems.md`).
   This is where components, archetypes, indexes, and systems all carry real
   weight.

package/skills/build-indexes/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: build-indexes
-description: Build a feature's ecs index-database — component/archetype indexes for O(1) lookup. As needed.
+description: Build a feature's index-database — component/archetype indexes for O(1) lookup. As needed.
 input: feature
 output: feature
 ---
 
 Skip if this feature doesn't contain or require indexes.
 
-Create `ecs/index-database/`: `index-database.ts` (extends `CoreDatabase`, adds the `indexes`
+Create `services/main-service/index-database/`: `index-database.ts` (extends `CoreDatabase`, adds the `indexes`
 facet from `./indexes/index.js`) plus an `indexes/` folder — one index per file + an `index.ts`
 barrel.
 
 Only if the feature needs indexed lookups. Comes after `core-database`.
 
-The how is in the auto-loading `features/ecs/indexes.md` rule.
+The how is in the auto-loading `features/services/main-service/indexes.md` rule.

package/skills/build-service-database/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: build-service-database
-description: Build a feature's ecs service-database — db-bound service factories. If the feature exposes services.
+description: Build a feature's service-database — db-bound service factories. If the feature exposes services.
 input: feature
 output: feature
 ---
 
-Create `ecs/service-database/`: `service-database.ts` (extends the previous layer, registers the
+Create `services/main-service/service-database/`: `service-database.ts` (extends the previous layer, registers the
 `services` facet). Two forms:
 
 - db-bound factories `create<Name>Service(db, …)` in `service-database/services/` (one per file + barrel), for services that read `db.observe.*` / call `db.transactions.*`; or
@@ -13,4 +13,4 @@ Create `ecs/service-database/`: `service-database.ts` (extends the previous laye
 
 Comes after `computed-database`.
 
-The how is in the auto-loading `features/ecs/services.md` rule.
+The how is in the auto-loading `features/services/main-service/services.md` rule.

package/skills/build-services/SKILL.md

@@ -11,6 +11,6 @@ Create the feature's `services/` layer: one `<name>-service/` namespace folder p
 contract — an `interface` (validated with `AsyncDataService.IsValid`), async-only members,
 and `create*` factories.
 
-Only if the feature talks to the outside world. Comes after `data/`, before `ecs/`.
+Only if the feature talks to the outside world. Comes after `data/`, before `services/main-service/`.
 
-The how is in the auto-loading `features/services/index.md` rule (and `namespace.md`).
+The how is in the auto-loading `features/services/index.md` rule (and `global/namespace.md`).

package/skills/build-systems/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-systems
-description: Build a feature's ecs system-database — the real-time tick loop (systems the scheduler runs each frame). For real-time features only.
+description: Build a feature's system-database — the real-time tick loop (systems the scheduler runs each frame). For real-time features only.
 input: feature
 output: feature
 ---
@@ -8,9 +8,12 @@ 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.
 
-Create `ecs/system-database/system-database.ts`: `Database.Plugin.create({ extends:
-Database.Plugin.combine(ComputedDatabase.plugin, scheduler), systems })` where the `systems`
-map is declared **inline** (see `features/ecs/systems.md` — inline is required for `db` to be
+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 `FeatureDatabase`. 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).
 
@@ -21,4 +24,4 @@ per-frame body helpers).
   combining `scheduler` (rAF), gated by the `schedulerState` resource.
 
 **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/ecs/systems.md` rule.
+Comes after `build-computed`. The how is in the auto-loading `features/services/main-service/systems.md` rule.

package/skills/build-transactions/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: build-transactions
-description: Build a feature's ecs transaction-database — atomic mutations over the store.
+description: Build a feature's transaction-database — atomic mutations over the store.
 input: feature
 output: feature
 ---
 
-Create `ecs/transaction-database/`: `transaction-database.ts` (extends `IndexDatabase`, adds
+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).
 
 Comes after `index-database` (or `core-database` if no indexes).
 
-The how is in the auto-loading `features/ecs/transactions.md` rule.
+The how is in the auto-loading `features/services/main-service/transactions.md` rule.

package/skills/build-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-ui
-description: Build a feature's ui/ layer — presentation bound to the ecs database. The final, top layer.
+description: Build a feature's ui/ layer — presentation bound to the main-service database. The final, top layer.
 input: feature
 output: feature
 ---

package/skills/meta-build/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: meta-build
+disable-model-invocation: true
 description: Iteratively build an application or game phase-by-phase in clean subagents, reviewing each phase and refining the build-* skills / rules until each is optimal, then summarizing.
 input: a prompt describing the application or game to build
 options:

package/skills/review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: review
+disable-model-invocation: true
 description: Review built feature/application output against the @adobe/data feature rules; report whether it is optimal and where any fix belongs. Read-only.
 input: a path to built output (a layer, a feature, or a whole app)
 output: a review — OPTIMAL, or a list of issues each tagged code | skill | rule