@abloatai/transaction 0.37.0

package/src/schema/queries.ts

@@ -0,0 +1,273 @@
+/**
+ * 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';
+import { AbloValidationError } from '../errors.js';
+
+// ── Query definition types ────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── 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<
+  TInput extends z.ZodType,
+  const TReturns extends string,
+>(spec: QuerySpec<TInput, TReturns>): QueryDef<TInput, TReturns> {
+  return {
+    input: spec.input,
+    returns: spec.returns,
+  };
+}
+
+// ── Queries record + type inference ───────────────────────────────────────
+
+/**
+ * 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;
+
+// ── 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<
+  S extends Schema,
+  const Q extends QueryRecord<S>,
+>(schema: S, queries: Q): Queries<S, Q> {
+  // 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: Record<string, QueryDef> = {};
+  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 as unknown as Q,
+  };
+}

package/src/schema/relation.ts

@@ -0,0 +1,291 @@
+/**
+ * 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'),
+ *   };
+ */
+
+// ── Relation options ──────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── Relation type brands ──────────────────────────────────────────────────
+
+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';
+// `export type { X } from` does NOT bind X in this module — the uses below need
+// their own import.
+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;
+}
+
+// ── Internal relation builder ─────────────────────────────────────────────
+
+class RelationBuilder<
+  Type extends RelationType,
+  Target extends string,
+  Field extends string,
+  Options extends BelongsToOptions = BelongsToOptions,
+> implements RelationDef<Type, Target, Field, Options>
+{
+  declare readonly [__relationType]: Type;
+  declare readonly [__relationTarget]: Target;
+  declare readonly [__relationField]: Field;
+
+  readonly type: Type;
+  readonly target: Target;
+  readonly foreignKey: Field;
+  /**
+   * 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: string;
+  readonly options: 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?: string;
+
+  constructor(type: Type, target: Target, foreignKey: Field, options?: Options) {
+    this.type = type;
+    this.target = target;
+    this.foreignKey = foreignKey;
+    this.foreignKeyColumn = foreignKey;
+    this.options = (options ?? ({} as 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 extends string,
+    Field extends string,
+    const Opts extends BelongsToOptions = Record<string, never>,
+  >(
+    target: Target,
+    foreignKey: Field,
+    options?: Opts
+  ): RelationDef<'belongsTo', Target, Field, Opts> {
+    return new RelationBuilder('belongsTo', target, foreignKey, options ?? ({} as 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
+   * ```
+   */
+  hasMany<Target extends string, Field extends string>(
+    target: Target,
+    foreignKey: Field,
+    options?: { orderBy?: string },
+  ): RelationDef<'hasMany', Target, Field> {
+    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 extends string, Field extends string>(
+    target: Target,
+    foreignKey: Field
+  ): RelationDef<'hasOne', Target, Field> {
+    return new RelationBuilder('hasOne', target, foreignKey);
+  },
+} as const;

package/src/schema/residency.ts

@@ -0,0 +1,30 @@
+/**
+ * A model's residency: which database its rows live in. This is a sibling axis
+ * to `tenancy`, which instead describes how rows are isolated within a single
+ * database.
+ *
+ *   - `tenant`  — the tenant data plane. For a customer-connected database this
+ *                 is the customer's own database, and provisioning creates these
+ *                 tables there.
+ *   - `control` — the coordination plane the engine owns: the change log,
+ *                 attribution, audit, and the like. These tables are never
+ *                 created in a customer's database.
+ *
+ * The name is `residency` rather than `plane` because "plane" already refers to
+ * the server's tenancy scope — organization, environment, and optionally
+ * project and sandbox. On the wire the serialized option is still keyed as
+ * `plane`, a frozen part of the wire format; only the TypeScript name differs.
+ *
+ * Declaring this boundary lets provisioning derive what a customer's database
+ * receives — the models whose residency is `tenant` — rather than hand-coding
+ * that list. Defaults to `tenant`.
+ */
+
+import { z } from 'zod';
+
+export const residencySchema = z.enum(['tenant', 'control']);
+export type ModelResidency = z.infer<typeof residencySchema>;
+
+/** Default residency for a model that doesn't declare one — the tenant data plane. */
+export const DEFAULT_RESIDENCY: ModelResidency = 'tenant';
+