@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/resources/where.js

@@ -0,0 +1,115 @@
+/**
+ * The where-clause grammar carried by a filtered read.
+ *
+ * A `where` is a flat list of `[column, operator, value]` conditions combined
+ * with AND. The protocol carries no model-specific logic: the server compiles a
+ * condition against your schema, so adding a model or relation is a schema
+ * change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every block whose `sectionId` falls in a set of ids.
+ *
+ * These types describe the *request*, not any local copy of the rows it returns,
+ * so they live with the settlement core rather than the reactive consumer.
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+/**
+ * The comparison operators a {@link WhereClause} may use: equality and
+ * inequality, ordering, set membership (`IN` / `NOT IN`), null checks
+ * (`IS` / `IS NOT`), and case-sensitive or case-insensitive pattern
+ * matching (`LIKE`, `ILIKE`, and their negations).
+ */
+export const whereOpSchema = z.enum([
+    '=',
+    '!=',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'IN',
+    'NOT IN',
+    'IS',
+    'IS NOT',
+    'LIKE',
+    'NOT LIKE',
+    'ILIKE',
+    'NOT ILIKE',
+]);
+/**
+ * How each operator binds its operand — the classification a compiler needs
+ * before it can render or evaluate a condition: a scalar on the right, an array
+ * to expand, or a null check with no operand at all. `LIKE_OPS` is the subset
+ * whose operand is a pattern and therefore needs pattern validation.
+ *
+ * These live here, beside the operators, because every consumer of the grammar
+ * needs the same split and there is more than one consumer: a where clause is
+ * compiled to SQL on a hosted plane and evaluated in memory against the log on
+ * a source plane. Two hand-maintained copies of this split meant the same
+ * request could be accepted by one plane and rejected by the other — and the
+ * pattern-safety set existed on only one of them.
+ */
+export const WHERE_SCALAR_OPS = new Set([
+    '=',
+    '!=',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'LIKE',
+    'NOT LIKE',
+    'ILIKE',
+    'NOT ILIKE',
+]);
+export const WHERE_ARRAY_OPS = new Set(['IN', 'NOT IN']);
+export const WHERE_NULL_OPS = new Set(['IS', 'IS NOT']);
+export const WHERE_LIKE_OPS = new Set([
+    'LIKE',
+    'NOT LIKE',
+    'ILIKE',
+    'NOT ILIKE',
+]);
+/**
+ * Does this operator accept this operand? The rule the sets above imply, stated
+ * once and thrown once.
+ *
+ * The sets were collapsed here because two copies of the split let one plane
+ * accept a request the other refused. The check that consumes them stayed
+ * duplicated — the SQL compiler and the log-plane evaluator each carried their
+ * own arity tests and their own wording — which leaves the same gap one step
+ * further along: relax `IN` in one evaluator and a request succeeds against a
+ * hosted plane and fails against a connected one, with no test in a position to
+ * notice.
+ *
+ * Returns the classification the caller needs next, so the check and the branch
+ * are the same statement rather than two that can disagree.
+ */
+export function classifyWhereOperand(op, value) {
+    if (WHERE_NULL_OPS.has(op)) {
+        if (value !== null) {
+            throw new AbloValidationError(`${op} only supports null RHS`, {
+                code: 'query_unsupported_operator',
+            });
+        }
+        return 'null';
+    }
+    if (WHERE_ARRAY_OPS.has(op)) {
+        if (!Array.isArray(value)) {
+            throw new AbloValidationError(`${op} requires an array RHS`, {
+                code: 'query_unsupported_operator',
+            });
+        }
+        return 'array';
+    }
+    if (WHERE_SCALAR_OPS.has(op)) {
+        if (Array.isArray(value)) {
+            throw new AbloValidationError(`${op} requires a scalar RHS`, {
+                code: 'query_unsupported_operator',
+            });
+        }
+        return 'scalar';
+    }
+    throw new AbloValidationError(`unsupported operator: ${op}`, {
+        code: 'query_unsupported_operator',
+    });
+}

package/dist/{client → transaction/resources}/writeOptionsSchema.d.ts

@@ -16,11 +16,8 @@
  * asserts the shape rather than replacing the value with a parsed copy.
  */
 import { z } from 'zod';
