feat(data): value-partitioned archetypes (shared components)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-monorepo",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "private": true,
   "scripts": {
     "build": "pnpm -r run build",

packages/data-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "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,

packages/data-gpu-samples/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-gpu-samples",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "WebGPU samples built on @adobe/data-gpu",
   "type": "module",
   "private": true,

packages/data-gpu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-gpu",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Adobe data WebGPU plugins and types for graphics and compute",
   "type": "module",
   "private": false,

packages/data-lit-tictactoe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-lit-tictactoe",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Tic-Tac-Toe sample - Lit web components with @adobe/data-lit and AgenticService",
   "type": "module",
   "private": true,

packages/data-lit-todo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-lit-todo",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Todo sample app demonstrating @adobe/data with Lit",
   "type": "module",
   "private": true,

packages/data-lit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-lit",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Adobe data Lit bindings - hooks, elements, decorators",
   "type": "module",
   "private": false,

packages/data-p2p-tictactoe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-p2p-tictactoe",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Serverless P2P tic-tac-toe — WebRTC DataChannel + @adobe/data-sync",
   "type": "module",
   "private": true,

packages/data-persistence/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@adobe/data-persistence",
-    "version": "0.9.82",
+    "version": "0.9.83",
     "description": "Worker-based incremental persistence layer for @adobe/data ECS over OPFS (browser) and node:fs (server).",
     "type": "module",
     "sideEffects": false,

packages/data-react-hello/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-react-hello",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Hello World sample - click counter using @adobe/data-react",
   "type": "module",
   "private": true,

packages/data-react-pixie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-react-pixie",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "PixiJS React sample - ECS sprites (bunny, fox) with @adobe/data-react",
   "type": "module",
   "private": true,

packages/data-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-react",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Adobe data React bindings — hooks and context for ECS database",
   "type": "module",
   "private": false,

packages/data-solid-dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-solid-dashboard",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Mini dashboard sample — multiple components sharing one @adobe/data ECS database with SolidJS",
   "type": "module",
   "private": true,

packages/data-solid/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-solid",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Adobe data SolidJS bindings — context and provider for ECS database",
   "type": "module",
   "private": false,

packages/data-sync/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@adobe/data-sync",
-    "version": "0.9.82",
+    "version": "0.9.83",
     "description": "Multi-user real-time synchronisation for @adobe/data ECS — server, client, and in-process loopback.",
     "type": "module",
     "sideEffects": false,

packages/data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data",
-  "version": "0.9.82",
+  "version": "0.9.83",
   "description": "Adobe data oriented programming library",
   "type": "module",
   "sideEffects": false,

packages/data/src/ecs/README.md

@@ -211,6 +211,36 @@ resolve `Track` to its concrete columns.
 - Don't let the schema be the **lone** export of a `stripInternal`-emitted
   module — pair it with another export (e.g. the `components` object above).
 
+### Partition components (experimental)
+
+> **Experimental.** API and semantics may change in a future minor release.
+
+A **partition component** (a primitive component marked `partition: true`) stores every distinct runtime value in its *own* archetype — the "shared component" pattern. Within a partition archetype the value is constant, so its column is a zero-per-row const buffer, and entities sharing a value are contiguous in memory (a coarse, storage-level spatial/grouping index).
+
+```ts
+const worldPlugin = Database.Plugin.create({
+  components: {
+    cell: { type: "integer", partition: true }, // primitive only
+    position: Vec3.schema,
+  },
+  archetypes: { Occupant: ["cell", "position"] },
+  transactions: {
+    // A partitioned named archetype is a Router: `insert` routes each row to the
+    // concrete child archetype for its `cell` value (created on first use).
+    spawn: (t, cell: number, pos: [number, number, number]) =>
+      t.archetypes.Occupant.insert({ cell, position: pos }),
+  },
+});
+```
+
+- **`ensureArchetype(keys)`** returns a `Router` (write-only: `insert` only) when `keys` include a partition component without a value; supply the value — `ensureArchetype(keys, { cell: 7 })` — to get the concrete child archetype (dense columns) directly.
+- **Reads** go through `queryArchetypes(include, { where })`: `where` filters by partition value at *archetype* granularity (O(archetypes), no row scan), e.g. `queryArchetypes(["cell", "position"], { where: { cell: 7 } })`. Omit `where` to iterate every value-child.
+- **`select(..., { order })`** whose leading order key(s) are partition components sorts per-bucket and concatenates — O(N log(N/K)), and O(N) when a partition key is the sole order key.
+- **`update`** that changes a partition value migrates the entity to the child for the new value (like adding/removing a component).
+- **Multiple** partition components compose: archetypes are the *cross product* of the distinct value tuples.
+
+**Cost / when to use.** Changing a partition value is a structural move (archetype migration), and archetype count is the product of distinct values across all partition columns — so a fine or fast-changing key fragments badly. Partition on **coarse, low-cardinality, slowly-changing** keys (region, team, layer); use a normal component + an [index](#indexes) or an external structure for fine or per-frame keys. A store that declares no partition component pays nothing.
+
 ## Indexes
 
 Indexes give O(1) lookup by some derived or column-valued key. Declare them on the plugin alongside components and archetypes; the runtime maintains them automatically on every insert/update/delete and exposes typed lookup handles at `db.indexes.<name>` and `t.indexes.<name>` (inside transactions).

packages/data/src/ecs/archetype/archetype.ts

@@ -43,6 +43,31 @@ export interface Archetype<C extends RequiredComponents = RequiredComponents> ex
     fromData: (data: unknown) => void
 }
 
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace Archetype {
+    /**
+     * Write-only handle over a *family* of archetypes that share a component set
+     * but differ by the value of one or more `partition` components. `insert`
+     * reads the partition value(s) from the row, resolves (creating on first use)
+     * the concrete child archetype for that value, and inserts there.
+     *
+     * A family has no single dense column view, so — unlike {@link Archetype} — a
+     * Router exposes no `columns`, `rowCount`, or iteration. Read a family through
+     * `queryArchetypes` (optionally filtered by partition value), or narrow to one
+     * concrete member by supplying the value to `ensureArchetype`.
+     *
+     * `insert` is deliberately signature-identical to {@link Archetype.insert}: a
+     * discriminated `Archetype<C> | Archetype.Router<C>` (produced when the
+     * requested keys are not statically known to include/exclude a partition
+     * component) therefore still permits `.insert` with no narrowing — only dense
+     * column access requires having resolved to a concrete {@link Archetype}.
+     */
+    export interface Router<C extends RequiredComponents = RequiredComponents> {
+        readonly components: ComponentSet<StringKeyof<C>>;
+        insert: <T extends EntityInsertValues<C>>(rowData: Exact<EntityInsertValues<C>, T>) => Entity;
+    }
+}
+
 export type FromArchetype<T> =
     T extends ReadonlyArchetype<infer C> ? { readonly [K in keyof C]: C[K] } :
     T extends Archetype<infer C> ? { readonly [K in keyof C]: C[K] } :

packages/data/src/ecs/database/create-plugin.ts

@@ -7,6 +7,7 @@ import type { ArchetypeComponents } from "../store/archetype-components.js";
 import type { TransactionDeclarations, ToTransactionFunctions } from "../store/transaction-functions.js";
 import type { ToActionFunctions } from "../store/action-functions.js";
 import type { FromSchemas } from "../../schema/index.js";
+import type { PartitionKeysOf } from "../store/partition.js";
 import type { StringKeyof, NoInfer, RemoveIndex } from "../../types/types.js";
 import { combinePlugins } from "./combine-plugins.js";
 import { Store } from "../store/store.js";
@@ -189,7 +190,7 @@ export function createPlugin<
     const RS extends ResourceSchemas,
     const A extends ArchetypeComponents<StringKeyof<RemoveIndex<CS> & XP['components'] & IP['components']>>,
     const IX extends IndexDeclarations<FromSchemas<RemoveIndex<CS> & XP['components'] & IP['components']>, RemoveIndex<A> & XP['archetypes'] & IP['archetypes']>,
-    const TD extends TransactionDeclarations<FromSchemas<RemoveIndex<CS> & XP['components'] & IP['components']>, FromSchemas<RemoveIndex<RS> & XP['resources'] & IP['resources']>, RemoveIndex<A> & XP['archetypes'] & IP['archetypes'], RemoveIndex<IX> & XP['indexes'] & IP['indexes']>,
+    const TD extends TransactionDeclarations<FromSchemas<RemoveIndex<CS> & XP['components'] & IP['components']>, FromSchemas<RemoveIndex<RS> & XP['resources'] & IP['resources']>, RemoveIndex<A> & XP['archetypes'] & IP['archetypes'], RemoveIndex<IX> & XP['indexes'] & IP['indexes'], PartitionKeysOf<RemoveIndex<CS> & XP['components'] & IP['components']>>,
     const AD,
     const S extends string = never,
     const SVF extends ServiceFactories<Database.FromPlugin<AmbientPlugin<XP, IP>>> = {},

packages/data/src/ecs/database/database.partition.test.ts

@@ -0,0 +1,49 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect } from "vitest";
+import { Database } from "./database.js";
+
+// A plugin whose `cell` component partitions, with a unique name index. The
+// transactions write through the transaction context `t`, exercising routing
+// and index maintenance on the committed-transaction path.
+const plugin = () => Database.Plugin.create({
+    components: {
+        cell: { type: "integer", partition: true },
+        name: { type: "string" },
+    },
+    archetypes: { Spatial: ["cell", "name"] },
+    indexes: { byName: { key: "name", unique: true } },
+    transactions: {
+        add: (t, input: { cell: number; name: string }) => t.archetypes.Spatial.insert(input),
+        move: (t, input: { entity: number; cell: number }) => { t.update(input.entity, { cell: input.cell }); },
+    },
+});
+
+describe("Database partition integration (transaction context)", () => {
+    it("routes t.archetypes.<PartitionedName> inserts and maintains indexes", () => {
+        const db = Database.create(plugin());
+        const a = db.transactions.add({ cell: 1, name: "alice" });
+        const b = db.transactions.add({ cell: 2, name: "bob" });
+
+        expect(db.indexes.byName.get({ name: "alice" })).toBe(a);
+        expect(db.indexes.byName.get({ name: "bob" })).toBe(b);
+        // Distinct cells → distinct concrete archetypes.
+        expect(db.locate(a)!.archetype).not.toBe(db.locate(b)!.archetype);
+        expect(db.get(a, "cell")).toBe(1);
+    });
+
+    it("migrates on a partition-value change inside a transaction; index follows", () => {
+        const db = Database.create(plugin());
+        const e = db.transactions.add({ cell: 1, name: "mover" });
+        db.transactions.move({ entity: e, cell: 2 });
+        expect(db.get(e, "cell")).toBe(2);
+        expect(db.indexes.byName.get({ name: "mover" })).toBe(e);
+    });
+
+    it("enforces a unique index across value-children inside a transaction (atomic)", () => {
+        const db = Database.create(plugin());
+        const first = db.transactions.add({ cell: 1, name: "dup" });
+        expect(() => db.transactions.add({ cell: 2, name: "dup" })).toThrow(/[Uu]nique/);
+        // Original intact — the failed transaction rolled back cleanly.
+        expect(db.indexes.byName.get({ name: "dup" })).toBe(first);
+    });
+});

