@adobe/data-ai 0.10.1 → 0.10.3

package/.claude/rules/README.md

@@ -35,7 +35,8 @@ The `global/` rules (`namespace.md`, `cohesion.md`, `type-casts.md`,
 `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
+`data-modelling.md`, `archetypes.md` (row iteration), `plugin-modelling.md`,
+`versioning.md` (schema history & upgrade-on-load), 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/`).

package/.claude/rules/archetypes.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - '**/*-plugin.ts'
+  - '**/*-plugin/**/*.ts'
+  - '**/*-database.ts'
+  - '**/*-database/**/*.ts'
+---
+
+# Archetypes — the ECS query & iteration model
+
+General to all `@adobe/data` ECS use, feature-organized or not. The
+`core-database/archetypes.ts` *file* conventions live in
+`features/services/main-service/archetypes.md`.
+
+An archetype is a named set of component keys — a kind of entity — and also a
+**query**: `queryArchetypes(include, { exclude })` (and the `select` / `count`
+built on it) returns every archetype whose columns are a **superset** of
+`include`. So `count(archetype.components)` counts that kind and every kind that
+extends it, and a base archetype no entity is inserted into is a first-class
+query, not dead weight.
+
+## Model each logical supertype as a base archetype
+
+Give a state-model supertype (`Layer` ⊃ `ImageLayer` / `GroupLayer`) its own
+archetype over the shared components — with a matching `data/` type — and build
+the subtypes off it:
+
+```ts
+const layer = ["placement", "name", "visible", "opacity"] as const;
+const archetypes = { Layer: layer, ImageLayer: ["image", ...layer, "asset"], GroupLayer: ["group", ...layer] };
+```
+
+`count(archetypes.Layer.components)` then spans every layer kind, current and
+future — correct by construction. Skip a supertype archetype only when nothing
+queries over it.
+
+## Row iteration
+
+**Select in the query, not the loop.** `queryArchetypes(include, { exclude })` takes
+required and excluded component lists — use them; don't query wider then skip rows or
+archetypes with an `if`.
+
+**When every row migrates out, iterate tail → head.** Archetypes are densely
+packed: removing a non-last row hole-fills by moving the tail into the gap.
+Forward iteration while migrating every row pays that shift each step — and forces
+an id snapshot to survive it. Reverse removes from the tail: no shift, no snapshot.
+
+```ts
+// ✅ no shifts, no allocation
+for (let i = arch.rowCount - 1; i >= 0; i--) {
+    db.store.update(arch.columns.id.get(i), { _worldMatrix: Mat4x4.identity });
+}
+```
+
+If only *some* rows migrate, snapshot just the ids you'll touch — forward is then fine.
+
+**Don't snapshot what the query already filters.** A "every id right now" snapshot
+is only needed when forward iteration would invalidate; reverse iteration or an
+`exclude` clause removes the need.

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

@@ -195,7 +195,7 @@ export const createTodo = (
     return { entities: new Map(state.entities).set(id, { name, complete: false, order }) };
 };
 