-export declare const onStaleModeSchema: z.ZodEnum<{
-    reject: "reject";
-    overwrite: "overwrite";
-    notify: "notify";
-}>;
+import { onStaleModeSchema } from '../coordination/schema.js';
+export { onStaleModeSchema };
 export declare const writeOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     label: z.ZodOptional<z.ZodString>;
@@ -38,7 +35,6 @@ export declare const writeOptionsSchema: z.ZodObject<{
     claim: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         id: z.ZodString;
     }, z.core.$loose>]>>>;
-    causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
 /**

package/dist/{client → transaction/resources}/writeOptionsSchema.js

@@ -17,8 +17,14 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
-import { commitStatusSchema } from '../wire/commit.js';
-export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
+import { commitWaitSchema } from '../wire/commit.js';
+import { onStaleModeSchema } from '../coordination/schema.js';
+// Re-exported, not redeclared. `coordination/schema.ts` owns this enum — it is
+// what the wire schemas and the server validate against — while the published
+// SDK barrel exports the name from this module. Declaring it twice put a second
+// object behind the public export that agreed with the canonical one only by
+// both happening to list the same three strings.
+export { onStaleModeSchema };
 export const writeOptionsSchema = z.object({
     /** Idempotency key the server records in `mutation_log` to make retries
      *  safe; `null` opts out of that protection. */
