@adobe/ecs-persistence 0.0.0-stage → 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

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component, Resource, World } from "@adobe/ecs";
+import type { Persisted } from "./program.js";
+
+/** Where a snapshot holds what it holds, a key only this package uses. */
+export const contents: unique symbol = Symbol("snapshot contents");
+
+/**
+ * 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 = {
+    /** 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

@@ -0,0 +1,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component, Resource, type Schema, type Traits } from "@adobe/ecs";
+
+/** 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 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>>;
+};
+
+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 = 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 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", by);
+    if (typeof resources === "string") return resources;
+    return { by, components, resources };
+};

package/src/selection/selection.ts

@@ -0,0 +1,110 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component, System, type Entity, type Resource, type World } from "@adobe/ecs";
+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`, `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 where?: Where; readonly resources?: boolean }
+    | { readonly root: Entity };
+
+/** 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[];
+};
+
+/** A readonly system reading the tables `declaration` names. */
+const tablesSystemOf = (declaration: Reading) =>
+    System.create({ readonly: true, tables: declaration }, ({ tables }) => tables);
+
+/** The rows of `table` whose entities `keep` takes, as a table of their own. */
+const rowsOf = (table: World.Table, keep: (entity: number) => boolean): World.Table | null => {
+    const rows: number[] = [];
+    for (let row = 0; row < table.count; row++) if (keep(table.entities[row])) rows.push(row);
+    if (rows.length === table.count) return table;
+    if (rows.length === 0) return null;
+    const columns: { [key: symbol]: World.Table.Column } = {};
+    for (const key of Object.getOwnPropertySymbols(table.columns)) {
+        const column: World.Table.Column | undefined = Reflect.get(table.columns, key);
+        if (column === undefined) continue;
+        if (column.kind === "value") columns[key] = column;
+        else if (column.kind === "values") columns[key] = { kind: "values", values: rows.map(row => column.values[row]) };
+        else {
+            const { stride } = column;
+            const bytes = new Uint8Array(rows.length * stride);
+            rows.forEach((row, at) => bytes.set(column.bytes.subarray(row * stride, (row + 1) * stride), at * stride));
+            columns[key] = { kind: "bytes", bytes, stride };
+        }
+    }
+    return { count: rows.length, entities: Float64Array.from(rows, row => table.entities[row]), columns };
+};
+
+/** The entities `root` owns, itself included, through the owner references among `owners` in the tables. */
+const subtreeOf = (tables: readonly World.Table[], owners: readonly Component.Key[], root: Entity): ReadonlySet<number> => {
+    const children = new Map<number, number[]>();
+    for (const table of tables) {
+        for (const reference of owners) {
+            const key: symbol = reference;
+            const column: World.Table.Column | undefined = Reflect.get(table.columns, key);
+            if (column?.kind !== "bytes") continue;
+            const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
+            for (let row = 0; row < table.count; row++) {
+                const owner = view.getFloat64(row * column.stride, true);
+                const list = children.get(owner);
+                if (list === undefined) children.set(owner, [table.entities[row]]);
+                else list.push(table.entities[row]);
+            }
+        }
+    }
+    const taken = new Set<number>([root]);
+    const waiting: number[] = [root];
+    for (let next = waiting.pop(); next !== undefined; next = waiting.pop()) {
+        for (const child of children.get(next) ?? []) {
+            if (taken.has(child)) continue;
+            taken.add(child);
+            waiting.push(child);
+        }
+    }
+    return taken;
+};
+
+/** 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);
+    const subtree = "root" in selection;
+    const resources = subtree || selection.resources === false ? [] : [...program.resources.values()];
+    const declaration: Reading = subtree
+        ? { components: keys }
+        : { 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) {
+        const owners = keys.filter(key => Component.declarations().get(key)?.reference === "owner");
+        const taken = subtreeOf(tables, owners, selection.root);
+        tables = tables.flatMap(table => rowsOf(table, entity => taken.has(entity)) ?? []);
+    }
+    return { by: program.by, components, tables, resources: resources.map(persisted => ({ persisted, value: read.resources[persisted.key] })) };
+};

package/src/snapshot.ts

@@ -0,0 +1,30 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { World } from "@adobe/ecs";
+import type { Failure } from "./failure.js";
+import { contents, type Contents } from "./program/contents.js";
+import { programOf, type NamingTrait } from "./program/program.js";
+import { select, type Selection } from "./selection/selection.js";
+
+/**
+ * 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 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; 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

@@ -0,0 +1,79 @@
+// © 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, 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> });
+
+const isTables = (value: unknown): value is readonly World.Table[] => Array.isArray(value) && value.every(table =>
+    typeof table === "object" && table !== null && typeof Reflect.get(table, "count") === "number" && Reflect.get(table, "entities") instanceof Float64Array
+    && typeof Reflect.get(table, "columns") === "object");
+
+const isKeyed = (value: unknown): value is { readonly [key: symbol]: unknown } => typeof value === "object" && value !== null;
+
+/** `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 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`.
+ * - `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: 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 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) };
+}
+
+/** 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) => {
+        const made = spawned[t];
+        for (let row = 0; row < table.count; row++) {
+            // A table's entities and `spawnTables`' are entities, `Entity.none`, 0, for a row it didn't spawn.
+            const entity = made[row] as Entity;
+            entities.set(table.entities[row] as Entity, entity === 0 ? null : entity);
+        }
+    });
+    return entities;
+};

package/src/values/values.ts

@@ -0,0 +1,97 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "@adobe/ecs";
+
+// Values of components stored as values, strings and other data that isn't a fixed layout, as JSON their schema reads
+// back: a map as its entries, a set as its items, numbers JSON lacks as text, and a union's value as its member's
+// index and its JSON.
+
+/** A number JSON can't hold, as text: `NaN`, `Infinity`, `-Infinity` or `-0`. */
+const numberToJson = (value: number): number | string =>
+    Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : value === -Infinity ? "-Infinity" : Object.is(value, -0) ? "-0" : value;
+
+const numberFromJson = (json: unknown): unknown => {
+    if (typeof json !== "string") return json;
+    switch (json) {
+        case "NaN": return NaN;
+        case "Infinity": return Infinity;
+        case "-Infinity": return -Infinity;
+        case "-0": return -0;
+        default: return json;
+    }
+};
+
+/** Whether a value is of the JSON kind a schema's values are, to pick a union's member. */
+const fits = (schema: Schema, value: unknown): boolean => {
+    if ("const" in schema) return Object.is(schema.const, value) || JSON.stringify(schema.const) === JSON.stringify(value);
+    if ("anyOf" in schema) return schema.anyOf.some(member => fits(member, value));
+    if ("allOf" in schema) return schema.allOf.every(member => fits(member, value));
+    if (!("type" in schema)) return true;
+    switch (schema.type) {
+        case "number": case "integer": return typeof value === "number";
+        case "string": return typeof value === "string";
+        case "boolean": return typeof value === "boolean";
+        case "null": return value === null;
+        case "array": return Array.isArray(value);
+        case "set": return value instanceof Set;
+        case "map": return value instanceof Map;
+        case "object": return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Set) && !(value instanceof Map);
+        default: return true;
+    }
+};
+
+/** A value of `schema` as JSON. */
+export const toJson = (schema: Schema, value: unknown): unknown => {
+    if ("anyOf" in schema) {
+        const index = schema.anyOf.findIndex(candidate => fits(candidate, value));
+        const member = schema.anyOf[index];
+        return member === undefined ? [-1, value] : [index, toJson(member, value)];
+    }
+    if (typeof value === "number") return numberToJson(value);
+    if (!("type" in schema)) return value;
+    switch (schema.type) {
+        case "array": return Array.isArray(value) ? value.map(item => toJson(schema.items, item)) : value;
+        case "set": return value instanceof Set ? Array.from(value, item => toJson(schema.items, item)) : value;
+        case "map": return value instanceof Map ? Array.from(value, ([key, item]) => [toJson(schema.keys, key), toJson(schema.values, item)]) : value;
+        case "object": {
+            if (typeof value !== "object" || value === null) return value;
+            const json: { [name: string]: unknown } = {};
+            for (const name of Object.keys(value)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(value, name);
+                if (item !== undefined) json[name] = field === undefined ? item : toJson(field, item);
+            }
+            return json;
+        }
+        default: return value;
+    }
+};
+
+/** A value of `schema` read back from its JSON. */
+export const fromJson = (schema: Schema, json: unknown): unknown => {
+    if ("anyOf" in schema) {
+        if (!Array.isArray(json) || typeof json[0] !== "number") return json;
+        const member = schema.anyOf[json[0]];
+        return member === undefined ? json[1] : fromJson(member, json[1]);
+    }
+    if ("const" in schema) return schema.const;
+    if (!("type" in schema)) return json;
+    switch (schema.type) {
+        case "number": case "integer": return numberFromJson(json);
+        case "array": return Array.isArray(json) ? json.map(item => fromJson(schema.items, item)) : json;
+        case "set": return Array.isArray(json) ? new Set(json.map(item => fromJson(schema.items, item))) : json;
+        case "map": return Array.isArray(json)
+            ? new Map(json.map(entry => Array.isArray(entry) ? [fromJson(schema.keys, entry[0]), fromJson(schema.values, entry[1])] : [entry, undefined]))
+            : json;
+        case "object": {
+            if (typeof json !== "object" || json === null || Array.isArray(json)) return json;
+            const value: { [name: string]: unknown } = {};
+            for (const name of Object.keys(json)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(json, name);
+                value[name] = field === undefined ? item : fromJson(field, item);
+            }
+            return value;
+        }
+        default: return json;
+    }
+};