@adobe/data-ai 0.9.90 → 0.9.92

package/.claude/rules/README.md

@@ -13,6 +13,8 @@ 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 → services → data)
   data/
@@ -28,12 +30,15 @@ features/
   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

package/.claude/rules/data-modelling.md

@@ -15,9 +15,10 @@ discriminated unions.
 ## Example
 
 ```ts
-// types/http-method/schema.ts
-export const schema = { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] }
-    as const satisfies Schema;
+// types/http-method/http-method.ts — the hand-authored type owns the member identity
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+// (a schema.ts, if/when a runtime boundary needs one, is written to match this
+//  type and pinned to it — see global/namespace.md and features/data/index.md)
 
 // In an unrelated request-counter plugin:
 

package/.claude/rules/ecs.md

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

package/.claude/rules/element.md

@@ -125,7 +125,7 @@ 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/services/main-service/index.md`): `typeof
-FeatureDatabase.plugin` for a self-contained feature. **Exception:** an element
+MainService.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
 minimal base layer it consumes (e.g. `ComputedDatabase.plugin`) so every

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

@@ -11,24 +11,63 @@ 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
-its schema, its derived type, and its pure synchronous helpers together:
+Each data type is its own namespace folder (see `global/namespace.md`), holding
+its hand-authored type, its (optional, matching) schema, and its pure
+synchronous helpers together:
 
 ```
 data/player-mark/
-  player-mark.ts   # type alias + `export * as PlayerMark from "./public.js"`
-  schema.ts        # `export const schema = { … } as const satisfies Schema`
+  player-mark.ts   # HAND-AUTHORED type + `export * as PlayerMark from "./public.js"`
+  schema.ts        # (optional / later) schema matching the type, pinned via Assert<Equal<…>>
   public.ts        # re-exports schema + helpers
   is.ts  values.ts  opponent.ts  …   # one pure helper per file
 ```
 
-- The **type is derived from the schema** (`Schema.ToType<typeof schema>`),
-  never hand-written alongside it.
-- The **schema is the single source of truth** for the shape; the derived
-  type and every consumer flow from it.
+- The **type is authored by hand** in `<type>.ts` — the readable source of
+  truth. Write it with the richest types available (`F32`, `Vec3`, unions,
+  branded aliases) so members carry their semantic meaning and get strong
+  IntelliSense / hover docs.
+- The **schema is derived from the type, not the reverse.** It is written to
+  match the type and **pinned** to it with a compile-time assertion so the two
+  cannot drift (see below). A field typed as a branded primitive reuses that
+  type's schema — `F32` → `F32.schema`, `Vec3` → `Vec3.schema`.
+- **Schemas are optional until a runtime boundary needs one.** A pure `data/`
+  type is complete with `<type>.ts` alone. The schema is added only when
+  persistence, the wire, or an ECS component/resource requires it — and is
+  typically written by the agent in a later phase (e.g. when implementing the
+  ECS), not by the human up front.
 - Helpers are synchronous and pure; each has a sibling `*.test.ts`.
-- Objects with only numeric 32 bit values/sub-structs should use Schema.fromStructProperties
-  It guarantees a valid struct schema which will be stored in linear memory.
+- Objects of only 32-bit numeric values / sub-structs: the schema uses
+  `Schema.fromStructProperties` (guarantees a valid struct schema, stored in
+  linear memory).
+
+## Pinning the schema to the type
+
+The type is written first and by hand; the schema is written to match it and
+is locked to it at compile time, so schema authoring (whenever it happens)
+cannot silently drift from the type readers rely on.
+
+```ts
+// player-mark/player-mark.ts — HAND-AUTHORED, the source of truth
+export type PlayerMark = 'X' | 'O';
+export * as PlayerMark from './public.js';
+
+// player-mark/schema.ts — written to MATCH the type (often later, by the agent)
+import { Schema } from '@adobe/data/schema';
+import type { Assert, Equal } from '@adobe/data/types';
+import type { PlayerMark } from './player-mark.js';
+
+export const schema = { type: 'string', enum: ['X', 'O'] } as const satisfies Schema;
+
+// Compile-time pin: fails to build if schema and type diverge.
+type _Pin = Assert<Equal<Schema.ToType<typeof schema>, PlayerMark>>;
+```
+
+The `Assert<Equal<…>>` line is the whole safety net: `Schema.ToType<typeof
+schema>` must be exactly the hand-authored type (including readonly/optional),
+or the file does not compile. `Schema.ToType` is used **only** inside the
+assertion — never as the exported type. Consumers always import the
+hand-authored `PlayerMark`.
 
 One folder is special: **`data/state/`** holds the feature's single `State`
 aggregate and its pure transforms/derivations (its own rule, `state.md`);

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

