@abloatai/transaction 0.37.0

package/dist/schema/queries.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Query definitions for a schema.
+ *
+ * A query pairs a Zod input schema with the name of the model it returns.
+ * Input types flow through `z.infer` and result types through `InferModel`,
+ * the same inference path `model` and `relation` use, so there is no separate
+ * type system to learn.
+ *
+ * Usage:
+ *   import { z } from 'zod';
+ *   import {
+ *     defineSchema, defineQueries, model, query, relation,
+ *   } from '@abloatai/transaction/schema';
+ *
+ *   const schema = defineSchema({
+ *     block: model(
+ *       { sectionId: z.string(), type: z.string() },
+ *       { section: relation.belongsTo('sections', 'sectionId') },
+ *       { load: 'lazy', typename: 'Block', persist: {} },
+ *     ),
+ *   });
+ *
+ *   const queries = defineQueries(schema, {
+ *     blocksByReport: query({
+ *       input:   z.object({ reportId: z.string() }),
+ *       returns: 'block',   // ← type-checked against schema.models
+ *     }),
+ *   });
+ *
+ *   type Input  = InferQueryInput<typeof queries.queries.blocksByReport>;
+ *   //    ^? { reportId: string }
+ *   type Result = InferQueryResult<
+ *     typeof schema,
+ *     typeof queries.queries.blocksByReport
+ *   >;
+ *   //    ^? Array<Block>
+ *
+ * Design notes:
+ *
+ *  - `query()` accepts any string for `returns`. The check that the string
+ *    names a real model runs when the query passes through
+ *    `defineQueries(schema, ...)`, the same way
+ *    `relation.belongsTo('projects', 'projectId')` takes a plain string at
+ *    the factory and defers the cross-reference check to schema assembly.
+ *
+ *  - A query carries no `name` until `defineQueries()` assigns one from its
+ *    record key — the same pattern `defineSchema({ tasks: model(...) })`
+ *    uses, where the model's name is the record key rather than a field on
+ *    the factory.
+ *
+ *  - Every query returns an array of a single model type. To fetch several
+ *    model types at once, run several queries in one batch rather than
+ *    declaring a combined shape. Each `QueryDef` therefore points at exactly
+ *    one model, and the loader hydrates results through a single
+ *    `schema.models[queryDef.returns]` lookup.
+ */
+import { z } from 'zod';
+import type { Schema, InferModel, InferModelNames } from './schema.js';
+/**
+ * A single query definition: a zod input shape, the schema key of the
+ * model it returns, and (after assembly) the name it was registered
+ * under.
+ *
+ * `name` is filled in by `defineQueries()` from the record key. It is
+ * optional on the type so `query()` can return a value without one —
+ * downstream code should only read `name` after the query has been
+ * passed through `defineQueries()`.
+ */
+export interface QueryDef<TInput extends z.ZodType = z.ZodType, TReturns extends string = string> {
+    /** Zod schema for the query's input arguments. */
+    readonly input: TInput;
+    /**
+     * The schema key of the model this query returns. Narrowed by
+     * `defineQueries()` to `InferModelNames<S>` via the `Q` generic, so
+     * a query whose `returns` does not match a known model fails at
+     * compile time.
+     */
+    readonly returns: TReturns;
+    /**
+     * The name under which the query is registered. {@link defineQueries}
+     * fills this in from the record key; you do not set it directly. It lives
+     * on the definition itself so dispatch and lookup code can read the name
+     * straight off a {@link QueryDef} without carrying the surrounding
+     * {@link Queries} object.
+     */
+    readonly name?: string;
+}
+/**
+ * The raw spec accepted by `query()`. Internal type — consumers never
+ * reference this directly, they call `query({ input, returns })`.
+ */
+interface QuerySpec<TInput extends z.ZodType, TReturns extends string> {
+    readonly input: TInput;
+    readonly returns: TReturns;
+}
+/**
+ * Define a query.
+ *
+ * `TReturns` is a `const` generic so TypeScript preserves the literal
+ * type of the `returns` value at call time (e.g., `'block'`
+ * 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 blocksByReport = query({
+ *   input:   z.object({ reportId: z.string() }),
+ *   returns: 'block',
+ * });
+ * ```
+ */
+export declare function query<TInput extends z.ZodType, const TReturns extends string>(spec: QuerySpec<TInput, TReturns>): QueryDef<TInput, TReturns>;
+/**
+ * A record of query names → query definitions, parameterized by a
+ * schema so each query's `returns` must reference a known model.
+ *
+ * This is the constraint type used by `defineQueries()` — it's what
+ * turns "any string" into "a model in this schema" without touching
+ * the `query()` factory itself.
+ */
+export type QueryRecord<S extends Schema> = Record<string, QueryDef<z.ZodType, InferModelNames<S>>>;
+/**
+ * The object returned by `defineQueries()`. Holds a reference back to
+ * the schema (so the loader can resolve `queryDef.returns` to
+ * a `ModelDef` at runtime via `schema.models[def.returns]`) and the
+ * resolved record of queries, each with its `name` field filled in.
+ */
+export interface Queries<S extends Schema, Q extends QueryRecord<S>> {
+    readonly schema: S;
+    readonly queries: Q;
+}
+/**
+ * Infer the input type of a query from its zod schema.
+ *
+ * ```ts
+ * type Input = InferQueryInput<typeof queries.queries.blocksByReport>;
+ * // { reportId: string }
+ * ```
+ */
+export type InferQueryInput<Q extends QueryDef> = z.infer<Q['input']>;
+/**
+ * Infer the result type of a query by looking up its `returns` model
+ * in the schema.
+ *
+ * Returns `Array<InferModel<S, returns>>` — all queries return a
+ * collection at this layer. Single-entity fetches use
+ * `ids: [singleId]` and the caller picks `result[0]`; this avoids a
+ * second `scope: 'single'` shape in the DSL for a case that can be
+ * expressed with the collection form.
+ *
+ * ```ts
+ * type Result = InferQueryResult<
+ *   typeof schema,
+ *   typeof queries.queries.blocksByReport
+ * >;
+ * // Array<Block>
+ * ```
+ */
+export type InferQueryResult<S extends Schema, Q extends QueryDef> = Q extends QueryDef<z.ZodType, infer R> ? R extends InferModelNames<S> ? InferModel<S, R>[] : never : never;
+/**
+ * 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.blocksByReport.name === 'blocksByReport'`. Dispatch and
+ * lookup code read `queryDef.name` directly rather than re-deriving it from
+ * the surrounding record.
+ *
+ * ```ts
+ * const schema = defineSchema({
+ *   block: model(
+ *     { sectionId: z.string() },
+ *     {},
+ *     { load: 'lazy', typename: 'Block', persist: {} },
+ *   ),
+ * });
+ *
+ * const queries = defineQueries(schema, {
+ *   blocksByReport: query({
+ *     input:   z.object({ reportId: z.string() }),
+ *     returns: 'block',   // ← type-checked
+ *   }),
+ * });
+ * ```
+ */
+export declare function defineQueries<S extends Schema, const Q extends QueryRecord<S>>(schema: S, queries: Q): Queries<S, Q>;
+export {};
+//# sourceMappingURL=queries.d.ts.map