packages/data/src/ecs/database/database.partition.type-test.ts

@@ -0,0 +1,46 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Compile-time (red/green) verification that the transaction context `t`
+// discriminates partition archetypes — both `t.archetypes.<Name>` and
+// `t.ensureArchetype`. Wrapped in a never-called function so the file
+// type-checks without executing the plugin factory.
+
+import { Database } from "./database.js";
+
+function _transactionContextDiscrimination() {
+    Database.Plugin.create({
+        components: {
+            cell: { type: "integer", partition: true },
+            position: { type: "number" },
+            health: { type: "number" },
+        },
+        archetypes: {
+            Spatial: ["cell", "position"],   // partition family
+            Mob: ["position", "health"],     // concrete
+        },
+        transactions: {
+            check: (t) => {
+                // A partitioned named archetype is a Router on `t` — write via insert.
+                t.archetypes.Spatial.insert({ cell: 1, position: 2 });
+                // @ts-expect-error - Spatial is a partition family (Router), not a concrete Archetype
+                t.archetypes.Spatial.columns;
+
+                // A non-partition named archetype is a concrete Archetype on `t`.
+                t.archetypes.Mob.columns;
+                t.archetypes.Mob.insert({ position: 1, health: 100 });
+
+                // ensureArchetype on `t` discriminates just like on the store.
+                const router = t.ensureArchetype(["id", "cell", "position"]);
+                router.insert({ cell: 1, position: 2 });
+                // @ts-expect-error - a partition family (Router) has no columns
+                router.columns;
+
+                const concrete = t.ensureArchetype(["id", "cell", "position"], { cell: 7 });
+                concrete.columns;
+
+                // @ts-expect-error - partition value must match the component type (cell is number)
+                t.ensureArchetype(["id", "cell", "position"], { cell: "nope" });
+            },
+        },
+    });
+}

