zerodrift 1.0.0

package/dist/schema/createStore.js

@@ -0,0 +1,264 @@
+import { action, computed } from "mobx";
+import { ModelRegistry } from "../core/ModelRegistry";
+import { prop } from "../core/ObjectPool";
+import { installActionMethod, installComputedAccessor, } from "../core/refAccessors";
+import { compileSchema } from "./compile";
+/**
+ * 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 function createStore(opts) {
+    const compiled = compileSchema(opts.schema);
+    const sm = opts.storeManager;
+    const merged = mergeExtensions(opts.extensions);
+    for (const [entityKey, registryName] of compiled.nameByKey) {
+        const defs = merged.get(entityKey);
+        if (defs == null) {
+            continue;
+        }
+        applyExtension(registryName, defs, sm);
+    }
+    const store = {
+        batch: sm.batch.bind(sm),
+        atomic: sm.atomic.bind(sm),
+        undo: () => sm.undo(),
+        redo: () => sm.redo(),
+        get undoDepth() {
+            return sm.transactionQueue.undoDepth;
+        },
+        get redoDepth() {
+            return sm.transactionQueue.redoDepth;
+        },
+        // Dynamic delegate (not `.bind(sm)`) so test-time `vi.spyOn(sm, "runUndoable")`
+        // intercepts calls. `bind` would capture the original at construction time.
+        runUndoable: ((fn, opts) => sm.runUndoable(fn, opts)),
+    };
+    for (const [entityKey, registryName] of compiled.nameByKey) {
+        store[entityKey] = createEntityNamespace(registryName, sm);
+    }
+    return store;
+}
+function mergeExtensions(extensions) {
+    const out = new Map();
+    if (extensions == null) {
+        return out;
+    }
+    for (const ext of extensions) {
+        for (const [entityKey, defs] of Object.entries(ext.byEntity)) {
+            if (defs == null) {
+                continue;
+            }
+            let bucket = out.get(entityKey);
+            if (bucket == null) {
+                bucket = { computed: {}, actions: {} };
+                out.set(entityKey, bucket);
+            }
+            Object.assign(bucket.computed, defs.computed);
+            Object.assign(bucket.actions, defs.actions);
+        }
+    }
+    return out;
+}
+function applyExtension(registryName, defs, sm) {
+    const meta = ModelRegistry.getModelMeta(registryName);
+    if (meta == null) {
+        return;
+    }
+    const prototype = meta.ctor.prototype;
+    for (const [name, fn] of Object.entries(defs.computed)) {
+        installComputedAccessor(prototype, name, fn);
+        meta.computedProps.add(name);
+        rebindComputedInstances(sm, registryName, name);
+    }
+    for (const [name, fn] of Object.entries(defs.actions)) {
+        installActionMethod(prototype, name, fn);
+        meta.actions.add(name);
+        rebindActionInstances(sm, registryName, name);
+    }
+}
+function rebindComputedInstances(sm, registryName, name) {
+    for (const instance of sm.objectPool.getAll(registryName)) {
+        const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(instance), name);
+        if (descriptor?.get == null) {
+            continue;
+        }
+        const fn = descriptor.get.bind(instance);
+        const memo = computed(fn);
+        Object.defineProperty(instance, name, {
+            get: () => memo.get(),
+            configurable: true,
+        });
+    }
+}
+function rebindActionInstances(sm, registryName, name) {
+    for (const instance of sm.objectPool.getAll(registryName)) {
+        const method = Object.getPrototypeOf(instance)[name];
+        if (typeof method !== "function") {
+            continue;
+        }
+        Object.defineProperty(instance, name, {
+            configurable: true,
+            writable: true,
+            value: action(method.bind(instance)),
+        });
+    }
+}
+function createEntityNamespace(registryName, sm) {
+    const meta = ModelRegistry.getModelMeta(registryName);
+    if (meta == null) {
+        throw new Error(`createStore: model "${registryName}" is not in ModelRegistry. ` +
+            `Did the schema fail to compile?`);
+    }
+    const Ctor = meta.ctor;
+    const toRecord = (model) => model;
+    const recordsFrom = (list) => list.map(toRecord);
+    function draft(arg) {
+        if (typeof arg === "string") {
+            return sm.getOrLoadById(registryName, arg).then((model) => {
+                if (model == null) {
+                    throw noRecordError(registryName, "draft", arg);
+                }
+                return toRecord(model);
+            });
+        }
+        const instance = new Ctor();
+        if (arg != null) {
+            instance.hydrate(arg);
+        }
+        // Make it observable now (still store===null, not pooled) so fields set
+        // between `draft(input)` and `save()` route through the property setter,
+        // not a shadowing own-property that makeModelObservable would later
+        // discard for the hydrated __raw_ value. Trade-off: a non-lazy
+        // @Reference / @ReferenceCollection eager-loads at draft() time rather
+        // than save() time (same load surface as create, earlier).
+        instance.makeModelObservable();
+        return toRecord(instance);
+    }
+    const ns = {
+        peek(id) {
+            const model = sm.objectPool.getById(registryName, id);
+            return model == null ? undefined : toRecord(model);
+        },
+        has(id) {
+            return sm.objectPool.getById(registryName, id) != null;
+        },
+        peekAll() {
+            return recordsFrom(sm.objectPool.getAll(registryName));
+        },
+        peekByIndex(key, value) {
+            return recordsFrom(sm.peekByIndex(registryName, key, value));
+        },
+        async get(id) {
+            const model = await sm.getOrLoadById(registryName, id);
+            return model == null ? null : toRecord(model);
+        },
+        async getByIds(ids) {
+            const list = await sm.getOrLoadByIds(registryName, [...ids]);
+            return recordsFrom(list);
+        },
+        async getByIndex(key, value) {
+            const list = await sm.getOrLoadCollection(registryName, key, value);
+            return recordsFrom(list);
+        },
+        async getByIndexValues(key, values) {
+            // Fan out in parallel; getOrLoadCollection is a no-op for already-covered
+            // (key, value) pairs, so re-firing for stale buckets is cheap.
+            await Promise.all(values.map((v) => sm.getOrLoadCollection(registryName, key, v)));
+            // After every bucket is loaded, walk the pool once per value to
+            // preserve input order, deduping records that match multiple values.
+            const seen = new Set();
+            const out = [];
+            for (const v of values) {
+                for (const m of sm.peekByIndex(registryName, key, v)) {
+                    if (!seen.has(m.id)) {
+                        seen.add(m.id);
+                        out.push(m);
+                    }
+                }
+            }
+            return recordsFrom(out);
+        },
+        async getAll() {
+            const list = await sm.getOrLoadAll(registryName);
+            return recordsFrom(list);
+        },
+        create(input) {
+            // store===null on a fresh instance, so commitCreate (not assign+save)
+            // is the create path; it folds into an open batch/atomic via the queue.
+            const instance = new Ctor();
+            instance.hydrate(input);
+            sm.commitCreate(instance);
+            return toRecord(instance);
+        },
+        patch(id, fields) {
+            const model = requireInstance(sm, registryName, id, "patch");
+            model.assign(fields);
+            model.save();
+            return toRecord(model);
+        },
+        delete(id) {
+            const model = requireInstance(sm, registryName, id, "delete");
+            sm.deleteModel(model);
+        },
+        archive(id) {
+            const model = requireInstance(sm, registryName, id, "archive");
+            sm.archiveModel(model);
+        },
+        draft,
+        seed(records) {
+            const seeded = sm.seed(registryName, records);
+            return seeded.map(toRecord);
+        },
+        async refresh(ids) {
+            const list = await sm.refreshModels(registryName, [...ids]);
+            return recordsFrom(list);
+        },
+        async refreshAll() {
+            await sm.refreshAllOfModel(registryName);
+        },
+        async refreshByIndex(key, value) {
+            // Delegates to StoreManager.refreshCollection which diffs previous vs
+            // fresh ids — server-removed records leave the pool, surviving
+            // instances are updated in place so held references stay valid.
+            const list = await sm.refreshCollection(registryName, key, value);
+            return recordsFrom(list);
+        },
+        watchAll(cb) {
+            return sm.objectPool.subscribe(registryName, cb);
+        },
+        watchByIndex(key, value, cb) {
+            return sm.objectPool.subscribe(registryName, (m) => prop(m, key) === value, cb);
+        },
+    };
+    // Stash the registry name on the namespace so the typed React hooks can
+    // recover it without forcing every callsite to repeat the string. Hidden
+    // from enumeration so it doesn't leak into JSON serialization or hover
+    // tooltips on the public surface.
+    Object.defineProperty(ns, REGISTRY_NAME, {
+        value: registryName,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return ns;
+}
+/** @internal Symbol carrying the ModelRegistry name on each namespace. */
+export const REGISTRY_NAME = Symbol("syncEngine/registryName");
+/** @internal Read the registry name a namespace was built for. */
+export function entityNamespaceRegistryName(ns) {
+    return ns[REGISTRY_NAME];
+}
+/** Shared "namespace write referenced a missing record" error. `scope`
+ * qualifies where we looked — pool-only (`requireInstance`) vs. fully
+ * resolved (`draft(id)` via getOrLoadById). */
+function noRecordError(registryName, action, id, scope = "") {
+    return new Error(`createStore.${registryName}.${action}: no record with id "${id}"${scope}.`);
+}
+function requireInstance(sm, registryName, id, action) {
+    const model = sm.objectPool.getById(registryName, id);
+    if (model == null) {
+        throw noRecordError(registryName, action, id, " in the pool");
+    }
+    return model;
+}

