@abloatai/ablo 0.26.0 → 0.28.0

package/dist/schema/tenancy.d.ts

@@ -1,36 +1,32 @@
 /**
- * Tenancy — the single source of truth for how a model's rows are scoped to a
- * tenant. There are exactly two layers here, and keeping them separate is the
- * whole point:
+ * 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 Zod discriminated union. This is
- *      what every consumer (provision/RLS, introspection, runtime, CLI) reads
- *      and what crosses the wire in `ModelJSON`. One shape, exhaustively
- *      switchable, so the type system holds the isolation boundary.
- *   2. The AUTHORING form — {@link PolicyInput}, the `policy: { by }` option a
- *      schema author writes. The name follows Postgres/Supabase RLS vocabulary:
- *      a `policy` is the rule that decides which rows a tenant may read.
- *      {@link resolvePolicy} maps it to the canonical {@link Tenancy} at
- *      `model()`-build time (much as Supabase's `create policy` compiles to a
- *      `pg_policy` row), so the authoring vocabulary never reaches the wire or
- *      any consumer.
+ *   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.
  *
- * Why one authoring option (`policy`) instead of the old
- * `orgScoped`/`scopedVia`/`orgColumn` trio: those three were synonyms for one
- * decision ("how is this row scoped?"), and the most dangerous of them
- * (`orgScoped: false`) silently exposed a whole table cross-tenant. Collapsing
- * them into a single discriminated union makes the opt-out (`{ by: 'none' }`) a
- * loud, deliberate branch instead of a falsy flag — one concept, one name.
+ * Both forms discriminate on a single tag, which makes the opt-out from tenant
+ * scoping (`{ by: 'none' }`) an explicit, named branch rather than a falsy flag —
+ * important, because that branch makes an entire table readable across tenants.
  */
 import { z } from 'zod';
-/** Default physical tenancy column. The ONLY place this literal is canonical. */
+/** The default physical tenancy column. This is the single canonical definition of that column name. */
 export declare const DEFAULT_ORG_COLUMN = "organization_id";
 /**
- * Scope a table's rows through a parent table (for rows that carry no tenancy
- * column of their own — e.g. `slide_layers` → slide → deck → org). This is the
- * CANONICAL `parent` payload; authors write the friendlier {@link PolicyInput}
- * `{ by: 'parent', fk, parent }` shape, normalized into this by
- * {@link resolvePolicy}.
+ * Scopes a table's rows through a parent table, for rows that carry no tenancy
+ * column of their own (for example, slide layers scoped through their slide, deck,
+ * 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 declare const scopedViaRefSchema: z.ZodObject<{
     localKey: z.ZodString;
@@ -39,7 +35,7 @@ export declare const scopedViaRefSchema: z.ZodObject<{
     parentOrgColumn: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ScopedViaRef = z.infer<typeof scopedViaRefSchema>;
-/** How a model's rows are scoped to a tenant — the CANONICAL, wire-facing form. */
+/** How a model's rows are scoped to a tenant — the canonical, wire-facing form. */
 export declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"column">;
     column: z.ZodString;
@@ -56,19 +52,19 @@ export declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "kind">;
 export type Tenancy = z.infer<typeof tenancySchema>;
 /**
- * The AUTHORING form of tenancy — what a schema author writes as the model's
- * `policy` option (Postgres/Supabase RLS vocabulary: a policy is the rule that
- * scopes which rows a tenant may read). A Zod discriminated union on `by`, so
- * the three branches are mutually exclusive and the dangerous opt-out
+ * 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. It is a discriminated union on
+ * `by`, so the three branches are mutually exclusive and the opt-out
  * (`{ by: 'none' }`) is an explicit, named choice rather than a falsy flag.
  *
- * - `{ by: 'column' }`            — row-local tenancy column (the default).
- *   `column` overrides the name (default {@link DEFAULT_ORG_COLUMN}).
+ * - `{ 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 overrides.
- * - `{ by: 'none' }`             — genuinely global / reference data. ⚠ Makes
- *   the whole table readable cross-tenant — only correct for tenant-less tables.
+ *   this table has no tenancy column of its own. `parentKey` (default `'id'`) and
+ *   `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are optional overrides.
+ * - `{ 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.
  */
 export declare const policyInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     by: z.ZodLiteral<"column">;
