@abloatai/ablo 0.3.0

package/dist/schema/queries.js

@@ -0,0 +1,145 @@
+/**
+ * Schema Query Definitions
+ *
+ * A query is a zod input schema + a string reference to a schema model
+ * that the query returns. Types flow via `z.infer` for inputs and
+ * `InferModel` for results — the same inference path `model` and
+ * `relation` already use. No second type system.
+ *
+ * Usage:
+ *   import { z } from 'zod';
+ *   import {
+ *     defineSchema, defineQueries, model, query, relation,
+ *   } from '@ablo/sync-engine/schema';
+ *
+ *   const schema = defineSchema({
+ *     slideLayer: model(
+ *       { slideId: z.string(), type: z.string() },
+ *       { slide: relation.belongsTo('slides', 'slideId') },
+ *       { load: 'lazy', typename: 'SlideLayer', persist: {} },
+ *     ),
+ *   });
+ *
+ *   const queries = defineQueries(schema, {
+ *     slideLayersByDeck: query({
+ *       input:   z.object({ deckId: z.string() }),
+ *       returns: 'slideLayer',   // ← type-checked against schema.models
+ *     }),
+ *   });
+ *
+ *   type Input  = InferQueryInput<typeof queries.queries.slideLayersByDeck>;
+ *   //    ^? { deckId: string }
+ *   type Result = InferQueryResult<
+ *     typeof schema,
+ *     typeof queries.queries.slideLayersByDeck
+ *   >;
+ *   //    ^? Array<SlideLayer>
+ *
+ * Design notes:
+ *
+ *  - `query()` accepts any string for `returns`. The constraint that it
+ *    must reference a real schema model is applied when the query is
+ *    passed to `defineQueries(schema, ...)`. This mirrors how
+ *    `relation.belongsTo('projects', 'projectId')` accepts a plain
+ *    string at the factory and defers the cross-reference check to
+ *    schema assembly time.
+ *
+ *  - Queries do NOT carry a `name` until they pass through
+ *    `defineQueries()`. The name is assigned from the record key —
+ *    same pattern as `defineSchema({ tasks: model(...) })` where the
+ *    model name is the record key, not a field on the model factory.
+ *
+ *  - All queries return an array of a single model type. Multi-model
+ *    fetches (e.g., files + folders) are expressed as multiple queries
+ *    in a single batch at dispatch time, not as "bundle" shapes in the
+ *    schema. This keeps each `QueryDef` pointed at exactly one model
+ *    and lets the generic loader hydrate via a single
+ *    `schema.models[queryDef.returns]` lookup.
+ */
+import { AbloValidationError } from '../errors.js';
+// ── query() factory ───────────────────────────────────────────────────────
+/**
+ * Define a query.
+ *
+ * `TReturns` is a `const` generic so TypeScript preserves the literal
+ * type of the `returns` value at call time (e.g., `'slideLayer'`
+ * instead of widening to `string`). This is what lets `defineQueries`
+ * type-check `returns` against the schema's model keys without
+ * requiring the consumer to write `as const` manually.
+ *
+ * ```ts
+ * const slideLayersByDeck = query({
+ *   input:   z.object({ deckId: z.string() }),
+ *   returns: 'slideLayer',
+ * });
+ * ```
+ */
+export function query(spec) {
+    return {
+        input: spec.input,
+        returns: spec.returns,
+    };
+}
+// ── defineQueries() factory ───────────────────────────────────────────────
+/**
+ * Define a typed query set against a schema.
+ *
+ * Each entry's `returns` field is constrained to the schema's model
+ * names at compile time via the `Q` generic bound to `QueryRecord<S>`.
+ * A query whose `returns` does not match a known model will fail at
+ * the `defineQueries` call site with a TypeScript error, not at
+ * runtime.
+ *
+ * The factory also performs a runtime validation of the same
+ * invariant. This catches the edge case where the schema and the
+ * queries live in separate modules that drift out of sync — for
+ * example, when a developer removes a model from the schema without
+ * updating the queries that referenced it. The runtime error points
+ * at the specific offending query and lists the available models,
+ * which is a nicer failure mode than a generic "property does not
+ * exist" error deep inside the loader.
+ *
+ * Each resolved query gets its `name` populated from the record key:
+ * `queries.slideLayersByDeck.name === 'slideLayersByDeck'`. Wire
+ * dispatch, the Go registry, and the loader orchestrator all read
+ * `queryDef.name` directly rather than re-deriving it.
+ *
+ * ```ts
+ * const schema = defineSchema({
+ *   slideLayer: model(
+ *     { slideId: z.string() },
+ *     {},
+ *     { load: 'lazy', typename: 'SlideLayer', persist: {} },
+ *   ),
+ * });
+ *
+ * const queries = defineQueries(schema, {
+ *   slideLayersByDeck: query({
+ *     input:   z.object({ deckId: z.string() }),
+ *     returns: 'slideLayer',   // ← type-checked
+ *   }),
+ * });
+ * ```
+ */
+export function defineQueries(schema, queries) {
+    // Rebuild the queries record with `name` populated per entry. Same
+    // shallow-spread strategy `defineSchema` uses for `typename` / `persist`
+    // defaults — preserves input references, avoids mutating `readonly`
+    // fields in place, and keeps each resolved `QueryDef` immutable from
+    // construction onward.
+    const resolvedQueries = {};
+    for (const [name, def] of Object.entries(queries)) {
+        if (!(def.returns in schema.models)) {
+            throw new AbloValidationError(`defineQueries: query "${name}" declares returns: "${def.returns}", ` +
+                `which is not a model in the schema. ` +
+                `Available models: ${Object.keys(schema.models).join(', ') || '(none)'}`, { code: 'query_returns_unknown_model' });
+        }
+        resolvedQueries[name] = { ...def, name };
+    }
+    return {
+        schema,
+        // Cast back to Q: the rebuild only added `name` (already optional on
+        // QueryDef) to each entry, so the shape is structurally unchanged.
+        queries: resolvedQueries,
+    };
+}