package/dist/schema/extend.d.ts

@@ -0,0 +1,46 @@
+import type { EntityKey, InferEntity } from "./infer";
+import type { SchemaDef } from "./types";
+export type ComputedFn<S extends SchemaDef, K extends EntityKey<S>> = (record: InferEntity<S, K>) => unknown;
+export type ActionFn<S extends SchemaDef, K extends EntityKey<S>> = (record: InferEntity<S, K>, ...args: never[]) => unknown;
+export interface ExtensionDef<S extends SchemaDef, K extends EntityKey<S>> {
+    computed?: Record<string, ComputedFn<S, K>>;
+    actions?: Record<string, ActionFn<S, K>>;
+}
+export type ExtensionMap<S extends SchemaDef> = {
+    [K in EntityKey<S>]?: ExtensionDef<S, K>;
+};
+/**
+ * Carries the schema generic and the *literal* `byEntity` shape so that
+ * `MergedExtensionMembers` can read each `computed[name]` / `actions[name]`
+ * function literal at the type level — that's how computed return types and
+ * action signatures end up on the records returned by `store.<entity>`.
+ */
+export interface ExtensionDescriptor<S extends SchemaDef, BE extends Record<string, unknown> = ExtensionMap<S>> {
+    /** @internal */
+    readonly _schema?: S;
+    readonly byEntity: BE;
+}
+export declare function extend<S extends SchemaDef, K extends EntityKey<S>, const Defs extends ExtensionDef<S, K>>(schema: S, entityKey: K, defs: Defs): ExtensionDescriptor<S, {
+    [P in K]: Defs;
+}>;
+export declare function extend<S extends SchemaDef, const BE extends ExtensionMap<S>>(schema: S, defs: BE): ExtensionDescriptor<S, BE>;
+type ComputedReturnsOf<Defs> = Defs extends {
+    computed?: infer C;
+} ? C extends Record<string, (...args: never[]) => unknown> ? {
+    readonly [P in keyof C]: ReturnType<C[P]>;
+} : Record<never, never> : Record<never, never>;
+type ActionMethodsOf<Defs> = Defs extends {
+    actions?: infer A;
+} ? A extends Record<string, (...args: never[]) => unknown> ? {
+    [P in keyof A]: A[P] extends (record: never, ...args: infer Args) => infer R ? (...args: Args) => R : never;
+} : Record<never, never> : Record<never, never>;
+type MembersFromOne<S extends SchemaDef, K extends EntityKey<S>, Ext> = Ext extends ExtensionDescriptor<S, infer BE> ? K extends keyof BE ? ComputedReturnsOf<BE[K]> & ActionMethodsOf<BE[K]> : Record<never, never> : Record<never, never>;
+/**
+ * Distribute `MembersFromOne` over each element of the extensions tuple
+ * (via `Exts[number]`) and intersect the resulting union — same shape as a
+ * tuple-rest recursive walk but without the recursion depth, so schemas with
+ * many extension descriptors stay well below TS's instantiation limits.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+export type MergedExtensionMembers<S extends SchemaDef, K extends EntityKey<S>, Exts extends readonly ExtensionDescriptor<S>[]> = Exts extends readonly [] ? Record<never, never> : UnionToIntersection<MembersFromOne<S, K, Exts[number]>>;
+export {};

package/dist/schema/extend.js

@@ -0,0 +1,6 @@
+export function extend(_schema, arg2, arg3) {
+    if (typeof arg2 === "string") {
+        return { byEntity: { [arg2]: arg3 } };
+    }
+    return { byEntity: arg2 };
+}

package/dist/schema/index.d.ts

@@ -0,0 +1,13 @@
+export { LoadStrategy } from "../core/types";
+export { defineSchema, entity, link, fields } from "./builders";
+export { fields as s } from "./builders";
+export { compileSchema } from "./compile";
+export type { CompiledSchema } from "./compile";
+export { createStore } from "./createStore";
+export type { EntityStore, EntityNamespace, RecordWithExtensions, StoreApi, } from "./createStore";
+export { extend } from "./extend";
+export type { ActionFn, ComputedFn, ExtensionDef, ExtensionDescriptor, ExtensionMap, MergedExtensionMembers, } from "./extend";
+export { fromZod, entityFromZod } from "./zod";
+export type { EntityFromZodFieldOverride, EntityFromZodOpts } from "./zod";
+export type { EntityDef, FieldBuilder, FieldKind, FieldMeta, LinkDef, LinkFromSpec, LinkToSpec, OnDelete, SchemaDef, } from "./types";
+export type { EntityKey, IndexedFieldKeys, InferCreateInput, InferEntity, InferUpdateInput, RelationCollection, } from "./infer";

package/dist/schema/index.js

@@ -0,0 +1,8 @@
+// Public schema-authoring surface. See agent-docs/RFC-schema-first-authoring.md.
+export { LoadStrategy } from "../core/types";
+export { defineSchema, entity, link, fields } from "./builders";
+export { fields as s } from "./builders";
+export { compileSchema } from "./compile";
+export { createStore } from "./createStore";
+export { extend } from "./extend";
+export { fromZod, entityFromZod } from "./zod";

package/dist/schema/infer.d.ts

@@ -0,0 +1,102 @@
+import type { EntityDef, FieldBuilder, FieldMeta, SchemaDef } from "./types";
+type FieldType<F> = F extends FieldBuilder<infer T, FieldMeta> ? T : never;
+type FieldIsNullable<F> = null extends FieldType<F> ? true : false;
+type FieldIsIndexed<F> = F extends FieldBuilder<unknown, infer M> ? M extends {
+    indexed: true;
+} ? true : false : false;
+export type EntityKey<S extends SchemaDef> = keyof S["entities"] & string;
+/**
+ * Field keys on an entity that were declared with `.indexed()`. Used to
+ * constrain `store.<entity>.loadByIndex(key, value)` so callers can only pass
+ * indexes that actually exist on disk.
+ */
+export type IndexedFieldKeys<S extends SchemaDef, K extends EntityKey<S>> = {
+    [P in keyof EntityFieldsRecord<S, K>]: FieldIsIndexed<EntityFieldsRecord<S, K>[P]> extends true ? P : never;
+}[keyof EntityFieldsRecord<S, K>] & string;
+type EntityFieldsRecord<S extends SchemaDef, K extends EntityKey<S>> = S["entities"][K] extends EntityDef<infer F> ? F : never;
+/**
+ * Stub shape for the reactive lazy-collection wrapper that today's
+ * `RefCollection` / `BackRef` runtime classes return. The schema-typed
+ * record can't extend `BaseModel` without coupling the type wall the
+ * proxy is meant to abstract, so we expose a narrow interface here and
+ * project `RefCollection` onto it when the typed client lands (Phase 3).
+ */
+export interface RelationCollection<T> {
+    load(): Promise<readonly T[]>;
+    readonly items: readonly T[];
+    /**
+     * Fires whenever the collection's items list changes (records added,
+     * removed, or replaced). Payload-less — re-read `items` inside `cb`.
+     * Returns an unsubscribe function. Same verb as `record.watch` /
+     * `store.<entity>.watchAll`.
+     */
+    watch(cb: () => void): () => void;
+}
+type EntityFieldTypes<S extends SchemaDef, K extends EntityKey<S>> = {
+    -readonly [P in keyof EntityFieldsRecord<S, K>]: FieldType<EntityFieldsRecord<S, K>[P]>;
+};
+type SingularRelationKey<S extends SchemaDef, K extends EntityKey<S>, LK extends keyof S["links"]> = S["links"][LK] extends {
+    from: {
+        entity: K;
+        as: infer A extends string;
+    };
+} ? A : never;
+type SingularRelationValue<S extends SchemaDef, K extends EntityKey<S>, LK extends keyof S["links"]> = S["links"][LK] extends {
+    from: {
+        entity: K;
+        field: infer FFK;
+    };
+    to: {
+        entity: infer TE extends string;
+    };
+} ? TE extends EntityKey<S> ? FFK extends keyof EntityFieldsRecord<S, K> ? FieldIsNullable<EntityFieldsRecord<S, K>[FFK]> extends true ? InferEntity<S, TE> | null : InferEntity<S, TE> : never : never : never;
+type SingularRelations<S extends SchemaDef, K extends EntityKey<S>> = {
+    [LK in keyof S["links"] as SingularRelationKey<S, K, LK>]: SingularRelationValue<S, K, LK>;
+};
+type ReverseCollectionKey<S extends SchemaDef, K extends EntityKey<S>, LK extends keyof S["links"]> = S["links"][LK] extends {
+    to: {
+        entity: K;
+        many: infer M extends string;
+    };
+} ? M : never;
+type ReverseCollectionValue<S extends SchemaDef, LK extends keyof S["links"]> = S["links"][LK] extends {
+    from: {
+        entity: infer FE extends string;
+    };
+} ? FE extends EntityKey<S> ? RelationCollection<InferEntity<S, FE>> : never : never;
+type ReverseCollections<S extends SchemaDef, K extends EntityKey<S>> = {
+    [LK in keyof S["links"] as ReverseCollectionKey<S, K, LK>]: ReverseCollectionValue<S, LK>;
+};
+/**
+ * The record shape for a schema entity: declared fields, plus singular
+ * relation properties for every link that originates on this entity, plus
+ * reverse-collection properties for every link that targets it.
+ *
+ * Does not include extension members (computed / actions) — those are layered
+ * in by `InferRecord` once `extend(...)` lands.
+ *
+ * Returned as a plain intersection — wrapping in a `Prettify` mapped type
+ * would force TS to materialize a fresh object per relation step every time
+ * `InferEntity` recurses through a link. Users can pretty their own aliases
+ * 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>;
+/**
+ * A create-input field is optional when the runtime can fill it without
+ * the caller: id-kind (BaseModel auto-assigns a UUID), defaulted fields,
+ * and schema fields explicitly marked optional (e.g. via Zod's `.optional()`).
+ */
+type IsOptionalCreateField<F> = F extends FieldBuilder<unknown, infer M> ? M extends {
+    kind: "id";
+} | {
+    default: unknown;
+} ? true : M extends {
+    optional: true;
+} ? true : false : false;
+export type InferCreateInput<S extends SchemaDef, K extends EntityKey<S>> = {
+    [P in keyof EntityFieldsRecord<S, K> as IsOptionalCreateField<EntityFieldsRecord<S, K>[P]> extends true ? never : P]: FieldType<EntityFieldsRecord<S, K>[P]>;
+} & {
+    [P in keyof EntityFieldsRecord<S, K> as IsOptionalCreateField<EntityFieldsRecord<S, K>[P]> extends true ? P : never]?: FieldType<EntityFieldsRecord<S, K>[P]>;
+};
+export type InferUpdateInput<S extends SchemaDef, K extends EntityKey<S>> = Partial<EntityFieldTypes<S, K>>;
+export {};