@@ -84,19 +80,21 @@ export declare const policyInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "by">;
 export type PolicyInput = z.infer<typeof policyInputSchema>;
 /**
- * Normalize the authoring {@link PolicyInput} into the one canonical
- * {@link Tenancy}. Called once, at `model()`-build, so `ModelDef`/`ModelJSON`
- * and every consumer see only the canonical union. Omitting `policy` defaults
- * to a row-local `organization_id` column.
+ * 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 declare function resolvePolicy(input?: PolicyInput): Tenancy;
 /**
- * Read the canonical {@link Tenancy} off an already-built model def (or parsed
- * `ModelJSON`), defaulting to a row-local `organization_id` column when absent.
+ * 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 (provision/RLS, membership resolver,
- * DDL, CLI) call it to get a model's tenancy without re-deriving the default in
- * each place. It is NOT the authoring normalizer; that's {@link resolveIsolation}.
+ * 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 declare function resolveTenancy(def: {
     tenancy?: Tenancy;

package/dist/schema/tenancy.js

@@ -1,39 +1,35 @@
 /**
- * Tenancy — the single source of truth for how a model's rows are scoped to a
- * tenant. There are exactly two layers here, and keeping them separate is the
- * whole point:
+ * 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 Zod discriminated union. This is
- *      what every consumer (provision/RLS, introspection, runtime, CLI) reads
- *      and what crosses the wire in `ModelJSON`. One shape, exhaustively
- *      switchable, so the type system holds the isolation boundary.
- *   2. The AUTHORING form — {@link PolicyInput}, the `policy: { by }` option a
- *      schema author writes. The name follows Postgres/Supabase RLS vocabulary:
- *      a `policy` is the rule that decides which rows a tenant may read.
- *      {@link resolvePolicy} maps it to the canonical {@link Tenancy} at
- *      `model()`-build time (much as Supabase's `create policy` compiles to a
- *      `pg_policy` row), so the authoring vocabulary never reaches the wire or
- *      any consumer.
+ *   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.
  *
- * Why one authoring option (`policy`) instead of the old
- * `orgScoped`/`scopedVia`/`orgColumn` trio: those three were synonyms for one
- * decision ("how is this row scoped?"), and the most dangerous of them
- * (`orgScoped: false`) silently exposed a whole table cross-tenant. Collapsing
- * them into a single discriminated union makes the opt-out (`{ by: 'none' }`) a
- * loud, deliberate branch instead of a falsy flag — one concept, one name.
+ * Both forms discriminate on a single tag, which makes the opt-out from tenant
+ * scoping (`{ by: 'none' }`) an explicit, named branch rather than a falsy flag —
+ * important, because that branch makes an entire table readable across tenants.
  */
 import { z } from 'zod';