package/dist/schema/relation.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Schema Relation Definitions
+ *
+ * Declarative relations between models. Used for:
+ * - FK index registration (ObjectPool.registerForeignKey)
+ * - Model create priority derivation (parents before children)
+ * - Query include/join support
+ *
+ * Usage:
+ *   import { relation } from '@ablo/sync-engine/schema';
+ *
+ *   const taskRelations = {
+ *     project: relation.belongsTo('projects', 'projectId'),
+ *     assignee: relation.belongsTo('users', 'assigneeId'),
+ *     comments: relation.hasMany('comments', 'taskId'),
+ *   };
+ */
+/**
+ * Options for `relation.belongsTo(...)`. All default to `false` — behavior
+ * is opt-in per relation.
+ *
+ * When `index: true`, the sync engine registers an O(1) foreign-key index
+ * on the child model's ObjectPool entry at construction time, so that
+ * `pool.getByForeignKey(childType, foreignKey, parentId)` becomes constant-
+ * time instead of a full scan. Use on hot paths like `SlideLayer.slideId`
+ * where you frequently want "all layers for this slide."
+ *
+ * When `enrich: true`, incoming deltas for the child model have their
+ * parent reference auto-populated from the ObjectPool before the model
+ * data lands. I.e., a delta for `Task { teamId: 't1' }` picks up the
+ * `teams:t1` entity from the pool and attaches it as `data.team`, so
+ * consumers can read `task.team` directly without a second lookup.
+ * If the parent isn't in the pool yet, enrichment silently no-ops
+ * (the child data is still applied) — enrichment is best-effort.
+ *
+ * When `defer: true`, the FK-create-priority computer (Tarjan SCC in
+ * `client/createSyncEngine.ts`) ignores this edge when building the
+ * dependency graph. Use on the *soft* side of a real cycle to break it
+ * deterministically — i.e. the side where you're willing to insert the
+ * child first with the FK left null and patch it in a follow-up
+ * UPDATE. The other side of the cycle then becomes a strict topological
+ * predecessor, so the child gets a higher priority than the parent
+ * instead of being tied with it.
+ *
+ * `defer` only affects priority computation, not what the engine sends
+ * on the wire — it does NOT auto-rewrite an INSERT to (insert-null +
+ * update-later). Pair with a Postgres `DEFERRABLE INITIALLY DEFERRED`
+ * constraint when you actually want the FK check to be relaxed at the
+ * database level. Example use case:
+ *
+ *   ```ts
+ *   layouts: model({ deckId: z.string().nullish() }, {
+ *     // The deck-owns-layout link is nullable AND the consumer always
+ *     // creates the layout first; mark it `defer` so SlideDeck can
+ *     // commit ahead of Layout instead of being trapped in the same
+ *     // SCC priority bucket.
+ *     deck: relation.belongsTo('slideDecks', 'deckId', { defer: true }),
+ *   }),
+ *   ```
+ */
+export interface BelongsToOptions {
+    readonly index?: boolean;
+    readonly enrich?: boolean;
+    readonly defer?: boolean;
+}
+declare const __relationType: unique symbol;
+declare const __relationTarget: unique symbol;
+declare const __relationField: unique symbol;
+export type RelationType = 'belongsTo' | 'hasMany' | 'hasOne';
+/**
+ * A relation definition with embedded type information.
+ *
+ * The 4th generic `Options` captures per-relation options at the type
+ * level (currently only `belongsTo` uses this — `hasMany`/`hasOne`
+ * default to empty). The `const Opts` modifier on the `belongsTo`
+ * factory preserves literal inference: `{ enrich: true }` narrows to
+ * `true`, not `boolean`, so future type-level features (like
+ * `InferModel` auto-adding enriched-parent properties) can read the
+ * literal value off the relation def at compile time.
+ *
+ * `options` is always present at runtime — the factory assigns an
+ * empty object when the caller omits it, which keeps
+ * `relation.options.index` / `relation.options.enrich` safe to read
+ * without a null guard downstream.
+ */
+export interface RelationDef<Type extends RelationType = RelationType, Target extends string = string, Field extends string = string, Options extends BelongsToOptions = BelongsToOptions> {
+    readonly [__relationType]: Type;
+    readonly [__relationTarget]: Target;
+    readonly [__relationField]: Field;
+    /** Runtime metadata */
+    readonly type: Type;
+    readonly target: Target;
+    /**
+     * The child model's JS field that holds the parent's id. Always the
+     * camelCase schema field name — used by the client ObjectPool to read
+     * `model[foreignKey]`, by `LazyReferenceCollection` for IndexedDB
+     * index keys, and by `ModelRegistry` for cascade wiring. Never used
+     * verbatim in raw SQL.
+     */
+    readonly foreignKey: Field;
+    /**
+     * The same foreign key expressed as a database column identifier. Set
+     * by `defineSchema` when a `casing` option is configured (e.g.
+     * `'snake_case'` produces `message_id` from `messageId`). Used by
+     * server-side SQL compilers to interpolate the real column name into
+     * queries — `postgres.camel`-style data-layer transforms do NOT rewrite
+     * identifiers embedded in raw SQL, so the translation has to happen
+     * somewhere, and schema-build time is the one-place-once answer.
+     *
+     * Defaults to {@link foreignKey} when `casing` is unset (identity) —
+     * the SDK stays backward-compatible for consumers whose DB columns
+     * already match their JS field names.
+     */
+    readonly foreignKeyColumn: string;
+    readonly options: Options;
+    /**
+     * Optional sort field for `hasMany` relations. When set, the
+     * generated relation getter sorts results by this field. Populated
+     * by `relation.hasMany(target, fk, { orderBy: 'fieldName' })`.
+     */
+    readonly _orderBy?: string;
+}
+export declare const relation: {
+    /**
+     * This model belongs to another model via a foreign key.
+     * e.g., Task belongs to Project via projectId
+     *
+     * ```ts
+     * // Simple reference (no options)
+     * project: relation.belongsTo('projects', 'projectId'),
+     *
+     * // Register an FK index for O(1) child lookups
+     * slide: relation.belongsTo('slides', 'slideId', { index: true }),
+     *
+     * // Auto-populate the parent on delta arrival
+     * team: relation.belongsTo('teams', 'teamId', { enrich: true }),
+     *
+     * // Both
+     * parent: relation.belongsTo('threads', 'parentId', { index: true, enrich: true }),
+     *
+     * // Mark the soft side of a cycle so the priority computer breaks
+     * // the cycle deterministically instead of tying the two models.
+     * deck: relation.belongsTo('slideDecks', 'deckId', { defer: true }),
+     * ```
+     */
+    readonly belongsTo: <Target extends string, Field extends string, const Opts extends BelongsToOptions = Record<string, never>>(target: Target, foreignKey: Field, options?: Opts) => RelationDef<"belongsTo", Target, Field, Opts>;
+    /**
+     * This model has many of another model.
+     * e.g., Project has many Tasks (via Task.projectId)
+     *
+     * At runtime, generates a getter on the parent model that returns
+     * all child models matching the FK via ObjectPool.getByForeignKey.
+     * The FK index on the child model is auto-registered.
+     *
+     * ```ts
+     * slides: relation.hasMany('slideLayers', 'slideId'),
+     * // → deck.slides returns all SlideLayer[] where slideId === deck.id
+     *
+     * slides: relation.hasMany('slideLayers', 'slideId', { orderBy: 'zIndex' }),
+     * // → deck.slides returns SlideLayer[] sorted by zIndex ascending
+     * ```
+     */
+    readonly hasMany: <Target extends string, Field extends string>(target: Target, foreignKey: Field, options?: {
+        orderBy?: string;
+    }) => RelationDef<"hasMany", Target, Field>;
+    /**
+     * This model has one of another model.
+     * e.g., User has one Profile (via Profile.userId)
+     */
+    readonly hasOne: <Target extends string, Field extends string>(target: Target, foreignKey: Field) => RelationDef<"hasOne", Target, Field>;
+};
+export {};