package/dist/schema/infer.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/types.d.ts

@@ -0,0 +1,76 @@
+import type { LoadStrategy, OnDelete } from "../core/types";
+export type FieldKind = "id" | "string" | "number" | "boolean" | "date" | "json" | "refId";
+export interface FieldMeta {
+    kind: FieldKind;
+    nullable: boolean;
+    optional: boolean;
+    indexed: boolean;
+    ephemeral: boolean;
+    default?: unknown;
+    refTarget?: string;
+    serializer?: (value: unknown) => unknown;
+    deserializer?: (raw: unknown) => unknown;
+}
+/**
+ * Carries two pieces of information through the type system:
+ *   T — the TS type the field exposes (`string`, `number | null`, `Date`, …).
+ *       `InferEntity` reads this to build the record shape.
+ *   M — the runtime metadata, with literal-preserved fields like
+ *       `kind: "refId"` and `refTarget: "team"` so `link(...)` / inference
+ *       can pull relation targets back out of the schema at the type level.
+ */
+export interface FieldBuilder<T, M extends FieldMeta = FieldMeta> {
+    /** @internal — phantom slot used only for type inference. */
+    readonly _t?: T;
+    readonly meta: M;
+    nullable(): FieldBuilder<T | null, M>;
+    indexed(): FieldBuilder<T, Omit<M, "indexed"> & {
+        indexed: true;
+    }>;
+    default(value: T): FieldBuilder<T, Omit<M, "default"> & {
+        default: T;
+    }>;
+    ephemeral(): FieldBuilder<T, M>;
+    serialize(fn: (value: T) => unknown): FieldBuilder<T, M>;
+    deserialize(fn: (raw: unknown) => T): FieldBuilder<T, M>;
+}
+export type AnyFieldBuilder = FieldBuilder<unknown, FieldMeta>;
+export interface EntityDef<F extends Record<string, AnyFieldBuilder> = Record<string, AnyFieldBuilder>> {
+    loadStrategy: LoadStrategy;
+    usedForPartialIndexes?: boolean;
+    /** Override the registry name. Defaults to PascalCase of the entity key at compile time. */
+    name?: string;
+    /** Forces a schemaVersion override. Otherwise computed by the compiler. */
+    version?: number;
+    /**
+     * Marks this entity as registered elsewhere (typically by `@ClientModel`).
+     * The compiler skips class generation and property/link registration for
+     * external entities, but still allows other schema entities to reference
+     * them via `s.refId(...)` and `link({ to: { entity: ... } })`. `name` must
+     * be set explicitly so the schema can resolve cross-references against the
+     * existing registry entry.
+     */
+    external?: boolean;
+    fields: F;
+}
+export interface LinkFromSpec<Entity extends string = string, Field extends string = string, As extends string = string> {
+    entity: Entity;
+    field: Field;
+    as: As;
+}
+export interface LinkToSpec<Entity extends string = string, Many extends string = string> {
+    entity: Entity;
+    many: Many;
+    lazy?: boolean;
+}
+export type { OnDelete };
+export interface LinkDef<FromEntity extends string = string, FromField extends string = string, As extends string = string, ToEntity extends string = string, Many extends string = string> {
+    from: LinkFromSpec<FromEntity, FromField, As>;
+    to: LinkToSpec<ToEntity, Many>;
+    onDelete?: OnDelete;
+}
+export type AnyLinkDef = LinkDef;
+export interface SchemaDef<E extends Record<string, EntityDef> = Record<string, EntityDef>, L extends Record<string, AnyLinkDef> = Record<string, AnyLinkDef>> {
+    entities: E;
+    links: L;
+}

