zerodrift 1.0.4 → 1.2.0

package/README.md

@@ -157,15 +157,17 @@ Both authoring paths compile to the same registry, so schema entities and decora
 
 ## React quick start
 
-Wrap your app in `<SyncProvider>` once. Import your model file as a side effect so decorators run before bootstrap.
+Wrap your app in `<SyncProvider>` once. For the decorator path, import your model file as a side effect so decorators run before bootstrap; for the schema-first path, pass `schema={schema}` and the provider registers entities before fetching.
 
 ```tsx
 import { SyncProvider } from "zerodrift/react";
-import "./models";
+import { schema } from "./schema";   // schema-first
+// import "./models";                  // or: decorator path — side-effect import
 
 export default function Providers({ children }) {
   return (
     <SyncProvider
+      schema={schema}
       config={{
         workspaceId: "workspace-123",
         transport: {
@@ -194,6 +196,16 @@ export default function Providers({ children }) {
 }
 ```
 
+In schema-first children, pull the typed store with `useStore<typeof schema>()` (add `typeof extensions` as the second generic if you also passed extensions):
+
+```tsx
+import { useStore } from "zerodrift/react";
+import { schema } from "./schema";
+
+const store = useStore<typeof schema>();
+const { data: issue } = useRecord(store.issue, issueId);
+```
+
 Common reads and writes. The read hooks take a **handle** — a model class
 (decorator path) or a `store.<entity>` namespace (schema path) — and infer
 the record type from it. Every result has the same shape:
@@ -206,6 +218,12 @@ const { data: teamIssues } = useRecordsByIndex(Issue, "teamId", teamId);
 const { data: comments } = useRelation(issue?.comments);    // a relation
 const { phase } = useBootstrapStatus();
 
+// Every read hook takes an optional trailing `{ pause }` — while true it reads
+// the pool but holds all fetching (auto-fire and reload) until flipped false:
+const { data: c } = useRecordsByIndex(store.comment, "issueId", issueId, {
+  pause: !panelOpen,
+});
+
 issue.title = "New title";
 issue.save();
 
