@adobe/data-ai 0.9.91 → 0.9.93

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

@@ -3,69 +3,216 @@ paths:
   - '**/features/*/services/main-service/**/conformance/**/*.ts'
 ---
 
-# 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
-enters the runtime bundle (test-support may import the test framework — it is not
-a runtime declaration). **Never call `fromState` / `toState` (or a shared
-clear-all + reinsert helper used only for that projection) from systems,
-transactions, or UI** — that is a full-store rewrite, not an O(1) ECS update.
-**Feature-level**: one projection per feature, reused by every transaction test
-and the system tick-loop test — don't nest it under `transaction-database/`.
-
-The property, per `{ before, args, after }` case:
-`toState(apply(fromState(before), args)) ≡ spec(before, args)`.
-
-Conformance test-support splits by concern along the layer boundary:
-
-- **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
-    its full named-archetype component set, so the shapes never alias.
-  - `expect-conforms.ts` → **one export, `expectConforms({ cases, spec, apply })`**.
-    Per case it asserts `spec(before, args) ≡ after` (keeps the case honest), then
-    `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).
-
-## No cast — build on `Store.create`, not a `Database`
-
-A **transaction is `(store, args) => void`**, so transaction conformance needs no
-`Database`: `Store.create(<schema-layer>.plugin)` returns a cast-free writable
-`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
-(transactions / computed / systems) add none.
-`fromState`/`toState`/`apply` all operate on it, and `apply` calls the **raw
-transaction function** directly:
+# services/main-service/conformance/ — keeping the ECS honest against the spec
+
+Test-only (imported only by `*.test.ts`, in no facet barrel). The `data/state`
+cases are the shared truth; the shared **`@adobe/data/testing`** runner replays
+them against the ECS. This folder holds only the *feature-specific projection*
+(`projection.ts`) plus one `conformance.test.ts` that makes a **single**
+`Conformance.runFeature({...})` call. Reference: `data-lit-tictactoe`'s
+`conformance/` (the zero-config example) and `data-lit-todo` (entity markers +
+`hydrate`); `data-lit-space-rock-game` for the entity-bag / real-time variant.
+
+**The projection helpers — `fromState`, `toState`, and the
+`toData(store, entity)` reader — are strictly for conformance tests and MUST
+NEVER run in production code, ever.** `fromState`/`toState` rewrite the whole
+store out-of-band; runtime code reads through observables/indexes and writes
+through transactions. (This conformance `toData(store, entity)` reader is
+unrelated to the library's `db.toData()` store-serialization method, which *is*
+a normal runtime API — the collision is only in the name.) Likewise
+`Match.matches` / `Match.assert` are comparison helpers for `*.test.ts` only —
+never a runtime branch.
+
+## What `@adobe/data/testing` gives you
+
+Two namespaces, imported only from `*.test.ts` (the module is
+`sideEffects: false`, and `vitest` is an optional peer dependency, satisfied
+here):
+
+- **`Match`** — the tolerant, matcher-aware value comparison: `matches(actual,
+  expected, options?)` and its throwing wrapper `assert(...)`, plus the matchers
+  `Match.anyNumber` / `Match.anyString` / `Match.ref(label)`. Options are
+  `{ unordered?: ReadonlySet<string>; tolerance?: number }` — arrays compare **in
+  order** (default) unless a key is named in `unordered`, and numbers snap to
+  `tolerance` (default `0.01`) to absorb F32↔f64 / trig noise. Framework-agnostic:
+  it honors any asymmetric matcher, so vitest's `expect.any(...)` interops.
+- **`Conformance`** — the case types (`Case`, `Cases`, `DerivationCase`,
+  `DerivationCases`, `Effects`, `ServiceCall`), the `entity(specId)` identity
+  marker, the id `resolver(map)`, the whole-feature driver **`runFeature`**, the
+  pure-spec driver **`runSpec`**, and the lower-level per-surface drivers
+  `runTransactions` / `runActions` / `runComputeds` (internals of `runFeature`,
+  exported for the escape hatch below). Auto-pairing (transition ⇄ op by name),
+  effect recording, and id resolution are built **into** the drivers — no
+  per-feature helper writes them. The `Effects` type-test also lives here (once),
+  so there is no per-feature `conformance-case.type-test.ts` to author.
+
+## Projection (store ⇄ State) — the one per-feature piece
+
+`projection.ts` is the only feature-specific file, and it is a **single
+aggregated export** — the three test-only helpers in one file, one `export`:
+
+```ts
+// conformance/projection.ts
+export const projection = { fromState, toState, toData };
+```
+
+- `fromState(store, state)` seeds a store to a `State` (clear tail→head, insert
+  entities, set resources). It **returns the `id → entity` map**
+  (`ReadonlyMap<Id, Entity>`) it built while seeding — the ECS assigns ids from
+  its own id-space, so the runner turns this map into a `resolve` via
+  `Conformance.resolver`; **no feature writes id resolution by hand**. A feature
+  whose transactions are index-addressed or singleton returns `void`, and any id
+  then resolves 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; the runner reuses it to hydrate id-list
+  computed outputs. **Present only when the feature has entities** (omit for a
+  scalar / resource-only feature).
+
+This replaces the old separate `create-store.ts` / `from-state.ts` /
+`to-state.ts` / `to-data.ts`. **`create-store` is gone** — `runFeature` builds
+every store/db itself with `Store.create(plugin)` / `Database.create(plugin)`.
+
+## ECS conformance is ONE call — `Conformance.runFeature`
+
+`conformance/conformance.test.ts` is a single call that conforms the whole
+feature — transaction + action + computed conformance **plus** the projection
+round-trip. No per-surface test file, no `define` callback, no `conforms(...)`
+adapters, no coverage guard.
+
+```ts
+import { State } from "../../../data/state/state.js";
+import { transitions } from "../../../data/state/transitions.js";
+
+Conformance.runFeature({
+  state: State,
+  transitions,
+  plugin: MainService.plugin,
+  computedPlugin: ComputedDatabase.plugin,   // omit if no state/ derivations
+  projection,
+  hydrate: ["visibleTodos"],                 // entity-id-list computeds; omit if none
+  match: { unordered: new Set(["bullets", "asteroids"]) }, // entity bags / tolerance; omit if none
+  ops: { actions: import.meta.glob([...]) }, // ONLY when ops aren't in the plugin facet
+});
+```
+
+- **`state`** is the `State` namespace itself — the runner calls `State.create()`
+  for the default each case's `before` deltas over, and round-trips `State.samples`
+  through the projection.
+- **`transitions`** is imported from the feature's test-only
+  `data/state/transitions.ts` (the single `import.meta.glob` of the `{ fn, cases }`
+  source, shared with `spec.test.ts` — see `data/state.md`). Never re-glob it here.
+- **Ops come off the plugin facets.** The runner reads
+  `plugin.transactions` / `plugin.actions` / `computedPlugin.computed` and builds
+  the stores/dbs itself (`Store.create(plugin)` for transactions,
+  `Database.create(plugin)` for actions, `Database.create(computedPlugin)` for
+  computeds). Each op pairs to its **same-named** transition/derivation; auto-pairing
+  can't forget an item, so there is **no coverage guard** — an op with **no
+  same-named transition** is infrastructure or system-dispatched and is simply
+  **skipped** (a streaming action with no transition is skipped too).
+- **`ops`** overrides the facet-discovered ops per surface — use it **only** when
+  an op isn't registered in the plugin facet: a per-transition action kept out of
+  the facet (to bound the plugin's type) is discovered via an
+  `ops.actions: import.meta.glob([".../actions/*.ts", "!.../actions/index.ts"], { eager: true })`
+  glob (p2p negotiation). Ordinary features omit `ops` entirely.
+- **`computedPlugin`** is the `ComputedDatabase` **layer** plugin — build computed
+  conformance from this layer, **not** the assembled `MainService`: a behaviour
+  layer above may `withCache` a pre-seed value that a direct `fromState` seed emits
+  no transaction to invalidate; the computed layer keeps the seed authoritative.
+  Omit it when the feature has no `state/` derivations (a computed with no
+  derivation is skipped anyway, and single-`data/<type>` math is covered by that
+  helper's own test).
+- **`hydrate`** names the computeds that emit an **entity-id list** (todo's
+  `visibleTodos`) so the runner maps each id through `toData` into the value shape
+  the derivation yields. Comparison is identity otherwise. Omit if none.
+- **`match`** threads `MatchOptions` through every comparison (see below). Omit if
+  none.
+- **Projection round-trip.** When `State.samples` is non-empty, the runner adds a
+  `toState ∘ fromState ≡ identity` test per sample — proving the pair round-trips
+  faithfully so a symmetric bug in `fromState`/`toState` can't cancel out and mask
+  a real ECS defect. No separate `projection.test.ts`.
+
+`data-lit-tictactoe` is the zero-config call (no `computedPlugin`, no `hydrate`,
+no `match`, no `ops` — moves are board-index addressed, so no `entity()`
+markers). `data-lit-todo` adds `hydrate: ["visibleTodos"]` and `entity()` markers.
+`data-lit-space-rock-game` adds `match: { unordered: … }` for its entity bags
+(its per-frame transitions are conformed by the systems tick loop, not here — see
+`systems.md`).
+
+## The pure spec — `data/state/spec.test.ts`
+
+Lives in `data/state/`, not here. One call, importing the same `transitions`:
 
 ```ts
-expectConforms({ cases, spec: State.hitTarget, apply: (store, args) => hitTarget(store, args) });
+import { State } from "./state.js";
+import { transitions } from "./transitions.js";
+
+Conformance.runSpec({ state: State, transitions });
 ```
 
-A mutation addressed by **entity id** resolves its entities from the seeded store
-inside `apply` (the shared cases stay spec-shaped). Reads never need a cast —
-`Database extends ReadonlyStore`.
-
-**Systems** are the one exception: they run via `db.system.functions` and reach
-the store through the db. Get that writable view with the library lens —
-`Database.toSystemDatabase(Database.create(plugin))` (the widening twin of
-`UIService.restrict`, cast-free) — then `fromState(db.store, before)` → drive one
-frame → `toState(db.store)`. Test **selection/detection** logic (which entities
-interact) separately, with seeded edge-case geometries.
-
-## State equality — ordering vs precision, kept separate
-
-`expect-state-matches.ts` compares with **`equalsUnordered`** from `@adobe/data`
-(arrays as multisets — archetype hole-fill reorders rows — objects key-order
-independent). Absorb float noise — F32↔f64 storage rounding **and** trig epsilon
-(a quadrant `cos`/`sin` yields ~3e-15 where a case authors `0`) — by quantizing
-every number on both sides onto a small grid (`Math.round(Math.fround(n)*k)/k`)
-before comparing. Ordering and precision stay separate concerns. **Guard the
-projection itself** with one `fromState → toState` identity test on
-representative states.
+It discovers every file exporting `cases`, enforces the two-exports rule, and
+dispatches on case shape (transition → state + effects, derivation →
+`fn(input) ≡ value`), seeding each case's `before`/`input` as a delta over
+`State.create()`. Unwraps any `entity(specId)` arg marker to its plain data-id for
+the pure side.
+
+## The exception — a per-surface `userId`, via the lower-level runners
+
+A feature that needs **ambient per-case context differing per surface** — a
+user-scoped `userId` that must be seeded before the raw transaction *and*
+independently before the action dispatch (**p2p presence**) — does **not** use
+`runFeature`. It calls `Conformance.runTransactions` / `runActions` (still
+exported) directly, each with its own `seedContext` (and any per-surface
+concurrency), because the seam differs between the transaction store and the
+action db. `runFeature` has no place to thread two different `seedContext`s, so
+this feature drops to the lower level. This is the escape hatch — ordinary
+features never touch these drivers directly.
+
+## Identity — the `entity(specId)` marker
+
+An entity-addressed transition writes its addressed id as `args: { id: entity(2) }`
+— import `entity`, re-exported from the feature's `data/state/conformance-case.ts`.
+`runSpec` unwraps it to the plain data-id; the ECS runner resolves it to the
+**seeded entity** via the id→entity map `fromState` returns (turned into a `resolve`
+by `Conformance.resolver` — no feature writes `resolve` by hand). Two conventions
+make the wiring vanish: the ECS op takes the entity **under the transition's own arg
+key** (`{ id }`, same-shape args, no reshape), and `fromState` returns the
+`ReadonlyMap<Id, Entity>` id→entity map (or `void` for an index-addressed / singleton
+feature, whose ids then resolve to `Entity.none`). `data-lit-todo` is the reference.
+
+## Name-parity — add a same-named op, never a per-item adapter
+
+Every app transition is realized by a **same-named** transaction and/or action. When
+the real UI op is richer or renamed — todo's `dragTodo`, space-rock's `newGame` — that
+op is infra, and a thin **same-named** op (todo's `reorderTodo` action, space-rock's
+`createInitial` transaction) gives the transition something to pair with. Do **not**
+reintroduce a per-item adapter to bridge a name mismatch — add the same-named op.
+
+## Ordering, tolerance, `ref` — all via `match`
+
+`runFeature` threads `match?: MatchOptions` through to every comparison, so
+per-feature tuning is data, not code:
+
+- **Ordered by default.** `toState` reads a display-ordered collection in order —
+  that is what verifies a reorder — and positional tuples (a `Vec2`) must stay in
+  order.
+- **Entity bags compare as multisets.** A collection the ECS materialises with no
+  display order (bullets, asteroids) is named in
+  `match: { unordered: new Set(["bullets", "asteroids"]) }` so just those fields
+  compare order-independently — never blanket-unordered (it would conflate
+  `[100,180]` with `[180,100]`).
+- **Float noise** is absorbed by the default `tolerance` (`0.01`); raise it only
+  when a case genuinely needs a looser grid.
+- **`Match.ref(label)`** on the expected side asserts id correspondence for a
+  referential feature (an id that must line up in two places); `Match.anyNumber` /
+  `anyString` leave an id a case doesn't pin fully open.
+
+## Recording side effects — built in, no Proxy
+
+Effect recording lives in the drivers: they enumerate a plain-object service's own
+methods and closure-wrap each to record `[method, ...args]` calls, then delegate
+(no `Proxy`, per the repo rule). `runSpec` records the case's injected service
+`args`; the action surface records the `db.services` overrides. A case's `effects`
+asserts each **declared** service's calls exactly (`Array` = ordered, `Set` = any
+order); undeclared services (value-returning reads like `generateName`) are
+ignored.

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/transactions.md

@@ -30,12 +30,21 @@ export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
   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.
-- **Conform every transaction to its `data/` transform** in its sibling
-  `*.test.ts`, via `expectConforms` over the spec's shared cases (see
-  `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.
+- Keep transaction files **single-export** (the `transactions/` barrel is
+  `export *`-ed into the plugin facet, so a second export would pollute it).
+- **Conformance is wired once, centrally, and auto-paired** — not per-file. The
+  feature's single `conformance/conformance.test.ts` `Conformance.runFeature({...})`
+  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 `entity(specId)` marker 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

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

@@ -38,7 +38,7 @@ A binding element is a thin wire between a service and a presentation. The class
 
 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` allowlist
 
@@ -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/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/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.91",
+  "version": "0.9.93",
   "description": "Architecture skills for @adobe/data — data-oriented modelling, archetype iteration, hot-path performance, and related conventions.",
   "author": {
     "name": "Adobe"