package/dist/schema/relation.js

@@ -0,0 +1,104 @@
+/**
+ * Schema Relation Definitions
+ *
+ * Declarative relations between models. Used for:
+ * - FK index registration (ObjectPool.registerForeignKey)
+ * - Model create priority derivation (parents before children)
+ * - Query include/join support
+ *
+ * Usage:
+ *   import { relation } from '@ablo/sync-engine/schema';
+ *
+ *   const taskRelations = {
+ *     project: relation.belongsTo('projects', 'projectId'),
+ *     assignee: relation.belongsTo('users', 'assigneeId'),
+ *     comments: relation.hasMany('comments', 'taskId'),
+ *   };
+ */
+// ── Internal relation builder ─────────────────────────────────────────────
+class RelationBuilder {
+    type;
+    target;
+    foreignKey;
+    /**
+     * Starts out identical to {@link foreignKey}. `defineSchema` overwrites
+     * this when a `casing` option is set — it's declared as a mutable
+     * (non-readonly on the implementation side) so the schema builder can
+     * resolve it once at build time without allocating a new object per
+     * relation. Consumers see it typed as `readonly` on {@link RelationDef}.
+     */
+    foreignKeyColumn;
+    options;
+    /**
+     * Stashed by `hasMany` when the caller provides `{ orderBy }`. Read
+     * back in `createSyncEngine` to install the sort comparator on the
+     * generated relation getter. Declared on the builder so both writer
+     * and reader stay type-safe — no `as unknown as Record<...>` smuggle.
+     */
+    _orderBy;
+    constructor(type, target, foreignKey, options) {
+        this.type = type;
+        this.target = target;
+        this.foreignKey = foreignKey;
+        this.foreignKeyColumn = foreignKey;
+        this.options = (options ?? {});
+    }
+}
+// ── Public relation factories ─────────────────────────────────────────────
+export const relation = {
+    /**
+     * This model belongs to another model via a foreign key.
+     * e.g., Task belongs to Project via projectId
+     *
+     * ```ts
+     * // Simple reference (no options)
+     * project: relation.belongsTo('projects', 'projectId'),
+     *
+     * // Register an FK index for O(1) child lookups
+     * slide: relation.belongsTo('slides', 'slideId', { index: true }),
+     *
+     * // Auto-populate the parent on delta arrival
+     * team: relation.belongsTo('teams', 'teamId', { enrich: true }),
+     *
+     * // Both
+     * parent: relation.belongsTo('threads', 'parentId', { index: true, enrich: true }),
+     *
+     * // Mark the soft side of a cycle so the priority computer breaks
+     * // the cycle deterministically instead of tying the two models.
+     * deck: relation.belongsTo('slideDecks', 'deckId', { defer: true }),
+     * ```
+     */
+    belongsTo(target, foreignKey, options) {
+        return new RelationBuilder('belongsTo', target, foreignKey, options ?? {});
+    },
+    /**
+     * This model has many of another model.
+     * e.g., Project has many Tasks (via Task.projectId)
+     *
+     * At runtime, generates a getter on the parent model that returns
+     * all child models matching the FK via ObjectPool.getByForeignKey.
+     * The FK index on the child model is auto-registered.
+     *
+     * ```ts
+     * slides: relation.hasMany('slideLayers', 'slideId'),
+     * // → deck.slides returns all SlideLayer[] where slideId === deck.id
+     *
+     * slides: relation.hasMany('slideLayers', 'slideId', { orderBy: 'zIndex' }),
+     * // → deck.slides returns SlideLayer[] sorted by zIndex ascending
+     * ```
+     */
+    hasMany(target, foreignKey, options) {
+        const builder = new RelationBuilder('hasMany', target, foreignKey);
+        if (options?.orderBy) {
+            builder._orderBy = options.orderBy;
+        }
+        return builder;
+    },
+    /**
+     * This model has one of another model.
+     * e.g., User has one Profile (via Profile.userId)
+     */
+    hasOne(target, foreignKey) {
+        return new RelationBuilder('hasOne', target, foreignKey);
+    },
+};

