zerodrift 1.0.0

package/dist/schema/compile.js

@@ -0,0 +1,334 @@
+import { BaseModel } from "../core/BaseModel";
+import { hashString } from "../core/hash";
+import { ModelRegistry } from "../core/ModelRegistry";
+import { defineObservableProperty } from "../core/observability";
+import { installCollectionAccessor, installReferenceAccessor, } from "../core/refAccessors";
+import { PropertyType } from "../core/types";
+/**
+ * Compile a `SchemaDef` produced by `defineSchema(...)` into the existing
+ * `ModelRegistry`. Each schema entity becomes a synthetic `BaseModel`
+ * subclass, registered under its PascalCased key (or `entity({ name })`
+ * override). After this returns, `ModelRegistry`, `StoreManager`, and the
+ * sync runtime see schema-defined models exactly the way they see
+ * decorator-defined ones.
+ *
+ * The function is pure with respect to the input `schema` object, but
+ * registers globally as a side effect — same contract as `@ClientModel`.
+ * Validation runs before any registry mutation; on failure the registry
+ * is untouched.
+ *
+ * The four passes below have an ordering dependency: ctors must be created
+ * before their fields can carry resolved `referenceTo` registry names; fields
+ * must exist before `registerLink` can `updateProperty` the FK; and the
+ * per-entity hash must run last so it captures every link side-effect.
+ */
+export function compileSchema(schema) {
+    validateSchema(schema);
+    const nameByKey = resolveNames(schema);
+    const ctorByKey = new Map();
+    const externalKeys = collectExternalKeys(schema);
+    for (const [key, entityDef] of Object.entries(schema.entities)) {
+        if (externalKeys.has(key)) {
+            continue;
+        }
+        const name = nameByKey.get(key);
+        const ctor = createSyntheticClass(name, entityDef);
+        ctorByKey.set(key, ctor);
+        const meta = ModelRegistry.registerModel(name, ctor);
+        meta.loadStrategy = entityDef.loadStrategy;
+        meta.usedForPartialIndexes = entityDef.usedForPartialIndexes ?? false;
+        if (entityDef.version != null) {
+            meta.schemaVersion = entityDef.version;
+        }
+    }
+    for (const [key, entityDef] of Object.entries(schema.entities)) {
+        if (externalKeys.has(key)) {
+            continue;
+        }
+        const name = nameByKey.get(key);
+        const ctor = ctorByKey.get(key);
+        for (const [fieldName, builder] of Object.entries(entityDef.fields)) {
+            registerField(ctor, name, fieldName, builder, nameByKey);
+        }
+    }
+    for (const linkDef of Object.values(schema.links)) {
+        registerLink(linkDef, externalKeys, ctorByKey, nameByKey);
+    }
+    for (const [key, entityDef] of Object.entries(schema.entities)) {
+        if (externalKeys.has(key) || entityDef.version != null) {
+            continue;
+        }
+        const name = nameByKey.get(key);
+        const meta = ModelRegistry.getModelMeta(name);
+        meta.schemaVersion = hashEntityMeta(meta);
+    }
+    return {
+        modelNames: [...nameByKey.values()],
+        nameByKey,
+        schemaHash: ModelRegistry.schemaHash,
+    };
+}
+/**
+ * Entity keys that would collide with `store.<top-level>` methods (`store.batch`,
+ * future additions). Validation rejects these up front so a schema can't
+ * silently shadow the typed surface.
+ */
+const RESERVED_DB_KEYS = new Set([
+    "batch",
+    "undo",
+    "redo",
+    "undoDepth",
+    "redoDepth",
+    "runUndoable",
+]);
+function validateSchema(schema) {
+    const errors = [];
+    const entityKeys = new Set(Object.keys(schema.entities));
+    const seenRegistryNames = new Set();
+    for (const [key, entityDef] of Object.entries(schema.entities)) {
+        if (RESERVED_DB_KEYS.has(key)) {
+            errors.push(`entity key "${key}" collides with the reserved top-level \`store.${key}\`. ` +
+                `Rename the entity (e.g. "${key}Entry") or override its registry name.`);
+        }
+        if (entityDef.external === true && entityDef.name == null) {
+            errors.push(`entity "${key}": external: true requires an explicit name so the ` +
+                `compiler can resolve cross-references against the existing registry entry.`);
+        }
+        const name = entityDef.name ?? pascalCase(key);
+        if (entityDef.external === true && ModelRegistry.getModelMeta(name) == null) {
+            errors.push(`entity "${key}": external model "${name}" is not registered in ` +
+                `ModelRegistry. Import/run its @ClientModel definition before compiling the schema.`);
+        }
+        if (seenRegistryNames.has(name)) {
+            errors.push(`Two entities compile to the same registry name "${name}". ` +
+                `Override one with \`entity({ name: "..." })\`.`);
+        }
+        seenRegistryNames.add(name);
+        let idCount = 0;
+        for (const builder of Object.values(entityDef.fields)) {
+            if (builder.meta.kind === "id") {
+                idCount++;
+            }
+        }
+        if (idCount > 1) {
+            errors.push(`Entity "${key}" declares more than one s.id() field.`);
+        }
+    }
+    const fkBacklinkCount = new Map();
+    const relationNamesByEntity = new Map();
+    for (const [linkKey, linkDef] of Object.entries(schema.links)) {
+        const fromKey = linkDef.from.entity;
+        const fieldKey = linkDef.from.field;
+        const toKey = linkDef.to.entity;
+        if (!entityKeys.has(fromKey)) {
+            errors.push(`link "${linkKey}": from.entity "${fromKey}" is not a declared entity. ` +
+                `Valid entities: ${[...entityKeys].join(", ")}.`);
+            continue;
+        }
+        if (!entityKeys.has(toKey)) {
+            errors.push(`link "${linkKey}": to.entity "${toKey}" is not a declared entity. ` +
+                `Valid entities: ${[...entityKeys].join(", ")}.`);
+            continue;
+        }
+        const fromEntity = schema.entities[fromKey];
+        const fkBuilder = fromEntity.fields[fieldKey];
+        if (fkBuilder == null) {
+            errors.push(`link "${linkKey}": field "${fieldKey}" does not exist on entity "${fromKey}".`);
+            continue;
+        }
+        if (fkBuilder.meta.kind !== "refId") {
+            errors.push(`link "${linkKey}": field "${fromKey}.${fieldKey}" is ${fkBuilder.meta.kind}; ` +
+                `link FKs must be declared with s.refId(...).`);
+            continue;
+        }
+        if (fkBuilder.meta.refTarget !== toKey) {
+            errors.push(`link "${linkKey}": s.refId target is "${fkBuilder.meta.refTarget}" ` +
+                `but link.to.entity is "${toKey}". They must match.`);
+            continue;
+        }
+        const fkBacklinkKey = `${fromKey}.${fieldKey}`;
+        fkBacklinkCount.set(fkBacklinkKey, (fkBacklinkCount.get(fkBacklinkKey) ?? 0) + 1);
+        if (fromEntity.fields[linkDef.from.as] != null) {
+            errors.push(`link "${linkKey}": from.as "${linkDef.from.as}" collides with a ` +
+                `field already declared on entity "${fromKey}".`);
+        }
+        const toEntity = schema.entities[toKey];
+        if (toEntity.fields[linkDef.to.many] != null) {
+            errors.push(`link "${linkKey}": to.many "${linkDef.to.many}" collides with a ` +
+                `field already declared on entity "${toKey}".`);
+        }
+        addRelationName(relationNamesByEntity, fromKey, linkDef.from.as, errors);
+        addRelationName(relationNamesByEntity, toKey, linkDef.to.many, errors);
+    }
+    for (const [key, count] of fkBacklinkCount) {
+        if (count > 1) {
+            errors.push(`FK "${key}" is referenced by ${count} links — each refId field can ` +
+                `back at most one link.`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Schema validation failed:\n  - ${errors.join("\n  - ")}`);
+    }
+}
+function addRelationName(relationNamesByEntity, entityKey, name, errors) {
+    let names = relationNamesByEntity.get(entityKey);
+    if (names == null) {
+        names = new Set();
+        relationNamesByEntity.set(entityKey, names);
+    }
+    if (names.has(name)) {
+        errors.push(`entity "${entityKey}": relation property "${name}" is declared by ` +
+            `more than one link.`);
+    }
+    else {
+        names.add(name);
+    }
+}
+function collectExternalKeys(schema) {
+    const out = new Set();
+    for (const [key, entityDef] of Object.entries(schema.entities)) {
+        if (entityDef.external === true) {
+            out.add(key);
+        }
+    }
+    return out;
+}
+function resolveNames(schema) {
+    const out = new Map();
+    for (const [key, entityDef] of Object.entries(schema.entities)) {
+        out.set(key, entityDef.name ?? pascalCase(key));
+    }
+    return out;
+}
+function pascalCase(input) {
+    if (input.length === 0) {
+        return input;
+    }
+    return input[0].toUpperCase() + input.slice(1);
+}
+function createSyntheticClass(name, entityDef) {
+    const defaults = collectDefaults(entityDef);
+    const ctor = defaults.length === 0
+        ? class extends BaseModel {
+        }
+        : class extends BaseModel {
+            constructor() {
+                super();
+                for (const [key, value] of defaults) {
+                    this[key] = value;
+                }
+            }
+        };
+    Object.defineProperty(ctor, "name", { value: name });
+    ctor._modelName = name;
+    return ctor;
+}
+function collectDefaults(entityDef) {
+    const out = [];
+    for (const [fieldName, builder] of Object.entries(entityDef.fields)) {
+        if (builder.meta.kind === "id") {
+            continue;
+        }
+        if ("default" in builder.meta && builder.meta.default !== undefined) {
+            out.push([fieldName, builder.meta.default]);
+        }
+    }
+    return out;
+}
+function registerField(ctor, modelName, fieldName, builder, nameByKey) {
+    const meta = builder.meta;
+    if (meta.kind === "id") {
+        return;
+    }
+    const propMeta = {
+        name: fieldName,
+        type: meta.kind === "refId"
+            ? PropertyType.Reference
+            : meta.ephemeral
+                ? PropertyType.EphemeralProperty
+                : PropertyType.Property,
+    };
+    if (meta.indexed) {
+        propMeta.indexed = true;
+    }
+    if (meta.nullable) {
+        propMeta.nullable = true;
+    }
+    if (meta.serializer != null) {
+        propMeta.serializer = meta.serializer;
+    }
+    if (meta.deserializer != null) {
+        propMeta.deserializer = meta.deserializer;
+    }
+    if (meta.kind === "refId" && meta.refTarget != null) {
+        propMeta.referenceTo =
+            nameByKey.get(meta.refTarget) ?? pascalCase(meta.refTarget);
+    }
+    ModelRegistry.registerProperty(modelName, propMeta);
+    defineObservableProperty(ctor.prototype, fieldName);
+}
+function registerLink(linkDef, externalKeys, ctorByKey, nameByKey) {
+    const fromExternal = externalKeys.has(linkDef.from.entity);
+    const toExternal = externalKeys.has(linkDef.to.entity);
+    const fromName = nameByKey.get(linkDef.from.entity);
+    const toName = nameByKey.get(linkDef.to.entity);
+    const fromCtor = ctorByKey.get(linkDef.from.entity);
+    const toCtor = ctorByKey.get(linkDef.to.entity);
+    const fkField = linkDef.from.field;
+    const asField = linkDef.from.as;
+    const manyField = linkDef.to.many;
+    // From-side updates only apply when the source entity is owned by this
+    // schema; for external sources we leave the FK property untouched on the
+    // foreign class to avoid clobbering decorator-defined metadata.
+    if (!fromExternal && fromCtor != null) {
+        const refUpdates = { lazy: true };
+        if (linkDef.onDelete != null) {
+            refUpdates.onDelete = linkDef.onDelete;
+        }
+        ModelRegistry.updateProperty(fromName, fkField, refUpdates);
+        ModelRegistry.registerProperty(fromName, {
+            name: asField,
+            type: PropertyType.ReferenceModel,
+            referenceTo: toName,
+            idField: fkField,
+        });
+        installReferenceAccessor(fromCtor.prototype, asField, fkField, toName);
+    }
+    // To-side reverse-collection only when the target entity is owned by this
+    // schema. Schema → decorator links don't pollute the decorator's prototype.
+    if (!toExternal && toCtor != null) {
+        ModelRegistry.registerProperty(toName, {
+            name: manyField,
+            type: PropertyType.ReferenceCollection,
+            referenceTo: fromName,
+            lazy: linkDef.to.lazy ?? true,
+            inverseOf: fkField,
+        });
+        installCollectionAccessor(toCtor.prototype, manyField);
+    }
+}
+function hashEntityMeta(meta) {
+    const props = [...meta.properties.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((p) => [
+        p.name,
+        p.type,
+        `referenceTo=${p.referenceTo ?? ""}`,
+        `inverseOf=${p.inverseOf ?? ""}`,
+        `idField=${p.idField ?? ""}`,
+        `idsField=${p.idsField ?? ""}`,
+        `onDelete=${p.onDelete ?? ""}`,
+        `lazy=${p.lazy === true}`,
+        `nullable=${p.nullable === true}`,
+        `indexed=${p.indexed === true}`,
+        `serializer=${p.serializer != null}`,
+        `deserializer=${p.deserializer != null}`,
+    ].join(";"))
+        .join(",");
+    return hashString([
+        meta.name,
+        `loadStrategy=${meta.loadStrategy}`,
+        `usedForPartialIndexes=${meta.usedForPartialIndexes}`,
+        `props=[${props}]`,
+    ].join("|"));
+}

package/dist/schema/createStore.d.ts

@@ -0,0 +1,235 @@
+import type { StoreManager } from "../core/StoreManager";
+import type { UndoResult } from "../core/TransactionQueue";
+import type { ExtensionDescriptor, MergedExtensionMembers } from "./extend";
+import type { EntityKey, IndexedFieldKeys, InferCreateInput, InferEntity, InferUpdateInput } from "./infer";
+import type { SchemaDef } from "./types";
+/**
+ * Curated subset of `BaseModel` lifecycle methods we expose on records so
+ * imperative "mutate fields then commit" workflows have a typed path. Keeps
+ * the rest of `BaseModel`'s internals (`hydrate`, `serialize`, `assign`,
+ * `__mobx`, …) hidden so the public surface stays schema-driven.
+ */
+export interface RecordCommitInterface {
+    /** Flush pending field changes to the transaction queue. */
+    save(): void;
+    /** True iff there is at least one pending change since the last save. */
+    readonly hasUnsavedChanges: boolean;
+    /** Drop pending changes and reset to the last-saved values. */
+    discardUnsavedChanges(): void;
+    /**
+     * MobX-tracked subscription. The selector reads any reactive field or
+     * derivation on this record; `cb` fires whenever its result changes.
+     * Returns an unsubscribe function.
+     *
+     *     record.watch(r => r.title, (next, prev) => …)
+     *
+     * Inside React, prefer `useRecord` / `useRelation` — they wire the same
+     * thing through `useSyncExternalStore`. This is the imperative path.
+     */
+    watch<T>(selector: (record: this) => T, cb: (next: T, prev: T) => void): () => void;
+}
+export type RecordWithExtensions<S extends SchemaDef, K extends EntityKey<S>, Exts extends readonly ExtensionDescriptor<S>[]> = InferEntity<S, K> & MergedExtensionMembers<S, K, Exts> & RecordCommitInterface;
+export interface EntityNamespace<S extends SchemaDef, K extends EntityKey<S>, Exts extends readonly ExtensionDescriptor<S>[]> {
+    /**
+     * Resolve a single record. Pool-first under the hood, so a hit costs only
+     * a microtask; a miss falls back to IDB and (if configured) the on-demand
+     * fetcher.
+     */
+    get(id: string): Promise<RecordWithExtensions<S, K, Exts> | null>;
+    /** Resolve many records by id. Pool-first per id; missing ones are loaded together. */
+    getByIds(ids: readonly string[]): Promise<ReadonlyArray<RecordWithExtensions<S, K, Exts>>>;
+    /**
+     * Resolve every record matching `value` on a declared `.indexed()` field.
+     * The `key` is constrained at the type level to fields actually marked
+     * indexed in the schema.
+     *
+     * `value` is `string` because IDB indexes are string-typed; values from
+     * non-string indexed fields (numbers, dates, refIds) need to be stringified
+     * the same way the runtime serializes them. Future versions may type the
+     * value against the field's TS type once StoreManager.getOrLoadCollection
+     * accepts non-string values.
+     */
+    getByIndex(key: IndexedFieldKeys<S, K>, value: string): Promise<ReadonlyArray<RecordWithExtensions<S, K, Exts>>>;
+    /**
+     * Resolve every record matching any of `values` on a declared `.indexed()`
+     * field. Fans out one `getByIndex` call per value in parallel; the pool
+     * dedupes if records appear in multiple buckets. Records are returned in
+     * input-`values` order, with duplicates collapsed to first occurrence.
+     *
+     * If your backend supports compound index queries, opt in via
+     * `serverSupportsCompoundIndexKeys: true` + `onDemandIndexBatchFetcher` to
+     * collapse the fan-out into one server round-trip when the values share a
+     * parent FK. See `agent-docs/04-lazy-loading.md`.
+     */
+    getByIndexValues(key: IndexedFieldKeys<S, K>, values: readonly string[]): Promise<ReadonlyArray<RecordWithExtensions<S, K, Exts>>>;
+    /**
+     * Resolve every record of this entity. Hydrates from IDB on first call,
+     * relies on partial-index coverage and SSE deltas on subsequent calls.
+     */
+    getAll(): Promise<ReadonlyArray<RecordWithExtensions<S, K, Exts>>>;
+    /**
+     * Sync pool snapshot for a single record. Returns `undefined` if the
+     * record isn't currently hydrated — `undefined` means "not in this
+     * microtask's pool," **not** "doesn't exist." (Mirrors
+     * `objectPool.getById`; distinct from `get`, which resolves `null` only
+     * after a fetch confirms absence.) Use `get(id)` to fetch, or `has(id)`
+     * for a boolean membership check.
+     */
+    peek(id: string): RecordWithExtensions<S, K, Exts> | undefined;
+    /** Sync: is this record currently hydrated in the pool? Pairs with `peek`
+     * for code that only needs presence, not the record. */
+    has(id: string): boolean;
+    /** Sync pool snapshot of every record currently hydrated for this entity. */
+    peekAll(): ReadonlyArray<RecordWithExtensions<S, K, Exts>>;
+    /**
+     * Sync pool filter: every pooled record where `record[key] === value`.
+     * `key` is constrained to fields actually marked `.indexed()` in the
+     * schema, mirroring `getByIndex` — querying non-indexed fields here is
+     * usually a sign you wanted `getByIndex` (which can fall back to IDB).
+     */
+    peekByIndex(key: IndexedFieldKeys<S, K>, value: string): ReadonlyArray<RecordWithExtensions<S, K, Exts>>;
+    /**
+     * Create a record and commit it at the current boundary. Returns the live
+     * record (already in the pool, transaction enqueued). For a record you
+     * want to build up before committing — e.g. a "create on submit, abandon
+     * on cancel" form — use `draft(input)` instead.
+     */
+    create(input: InferCreateInput<S, K>): RecordWithExtensions<S, K, Exts>;
+    /**
+     * Apply a partial field update and commit it at the current boundary.
+     * Returns the record so callers can chain. Throws if no record with `id`
+     * is in the pool — to patch a lazy-loaded record, `await get(id)` (or use
+     * `draft(id)`) first.
+     */
+    patch(id: string, fields: InferUpdateInput<S, K>): RecordWithExtensions<S, K, Exts>;
+    /**
+     * Open a staged editing buffer. Nothing is committed until the returned
+     * record's `save()` runs (or an enclosing `batch`/`atomic` flushes it);
+     * `discardUnsavedChanges()` rolls back.
+     *
+     * - `draft(id)` — resolves the existing record (pool → IDB → on-demand,
+     *   same as `get`) and hands it back in staging mode. Async. Rejects if
+     *   no record with `id` exists.
+     * - `draft(input?)` — a brand-new uncommitted record with its `id` minted
+     *   up front (so relations can point at it). Sync. Abandoning it without
+     *   `save()` leaves nothing behind.
+     */
+    draft(id: string): Promise<RecordWithExtensions<S, K, Exts>>;
+    draft(input?: Partial<InferCreateInput<S, K>>): RecordWithExtensions<S, K, Exts>;
+    /** Delete the record with full cascade / restrict semantics. Commits at
+     * the current boundary. */
+    delete(id: string): void;
+    /** Soft-delete (archive) the record with full cascade / restrict
+     * semantics. Commits at the current boundary. */
+    archive(id: string): void;
+    /**
+     * Hydrate records straight into the pool — no transactions enqueued, no
+     * IDB writes. Re-seeding an existing id refreshes that instance in place.
+     * For tests and stories, not production.
+     */
+    seed(records: ReadonlyArray<Partial<InferCreateInput<S, K>>>): ReadonlyArray<RecordWithExtensions<S, K, Exts>>;
+    /** Force a network re-fetch of the listed ids. */
+    refresh(ids: readonly string[]): Promise<ReadonlyArray<RecordWithExtensions<S, K, Exts>>>;
+    /** Force a network re-fetch of every record of this entity. */
+    refreshAll(): Promise<void>;
+    /**
+     * Force a network re-fetch of every record matching `value` on a declared
+     * `.indexed()` field. Evicts the partial-index coverage cache first so the
+     * next load is guaranteed to hit the server.
+     */
+    refreshByIndex(key: IndexedFieldKeys<S, K>, value: string): Promise<ReadonlyArray<RecordWithExtensions<S, K, Exts>>>;
+    /**
+     * Subscribe to pool-level changes for this entity. The callback fires
+     * payload-less — re-read with `peekAll` / `peekByIndex` / `peek` inside
+     * the handler. Returns an unsubscribe function.
+     *
+     * Inside React, prefer `useRecords` — it wires the same primitive through
+     * `useSyncExternalStore`. This is the imperative path for headless code.
+     */
+    watchAll(cb: () => void): () => void;
+    /**
+     * Subscribe to pool-level changes filtered by `record[key] === value`.
+     * The pool runs the predicate at write-time and only invokes `cb` when a
+     * matching record was added or removed. Cheaper than `watchAll` followed
+     * by an in-handler `peekByIndex` filter.
+     *
+     * Caveat: this fires on **set-membership changes**, not field
+     * reassignments. A record moving between buckets via a setter
+     * (`record[key] = newValue`) goes through MobX boxes, not pool notify —
+     * pair with `record.watch(r => r[key], cb)` if you need that case too.
+     */
+    watchByIndex(key: IndexedFieldKeys<S, K>, value: string, cb: () => void): () => void;
+}
+/**
+ * Top-level `store` methods that aren't entity namespaces. Kept on a sibling
+ * intersection so `EntityStore<S>` stays "one entry per entity key" — the schema
+ * compiler reserves these names so an entity can't shadow them.
+ *
+ * For React, prefer `useUndoRedo()` from `zerodrift/react` — it
+ * subscribes to the transaction queue so `canUndo` / `canRedo` are
+ * reactive. These methods are the imperative path for non-React
+ * consumers (CLI tools, headless agents, tests).
+ */
+export interface StoreApi {
+    /**
+     * Run `fn` inside a transaction batch. Every `store.<entity>.create / update /
+     * delete` call inside shares a single `batchId`, ships in one HTTP POST,
+     * and reverses as one unit on undo. Returns the `batchId`.
+     *
+     * Accepts both sync and async functions — `endBatch` always fires after
+     * the function (or its returned Promise) completes, even on throw.
+     *
+     * The async overload is declared first so an `async () => {}` literal
+     * picks it; a sync `() => {}` returns `void` which can't satisfy
+     * `Promise<void>`, so it falls through to the sync overload.
+     */
+    batch(fn: () => Promise<void>): Promise<string>;
+    batch(fn: () => void): string;
+    /**
+     * Stage optimistic edits with all-or-nothing local commit semantics.
+     * Every model touched inside `fn` is `save()`d on success (in one batch
+     * → one undo entry) or `discardUnsavedChanges()`d on throw. See
+     * `StoreManager.atomic` for the full contract (SSE rebasing during
+     * await, runUndoable side effects, no nesting).
+     */
+    atomic<T>(fn: () => Promise<T>): Promise<T>;
+    atomic<T>(fn: () => T): T;
+    /** Pop and revert the top of the undo stack. */
+    undo(): Promise<UndoResult | null>;
+    /** Re-apply the top of the redo stack. */
+    redo(): Promise<UndoResult | null>;
+    /** Number of entries currently on the undo stack. */
+    readonly undoDepth: number;
+    /** Number of entries currently on the redo stack. */
+    readonly redoDepth: number;
+    /**
+     * Run a remote side-effect that returns a `changeLogId`, recording it on
+     * the undo stack so the next `store.undo()` invokes the
+     * `undoableActions.undo` handler with that id. `fn` may return either the
+     * `changeLogId` directly or any object carrying one. Inside an open
+     * `store.batch(...)`, the action joins the batch.
+     */
+    runUndoable<T extends string | {
+        changeLogId: string;
+    }>(fn: () => Promise<T> | T, opts?: {
+        actionType?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<T>;
+}
+export type EntityStore<S extends SchemaDef, Exts extends readonly ExtensionDescriptor<S>[] = readonly []> = {
+    [K in EntityKey<S>]: EntityNamespace<S, K, Exts>;
+} & StoreApi;
+/**
+ * Project a `SchemaDef` over a live `StoreManager`. The runtime values are
+ * `BaseModel` instances that structurally satisfy the inferred record type;
+ * the proxy-based public surface described in the RFC lands later.
+ */
+export declare function createStore<S extends SchemaDef, const Exts extends readonly ExtensionDescriptor<S>[] = readonly []>(opts: {
+    schema: S;
+    storeManager: StoreManager<any>;
+    extensions?: Exts;
+}): EntityStore<S, Exts>;
+/** @internal Symbol carrying the ModelRegistry name on each namespace. */
+export declare const REGISTRY_NAME: unique symbol;
+/** @internal Read the registry name a namespace was built for. */
+export declare function entityNamespaceRegistryName(ns: EntityNamespace<SchemaDef, string, readonly ExtensionDescriptor<SchemaDef>[]>): string;