packages/data/src/ecs/database/database.ts

@@ -21,6 +21,7 @@ import type { ConcurrencyStrategy } from "./concurrency/concurrency-strategy.js"
 import { observeSelectDeep as _observeSelectDeep } from "./public/observe-select-deep.js";
 import { ResourceSchemas } from "../resource-schemas.js";
 import { ComponentSchemas } from "../component-schemas.js";
+import { PartitionKeysOf } from "../store/partition.js";
 import { FromSchemas } from "../../schema/index.js";
 import type {
   TransactionDeclarations,
@@ -110,7 +111,8 @@ export interface Database<
   SV = {},
   CV = unknown,
   IX extends IndexDeclarations<C> = {},
-> extends ReadonlyStore<C, R, A, IX>, Service {
+  PK extends string = never,
+> extends ReadonlyStore<C, R, A, IX, PK>, Service {
   readonly transactions: F & Service;
   readonly actions: AF & Service;
   readonly services: SV;
@@ -283,7 +285,8 @@ export namespace Database {
     ToActionFunctions<RemoveIndex<P['actions']>>,
     FromServiceFactories<RemoveIndex<P['services']>>,
     FromComputedFactories<RemoveIndex<P['computed']>>,
-    RemoveIndex<P['indexes']>
+    RemoveIndex<P['indexes']>,
+    PartitionKeysOf<RemoveIndex<P['components']>>
   >;
 
   /**
@@ -311,7 +314,7 @@ export namespace Database {
   // so a `db.derive` on an intersection receiver (see the top-level `derive`
   // signature, which passes `Database.Read<this>`) sees the combined
   // indexes + resources + archetypes, and consumers never need to cast.
-  export type Read<DB extends Database<any, any, any, any, any, any, any, any, any>> =
+  export type Read<DB extends Database<any, any, any, any, any, any, any, any, any, any>> =
     Pick<DB, "get" | "read" | "resources"> & {
       // Presence `select` only — `include` (+ `exclude`), no `where` / `order`.
       // Membership queries are reactively precise (they change only on archetype
@@ -331,7 +334,7 @@ export namespace Database {
         readonly [K in keyof DB["indexes"]]: Omit<DB["indexes"][K], "observe">;
       };
       readonly archetypes: {
-        readonly [K in keyof DB["archetypes"]]: Pick<DB["archetypes"][K], "components" | "id">;
+        readonly [K in keyof DB["archetypes"]]: Pick<DB["archetypes"][K], ("components" | "id") & keyof DB["archetypes"][K]>;
       };
     };
 
@@ -418,7 +421,7 @@ export namespace Database {
      * another plugin's transaction declaration; `ToStore<P>` is the bare
      * store type and does not include `userId`.
      */
-    export type ToTransactionContext<P extends Database.Plugin> = TransactionContext<FromSchemas<RemoveIndex<P['components']>>, FromSchemas<RemoveIndex<P['resources']>>, RemoveIndex<P['archetypes']>>;
+    export type ToTransactionContext<P extends Database.Plugin> = TransactionContext<FromSchemas<RemoveIndex<P['components']>>, FromSchemas<RemoveIndex<P['resources']>>, RemoveIndex<P['archetypes']>, RemoveIndex<P['indexes']>, PartitionKeysOf<RemoveIndex<P['components']>>>;
     export type ToSystemDatabase<P extends Database.Plugin> = Database.FromPlugin<P> & {
       // Systems are allowed to access the database store directly.
       // This direct access will NOT trigger observable transactions.

packages/data/src/ecs/database/index.ts

@@ -9,7 +9,6 @@ export * from "./reconciling/reconciling-entry.js";
 export * from "./observed/create-observed-database.js";
 export * from "./observed/observed-database.js";
 export * from "./database.js";
-export * from "./observe-dependent-value.js";
 export * from "./transactional-store/index.js";
 export * from "./database-schema/index.js";
 export type { Undoable } from "./undoable.js";