@@ -227,7 +245,7 @@ const { data: teams } = useRecords(store.team);
 const { data: teamIssues } = useRecordsByIndex(store.issue, "teamId", teamId);
 ```
 
-See [agent-docs/08-react-integration.md](agent-docs/08-react-integration.md) for hook return shapes, context-driven id generation, Storybook seeding, and testing patterns.
+See [agent-docs/08-react-integration.md](agent-docs/08-react-integration.md) for hook return shapes, context-driven id generation, Storybook seeding, and testing patterns. For the full `transport` field list (`bootstrapSyncGroups`, `modelStreams`, `sseClientFactory`, `syncTransform`, …) see [TransportConfig reference](agent-docs/07-realtime-sync.md#transportconfig-reference).
 
 ## Headless usage
 

package/dist/core/BaseSSEConnection.d.ts

@@ -8,19 +8,25 @@ export interface SSEClient {
 }
 export type SSEClientFactory = (url: string) => SSEClient;
 export type SSEErrorReporter = (err: Error, context: EngineErrorContext) => void;
+/** Either a fixed URL or a thunk re-evaluated on every (re)connect. */
+export type SSEEndpoint = string | (() => string);
 export declare const createBrowserSSEFactory: (init?: EventSourceInit) => SSEClientFactory;
 export declare abstract class BaseSSEConnection {
-    protected url: string;
+    protected url: SSEEndpoint;
     private sseClientFactory;
     private reportError?;
     private eventSource;
     private reconnectTimer;
     private stopped;
-    constructor(url: string, sseClientFactory?: SSEClientFactory, reportError?: SSEErrorReporter | undefined);
+    constructor(url: SSEEndpoint, sseClientFactory?: SSEClientFactory, reportError?: SSEErrorReporter | undefined);
     connect(): void;
     disconnect(): void;
     reconnect(): void;
     get isConnected(): boolean;
+    /** Resolve the endpoint to a concrete string. Subclasses building dynamic
+     * URLs (e.g. appending query params) must read through this instead of
+     * `this.url` directly so a thunk endpoint is re-evaluated on every connect. */
+    protected resolveUrl(): string;
     protected buildUrl(): string;
     protected abstract onMessage(data: string): void;
     protected onReconnect(): void;

package/dist/core/BaseSSEConnection.js

@@ -36,8 +36,14 @@ export class BaseSSEConnection {
     get isConnected() {
         return this.eventSource != null;
     }
+    /** Resolve the endpoint to a concrete string. Subclasses building dynamic
+     * URLs (e.g. appending query params) must read through this instead of
+     * `this.url` directly so a thunk endpoint is re-evaluated on every connect. */
+    resolveUrl() {
+        return typeof this.url === "function" ? this.url() : this.url;
+    }
     buildUrl() {
-        return this.url;
+        return this.resolveUrl();
     }
     onReconnect() { }
     onOpen() { }
@@ -51,7 +57,21 @@ export class BaseSSEConnection {
             this.eventSource = null;
             this.onClose();
         }
-        const url = this.buildUrl();
+        // buildUrl() can throw when the endpoint is a thunk (e.g. cursor read
+        // crashes). Catch + schedule a reconnect so a transient failure doesn't
+        // permanently kill the stream.
+        let url;
+        try {
+            url = this.buildUrl();
+        }
+        catch (err) {
+            this.reportError?.(toError(err), {
+                kind: "sseConstruction",
+                url: "<endpoint-thunk-threw>",
+            });
+            this.scheduleReconnect();
+            return;
+        }
         try {
             this.eventSource = this.sseClientFactory(url);
             this.eventSource.onmessage = (e) => {

package/dist/core/Database.d.ts

@@ -201,7 +201,8 @@ export interface StorageAdapter {
     close(): Promise<void>;
     /**
      * Close the connection AND permanently delete all persisted data.
-     * Use for explicit logout / factory-reset flows — NOT for routine teardown.
+     * Called by StoreManager.destroy() for explicit logout / factory-reset
+     * flows — NOT for routine teardown.
      */
     destroy(): Promise<void>;
     get isConnected(): boolean;

package/dist/core/ModelStream.d.ts

@@ -5,7 +5,7 @@
  */
 import type { StorageAdapter } from "./Database.js";
 import { ObjectPool } from "./ObjectPool.js";
-import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection.js";
+import { BaseSSEConnection, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter } from "./BaseSSEConnection.js";
 export interface ModelUpdate {
     modelName: string;
     modelId: string;
@@ -23,7 +23,7 @@ export declare class ModelStream extends BaseSSEConnection {
     private transform?;
     private updateQueue;
     private processing;
-    constructor(url: string, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
+    constructor(url: SSEEndpoint, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
     disconnect(): void;
     protected onOpen(): void;
     protected onClose(): void;

package/dist/core/StoreManager.d.ts

@@ -21,7 +21,7 @@
 import { ObjectPool } from "./ObjectPool.js";
 import { BootstrapType, type StorageAdapter, type DatabaseMeta, type PartialIndexEntry } from "./Database.js";
 import { TransactionQueue, type TransactionSender, type UndoableActionHandlers } from "./TransactionQueue.js";
-import { type DeltaPacket, type SSEClientFactory, type SyncMessageTransform } from "./SyncConnection.js";
+import { type DeltaPacket, type SSEClientFactory, type SSEEndpoint, type SyncMessageTransform } from "./SyncConnection.js";
 import { type ModelStreamMessageTransform } from "./ModelStream.js";
 import { type IndexBatchFetcher } from "./BatchModelLoader.js";
 import { BaseModel } from "./BaseModel.js";
@@ -40,6 +40,17 @@ export declare class RestrictDeleteError extends Error {
     restrictedByProperty: string;
     constructor(deletedModelName: string, deletedModelId: string, restrictedByModel: string, restrictedByProperty: string);
 }
+/** Per-call options for the `evict*` methods. */
+export interface EvictOptions {
+    /**
+     * Drop matching instances from the in-memory pool only, leaving the rows in
+     * IndexedDB (and the collection-coverage cache) intact. Use it on a layer
+     * switch to free memory now and rehydrate fast from IDB on return — no server
+     * round-trip. Default false: both the pool and IDB are cleared, and a future
+     * load refetches from the server.
+     */
+    keepInDb?: boolean;
+}
 export interface BootstrapResponse {
     lastSyncId: number;
     subscribedSyncGroups: string[];
@@ -68,7 +79,7 @@ export interface BootstrapFetcherOptions extends FetcherContext {
 }
 export type BootstrapFetcher = (type: BootstrapType.Full | BootstrapType.Partial, options?: BootstrapFetcherOptions) => Promise<BootstrapResponse>;
 export interface ModelStreamConfig {
-    url: string;
+    url: SSEEndpoint;
     onStatusChange?: (connected: boolean) => void;
     /**
      * Use when the backend sends a different envelope than the engine's
@@ -107,7 +118,10 @@ export type OnDemandConfig = {
 export interface TransportConfig {
     bootstrapFetcher: BootstrapFetcher;
     transactionSender?: TransactionSender;
-    syncUrl?: string;
+    /** SSE endpoint for live deltas — a static string, or a thunk evaluated
+     * on every (re)connect (so callers can fold in cursors from localStorage,
+     * auth tokens in the path, etc., without rebuilding the engine). */
+    syncUrl?: SSEEndpoint;
     /**
      * Optional async hook that returns the user's sync-group memberships
      * before any bootstrap fetch runs. The returned groups are append-only
@@ -723,17 +737,20 @@ export declare class StoreManager<TContext = unknown> {
      * Predicate receives hydrated instances (pool) and raw records (IDB); write
      * predicates that test plain property values so they work on both shapes.
      * IDB side is a full cursor scan — prefer `evictByIndex` when the match is
-     * "indexed column equals value".
+     * "indexed column equals value". Pass `{ keepInDb: true }` to release only
+     * the pool and leave the IDB rows cached. Returns the number of rows dropped.
      */
-    evictWhere(modelName: string, predicate: (m: Record<string, unknown>) => boolean): Promise<number>;
+    evictWhere(modelName: string, predicate: (m: Record<string, unknown>) => boolean, opts?: EvictOptions): Promise<number>;
     /**
      * Remove every record where `record[indexKey] === value`, using the IDB
      * index for the database side. Pool side is still a linear scan (no
      * secondary in-memory index by field value). Also clears the matching
      * `loadedCollections` cache key so a future `getOrLoadCollection(modelName,
      * indexKey, value)` re-fetches from the server instead of trusting IDB.
+     * Pass `{ keepInDb: true }` to release only the pool — IDB rows and the
+     * coverage entry are left intact, so the next load rehydrates from IDB.
      */
-    evictByIndex(modelName: string, indexKey: string, value: string): Promise<void>;
+    evictByIndex(modelName: string, indexKey: string, value: string, opts?: EvictOptions): Promise<void>;
     /**
      * Cascade `evictByIndex` across every model type that owns this FK. Use
      * when an "owner" id (workspaceId, teamId, userId, …) goes away and the
@@ -741,8 +758,10 @@ export declare class StoreManager<TContext = unknown> {
      * declare `indexKey` as `indexed: true` are skipped — `deleteModelsByIndex`
      * falls back to a full-store cursor scan when the index is missing, and
      * walking every store at every call is rarely what the caller wants.
+     * `opts` is forwarded to each `evictByIndex` — pass `{ keepInDb: true }` to
+     * release the pool for the whole scope while keeping IDB warm (layer switch).
      */
-    evictAllByIndex(indexKey: string, value: string): Promise<void>;
+    evictAllByIndex(indexKey: string, value: string, opts?: EvictOptions): Promise<void>;
     /** Pool-first bulk lookup by ID (for OwnedCollection resolution). */
     getOrLoadByIds<T extends BaseModel = BaseModel>(modelName: string, ids: string[]): Promise<T[]>;
     /** Pool-first single-model lookup by ID. */
@@ -829,7 +848,15 @@ export declare class StoreManager<TContext = unknown> {
      * cleared here because the schema-mismatch path keeps coverage entries;
      * the `fullyLoadedModels` mirror stays consistent with that. */
     private resetPoolState;
+    /** Routine cleanup (e.g. React unmount): stop sync, clear the object pool,
+     * and `close()` the persistence layer — persisted data is preserved so the
+     * next load can do a fast partial/local bootstrap. Not a logout. */
     teardown(): Promise<void>;
+    /** Logout / account switch: stop sync, clear the object pool, and `destroy()`
+     * the persistence layer — permanently wiping its data, whether persistence is
+     * IndexedDB or in-memory. Unlike {@link teardown}, nothing survives. */
+    destroy(): Promise<void>;
+    private shutdown;
     /** Debounced reconnect for SSE when `loadedModels` mutates. A burst of
      * transitions in the same tick (or across awaited writes in the same
      * async chain) coalesces into a single reconnect. setTimeout — not

package/dist/core/StoreManager.js

@@ -1551,10 +1551,14 @@ export class StoreManager {
      * Predicate receives hydrated instances (pool) and raw records (IDB); write
      * predicates that test plain property values so they work on both shapes.
      * IDB side is a full cursor scan — prefer `evictByIndex` when the match is
-     * "indexed column equals value".
+     * "indexed column equals value". Pass `{ keepInDb: true }` to release only
+     * the pool and leave the IDB rows cached. Returns the number of rows dropped.
      */
-    async evictWhere(modelName, predicate) {
+    async evictWhere(modelName, predicate, opts = {}) {
         const poolCount = this.evictFromPool(modelName, predicate);
+        if (opts.keepInDb === true) {
+            return poolCount;
+        }
         const records = await this.database.readAllModels(modelName);
         const ids = records.filter(predicate).map((r) => r.id);
         if (ids.length > 0) {
@@ -1568,9 +1572,16 @@ export class StoreManager {
      * secondary in-memory index by field value). Also clears the matching
      * `loadedCollections` cache key so a future `getOrLoadCollection(modelName,
      * indexKey, value)` re-fetches from the server instead of trusting IDB.
+     * Pass `{ keepInDb: true }` to release only the pool — IDB rows and the
+     * coverage entry are left intact, so the next load rehydrates from IDB.
      */
-    async evictByIndex(modelName, indexKey, value) {
+    async evictByIndex(modelName, indexKey, value, opts = {}) {
         this.evictFromPool(modelName, (m) => m[indexKey] === value);
+        if (opts.keepInDb === true) {
+            // Pool-only release: IDB rows and the collection-coverage entry stay,
+            // so a future getOrLoadCollection rehydrates from IDB without refetch.
+            return;
+        }
         await this.database.deleteModelsByIndex(modelName, indexKey, value);
         this.partialIndexCoverage.delete(StoreManager.collectionKey(modelName, indexKey, value));
         if (indexKey === ALL_INDEX_KEY_SENTINEL) {
@@ -1597,10 +1608,12 @@ export class StoreManager {
      * declare `indexKey` as `indexed: true` are skipped — `deleteModelsByIndex`
      * falls back to a full-store cursor scan when the index is missing, and
      * walking every store at every call is rarely what the caller wants.
+     * `opts` is forwarded to each `evictByIndex` — pass `{ keepInDb: true }` to
+     * release the pool for the whole scope while keeping IDB warm (layer switch).
      */
-    async evictAllByIndex(indexKey, value) {
+    async evictAllByIndex(indexKey, value, opts = {}) {
         const models = ModelRegistry.allModels().filter((meta) => meta.properties.get(indexKey)?.indexed === true);
-        await Promise.all(models.map((meta) => this.evictByIndex(meta.name, indexKey, value)));
+        await Promise.all(models.map((meta) => this.evictByIndex(meta.name, indexKey, value, opts)));
     }
     /** Pool-first bulk lookup by ID (for OwnedCollection resolution). */
     async getOrLoadByIds(modelName, ids) {
@@ -1980,7 +1993,19 @@ export class StoreManager {
         this.inflightFullLoads.clear();
         this.seededSyncGroups = [];
     }
+    /** Routine cleanup (e.g. React unmount): stop sync, clear the object pool,
+     * and `close()` the persistence layer — persisted data is preserved so the
+     * next load can do a fast partial/local bootstrap. Not a logout. */
     async teardown() {
+        await this.shutdown(false);
+    }
+    /** Logout / account switch: stop sync, clear the object pool, and `destroy()`
+     * the persistence layer — permanently wiping its data, whether persistence is
+     * IndexedDB or in-memory. Unlike {@link teardown}, nothing survives. */
+    async destroy() {
+        await this.shutdown(true);
+    }
+    async shutdown(destroyData) {
         this.stopped = true;
         BaseModel.storeManager = null;
         this.loadedModelsUnsub?.();
@@ -1998,7 +2023,7 @@ export class StoreManager {
         this.transactionQueue.destroy();
         this.indexBatchLoader?.dispose();
         this.indexBatchLoader = null;
-        await this.database.close();
+        await (destroyData ? this.database.destroy() : this.database.close());
         this.objectPool.clear();
         this.stores.clear();
         this.partialIndexCoverage.clear();

package/dist/core/SyncConnection.d.ts

@@ -24,8 +24,8 @@
 import type { StorageAdapter } from "./Database.js";
 import { ObjectPool } from "./ObjectPool.js";
 import { TransactionQueue } from "./TransactionQueue.js";
-import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection.js";
-export { type SSEClient, type SSEClientFactory, type SSEErrorReporter, createBrowserSSEFactory, } from "./BaseSSEConnection.js";
+import { BaseSSEConnection, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter } from "./BaseSSEConnection.js";
+export { type SSEClient, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter, createBrowserSSEFactory, } from "./BaseSSEConnection.js";
 /**
  * Encode each element then comma-join — the right shape for a list-of-
  * strings inside a URL query parameter or a stable cache key. Commas
@@ -92,7 +92,7 @@ export declare class SyncConnection extends BaseSSEConnection {
      * gate, which doesn't see `getOrLoadAll`'s sentinel coverage. */
     private isModelFullyLoaded?;
     private recordInflightDelete?;
-    constructor(url: string, database: StorageAdapter, pool: ObjectPool, queue: TransactionQueue, opts?: SyncConnectionOptions);
+    constructor(url: SSEEndpoint, database: StorageAdapter, pool: ObjectPool, queue: TransactionQueue, opts?: SyncConnectionOptions);
     protected buildUrl(): string;
     protected onMessage(data: string): void;
     protected onReconnect(): void;

package/dist/core/SyncConnection.js

@@ -67,11 +67,8 @@ export class SyncConnection extends BaseSSEConnection {
         const meta = this.database.currentMeta;
         const lastSyncId = meta?.lastSyncId ?? 0;
         const syncGroups = encodeCsvList(meta?.subscribedSyncGroups ?? []);
-        // Tell the server which models we're subscribed to (catchup + live
-        // stream; absent → no filter). Union of always-subscribed (Eager +
-        // Ephemeral, see ModelRegistry) with adapter-tracked loadedModels.
-        // Sort for a stable URL — equivalent sets must produce identical URLs
-        // so the engine doesn't churn reconnects when iteration order shifts.
+        // Sort the union — equivalent sets must produce identical URLs so the
+        // engine doesn't churn reconnects when iteration order shifts.
         const subscribed = [
             ...new Set([
                 ...ModelRegistry.alwaysSubscribedModelNames(),
@@ -79,7 +76,11 @@ export class SyncConnection extends BaseSSEConnection {
             ]),
         ].sort();
         const onlyModels = subscribed.length > 0 ? `&onlyModels=${encodeCsvList(subscribed)}` : "";
-        return `${this.url}?lastSyncId=${lastSyncId}&syncGroups=${syncGroups}${onlyModels}`;
+        const base = this.resolveUrl();
+        // Thunk endpoints often already carry query params (tenant, cursor, …);
+        // pick `&` when the base is already in query-string mode.
+        const sep = base.includes("?") ? "&" : "?";
+        return `${base}${sep}lastSyncId=${lastSyncId}&syncGroups=${syncGroups}${onlyModels}`;
     }
     onMessage(data) {
         const raw = JSON.parse(data);

package/dist/core/index.d.ts

@@ -9,8 +9,8 @@ export { MemoryAdapter } from "./MemoryAdapter.js";
 export { BootstrapType } from "./Database.js";
 export type { DatabaseMeta, StorageAdapter } from "./Database.js";
 export { StoreManager, RestrictDeleteError } from "./StoreManager.js";
-export type { BootstrapResponse, BootstrapFetcher, BootstrapFetcherOptions, FetcherContext, StoreManagerConfig, TransportConfig, LoadingConfig, PersistenceConfig, HooksConfig, AdvancedConfig, OnDemandConfig, OnDemandFetcher, OnDemandBatchFetcher, ModelStreamConfig, } from "./StoreManager.js";
+export type { BootstrapResponse, EvictOptions, BootstrapFetcher, BootstrapFetcherOptions, FetcherContext, StoreManagerConfig, TransportConfig, LoadingConfig, PersistenceConfig, HooksConfig, AdvancedConfig, OnDemandConfig, OnDemandFetcher, OnDemandBatchFetcher, ModelStreamConfig, } from "./StoreManager.js";
 export type { UndoableAction } from "./Transaction.js";
 export type { TransactionSender, BatchResponse, UndoableActionHandlers, UndoResult, } from "./TransactionQueue.js";
-export type { SyncAction, DeltaPacket, SyncMessageTransform, } from "./SyncConnection.js";
+export type { SyncAction, DeltaPacket, SSEEndpoint, SyncMessageTransform, } from "./SyncConnection.js";
 export type { ModelUpdate, ModelStreamMessageTransform } from "./ModelStream.js";

package/dist/react/index.d.ts

@@ -11,12 +11,16 @@ import { StoreManager, type StoreManagerConfig } from "../core/StoreManager.js";
 import { BootstrapPhase } from "../core/types.js";
 import { LazyCollectionBase, BackRef } from "../core/LazyCollection.js";
 import type { BaseModel } from "../core/BaseModel.js";
+import { type EntityNamespace, type EntityStore, type RecordWithExtensions } from "../schema/createStore.js";
+import type { ExtensionDescriptor } from "../schema/extend.js";
+import type { EntityKey, IndexedFieldKeys } from "../schema/infer.js";
+import type { SchemaDef } from "../schema/types.js";
 export interface SyncStatus {
     phase: BootstrapPhase;
     detail?: string;
     error?: string;
 }
-export declare function SyncProvider<TContext = unknown>({ config, context, children, fallback, }: {
+export declare function SyncProvider<TContext = unknown, S extends SchemaDef = SchemaDef>({ config, schema, extensions, context, children, fallback, }: {
     config: StoreManagerConfig<TContext>;
     /** Live context forwarded to `StoreManager.setContext` — consumed by
      * `identifierFn` when minting ids for client-side models. Pushed
@@ -25,12 +29,22 @@ export declare function SyncProvider<TContext = unknown>({ config, context, chil
     children: React.ReactNode;
     /** Shown while bootstrap is in progress. */
     fallback?: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element | null;
+} & ({
+    schema?: undefined;
+    extensions?: undefined;
+} | {
+    /** Schema-first wiring. Read the store back with `useStore<typeof schema>()`. */
+    schema: S;
+    extensions?: readonly ExtensionDescriptor<S>[];
+})): import("react/jsx-runtime").JSX.Element | null;
 export declare function useSyncEngine(): {
     sm: StoreManager<any>;
     status: SyncStatus;
+    store?: EntityStore<any, any>;
 };
 export declare function useBootstrapStatus(): SyncStatus;
+/** Read the schema-first store from context — `useStore<typeof schema>()`. */
+export declare function useStore<S extends SchemaDef, const Exts extends readonly ExtensionDescriptor<S>[] = readonly []>(): EntityStore<S, Exts>;
 /**
  * Uniform async-resource shape for every load-aware hook (`useRecord`,
  * `useRecords`, `useRecordsByIndex`, `useRelation`). `data` is the payload
@@ -45,6 +59,17 @@ export interface AsyncResource<T> {
     error: Error | null;
     reload: () => Promise<void>;
 }
+/** Per-call options shared by the load-aware read hooks. */
+export interface UseQueryOptions {
+    /**
+     * When true, hold all fetching — auto-fire on mount/dependency change *and*
+     * `reload()` are suppressed until it flips false. The hook still reads the
+     * pool synchronously, so anything already resident renders immediately;
+     * only the async backfill waits. Use it to defer a fetch until a prerequisite
+     * is ready (auth resolved, a parent record loaded, a panel actually opened).
+     */
+    pause?: boolean;
+}
 /** Returns `store.batch` — the sync overload yields the `batchId` string,
  * the async overload a `Promise<string>`. */
 export declare function useBatch(): StoreManager["batch"];
@@ -54,12 +79,8 @@ export declare function useUndoRedo(): {
     canUndo: boolean;
     canRedo: boolean;
 };
-export declare function useRelation<T extends BaseModel = BaseModel>(relation: LazyCollectionBase<T> | null | undefined): AsyncResource<T[]>;
-export declare function useRelation<T extends BaseModel = BaseModel>(relation: BackRef<T> | null | undefined): AsyncResource<T | null>;
-import { type EntityNamespace, type RecordWithExtensions } from "../schema/createStore.js";
-import type { ExtensionDescriptor } from "../schema/extend.js";
-import type { EntityKey, IndexedFieldKeys } from "../schema/infer.js";
-import type { SchemaDef } from "../schema/types.js";
+export declare function useRelation<T extends BaseModel = BaseModel>(relation: LazyCollectionBase<T> | null | undefined, opts?: UseQueryOptions): AsyncResource<T[]>;
+export declare function useRelation<T extends BaseModel = BaseModel>(relation: BackRef<T> | null | undefined, opts?: UseQueryOptions): AsyncResource<T | null>;
 type AnyNamespace = EntityNamespace<any, any, any>;
 type ModelCtor<T extends BaseModel = BaseModel> = abstract new (...args: any[]) => T;
 type Handle = AnyNamespace | ModelCtor;
@@ -73,10 +94,10 @@ type RecordOf<H> = H extends ModelCtor<infer T> ? T : RecordOfNamespace<H>;
  * namespace, unconstrained `string` for a decorator class. */
 type IndexKeyOf<H> = H extends ModelCtor ? string : IndexKeyOfNamespace<H>;
 /** Reactive single record by id. Pool-first sync read; async backfill on miss. */
-export declare function useRecord<H extends Handle>(handle: H, id: string | null | undefined): AsyncResource<RecordOf<H> | null>;
+export declare function useRecord<H extends Handle>(handle: H, id: string | null | undefined, opts?: UseQueryOptions): AsyncResource<RecordOf<H> | null>;
 /** Reactive list of records, optionally filtered to (and ordered by) `ids`. */
-export declare function useRecords<H extends Handle>(handle: H, ids?: string[] | null): AsyncResource<RecordOf<H>[]>;
+export declare function useRecords<H extends Handle>(handle: H, ids?: string[] | null, opts?: UseQueryOptions): AsyncResource<RecordOf<H>[]>;
 /** Reactive list of records matching one value, or any of several, on a
  * foreign-key index. */
-export declare function useRecordsByIndex<H extends Handle>(handle: H, indexKey: IndexKeyOf<H>, value: string | readonly string[] | null | undefined): AsyncResource<RecordOf<H>[]>;
+export declare function useRecordsByIndex<H extends Handle>(handle: H, indexKey: IndexKeyOf<H>, value: string | readonly string[] | null | undefined, opts?: UseQueryOptions): AsyncResource<RecordOf<H>[]>;
 export {};

package/dist/react/index.js

@@ -12,18 +12,25 @@ import { StoreManager } from "../core/StoreManager.js";
 import { BootstrapPhase } from "../core/types.js";
 import { BackRef } from "../core/LazyCollection.js";
 import { readFk } from "../core/ObjectPool.js";
+import { createStore, entityNamespaceRegistryName, } from "../schema/createStore.js";
 // `<any>` keeps the hooks free of TContext — none of them touch it.
 const SyncContext = createContext(null);
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------
-export function SyncProvider({ config, context, children, fallback, }) {
+export function SyncProvider({ config, schema, extensions, context, children, fallback, }) {
     const [status, setStatus] = useState({
         phase: BootstrapPhase.Idle,
     });
     const smRef = useRef(null);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const storeRef = useRef(undefined);
     const cfgRef = useRef(config);
     cfgRef.current = config;
+    const schemaRef = useRef(schema);
+    schemaRef.current = schema;
+    const extensionsRef = useRef(extensions);
+    extensionsRef.current = extensions;
     // Detect bfcache restores. When a tab is duplicated (or the user navigates
     // back/forward) the browser may restore the page from its back/forward cache
     // (bfcache). In that case the JS heap is frozen and thawed — React effects do
@@ -60,6 +67,15 @@ export function SyncProvider({ config, context, children, fallback, }) {
         if (contextRef.current !== undefined) {
             sm.setContext(contextRef.current);
         }
+        // createStore registers schema entities into ModelRegistry — must
+        // run before bootstrap() so the first fetch sees them.
+        if (schemaRef.current != null) {
+            storeRef.current = createStore({
+                schema: schemaRef.current,
+                storeManager: sm,
+                extensions: extensionsRef.current,
+            });
+        }
         smRef.current = sm;
         sm.bootstrap().catch((err) => {
             if (active) {
@@ -70,6 +86,7 @@ export function SyncProvider({ config, context, children, fallback, }) {
             active = false;
             sm.teardown();
             smRef.current = null;
+            storeRef.current = undefined;
         };
     }, [cfgRef.current.workspaceId]);
     // Push context updates synchronously so an event handler dispatched in the
@@ -87,7 +104,7 @@ export function SyncProvider({ config, context, children, fallback, }) {
         fallback != null) {
         return _jsx(_Fragment, { children: fallback });
     }
-    return (_jsx(SyncContext.Provider, { value: { sm: smRef.current, status }, children: children }));
+    return (_jsx(SyncContext.Provider, { value: { sm: smRef.current, status, store: storeRef.current }, children: children }));
 }
 // ---------------------------------------------------------------------------
 // Core hook
@@ -102,6 +119,14 @@ export function useSyncEngine() {
 export function useBootstrapStatus() {
     return useSyncEngine().status;
 }
+/** Read the schema-first store from context — `useStore<typeof schema>()`. */
+export function useStore() {
+    const ctx = useSyncEngine();
+    if (ctx.store == null) {
+        throw new Error("useStore() requires <SyncProvider schema={…}>.");
+    }
+    return ctx.store;
+}
 /** Subscribe to a model type's pool changes and read a snapshot synchronously.
  *
  * `getSnapshot` is intentionally NOT stabilized — useSyncExternalStore calls
@@ -159,12 +184,13 @@ const settled = (ready, isLoading, error) => ready && !isLoading && error == nul
 // (schema namespace or model class) to a registry name and delegate here,
 // so the pool-subscription / loader machinery lives in exactly one place.
 /** Reactive single model by id. Pool-first sync read; async backfill on miss. */
-function useRecordByName(modelName, id) {
+function useRecordByName(modelName, id, opts) {
     const { sm, status } = useSyncEngine();
     const pool = sm.objectPool;
     const ready = status.phase === BootstrapPhase.Ready;
+    const pause = opts?.pause ?? false;
     const item = usePoolSnapshot(modelName, () => id != null ? (pool.getById(modelName, id) ?? null) : null);
-    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadById(modelName, id), ready && id != null, `${modelName}:${id ?? ""}`, 
+    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadById(modelName, id), ready && id != null && !pause, `${modelName}:${id ?? ""}`, 
     // Skip the load when the pool already has the entry — eager models
     // render with isLoading: false from frame zero.
     () => id != null && pool.getById(modelName, id) == null);
@@ -180,10 +206,11 @@ function useRecordByName(modelName, id) {
  * set. Without `ids`: every instance in the pool. With `ids`: just those, in
  * the order given, with async backfill for any missing from the pool. The
  * ids array is compared by content so inline literals don't cause re-fetches. */
-function useRecordsByName(modelName, ids) {
+function useRecordsByName(modelName, ids, opts) {
     const { sm, status } = useSyncEngine();
     const pool = sm.objectPool;
     const ready = status.phase === BootstrapPhase.Ready;
+    const pause = opts?.pause ?? false;
     const idsKey = ids?.join(",") ?? "";
     const all = usePoolSnapshot(modelName, () => pool.getAll(modelName));
     const items = useMemo(() => {
@@ -195,7 +222,7 @@ function useRecordsByName(modelName, ids) {
             .map((id) => byId.get(id))
             .filter((m) => m != null);
     }, [all, idsKey]);
-    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadByIds(modelName, ids ?? []), ready && ids != null && ids.length > 0, `${modelName}:${idsKey}`, () => ids != null && ids.some((id) => pool.getById(modelName, id) == null));
+    const { isLoading, error, reload } = useLoader(() => sm.getOrLoadByIds(modelName, ids ?? []), ready && ids != null && ids.length > 0 && !pause, `${modelName}:${idsKey}`, () => ids != null && ids.some((id) => pool.getById(modelName, id) == null));
     return {
         data: ready ? items : [],
         isLoading,
@@ -214,9 +241,10 @@ function useRecordsByName(modelName, ids) {
  * For one-round-trip multi-value fetches, configure
  * `onDemandIndexBatchFetcher` + `serverSupportsCompoundIndexKeys: true` —
  * see `agent-docs/04-lazy-loading.md`. */
-function useRecordsByIndexName(modelName, indexKey, value) {
+function useRecordsByIndexName(modelName, indexKey, value, opts) {
     const { sm, status } = useSyncEngine();
     const ready = status.phase === BootstrapPhase.Ready;
+    const pause = opts?.pause ?? false;
     const values = value == null
         ? []
         : (Array.isArray(value) ? value : [value]).filter((v) => v != null && v !== "");
@@ -236,7 +264,7 @@ function useRecordsByIndexName(modelName, indexKey, value) {
     }, [all, indexKey, valuesKey, hasValues]);
     const { isLoading, error, reload } = useLoader(async () => {
         await Promise.all(values.map((v) => sm.getOrLoadCollection(modelName, indexKey, v)));
-    }, ready && hasValues, `${modelName}:${indexKey}:${valuesKey}`, () => hasValues &&
+    }, ready && hasValues && !pause, `${modelName}:${indexKey}:${valuesKey}`, () => hasValues &&
         values.some((v) => !sm.isCollectionLoaded(modelName, indexKey, v)));
     return {
         data: ready ? items : [],
@@ -276,9 +304,10 @@ export function useUndoRedo() {
         canRedo: redoDepth > 0,
     };
 }
-export function useRelation(relation) {
+export function useRelation(relation, opts) {
     const [tick, forceRender] = useState(0);
     const isBackRef = relation instanceof BackRef;
+    const pause = opts?.pause ?? false;
     // Collections expose watch() for invalidation; BackRef does not.
     useEffect(() => {
         if (relation == null || isBackRef) {
@@ -287,10 +316,10 @@ export function useRelation(relation) {
         return relation.watch(() => forceRender((n) => n + 1));
     }, [relation, isBackRef]);
     useEffect(() => {
-        if (relation != null && !relation.isLoaded && !relation.isLoading) {
+        if (!pause && relation != null && !relation.isLoaded && !relation.isLoading) {
             relation.load().then(() => forceRender((n) => n + 1));
         }
-    }, [relation, tick]);
+    }, [relation, tick, pause]);
     if (relation == null) {
         // Can't tell collection from back-ref at null; `[]` is the map-safe
         // default. A null back-ref reads `[]` rather than `null` — harmless
@@ -312,6 +341,9 @@ export function useRelation(relation) {
         isLoaded: relation.isLoaded ?? false,
         error: relation.error ?? null,
         reload: async () => {
+            if (pause) {
+                return;
+            }
             await (isBackRef
                 ? relation.load()
                 : relation.reload());
@@ -328,23 +360,6 @@ function useStableCallback(callback) {
     }, [callback]);
     return stableRef.current;
 }
-// ---------------------------------------------------------------------------
-// Public read hooks — keyed by a "handle"
-//
-// A handle is either a schema namespace (`store.issue`) or a decorator
-// model class (`Issue`). Both resolve to a registry name; the record type
-// is inferred from whichever form was passed, so the same four hooks serve
-// both authoring paths with one vocabulary:
-//
-//   useRecord(handle, id)               → AsyncResource<T | null>
-//   useRecords(handle, ids?)            → AsyncResource<T[]>
-//   useRecordsByIndex(handle, key, v|v[]) → AsyncResource<T[]>
-//   useRelation(record.relation)        → AsyncResource<T[] | T | null>
-//
-// For namespace handles the index key is constrained to the schema's
-// `.indexed()` fields; for class handles it's `string`.
-// ---------------------------------------------------------------------------
-import { entityNamespaceRegistryName, } from "../schema/createStore.js";
 function handleRegistryName(handle) {
     if (typeof handle === "function") {
         // Set by @ClientModel (explicit { name } or ctor.name fallback).
@@ -359,15 +374,15 @@ function handleRegistryName(handle) {
 // has `__mobx`/`store`; RecordOf has schema fields + extensions). One cast
 // per wrapper, contained.
 /** Reactive single record by id. Pool-first sync read; async backfill on miss. */
-export function useRecord(handle, id) {
-    return useRecordByName(handleRegistryName(handle), id);
+export function useRecord(handle, id, opts) {
+    return useRecordByName(handleRegistryName(handle), id, opts);
 }
 /** Reactive list of records, optionally filtered to (and ordered by) `ids`. */
-export function useRecords(handle, ids) {
-    return useRecordsByName(handleRegistryName(handle), ids);
+export function useRecords(handle, ids, opts) {
+    return useRecordsByName(handleRegistryName(handle), ids, opts);
 }
 /** Reactive list of records matching one value, or any of several, on a
  * foreign-key index. */
-export function useRecordsByIndex(handle, indexKey, value) {
-    return useRecordsByIndexName(handleRegistryName(handle), indexKey, value);
+export function useRecordsByIndex(handle, indexKey, value, opts) {
+    return useRecordsByIndexName(handleRegistryName(handle), indexKey, value, opts);
 }

package/dist/schema/index.d.ts

@@ -7,7 +7,7 @@ export { createStore } from "./createStore.js";
 export type { EntityStore, EntityNamespace, RecordWithExtensions, StoreApi, } from "./createStore.js";
 export { extend } from "./extend.js";
 export type { ActionFn, ComputedFn, ExtensionDef, ExtensionDescriptor, ExtensionMap, MergedExtensionMembers, } from "./extend.js";
-export { fromZod, entityFromZod } from "./zod.js";
+export { fromZod, entityFromZod, entitiesFromZod } from "./zod.js";
 export type { EntityFromZodFieldOverride, EntityFromZodOpts } from "./zod.js";
 export type { EntityDef, FieldBuilder, FieldKind, FieldMeta, LinkDef, LinkFromSpec, LinkToSpec, OnDelete, SchemaDef, } from "./types.js";
-export type { EntityKey, IndexedFieldKeys, InferCreateInput, InferEntity, InferUpdateInput, RelationCollection, } from "./infer.js";
+export type { EntityKey, IndexedFieldKeys, InferCreateInput, InferEntity, InferRecord, InferUpdateInput, RelationCollection, } from "./infer.js";

package/dist/schema/index.js

@@ -5,4 +5,4 @@ export { fields as s } from "./builders.js";
 export { compileSchema } from "./compile.js";
 export { createStore } from "./createStore.js";
 export { extend } from "./extend.js";
-export { fromZod, entityFromZod } from "./zod.js";
+export { fromZod, entityFromZod, entitiesFromZod } from "./zod.js";

package/dist/schema/infer.d.ts

@@ -81,6 +81,15 @@ type ReverseCollections<S extends SchemaDef, K extends EntityKey<S>> = {
  * with a one-line helper at the call site if they want.
  */
 export type InferEntity<S extends SchemaDef, K extends EntityKey<S>> = EntityFieldTypes<S, K> & SingularRelations<S, K> & ReverseCollections<S, K>;
+/**
+ * Alias for {@link InferEntity}. Provided so the three record-shape helpers
+ * read uniformly at call sites:
+ *
+ *     type Need       = InferRecord<typeof schema, "need">;
+ *     type NeedCreate = InferCreateInput<typeof schema, "need">;
+ *     type NeedUpdate = InferUpdateInput<typeof schema, "need">;
+ */
+export type InferRecord<S extends SchemaDef, K extends EntityKey<S>> = InferEntity<S, K>;
 /**
  * A create-input field is optional when the runtime can fill it without
  * the caller: id-kind (BaseModel auto-assigns a UUID), defaulted fields,

package/dist/schema/zod.d.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import type { AnyFieldBuilder, EntityDef, FieldBuilder } from "./types.js";
+import type { AnyFieldBuilder, EntityDef, FieldBuilder, FieldKind, FieldMeta } from "./types.js";
 /**
  * Convert any Zod schema into the equivalent schema-first `FieldBuilder`.
  * Handles the common nullable / optional / default modifiers; anything more
@@ -10,31 +10,111 @@ import type { AnyFieldBuilder, EntityDef, FieldBuilder } from "./types.js";
  * caller to have installed `zod`.
  */
 export declare function fromZod<Z extends z.ZodType>(zSchema: Z): FieldBuilder<z.infer<Z>>;
+/**
+ * Maps Zod's `_zod.def.type` discriminator to a schema `FieldKind`. Mirrors
+ * the runtime `PRIMITIVE_KIND` map; anything not covered collapses to `"json"`,
+ * matching `fromZod`'s fallback.
+ */
+type ZodKindFromTypeName<T> = T extends "string" ? "string" : T extends "number" | "int" ? "number" : T extends "boolean" ? "boolean" : T extends "date" ? "date" : "json";
+/**
+ * Type-level analogue of `fromZod`'s runtime walker: peels off `nullable` /
+ * `optional` / `default` wrappers, stamping each on the accumulator, then
+ * collapses the leaf to a kind via `ZodKindFromTypeName`. The result is
+ * intersected with `FieldMeta` so `IsOptionalCreateField` sees the same
+ * `{kind, optional, default}` flags the runtime produces — keeping
+ * create-input optionality aligned for `.optional()` and `.default(...)`
+ * Zod fields, not just `id`.
+ */
+type ZodToFieldMeta<Z, Accum = Record<never, never>> = Z extends {
+    _zod: {
+        def: {
+            type: "nullable";
+            innerType: infer I;
+        };
+    };
+} ? ZodToFieldMeta<I, Accum & {
+    nullable: true;
+}> : Z extends {
+    _zod: {
+        def: {
+            type: "optional";
+            innerType: infer I;
+        };
+    };
+} ? ZodToFieldMeta<I, Accum & {
+    optional: true;
+}> : Z extends {
+    _zod: {
+        def: {
+            type: "default";
+            innerType: infer I;
+        };
+    };
+} ? ZodToFieldMeta<I, Accum & {
+    default: unknown;
+}> : Z extends {
+    _zod: {
+        def: {
+            type: infer T extends string;
+        };
+    };
+} ? Accum & {
+    kind: ZodKindFromTypeName<T>;
+} : Accum;
+/** Empty meta marker — convention-driven flags (autoIndex) layer on top.
+ * `id` is excluded because the storage layer treats the PK specially and
+ * never materializes a secondary index for it; the empty-string suffix is
+ * excluded so a defaulted/blank config value doesn't index every field. */
+type AutoIndexMeta<K, AI extends string | undefined> = K extends "id" ? Record<never, never> : AI extends "" ? Record<never, never> : AI extends string ? K extends `${string}${AI}` ? {
+    indexed: true;
+} : Record<never, never> : Record<never, never>;
+/**
+ * Auto-derived `FieldBuilder` type for a Zod-object key. The `id` key is
+ * special-cased to carry `{kind: "id"}` (the runtime routes `id` through
+ * `fields.id()` regardless of the Zod-declared id type). Every other key
+ * walks its Zod schema via `ZodToFieldMeta` so PK, optional, and default
+ * flags all flow into the field's create-input optionality the same way.
+ * `AI` is the opts.autoIndex suffix — matching keys pick up `{indexed: true}`.
+ */
+type AutoFieldFromZod<K, ZS, AI extends string | undefined = undefined> = K extends "id" ? FieldBuilder<string, FieldMeta & {
+    kind: "id";
+} & AutoIndexMeta<K, AI>> : ZS extends z.ZodType ? FieldBuilder<z.infer<ZS>, FieldMeta & ZodToFieldMeta<ZS> & AutoIndexMeta<K, AI>> : FieldBuilder<unknown, FieldMeta & {
+    kind: FieldKind;
+}>;
 /**
  * Per-field override for `entityFromZod`. Either a chaining function
  * (modifies the auto-derived `FieldBuilder`) or a full `FieldBuilder`
  * (replaces it — useful for FKs and other shapes Zod can't model).
  */
 export type EntityFromZodFieldOverride<AutoT = unknown> = AnyFieldBuilder | ((auto: FieldBuilder<AutoT>) => AnyFieldBuilder);
-type EntityFromZodFieldOverrides<Z extends z.ZodObject> = {
-    [K in keyof z.infer<Z> & string]?: AnyFieldBuilder | ((auto: FieldBuilder<z.infer<Z>[K]>) => unknown);
+type EntityFromZodFieldOverrides<Z extends z.ZodObject, AI extends string | undefined = undefined> = {
+    [K in keyof Z["shape"] & string]?: AnyFieldBuilder | ((auto: AutoFieldFromZod<K, Z["shape"][K], AI>) => unknown);
+};
+/**
+ * Maps any `opts.fields` key that isn't declared on the Zod object to a
+ * branded error-string type. The intersection with the override map then
+ * forces TS to surface "is not assignable to type \"Error: 'foo' is not a
+ * field…\"" — naming the offender — instead of the bare "not assignable to
+ * type 'never'" the previous `Record<…, never>` form produced.
+ */
+type NoExtraZodFieldKeys<Z extends z.ZodObject, F> = {
+    [K in keyof F as K extends keyof Z["shape"] ? never : K]: `Error: '${K & string}' is not a field declared on the Zod object passed to entityFromZod`;
 };
-type NoExtraZodFieldKeys<Z extends z.ZodObject, F> = Record<Exclude<keyof F, keyof z.infer<Z> & string>, never>;
 /**
  * Resolve the field type contributed by an override entry. Functions are
  * unwrapped via their inferred return type so chained modifiers like
  * `.indexed()` carry their narrowed `M` into the entity's inferred fields;
  * direct `FieldBuilder` overrides are used as-is. When no override is
- * provided the auto-derived `FieldBuilder<AutoT>` from Zod stands.
+ * provided the auto-derived `Auto` field stands.
  */
-type FieldFromOverride<O, AutoT> = O extends (...args: never[]) => infer R ? R extends FieldBuilder<infer RT, infer RM> ? [unknown] extends [RT] ? FieldBuilder<AutoT, RM> : R : FieldBuilder<AutoT> : O extends AnyFieldBuilder ? O : FieldBuilder<AutoT>;
+type FieldFromOverride<O, Auto> = O extends (...args: never[]) => infer R ? R extends FieldBuilder<infer RT, infer RM> ? [unknown] extends [RT] ? Auto extends FieldBuilder<infer AT, FieldMeta> ? FieldBuilder<AT, RM> : never : R : Auto : O extends AnyFieldBuilder ? O : Auto;
 /**
  * Per-key merge of the Zod-inferred fields with `opts.fields` overrides.
  * Override metadata (`.indexed()`, refId target, …) propagates into the
  * entity's TS type so downstream helpers like `IndexedFieldKeys` see them.
  */
-type MergedFieldsFromZodObject<Z extends z.ZodObject, F> = {
-    [K in keyof z.infer<Z>]: K extends keyof F ? FieldFromOverride<F[K], z.infer<Z>[K]> : FieldBuilder<z.infer<Z>[K]>;
+type MergedFieldsFromZodObject<Z extends z.ZodObject, F, Om extends readonly string[] = readonly [], AI extends string | undefined = undefined> = {
+    [K in keyof Z["shape"] as K extends Om[number] ? never : K]: K extends keyof F ? FieldFromOverride<F[K], AutoFieldFromZod<K, Z["shape"][K], AI>> : AutoFieldFromZod<K, Z["shape"][K], AI>;
 };
 /** Non-`fields` portion of the opts — shared across the public type and
  * the function's inferred-`F` signature. Tracks `EntityDef` so any new
@@ -56,8 +136,15 @@ export interface EntityFromZodOpts<Z extends z.ZodObject = z.ZodObject> extends
      *     });
      */
     fields?: {
-        [K in keyof z.infer<Z> & string]?: EntityFromZodFieldOverride<z.infer<Z>[K]>;
+        [K in keyof Z["shape"] & string]?: AnyFieldBuilder | ((auto: AutoFieldFromZod<K, Z["shape"][K]>) => AnyFieldBuilder);
     };
+    /** Fields whose Zod name ends with this suffix pick up `.indexed()` —
+     * intended for the common FK-naming convention (`/ID$/` → `autoIndex: "ID"`).
+     * Suppressed for any key that supplies a builder-form override. */
+    autoIndex?: string;
+    /** Field names to drop entirely from the produced entity. Common when the
+     * source Zod was generated from a DTO that carries transport-only keys. */
+    omit?: readonly string[];
 }
 /**
  * Convert a `z.object({ ... })` into an `EntityDef`. Each key on the Zod
@@ -84,7 +171,33 @@ export interface EntityFromZodOpts<Z extends z.ZodObject = z.ZodObject> extends
  * shape and validation; `link(...)` remains the source of truth for the
  * graph.
  */
-export declare function entityFromZod<Z extends z.ZodObject, const F = Record<never, never>>(zSchema: Z, opts: EntityFromZodOptsBase & {
-    fields?: F & EntityFromZodFieldOverrides<Z> & NoExtraZodFieldKeys<Z, F>;
-}): EntityDef<MergedFieldsFromZodObject<Z, F>>;
+export declare function entityFromZod<Z extends z.ZodObject, const F = Record<never, never>, const Om extends readonly (keyof Z["shape"] & string)[] = readonly [], const AI extends string | undefined = undefined>(zSchema: Z, opts: EntityFromZodOptsBase & {
+    fields?: F & EntityFromZodFieldOverrides<Z, AI> & NoExtraZodFieldKeys<Z, F>;
+    autoIndex?: AI;
+    omit?: Om;
+}): EntityDef<MergedFieldsFromZodObject<Z, F, Om, AI>>;
+/**
+ * Map a whole `{key: ZodObject}` module (e.g. an OpenAPI-generated barrel)
+ * into an entities record by calling `entityFromZod` per key with shared
+ * opts. The entity key in the returned record is the input key; the registry
+ * name is auto-derived (PascalCase of the key) by `compileSchema` — no need
+ * to spell `name` per entity.
+ *
+ *     const entities = entitiesFromZod(generatedZods, {
+ *       loadStrategy: LoadStrategy.Eager,
+ *       autoIndex: "ID",
+ *       omit: ["createdAt", "updatedAt"],
+ *     });
+ *     const schema = defineSchema({ entities, links: { ... } });
+ *
+ * Per-entity overrides are not threaded — drop down to `entityFromZod` for
+ * the handful that need a custom `fields` map or distinct `loadStrategy`.
+ */
+type EntitiesFromZodResult<Zods extends Record<string, z.ZodObject>, Om extends readonly string[], AI extends string | undefined> = {
+    [K in keyof Zods]: EntityDef<MergedFieldsFromZodObject<Zods[K], Record<never, never>, Om, AI>>;
+};
+export declare function entitiesFromZod<Zods extends Record<string, z.ZodObject>, const Om extends readonly string[] = readonly [], const AI extends string | undefined = undefined>(zods: Zods, opts: Pick<EntityFromZodOptsBase, "loadStrategy" | "usedForPartialIndexes"> & {
+    autoIndex?: AI;
+    omit?: Om;
+}): EntitiesFromZodResult<Zods, Om, AI>;
 export {};

package/dist/schema/zod.js

@@ -82,9 +82,19 @@ export function fromZod(zSchema) {
  */
 export function entityFromZod(zSchema, opts) {
     const overrides = (opts.fields ?? {});
+    const omitted = new Set(opts.omit ?? []);
+    const autoIndexSuffix = opts.autoIndex != null && opts.autoIndex !== "" ? opts.autoIndex : null;
     const fieldsRecord = {};
     for (const [key, fieldSchema] of Object.entries(zSchema.shape)) {
-        const auto = key === "id" ? fields.id() : fromZod(fieldSchema);
+        if (omitted.has(key)) {
+            continue;
+        }
+        let auto = key === "id" ? fields.id() : fromZod(fieldSchema);
+        if (autoIndexSuffix != null &&
+            key !== "id" &&
+            key.endsWith(autoIndexSuffix)) {
+            auto = auto.indexed();
+        }
         const override = overrides[key];
         fieldsRecord[key] =
             typeof override === "function"
@@ -99,3 +109,15 @@ export function entityFromZod(zSchema, opts) {
         fields: fieldsRecord,
     });
 }
+export function entitiesFromZod(zods, opts) {
+    const out = {};
+    for (const [key, zod] of Object.entries(zods)) {
+        out[key] = entityFromZod(zod, {
+            loadStrategy: opts.loadStrategy,
+            usedForPartialIndexes: opts.usedForPartialIndexes,
+            autoIndex: opts.autoIndex,
+            omit: opts.omit,
+        });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zerodrift",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "private": false,
   "description": "A TypeScript local-first sync engine: synchronous in-memory reads, optimistic writes, realtime SSE sync, offline IndexedDB persistence. Runs in the browser and in Node.",
   "license": "MIT",