@abloatai/transaction 0.37.0

package/src/schema/tenancy.ts

@@ -0,0 +1,221 @@
+/**
+ * Defines how a model's rows are scoped to a tenant. Two forms live here, and the
+ * separation between them is deliberate:
+ *
+ *   1. The canonical form, {@link Tenancy} — a discriminated union that every
+ *      consumer reads (provisioning and row-level security, introspection, the
+ *      runtime, and the CLI) and the shape that crosses the wire in `ModelJSON`.
+ *      One exhaustively switchable shape, so the type system enforces the isolation
+ *      boundary.
+ *   2. The authoring form, {@link PolicyInput} — the `policy: { by }` option a
+ *      schema author writes. The name follows SQL row-level security, where a
+ *      policy is the rule that decides which rows a tenant may read.
+ *      {@link resolvePolicy} converts it to the canonical {@link Tenancy} when the
+ *      model is built, so the authoring vocabulary never reaches the wire or any
+ *      consumer.
+ *
+ * The canonical form is an exhaustively switchable discriminated union, so the type
+ * system enforces the isolation boundary at every consumer. The authoring form is a
+ * flat object whose `by` names the choice and whose per-branch rules are checked by a
+ * refinement — the opt-out from tenant scoping (`{ by: 'none' }`) and the
+ * source-derived case (`{ by: 'source' }`) are explicit, named values rather than
+ * falsy flags, important because `none` makes an entire table readable across tenants.
+ */
+
+import { z } from 'zod';
+
+/** The default physical tenancy column. This is the single canonical definition of that column name. */
+export const DEFAULT_ORG_COLUMN = 'organization_id';
+
+/**
+ * Scopes a table's rows through a parent table, for rows that carry no tenancy
+ * column of their own (for example, blocks scoped through their section, report,
+ * and organization). This is the canonical `parent` payload; authors write the
+ * friendlier {@link PolicyInput} `{ by: 'parent', fk, parent }` form, which
+ * {@link resolvePolicy} normalizes into this.
+ */
+export const scopedViaRefSchema = z.object({
+  /** Column on this table that points at the parent (for example, `'team_id'`). */
+  localKey: z.string().min(1),
+  /** Parent table name (e.g. `'team'`). */
+  parentTable: z.string().min(1),
+  /** Column on the parent that `localKey` references. Default `'id'`. */
+  parentKey: z.string().min(1).optional(),
+  /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+  parentOrgColumn: z.string().min(1).optional(),
+});
+export type ScopedViaRef = z.infer<typeof scopedViaRefSchema>;
+
+/** How a model's rows are scoped to a tenant — the canonical, wire-facing form. */
+export const tenancySchema = z.discriminatedUnion('kind', [
+  /** Row-local tenancy column (default name `organization_id`, overridable). */
+  z.object({ kind: z.literal('column'), column: z.string().min(1) }),
+  /** Scoped through a parent table's tenancy. */
+  z.object({ kind: z.literal('parent'), via: scopedViaRefSchema }),
+  /** Not tenant-scoped (global / reference data). */
+  z.object({ kind: z.literal('none') }),
+  /**
+   * Scoped by the data source itself: the model carries no tenancy column, and the
+   * owning organization is derived from the connected source that registered it — the
+   * registration is the tenant boundary. This is the natural default for a
+   * single-tenant connected database (`ablo connect`), which holds one org's rows and
+   * so has no per-row `organization_id` to read. Carries no payload for the same
+   * reason `none` does: the binding lives in the source registration, not the model.
+   */
+  z.object({ kind: z.literal('source') }),
+]);
+export type Tenancy = z.infer<typeof tenancySchema>;
+
+/**
+ * The authoring form of tenancy — what a schema author writes as the model's
+ * `policy` option. The name follows SQL row-level security, where a policy is the
+ * rule that decides which rows a tenant may read.
+ *
+ * The four choices `by` can take:
+ *
+ * - `{ by: 'column' }` — a row-local tenancy column (the default). `column`
+ *   overrides the name (default {@link DEFAULT_ORG_COLUMN}).
+ * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when
+ *   this table has no tenancy column of its own. `parentKey` (default `'id'`) and
+ *   `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are optional overrides.
+ * - `{ by: 'source' }` — derive the organization from the connected source that
+ *   registered the model, for a single-tenant connected database that carries no
+ *   `organization_id` column. The registration is the tenant boundary.
+ * - `{ by: 'none' }` — genuinely global or reference data. This makes the whole
+ *   table readable across tenants, so it is correct only for tables that have no tenant.
+ *
+ * The runtime schema is one flat object rather than a discriminated union: `by`
+ * selects the branch, and the {@link https://zod.dev | superRefine} pass enforces
+ * the per-branch field rules (`parent` requires `fk` and `parent`; the other three
+ * take no branch fields). The exported {@link PolicyInput} type is hand-written as a
+ * precise union so the compiler still requires the right fields per `by` — the flat
+ * schema validates at runtime, the union guides at author time, and the type guard
+ * below keeps the two from drifting.
+ */
+export const policyInputSchema = z
+  .object({
+    by: z.enum(['column', 'parent', 'none', 'source']),
+    /** `by: 'column'` — override the physical tenancy column name. Default {@link DEFAULT_ORG_COLUMN}. */
+    column: z.string().min(1).optional(),
+    /** `by: 'parent'` — column on this table that points at the parent (for example, `'sectionId'`). */
+    fk: z.string().min(1).optional(),
+    /** `by: 'parent'` — parent table name (e.g. `'sections'`). */
+    parent: z.string().min(1).optional(),
+    /** `by: 'parent'` — column on the parent that `fk` references. Default `'id'`. */
+    parentKey: z.string().min(1).optional(),
+    /** `by: 'parent'` — column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+    parentTenantColumn: z.string().min(1).optional(),
+  })
+  .superRefine((policy, ctx) => {
+    if (policy.by === 'parent') {
+      if (!policy.fk) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['fk'],
+          message:
+            "A `by: 'parent'` policy needs `fk` — the column on this table that points at the parent row whose tenancy it inherits.",
+        });
+      }
+      if (!policy.parent) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['parent'],
+          message:
+            "A `by: 'parent'` policy needs `parent` — the name of the parent table this table is scoped through.",
+        });
+      }
+    }
+    // A `column` policy may carry `column`; the parent fields belong only to `parent`.
+    // Flag a field that landed on the wrong branch so a typo doesn't silently no-op.
+    const parentOnly = ['fk', 'parent', 'parentKey', 'parentTenantColumn'] as const;
+    if (policy.by !== 'parent') {
+      for (const field of parentOnly) {
+        if (policy[field] !== undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [field],
+            message: `\`${field}\` only applies to a \`by: 'parent'\` policy; remove it or set \`by: 'parent'\`.`,
+          });
+        }
+      }
+    }
+    if (policy.by !== 'column' && policy.column !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['column'],
+        message: "`column` only applies to a `by: 'column'` policy; remove it or set `by: 'column'`.",
+      });
+    }
+  });
+
+/**
+ * The precise authoring type. Hand-written rather than inferred from
+ * {@link policyInputSchema} so the compiler enforces the per-branch fields the flat
+ * runtime schema can only check at parse time — an author writing `{ by: 'parent' }`
+ * gets a type error for the missing `fk`/`parent`, not a runtime one.
+ */
+export type PolicyInput =
+  | { by: 'column'; column?: string }
+  | { by: 'parent'; fk: string; parent: string; parentKey?: string; parentTenantColumn?: string }
+  | { by: 'source' }
+  | { by: 'none' };
+
+// Drift guard, both directions. Assignability one way only would let the schema
+// grow a fifth `by` value that no authoring branch can reach: the runtime would
+// accept it while `resolvePolicy`'s switch below never saw it. Pinning the
+// discriminants in both directions makes either side's addition a compile error.
+type _PolicyInputMatchesSchema = PolicyInput extends z.input<typeof policyInputSchema> ? true : never;
+type _SchemaByMatchesPolicyInput =
+  z.input<typeof policyInputSchema>['by'] extends PolicyInput['by'] ? true : never;
+const _policyInputAssignable: [_PolicyInputMatchesSchema, _SchemaByMatchesPolicyInput] = [
+  true,
+  true,
+];
+void _policyInputAssignable;
+
+/**
+ * Normalizes the authoring {@link PolicyInput} into the canonical {@link Tenancy}.
+ * Called once, when the model is built, so that `ModelDef`, `ModelJSON`, and every
+ * consumer see only the canonical union. Omitting `policy` defaults to a row-local
+ * `organization_id` column.
+ */
+export function resolvePolicy(input?: PolicyInput): Tenancy {
+  if (!input) return { kind: 'column', column: DEFAULT_ORG_COLUMN };
+  switch (input.by) {
+    case 'column':
+      return { kind: 'column', column: input.column ?? DEFAULT_ORG_COLUMN };
+    case 'parent':
+      return {
+        kind: 'parent',
+        via: {
+          localKey: input.fk,
+          parentTable: input.parent,
+          parentKey: input.parentKey,
+          parentOrgColumn: input.parentTenantColumn,
+        },
+      };
+    case 'source':
+      return { kind: 'source' };
+    case 'none':
+      return { kind: 'none' };
+  }
+}
+
+/**
+ * Reads the canonical {@link Tenancy} off an already-built model definition (or a
+ * parsed `ModelJSON`), defaulting to a row-local `organization_id` column when it is
+ * absent.
+ *
+ * This is the read-side helper. Consumers — provisioning and row-level security, the
+ * membership resolver, DDL generation, and the CLI — call it to get a model's
+ * tenancy without re-deriving the default each time. It is not the authoring
+ * normalizer; that is {@link resolvePolicy}.
+ */
+export function resolveTenancy(def: { tenancy?: Tenancy }): Tenancy {
+  return def.tenancy ?? { kind: 'column', column: DEFAULT_ORG_COLUMN };
+}
+
+/** The physical tenancy column for a column-scoped model, else `null`. */
+export function tenancyColumn(t: Tenancy): string | null {
+  return t.kind === 'column' ? t.column : null;
+}

package/src/server/adapter.ts

@@ -0,0 +1,203 @@
+/**
+ * `@abloatai/transaction/server` — the `DataAdapter` storage contract.
+ *
+ * A `DataAdapter` is the boundary between the sync engine and a database. The
+ * engine asks it to do three things — `read` canonical rows, `commit` a change,
+ * and `sync` the change log — and expects nothing beyond that. Everything
+ * higher up, such as proposing a change or resolving a conflict, is handled
+ * before the adapter is ever called.
+ *
+ * This module declares the contract and the value types that travel through it;
+ * you supply the implementation for your own database. The reference Postgres
+ * implementation ships separately, because it carries a SQL driver and raw
+ * queries that have no place in this browser-safe build.
+ *
+ * Every shape here builds on {@link Row}, the single canonical form of a
+ * database row that the rest of the engine reads and writes.
+ */
+
+import type {
+  SourceListQuery,
+  SourceOperation,
+  SourceRequestContext,
+} from '../source/index.js';
+import type { ServerSyncDelta } from '../wire/delta.js';
+import type { BootstrapModel } from './readConfig.js';
+import type { CommitContext, CommitExecutionResult } from './commit.js';
+import type { StorageMode } from './storageMode.js';
+
+/**
+ * A canonical database row: one record, keyed by column name. The value type is
+ * `unknown` by design, not `any` — columns arrive as JSON or in whatever form
+ * the driver hands back, so a caller must narrow a value before using it. Reach
+ * for this type wherever a row is passed around; it is the one name for that
+ * shape, and a later schema-typed `read<T>()` can specialize it to a concrete
+ * model without changing any call site.
+ */
+export type Row = Record<string, unknown>;
+
+// ── read results ───────────────────────────────────────────────────────────
+
+/**
+ * The result of a {@link Row} read. Its two shapes mirror the two kinds of
+ * {@link ReadRequest}:
+ *  - `bootstrap`: a full load, returned as a map from model name to its rows.
+ *  - `query`: the rows of a single filtered query.
+ */
+export type ReadResult =
+  | {
+      readonly kind: 'bootstrap';
+      /** model name → its rows. Empty models are omitted. */
+      readonly models: Record<string, Row[]>;
+      /** Models whose read failed (partial success), if any. */
+      readonly failedModels?: string[];
+      /**
+       * Present when a paged read (`ReadRequest.page`) stopped at its row
+       * limit with rows remaining: pass it back as the next page's cursor.
+       * Absent on the final page and on unpaged reads.
+       */
+      readonly nextCursor?: string;
+    }
+  | {
+      readonly kind: 'query';
+      readonly rows: readonly Row[];
+    };
+
+// ── sync ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Where a `sync` call resumes: the client's last-seen position in the
+ * `sync_deltas` change log. The cursor carries only that position. Everything
+ * else a sync needs — the organization, the sync groups, the largest gap it
+ * will stream — is bound onto the adapter when it is resolved, so a client can
+ * never ask to read an organization other than its own. A `lastSyncId` of zero
+ * or less means "no position yet", which `sync` answers with `needsFullRead`.
+ */
+export interface SyncCursor {
+  readonly lastSyncId: number;
+}
+
+// ── capabilities ─────────────────────────────────────────────────────────────
+
+export interface DataAdapterCapabilities {
+  /** The backend can dry-run a change without committing it. */
+  readonly propose?: boolean;
+  /** `commit` is atomic (all-or-nothing) across the change's operations. */
+  readonly transactions?: boolean;
+  /** Changes fan out in real time (vs poll-only). */
+  readonly realtime?: boolean;
+  /** The backend can be introspected for its schema. */
+  readonly schemaIntrospection?: boolean;
+}
+
+// ── proposal (capability-gated) ───────────────────────────────────────────────
+
+/** Result of a dry-run proposal (only adapters with `capabilities.propose`). */
+export interface ProposalResult {
+  readonly ok: boolean;
+  readonly conflicts?: readonly {
+    readonly model: string;
+    readonly id: string;
+    readonly reason: string;
+  }[];
+  readonly rows?: readonly Row[];
+}
+
+// ── read request ───────────────────────────────────────────────────────────
+
+/**
+ * A request for canonical rows, in one of two shapes:
+ *  - `bootstrap`: the full-load reader — every enabled model's rows at once.
+ *  - `query`: a single filtered query against one model, used by the live
+ *    `/sync/query` path.
+ *
+ * A `query` carries its own execution as the `runHosted` closure, the same way
+ * a {@link ChangeSet} carries its write. This lets the adapter decide how to
+ * answer the request — a data source runs the customer's `list`, a hosted
+ * database runs the closure — without the query engine itself having to live
+ * inside the adapter.
+ */
+export type ReadRequest =
+  | {
+      readonly kind: 'bootstrap';
+      readonly models: readonly BootstrapModel[];
+      readonly requestedModels?: readonly string[];
+      readonly scope?: SourceRequestContext;
+      /**
+       * Keyset pagination for a SINGLE-model read (`requestedModels` names
+       * exactly one model): return at most `limit` rows, starting after the
+       * row whose id equals `cursor`. The result carries `nextCursor` while
+       * rows remain. Ignored for multi-model reads and by adapters whose
+       * backend pages upstream on its own.
+       */
+      readonly page?: { readonly cursor?: string; readonly limit: number };
+    }
+  | {
+      readonly kind: 'query';
+      readonly model: string;
+      /** Source-side model name, when it differs from `model`. */
+      readonly sourceModel?: string;
+      /** `__typename` stamped on each returned row. */
+      readonly typename: string;
+      readonly query: SourceListQuery;
+      readonly scope?: SourceRequestContext;
+      /** Runs the query against a hosted database: compile, take the tenant pool, apply row-level security, unpack the rows. */
+      readonly runHosted: () => Promise<Row[]>;
+    };
+
+// ── change set (commit input) ──────────────────────────────────────────────
+
+/**
+ * A change to apply to the canonical store. `runHosted` holds the write already
+ * bound to its execution: a hosted adapter simply runs it, while a data-source
+ * adapter ignores it and ships the operations to the customer's own endpoint.
+ * The adapter therefore decides how a change is applied, while the write logic
+ * itself is prepared above it.
+ */
+export interface ChangeSet {
+  readonly operations: readonly SourceOperation[];
+  readonly context: CommitContext;
+  readonly clientTxId: string;
+  readonly runHosted: () => Promise<CommitExecutionResult>;
+}
+
+// ── sync result ────────────────────────────────────────────────────────────
+
+export interface SyncResult {
+  /** Deltas in `(cursor.lastSyncId, nextCursor.lastSyncId]`, scoped to syncGroups. */
+  readonly changes: readonly ServerSyncDelta[];
+  readonly nextCursor: { readonly lastSyncId: number };
+  /** True when the gap was too large to stream — caller must full-`read`. */
+  readonly needsFullRead: boolean;
+}
+
+// ── the interface ──────────────────────────────────────────────────────────
+
+/**
+ * The interface every storage mode implements. The package defines the
+ * contract; you implement it against your own database. An adapter is
+ * responsible for one thing — reaching the data — and offers exactly three
+ * methods to do it: `read` fetches canonical rows, `commit` applies a change,
+ * and `sync` reads the change log. Anything above that line, such as proposing
+ * a change or resolving a conflict, happens before the adapter is called.
+ * `propose` is an optional capability, not a required method.
+ */
+export interface DataAdapter {
+  /** Names the adapter's storage mode, for diagnostics. Routing is decided by
+   *  the resolver, not by reading this field. */
+  readonly mode: StorageMode;
+  readonly capabilities: DataAdapterCapabilities;
+  read(req: ReadRequest): Promise<ReadResult>;
+  commit(change: ChangeSet): Promise<CommitExecutionResult>;
+  sync(cursor: SyncCursor): Promise<SyncResult>;
+}
+
+/** A `DataAdapter` whose backend can dry-run a change. Narrow to this only after confirming the `propose` capability. */
+export interface ProposableDataAdapter extends DataAdapter {
+  propose(change: ChangeSet): Promise<ProposalResult>;
+}
+
+/** Resolves an authenticated scope to the adapter that serves it. */
+export type AdapterResolver = (
+  scope: { readonly projectId: string; readonly accountScope?: string },
+) => Promise<DataAdapter> | DataAdapter;

package/src/server/commit.ts

@@ -0,0 +1,109 @@
+/**
+ * The commit contract types for the sync engine's server surface.
+ *
+ * {@link CommitContext} is the attribution envelope stamped onto every delta a
+ * commit produces; {@link CommitExecutionResult} is the receipt returned when the commit
+ * finishes. Both are plain data descriptors — no database driver, no SQL, no
+ * functions — so they belong to this package's public contract, which your commit
+ * implementation reads and writes. They feed the `ChangeSet` and `DataAdapter`
+ * contracts defined alongside them.
+ *
+ * The attribution fields reuse the shared {@link ParticipantKind},
+ * {@link ConfirmationState}, and {@link ParticipantRef} types, so the shape at
+ * commit time and the shape of a stored or broadcast delta share one definition
+ * rather than being kept in step by hand.
+ */
+import type { ParticipantKind, ConfirmationState } from '../log/syncDeltaRow.js';
+import type { ParticipantRef } from '../wire/delta.js';
+import type { CommitExecutionResultInput } from '../wire/commit.js';
+import type { Environment } from '../environment.js';
+import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
+
+export interface CommitContext {
+  participantId: string;
+  /**
+   * The kind of participant making the commit. Required, so that every delta carries
+   * structured attribution rather than a string-prefix convention.
+   */
+  participantKind: ParticipantKind;
+  organizationId: string;
+  /**
+   * Project scope used to route source-mode storage. When omitted, the commit
+   * targets the organization's default project.
+   */
+  projectId?: string;
+  /** Exact sandbox plane derived from the authenticated key, when present. */
+  sandboxId?: string;
+  /** Optional external account scope forwarded to storage resolvers. */
+  accountScope?: string;
+  /**
+   * The environment this commit runs in. Source-mode adapters forward it to the
+   * customer's handlers so that sandbox and production traffic can reach distinct
+   * customer-owned stores.
+   */
+  environment?: Environment;
+  /**
+   * The sync groups this participant subscribes to, taken from the connection
+   * upgrade or the capability token. Each is appended to every delta's `sync_groups`
+   * so that writes fan out to subscribers of entity-level groups (such as
+   * `report:abc`), not only the default `org:X` and `user:Y` groups. When omitted, the
+   * commit fans out to just the organization and user groups.
+   */
+  syncGroups?: readonly string[];
+  /**
+   * When true, the commit does not add `org:<organizationId>` to a delta's sync
+   * groups. Set this for sandbox writes, so that live organization subscribers do
+   * not receive test-environment changes.
+   */
+  omitOrgSyncGroup?: boolean;
+  /**
+   * The participant on whose authority the actor acted. For a direct human commit
+   * this equals the actor; for an agent commit it is the human at the root of the
+   * capability's delegation chain. Null for `system` principals.
+   */
+  onBehalfOf?: ParticipantRef | null;
+  /**
+   * The id of the scoped credential that authorized the commit. Non-null for agent
+   * and system commits when that credential is known; null for direct human commits.
+   */
+  capabilityId?: string | null;
+  /**
+   * The id of the human user at the root of the delegated-authority chain. Stored
+   * directly on `sync_deltas` so that audit triggers appending the hash chain never
+   * need to join mutable credential tables.
+   */
+  delegationChainRootUserId?: string | null;
+  /**
+   * The id of the API key row when the caller authenticated with an API key. Used by
+   * the idempotency cache and for usage attribution. Null for session and capability
+   * callers.
+   */
+  apiKeyId?: string | null;
+  /**
+   * Whether a human explicitly approved the change. Defaults to `auto` when the
+   * caller does not specify an approval state.
+   */
+  confirmationState?: ConfirmationState;
+  /**
+   * The premise for the whole batch. The committer declares the rows or groups
+   * it read to form this batch; the engine checks that none of them changed since
+   * each entry's `readAt` timestamp and applies that entry's `onStale` disposition
+   * across the batch. This differs from the per-operation `readAt` guard, which
+   * validates only the rows being written. Omit it to check the write targets alone.
+   */
+  reads?: ReadDependency[] | null;
+  /**
+   * Durable premises to persist for this commit's participant. Each entry is
+   * kept in `track_dependencies` and re-checked against every future delta; a
+   * later match opens a `StaleNotification` delivered out of band. Distinct
+   * from `reads`, which is checked once here and discarded.
+   */
+  track?: TrackDependency[] | null;
+}
+
+/**
+ * The server execution receipt persisted in `mutation_log`. Its runtime schema
+ * lives with the HTTP/WS settlement contract so queued correlation cannot drift
+ * between cache, transport, and client.
+ */
+export type CommitExecutionResult = CommitExecutionResultInput;

package/src/server/index.ts

@@ -0,0 +1,26 @@
+/**
+ * The server-side entry point of the sync engine. It re-exports the contract types
+ * you implement a storage backend against: the {@link DataAdapter} and its
+ * vocabulary ({@link Row}, {@link ReadRequest}, {@link ChangeSet}, and the rest),
+ * the {@link CommitContext} and {@link CommitExecutionResult} commit types, the
+ * {@link StorageMode} enumeration, and the per-model read configuration
+ * ({@link BootstrapModel}, {@link ColumnOverride}). These are plain, driver-free
+ * types; you supply the database code that fulfills them.
+ */
+export type {
+  Row,
+  ReadResult,
+  SyncCursor,
+  DataAdapterCapabilities,
+  ProposalResult,
+  ReadRequest,
+  ChangeSet,
+  SyncResult,
+  DataAdapter,
+  ProposableDataAdapter,
+  AdapterResolver,
+} from './adapter.js';
+export type { CommitContext, CommitExecutionResult } from './commit.js';
+export { commitExecutionResultSchema } from '../wire/commit.js';
+export { storageModeSchema, type StorageMode } from './storageMode.js';
+export type { ColumnOverride, BootstrapModel } from './readConfig.js';

package/src/server/readConfig.ts

@@ -0,0 +1,82 @@
+/**
+ * Canonical per-model read configuration consumed when a client bootstraps. Each
+ * {@link BootstrapModel} maps a model to its physical table, its tenancy column, and
+ * any parent scoping — plain data with no database driver. It feeds the read side of
+ * the data adapter contract; your query builder reads it to load a model's initial
+ * rows.
+ */
+
+/** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
+export interface ColumnOverride {
+  readonly field: string;
+  readonly column: string;
+  readonly alias: string;
+}
+
+/** Read configuration for one model: how to locate its rows and scope them to a tenant. */
+export interface BootstrapModel {
+  name: string;
+  /**
+   * Extra names accepted when a request looks up or filters this model. When the
+   * physical table name is canonical, `name` stays that table name and the aliases
+   * cover generated compatibility names such as `WeatherReports` or `weatherReports`.
+   */
+  aliases?: readonly string[];
+  /**
+   * The schema key used by source endpoints. `name` stays the wire and result model
+   * name (usually the typename), while source handlers are keyed by the developer's
+   * schema key, such as `files` or `blocks`.
+   */
+  sourceModel?: string;
+  table: string;
+  syncGroups?: string[];
+  enabled?: boolean;
+  /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
+  limit?: number;
+  /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
+  orderBy?: string;
+  /** Whether the table has organization_id. Default: true. */
+  orgScoped?: boolean;
+  /**
+   * The model derives its tenant from the connected data source (`policy:
+   * { by: 'source' }`) rather than a row column. It carries no tenant predicate on a
+   * log plane, so it is excluded from the bootstrap set entirely until the
+   * write-through connect path can resolve the org from the source registration —
+   * serving it now would return every row to every tenant. Kept on the type as a
+   * defense-in-depth marker so a source-scoped model that reaches `getBootstrapData`
+   * fails closed rather than bootstrapping unscoped.
+   */
+  sourceScoped?: boolean;
+  /** Physical tenancy column (default `organization_id`, configurable per model). */
+  orgColumn?: string;
+  /**
+   * Parent-table scoping for rows that have no `organization_id` column, mirroring
+   * the schema's `scopedVia` option. When set, the bootstrap query adds:
+   *
+   *   WHERE <table>.<localKey> IN
+   *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
+   *
+   * This applies on top of whatever `orgScoped` dictates, so a table can carry its
+   * own `organization_id` and still narrow through a parent. The common case,
+   * though, is `orgScoped: false` together with `scopedVia` on a table that lacks the
+   * column.
+   */
+  scopedVia?: {
+    localKey: string;
+    parentTable: string;
+    parentKey?: string;
+    parentOrgColumn?: string;
+  };
+  /** Client-facing field name → physical DB column for declared fields. */
+  fieldColumns?: Record<string, string>;
+  /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
+  columnOverrides?: readonly ColumnOverride[];
+  /**
+   * Physical columns the schema declares as JSON (via `field.json()`). A JSON field
+   * stored in a text column comes back from `row_to_json` as a serialized string, so
+   * the bootstrap reparses these columns to make the wire value the canonical object
+   * regardless of the physical column type. A `jsonb` column already returns an
+   * object, so reparsing it is a no-op.
+   */
+  jsonColumns?: readonly string[];
+}

package/src/server/storageMode.ts

@@ -0,0 +1,20 @@
+/**
+ * The compatibility set of storage modes a `DataAdapter` can run in. An adapter carries one of
+ * these as a label for diagnostics; it does not decide routing, which the adapter
+ * resolver handles separately. The package defines the enum so that the contract
+ * and every adapter agree on the same closed set of values:
+ *
+ *   - `hosted`     — a database this engine operates on the caller's behalf.
+ *   - `selfHosted` — the caller's own database, reached through the same execution
+ *                    path as `hosted`.
+ *   - `source`     — a caller-owned endpoint that accepts changes over HTTP without
+ *                    database credentials.
+ *
+ * These names describe where the data lives, not anything an end user sees.
+ */
+import { z } from 'zod';
+
+/** Runtime validator for the storage-mode values; {@link StorageMode} is its inferred type. */
+export const storageModeSchema = z.enum(['hosted', 'source', 'selfHosted']);
+/** The storage mode an adapter runs in — one of the values described in the module overview. */
+export type StorageMode = z.infer<typeof storageModeSchema>;