@@ -26,7 +32,7 @@ export const writeOptionsSchema = z.object({
     /** Human-readable audit tag, persisted to `mutation_log.label`. */
     label: z.string().max(255).optional(),
     /** Resolve when queued locally (default) or once the server confirms. */
-    wait: commitStatusSchema.optional(),
+    wait: commitWaitSchema.optional(),
     /** Stale guard: the sync watermark the caller's reasoning was based on. */
     readAt: z.number().int().nonnegative().nullish(),
     /** What the server does when the target moved past `readAt`. */
@@ -39,8 +45,6 @@ export const writeOptionsSchema = z.object({
     /** The claim this write belongs to — either a claim id, or a live claim
      *  handle whose `release`/`revoke` functions are preserved untouched. */
     claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
-    /** Reserved wire-compatibility field; current clients always send `null`. */
-    causedByTaskId: z.string().nullish(),
 });
 /**
  * Validates a write-options object against {@link writeOptionsSchema}. On

package/dist/{schema → transaction/schema}/field.d.ts

@@ -24,24 +24,18 @@
  *   });
  */
 import { z } from 'zod';
-/** The sync-engine metadata describing one field, available at runtime through a
- *  model's `fields` map. The {@link field} builders attach it, and the migration
- *  planner, type generator, and OpenAPI generator all read it. */
-export interface FieldMeta {
-    /** Sync-engine type tag, which maps to storage and serialization hints. */
-    type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'json';
-    /** Whether the field was marked optional via `.optional()` or `.nullable()`. */
-    isOptional: boolean;
-    /** Whether the field was marked indexed via `.indexed()`. */
-    isIndexed: boolean;
-    /**
-     * Physical database column name override. When absent, SQL layers derive
-     * the column from the field name using the active casing convention.
-     */
-    column?: string;
-    /** For enums: the allowed values. */
-    enumValues?: readonly string[];
-}
+/**
+ * The sync-engine metadata describing one field, available at runtime through a
+ * model's `fields` map. The {@link field} builders attach it, and the migration
+ * planner, type generator, and OpenAPI generator all read it.
+ *
+ * Declared in `wire/modelShape.ts` and inferred here, not restated: this record
+ * crosses the wire twice — serialized into the pushed artifact, and reported
+ * back by `GET /api/schema` — so a second declaration would be a copy that
+ * drifts in whichever direction nobody is looking.
+ */
+export type { FieldMeta } from '../wire/modelShape.js';
+import type { FieldMeta } from '../wire/modelShape.js';
 /**
  * Extract FieldMeta from a Zod schema. Returns null if no sync-engine
  * metadata is attached (e.g., raw `z.string()` usage).
@@ -103,18 +97,18 @@ export declare const field: {
      *
      * Example:
      * ```ts
-     * const slideDecks = model({
+     * const reports = model({
      *   metadata: field.json({
-     *     icon: z.string().default('presentation'),
+     *     icon: z.string().default('report'),
      *     color: z.string().default('#F59E0B'),
      *     summary: z.string().optional(),
      *   }),
      * });
      *
      * // At runtime:
-     * deck.metadata       // raw JSON string (unchanged)
-     * deck.metadataJson   // { icon: 'presentation', color: '#F59E0B', summary: undefined }
-     * deck.metadataJson.icon  // 'presentation' (typed, with default)
+     * report.metadata       // raw JSON string (unchanged)
+     * report.metadataJson   // { icon: 'report', color: '#F59E0B', summary: undefined }
+     * report.metadataJson.icon  // 'report' (typed, with default)
      * ```
      */
     readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => FieldBuilder<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;

package/dist/{schema → transaction/schema}/field.js

@@ -219,18 +219,18 @@ export const field = {
      *
      * Example:
      * ```ts
-     * const slideDecks = model({
+     * const reports = model({
      *   metadata: field.json({
-     *     icon: z.string().default('presentation'),
+     *     icon: z.string().default('report'),
      *     color: z.string().default('#F59E0B'),
      *     summary: z.string().optional(),
      *   }),
      * });
      *
      * // At runtime:
-     * deck.metadata       // raw JSON string (unchanged)
-     * deck.metadataJson   // { icon: 'presentation', color: '#F59E0B', summary: undefined }
-     * deck.metadataJson.icon  // 'presentation' (typed, with default)
+     * report.metadata       // raw JSON string (unchanged)
+     * report.metadataJson   // { icon: 'report', color: '#F59E0B', summary: undefined }
+     * report.metadataJson.icon  // 'report' (typed, with default)
      * ```
      */
     json(schemaOrShape) {

package/dist/transaction/schema/fieldRef.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A reference to one field of one model — the field as a value rather than as
+ * a quoted name.
+ *
+ * A model is declared as Zod schemas keyed by name, so a field's name lives on
+ * the object key and never on the value: `model({ status: z.enum([...]) })`
+ * gives you nothing to point at, and every surface that needs to name a field
+ * has had to quote it. `fields: ['titel']` then compiles, is granted, excludes
+ * nobody, and leaves the write of `title` unguarded — the conflict rule
+ * compares names as opaque strings, so an invented one matches no other claim
+ * and nothing reports it.
+ *
+ * {@link Schema.fields} carries one of these per field, stamped from the key
+ * `defineSchema` is already holding. Referencing a field that does not exist
+ * stops compiling, and renaming one is a compile error at every use rather than
+ * a claim that quietly stops matching.
+ *
+ * An object rather than a branded string, for the reason `ClaimPart` is one: a
+ * brand makes a concrete schema's claim params mutually unassignable with the
+ * erased `SchemaRecord` view, and the react context boundary erases and
+ * restores exactly that way. Objects stay pairwise comparable across it, which
+ * a union of literal keys does not — function parameters are contravariant, so
+ * a claim accepting `'title' | 'status'` is not assignable to one accepting
+ * `string`.
+ *
+ * `model` rides along so a reference carries where it came from. Claiming
+ * `users.email` through `ablo.tasks` is a mistake nothing can currently see.
+ */
+export interface FieldRef {
+    /** The schema key of the model this field belongs to. */
+    readonly model: string;
+    /** The field's own name — the key it was declared under. */
+    readonly field: string;
+}
+/** Whether a value is a {@link FieldRef}. */
+export declare function isFieldRef(value: unknown): value is FieldRef;
+/** Build the reference for one declared field. */
+export declare function fieldRef(model: string, field: string): FieldRef;

package/dist/transaction/schema/fieldRef.js

@@ -0,0 +1,11 @@
+/** Whether a value is a {@link FieldRef}. */
+export function isFieldRef(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.field === 'string' &&
+        typeof value.model === 'string');
+}
+/** Build the reference for one declared field. */
+export function fieldRef(model, field) {
+    return { model, field };
+}

package/dist/transaction/schema/loadStrategy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * When a model's rows are loaded from the server.
+ *
+ *   - `instant` — loaded during bootstrap, before the model is first used.
+ *   - `lazy`    — loaded all at once on first access.
+ *
+ * One declaration serves both sides of the seam. `LoadStrategy.instant` is the
+ * value the engine branches on once a model is registered; `'instant'` is the
+ * word an author writes in `model(…, { load })`. They are the same name because
+ * they are the same axis — a const object merged with the type of its own
+ * values, rather than an enum, because a string enum is nominal and would
+ * refuse the plain `'instant'` an author actually types.
+ *
+ * The set is deliberately this small. It previously named `partial`,
+ * `explicitlyRequested`, and `local` on the runtime side and `manual` on the
+ * authoring side, and not one of those was reachable end to end: `manual` had
+ * no implementation and resolved to `lazy`, while the other three had no way to
+ * be declared. A member no schema can produce, or no branch can observe, is a
+ * promise the engine has no way to keep.
+ */
+export declare const LoadStrategy: {
+    /** Loaded during startup, before it is first used — for models needed right away. */
+    readonly instant: "instant";
+    /** Loaded all at once the first time it is needed — for secondary models. */
+    readonly lazy: "lazy";
+};
+export type LoadStrategy = (typeof LoadStrategy)[keyof typeof LoadStrategy];
+/** The strategy a model gets when it declares none. */
+export declare const DEFAULT_LOAD_STRATEGY: LoadStrategy;
+/**
+ * Whether a model's rows arrive in the bootstrap payload rather than on first
+ * access. This is the question the client asks when it builds the bootstrap
+ * subscription and the question the server asks when it assembles the payload,
+ * and the two must answer it identically or a model is requested by one side
+ * and withheld by the other.
+ *
+ * It is a function rather than a comparison spelled at each site because the
+ * sites disagreed about how to spell it: one asked `load !== 'lazy'`, another
+ * `load === 'instant'`, a third `load === 'lazy' ? … : …`. Against a two-member
+ * set those are the same predicate, so nothing failed. Against a third member
+ * they are three different predicates, and the first would have enrolled it in
+ * bootstrap while the second withheld it — the kind of split that surfaces as
+ * rows that never arrive, far from the line that caused it.
+ */
+export declare function loadsAtBootstrap(load: LoadStrategy | undefined): boolean;

package/dist/transaction/schema/loadStrategy.js

@@ -0,0 +1,46 @@
+/**
+ * When a model's rows are loaded from the server.
+ *
+ *   - `instant` — loaded during bootstrap, before the model is first used.
+ *   - `lazy`    — loaded all at once on first access.
+ *
+ * One declaration serves both sides of the seam. `LoadStrategy.instant` is the
+ * value the engine branches on once a model is registered; `'instant'` is the
+ * word an author writes in `model(…, { load })`. They are the same name because
+ * they are the same axis — a const object merged with the type of its own
+ * values, rather than an enum, because a string enum is nominal and would
+ * refuse the plain `'instant'` an author actually types.
+ *
+ * The set is deliberately this small. It previously named `partial`,
+ * `explicitlyRequested`, and `local` on the runtime side and `manual` on the
+ * authoring side, and not one of those was reachable end to end: `manual` had
+ * no implementation and resolved to `lazy`, while the other three had no way to
+ * be declared. A member no schema can produce, or no branch can observe, is a
+ * promise the engine has no way to keep.
+ */
+export const LoadStrategy = {
+    /** Loaded during startup, before it is first used — for models needed right away. */
+    instant: 'instant',
+    /** Loaded all at once the first time it is needed — for secondary models. */
+    lazy: 'lazy',
+};
+/** The strategy a model gets when it declares none. */
+export const DEFAULT_LOAD_STRATEGY = LoadStrategy.instant;
+/**
+ * Whether a model's rows arrive in the bootstrap payload rather than on first
+ * access. This is the question the client asks when it builds the bootstrap
+ * subscription and the question the server asks when it assembles the payload,
+ * and the two must answer it identically or a model is requested by one side
+ * and withheld by the other.
+ *
+ * It is a function rather than a comparison spelled at each site because the
+ * sites disagreed about how to spell it: one asked `load !== 'lazy'`, another
+ * `load === 'instant'`, a third `load === 'lazy' ? … : …`. Against a two-member
+ * set those are the same predicate, so nothing failed. Against a third member
+ * they are three different predicates, and the first would have enrolled it in
+ * bootstrap while the second withheld it — the kind of split that surfaces as
+ * rows that never arrive, far from the line that caused it.
+ */
+export function loadsAtBootstrap(load) {
+    return (load ?? DEFAULT_LOAD_STRATEGY) === LoadStrategy.instant;
+}

package/dist/{schema → transaction/schema}/model.d.ts

@@ -1,7 +1,8 @@
 /**
- * Defines a model — one table's worth of fields plus its relations and options. A
- * model is a Zod object schema paired with optional relation definitions; the row
- * type is inferred directly from Zod, with no separate type system to keep in sync.
+ * Defines a model — one table's worth of fields, and one options object holding
+ * everything else the engine needs to know about it. A model is a Zod object schema
+ * paired with those options; the row type is inferred directly from Zod, with no
+ * separate type system to keep in sync.
  *
  * Usage:
  *   import { z } from 'zod';
@@ -12,7 +13,8 @@
  *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *     projectId: z.string().optional(),
  *   }, {
- *     project: relation.belongsTo('projects', 'projectId'),
+ *     relations: { project: relation.belongsTo('projects', 'projectId') },
+ *     load: 'lazy',
  *   });
  */
 import { z } from 'zod';
@@ -24,14 +26,8 @@ export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
 import { type ModelResidency } from './residency.js';
 import type { ConflictAxis } from '../policy/types.js';
 export type { ConflictAxis } from '../policy/types.js';
-/**
- * Controls when model data is loaded from the server.
- *
- * - `'instant'` — loaded during bootstrap (appears immediately on page load)
- * - `'lazy'`    — loaded on first access (e.g., when you navigate to a page that needs it)
- * - `'manual'`  — only loaded when you explicitly call sync.model.load()
- */
-export type LoadStrategy = 'instant' | 'lazy' | 'manual';
+import { LoadStrategy } from './loadStrategy.js';
+export { LoadStrategy, DEFAULT_LOAD_STRATEGY, loadsAtBootstrap } from './loadStrategy.js';
 /** A record of relation definitions */
 export type RelationRecord = Record<string, RelationDef>;
 /**
@@ -58,11 +54,26 @@ export interface PersistOptions {
 export interface GrantsRef {
     /** Relation name pointing at the identity that gains access (e.g. `'user'`). */
     subject: string;
-    /** Relation name pointing at the scope-root entity (e.g. `'dataroom'`). */
+    /** Relation name pointing at the scope-root entity (e.g. `'workspace'`). */
     scope: string;
 }
 /** Options for model() */
 export interface ModelOptions {
+    /**
+     * Edges from this model to others, keyed by the accessor name they create. The
+     * engine reads them to index foreign keys, to order inserts so a parent row lands
+     * before the rows referencing it, and to generate the accessors that let you read
+     * `task.project` or `project.tasks` directly. Built with the {@link relation}
+     * factories.
+     *
+     * ```ts
+     * relations: {
+     *   project: relation.belongsTo('projects', 'projectId'),
+     *   comments: relation.hasMany('comments', 'taskId'),
+     * }
+     * ```
+     */
+    relations?: RelationRecord;
     /** When to load this model's data. Default: 'instant' */
     load?: LoadStrategy;
     /** Max records to bootstrap. Default: unlimited. Only applies to 'instant' strategy. */
@@ -74,7 +85,7 @@ export interface ModelOptions {
      * wire (the `__typename`). The loader stamps it onto incoming rows and uses it to
      * find the matching model class. It defaults to the schema key (`tasks` →
      * `'tasks'`); set it explicitly when the wire shape uses different casing, such as
-     * schema key `slideLayer` mapping to typename `'SlideLayer'`.
+     * schema key `block` mapping to typename `'Block'`.
      *
      * This is the one value that identifies the model on the wire; the client-side
      * store name, query result references, and delta routing all resolve through it.
@@ -98,8 +109,8 @@ export interface ModelOptions {
      *   omitted). `column` overrides the column name, which defaults to
      *   `organization_id`.
      * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when the
-     *   table has no tenancy column of its own (for example `slide_layers` → slide →
-     *   deck → organization). In place of `organization_id = $1` the read emits
+     *   table has no tenancy column of its own (for example `blocks` → section →
+     *   report → organization). In place of `organization_id = $1` the read emits
      *   `WHERE <table>.<fk> IN (SELECT <parentKey> FROM <parent> WHERE
      *   <parentTenantColumn> = $1)`. Use it for any `load: 'instant'` child table that
      *   would otherwise expose other tenants' rows at bootstrap.
@@ -125,8 +136,8 @@ export interface ModelOptions {
      * optional parts:
      *
      * - `root` — marks this model a scope root, so each of its records forms the group
-     *   `<kind>:<id>`. The kind defaults to the lowercased typename (`Deck` →
-     *   `deck:<id>`); pass a string to override it (`root: 'matter'`). Child models
+     *   `<kind>:<id>`. The kind defaults to the lowercased typename (`Report` →
+     *   `report:<id>`); pass a string to override it (`root: 'matter'`). Child models
      *   inherit a root's group through their `belongsTo` relations.
      * - `grants` — a membership edge that grants an identity access to a scope root.
      *   Both values name `belongsTo` relations on this model (`subject` names the
@@ -138,7 +149,7 @@ export interface ModelOptions {
      *
      * ```ts
      * // dataroomMember: { userId, dataroomId }
-     * groups: { grants: { subject: 'user', scope: 'dataroom' } }
+     * groups: { grants: { subject: 'user', scope: 'workspace' } }
      * // a message → its addressee's inbox, keyed on `toId`
      * groups: { roles: [entityRole({ kind: 'inbox', source: 'toId' })] }
      * ```
@@ -196,7 +207,7 @@ export interface ModelOptions {
      * value.
      *
      * @example
-     * model({ title: z.string(), metadata: z.string() }, {}, {
+     * model({ title: z.string(), metadata: z.string() }, {
      *   computed: {
      *     displayTitle: (self) => self.title || `Untitled`,
      *     metadataObject: (self) => {
@@ -233,7 +244,7 @@ export interface ModelOptions {
      * loaded. Use it for foreign keys whose absence would crash code that depends on
      * them — for example a child row that cannot be placed without its parent's id.
      *
-     * @example requiredFields: ['slideId']
+     * @example requiredFields: ['sectionId']
      */
     requiredFields?: readonly string[];
 }
@@ -321,40 +332,44 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
     readonly requiredFields?: readonly string[];
 }
 /**
- * Defines a model from a Zod shape, with optional relations and options. The row
- * type is inferred from the shape; fields built with the {@link field} builders
- * carry extra metadata, while plain Zod fields get metadata inferred from their Zod
- * type. The third argument sets options such as the {@link LoadStrategy}.
+ * Defines a model from a Zod shape and its options. The row type is inferred from
+ * the shape; fields built with the {@link field} builders carry extra metadata,
+ * while plain Zod fields get metadata inferred from their Zod type. Everything else
+ * about the model — its {@link ModelOptions.relations}, its {@link LoadStrategy},
+ * the table it maps to — lives in the second argument, so a model that needs one
+ * setting never has to name the settings it does not use.
  *
  * ```ts
  * import { z } from 'zod';
  * import { model, relation } from '@abloatai/ablo/schema';
  *
- * // Loaded at bootstrap (the default)
+ * // Fields alone
+ * const tags = model({ label: z.string() });
+ *
+ * // Loaded at bootstrap (the default), with an edge to its project
  * const tasks = model({
  *   title: z.string(),
  *   status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *   projectId: z.string().optional(),
  * }, {
- *   project: relation.belongsTo('projects', 'projectId'),
+ *   relations: { project: relation.belongsTo('projects', 'projectId') },
  * });
  *
  * // Loaded on first access
- * const slideLayers = model({ slideId: z.string(), type: z.string() }, {
- *   slide: relation.belongsTo('slides', 'slideId'),
- * }, { load: 'lazy' });
- *
- * // Loaded only when explicitly requested
- * const auditLogs = model({ action: z.string() }, {}, { load: 'manual' });
+ * const blocks = model({ sectionId: z.string(), type: z.string() }, {
+ *   relations: { section: relation.belongsTo('sections', 'sectionId') },
+ *   load: 'lazy',
+ * });
  * ```
  */
-export declare function model<Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, relations?: R, options?: ModelOptions & {
+export declare function model<Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, options?: ModelOptions & {
+    relations?: R;
     computed?: C;
 }): ModelDef<Shape, R, C>;
 /**
  * Returns the sync-group kind a scope-root model produces, or `undefined` when the
  * model is not a scope root. `scope: true` derives the kind from the lowercased
- * typename (`SlideDeck` → `slidedeck`); `scope: 'deck'` sets it explicitly, which
+ * typename (`ReportSection` → `reportsection`); `scope: 'section'` sets it explicitly, which
  * you use when the wire kind must differ from the typename. This is the single place
  * that decides a record's own group, so every layer that reads it agrees.
  */