@adobe/ecs-persistence 0.0.1 → 0.1.0

package/src/match/keys.ts

@@ -0,0 +1,105 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/** A table's key, a column of bytes for each part, `stride` bytes per row: a row's key is its bytes in each. */
+export type KeyColumns = readonly { readonly bytes: Uint8Array; readonly stride: number }[];
+
+/**
+ * Keys of rows of tables, each with a number: an open-addressing table of slots, linear probing, at most half full,
+ * each slot two words, a key's hash and its entry plus one, or 0 for none, so a probe reads its slots until a hash
+ * matches. An entry is a row of the tables it was added from, whose bytes are its key.
+ */
+export type KeyTable = {
+    readonly mask: number;
+    readonly slots: Int32Array;
+    readonly tables: Int32Array;
+    readonly rows: Int32Array;
+    readonly values: Float64Array;
+    readonly columns: KeyColumns[];
+    count: number;
+};
+
+/** A table for up to `capacity` keys. */
+export const createKeyTable = (capacity: number): KeyTable => {
+    let size = 16;
+    while (size < 2 * capacity) size *= 2;
+    return {
+        mask: size - 1,
+        slots: new Int32Array(2 * size),
+        tables: new Int32Array(capacity),
+        rows: new Int32Array(capacity),
+        values: new Float64Array(capacity),
+        columns: [],
+        count: 0,
+    };
+};
+
+/** FNV-1a over a row's bytes in each column, then mixed so its low bits, which pick a slot, depend on all of them. */
+const hashOf = (columns: KeyColumns, row: number): number => {
+    let hash = 0x811c9dc5;
+    for (let c = 0; c < columns.length; c++) {
+        const { bytes, stride } = columns[c];
+        for (let at = row * stride, end = at + stride; at < end; at++) hash = Math.imul(hash ^ bytes[at], 0x01000193);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x85ebca6b);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 0xc2b2ae35);
+    return hash ^ (hash >>> 16);
+};
+
+const equalAt = (a: KeyColumns, rowA: number, b: KeyColumns, rowB: number): boolean => {
+    if (a.length !== b.length) return false;
+    for (let c = 0; c < a.length; c++) {
+        const { bytes: left, stride } = a[c];
+        const { bytes: right, stride: other } = b[c];
+        if (stride !== other) return false;
+        for (let k = 0, i = rowA * stride, j = rowB * stride; k < stride; k++) if (left[i + k] !== right[j + k]) return false;
+    }
+    return true;
+};
+
+/** The slot holding `row`'s key, or the empty one where it would go. */
+const slotOf = (table: KeyTable, columns: KeyColumns, row: number, hash: number): number => {
+    const { mask, slots, tables, rows } = table;
+    for (let slot = hash & mask; ; slot = (slot + 1) & mask) {
+        const entry = slots[2 * slot + 1] - 1;
+        if (entry < 0) return slot;
+        if (slots[2 * slot] === hash && equalAt(table.columns[tables[entry]], rows[entry], columns, row)) return slot;
+    }
+};
+
+/**
+ * Begins adding the rows of a table of `columns`; `addKey` then takes rows of it. Each table's columns are kept, since
+ * its entries' keys are their rows' bytes.
+ */
+export const addKeyColumns = (table: KeyTable, columns: KeyColumns): void => {
+    table.columns.push(columns);
+};
+
+/**
+ * Adds row `row` of the table `addKeyColumns` began last, with `value`, unless a key equal to its is there: whether
+ * it was added. Takes at most the capacity the table was created with.
+ */
+export const addKey = (table: KeyTable, row: number, value: number): boolean => {
+    const at = table.columns.length - 1;
+    const columns = table.columns[at];
+    const hash = hashOf(columns, row);
+    const slot = slotOf(table, columns, row, hash);
+    if (table.slots[2 * slot + 1] !== 0) return false;
+    const entry = table.count++;
+    table.slots[2 * slot] = hash;
+    table.slots[2 * slot + 1] = entry + 1;
+    table.tables[entry] = at;
+    table.rows[entry] = row;
+    table.values[entry] = value;
+    return true;
+};
+
+/**
+ * The entry whose key is equal to row `row`'s of `columns`, or -1 for none. `guess` is an entry to compare first, such
+ * as the one after the entry found for the row before: rows in the order they were added are found without hashing.
+ */
+export const findKey = (table: KeyTable, columns: KeyColumns, row: number, guess: number): number => {
+    if (guess >= 0 && guess < table.count && equalAt(table.columns[table.tables[guess]], table.rows[guess], columns, row)) return guess;
+    return table.slots[2 * slotOf(table, columns, row, hashOf(columns, row)) + 1] - 1;
+};

