@abloatai/transaction 0.37.0

package/src/schema/select.ts

@@ -0,0 +1,115 @@
+/**
+ * `selectModels` projects a schema down to a subset of its models.
+ *
+ * It lets one canonical schema serve several apps, each subscribing only to the
+ * models it needs. Rather than re-declare a model's fields in a second schema —
+ * which you would then have to keep identical by hand — an app selects the
+ * models it wants from the canonical schema. Field shapes, resolved foreign-key
+ * columns, computed getters, typenames, and identity roles all come from the
+ * source, so a subset cannot drift from the canonical definition.
+ *
+ * ```ts
+ * import { schema as full } from './schema';
+ * import { selectModels } from '@abloatai/transaction/schema';
+ *
+ * // Subscribe to identity and document content only.
+ * export const schema = selectModels(full, ['users', 'organizations', 'workspaces', 'folders', 'files']);
+ * ```
+ *
+ * Relations whose target falls outside the selected set are dropped, so the
+ * subset sees only its own models. Dropping a relation that carries `parent`
+ * scope-inheritance throws instead, because silently losing it would mis-route
+ * a record's fan-out — the selected set must be closed under `parent` edges.
+ */
+
+import type { Schema, SchemaRecord } from './schema.js';
+import { buildFieldRefs } from './schema.js';
+import type { ModelDef } from './model.js';
+import type { RelationDef } from './relation.js';
+import { AbloValidationError } from '../errors.js';
+import { schemaHash } from './serialize.js';
+
+export function selectModels<S extends SchemaRecord, K extends keyof S & string>(
+  schema: Schema<S>,
+  keys: readonly K[],
+): Schema<Pick<S, K>> {
+  const keep = new Set<string>(keys as readonly string[]);
+  const models: Record<string, ModelDef> = {};
+  const validators: Record<string, unknown> = {};
+
+  for (const key of keys) {
+    const def = schema.models[key];
+    if (!def) {
+      throw new AbloValidationError(
+        `selectModels: "${key}" is not a model in the source schema`,
+        { code: 'invalid_schema', param: key },
+      );
+    }
+
+    // Prune relations whose target isn't in the selected set. A pruned
+    // `parent` edge is a routing error, not a silent drop.
+    const relations: Record<string, RelationDef> = {};
+    for (const [relName, rel] of Object.entries(def.relations as Record<string, RelationDef>)) {
+      if (keep.has(rel.target)) {
+        relations[relName] = rel;
+        continue;
+      }
+      if (rel.options?.parent) {
+        throw new AbloValidationError(
+          `selectModels: model "${key}" has a parent relation "${relName}" → "${rel.target}", ` +
+            `which is not in the selected set. Include "${rel.target}" so scope inheritance still routes.`,
+          { code: 'invalid_schema', param: `${key}.${relName}` },
+        );
+      }
+    }
+
+    models[key] = { ...def, relations };
+    validators[key] = (schema.validators as Record<string, unknown>)[key];
+  }
+
+  return {
+    models: models as unknown as Pick<S, K>,
+    // References for exactly the models this projection kept.
+    fields: buildFieldRefs(models) as Schema<Pick<S, K>>['fields'],
+    validators: validators as Schema<Pick<S, K>>['validators'],
+    identityRoles: schema.identityRoles,
+    sessionSettings: schema.sessionSettings,
+    // Record the full source's hash so the drift check can recognize this subset
+    // as current against a server running that full schema. Prefer the source's
+    // OWN `sourceSchemaHash` when it is itself a projection, so a subset-of-a-
+    // subset still points at the original full schema rather than an intermediate
+    // one. `schemaHash` ignores this field, so re-projecting stays deterministic.
+    sourceSchemaHash: schema.sourceSchemaHash ?? schemaHash(schema),
+  };
+}
+
+/**
+ * `omitModels` is `selectModels` from the other side: keep every model EXCEPT
+ * the named ones. Use it when an app is the general case and a separate app
+ * owns the omitted models — the suite shell drops a specialized store that the
+ * standalone app selects for itself:
+ *
+ * ```ts
+ * export const schema = omitModels(full, ['reports', 'reportSections']);
+ * ```
+ *
+ * Same validation as `selectModels`: relations into the omitted set are
+ * dropped, and a dropped `parent` edge throws — so a model whose scope routes
+ * through an omitted parent cannot be silently kept.
+ */
+export function omitModels<S extends SchemaRecord, K extends keyof S & string>(
+  schema: Schema<S>,
+  keys: readonly K[],
+): Schema<Omit<S, K>> {
+  const drop = new Set<string>(keys as readonly string[]);
+  for (const key of keys) {
+    if (!schema.models[key]) {
+      throw new AbloValidationError(
+        `omitModels: "${key}" is not a model in the source schema`,
+        { code: 'invalid_schema', param: key },
+      );
+    }
+  }
+  const kept = Object.keys(schema.models).filter((k) => !drop.has(k));
+  return selectModels(schema, kept as (keyof S & string)[]) as Schema<Omit<S, K>>;
+}