package/dist/schema/schema.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Schema Definition + Type Inference
+ *
+ * defineSchema() wraps your models. Types are inferred via Zod — no custom type system.
+ *
+ * Usage:
+ *   import { z } from 'zod';
+ *   import { defineSchema, model, relation } from '@ablo/sync-engine/schema';
+ *
+ *   const schema = defineSchema({
+ *     tasks: model({
+ *       title: z.string(),
+ *       status: z.enum(['todo', 'doing', 'done']).default('todo'),
+ *       projectId: z.string().optional(),
+ *     }, {
+ *       project: relation.belongsTo('projects', 'projectId'),
+ *     }),
+ *   });
+ *
+ *   type Task = InferModel<typeof schema, 'tasks'>;
+ */
+import { z } from 'zod';
+import type { ModelDef, RelationRecord } from './model.js';
+import type { RelationDef } from './relation.js';
+/** The set of built-in casing conventions supported by `defineSchema`. */
+export type CasingConvention = 'snake_case' | 'camelCase';
+/** Plug point for custom conventions (e.g. mixed legacy databases). */
+export type CasingFn = (jsField: string) => string;
+/** `defineSchema`'s casing option. Identity when unset. */
+export type Casing = CasingConvention | CasingFn;
+/**
+ * The identity shape passed to {@link IdentityRole.extract}. Free-form
+ * `Record<string, unknown>` because each schema chooses what fields
+ * its roles read — Ablo's roles read `organizationId`/`userId`/`teamIds`;
+ * a tenant model with `regionId`/`customerId` is equally valid. The
+ * server hands its resolved identity (whatever shape its AuthProvider
+ * returns) straight to `extract` without translation.
+ */
+export type IdentityContext = Record<string, unknown>;
+/**
+ * Open registration of an identity-anchored sync-group. Each role
+ * declares (a) a free-form `kind` label (purely for diagnostics), (b)
+ * a `template` containing a single `{id}` placeholder, and (c) an
+ * `extract` function that pulls the relevant ids out of an arbitrary
+ * identity context.
+ *
+ * No closed enum. A consumer whose identity shape is
+ * `{ regionId, customerId }` registers:
+ *
+ * ```ts
+ * defineSchema({ ... }, {
+ *   identityRoles: [
+ *     { kind: 'region',   template: 'region:{id}',
+ *       extract: (i) => i.regionId ? [String(i.regionId)] : [] },
+ *     { kind: 'customer', template: 'customer:{id}',
+ *       extract: (i) => i.customerId ? [String(i.customerId)] : [] },
+ *   ],
+ * });
+ * ```
+ *
+ * The server's `composeIdentitySyncGroups` walks every registered role
+ * and produces the union — no hardcoded `org:` / `user:` / `team:`
+ * anywhere in the engine.
+ */
+export interface IdentityRole {
+    /** Free-form label for diagnostics/logging. Not parsed. */
+    readonly kind: string;
+    /**
+     * Sync-group template with a single `{id}` placeholder. Substituted
+     * once per id returned by `extract`. Example: `'org:{id}'` →
+     * `'org:abc-123'`.
+     */
+    readonly template: string;
+    /**
+     * Extract zero or more ids from the resolved identity context. Pure
+     * function — must not allocate persistent state, must be safe to
+     * call once per request. Return an empty array when the role
+     * doesn't apply to this identity.
+     */
+    readonly extract: (identity: IdentityContext) => readonly string[];
+}
+/** Options for `defineSchema`. */
+export interface DefineSchemaOptions {
+    /**
+     * How to translate camelCase JS field names into database column
+     * identifiers. Applied once, at schema build, to every relation's
+     * `foreignKey` to produce `foreignKeyColumn`. Consumers whose DB
+     * columns already match their JS field names can omit this — the
+     * default is identity (no transform).
+     *
+     * Accepts a named convention or a custom function:
+     *
+     * ```ts
+     * defineSchema({ ... }, { casing: 'snake_case' })
+     * defineSchema({ ... }, { casing: (key) => key.toUpperCase() })
+     * ```
+     */
+    readonly casing?: Casing;
+    /**
+     * Identity-anchored sync-group roles. Server's
+     * `composeIdentitySyncGroups` iterates these to build the
+     * participant's allowed-set, replacing the prior hardcoded
+     * `org:/user:/team:` triad in `@ablo/schema`. See {@link IdentityRole}
+     * for the open-registration shape — no closed enum, consumer fully
+     * controls both the template string and the extractor function.
+     *
+     * Leave unset for schemas that don't need identity-derived scoping
+     * (e.g. fully public read models). When unset, `composeIdentitySyncGroups`
+     * returns `[]` and consumers fall back to whatever explicit
+     * `syncGroups` the AuthProvider attaches to the Identity.
+     */
+    readonly identityRoles?: readonly IdentityRole[];
+}
+/** A record of model names → model definitions */
+export type SchemaRecord = Record<string, ModelDef>;
+/** Base fields every synced model gets automatically */
+declare const baseFieldsSchema: z.ZodObject<{
+    id: z.ZodString;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+    organizationId: z.ZodOptional<z.ZodString>;
+    createdBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The base fields type — pure data columns. */
+export type BaseModelFields = z.infer<typeof baseFieldsSchema>;
+/**
+ * Methods every dynamic model class inherits from `Model`. Intersected
+ * into `InferModel` (the read-side type) but NOT into `InferCreate` /
+ * `UpdatePatch` — methods aren't legal create/update inputs.
+ */
+export interface BaseModelMethods {
+    /** Wire-format model name (e.g. `'Slide'`, `'Comment'`). */
+    getModelName(): string;
+    /** Plain-object serialization suitable for sending over the wire. */
+    toJSON(): Record<string, unknown>;
+}
+/** The schema object returned by defineSchema() */
+export interface Schema<S extends SchemaRecord = SchemaRecord> {
+    /** The raw model definitions */
+    readonly models: S;
+    /** Zod schemas with base fields merged in */
+    readonly validators: {
+        readonly [K in keyof S]: S[K] extends ModelDef<infer Shape> ? z.ZodObject<Shape & typeof baseFieldsSchema.shape> : never;
+    };
+    /**
+     * Identity-anchored sync-group roles registered via
+     * `defineSchema({...}, { identityRoles })`. Empty array when unset.
+     * Server's `composeIdentitySyncGroups(identity, schema)` reads this
+     * to derive a participant's allowed sync-group set.
+     */
+    readonly identityRoles: readonly IdentityRole[];
+}
+/**
+ * Infer the full model type from a schema.
+ * Includes base fields (id, createdAt, updatedAt, etc.)
+ *
+ * ```ts
+ * type Task = InferModel<typeof schema, 'tasks'>;
+ * ```
+ */
+export type InferModel<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C> ? z.infer<z.ZodObject<Shape>> & BaseModelFields & BaseModelMethods & InferComputed<C> & InferRelations<S, R> : never;
+/**
+ * Infer relation accessor types from a model's relations record.
+ *
+ * The dynamic class installs prototype getters for each declared relation in
+ * `createSyncEngine.ts` (`hasMany` → `store.getByForeignKey(...)`, `belongsTo`
+ * → pool lookup by FK). This type mirrors those installations so callers can
+ * write `slide.layers` and `slide.deck` without manual casts.
+ *
+ * - `hasMany` → `InferModel<S, Target>[]`
+ * - `belongsTo` / `hasOne` → `InferModel<S, Target> | undefined` (undefined
+ *   when the FK is unset or the parent isn't in the pool yet)
+ *
+ * Kept as `readonly` because the accessors are prototype-level getters with
+ * no setter — writing to `slide.layers = [...]` would be a no-op at runtime.
+ */
+export type InferRelations<S extends Schema, R extends RelationRecord> = string extends keyof R ? unknown : {
+    readonly [K in keyof R]: R[K] extends RelationDef<infer Type, infer Target, infer _F, infer _O> ? Target extends keyof S['models'] ? Type extends 'hasMany' ? InferModel<S, Target>[] : Type extends 'hasOne' | 'belongsTo' ? InferModel<S, Target> | undefined : never : never : never;
+};
+/**
+ * Infer the return types of computed getters.
+ * Maps each computed function's return type into a readonly property.
+ *
+ * ```ts
+ * // Given: computed: { displayTitle: (self) => self.title || 'Untitled' }
+ * // Infers: { readonly displayTitle: string }
+ * ```
+ */
+export type InferComputed<C> = string extends keyof C ? unknown : {
+    readonly [K in keyof C]: C[K] extends (...args: any[]) => infer R ? R : never;
+};
+/**
+ * Infer the create input type. Only schema-defined fields are accepted —
+ * base fields (id, createdAt, updatedAt) are auto-generated by the SDK
+ * and cannot be passed by the consumer.
+ *
+ * The only exception is `id`: consumers can optionally provide one for
+ * client-generated IDs (useful for optimistic UI that needs to reference
+ * the entity before the server confirms).
+ *
+ * ```ts
+ * type CreateTask = InferCreate<typeof schema, 'tasks'>;
+ * // { title: string; status?: 'todo' | 'doing' | 'done'; id?: string }
+ * // createdAt, updatedAt are NOT accepted — they're auto-generated
+ * ```
+ */
+export type InferCreate<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape> ? z.input<z.ZodObject<Shape>> & Partial<BaseModelFields> : never;
+/**
+ * Extract all model names from a schema.
+ */
+export type InferModelNames<S extends Schema> = keyof S['models'] & string;
+/**
+ * The value type for inserting a new row. Same shape as {@link InferCreate}:
+ * consumer-writable fields + optional `id` for client-generated IDs.
+ *
+ * Matches Zero's `InsertValue<TableSchema>` from `zql/src/mutate/crud.ts`.
+ */
+export type InsertValue<S extends Schema, ModelName extends keyof S['models']> = InferCreate<S, ModelName>;
+/**
+ * The value type for upserting (insert or overwrite). Same shape as
+ * {@link InsertValue} — a full row. If a row with the same `id` exists,
+ * it gets overwritten.
+ */
+export type UpsertValue<S extends Schema, ModelName extends keyof S['models']> = InsertValue<S, ModelName>;
+/**
+ * The value type for updating an existing row. `id` is required (identifies
+ * the row to update); all other fields are optional (only provided fields
+ * are changed).
+ *
+ * Matches Zero's `UpdateValue<TableSchema>` from `zql/src/mutate/crud.ts`.
+ */
+export type UpdateValue<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape> ? {
+    id: string;
+} & Partial<z.input<z.ZodObject<Shape>>> : never;
+/**
+ * The value type for deleting a row. Just the primary key.
+ *
+ * Matches Zero's `DeleteID<TableSchema>` from `zql/src/mutate/crud.ts`.
+ */
+export type DeleteId<S extends Schema, ModelName extends keyof S['models']> = {
+    id: string;
+};
+export declare function defineSchema<const S extends SchemaRecord>(models: S, options?: DefineSchemaOptions): Schema<S>;
+/**
+ * Compose the canonical sync-group set this identity is allowed to
+ * subscribe to, derived purely from the schema's registered
+ * {@link IdentityRole}s. Walks every role, calls its `extract` against
+ * the identity context, and substitutes each id into the role's
+ * `template`. Output is stable, deduped, and never includes a literal
+ * convention string from this function itself — the convention lives
+ * 100% in the consumer's schema declaration.
+ *
+ * Returns `[]` when the schema has no identity roles registered or
+ * when no role's extractor produces an id. Caller decides what to do
+ * with `[]`; the server's intersect-with-requested logic treats it as
+ * "no scope" rather than "match everything."
+ */
+export declare function composeIdentitySyncGroups(identity: IdentityContext, schema: Pick<Schema, 'identityRoles'>): readonly string[];
+export {};