package/src/match/match.ts

@@ -0,0 +1,165 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Index, System, type Component, type Schema, type World } from "@adobe/ecs";
+import type { Failure } from "../failure.js";
+import type { Contents } from "../program/contents.js";
+import { toJson } from "../values/values.js";
+import { addKey, addKeyColumns, createKeyTable, findKey, type KeyColumns } from "./keys.js";
+
+/** An index whose entities are the same in two worlds where their keys are: a unique one. */
+export type Matching = Index<{ readonly unique: true }>;
+
+/** What a match reads of a world: the tables of the entities an index holds, with its key's columns. */
+const keysSystemOf = (declaration: Index.Declared) => System.create({
+    readonly: true,
+    tables: { components: declaration.key, with: [...declaration.key, ...declaration.components.with ?? []], not: declaration.components.not ?? [] },
+}, ({ tables }) => tables.archetypes);
+
+/** A part of an index's key: its component, and that component's schema as the snapshot holds it. */
+type Part = { readonly key: Component.Key; readonly schema: Schema };
+
+/** Bytes as text, a character each, so equal bytes give equal text and a row's are a slice of its column's. */
+const bytesDecoder = new TextDecoder("latin1");
+
+/**
+ * Each row's key in a table, as text, or null for a table without a column of each part: each part's column, its bytes
+ * in the world's layout, which two worlds of one program share, or its value as JSON by its schema. Equal keys give
+ * equal text.
+ */
+const keysOf = (table: World.Table, parts: readonly Part[]): ((row: number) => string) | null => {
+    const columns: ((row: number) => string)[] = [];
+    for (const { key, schema } of parts) {
+        const column = table.columns[key];
+        if (column === undefined) return null;
+        if (column.kind === "bytes") {
+            const text = bytesDecoder.decode(column.bytes);
+            const { stride } = column;
+            columns.push(row => text.slice(row * stride, (row + 1) * stride));
+        }
+        else if (column.kind === "values") columns.push(row => JSON.stringify(toJson(schema, column.values[row])));
+        else {
+            const text = JSON.stringify(toJson(schema, column.value));
+            columns.push(() => text);
+        }
+    }
+    const [only] = columns;
+    return columns.length === 1 && only !== undefined ? only : row => columns.map(part => part(row)).join("\u0000");
+};
+
+/** Whether a table holds the entities an index holds: every key part and `with` component, and none in `not`. */
+const covers = (table: World.Table, declaration: Index.Declared): boolean =>
+    [...declaration.key, ...declaration.components.with ?? []].every(key => table.columns[key] !== undefined)
+    && (declaration.components.not ?? []).every(key => table.columns[key] === undefined);
+
+/**
+ * Adds to `existing` each of the snapshot's entities an index holds, to the world's with its key, or fails, as data,
+ * for two of the snapshot's with one key; `name` is the index's.
+ */
+type Matched = (name: string, existing: Map<number, number>) => Promise<Failure | undefined>;
+
+const twoWithOneKey = (name: string): Failure => ({ failure: `Index "${name}" can't match: two of the snapshot's entities have one key.` });
+
+const readWorld = (world: World, declaration: Index.Declared): Promise<readonly World.Table[] | Failure> =>
+    world.run(keysSystemOf(declaration)).catch((error: unknown) => ({ failure: error instanceof Error ? error.message : String(error) }));
+
+/** Two of the world's entities with one key: the one with the lower entity index, as its unique index keeps. */
+const keep = (existing: Map<number, number>, entity: number, candidate: number): void => {
+    const kept = existing.get(entity);
+    if (kept === undefined || (candidate >>> 0) < (kept >>> 0)) existing.set(entity, candidate);
+};
+
+/** A table's columns of each part, or null for one without a column of bytes for each. */
+const bytesOf = (table: World.Table, parts: readonly Part[]): KeyColumns | null => {
+    const columns: KeyColumns[number][] = [];
+    for (const { key } of parts) {
+        const column = table.columns[key];
+        if (column === undefined || column.kind !== "bytes") return null;
+        columns.push(column);
+    }
+    return columns;
+};
+
+/**
+ * Matches by the bytes of keys' columns, without making text of them, when every table of the snapshot holding the
+ * index's entities has columns of bytes for its key; null otherwise. The world's tables, of the same program, then do too.
+ */
+const matchBytes = (world: World, from: Contents, declaration: Index.Declared, parts: readonly Part[]): Matched | null => {
+    const tables = from.tables.filter(table => covers(table, declaration));
+    const columns = tables.map(table => bytesOf(table, parts));
+    if (columns.some(item => item === null)) return null;
+    return async (name, existing) => {
+        const saved = createKeyTable(tables.reduce((sum, table) => sum + table.count, 0));
+        for (let t = 0; t < tables.length; t++) {
+            const keys = columns[t];
+            if (keys === null) continue;
+            addKeyColumns(saved, keys);
+            const { entities, count } = tables[t];
+            for (let row = 0; row < count; row++) if (!addKey(saved, row, entities[row])) return twoWithOneKey(name);
+        }
+        if (saved.count === 0) return undefined;
+        const read = await readWorld(world, declaration);
+        if ("failure" in read) return read;
+        for (const table of read) {
+            const keys = bytesOf(table, parts);
+            if (keys === null) continue;
+            for (let row = 0, entry = -1; row < table.count; row++) {
+                entry = findKey(saved, keys, row, entry + 1);
+                if (entry >= 0) keep(existing, saved.values[entry], table.entities[row]);
+            }
+        }
+        return undefined;
+    };
+};
+
+/** Matches by keys as text, which any column gives. */
+const matchText = (world: World, from: Contents, declaration: Index.Declared, parts: readonly Part[]): Matched => async (name, existing) => {
+    const saved = new Map<string, number>();
+    for (const table of from.tables) {
+        if (!covers(table, declaration)) continue;
+        const keyAt = keysOf(table, parts);
+        if (keyAt === null) continue;
+        for (let row = 0; row < table.count; row++) {
+            const key = keyAt(row);
+            if (saved.has(key)) return twoWithOneKey(name);
+            saved.set(key, table.entities[row]);
+        }
+    }
+    if (saved.size === 0) return undefined;
+    const read = await readWorld(world, declaration);
+    if ("failure" in read) return read;
+    for (const table of read) {
+        const keyAt = keysOf(table, parts);
+        if (keyAt === null) continue;
+        for (let row = 0; row < table.count; row++) {
+            const entity = saved.get(keyAt(row));
+            if (entity !== undefined) keep(existing, entity, table.entities[row]);
+        }
+    }
+    return undefined;
+};
+
+/**
+ * Each of the snapshot's entities that `indexes` say is the same as one of `world`'s, to that one: an index holds both,
+ * with equal keys. Fails, as data, for an index whose key, `with` or `not` names a component the snapshot's trait doesn't
+ * cover, or two of the snapshot's entities one index holds with one key.
+ */
+export const existingFor = async (world: World, from: Contents, indexes: readonly Matching[]): Promise<ReadonlyMap<number, number> | Failure> => {
+    const existing = new Map<number, number>();
+    const persisted = new Map(from.components.map(item => [item.key, item]));
+    for (const index of indexes) {
+        const declaration = Index.declarationOf(index);
+        if (declaration === undefined) return { failure: `${index.name} isn't an index.` };
+        const parts: Part[] = [];
+        for (const key of declaration.key) {
+            const found = persisted.get(key);
+            if (found === undefined) return { failure: `Index "${index.name}" can't match: a part of its key isn't one the snapshot's trait covers, so the snapshot holds no key for it.` };
+            parts.push({ key, schema: found.schema });
+        }
+        if ([...declaration.components.with ?? [], ...declaration.components.not ?? []].some(key => !persisted.has(key))) {
+            return { failure: `Index "${index.name}" can't match: its with or not names a component the snapshot's trait doesn't cover, so the snapshot can't tell which of its entities the index holds.` };
+        }
+        const matched = matchBytes(world, from, declaration, parts) ?? matchText(world, from, declaration, parts);
+        const found = await matched(index.name, existing);
+        if (found !== undefined) return found;
+    }
+    return existing;
+};