package/src/schema/serialize.ts

@@ -0,0 +1,373 @@
+/**
+ * Schema ⇄ JSON.
+ *
+ * A `Schema` is fully serializable apart from its client-only closures — the
+ * Zod validators and computed getters. {@link serializeSchema} emits the
+ * plain-data JSON form and {@link parseSchema} reconstructs a working `Schema`
+ * from it: one `Schema` type with two representations.
+ *
+ * A hosted, multi-tenant server loads a tenant's schema with `parseSchema(json)`
+ * rather than importing it in process. The JSON is what `ablo push` sends and
+ * what the server stores per tenant and version.
+ *
+ * What round-trips:
+ *   - all model routing and scoping metadata: typename, tableName, load,
+ *     mutable, the `tenancy` descriptor, bootstrap hints, scope, grants,
+ *     entityRoles, the `conflict` disposition map, persist, autoFill,
+ *     requiredFields, and lazyObservable. The authoring shorthands (`policy`
+ *     and `groups`) are normalized into these canonical fields when the model
+ *     is built, so only the canonical fields cross here.
+ *   - relations, including the resolved `foreignKeyColumn`
+ *   - field metadata (names and type tags), from which validators are rebuilt
+ *   - identity roles
+ *
+ * What does not round-trip, because the server never needs it:
+ *   - computed getters, which are closures and are dropped
+ *   - exact Zod refinements, which are rebuilt as permissive validators from
+ *     {@link FieldMeta}; the server does no field-shape validation
+ */
+
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+import type { FieldMeta } from './field.js';
+import { buildFieldRefs } from './schema.js';
+import type { Tenancy } from './tenancy.js';
+import type { ModelResidency } from './residency.js';
+import type {
+  ModelDef,
+  RelationRecord,
+  GrantsRef,
+  LoadStrategy,
+  PersistOptions,
+  AutoFillRule,
+  ConflictAxis,
+} from './model.js';
+import {
+  relation,
+  type RelationDef,
+  type RelationType,
+} from './relation.js';
+import {
+  baseFieldsSchema,
+  type Schema,
+  type SchemaRecord,
+  type IdentityRole,
+  type EntityRole,
+  type SessionSettings,
+} from './schema.js';
+
+/** Current schema-JSON envelope version. Bump this on a breaking change to the
+ * JSON shape itself — not to a user's schema. */
+const SCHEMA_JSON_VERSION = 3 as const;
+
+// ── Wire types ──────────────────────────────────────────────────────────────
+
+/** A relation in JSON form. Mirrors the serializable members of {@link RelationDef}. */
+export interface RelationJSON {
+  readonly type: RelationType;
+  readonly target: string;
+  readonly foreignKey: string;
+  readonly foreignKeyColumn: string;
+  readonly options?: Record<string, boolean>;
+  readonly orderBy?: string;
+}
+
+/** A model in JSON form. Everything on {@link ModelDef} except closures. */
+export interface ModelJSON {
+  readonly fields: Record<string, FieldMeta>;
+  readonly relations: Record<string, RelationJSON>;
+  readonly load: LoadStrategy;
+  readonly typename: string;
+  readonly tableName?: string;
+  readonly tenancy: Tenancy;
+  /** The database plane the model's rows live in. Optional for backward
+   *  compatibility: when absent (an artifact written before this field existed)
+   *  it reads as `tenant`, the default. See {@link ModelResidency}. */
+  readonly plane?: ModelResidency;
+  readonly scope?: boolean | string;
+  readonly grants?: GrantsRef;
+  readonly entityRoles?: readonly EntityRole[];
+  /** The declared write-conflict disposition per committer kind. When absent,
+   *  the engine falls back to its default. */
+  readonly conflict?: ConflictAxis;
+  readonly bootstrapLimit?: number;
+  readonly bootstrapOrderBy?: string;
+  readonly mutable?: boolean;
+  readonly lazyObservable?: boolean;
+  readonly persist?: PersistOptions;
+  readonly autoFill?: readonly AutoFillRule[];
+  readonly requiredFields?: readonly string[];
+}
+
+/** The JSON form of a {@link Schema}. The `ablo push` payload. */
+export interface SchemaJSON {
+  readonly v: typeof SCHEMA_JSON_VERSION;
+  readonly models: Record<string, ModelJSON>;
+  readonly identityRoles: readonly IdentityRole[];
+  /** Optional so schemas pushed before ADR 0011 still parse (defaults to `{}`). */
+  readonly sessionSettings?: SessionSettings;
+}
+
+// ── Serialize ────────────────────────────────────────────────────────────────
+
+function relationToJSON(rel: RelationDef): RelationJSON {
+  const options = rel.options as Record<string, boolean> | undefined;
+  return {
+    type: rel.type,
+    target: rel.target,
+    foreignKey: rel.foreignKey,
+    foreignKeyColumn: rel.foreignKeyColumn,
+    options: options && Object.keys(options).length > 0 ? { ...options } : undefined,
+    orderBy: rel._orderBy,
+  };
+}
+
+function modelToJSON(def: ModelDef): ModelJSON {
+  const relations: Record<string, RelationJSON> = {};
+  for (const [name, rel] of Object.entries(def.relations)) {
+    relations[name] = relationToJSON(rel);
+  }
+  return {
+    fields: def.fields,
+    relations,
+    load: def.load,
+    // `defineSchema` always resolves `typename` to the schema key when unset,
+    // so it is present on a built ModelDef; fall back defensively anyway.
+    typename: def.typename ?? '',
+    tableName: def.tableName,
+    tenancy: def.tenancy,
+    plane: def.plane,
+    scope: def.scope,
+    grants: def.grants,
+    entityRoles: def.entityRoles,
+    conflict: def.conflict,
+    bootstrapLimit: def.bootstrapLimit,
+    bootstrapOrderBy: def.bootstrapOrderBy,
+    mutable: def.mutable,
+    lazyObservable: def.lazyObservable,
+    persist: def.persist,
+    autoFill: def.autoFill,
+    requiredFields: def.requiredFields,
+  };
+}
+
+/**
+ * Project a `Schema` to its JSON form. Drops the client-only closures
+ * (validators, `computed`); keeps everything the server and a faithful
+ * rebuild need. The result is plain data — `JSON.stringify`-safe.
+ */
+export function toSchemaJSON(schema: Schema): SchemaJSON {
+  const models: Record<string, ModelJSON> = {};
+  for (const [key, def] of Object.entries(schema.models)) {
+    if (def.typename === '' || def.typename === undefined) {
+      // typename '' only happens for a malformed def; surface it loudly
+      // rather than ship a model the server can't route.
+      models[key] = { ...modelToJSON(def), typename: key };
+    } else {
+      models[key] = modelToJSON(def);
+    }
+  }
+  return {
+    v: SCHEMA_JSON_VERSION,
+    models,
+    identityRoles: schema.identityRoles,
+    ...(Object.keys(schema.sessionSettings).length > 0
+      ? { sessionSettings: schema.sessionSettings }
+      : {}),
+  };
+}
+
+/** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
+export function serializeSchema(schema: Schema): string {
+  return JSON.stringify(toSchemaJSON(schema));
+}
+
+// ── Parse ──────────────────────────────────────────────────────────────────
+
+/** Rebuild a Zod validator for a field from its metadata. Permissive by
+ * design — the server does no field-shape validation; this exists so a
+ * parsed `Schema` is structurally a real `Schema`. */
+function zodForField(meta: FieldMeta): z.ZodType {
+  let base: z.ZodType;
+  switch (meta.type) {
+    case 'string':
+      base = z.string();
+      break;
+    case 'number':
+      base = z.number();
+      break;
+    case 'boolean':
+      base = z.boolean();
+      break;
+    case 'date':
+      base = z.date();
+      break;
+    case 'enum':
+      base =
+        meta.enumValues && meta.enumValues.length > 0
+          ? z.enum(meta.enumValues as [string, ...string[]])
+          : z.string();
+      break;
+    case 'json':
+    default:
+      base = z.unknown();
+      break;
+  }
+  return meta.isOptional ? base.optional() : base;
+}
+
+function relationFromJSON(rel: RelationJSON): RelationDef {
+  const setColumn = <R extends RelationDef>(definition: R): R => {
+    // The builder normally derives this from schema casing. Serialized schemas
+    // already carry the resolved database column, so restore that runtime field.
+    Reflect.set(definition, 'foreignKeyColumn', rel.foreignKeyColumn);
+    return definition;
+  };
+
+  switch (rel.type) {
+    case 'belongsTo': {
+      const options = rel.options;
+      return setColumn(relation.belongsTo(rel.target, rel.foreignKey, {
+        ...(options?.index === undefined ? {} : { index: options.index }),
+        ...(options?.enrich === undefined ? {} : { enrich: options.enrich }),
+        ...(options?.defer === undefined ? {} : { defer: options.defer }),
+        ...(options?.parent === undefined ? {} : { parent: options.parent }),
+        ...(options?.fk === undefined ? {} : { fk: options.fk }),
+      }));
+    }
+    case 'hasMany':
+      return setColumn(
+        relation.hasMany(
+          rel.target,
+          rel.foreignKey,
+          rel.orderBy === undefined ? undefined : { orderBy: rel.orderBy },
+        ),
+      );
+    case 'hasOne':
+      return setColumn(relation.hasOne(rel.target, rel.foreignKey));
+  }
+}
+
+function modelFromJSON(json: ModelJSON): ModelDef {
+  // `z.ZodRawShape` is a readonly index signature in Zod v4, so build a
+  // mutable record and cast once when handing it to `z.object`/`ModelDef`.
+  const shapeMut: Record<string, z.ZodType> = {};
+  for (const [name, meta] of Object.entries(json.fields)) {
+    shapeMut[name] = zodForField(meta);
+  }
+  const shape = shapeMut as z.ZodRawShape;
+  const relations: RelationRecord = {};
+  for (const [name, rel] of Object.entries(json.relations)) {
+    relations[name] = relationFromJSON(rel);
+  }
+  return {
+    schema: z.object(shape),
+    shape,
+    fields: json.fields,
+    relations,
+    load: json.load,
+    bootstrapLimit: json.bootstrapLimit,
+    bootstrapOrderBy: json.bootstrapOrderBy,
+    typename: json.typename,
+    persist: json.persist,
+    tableName: json.tableName,
+    tenancy: json.tenancy,
+    // Absent in older artifacts → default `tenant`, matching the model builder
+    // and provisioning defaults so the round-trip stays stable.
+    plane: json.plane ?? 'tenant',
+    scope: json.scope,
+    grants: json.grants,
+    entityRoles: json.entityRoles,
+    // Absent in older artifacts → undefined, so the commit path falls through to
+    // the function registry or the engine default.
+    conflict: json.conflict,
+    mutable: json.mutable,
+    lazyObservable: json.lazyObservable,
+    // computed getters are closures and intentionally not serialized; a
+    // parsed schema (server-side) has none.
+    computed: undefined,
+    autoFill: json.autoFill,
+    requiredFields: json.requiredFields,
+  };
+}
+
+/**
+ * Reconstruct a working `Schema` from its JSON form. Validators are rebuilt
+ * permissively from field metadata (the server never validates field shapes);
+ * `computed` getters are absent. Everything the server reads — routing,
+ * scoping, relations, identity roles — is restored exactly.
+ */
+export function fromSchemaJSON(json: SchemaJSON): Schema {
+  const models: Record<string, ModelDef> = {};
+  const validators: Record<string, z.ZodObject<z.ZodRawShape>> = {};
+  for (const [key, modelJson] of Object.entries(json.models)) {
+    const def = modelFromJSON(modelJson);
+    models[key] = def;
+    validators[key] = baseFieldsSchema.merge(def.schema);
+  }
+  return {
+    models: models,
+    // A schema rebuilt from JSON carries references too — the shapes are here.
+    fields: buildFieldRefs(models),
+    validators: validators as Schema['validators'],
+    identityRoles: json.identityRoles,
+    sessionSettings: json.sessionSettings ?? {},
+  };
+}
+
+/** Parse a `Schema` from a JSON string (inverse of {@link serializeSchema}). */
+export function parseSchema(json: string): Schema {
+  const parsed = JSON.parse(json) as SchemaJSON;
+  if (parsed.v !== SCHEMA_JSON_VERSION) {
+    throw new AbloValidationError(
+      `parseSchema: unsupported schema-JSON version ${parsed.v} (expected ${SCHEMA_JSON_VERSION})`,
+      { code: 'schema_definition_invalid' },
+    );
+  }
+  return fromSchemaJSON(parsed);
+}
+
+// ── Hash ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Stable content hash of a `Schema`'s JSON form. FNV-1a over a canonical
+ * (sorted-key) encoding — deterministic across runs and order-invariant, no
+ * `crypto` dependency. Used for connect-time version gating: the client sends
+ * the hash it was built against, the server compares it to the tenant's
+ * active schema hash. Not a security primitive.
+ */
+export function schemaHash(schema: Schema): string {
+  return fnv1a(canonicalJson(toSchemaJSON(schema)));
+}
+
+/**
+ * Content hash of ONE serialized model — the unit of the semantic drift check.
+ * Two schemas agree on a model exactly when these match, which is what lets a
+ * client compare only the models it declares instead of welding itself to the
+ * whole-schema hash (where any additive push reads as drift). Computed over the
+ * model's `SchemaJSON` entry with the same canonicalization and hash as
+ * {@link schemaHash}, on both the client and the server's `GET /api/schema`.
+ */
+export function modelHash(modelJson: unknown): string {
+  return fnv1a(canonicalJson(modelJson));
+}
+
+/** FNV-1a over an already-canonical string — shared by both hashes above. */
+function fnv1a(canonical: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < canonical.length; i++) {
+    h ^= canonical.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+/** Stable JSON: object keys sorted recursively, `undefined` dropped. */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}

