@adobe/data-ai 0.10.22 → 0.10.24

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

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

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

@@ -6,6 +6,8 @@ paths:
 
 # ui/ — user interface
 
+> **Legacy feature** (has `data/state/` or `services/main-service/`)? Its data and services follow the legacy rules; the ui rules here still apply.
+
 The top layer: UI that binds the feature's `MainService` database (`ecs/main-service.ts`)
 to what the user sees. It owns no business logic — it subscribes to state, hands it to
 a pure presentation, and wires user input to `service.actions.*`.

package/.claude/rules/service.md

@@ -6,7 +6,7 @@ paths:
 
 # Service authoring
 
-> Inside a feature, `features/services/index.md` governs the folder layout: a small service keeps `create.ts` and `create-fake.ts` flat beside the interface (the single-file exception below); one with helpers moves its implementation into a sub-folder. Database-bound factories in `ecs/services/` follow `features/ecs/services.md`.
+> Inside a feature, `features/services/index.md` covers the service layer; database-bound factories in `ecs/services/` follow `features/ecs/services.md`.
 
 Asynchronous data services. Live in the `services/` layer. Adhere to the namespace rule for type and function organization.
 
@@ -44,74 +44,26 @@ Compile-time check: `Assert<AsyncDataService.IsValid<ServiceInterface>>`.
 
 ---
 