package/dist/schema/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/schema/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKvE;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ,CACvB,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EACpC,QAAQ,SAAS,MAAM,GAAG,MAAM;IAEhC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,UAAU,SAAS,CACjB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,QAAQ,SAAS,MAAM;IAEvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;CAC5B;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CACnB,MAAM,SAAS,CAAC,CAAC,OAAO,EACxB,KAAK,CAAC,QAAQ,SAAS,MAAM,EAC7B,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAK/D;AAID;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI,MAAM,CAChD,MAAM,EACN,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CACxC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,OAAO,CACtB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC;IAExB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,QAAQ,IAChB,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GACtC,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,GAC1B,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAClB,KAAK,GACP,KAAK,CAAC;AAIV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,EAChB,KAAK,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,EAC9B,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAyBtC"}

package/dist/schema/queries.js

@@ -0,0 +1,144 @@
+/**
+ * Query definitions for a schema.
+ *
+ * A query pairs a Zod input schema with the name of the model it returns.
+ * Input types flow through `z.infer` and result types through `InferModel`,
+ * the same inference path `model` and `relation` use, so there is no separate
+ * type system to learn.
+ *
+ * Usage:
+ *   import { z } from 'zod';
+ *   import {
+ *     defineSchema, defineQueries, model, query, relation,
+ *   } from '@abloatai/transaction/schema';
+ *
+ *   const schema = defineSchema({
+ *     block: model(
+ *       { sectionId: z.string(), type: z.string() },
+ *       { section: relation.belongsTo('sections', 'sectionId') },
+ *       { load: 'lazy', typename: 'Block', persist: {} },
+ *     ),
+ *   });
+ *
+ *   const queries = defineQueries(schema, {
+ *     blocksByReport: query({
+ *       input:   z.object({ reportId: z.string() }),
+ *       returns: 'block',   // ← type-checked against schema.models
+ *     }),
+ *   });
+ *
+ *   type Input  = InferQueryInput<typeof queries.queries.blocksByReport>;
+ *   //    ^? { reportId: string }
+ *   type Result = InferQueryResult<
+ *     typeof schema,
+ *     typeof queries.queries.blocksByReport
+ *   >;
+ *   //    ^? Array<Block>
+ *
+ * Design notes:
+ *
+ *  - `query()` accepts any string for `returns`. The check that the string
+ *    names a real model runs when the query passes through
+ *    `defineQueries(schema, ...)`, the same way
+ *    `relation.belongsTo('projects', 'projectId')` takes a plain string at
+ *    the factory and defers the cross-reference check to schema assembly.
+ *
+ *  - A query carries no `name` until `defineQueries()` assigns one from its
+ *    record key — the same pattern `defineSchema({ tasks: model(...) })`
+ *    uses, where the model's name is the record key rather than a field on
+ *    the factory.
+ *
+ *  - Every query returns an array of a single model type. To fetch several
+ *    model types at once, run several queries in one batch rather than
+ *    declaring a combined shape. Each `QueryDef` therefore points at exactly
+ *    one model, and the loader hydrates results through 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., `'block'`
+ * 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 blocksByReport = query({
+ *   input:   z.object({ reportId: z.string() }),
+ *   returns: 'block',
+ * });
+ * ```
+ */
+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.blocksByReport.name === 'blocksByReport'`. Dispatch and
+ * lookup code read `queryDef.name` directly rather than re-deriving it from
+ * the surrounding record.
+ *
+ * ```ts
+ * const schema = defineSchema({
+ *   block: model(
+ *     { sectionId: z.string() },
+ *     {},
+ *     { load: 'lazy', typename: 'Block', persist: {} },
+ *   ),
+ * });
+ *
+ * const queries = defineQueries(schema, {
+ *   blocksByReport: query({
+ *     input:   z.object({ reportId: z.string() }),
+ *     returns: 'block',   // ← 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,
+    };
+}
+//# sourceMappingURL=queries.js.map

package/dist/schema/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/schema/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAiDnD,6EAA6E;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,KAAK,CAGnB,IAAiC;IACjC,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC;AAoED,6EAA6E;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,aAAa,CAG3B,MAAS,EAAE,OAAU;IACrB,mEAAmE;IACnE,yEAAyE;IACzE,oEAAoE;IACpE,qEAAqE;IACrE,uBAAuB;IACvB,MAAM,eAAe,GAA6B,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,mBAAmB,CAC3B,yBAAyB,IAAI,wBAAwB,GAAG,CAAC,OAAO,KAAK;gBACnE,sCAAsC;gBACtC,qBAAqB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,EAC1E,EAAE,IAAI,EAAE,6BAA6B,EAAE,CACxC,CAAC;QACJ,CAAC;QACD,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,OAAO;QACL,MAAM;QACN,qEAAqE;QACrE,mEAAmE;QACnE,OAAO,EAAE,eAA+B;KACzC,CAAC;AACJ,CAAC"}

package/dist/schema/relation.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Declarative relations between your models — the edges that turn a flat set
+ * of models into a graph. You attach relations to a model with the
+ * {@link relation} factories; the engine reads them to index foreign keys for
+ * fast child lookups, to order inserts so a parent row lands before the rows
+ * that reference it, and to generate the accessor properties that let you read
+ * `task.project` or `project.tasks` directly.
+ *
+ * Usage:
+ *   import { relation } from '@abloatai/transaction/schema';
+ *
+ *   const taskRelations = {
+ *     project: relation.belongsTo('projects', 'projectId'),
+ *     assignee: relation.belongsTo('users', 'assigneeId'),
+ *     comments: relation.hasMany('comments', 'taskId'),
+ *   };
+ */
+/**
+ * Options for `relation.belongsTo`. Each defaults to `false`, so every
+ * behavior below is opt-in per relation.
+ *
+ * `index: true` registers a foreign-key index for the child model when the
+ * engine starts, turning "every child that points at this parent" from a full
+ * scan into a constant-time lookup. Reach for it on relations you query this
+ * way often, such as a block's `sectionId`.
+ *
+ * `enrich: true` auto-populates the parent reference on an incoming change
+ * before the child data lands. A change to `Task { teamId: 't1' }` picks up the
+ * already-loaded `teams:t1` record and attaches it as `data.team`, so you can
+ * read `task.team` without a second lookup. Enrichment is best-effort: if the
+ * parent has not loaded yet it quietly does nothing, and the child data still
+ * applies.
+ *
+ * `defer: true` tells the engine to ignore this edge when it works out the
+ * order in which to insert rows. Use it on the soft side of a genuine reference
+ * cycle — the side where you are willing to insert the child first with the
+ * foreign key left null and fill it in with a later update. The other side of
+ * the cycle then becomes a strict predecessor, so the child is ordered after
+ * the parent rather than tied with it.
+ *
+ * `defer` changes only that ordering, not what the engine sends on the wire; it
+ * does not rewrite an insert into an insert-then-update. Pair it with a Postgres
+ * `DEFERRABLE INITIALLY DEFERRED` constraint when you also want the database to
+ * relax the foreign-key check itself. For example:
+ *
+ *   ```ts
+ *   layouts: model({ reportId: z.string().nullish() }, {
+ *     // The report-owns-layout link is nullable and the layout is always
+ *     // created first; marking it `defer` lets the report commit ahead of the
+ *     // layout instead of sharing its insert-order slot.
+ *     report: relation.belongsTo('reports', 'reportId', { defer: true }),
+ *   }),
+ *   ```
+ */
+export interface BelongsToOptions {
+    readonly index?: boolean;
+    readonly enrich?: boolean;
+    readonly defer?: boolean;
+    /**
+     * Marks the relation's target as this record's parent: the entity the record
+     * lives inside and inherits its access scope from. When a record is written,
+     * the engine routes it into its parent's sync group — following a chain of
+     * `parent` edges all the way up — so the change reaches everyone subscribed to
+     * the owning entity. This is the familiar rule that access flows down from a
+     * container to the things it holds, as a folder does to its files.
+     *
+     * Do not set `parent` on a reference that merely points at another record for
+     * provenance or as a template, such as `sourceSectionId` or `templateId`; doing
+     * so would leak the record into an unrelated scope. The engine also cannot
+     * infer the parent from whether a field is optional — many real parent keys
+     * are optional, like a root folder or an inbox task — so you must declare the
+     * parent edge explicitly.
+     *
+     * It reads naturally at the call site:
+     * `belongsTo('report', 'reportId', { parent: true })` — the report is the parent.
+     */
+    readonly parent?: boolean;
+    /**
+     * Emit a real Postgres foreign-key constraint for this relation when the
+     * engine provisions tables in a customer-owned database. This is independent
+     * of `parent`: `parent` decides which subscribers a change reaches, while
+     * `fk` decides whether the database enforces referential integrity. A relation
+     * may set either, both, or neither.
+     *
+     * Set `fk: true` only when the target row lives in the same database and is
+     * written in the same commit as this row, and points at a strong, contained
+     * entity. Leave it off provenance or template pointers (`sourceSectionId`,
+     * `templateId`), cross-tenant references, or anything that may be written in a
+     * different transaction than its target — a hard constraint there would reject
+     * the write and break out-of-order sync. The constraint is emitted as
+     * `DEFERRABLE INITIALLY DEFERRED, ON DELETE NO ACTION`: a plain integrity
+     * guard, leaving any cascade or null-on-delete behavior to the application.
+     */
+    readonly fk?: boolean;
+}
+declare const __relationType: unique symbol;
+declare const __relationTarget: unique symbol;
+declare const __relationField: unique symbol;
+/**
+ * The three edges the engine resolves. Inferred from `wire/modelShape.ts`
+ * rather than restated: the set is reported to callers by `GET /api/schema`,
+ * so it is protocol, and protocol has one definition.
+ */
+export type { RelationType } from '../wire/modelShape.js';
+import type { RelationType } from '../wire/modelShape.js';
+/**
+ * A relation definition, carrying its type information at both the type and
+ * runtime level.
+ *
+ * The `Options` generic captures a relation's options in the type system; only
+ * `belongsTo` uses it, while `hasMany` and `hasOne` leave it empty. The `const`
+ * modifier on the `belongsTo` factory preserves literal inference, so
+ * `{ enrich: true }` is remembered as `true` rather than widened to `boolean`,
+ * letting type-level features read the exact option value.
+ *
+ * `options` is always present at runtime: the factory substitutes an empty
+ * object when you omit it, so reading `options.index` or `options.enrich` needs
+ * no null check.
+ */
+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 field on the child model that holds the parent's id, as a camelCase
+     * schema field name. The engine reads `model[foreignKey]` to resolve the
+     * relation and to build client-side index keys; it is never interpolated into
+     * raw SQL — that is what {@link foreignKeyColumn} is for.
+     */
+    readonly foreignKey: Field;
+    /**
+     * The same foreign key expressed as a database column identifier.
+     * {@link foreignKey} is translated into this when you configure a `casing`
+     * option on `defineSchema` — for example `'snake_case'` turns `messageId`
+     * into `message_id`. The server interpolates this column name into SQL
+     * directly, because a driver's automatic camelCase-to-snake_case mapping does
+     * not reach identifiers embedded in raw SQL; resolving the name once at
+     * schema-build time is what makes it available there.
+     *
+     * Defaults to {@link foreignKey} when no `casing` option is set, so consumers
+     * whose database columns already match their field names need no
+     * configuration.
+     */
+    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
+     * section: relation.belongsTo('sections', 'sectionId', { 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.
+     * report: relation.belongsTo('reports', 'reportId', { 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 — for example, a project has many
+     * tasks via `Task.projectId`.
+     *
+     * At runtime the engine adds a getter to the parent model that returns every
+     * child whose foreign key matches, and registers the foreign-key index on the
+     * child model automatically.
+     *
+     * ```ts
+     * blocks: relation.hasMany('blocks', 'sectionId'),
+     * // → section.blocks returns all Block[] where sectionId === section.id
+     *
+     * blocks: relation.hasMany('blocks', 'sectionId', { orderBy: 'zIndex' }),
+     * // → section.blocks returns Block[] 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 — for example, a user has one profile
+     * via `Profile.userId`.
+     */
+    readonly hasOne: <Target extends string, Field extends string>(target: Target, foreignKey: Field) => RelationDef<"hasOne", Target, Field>;
+};
+//# sourceMappingURL=relation.d.ts.map

package/dist/schema/relation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.d.ts","sourceRoot":"","sources":["../../src/schema/relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;CACvB;AAID,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAC5C,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAC9C,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAE7C;;;;GAIG;AACH,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW,CAC1B,IAAI,SAAS,YAAY,GAAG,YAAY,EACxC,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IAEnD,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,KAAK,CAAC;IAElC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AA8CD,eAAO,MAAM,QAAQ;IACnB;;;;;;;;;;;;;;;;;;;;;OAqBG;yBAED,MAAM,SAAS,MAAM,EACrB,KAAK,SAAS,MAAM,QACd,IAAI,SAAS,gBAAgB,kCAE3B,MAAM,cACF,KAAK,YACP,IAAI,KACb,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC;IAIhD;;;;;;;;;;;;;;;OAeG;uBACK,MAAM,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,UACzC,MAAM,cACF,KAAK,YACP;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAC7B,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC;IAQxC;;;OAGG;sBACI,MAAM,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,UACxC,MAAM,cACF,KAAK,KAChB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;CAG/B,CAAC"}

package/dist/schema/relation.js

@@ -0,0 +1,105 @@
+/**
+ * Declarative relations between your models — the edges that turn a flat set
+ * of models into a graph. You attach relations to a model with the
+ * {@link relation} factories; the engine reads them to index foreign keys for
+ * fast child lookups, to order inserts so a parent row lands before the rows
+ * that reference it, and to generate the accessor properties that let you read
+ * `task.project` or `project.tasks` directly.
+ *
+ * Usage:
+ *   import { relation } from '@abloatai/transaction/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 double-cast smuggle through `Record<...>`.
+     */
+    _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
+     * section: relation.belongsTo('sections', 'sectionId', { 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.
+     * report: relation.belongsTo('reports', 'reportId', { defer: true }),
+     * ```
+     */
+    belongsTo(target, foreignKey, options) {
+        return new RelationBuilder('belongsTo', target, foreignKey, options ?? {});
+    },
+    /**
+     * This model has many of another model — for example, a project has many
+     * tasks via `Task.projectId`.
+     *
+     * At runtime the engine adds a getter to the parent model that returns every
+     * child whose foreign key matches, and registers the foreign-key index on the
+     * child model automatically.
+     *
+     * ```ts
+     * blocks: relation.hasMany('blocks', 'sectionId'),
+     * // → section.blocks returns all Block[] where sectionId === section.id
+     *
+     * blocks: relation.hasMany('blocks', 'sectionId', { orderBy: 'zIndex' }),
+     * // → section.blocks returns Block[] 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 — for example, a user has one profile
+     * via `Profile.userId`.
+     */
+    hasOne(target, foreignKey) {
+        return new RelationBuilder('hasOne', target, foreignKey);
+    },
+};
+//# sourceMappingURL=relation.js.map

package/dist/schema/relation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.js","sourceRoot":"","sources":["../../src/schema/relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA6JH,6EAA6E;AAE7E,MAAM,eAAe;IAWV,IAAI,CAAO;IACX,MAAM,CAAS;IACf,UAAU,CAAQ;IAC3B;;;;;;OAMG;IACH,gBAAgB,CAAS;IAChB,OAAO,CAAU;IAC1B;;;;;OAKG;IACH,QAAQ,CAAU;IAElB,YAAY,IAAU,EAAE,MAAc,EAAE,UAAiB,EAAE,OAAiB;QAC1E,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,gBAAgB,GAAG,UAAU,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,IAAK,EAAc,CAAC,CAAC;IAC9C,CAAC;CACF;AAED,6EAA6E;AAE7E,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAKP,MAAc,EACd,UAAiB,EACjB,OAAc;QAEd,OAAO,IAAI,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,IAAK,EAAW,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CACL,MAAc,EACd,UAAiB,EACjB,OAA8B;QAE9B,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QACnE,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACrB,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;QACrC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,MAAM,CACJ,MAAc,EACd,UAAiB;QAEjB,OAAO,IAAI,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3D,CAAC;CACO,CAAC"}