package/src/schema/sugar.ts

@@ -0,0 +1,194 @@
+/**
+ * A concise, claim-first way to declare a model. Each verb is shorthand for a
+ * {@link model} call with two decisions already made, so a reader learns the two
+ * facts that matter most about an entity before scanning its fields:
+ *
+ *   - Writability: `mutable.*` lets clients send create, update, and delete
+ *     operations over the commit protocol. `readOnly.*` means the server owns the
+ *     model — its changes stream to clients as deltas, but clients cannot mutate it.
+ *   - Load strategy: `.instant` loads the model at bootstrap, `.lazy` loads it on
+ *     first access, and `.manual` loads it only when you query it explicitly.
+ *
+ * The two-token form (`mutable.lazy({...})`) states the safety claim in the first
+ * token and the load shape in the second. The plain {@link model} factory remains
+ * available; these verbs are a convenience layered over it.
+ *
+ * @example
+ * ```ts
+ * tasks: mutable.lazy({ title: z.string() }, {
+ *   typename: 'Task', tableName: 'tasks',
+ *   relations: { ... },
+ *   computed: tasksComputed,
+ * }),
+ * ```
+ */
+
+import type { z } from 'zod';
+import {
+  model,
+  type ModelDef,
+  type ModelOptions,
+  type ComputedRecord,
+  type RelationRecord,
+} from './model.js';
+
+/**
+ * Options accepted by every sugar verb. A strict subset of
+ * {@link ModelOptions} — anything the verb infers (`mutable`, `load`,
+ * `lazyObservable`) is deliberately absent so the call site can't
+ * contradict its verb.
+ */
+export interface SugarOptions<
+  R extends RelationRecord = RelationRecord,
+  C extends ComputedRecord = ComputedRecord,
+> {
+  /** Relations to other models. Same shape as `model()`'s second arg. */
+  relations?: R;
+  /** Computed getters installed on the model class prototype. */
+  computed?: C;
+  /**
+   * Wire `__typename` (PascalCase, e.g. `'Task'`). Defaults to the schema
+   * key via `defineSchema` — override when the wire shape differs from
+   * the camelCase schema key.
+   */
+  typename?: string;
+  /**
+   * The physical table name. Override it when the table name differs from the
+   * snake_case of the typename — for example, a `Member` type stored in a table
+   * named `'member'` rather than `'members'`.
+   */
+  tableName?: string;
+  /**
+   * The row-access policy for tenant isolation — the rule deciding who may read a
+   * row. A discriminated union on `by` (`column`, `parent`, or `none`). See
+   * {@link ModelOptions.policy}.
+   */
+  policy?: ModelOptions['policy'];
+  /**
+   * Sync-group routing — which delta *channels* a row fans into
+   * (`root` / `grants` / `roles`). See {@link ModelOptions.groups}.
+   */
+  groups?: ModelOptions['groups'];
+  /** Max rows loaded during bootstrap. Only applies to `.instant`. */
+  bootstrapLimit?: number;
+  /** Bootstrap sort order (e.g. `'created_at DESC'`). */
+  bootstrapOrderBy?: string;
+  /** IndexedDB persistence hints — see {@link ModelOptions.persist}. */
+  persist?: ModelOptions['persist'];
+  /**
+   * Defer MobX observability to first access. Override the verb's
+   * default when a `.lazy` model is small enough that eager MobX setup
+   * is fine, or a `.instant` model is hot enough to justify deferral.
+   */
+  lazyObservable?: boolean;
+}
+
+/** Internal helper — builds a ModelDef with baseline safety+load flags applied. */
+function build<
+  Shape extends z.ZodRawShape,
+  R extends RelationRecord,
+  C extends ComputedRecord,
+>(
+  shape: Shape,
+  opts: SugarOptions<R, C> | undefined,
+  baseline: Pick<ModelOptions, 'mutable' | 'load' | 'lazyObservable'>,
+): ModelDef<Shape, R, C> {
+  return model(shape, { relations: (opts?.relations ?? {}) as R, mutable: baseline.mutable,
+    load: baseline.load,
+    lazyObservable: opts?.lazyObservable ?? baseline.lazyObservable,
+    typename: opts?.typename,
+    tableName: opts?.tableName,
+    policy: opts?.policy,
+    groups: opts?.groups,
+    bootstrapLimit: opts?.bootstrapLimit,
+    bootstrapOrderBy: opts?.bootstrapOrderBy,
+    persist: opts?.persist,
+    computed: opts?.computed, });
+}
+
+/**
+ * Client-writable entities. `mutable.*` is the opt-in signal for wire
+ * mutations via `commit` — equivalent to setting
+ * `{ mutable: true, load: X }` on `model()`.
+ *
+ * Pick the load suffix by data-access pattern:
+ *   - `.instant`  — small, always-needed (Theme, Layout, StatusGroup)
+ *   - `.lazy`     — large collections fetched on first query
+ *     (Block, Message, Task)
+ */
+export const mutable = {
+  instant: <
+    Shape extends z.ZodRawShape,
+    R extends RelationRecord = Record<string, never>,
+    C extends ComputedRecord = Record<string, never>,
+  >(
+    shape: Shape,
+    opts?: SugarOptions<R, C>,
+  ): ModelDef<Shape, R, C> =>
+    // Reactive by default (see readonly.instant note): opt out with
+    // `lazyObservable: false` only for very large read-only list models.
+    build(shape, opts, { mutable: true, load: 'instant', lazyObservable: true }),
+
+  lazy: <
+    Shape extends z.ZodRawShape,
+    R extends RelationRecord = Record<string, never>,
+    C extends ComputedRecord = Record<string, never>,
+  >(
+    shape: Shape,
+    opts?: SugarOptions<R, C>,
+  ): ModelDef<Shape, R, C> =>
+    build(shape, opts, { mutable: true, load: 'lazy', lazyObservable: true }),
+};
+
+/**
+ * Server-managed entities. `readOnly.*` means clients subscribe to
+ * deltas but cannot emit mutations — any `commit` op for this model
+ * is rejected at the server with "Unknown model."
+ *
+ * Use for:
+ *   - Server-written state: `sync_deltas`, `presence`, version vectors
+ *   - Ingestion pipelines: digest entries, filing jobs
+ *   - Audit surfaces: anything where clients watch but only the server
+ *     writes
+ */
+export const readOnly = {
+  instant: <
+    Shape extends z.ZodRawShape,
+    R extends RelationRecord = Record<string, never>,
+    C extends ComputedRecord = Record<string, never>,
+  >(
+    shape: Shape,
+    opts?: SugarOptions<R, C>,
+  ): ModelDef<Shape, R, C> =>
+    // Reactive by default, like every variant: a remote delta that mutates a row
+    // in place must re-render reactive reads. Opt out per-model with
+    // `lazyObservable: false` for very large read-only lists where per-field
+    // atoms cost more than the QueryView's entry-replaced reactivity.
+    build(shape, opts, { mutable: false, load: 'instant', lazyObservable: true }),
+
+  lazy: <
+    Shape extends z.ZodRawShape,
+    R extends RelationRecord = Record<string, never>,
+    C extends ComputedRecord = Record<string, never>,
+  >(
+    shape: Shape,
+    opts?: SugarOptions<R, C>,
+  ): ModelDef<Shape, R, C> =>
+    build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
+
+  /**
+   * Internal-only: kept out of bootstrap and never written by clients. The
+   * strongest safety posture — use for tables the SDK must know about (for type
+   * inference) but that no client should be able to write. Rows still reach a
+   * client that reads the model, so this is a write boundary, not a read one.
+   */
+  internal: <
+    Shape extends z.ZodRawShape,
+    R extends RelationRecord = Record<string, never>,
+    C extends ComputedRecord = Record<string, never>,
+  >(
+    shape: Shape,
+    opts?: SugarOptions<R, C>,
+  ): ModelDef<Shape, R, C> =>
+    build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
+};