-/** Default physical tenancy column. The ONLY place this literal is canonical. */
+/** The default physical tenancy column. This is the single canonical definition of that column name. */
 export const DEFAULT_ORG_COLUMN = 'organization_id';
 /**
- * Scope a table's rows through a parent table (for rows that carry no tenancy
- * column of their own — e.g. `slide_layers` → slide → deck → org). This is the
- * CANONICAL `parent` payload; authors write the friendlier {@link PolicyInput}
- * `{ by: 'parent', fk, parent }` shape, normalized into this by
- * {@link resolvePolicy}.
+ * Scopes a table's rows through a parent table, for rows that carry no tenancy
+ * column of their own (for example, slide layers scoped through their slide, deck,
+ * 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 pointing at the parent (e.g. `'team_id'`). */
+    /** 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),
@@ -42,7 +38,7 @@ export const scopedViaRefSchema = z.object({
     /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
     parentOrgColumn: z.string().min(1).optional(),
 });
-/** How a model's rows are scoped to a tenant — the CANONICAL, wire-facing form. */
+/** 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) }),
@@ -52,19 +48,19 @@ export const tenancySchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('none') }),
 ]);
 /**
- * The AUTHORING form of tenancy — what a schema author writes as the model's
- * `policy` option (Postgres/Supabase RLS vocabulary: a policy is the rule that
- * scopes which rows a tenant may read). A Zod discriminated union on `by`, so
- * the three branches are mutually exclusive and the dangerous opt-out
+ * 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. It is a discriminated union on
+ * `by`, so the three branches are mutually exclusive and the opt-out
  * (`{ by: 'none' }`) is an explicit, named choice rather than a falsy flag.
  *
- * - `{ by: 'column' }`            — row-local tenancy column (the default).
- *   `column` overrides the name (default {@link DEFAULT_ORG_COLUMN}).
+ * - `{ 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 overrides.
- * - `{ by: 'none' }`             — genuinely global / reference data. ⚠ Makes
- *   the whole table readable cross-tenant — only correct for tenant-less tables.
+ *   this table has no tenancy column of its own. `parentKey` (default `'id'`) and
+ *   `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are optional overrides.
+ * - `{ 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.
  */
 export const policyInputSchema = z.discriminatedUnion('by', [
     z.object({
@@ -74,7 +70,7 @@ export const policyInputSchema = z.discriminatedUnion('by', [
     }),
     z.object({
         by: z.literal('parent'),
-        /** Column on THIS table pointing at the parent (e.g. `'slideId'`). */
+        /** Column on this table that points at the parent (for example, `'slideId'`). */
         fk: z.string().min(1),
         /** Parent table name (e.g. `'slides'`). */
         parent: z.string().min(1),
@@ -86,10 +82,10 @@ export const policyInputSchema = z.discriminatedUnion('by', [
     z.object({ by: z.literal('none') }),
 ]);
 /**
- * Normalize the authoring {@link PolicyInput} into the one canonical
- * {@link Tenancy}. Called once, at `model()`-build, so `ModelDef`/`ModelJSON`
- * and every consumer see only the canonical union. Omitting `policy` defaults
- * to a row-local `organization_id` column.
+ * 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) {
     if (!input)
@@ -112,12 +108,14 @@ export function resolvePolicy(input) {
     }
 }
 /**
- * Read the canonical {@link Tenancy} off an already-built model def (or parsed
- * `ModelJSON`), defaulting to a row-local `organization_id` column when absent.
+ * 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 (provision/RLS, membership resolver,
- * DDL, CLI) call it to get a model's tenancy without re-deriving the default in
- * each place. It is NOT the authoring normalizer; that's {@link resolveIsolation}.
+ * 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) {
     return def.tenancy ?? { kind: 'column', column: DEFAULT_ORG_COLUMN };

package/dist/server/adapter.d.ts

@@ -1,39 +1,39 @@
 /**
- * `@abloatai/ablo/server` — the DataAdapter CONTRACT vocabulary.
+ * `@abloatai/ablo/server` — the `DataAdapter` storage contract.
  *
- * This is the Better-Auth-style seam: the package defines the storage
- * interface and its value types; a host (today `apps/sync-server`, tomorrow a
- * consumer's app) implements it against a real database. The reference Postgres
- * implementation (`executeCommit` + `selectAdapter`) stays host-side — it
- * carries a `postgres` driver and raw SQL, which must never enter this
- * browser-shippable package.
+ * 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.
  *
- * Scope note: this file holds the parts of the contract that are PURE — they
- * depend only on primitives and {@link Row}. The full `DataAdapter` interface
- * (and its `sync()` method) references `SyncDelta`, which currently has two
- * definitions (server `db/deltas` vs package `core`) pending unification; the
- * `commit`/`read` request envelopes reference server domain types
- * (`CommitContext`, `BootstrapModel`). Those stay server-local and re-import
- * these primitives until that canonicalization lands.
+ * 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 '../schema/sync-delta-wire.js';
-import type { BootstrapModel } from './read-config.js';
+import type { ServerSyncDelta } from '../wire/delta.js';
+import type { BootstrapModel } from './readConfig.js';
 import type { CommitContext, CommitResult } from './commit.js';
-import type { StorageMode } from './storage-mode.js';
+import type { StorageMode } from './storageMode.js';
 /**
- * A canonical row — one model record keyed by column name. The VALUE type is
- * `unknown`, on purpose and as a best practice: a row's columns are JSONB /
- * driver-dynamic, so `unknown` forces callers to narrow before use (the safe
- * opposite of `any`). This is the single named domain type for "a row"; nothing
- * in the spine uses a bare `unknown[]`. When the schema engine emits per-model
- * types, `read<T>()` can narrow this to `T` without touching call sites.
+ * 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>;
 /**
- * The result of a {@link Row} read. Two shapes mirror the two request kinds:
- *  - `bootstrap`: full-load — model name → its rows (empty models omitted).
- *  - `query`: a single filtered model query.
+ * 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';
@@ -46,11 +46,12 @@ export type ReadResult = {
     readonly rows: readonly Row[];
 };
 /**
- * Resume position for `sync` — the client's last-seen `sync_deltas` watermark.
- * Deliberately JUST the position: org / syncGroups / maxGap are server-derived
- * and bound onto the adapter at resolve time (a trust boundary — the client
- * never supplies the org it reads). `lastSyncId <= 0` means "no position yet",
- * which `sync` reports as `needsFullRead`.
+ * 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;
@@ -76,14 +77,16 @@ export interface ProposalResult {
     readonly rows?: readonly Row[];
 }
 /**
- * A request for canonical rows. Two shapes:
- *  - `bootstrap`: the full-load reader — give me every (enabled) model's rows.
- *  - `query`: a single filtered model query (the live `/sync/query` path).
+ * 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.
  *
- * The `query` shape keeps the hosted SQL/tenant/RLS execution as a `runHosted`
- * closure (same seam as a commit's `runHosted`): the adapter DISPATCHES — source
- * → the customer's `list`, hosted/selfHosted → run the closure — but the query
- * engine itself stays host-side rather than leaking into the adapter.
+ * 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';
@@ -99,16 +102,15 @@ export type ReadRequest = {
     readonly typename: string;
     readonly query: SourceListQuery;
     readonly scope?: SourceRequestContext;
-    /** Hosted/self-hosted execution (compile + tenant pool + RLS + unpack). */
+    /** Runs the query against a hosted database: compile, take the tenant pool, apply row-level security, unpack the rows. */
     readonly runHosted: () => Promise<Row[]>;
 };
 /**
- * A change to apply to the canonical store. `runHosted` is the pre-bound local
- * mutator execution (the hosted/self-hosted write path lives in the mutator
- * engine above the adapter); the hosted adapter simply runs it, while the source
- * adapter ignores it and ships the operations to the customer endpoint. This is
- * the seam that lets the adapter OWN the mode decision while the heavy mutator
- * logic stays host-side.
+ * 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[];
@@ -126,30 +128,28 @@ export interface SyncResult {
     readonly needsFullRead: boolean;
 }
 /**
- * The ONE interface every storage mode implements — the Better-Auth-style
- * `Adapter` seam. The package owns this contract; a host (today
- * `apps/sync-server`, tomorrow a consumer app) implements it against a real
- * database. Design rule (load-bearing, = Zero's mutator principle): **adapters
- * only guarantee reality access.** `read` fetches canonical rows, `commit`
- * applies a change, `sync` reads the change log; orchestration (proposal,
- * conflict policy) lives ABOVE the adapter. `propose` is a capability, never a
- * required method.
+ * 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 {
-    /** Diagnostic discriminator (≈ Better Auth's `adapterId`). Routing decisions
-     *  go through the resolver/factory, not this. */
+    /** 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<CommitResult>;
     sync(cursor: SyncCursor): Promise<SyncResult>;
 }
-/** An adapter whose backend can dry-run. Narrow to this only after checking the capability. */
+/** 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 (≈ Better Auth's
- *  `createAdapter` factory seam). */
+/** Resolves an authenticated scope to the adapter that serves it. */
 export type AdapterResolver = (scope: {
     readonly projectId: string;
     readonly accountScope?: string;

package/dist/server/adapter.js

@@ -1,19 +1,18 @@
 /**
- * `@abloatai/ablo/server` — the DataAdapter CONTRACT vocabulary.
+ * `@abloatai/ablo/server` — the `DataAdapter` storage contract.
  *
- * This is the Better-Auth-style seam: the package defines the storage
- * interface and its value types; a host (today `apps/sync-server`, tomorrow a
- * consumer's app) implements it against a real database. The reference Postgres
- * implementation (`executeCommit` + `selectAdapter`) stays host-side — it
- * carries a `postgres` driver and raw SQL, which must never enter this
- * browser-shippable package.
+ * 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.
  *
- * Scope note: this file holds the parts of the contract that are PURE — they
- * depend only on primitives and {@link Row}. The full `DataAdapter` interface
- * (and its `sync()` method) references `SyncDelta`, which currently has two
- * definitions (server `db/deltas` vs package `core`) pending unification; the
- * `commit`/`read` request envelopes reference server domain types
- * (`CommitContext`, `BootstrapModel`). Those stay server-local and re-import
- * these primitives until that canonicalization lands.
+ * 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.
  */
 export {};