package/dist/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/zod.d.ts

@@ -0,0 +1,90 @@
+import type { z } from "zod";
+import type { AnyFieldBuilder, EntityDef, FieldBuilder } from "./types";
+/**
+ * Convert any Zod schema into the equivalent schema-first `FieldBuilder`.
+ * Handles the common nullable / optional / default modifiers; anything more
+ * structured (objects, arrays, unions, enums) collapses to `s.json<T>()` so
+ * the runtime stores the raw value and the TS type still flows from Zod.
+ *
+ * Zod is an optional peer dependency — calling this function requires the
+ * caller to have installed `zod`.
+ */
+export declare function fromZod<Z extends z.ZodType>(zSchema: Z): FieldBuilder<z.infer<Z>>;
+/**
+ * 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 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.
+ */
+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>;
+/**
+ * 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]>;
+};
+/** Non-`fields` portion of the opts — shared across the public type and
+ * the function's inferred-`F` signature. Tracks `EntityDef` so any new
+ * top-level knob (like `external`) has to be added here intentionally. */
+type EntityFromZodOptsBase = Pick<EntityDef, "loadStrategy" | "usedForPartialIndexes" | "name" | "version">;
+export interface EntityFromZodOpts<Z extends z.ZodObject = z.ZodObject> extends EntityFromZodOptsBase {
+    /**
+     * Per-field overrides applied after the Zod-derived `FieldBuilder`.
+     * Keys are constrained to fields actually declared on the Zod object,
+     * so typos surface at compile time.
+     *
+     *     entityFromZod(ZodIssue, {
+     *       loadStrategy: LoadStrategy.Eager,
+     *       fields: {
+     *         teamId:    s.refId("team").nullable().indexed(),  // replace
+     *         email:     (b) => b.indexed(),                     // chain
+     *         draftNote: (b) => b.ephemeral(),
+     *       },
+     *     });
+     */
+    fields?: {
+        [K in keyof z.infer<Z> & string]?: EntityFromZodFieldOverride<z.infer<Z>[K]>;
+    };
+}
+/**
+ * Convert a `z.object({ ... })` into an `EntityDef`. Each key on the Zod
+ * object becomes a field via `fromZod`, then `opts.fields[key]` (if
+ * present) is applied — either chained onto the auto-derived builder, or
+ * used as a full replacement.
+ *
+ * The override map is captured via a `const`-modified generic so per-field
+ * metadata (`.indexed()`, refId target, …) flows into the returned
+ * `EntityDef` — `IndexedFieldKeys`, `getByIndex`, `peekByIndex`, and the
+ * typed React hooks all see Zod-built entities the same way they see
+ * hand-written ones.
+ *
+ * `F` is inferred from the provided `fields` map while an intersected
+ * override-map type supplies allowed keys and key-specific contextual typing
+ * for the `(auto) => ...` parameter. When no `fields` map is provided, `F`
+ * defaults to an empty record so untouched Zod fields stay on the auto-derived
+ * `FieldBuilder<z.infer<...>>` path.
+ * `EntityFromZodOpts<Z>` keeps the strict union for users who pre-type
+ * their opts variables.
+ *
+ * Only single-record entities are produced; relations still belong in the
+ * schema's `links` block. Treat the Zod object as the source of field
+ * 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 {};