-export const cases = Conformance.cases(createTodo,
+export const cases = /*@__PURE__*/ Conformance.cases(createTodo,
     { name: "adds the first todo",
       before: {},                       // empty delta — the default State.create() (empty entities)
       args: { name: "a", analytics: AnalyticsService.createFake() },
@@ -217,7 +217,10 @@ export const cases = Conformance.cases(createTodo,
   injected service, etc. into it, never as a third positional. A transition that takes
   **no** args omits `args` from each case entirely (the shared `Case` type makes
   `args` optional exactly then). **Guard no-ops by returning an empty patch `{}`**
-  (or the unchanged slice), never throw.
+  (or the unchanged slice), never throw for an ordinary "nothing to do here"
+  condition. Reserve `throw` for a genuine precondition violation the case wants
+  to name (see "A case that expects a throw" below) — the rare exception, not the
+  default guard style.
 - **A composer merges sub-patches explicitly.** A transition built from smaller
   ones spreads them — `return { ...s, ...sub(s) }` — so each sub-patch's writes
   layer in; a transition that merely **delegates** to one sub-transition returns
@@ -227,6 +230,22 @@ export const cases = Conformance.cases(createTodo,
   any barrel member) in a top-level `cases` literal dead-locks the import cycle.
   Import the concrete helper directly (`import { create } from "./create.js"`) or
   inline full-`State` literals.
+- **Always write the call as `/*@__PURE__*/ Conformance.cases(fn, …)`** (same for
+  `Conformance.derivations`) — the annotation is not optional style, it is what
+  makes the co-location safe. `@adobe/data-testing`'s `sideEffects: false` only
+  lets a bundler drop an unused *import* of the package; `Conformance.cases(fn,
+  …)` is still an ordinary function call happening in *this* file, and an
+  unannotated call is conservatively kept even when the `cases` export it
+  initializes is never read — because the transition function `fn` is legitimately
+  used elsewhere, this module is very much reachable, so the unused `cases` const
+  is the only thing tree-shaking has to remove, and it can't without the hint.
+  Verified against this repo's actual Vite/Rollup production build: a transition
+  whose `cases` call lacked the annotation shipped the full case-fixture data
+  (and the builder's inlined logic) into the bundle; adding `/*@__PURE__*/`
+  removed it completely while leaving the transition function itself intact. A
+  linter/codemod catching a bare `Conformance.cases(`/`Conformance.derivations(`
+  call (missing the leading comment) in a `data/state/*.ts` file would catch this
+  by construction — worth adding if these calls keep getting hand-authored.
 - **`Conformance.cases(fn, ...cases)`** (the builder above) derives each case's
   types from `fn`'s own signature — pass the transition function and cases can't drift
   from what it accepts. **`before` is a delta over `State.create()`** — list only
@@ -295,6 +314,32 @@ export const cases = Conformance.cases(createTodo,
   and isn't a `(state,args)=>state` transform, so `runSpec` skips it: **keep its own
   sibling `*.test.ts`** rather than deleting it and losing coverage.
 
+### A case that expects a throw
+
+A case is normally `{ name, before, args?, after, effects? }`. When a transition
+must reject its input outright — not the "guard no-op, return `{}`" case above,
+but a genuine precondition violation the spec wants to name — declare `throws`
+instead of `after`/`effects`:
+
+```ts
+export const cases = Conformance.cases(withdrawFunds,
+    { name: "rejects a withdrawal over the balance",
+      before: { balance: 10 },
+      args: { amount: 11 },
+      throws: "insufficient funds" },   // substring the thrown Error.message must contain
+);
+```
+
+`throws: true` accepts any thrown error; a string narrows to one whose message
+**contains** it. A case can declare `after`/`effects` **or** `throws`, never
+both — the shared `Case` type makes them mutually exclusive, and there is
+nothing to compare against `after` once a call never returns a patch. The same
+case runs against the pure transform (`runSpec`) **and** the paired ecs
+transaction/action (`runFeature`/`runTransactions`/`runActions`), so a `throws`
+case proves both sides reject the same input the same way. Reach for this only
+when throwing is the transition's actual contract — most invalid input should
+still no-op per the rule above.
+
 ## Injected services and side effects
 
 A transform that needs an outside capability injects it with **`Pick<Services,

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

@@ -1,6 +1,7 @@
 ---
 paths:
-  - '**/features/*/services/**/*.ts'
+  - '**/features/*/services/services.ts'
+  - '**/features/*/services/*-service/**/*.ts'
 ---
 
 # services/ — the feature's services

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

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/services/main-service/**/actions/**/*.ts'
+  - '**/features/*/services/main-service/action-database/actions/**/*.ts'
 ---
 
 # services/main-service/actions/ — async orchestration

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

@@ -5,10 +5,11 @@ paths:
 
 # core-database/archetypes.ts — the feature's archetypes
 
-An archetype is a named, ordered set of component keys — a kind of entity. One
-file, one export: `archetypes`, built with `Database.archetypes(components, …)`,
-which validates every key against the component map and preserves each
-archetype's literal tuple (so no per-archetype `as const satisfies`):
+One file, one export: `archetypes`, built with `Database.archetypes(components, …)`,
+which validates every key against the component map and preserves each archetype's
+literal tuple (so no per-archetype `as const satisfies`). The archetype **model** —
+query/superset semantics, base archetypes for logical supertypes, row iteration — is
+the rules-root `archetypes.md`; this file is the declaration convention.
 
 ```ts
 import { Database } from "@adobe/data/ecs";
@@ -19,19 +20,24 @@ export const archetypes = Database.archetypes(components, {
 });
 ```
 
-- `UpperCase` archetype names — an archetype names a *shape*, the way a class
-  name does.
+- `UpperCase` names — an archetype names a *shape*, like a class.
 - Archetypes may **span scopes**: a document entity can include an ephemeral
-  `session` column (e.g. a live `dragPosition` slot) — the `components` map
-  already merges every scope, so keys from any scope validate.
-- Archetypes are a packing / iteration convenience, **not** part of the
-  serialized data model.
+  `session` column — `components` merges every scope, so any-scope key validates.
+
+## satisfies CoreDatabase.Archetype
+
+Type-check a shared base tuple against `CoreDatabase.Archetype` (= `readonly Component[]`;
+see `core-database.md`) — the same type checks every `count` / `select` query key downstream:
+
+```ts
+const layer = ["placement", "name", "visible", "opacity"] as const satisfies CoreDatabase.Archetype;
+```
 
 ## Drift guard against the data-type
 
-An archetype that mirrors a `data/` row type carries a **non-exported**
-compile-time check — infer the row shape from the archetype and assert it equals
-that data-type — so the two can't drift apart:
+An archetype that mirrors a `data/` row type carries a **non-exported** compile-time
+check — infer the row shape from the archetype and assert it equals the data-type, so
+the two can't drift:
 
 ```ts
 import { Schema } from "@adobe/data/schema";
@@ -41,6 +47,3 @@ import type { PlacedMark } from "../../data/placed-mark/placed-mark.js";
 const _schema = Schema.fromArchetype(components, archetypes.PlacedMark);
 type _Check = Assert<Equal<Schema.ToType<typeof _schema>, PlacedMark>>;
 ```
-
-Iterating archetype **rows** at runtime is a separate concern — see the
-rules-root `archetypes.md`.

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

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

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

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/services/main-service/**/conformance/**/*.ts'
+  - '**/features/*/services/main-service/conformance/**/*.ts'
 ---
 
 # services/main-service/conformance/ — keeping the ECS honest against the spec
@@ -18,15 +18,12 @@ them against the ECS. This folder holds only the *feature-specific projection*
 `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.
+**The projection helpers (`fromState`, `toState`, `toData(store, entity)`) and
+`Match.matches` / `Match.assert` are test-only — never a production/runtime branch.**
+`fromState`/`toState` rewrite the whole store out-of-band; runtime code reads through
+observables/indexes and writes through transactions. (The conformance
+`toData(store, entity)` reader is unrelated to the library's runtime `db.toData()`
+store-serialization method — same name only.)
 
 ## What `@adobe/data-testing` gives you
 
@@ -168,7 +165,11 @@ 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()`. On the ECS side it resolves the reference args a case's `args`
-schema marks; the pure side reads them plain.
+schema marks; the pure side reads them plain. A transition case may declare
+`throws` instead of `after`/`effects` to assert the call rejects its input —
+see `../../data/state.md` ("A case that expects a throw"). `runSpec`,
+`runTransactions`, and `runActions` all honor it identically, so the same case
+proves the pure transform and its paired ecs op fail the same way.
 
 ## The exception — a per-surface `userId`, via the lower-level runners
 

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

@@ -0,0 +1,48 @@
+---
+paths:
+  - '**/features/*/services/main-service/**/core-database/core-database.ts'
+---
+
+# core-database/core-database.ts — the assembled schema + its namespace
+
+A thin assembler: `Database.Plugin.create({ components?, resources?, archetypes? })`
+over the facet files, exposed through the `CoreDatabase` namespace. This is the
+single-file namespace form (one value export — `plugin` — everything else a type;
+see `global/namespace.md`).
+
+```ts
+import { Database, type Store } from "@adobe/data/ecs";
+import { components } from "./components.js";
+import { resources } from "./resources.js";
+import { archetypes } from "./archetypes.js";
+
+const coreDatabasePlugin = Database.Plugin.create({ components, resources, archetypes });
+
+export type CoreDatabase = Database.Plugin.ToDatabase<typeof coreDatabasePlugin>;
+// Resolved component map, at module scope so the imported `Store` namespace isn't
+// shadowed by `CoreDatabase.Store` below.
+type CoreComponents = Store.Components<Database.Plugin.ToStore<typeof coreDatabasePlugin>>;
+
+export namespace CoreDatabase {
+  export const plugin = coreDatabasePlugin;
+  /** The store transactions operate on — a store *is* the transaction context. */
+  export type Store = Database.Plugin.ToStore<typeof coreDatabasePlugin>;
+  /** Index-declaration type bound to this database's components. */
+  export type Index = Database.Index<CoreComponents>;
+  /** A component name, and a component-key tuple — an archetype's defining shape, or the key
+   *  list of a `count` / `select` query. */
+  export type Component = Extract<keyof typeof components, string>;
+  export type Archetype = readonly Component[];
+}
+```
+
+## Derive `Component` / `Archetype` from `components`, never the plugin
+
+Read the keys straight from the leaf `components` module
+(`Extract<keyof typeof components, string>`). Do **not** derive them from the
+plugin (`Store.Components<ToStore<plugin>>`, i.e. `CoreComponents`): the plugin is
+built *from* `archetypes`, so a plugin-derived `Archetype` is **circular** the
+moment it is used to `satisfies`-check an archetype tuple — and the cycle
+collapses the entire database type to `{}`. The leaf derivation is cycle-free and
+usable both in `archetypes.ts` (to check shared bases) and downstream (to check
+`count` / `select` query keys).

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

@@ -1,6 +1,7 @@
 ---
 paths:
-  - '**/features/*/services/main-service/**/*.ts'
+  - '**/features/*/services/main-service/main-service.ts'
+  - '**/features/*/services/main-service/*-database/*-database.ts'
 ---
 
 # services/main-service/ — the feature service (ECS implementation)

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

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

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

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

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

@@ -1,7 +1,6 @@
 ---
 paths:
-  - '**/features/*/services/main-service/**/systems/**/*.ts'
-  - '**/systems/*.ts'
+  - '**/features/*/services/main-service/system-database/**/*.ts'
 ---
 
 # database/systems/ — the real-time tick loop
@@ -66,8 +65,12 @@ const plugin = Database.Plugin.create({
   HUD) are notified. Reserve direct `db.store` writes for the hot per-row paths
   (movement, aging) that run on every entity every frame and shouldn't pay
   per-entity transaction overhead.
-- **Optimize for execution speed in systems** if there are multiple items, then make sure we are using efficient store queries and reading/writing minimal data columns. If this is not hot path, then the simplified data functions can be used, but in hot paths we only consider data functions to be specification. (ie: only use them if it's clearly not a hot path or you cannot write anything more performant by directly using ecs store) 
-- **The step math may live in `data/`.** but only for non-hot path
+- **Optimize hot paths for speed.** With many entities, query with efficient
+  `queryArchetypes` and read/write minimal columns directly; avoid intermediate
+  allocations. On a hot path treat `data/` step functions as **spec only** — use
+  them when the path isn't hot or you can't beat them by writing the store
+  directly; off hot paths, reuse them freely. (Only transactions are observable —
+  direct store writes fire no observers.)
 - **Iterate archetypes per `archetypes.md`.** Express selection with
   `queryArchetypes(include, { exclude })`; when a system destroys/migrates rows
   (bullets expiring, entities dying) iterate **tail → head** so hole-fills don't
@@ -95,11 +98,8 @@ const plugin = Database.Plugin.create({
   and advanced this same tick), you can't advance *all* bodies in one system
   before the spawn — split that entity's advance out so it runs *after* the spawn,
   alongside the step that owns it.
-- Games or simulations with immediate mode rendering may want to store a session
-  resource of the canvas and render to it within a system. @adobe/data-gpu provides
-  example patterns for doing this.
-- All simulation systems should be optimized for performance.
-  Avoid allocating intermediate objects if possible; read/write columns directly if hot-path. You can use transactions if needed, for instance if we are writing non hot path things which we have other things observing. (Only transactions are observable, not direct writes)
+- Immediate-mode rendering: store the canvas in a session resource and render to
+  it inside a system (see @adobe/data-gpu for patterns).
 
 ## Driving the loop — the scheduler
 
@@ -136,58 +136,8 @@ an inline body grows too large — the schedule and registration still live inli
 entities collide, which pair resolves) separately, with seeded edge-case geometries
 — it's a system concern, not a transaction, and where subtle bugs hide.
 
-# Archetypes — iteration rules
+## Iterating archetype rows
 
-## Express selection in the query, not the loop
-
-`queryArchetypes(include, { exclude })` accepts both required and excluded
-component lists. Use them. Don't query a wider set and then skip rows or
-archetypes with an `if`.
-
-```ts
-// ❌ post-filter
-for (const arch of db.store.queryArchetypes(["position", "rotation"])) {
-    if (arch.components.has("_worldMatrix")) continue;
-    ...
-}
-
-// ✅ declarative
-for (const arch of db.store.queryArchetypes(
-    ["position", "rotation"],
-    { exclude: ["_worldMatrix"] },
-)) {
-    ...
-}
-```
-
-## When every row migrates out, iterate tail → head
-
-Archetypes are densely packed. Removing or migrating a row that isn't the
-last one triggers a hole-fill: the tail row is moved into the gap.
-Iterating `0 → rowCount-1` while migrating every row pays this cost on
-every iteration. Iterating `rowCount-1 → 0` means each removal is from
-the tail — no shift, indices ahead of the cursor stay valid.
-
-```ts
-// ❌ shifts the tail into every hole, and the snapshot allocation is
-//    only there to survive the shifts.
-const ids = [...];
-for (let i = 0; i < arch.rowCount; i++) ids[i] = arch.columns.id.get(i);
-for (const id of ids) db.store.update(id, { _worldMatrix: Mat4x4.identity });
-
-// ✅ no shifts, no allocation
-for (let i = arch.rowCount - 1; i >= 0; i--) {
-    db.store.update(arch.columns.id.get(i), { _worldMatrix: Mat4x4.identity });
-}
-```
-
-If only *some* rows migrate (filter inside the loop), snapshot the ids
-you'll touch — forward iteration is fine because rows you don't touch
-stay put.
-
-## Don't snapshot what the query already filters
-
-A snapshot of "all entity ids in this archetype right now" is only
-needed when forward iteration would invalidate. Reverse iteration
-removes the need; an `exclude` clause removes the need to look at rows
-that don't qualify in the first place.
+A per-frame system reads/writes archetype columns directly. The row-iteration
+rules — declarative `queryArchetypes` selection, tail → head migration, snapshot
+avoidance — are general ECS concerns in the rules-root `archetypes.md`.

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

@@ -1,6 +1,6 @@
 ---
 paths:
-  - '**/features/*/services/main-service/**/transactions/**/*.ts'
+  - '**/features/*/services/main-service/transaction-database/transactions/**/*.ts'
 ---
 
 # database/transactions/ — atomic mutations

package/.claude/rules/global/namespace.md

@@ -148,19 +148,18 @@ export const add = ({ x: x1, y: y1 }: Point, { x: x2, y: y2 }: Point): Point =>
 This pattern is ONLY allowed if there is only a single value export and every other export is just a type.
 As soon as there is more than one value type it MUST be promoted to the full namespace pattern.
 
-Example:
+Example — a type merged with one value export and any number of type-only members:
 
-    // core-database.ts
+    // window/window.ts
+    const value = createWindow();
 
-    const coreDatabasePlugin = Database.Plugin.create({
-        components,
-        resources,
-        archetypes,
-    });
+    export type Window = typeof value;
 
-    export type CoreDatabase = Database.Plugin.ToDatabase<typeof coreDatabasePlugin>;
-
-    export namespace CoreDatabase {
-        export const plugin = coreDatabasePlugin;
-        export type Store = Database.Plugin.ToStore<typeof coreDatabasePlugin>;
+    export namespace Window {
+        export const instance = value;   // the sole value export
+        export type Size = { width: number; height: number };
     }
+
+The canonical use is a feature's `core-database.ts` / layered `*-database.ts` (a
+`plugin` value plus `Store` / `Index` / `Component` / `Archetype` types) — see
+`features/services/main-service/core-database.md`.

package/.claude/rules/versioning.md

@@ -0,0 +1,143 @@
+---
+paths:
+  - '**/versioning/**/*.ts'
+  - '**/versions.ts'
+  - '**/versions.test.ts'
+---
+
+# Database schema versioning & upgrade-on-load
+
+A versioned `@adobe/data` database keeps an ordered **version history** so an old
+persisted document can be upgraded to the current schema on load. You (human or
+agent) should almost never have to reason about this by hand: **change the schema,
+run the tests, and the failing test prints the exact fix to apply.**
+
+## The pieces (all from `@adobe/data/ecs`)
+
+- **`versions.ts`** — `export const versions: readonly VersionEntry[]`. `entries[i]`
+  IS version `i`; `entries[0]` is a frozen copy of the initial schema. `currentVersion
+  = versions.length - 1`.
+- **`VersionEntry`** — `{ version, changes: { components?, resources? }, handler? }`.
+  `version` MUST equal the array index. `changes` is a **JSON Merge Patch** applied to
+  the folded-so-far schema — record ONLY what changes, not a restated copy:
+  - `name: { …fields… }` adds a new component/resource, or deep-merges those fields
+    onto the existing schema;
+  - a key set to **`undefined`** DELETES it — `name: undefined` drops the whole
+    component/resource; a nested `precision: undefined` drops just that field;
+  - `null` is a normal VALUE (so `default: null` sets the default), not a delete;
+    arrays/scalars replace wholesale.
+  Because it MERGES, a shape change must delete the fields that no longer apply —
+  number → object is `{ type: "object", properties: {…}, precision: undefined, default: undefined }`,
+  never a bare `{ type: "object", … }` (which would keep the old `precision`/`default`).
+  Never write empty `changes: {}` — an entry must record at least one change. Components
+  and resources are separate namespaces. `handler` is present ONLY for a change that is
+  not automatically convertible.
+- The version is **NOT an ECS resource** — it rides the save-format metadata. The db
+  exposes it as `db.version` (`= currentVersion`, or `0` when unversioned), stamps it into
+  every `toData` per persisted quadrant (`schemaVersions: { document, settings }`), and
+  reads it back on load. Do not declare a `documentVersion`/`version` component or resource.
+- **`createVersionUpgrader(versions)`** passed as `Database.create(plugin, { versioning })`.
+  No config — the per-quadrant saved versions come from the blob metadata. Each `handler`
+  touches exactly ONE persisted quadrant (`document` or `settings`); the upgrader replays
+  each quadrant from its own saved version up to current (see rule 7).
+- ONE co-located guard test in `versions.test.ts` calling `assertVersioning(...)` (see below).
+
+## Rules — do not violate
+
+1. **Existing entries are FROZEN.** Never edit, reorder, or delete an entry — it is
+   historical fact. Only ever APPEND a new entry.
+2. **Version 0 is a deep copy, never a reference.** It must not change when the live
+   schema changes; that is the whole point of a history.
+3. **Additive & minor changes need NO handler** — the load path auto-converts them
+   (add-field-with-default, widen/narrow, reorder, clamp, add component/resource).
+   Just record the `changes` patch.
+4. **Breaking changes REQUIRE a handler** — a type change, a rename, splitting/moving
+   a field. The handler runs against the store staged to the previous version and
+   mutates it in place to the new shape. For an ISOLATED single-component change,
+   `Store.remapComponent(store, name, newSchema, old => newValue)` does it in one call —
+   but it is NOT required and NOT always applicable. A migration that reads from or
+   writes to SEVERAL components (a cross-component move, deriving a new component from
+   others, splitting one into many) must be hand-written to your upgrade algorithm:
+   query the input components, compute, and write the outputs directly on the store.
+   Add a test case either way (rule 6).
+5. **Removing a component drops its data.** If the data still matters, migrate it in a
+   handler BEFORE the removal entry.
+6. **Versioned schemas must be REAL** — declare a `type` (or `enum`/`const`), and the
+   `default` must be fully described by that schema (no extra keys/structure). Only
+   SESSION values (`nonPersistent` AND `nonShared`, e.g. a GPU buffer) may be untyped,
+   and those are never versioned — leave them out of the history entirely.
+7. **A handler touches ONE quadrant.** Persisted quadrants (shared+persistent = the
+   cloud document; nonShared+persistent = local settings) can be saved separately and
+   drift to DIFFERENT versions. On load they are merged into one store and the upgrader
+   replays EACH quadrant from its own stamp — so a handler that changes schemas in more
+   than one quadrant fails the guard (when one quadrant is behind, staging its handler
+   must not touch the other). Split it into one version per quadrant — the upgrader reads
+   each quadrant's saved version from the blob metadata automatically.
+
+## When a schema change makes a test fail — the fix is in the error
+
+`assertVersionsMatchSchema` fails whenever the live schema no longer folds from the
+history. Its message is a literal recipe. To fix it:
+
+1. **Append one new entry** to the `versions` array with `version:` = the next index
+   and the `changes` block the error printed verbatim. `db.version` follows the history
+   automatically (`= versions.length - 1`) — there is no resource default to update.
+2. If the error marks a change **BREAKING — needs a handler**, add a `handler` to that
+   entry AND add a matching test case under `testUpgradeHandlers` (rule 6). The error
+   may point at `Store.remapComponent(...)` for an isolated single-component change, but
+   that is only a suggestion — write whatever upgrade code the change actually needs.
+
+Do exactly what the message says; do not touch existing entries.
+
+## The one guard test
+
+A single `assertVersioning(...)` runs BOTH checks — the history folds to the current
+schema (schema coverage) AND every entry with a `handler` has a passing test case
+(handler coverage + behavior). Keep this one test.
+
+```ts
+import { Database, assertVersioning, createVersionUpgrader } from "@adobe/data/ecs";
+import { MainService } from "../main-service.js";
+import { versions } from "./versions.js";
+
+describe("database schema versions", () => {
+  it("the version history is consistent (schema folds + every handler tested)", () =>
+    assertVersioning({
+      // the version-configured db, so db.version = the history's current version
+      database: Database.create(MainService.plugin, { versioning: createVersionUpgrader(versions) }),
+      entries: versions,
+      handlers: {
+        // Append a case per version that adds a `handler` (rule 6):
+        // <version>: { setup: (store) => <populate the version-(v-1) store, return entities>,
+        //              expect: (store, setup) => <assert the version-v result> },
+      },
+    }));
+});
+```
+
+(`assertVersionsMatchSchema` and `testUpgradeHandlers` remain exported for bespoke use.)
+```
+
+## Example: a breaking change (number → object) at version 1
+
+```ts
+// versions.ts — append (do NOT edit version 0)
+import { Store } from "@adobe/data/ecs";
+const HealthObject = { type: "object", properties: { current: { type: "number", precision: 1, default: 0 }, max: { type: "number", precision: 1, default: 0 } } };
+export const versions = [
+  { version: 0, changes: { components: { /* …frozen… */ hp: { type: "number", precision: 1, default: 0 } } } },
+  { version: 1,
+    // MERGE patch: add the object shape, DELETE the number-only fields it drops.
+    changes: { components: { hp: { type: "object", properties: HealthObject.properties, precision: undefined, default: undefined } } },
+    handler: (store) => Store.remapComponent(store, "hp", HealthObject, (old: number) => ({ current: old, max: old })) },
+];
+// `db.version` becomes 1 automatically (= versions.length - 1) — nothing else to set.
+
+// versions.test.ts — add the required case to the guard's `handlers`
+assertVersioning({ database: db, entries: versions, handlers: {
+  1: {
+    setup: (store) => store.ensureArchetype(["hp"]).insert({ hp: 42 }),
+    expect: (store, e) => expect(store.read(e)?.hp).toEqual({ current: 42, max: 42 }),
+  },
+} });
+```

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "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.10.1"
+    "@adobe/data": "0.10.3"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.10.1"
+    "@adobe/data": "0.10.3"
   },
   "license": "MIT",
   "scripts": {