package/src/program/contents.ts

@@ -6,11 +6,13 @@ import type { Persisted } from "./program.js";
 export const contents: unique symbol = Symbol("snapshot contents");
 
 /**
- * The persisted part of some of a world's entities: of each archetype, its entities and a column of each persisted
- * component it holds, keyed by this program's keys; and the values of persisted resources.
+ * What a trait covers of some of a world's entities: of each archetype, its entities and a column of each component
+ * the trait covers that it holds, keyed by this program's keys; and the values of the resources it covers.
  */
 export type Contents = {
-    /** Each persisted component a table of it may hold. */
+    /** The key of the trait it was taken or read by. */
+    readonly by: symbol;
+    /** Each component the trait covers that a table of it may hold. */
     readonly components: readonly Persisted<Component.Key>[];
     readonly tables: readonly World.Table[];
     readonly resources: readonly { readonly persisted: Persisted<Resource.Key>; readonly value: unknown }[];

package/src/program/program.ts

@@ -1,34 +1,45 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-import { Component, Resource, type Schema } from "@adobe/ecs";
-import { persist } from "../persist.js";
+import { Component, Resource, type Schema, type Traits } from "@adobe/ecs";
 
-/** A key persisted, with its name and schema. */
+/** A key a trait covers, with the name the trait saves it under and its schema. */
 export type Persisted<K extends symbol = symbol> = { readonly name: string; readonly key: K; readonly schema: Schema };
 
-/** What the program persists: its components and resources by name. */
+/** What a trait covers: its components and resources by name. */
 export type Program = {
+    readonly by: symbol;
     readonly components: ReadonlyMap<string, Persisted<Component.Key>>;
     readonly resources: ReadonlyMap<string, Persisted<Resource.Key>>;
 };
 
-/** The keys of `declarations` with a `persist` trait by name, or why one can't persist: it isn't data, or a name is taken. */
-const namedIn = <K extends symbol>(declarations: ReadonlyMap<K, Component.Declared>, kind: string): ReadonlyMap<string, Persisted<K>> | string => {
+type Keyed = Component.Key | Resource.Key;
+
+/** A trait of an application's own whose value names a key: its key a symbol, its value a string. */
+export type NamingTrait = { readonly [T in keyof Traits<Keyed>]: T extends symbol ? [Traits<Keyed>[T]] extends [string] ? T : never : never }[keyof Traits<Keyed>];
+
+/**
+ * The keys of `declarations` with the trait `by`, by the name it gives each, or why one can't be saved: the trait's
+ * value isn't a string, or the key isn't data, is derived, or has a name another has.
+ */
+const namedIn = <K extends symbol>(declarations: ReadonlyMap<K, Component.Declared>, kind: string, by: symbol): ReadonlyMap<string, Persisted<K>> | string => {
     const named = new Map<string, Persisted<K>>();
     for (const [key, declaration] of declarations) {
-        const name: unknown = declaration[persist];
-        if (typeof name !== "string") continue;
-        if (declaration.type === undefined) return `The ${kind} persisted as "${name}" isn't data: it has no schema.`;
-        if (named.has(name)) return `Two ${kind}s are persisted as "${name}".`;
+        const name: unknown = Reflect.get(declaration, by);
+        if (name === undefined) continue;
+        if (typeof name !== "string") return `A ${kind}'s value of the trait isn't a name: ${String(name)}.`;
+        if (declaration.type === undefined) return `The ${kind} the trait names "${name}" isn't data: it has no schema.`;
+        if (declaration.derived === true) return `The ${kind} the trait names "${name}" is derived, which its rule derives again once its entity is loaded.`;
+        if (named.has(name)) return `The trait names two ${kind}s "${name}".`;
         named.set(name, { name, key, schema: declaration.type });
     }
     return named;
 };
 
-/** What the program persists, as its modules registered so far declare it, or why it can't. */
-export const programOf = (): Program | string => {
-    const components = namedIn(Component.declarations(), "component");
+/** What the trait `by` covers, as the modules registered so far declare it, or why it can't be saved. */
+export const programOf = (by: unknown): Program | string => {
+    if (typeof by !== "symbol") return "`by` is the key of the trait to save by, a symbol.";
+    const components = namedIn(Component.declarations(), "component", by);
     if (typeof components === "string") return components;
-    const resources = namedIn(Resource.declarations(), "resource");
+    const resources = namedIn(Resource.declarations(), "resource", by);
     if (typeof resources === "string") return resources;
-    return { components, resources };
+    return { by, components, resources };
 };

package/src/selection/selection.ts

@@ -4,19 +4,24 @@ import type { Failure } from "../failure.js";
 import type { Contents } from "../program/contents.js";
 import type { Program } from "../program/program.js";
 
+/** Values of shared components, which archetypes hold one of each: `where` as a system's of values. */
+type Where = { readonly [K in Component.With<"shared">]?: Component<K> };
+
 /**
- * Which entities a snapshot takes: those matching `with` and `not`, every one holding a persisted component by
- * default; or `root` and every entity it owns, directly or through others, by persisted owner references.
+ * Which entities a snapshot takes: those matching `with`, `not` and `where`, every one holding a component its trait
+ * covers by default; or `root` and every entity it owns, directly or through others, by owner references its trait
+ * covers.
  */
 export type Selection =
-    | { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly resources?: boolean }
+    | { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly where?: Where; readonly resources?: boolean }
     | { readonly root: Entity };
 
-/** Which tables a snapshot reads: those of its persisted components, matching `with` and `not`, and its resources. */
+/** Which tables a snapshot reads: those of the components its trait covers, matching `with`, `not` and `where`, and its resources. */
 type Reading = {
     readonly components: readonly Component.Key[];
     readonly with?: readonly Component.Key[];
     readonly not?: readonly Component.Key[];
+    readonly where?: Where;
     readonly resources?: readonly Resource.Key[];
 };
 
@@ -75,7 +80,7 @@ const subtreeOf = (tables: readonly World.Table[], owners: readonly Component.Ke
     return taken;
 };
 
-/** The persisted part of the entities `selection` takes from `world`, on its thread, or why it can't be read. */
+/** What `program`'s trait covers of the entities `selection` takes from `world`, on its thread, or why it can't be read. */
 export const select = async (world: World, program: Program, selection: Selection): Promise<Contents | Failure> => {
     const components = [...program.components.values()];
     const keys = components.map(persisted => persisted.key);
@@ -83,8 +88,17 @@ export const select = async (world: World, program: Program, selection: Selectio
     const resources = subtree || selection.resources === false ? [] : [...program.resources.values()];
     const declaration: Reading = subtree
         ? { components: keys }
-        : { components: keys, with: selection.with ?? [], not: selection.not ?? [], resources: resources.map(persisted => persisted.key) };
-    const read = await world.run(tablesSystemOf(declaration)).catch((error: unknown) => ({ failure: error instanceof Error ? error.message : String(error) }));
+        : { components: keys, with: selection.with ?? [], not: selection.not ?? [], where: selection.where ?? {}, resources: resources.map(persisted => persisted.key) };
+    const failed = (error: unknown): Failure => ({ failure: error instanceof Error ? error.message : String(error) });
+    let system: ReturnType<typeof tablesSystemOf>;
+    try {
+        system = tablesSystemOf(declaration);
+    }
+    catch (error) {
+        // A `where` naming what isn't a shared component, or giving one a value not of its type.
+        return failed(error);
+    }
+    const read = await world.run(system).catch(failed);
     if ("failure" in read) return read;
     let tables = read.archetypes;
     if (subtree) {
@@ -92,5 +106,5 @@ export const select = async (world: World, program: Program, selection: Selectio
         const taken = subtreeOf(tables, owners, selection.root);
         tables = tables.flatMap(table => rowsOf(table, entity => taken.has(entity)) ?? []);
     }
-    return { components, tables, resources: resources.map(persisted => ({ persisted, value: read.resources[persisted.key] })) };
+    return { by: program.by, components, tables, resources: resources.map(persisted => ({ persisted, value: read.resources[persisted.key] })) };
 };

package/src/snapshot.ts

@@ -2,20 +2,28 @@
 import type { World } from "@adobe/ecs";
 import type { Failure } from "./failure.js";
 import { contents, type Contents } from "./program/contents.js";
-import { programOf } from "./program/program.js";
+import { programOf, type NamingTrait } from "./program/program.js";
 import { select, type Selection } from "./selection/selection.js";
 
-/** The persisted part of some of a world's entities and its persisted resources, which `encode` and `spawn` take. */
+/**
+ * What a trait covers of some of a world's entities and of its resources, which `encode` and `spawn` take, and the
+ * trait it was taken or read by.
+ */
 export type Snapshot = { readonly failure?: undefined; readonly [contents]: Contents };
 
 /**
- * A snapshot of some of `world`'s entities, read on its thread: by default every entity holding a persisted
- * component, and the persisted resources; with `with` and `not`, those a query matches, and the resources unless
- * `resources` is false; with `root`, it and every entity it owns, through persisted owner references, without
- * resources. Fails, as data, when the program's persisted keys can't be saved or the world can't be read.
+ * A snapshot of some of `world`'s entities, read on its thread, by the trait `by`: a trait of the application's own,
+ * whose value on a component's or resource's declaration is the name it's saved under. Of each entity it takes, it
+ * takes the components the trait covers. By default it takes every entity holding one of them, and the resources the
+ * trait covers; with `with` and `not`, those a query matches, and the resources unless `resources` is false; with
+ * `where`, those of the archetypes holding its values of shared components, as a system's `where` of values keeps it to
+ * them, read whole, so a snapshot of one value's entities costs what they hold, not the world; with `root`, it and every
+ * entity it owns, through owner references the trait covers, without resources. Fails, as data, when `by` isn't a
+ * symbol, what the trait covers can't be saved, `where` names what isn't a shared component or gives one a value not
+ * of its type, or the world can't be read.
  */
-export const snapshot = async (input: { readonly world: World } & Selection): Promise<Snapshot | Failure> => {
-    const program = programOf();
+export const snapshot = async (input: { readonly world: World; readonly by: NamingTrait } & Selection): Promise<Snapshot | Failure> => {
+    const program = programOf(input.by);
     if (typeof program === "string") return { failure: program };
     const taken = await select(input.world, program, input);
     return "failure" in taken ? taken : { [contents]: taken };

package/src/spawn.ts

@@ -1,13 +1,14 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { System, type Entity, type World } from "@adobe/ecs";
 import type { Failure } from "./failure.js";
+import { existingFor, type Matching } from "./match/match.js";
 import { contents } from "./program/contents.js";
 import type { Snapshot } from "./snapshot.js";
 
 /**
  * What `spawn` made: how many of the snapshot's entities it didn't spawn, those owned by an entity outside it; and,
- * unless asked not to, `entities`, each of the snapshot's entities to the one spawned for it, or null for one it
- * didn't spawn.
+ * unless asked not to, `entities`, each of the snapshot's entities to the one spawned for it, the one `match` found
+ * for it, or null for one it didn't spawn.
  */
 export type Spawned<Entities extends boolean = true> = { readonly failure?: undefined; readonly dropped: number }
     & (Entities extends false ? {} : { readonly entities: ReadonlyMap<Entity, Entity | null> });
@@ -18,34 +19,52 @@ const isTables = (value: unknown): value is readonly World.Table[] => Array.isAr
 
 const isKeyed = (value: unknown): value is { readonly [key: symbol]: unknown } => typeof value === "object" && value !== null;
 
-/** Spawns its input's tables and sets its resources, a snapshot's, rewriting their entities. */
-const spawnTables = System.create({}, ({ commands }, input: { readonly tables: unknown; readonly resources: unknown }) => {
-    if (!isTables(input.tables) || !isKeyed(input.resources)) throw new Error("A snapshot holds tables and resources.");
-    return commands.spawnTables(input.tables, input.resources);
+/** `spawnTables` takes entities by their numbers: a map of the snapshot's to the world's holds only numbers. */
+const isEntities = (value: unknown): value is ReadonlyMap<Entity, Entity> => {
+    if (!(value instanceof Map)) return false;
+    for (const [saved, found] of value) if (typeof saved !== "number" || typeof found !== "number") return false;
+    return true;
+};
+
+/** Spawns its input's tables and sets its resources, a snapshot's, rewriting their entities, those `existing` maps standing for theirs. */
+const spawnTables = System.create({}, ({ commands }, input: { readonly tables: unknown; readonly resources: unknown; readonly existing: unknown }) => {
+    if (!isTables(input.tables) || !isKeyed(input.resources) || !isEntities(input.existing)) throw new Error("A snapshot holds tables and resources.");
+    return commands.spawnTables(input.tables, { resources: input.resources, existing: input.existing });
 });
 
 /**
- * Spawns an entity in `world` for each of the snapshot's, with its persisted components, and sets the persisted
- * resources, on the world's thread, as the world's references would leave them had the entities outside the snapshot
+ * Spawns an entity in `world` for each of the snapshot's, with the components its trait covers, and sets the resources
+ * it holds, on the world's thread, as the world's references would leave them had the entities outside the snapshot
  * despawned: each entity value naming one of the snapshot's names the one spawned for it; an entity owned, directly
  * or through others, by an entity outside the snapshot isn't spawned, which the result counts; a weak reference to
- * one is left out; and any other entity value naming one is `Entity.none`. With `entities: false`, the result leaves
- * out its map of entities, which costs about 85 ms and 50 MB at a million. Fails, as data, for a column or
- * resource that doesn't fit, spawning nothing.
+ * one is left out; and any other entity value naming one is `Entity.none`.
+ * - `match`: unique indexes saying which of the snapshot's entities are already in `world`: one an index holds there,
+ *   with the key of one of the snapshot's it holds, stands for it, keeping its own values, and isn't spawned again. It
+ *   fails for an index whose key, `with` or `not` names a component the snapshot's trait doesn't cover, or two of the
+ *   snapshot's entities with one key.
+ * - `entities: false` leaves out the result's map of entities, which costs about 85 ms and 50 MB at a million.
+ *
+ * Fails, as data, for a column or resource that doesn't fit, spawning nothing.
  */
-export function spawn(input: { readonly world: World; readonly snapshot: Snapshot; readonly entities: false }): Promise<Spawned<false> | Failure>;
-export function spawn(input: { readonly world: World; readonly snapshot: Snapshot; readonly entities?: true }): Promise<Spawned | Failure>;
-export async function spawn(input: { readonly world: World; readonly snapshot: Snapshot; readonly entities?: boolean }): Promise<Spawned<boolean> | Failure> {
-    const { tables, resources } = input.snapshot[contents];
+export function spawn(input: Spawning & { readonly entities: false }): Promise<Spawned<false> | Failure>;
+export function spawn(input: Spawning & { readonly entities?: true }): Promise<Spawned | Failure>;
+export async function spawn(input: Spawning & { readonly entities?: boolean }): Promise<Spawned<boolean> | Failure> {
+    const from = input.snapshot[contents];
+    const { tables, resources } = from;
     const values: { [key: symbol]: unknown } = {};
     for (const { persisted, value } of resources) values[persisted.key] = value;
-    const spawned = await input.world.run(spawnTables, { tables, resources: values }).catch((error: unknown) => ({ failure: error instanceof Error ? error.message : String(error) }));
+    const existing = input.match === undefined || input.match.length === 0 ? new Map<number, number>() : await existingFor(input.world, from, input.match);
+    if ("failure" in existing) return existing;
+    const spawned = await input.world.run(spawnTables, { tables, resources: values, existing }).catch((error: unknown) => ({ failure: error instanceof Error ? error.message : String(error) }));
     if ("failure" in spawned) return spawned;
     if (input.entities === false) return { dropped: spawned.dropped };
     return { dropped: spawned.dropped, entities: entitiesOf(tables, spawned.entities) };
 }
 
-/** Each of the tables' entities to the one spawned for it, or null for one that wasn't. */
+/** What `spawn` takes: the world spawned into, the snapshot, and the indexes saying which of its entities are there already. */
+type Spawning = { readonly world: World; readonly snapshot: Snapshot; readonly match?: readonly Matching[] };
+
+/** Each of the tables' entities to the one spawned for it, the one existing for it, or null for one that wasn't. */
 const entitiesOf = (tables: readonly World.Table[], spawned: readonly Float64Array[]): ReadonlyMap<Entity, Entity | null> => {
     const entities = new Map<Entity, Entity | null>();
     tables.forEach((table, t) => {

package/src/persist.ts

@@ -1,15 +0,0 @@
-// © 2026 Adobe. MIT License. See /LICENSE for details.
-import type { Component, Components } from "@adobe/ecs";
-
-/**
- * The trait marking a component or resource to persist, its value the stable name saved data names it by: unlike its
- * key's id, the name stays the same across versions and moves of its module. Not on a derived component, which its
- * rule derives again once its entity is loaded.
- */
-export const persist = Symbol();
-
-declare module "@adobe/ecs" {
-    interface Traits<N> {
-        readonly [persist]: N extends Component.Key ? Components[N] extends { readonly derived: true } ? never : string : string;
-    }
-}