@@ -41,13 +41,16 @@ export * as State from "./public.js";
 - Guard and **return `state` unchanged** on a no-op / illegal input rather
   than throwing — this keeps transforms idempotent under repeated application.
 - 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 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.
+  correctness is everything. The test file **exports** its cases —
+  `export const cases: ConformanceCase<Args>[]` (the shared `conformance-case.ts`
+  type) — right alongside the `describe`/`it` that exercise them. This is
+  spec-owned truth the matching main-service conformance test imports **from the
+  `<transform>.test.js` file** unchanged (see `services/main-service/conformance.md`).
+  Keeping the cases in the test file rather than a separate `<transform>.cases.ts`
+  removes a file per transform — less folder clutter, same reuse. 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`.
 
 ## Derivations — `(state) => value`
 

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

@@ -88,7 +88,7 @@ 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 `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
+cases are spec-owned (exported from `data/state/<transform>.test.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.
@@ -106,6 +106,7 @@ current examples of this structure. `data-lit-todo` is the most complete
 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/`.
-Cross-cutting patterns live at the rules root — `namespace.md`,
-`data-modelling.md`, `archetypes.md` (row iteration), `type-casts.md`,
-`cohesion.md`.
+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

@@ -22,7 +22,7 @@ its own subtree.
 
 ## Capability contracts
 
-Each is a namespace folder (`namespace.md`); the export and folder both carry the
+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`).

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

@@ -13,19 +13,19 @@ timing — and then commit the result through a transaction.
 ```ts
 import type { ServiceDatabase } from "../../service-database/service-database.js";
 
-export const addRandomTodo = async (db: ServiceDatabase) => {
-    const name = await db.services.nameGenerator.generateName(); // await a services/ port
-    db.transactions.createTodo({ name });                        // then exactly one commit
+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 `db` parameter on the lowest database layer exposing what the
+- 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. `db.services.*` calls are `void` or
+  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.

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

@@ -7,7 +7,7 @@ paths:
 
 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 db
+Derivation logic itself lives in `data/`; a computed only wires a service
 observable to it.
 
 ```ts
@@ -16,8 +16,8 @@ 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((db: IndexDatabase) =>
-    Observe.withFilter(db.observe.resources.board, BoardState.deriveStatus),
+export const status = cached((service: IndexDatabase) =>
+    Observe.withFilter(service.observe.resources.board, BoardState.deriveStatus),
 );
 ```
 

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

@@ -29,8 +29,9 @@ Conformance test-support splits by concern along the layer boundary:
     `fromState(before)` → `apply(store, args)` → `toState ≡ after`.
 - **Spec-side, in `data/state/`** (State values, no store — so both the `data/`
   transform tests and this runner import them without a layer violation):
-  `conformance-case.ts` (`ConformanceCase<Args>`), the `<transform>.cases.ts`
-  cases, and `expect-state-matches.ts` (State equality).
+  `conformance-case.ts` (`ConformanceCase<Args>`), the cases **exported from each
+  `<transform>.test.ts`** (`import { cases } from "…/<transform>.test.js"` — no
+  separate `.cases.ts` file), and `expect-state-matches.ts` (State equality).
 
 ## No cast — build on `Store.create`, not a `Database`
 
@@ -39,7 +40,7 @@ A **transaction is `(store, args) => void`**, so transaction conformance needs n
 `CoreDatabase.Store` — pass the plugin directly, `Store.create` reads its schema
 facets. Source it from the **lowest layer that declares all the schema** —
 `IndexDatabase`, or `CoreDatabase` if the feature has no indexes — **not**
-`FeatureDatabase`: the store needs only schema, and the behaviour layers
+`MainService`: the store needs only schema, and the behaviour layers
 (transactions / computed / systems) add none.
 `fromState`/`toState`/`apply` all operate on it, and `apply` calls the **raw
 transaction function** directly:

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

@@ -119,26 +119,29 @@ export namespace IndexDatabase {
 }
 ```
 
-### The assembled database — `FeatureDatabase`
+### The assembled database — `MainService`
 
 *Which* layer is topmost varies with the facets a feature uses (computed /
 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:
+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/feature-database.ts
-export { SystemDatabase as FeatureDatabase } from "./system-database/system-database.js";
+// services/main-service/main-service.ts
+export { SystemDatabase as MainService } from "./system-database/system-database.js";
 ```
 
-Every consumer references **`FeatureDatabase`** (`.plugin`, `.Store`) — never the
+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` / `FeatureDatabase`. When *another* feature or package
+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>Database`, re-exported so from the feature's barrel
+/ `<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.
 
@@ -153,9 +156,10 @@ two features' `CoreDatabase`s never collide.
   reads/writes entities, resources, or archetypes; **`IndexDatabase.Store`** the
   moment it reads an index.
 - **the whole `Database`** — **computed**, **services**, and **actions** each
-  take `db: <Layer>` (the lowest layer whose database exposes what they
-  read/call): computed reads `db.observe.*`; services read observables and call
-  transactions; actions call `db.services.*` then `db.transactions.*`.
+  take `service: <Layer>` (the lowest layer whose database exposes what they
+  read/call): computed reads `service.observe.*`; services read observables and
+  call transactions; 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`.

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

@@ -5,20 +5,21 @@ paths:
 
 # database/services/ — database-bound service factories
 
-One factory per file: `create<Name>Service(db, …)` that binds a service
+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 = (db: ComputedDatabase, mark: PlayerMark): AgenticService =>
-    /* … reads db.observe.*, calls db.transactions.* … */;
+export const createAgentService = (service: ComputedDatabase, mark: PlayerMark): AgenticService =>
+    /* … reads service.observe.*, calls service.transactions.* … */;
 ```
 
-Type `db` on the lowest layer exposing what the factory reads/calls (never the
-`service-database` itself — that would be a cycle).
+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 (`db.services.agent`). Defining a standalone service
-contract (not yet bound to a db) belongs in the feature `services/` layer.
+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/systems.md

@@ -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,8 +121,10 @@ with no rAF and no rendering attached.
 
 ## Layer
 
-`system-database.ts` extends the previous main-service 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

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

@@ -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,15 +32,15 @@ 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 })`.
 
 No other members. No `@state`. No private handler fields. No lifecycle methods (`connectedCallback`, `updated`, `firstUpdated`,
 `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).
+(see `hooks.md` for hook-first lifecycle).
 
-## `@property` whitelist
+## `@property` allowlist
 
 The allowed set depends on **class role**:
 
@@ -114,7 +114,7 @@ one-liners** above.
 ## Lifecycle goes through hooks
 
 Any need for mount/unmount/update behavior routes through a hook. **Reuse order, one hook per file, presentation vs binding placement, and
-testing notes:** `.claude/rules/hooks.md`.
+testing notes:** `hooks.md`.
 
 Never inline lifecycle logic in the binding. App-entrypoint classes may override lifecycle methods when the concern is app-boot shaped
 (service wiring, ancestor lookup); even then, prefer a hook.
@@ -158,14 +158,14 @@ expose them by design; reaching for them means a missing computed.
 
 A binding element imports a sibling `*-presentation.ts` file that exports exactly `render` (required) and optionally `unlocalized`. Nothing
 else — no types, no styles, no helpers. Consumers derive the props type via `Parameters<typeof render>[0]`. Presentation stays hook-free by
-default; element hooks live here or in shared modules per `.claude/rules/hooks.md` and `.claude/rules/presentation.md`.
+default; element hooks live here or in shared modules per `hooks.md` and `features/ui/presentation.md`.
 
 **For refactors whose stated scope does not include presentations**, the matching `*-presentation.ts` file must not change. Verify with
 `git diff --name-only | grep presentation`. If a scope-limited refactor requires a presentation signature change, stop and reconsider the
 binding-side helper — the scope fence exists because presentations are the public contract between binding and render output.
 
 Callback prop names use **verb** or **verbNoun** form. Never `on*` prefix. The binding-side variable matches the presentation prop name 1:1.
-See `.claude/rules/presentation.md` for full examples.
+See `features/ui/presentation.md` for full examples.
 
 ## Size budget
 

package/.claude/rules/{namespace.md → global/namespace.md}

@@ -32,8 +32,10 @@ patterns (e.g., inline `export namespace` in shared files) that do not conform
 - `<type-name>/<type-name>.ts` is the only public import surface
 - Export a single type alias: `export type <type-name> = <type>` (or `export type * from "./<type-name>-types.js"` when the type lives in a
   separate file)
-- Schema-based types: schema in `<type-name>-schema.ts`, named `schema` (not `<type-name>Schema`), derive with
-  `Schema.ToType<typeof schema>`
+- The type alias is **hand-authored** in `<type-name>.ts`. When a schema is needed it lives in `<type-name>-schema.ts` (or
+  `schema.ts` inside the folder), named `schema` (not `<type-name>Schema`), and is **written to match the hand-authored type and pinned
+  to it** with `Assert<Equal<Schema.ToType<typeof schema>, <TypeName>>>` — never the other way around. `Schema.ToType` appears only in
+  that assertion, never as the exported type.
 - Export namespace: `export * as <type-name> from "./public.js"`
 - In public.ts, re-export every public constant file
 - Filenames map deterministically to single export:
@@ -43,6 +45,26 @@ patterns (e.g., inline `export namespace` in shared files) that do not conform
 - Function files: name by purpose only (e.g., `add.ts`, `sub.ts`). **Do not prefix** with the type name — the folder provides the namespace
   context.
 
+## Constants file
+
+Constants are the **one exception** to one-declaration-per-file. A namespace folder MAY have a single `constants.ts` exporting several
+plain `const` literals (no functions, no types), re-exported through `public.ts` so callers reach them as `<TypeName>.<constant>`:
+
+```ts
+// duration/constants.ts
+export const minSeconds = 5;
+export const maxSeconds = 300;
+export const defaultSeconds = 30;
+
+// duration/public.ts
+export * from './constants.js';
+
+// consumers: Duration.minSeconds, Duration.maxSeconds, Duration.defaultSeconds
+```
+
+Function declarations remain **one per file** (each in its own purpose-named file). If a value needs logic rather than being a plain
+literal, it is a function and does not belong in `constants.ts`.
+
 ## Anti-patterns (do not copy)
 
 - **`export namespace <TypeName> { ... }`** — Use `export * as <TypeName> from "./public.js"` instead.
@@ -63,18 +85,24 @@ patterns (e.g., inline `export namespace` in shared files) that do not conform
 
 ## Schema pattern example
 
+The type is authored first and by hand; the schema (if/when needed) is written
+to match it and pinned so it cannot drift.
+
 ```ts
-// src/types/player-mark/player-mark-schema.ts
-export const schema = { enum: ['X', 'O'] } as const;
+// src/types/player-mark/player-mark.ts — HAND-AUTHORED, the source of truth
+export type PlayerMark = 'X' | 'O';
+export * as PlayerMark from './public.js';
+
+// src/types/player-mark/player-mark-schema.ts — written to MATCH the type
+import { Schema } from '@adobe/data/schema';
+import type { Assert, Equal } from '@adobe/data/types';
+import type { PlayerMark } from './player-mark.js';
+export const schema = { type: 'string', enum: ['X', 'O'] } as const satisfies Schema;
+// Compile-time pin: fails to build if schema and type diverge.
+type _Pin = Assert<Equal<Schema.ToType<typeof schema>, PlayerMark>>;
 
 // src/types/player-mark/public.ts
 export { schema } from './player-mark-schema.js';
-
-// src/types/player-mark/player-mark.ts
-import { Schema } from '@adobe/data/schema';
-import { schema } from './player-mark-schema.js';
-export type PlayerMark = Schema.ToType<typeof schema>;
-export * as PlayerMark from './public.js';
 ```
 
 ## Example: `Point` type refactor

package/.claude/rules/{react.md → global/react.md}

@@ -76,7 +76,7 @@ use `Parameters<typeof render>[0]`.
 
 ## Action callbacks (not events)
 
-Use **verb** or **verbNoun** names — never `on*` prefix. See `.claude/rules/presentation.md` for full examples.
+Use **verb** or **verbNoun** names — never `on*` prefix. See `features/ui/presentation.md` for full examples.
 
 **Pass function references directly** when the signature matches; wrap in an arrow function only to supply arguments:
 

package/.claude/rules/lit.md

@@ -76,7 +76,7 @@ there.
 
 ## Action callbacks (not events)
 
-Use **verb** or **verbNoun** names — never `on*` prefix. See `.claude/rules/presentation.md` for full examples and rationale.
+Use **verb** or **verbNoun** names — never `on*` prefix. See `features/ui/presentation.md` for full examples and rationale.
 
 ---
 
@@ -91,7 +91,7 @@ view hosts. Multiple instances of the same element need a property to identify w
 
 ## Hooks
 
-Canonical rules (reuse order, one hook per file, binding vs presentation): `.claude/rules/hooks.md`.
+Canonical rules (reuse order, one hook per file, binding vs presentation): `hooks.md`.
 
 Use hooks from `src/elements/hooks/` and `@adobe/data-lit` instead of `connectedCallback`/`disconnectedCallback`. Use `useEffect` for
 setup/teardown, `useKeyboardEvent` for single key events.
@@ -107,7 +107,7 @@ When creating or modifying a Lit element:
 3. Use a single `useObservableValues` in the binding element. Observe only minimal values; use `Observe.withDefault` for slow-resolving
    values.
 4. Pass observed values and action callbacks to presentation.
-5. Keep presentation pure — no hooks (see `.claude/rules/hooks.md` for exceptions).
+5. Keep presentation pure — no hooks (see `hooks.md` for exceptions).
 6. Add `@property` only when entity binding requires it (multiple instances).
 7. Presentation exports only `render` (and localization bundles where appropriate). Binding element sets `static styles` from `*.css.ts`.
 8. Add `*-presentation.test.ts` for presentation when appropriate; do not unit test binding elements.

package/.claude/rules/observe.md

@@ -147,7 +147,7 @@ Observe.withMap(rows$, rows => rows.filter(r => r.selectedByUsers?.includes(user
 `observeSelectDeep` re-emits on **any** change to **any** listed component on **any** matched entity — so list only the fields actually
 read, and when the matched set is large pair it with a structural deduplicate downstream so identical-looking emissions don't propagate
 (`@adobe/data/observe`'s `withDeduplicate` is reference-equality only). `observeSelectDeep` from a UI element is banned — let each element
-observe its own entity (see `.claude/rules/ecs.md` and `.claude/rules/squirrel/ui-data-access.md`).
+observe its own entity (see `ecs.md`).
 
 ---
 

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adobe-data-ai",
-  "version": "0.9.90",
+  "version": "0.9.92",
   "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.90",
+  "version": "0.9.92",
   "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,12 +29,12 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.9.90"
+    "@adobe/data": "0.9.92"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.90"
+    "@adobe/data": "0.9.92"
   },
   "license": "MIT",
   "scripts": {

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

@@ -9,7 +9,7 @@ output: app
   plugin, so all schemas coexist, persist, and sync while the base type stays decoupled.
 - 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
+- The entry point creates the live database from `MainService.plugin` (the base
   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-data/SKILL.md

@@ -8,15 +8,15 @@ output: feature
 Create the feature's `data/` layer (pure spec; depends on nothing but `@adobe/data`
 and other `data/` declarations):
 
-- one namespace folder per data type — `<type>/{<type>.ts, schema.ts, public.ts, <helper>.ts}`;
+- one namespace folder per data type — `<type>/{<type>.ts, public.ts, <helper>.ts}` (+ `schema.ts` only when a runtime boundary needs it);
 - `data/state/` — the `State` aggregate plus its pure transforms/derivations.
 
 **Always create `data/state/`** — even for a shell feature whose only field is a
 boolean or enum. A feature with ECS resources/transactions but no `State` is
 incomplete: the transaction must wrap a pure transform, not invent the logic. In rare circumstances, there may be no real state in a feature in which case the state type = {}
 
-The schema is the single source of truth; the type derives from it (`Schema.ToType`).
+The hand-authored type in `<type>.ts` is the source of truth. The schema is optional up front — add `schema.ts` only when a runtime boundary (persistence, wire, or an ECS component/resource) needs one, write it to match the type, and pin it with `type _Pin = Assert<Equal<Schema.ToType<typeof schema>, <Type>>>` so it cannot drift. `Schema.ToType` is used only in that assertion, never as the exported type.
 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-services/SKILL.md

@@ -13,4 +13,4 @@ and `create*` factories.
 
 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

@@ -9,7 +9,10 @@ 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 `services/main-service/system-database/system-database.ts`: `Database.Plugin.create({ extends:
-Database.Plugin.combine(ComputedDatabase.plugin, scheduler), systems })` where the `systems`
+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).

package/skills/build-transactions/SKILL.md

@@ -5,7 +5,8 @@ input: feature
 output: feature
 ---
 
-Create `services/main-service/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).

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