-## Folder structure and cohesion
-
-**MUST NOT** place implementation files alongside the interface file. The `<name>-service/` folder MUST contain only the interface file and
-`public.ts`.
+## Folder structure
 
 ```
 services/<name>-service/
-  <name>-service.ts          ← interface + contract types; `export * as ServiceName from './public.js'` at bottom
-  public.ts                  ← re-exports factory (and other public exports) from the implementation sub-folder
-  <impl-name>/               ← REQUIRED sub-folder for all implementation files
-    create-<name>-service.ts ← factory function
-    *.ts                     ← helpers, utils, constants (implementation-private)
-    *.test.ts                ← tests live here alongside implementation
-```
-
-**Single-file exception**: a bare factory with no helpers, no utilities, and no constants MAY live as a flat file alongside the interface.
-The moment any additional implementation file is needed, the factory MUST move into a sub-folder.
-
-**Interface file** (`<name>-service.ts`) — interface declaration and types that define the public service contract. MUST NOT import from any
-implementation file or sub-folder. At the bottom of the file, exports the namespace: `export * as ServiceName from './public.js'`. This
-merges the interface type and the factory namespace under one identifier — callers type against the interface and invoke factory functions
-through the same name.
-
-**Separate types file at the interface level** — only permitted if it contains exclusively public-contract types (types that appear in the
-interface's method signatures or `Observe<>` generic arguments). Implementation-detail types — third-party API shapes, `window.*` global
-augmentations, internal utilities — MUST live inside the implementation sub-folder.
-
-**`*.test.ts` files MUST NOT appear at the interface folder level.** Every test file belongs inside the implementation sub-folder next to
-the code it tests; there is nothing at the interface level to test.
-
-**Implementation sub-folder** — all implementation logic including the factory, utilities, constants, helpers, and their tests. MUST NOT
-depend on the interface file's types via the `public.js` re-export; import directly from `<name>-service.js`.
-
-**public.ts** — MUST re-export the factory function and any other public exports from the implementation sub-folder. Does NOT re-export the
-interface — the interface is exported directly from `<name>-service.ts`.
-
-**No classes** — factory function or static plain object only. `this` bindings are brittle and block higher-order composition.
-
----
-
-## Factory export shape — `singletonFactory` + dual export
-
-Every service factory MUST be wrapped with `singletonFactory` from `factory-functions.js`. This guarantees one instance per argument tuple
-when the same factory is called multiple times, preventing duplicate subscriptions and torn state.
-
-Export **both** the raw `factory` and the singleton-wrapped `create`:
-
-```ts
-// <name>-service/<impl-name>/create-<name>-service.ts
-import { singletonFactory } from 'factory-functions.js';
-
-export const factory = (deps: Deps): NameService => {
-  // implementation
-};
-
-// `factory` — for test injection (bypasses the singleton cache; each test gets a fresh instance)
-// `create`  — for production use (singleton per deps-tuple)
-export const create = singletonFactory(factory);
-```
-
-`public.ts` re-exports both:
-
-```ts
-export { create, factory } from './<impl-name>/create-<name>-service.js';
+  <name>-service.ts   ← interface + contract types; `export * as ServiceName from './public.js'` at bottom
+  create.ts           ← the implementation factory (or a factory that throws when the app must inject it)
+  create-fake.ts      ← an inert fake with every method present
+  public.ts           ← re-exports `create` and `createFake`
 ```
 
-**Why:** Tests must create fresh instances without sharing a singleton cache. Production callers use `create`; tests that need isolation
-import `factory` directly.
+- **Interface file** (`<name>-service.ts`) — the interface and the types in its method
+  signatures. It never imports an implementation file. The namespace export at the
+  bottom merges the interface type and the factories under one name: callers type
+  against the interface and call `ServiceName.create`.
+- **An implementation that grows helpers** moves into a named sub-folder
+  (`create-<name>-service/` with its helpers and their tests); `public.ts` re-exports
+  its factory. Implementation-only types (third-party API shapes, `window.*`
+  augmentations) live there too, never in the interface file.
+- **No classes** — factory functions or plain objects only. `this` bindings are brittle
+  and block higher-order composition.
 
 ---
 
@@ -124,7 +76,7 @@ identifiers in any method signature, property name, or type parameter.
 
 ```ts
 interface SessionService extends Service {
-  readonly dunamis: DunamisSdk; // UI now knows Dunamis exists
+  readonly analyticsSdk: AnalyticsSdk; // UI now knows which SDK is used
 }
 ```
 
@@ -136,7 +88,7 @@ interface SessionService extends Service {
 }
 ```
 
-The interface is the contract between UI and data layers. If the underlying tool is swapped (Dunamis → another SDK, cookies → localStorage),
+The interface is the contract between UI and data layers. If the underlying tool is swapped (one SDK → another, cookies → localStorage),
 the interface must not change. Any leak of an internal tool name into the interface couples the UI to an implementation detail it must not
 know about.
 
@@ -146,21 +98,19 @@ know about.
 
 When creating or modifying a service:
 
-1. Place in `services/<name>-service/`.
+1. Place it in `services/<name>-service/`.
 2. Interface in `<name>-service.ts` — types only, extend `Service`, add `Assert<AsyncDataService.IsValid<>>`.
-3. All implementation files go inside a named sub-folder (e.g. `create-<name>-service/`).
+3. Add `create.ts`, `create-fake.ts` and `public.ts`; move the implementation into a sub-folder once it needs helpers.
 4. At the bottom of `<name>-service.ts`, add `export * as ServiceName from './public.js'`.
-5. In `public.ts`, re-export the factory (and any other public exports) from the implementation sub-folder.
-6. For front-end services: actions return void only; observables observe Data or Service only. For back-end services: functions return
+5. For front-end services: actions return void only; observables observe Data or Service only. For back-end services: functions return
    `Promise<Data>` or `AsyncGenerator<Data>`.
 
 ---
 
 ## Verify
 
-When any `src/**/services/**/*.ts` file is in the diff, confirm all three invariants:
+When any `services/**` file is in the diff, confirm:
 
-1. **Interface/implementation separation** — every `.ts` file added or modified in `<name>-service/` is either `<name>-service.ts`,
-   `public.ts`, or inside a named sub-folder. Any file at the root of the folder that is neither is a violation.
-2. **`public.ts` completeness** — `public.ts` re-exports the factory function (and any other public exports from the sub-folder).
-3. **Interface file purity** — `<name>-service.ts` contains no imports from implementation sub-folders.
+1. **Interface file purity** — `<name>-service.ts` imports no implementation file.
+2. **`public.ts` completeness** — it re-exports `create` and `createFake` (and any other public factory).
+3. **No implementation-only types in the interface** — they live with the implementation.

package/.claude-plugin/plugin.json

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

package/README.md

@@ -55,6 +55,14 @@ self-update**, editing your `package.json` and `.gitignore` to:
    scripts, so a `postinstall` shipped inside the package would silently not fire;
 3. gitignore the managed bundle folders.
 
+Each managed folder also gets a short "externally managed — do not edit" notice so
+an agent that opens it is warned before touching the regenerated files. The notice
+follows your repo's instruction convention: it is written as `AGENTS.md` by default
+(the cross-agent standard, which Claude Code also reads) and only as `CLAUDE.md` for a
+repo that is still CLAUDE.md-only. `install` never drops a `CLAUDE.md` into a repo that
+uses `AGENTS.md` — a stray `CLAUDE.md` anywhere makes Claude Code ignore every
+`AGENTS.md` project-wide.
+
 The copied files are regenerated artifacts — never committed, never edited in
 place. The wiring is idempotent, so re-running is harmless; with `--global` or in a
 directory with no `package.json`, `install` just copies (no wiring).

package/bin/cli.mjs

@@ -41,10 +41,13 @@ const { name: PKG_NAME, version: VERSION } = pkg;
 // each agent root.
 const BUNDLE = "adobe-data-ai";
 
-// A do-not-edit notice dropped at each bundle root. Claude Code loads nested
-// CLAUDE.md files when working in a subtree, so an agent that opens one of these
-// folders sees the notice before touching anything. `extra` adds a pointer to
-// the companion bundle.
+// A do-not-edit notice dropped at each bundle root so an agent that opens one of
+// these managed folders sees it before touching anything. The file is named for the
+// project's instruction convention (see `noticeFilename`) — never unconditionally
+// `CLAUDE.md`: Claude Code treats any CLAUDE.md in the tree as switching the whole
+// project into CLAUDE.md mode and then ignores every AGENTS.md project-wide (observed
+// on Claude Code 2.1.286), which would silently blank out instructions in an
+// AGENTS.md-based repo. `extra` adds a pointer to the companion bundle.
 function notice(extra) {
     return `# Externally managed — do not edit
 
@@ -58,11 +61,23 @@ version, then reinstall — do not modify these files in place.
 ${extra ? `\n${extra}\n` : ""}`;
 }
 
-function writeMeta(bundleDir, noticeBody, extraMeta) {
-    writeFileSync(join(bundleDir, "CLAUDE.md"), noticeBody);
+// Choose the managed notice's filename from the project's instruction convention.
+// Preference is AGENTS.md (the cross-agent standard, which Claude Code also reads); we
+// fall back to CLAUDE.md only for a repo still on the CLAUDE.md convention (a root
+// CLAUDE.md and no AGENTS.md), so the notice keeps auto-loading there. An AGENTS.md
+// repo (and a greenfield one) therefore never receives a data-ai CLAUDE.md — a stray
+// CLAUDE.md anywhere flips Claude Code out of AGENTS.md mode for the whole project.
+function noticeFilename(base) {
+    const hasClaude = existsSync(join(base, "CLAUDE.md"));
+    const hasAgents = existsSync(join(base, "AGENTS.md"));
+    return hasClaude && !hasAgents ? "CLAUDE.md" : "AGENTS.md";
+}
+
+function writeMeta(bundleDir, noticeBody, extraMeta, noticeFile) {
+    writeFileSync(join(bundleDir, noticeFile), noticeBody);
     writeFileSync(
         join(bundleDir, ".data-ai.json"),
-        JSON.stringify({ package: PKG_NAME, version: VERSION, ...extraMeta }, null, 2) + "\n",
+        JSON.stringify({ package: PKG_NAME, version: VERSION, notice: noticeFile, ...extraMeta }, null, 2) + "\n",
     );
 }
 
@@ -107,6 +122,7 @@ function installSkills(base, skills) {
         bundleDir,
         notice("The architecture rules these skills follow are installed at\n`.claude/rules/adobe-data-ai/` (referenced by name from each SKILL.md)."),
         { skills },
+        noticeFilename(base),
     );
     return bundleDir;
 }
@@ -118,7 +134,7 @@ function installRules(base) {
     // Copy the whole rules tree, minus the top-level README.md meta doc.
     const readme = join(rulesSrc, "README.md");
     cpSync(rulesSrc, bundleDir, { recursive: true, filter: (src) => src !== readme });
-    writeMeta(bundleDir, notice(), { rules: countRules(rulesSrc) });
+    writeMeta(bundleDir, notice(), { rules: countRules(rulesSrc) }, noticeFilename(base));
     return bundleDir;
 }
 

package/package.json

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

package/skills/build-actions/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create `ecs/actions/`: `action-database.ts` (extends the previous layer, adds `actions`
 from `./index.js`), one action per file, and a barrel. Every spec action has a
 same-named action. It awaits services and commits through at most one transaction

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

@@ -5,6 +5,8 @@ input: app
 output: app
 ---
 
+A legacy feature (has `data/state/` or `services/main-service/`) exposes its `MainService` from `services/main-service/`; compose it from there.
+
 Create `src/app/`:
 
 - `schema.ts` — the composed plugin: the base feature's `MainService.plugin`, `imports`

package/skills/build-computed/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the spec has no derivations and the UI needs no derived values.
 
 Create `ecs/computed/`: `computed-database.ts` (extends the previous layer, adds

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

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create:
 
 - `ecs/core/archetypes.ts` — `Database.archetypes(components, { … })`, spreading each

package/skills/build-data/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create the feature's `data/` layer: pure Data declarations, depending only on
 `@adobe/data` and the `data/` of features this one builds on.
 

package/skills/build-feature/SKILL.md

@@ -5,6 +5,9 @@ input: feature
 output: feature
 ---
 
+If the feature already has `data/state/` or `services/main-service/`, it uses the legacy
+state-based layout: extend it in place per those legacy rules; don't migrate it unless asked.
+
 /graph-execute
     /build-data
     /build-services

package/skills/build-indexes/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the feature needs no indexed lookups.
 
 Create `ecs/indexes/`: `index-database.ts` (extends `CoreDatabase`, adds `indexes` from

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

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the feature has no services.
 
 Create `ecs/services/service-database.ts` (extends the previous layer), registering

package/skills/build-services/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the feature talks to nothing outside itself.
 
 Create one `services/<name>-service/` namespace per service: the interface (an async

package/skills/build-spec/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create the feature's `spec/` folder, the specification the ECS will be conformed to:
 
 - `state.ts` — `State` built from `data/` types (singletons named for resources,

package/skills/build-systems/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip unless the feature is real-time (games, simulations).
 
 Create `ecs/systems/system-database.ts`: `Database.Plugin.create({ extends:

package/skills/build-transactions/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create `ecs/transactions/`: `transaction-database.ts` (extends the previous layer, adds
 `transactions` from `./index.js`), one mutation per file, and a barrel. Type the store
 `CoreDatabase.Store`, or `IndexDatabase.Store` once it reads an index. Guard by entity

package/skills/build-ui/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create `ui/`: one folder per UI unit —
 `<name>/{<name>.ts (lazy wrapper), <name>-element.ts (container), <name>-presentation.ts (pure render), <name>.css.ts}`.
 The element subscribes to `MainService` state and calls `service.actions.*`; the

package/skills/review/SKILL.md

@@ -6,6 +6,8 @@ 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
 ---
 
+Check a legacy feature (has `data/state/` or `services/main-service/`) against the legacy rules; don't flag the layout itself.
+
 Read the files under the given path and assess them against the relevant `features/`
 rules (each layer's rule and the cross-cutting rules — `namespace`, `data-modelling`,
 `type-casts`, `cohesion`, …):

package/skills/structure/SKILL.md

@@ -3,5 +3,7 @@ name: structure
 description: Use when laying out or reasoning about a feature's file/folder structure and layer dependencies.
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? It keeps its state-based layout (the legacy rules); don't migrate unless asked.
+
 See `features/index.md` (and the per-folder `features/` rules) for how features are
 structured and layered.