@abloatai/ablo 0.26.0 → 0.27.0

package/dist/keys/index.d.ts

@@ -1,21 +1,18 @@
 /**
- * Canonical Ablo API-key format — the single source of truth for how keys
- * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
- * and the web control-plane (`generate-key.ts`) consume THIS module, so the
- * format can no longer drift between the two mint sites (it used to live as
- * a hand-copied twin kept in sync by a comment).
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
+ * place so every component that issues or checks a key agrees on the format.
  *
- * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
- * subpath and NEVER re-exported from the browser-facing `.` entry, so the
- * client bundle never pulls in `node:crypto`.
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
+ * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
+ * so a browser bundle never pulls in `node:crypto`.
  *
- * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
- * base62 CRC32 checksum>`. The environment segment is the stable key-prefix
- * contract; parsed values are immediately mapped to `production` / `sandbox`.
- * The identifiable prefix + CRC32 checksum let
- * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
- * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
- * still validate by hash — they parse here as `checksummed: false`.
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
+ * mistyped or forged key locally, without a database round-trip. Older keys
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
+ * and parse here with `checksummed: false`.
  */
 import { z } from 'zod';
 import { type Environment } from '../environment.js';
@@ -35,10 +32,10 @@ export interface ParsedApiKey {
     checksummed: boolean;
 }
 /**
- * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
- * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
- * rejected (the offline-reject), while a legacy key parses as
- * `checksummed: false` and passes (the server still hash-validates it).
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
+ * rejected without any network call; an older key with no checksum parses with
+ * `checksummed: false` and is left for the server to validate by hash.
  */
 export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
 /** Parse + fully validate (incl. checksum). Returns null when invalid. */
@@ -57,21 +54,22 @@ export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
     prefix: string;
 };
 /**
- * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
- * bcrypt) — API keys are high-entropy random, so there's no dictionary to
- * defend against. Used at both write (mint) and lookup.
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
+ * minted and when one is looked up. A fast hash is the right choice here rather
+ * than a password hash like bcrypt: API keys are long random strings, so there is
+ * no dictionary of guesses to slow down.
  */
 export declare function hashApiKey(plaintext: string): string;
 /** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
 export declare const WEBHOOK_SECRET_PREFIX = "whsec_";
 /**
- * Mint a webhook signing secret per the Standard Webhooks spec
- * (https://www.standardwebhooks.com): a base64-encoded random key, 24–64 bytes,
- * labelled with the `whsec_` prefix. We use 32 bytes (256 bits) — comfortably
- * inside the range and matching Stripe/Svix. Unlike an API key this is NOT
- * hashed at rest: signing (`signAbloSourceRequest`) needs the live key, so it is
- * stored by reference via the secret store, returned to the customer once at
- * creation, and never echoed again (Stripe's policy).
+ * Mints a webhook signing secret following the Standard Webhooks specification
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
+ * because signing a request with {@link signAbloSourceRequest} needs the live
+ * value. It is therefore kept in a secret store, returned to the customer once at
+ * creation, and never shown again.
  */
 export declare function generateWebhookSecret(): {
     plaintext: string;

package/dist/keys/index.js

@@ -1,36 +1,36 @@
 /**
- * Canonical Ablo API-key format — the single source of truth for how keys
- * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
- * and the web control-plane (`generate-key.ts`) consume THIS module, so the
- * format can no longer drift between the two mint sites (it used to live as
- * a hand-copied twin kept in sync by a comment).
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
+ * place so every component that issues or checks a key agrees on the format.
  *
- * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
- * subpath and NEVER re-exported from the browser-facing `.` entry, so the
- * client bundle never pulls in `node:crypto`.
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
+ * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
+ * so a browser bundle never pulls in `node:crypto`.
  *
- * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
- * base62 CRC32 checksum>`. The environment segment is the stable key-prefix
- * contract; parsed values are immediately mapped to `production` / `sandbox`.
- * The identifiable prefix + CRC32 checksum let
- * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
- * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
- * still validate by hash — they parse here as `checksummed: false`.
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
+ * mistyped or forged key locally, without a database round-trip. Older keys
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
+ * and parse here with `checksummed: false`.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { z } from 'zod';
 import { ENVIRONMENTS, environmentFromKeyPrefix, environmentToKeyPrefix, } from '../environment.js';
 // ── Vocabulary ──────────────────────────────────────────────────────────
-// The Stripe-style key model:
-//   secret (sk_)      — backend / server-to-server / agents. Full authority. Never in a browser.
-//   restricted (rk_)  — scoped SERVER key (agent session tokens / capabilities).
-//   ephemeral (ek_)   — short-lived, backend-minted, USER-scoped BROWSER session credential
-//                       (Stripe ephemeral keys). Carries participantKind:'user' + baked syncGroups.
-//   publishable (pk_) — long-lived, browser-safe, org-scoped, READ-ONLY project key
-//                       (Stripe `pk_` / Supabase anon key). Used DIRECTLY as the bearer
-//                       (never exchanged, never expires → nothing to refresh). The org owns
-//                       it; it grants read access to the org's data plane and cannot write
-//                       or reach any control-plane operation.
+// The four key kinds:
+//   secret (sk_)      — backend and server-to-server use, including agents. Full
+//                       authority; never expose one in a browser.
+//   restricted (rk_)  — a scoped server key, such as an agent session token or a
+//                       narrowed capability.
+//   ephemeral (ek_)   — a short-lived, backend-minted session credential scoped to
+//                       one user, safe to hand to that user's browser. Carries
+//                       `participantKind: 'user'` and its baked-in sync groups.
+//   publishable (pk_) — a long-lived, browser-safe, organization-scoped read-only
+//                       key. It is used directly as the bearer token — never
+//                       exchanged, never expires, nothing to refresh. It grants
+//                       read access to the organization's data and cannot write or
+//                       reach any control-plane operation.
 export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral', 'publishable'];
 export const API_KEY_ENVS = ENVIRONMENTS;
 const PREFIX_BY_KIND = {
@@ -52,7 +52,7 @@ const KEY_BODY_LEN = 30;
 const CHECKSUM_LEN = 6;
 /** A new checksummed body is exactly this long and pure base62. */
 const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
-/** `<sk|rk|ek|pk>_<live|test>_<body>`; body charset covers base62 AND legacy base64url. */
+/** `<sk|rk|ek|pk>_<live|test>_<body>`; the body charset covers base62 as well as the legacy base64url form. */
 const KEY_RE = /^(sk|rk|ek|pk)_(live|test)_([0-9A-Za-z\-_]+)$/;
 const BASE62_RE = /^[0-9A-Za-z]+$/;
 // ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
@@ -102,10 +102,10 @@ function bodyIsChecksummed(body) {
     return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
 }
 /**
- * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
- * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
- * rejected (the offline-reject), while a legacy key parses as
- * `checksummed: false` and passes (the server still hash-validates it).
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
+ * rejected without any network call; an older key with no checksum parses with
+ * `checksummed: false` and is left for the server to validate by hash.
  */
 export const apiKeySchema = z.string().transform((raw, ctx) => {
     const m = KEY_RE.exec(raw);
@@ -165,9 +165,10 @@ export function generateApiKey(env = 'production', kind = 'secret') {
     return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
 }
 /**
- * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
- * bcrypt) — API keys are high-entropy random, so there's no dictionary to
- * defend against. Used at both write (mint) and lookup.
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
+ * minted and when one is looked up. A fast hash is the right choice here rather
+ * than a password hash like bcrypt: API keys are long random strings, so there is
+ * no dictionary of guesses to slow down.
  */
 export function hashApiKey(plaintext) {
     return createHash('sha256').update(plaintext).digest('hex');
@@ -175,13 +176,13 @@ export function hashApiKey(plaintext) {
 /** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
 export const WEBHOOK_SECRET_PREFIX = 'whsec_';
 /**
- * Mint a webhook signing secret per the Standard Webhooks spec
- * (https://www.standardwebhooks.com): a base64-encoded random key, 24–64 bytes,
- * labelled with the `whsec_` prefix. We use 32 bytes (256 bits) — comfortably
- * inside the range and matching Stripe/Svix. Unlike an API key this is NOT
- * hashed at rest: signing (`signAbloSourceRequest`) needs the live key, so it is
- * stored by reference via the secret store, returned to the customer once at
- * creation, and never echoed again (Stripe's policy).
+ * Mints a webhook signing secret following the Standard Webhooks specification
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
+ * because signing a request with {@link signAbloSourceRequest} needs the live
+ * value. It is therefore kept in a secret store, returned to the customer once at
+ * creation, and never shown again.
  */
 export function generateWebhookSecret() {
     const plaintext = `${WEBHOOK_SECRET_PREFIX}${randomBytes(32).toString('base64')}`;

package/dist/mutators/RecordingTransaction.d.ts

@@ -1,18 +1,18 @@
 /**
- * RecordingTransaction — wraps a base `Transaction` and captures inverse ops
- * for the undo system. Each write is observed BEFORE it runs (to snapshot
- * pre-state) and AFTER (to capture the forward op for redo).
+ * Wraps a {@link Transaction} and records the inverse of every write so the
+ * change can be undone. Each write is observed just before it runs, to snapshot
+ * the previous state, and just after, to record the forward operation for redo.
  *
- * The wrapped mutator sees the exact same `Transaction<S>` shape; recording
- * is invisible. When the mutator returns, the caller reads `getEntry()` and
- * pushes it into the active `UndoScope`.
+ * The mutator sees an ordinary `Transaction<S>` and is unaware it is being
+ * recorded. When the mutator returns, the caller reads
+ * {@link RecordingTransaction.getEntry} and pushes the result onto the active
+ * {@link UndoScope}.
  *
- * Why snapshots live here (not in the UndoScope):
- *   - Update inverse requires `prev` field values — must be captured before
- *     the write lands in the pool.
- *   - Delete inverse requires the full model data — same reason.
- *   - Create inverse is simpler (delete by id) but the id must be known
- *     post-creation (schema generates UUIDs if caller omitted one).
+ * The snapshots are taken here rather than in the undo scope because they must
+ * exist before the write lands: the inverse of an update needs the field's
+ * previous values, and the inverse of a delete needs the full row. The inverse
+ * of a create is just a delete by id, but that id is known only after creation,
+ * since the schema generates one when the caller omits it.
  */
 import type { Schema } from '../schema/schema.js';
 import type { SyncStoreContract } from '../react/context.js';
@@ -28,9 +28,9 @@ export interface RecordingTransaction<S extends Schema> {
     getEntry: (label?: string) => UndoEntry | null;
 }
 /**
- * Build a transaction that records inverses + forwards as it runs.
- * Consumers use this only when they want the invocation to be undoable;
- * read-only or side-effect-only mutators should use `createTransaction`
- * directly to avoid the bookkeeping overhead.
+ * Builds a transaction that records the forward and inverse of each write as it
+ * runs. Use this only when the mutator should be undoable; a read-only or
+ * side-effect-only mutator should call {@link createTransaction} directly to skip
+ * the bookkeeping.
  */
 export declare function createRecordingTransaction<S extends Schema>(schema: S, store: SyncStoreContract, organizationId: string): RecordingTransaction<S>;

package/dist/mutators/RecordingTransaction.js

@@ -1,25 +1,25 @@
 /**
- * RecordingTransaction — wraps a base `Transaction` and captures inverse ops
- * for the undo system. Each write is observed BEFORE it runs (to snapshot
- * pre-state) and AFTER (to capture the forward op for redo).
+ * Wraps a {@link Transaction} and records the inverse of every write so the
+ * change can be undone. Each write is observed just before it runs, to snapshot
+ * the previous state, and just after, to record the forward operation for redo.
  *
- * The wrapped mutator sees the exact same `Transaction<S>` shape; recording
- * is invisible. When the mutator returns, the caller reads `getEntry()` and
- * pushes it into the active `UndoScope`.
+ * The mutator sees an ordinary `Transaction<S>` and is unaware it is being
+ * recorded. When the mutator returns, the caller reads
+ * {@link RecordingTransaction.getEntry} and pushes the result onto the active
+ * {@link UndoScope}.
  *
- * Why snapshots live here (not in the UndoScope):
- *   - Update inverse requires `prev` field values — must be captured before
- *     the write lands in the pool.
- *   - Delete inverse requires the full model data — same reason.
- *   - Create inverse is simpler (delete by id) but the id must be known
- *     post-creation (schema generates UUIDs if caller omitted one).
+ * The snapshots are taken here rather than in the undo scope because they must
+ * exist before the write lands: the inverse of an update needs the field's
+ * previous values, and the inverse of a delete needs the full row. The inverse
+ * of a create is just a delete by id, but that id is known only after creation,
+ * since the schema generates one when the caller omits it.
  */
 import { createTransaction } from './Transaction.js';
 /**
- * Build a transaction that records inverses + forwards as it runs.
- * Consumers use this only when they want the invocation to be undoable;
- * read-only or side-effect-only mutators should use `createTransaction`
- * directly to avoid the bookkeeping overhead.
+ * Builds a transaction that records the forward and inverse of each write as it
+ * runs. Use this only when the mutator should be undoable; a read-only or
+ * side-effect-only mutator should call {@link createTransaction} directly to skip
+ * the bookkeeping.
  */
 export function createRecordingTransaction(schema, store, organizationId) {
     const inverses = [];
@@ -42,8 +42,8 @@ export function createRecordingTransaction(schema, store, organizationId) {
         getEntry: (label) => {
             if (inverses.length === 0)
                 return null;
-            // Undo applies inverses in REVERSE order of how the forward writes ran.
-            // Redo applies forwards in the ORIGINAL order.
+            // Undo applies the inverses in reverse order of the forward writes; redo
+            // applies the forwards in their original order.
             return { label, inverses: [...inverses].reverse(), forwards: [...forwards] };
         },
     };
@@ -54,30 +54,24 @@ function wrapMutateForKey(modelKey, mutate, store, inverses, forwards) {
         const model = store.pool.get(id);
         if (!model)
             return null;
-        // Model.toJSON produces a plain object suitable for re-create. We need
-        // ALL fields when generating a delete→create inverse, so toJSON's
-        // wider shape is exactly right.
+        // toJSON produces a plain object suitable for re-creating the row. The
+        // delete→create inverse needs every field, which is exactly what it returns.
         return model.toJSON();
     };
-    // Before-image for the undo inverse. Delegates to `Model.capturePreviousValues`
-    // — the SINGLE shared implementation (the stream path's
-    // `TransactionQueue.extractPreviousData` calls the same method). `fallbackToLive`
-    // is ON here: the manual-record path wants the live value as a last resort for
-    // a field that was neither pre-mutated nor in the original snapshot. (The
-    // stream path passes `false` so it can omit-and-drop instead — that flag is
-    // the one intentional difference between the two callers.)
+    // Captures the before-image for an undo inverse, delegating to the model's
+    // shared `capturePreviousValues`. `fallbackToLive` is enabled here so that a
+    // field that was neither pre-mutated nor present in the original snapshot falls
+    // back to its current value as a last resort.
     const snapshotFields = (id, fieldNames) => {
         const model = store.pool.get(id);
         if (!model)
             return null;
         return model.capturePreviousValues(fieldNames, { fallbackToLive: true });
     };
-    // After a mutator's `base.update` succeeds, drop the `modifiedProperties`
-    // entries we snapshotted from so the next mutator call sees THIS update's
-    // result as its baseline, not the pre-session old value. The transaction
-    // queue already captured its frozen copy synchronously inside `store.save`,
-    // so this clear is safe for server rollback. Shared with the stream path via
-    // `Model.consumeModifiedFields`.
+    // After an update succeeds, clear the modified-field markers it was snapshotted
+    // from, so the next write to the same row sees this update's result as its
+    // baseline rather than the older pre-update value. The queue has already taken
+    // its own frozen copy, so clearing here is safe.
     const consumeModifiedFields = (id, fieldNames) => {
         store.pool.get(id)?.consumeModifiedFields(fieldNames);
     };
@@ -110,9 +104,9 @@ function wrapMutateForKey(modelKey, mutate, store, inverses, forwards) {
         }),
         update: (async (patch) => {
             if (Array.isArray(patch)) {
-                // Snapshot all previous values BEFORE applying — later patches
-                // in the same list would corrupt the inverse state of earlier
-                // ones if we snapshotted lazily.
+                // Snapshot every row's previous values before applying any patch: later
+                // patches in the same list would corrupt an earlier one's inverse if the
+                // snapshots were taken lazily.
                 const prevPatches = [];
                 for (const p of patch) {
                     const fields = Object.keys(p).filter((k) => k !== 'id');

package/dist/mutators/Transaction.d.ts

@@ -1,35 +1,27 @@
 /**
- * Transaction — Zero-style typed transaction object exposed to custom mutators.
+ * The typed transaction object passed to a custom mutator. A mutator receives
+ * `{ tx, args }` and uses `tx.mutations.<modelKey>.*` to write and
+ * `tx.read.<modelKey>.*` to take synchronous snapshots of the current data.
  *
- * A mutator function receives `{ tx, args }`. Through `tx.mutations.<modelKey>.*`
- * it performs writes; through `tx.read.<modelKey>.*` it takes imperative
- * snapshots of the ObjectPool.
+ * Writes are applied eagerly as they are called, with no buffering: if a mutator
+ * throws partway through, the writes it already made stand. Reads are synchronous
+ * snapshots and use a fast index lookup where one is available for the field.
  *
- * Semantics:
- *   - Writes dispatch eagerly via the existing `createMutateActions` / store
- *     primitives (no buffering, no rollback). Partial state is possible if
- *     a mutator throws midway. Atomic rollback is a follow-up.
- *   - Reads are synchronous snapshots via `createReaderActions`. They use the
- *     FK index fast path where available (O(1) on registered FK fields).
- *
- * The mutate surface is intentionally one-row-at-a-time
- * (`create`/`update`/`delete`). For batches, mutator authors compose
- * `Promise.all(rows.map((r) => tx.mutations.x.create(r)))` — every push
- * stages in the same synchronous tick, the await happens once, and the
- * microtask coalescer in `TransactionQueue` collapses N pushes into one
- * wire commit. Same shape Zero uses: no `insertMany`, just an array map.
+ * The write surface deliberately works one row at a time. To write a batch,
+ * compose the calls yourself — `Promise.all(rows.map((r) => tx.mutations.x.create(r)))`.
+ * Every call stages its write in the same synchronous tick and the engine
+ * coalesces them into a single commit on the wire, so there is no separate
+ * bulk-insert method to learn.
  */
 import type { Schema } from '../schema/schema.js';
 import type { SyncStoreContract } from '../react/context.js';
 import { type MutateActions } from './mutateActions.js';
 import { type ReaderActions, type ReaderFindOptions } from './readerActions.js';
 /**
- * The full transaction surface. `tx.mutations.<key>.*` for writes,
- * `tx.read.<key>.*` for imperative reads. Re-exports the base read options
- * type so mutator authors can type `where` payloads without reaching into
- * the React barrel.
- *
- * The name `mutations` (not `mutate`) matches the React hook naming.
+ * The full transaction surface: `tx.mutations.<key>.*` for writes and
+ * `tx.read.<key>.*` for reads. It also re-exports the read-options type so a
+ * mutator author can type a `where` payload without importing it separately. The
+ * property is named `mutations` to match the corresponding React hook.
  */
 export interface Transaction<S extends Schema> {
     mutations: {
@@ -41,8 +33,8 @@ export interface Transaction<S extends Schema> {
 }
 export type { ReaderFindOptions };
 /**
- * Build a Transaction for a single mutator invocation. The returned object
- * lazily instantiates per-model actions on first access so we don't pay for
- * models the mutator never touches.
+ * Builds a {@link Transaction} for a single mutator invocation. The returned
+ * object creates each model's actions lazily on first access, so a mutator pays
+ * nothing for the models it never touches.
  */
 export declare function createTransaction<S extends Schema>(schema: S, store: SyncStoreContract, organizationId: string): Transaction<S>;

package/dist/mutators/Transaction.js

@@ -1,31 +1,25 @@
 /**
- * Transaction — Zero-style typed transaction object exposed to custom mutators.
+ * The typed transaction object passed to a custom mutator. A mutator receives
+ * `{ tx, args }` and uses `tx.mutations.<modelKey>.*` to write and
+ * `tx.read.<modelKey>.*` to take synchronous snapshots of the current data.
  *
- * A mutator function receives `{ tx, args }`. Through `tx.mutations.<modelKey>.*`
- * it performs writes; through `tx.read.<modelKey>.*` it takes imperative
- * snapshots of the ObjectPool.
+ * Writes are applied eagerly as they are called, with no buffering: if a mutator
+ * throws partway through, the writes it already made stand. Reads are synchronous
+ * snapshots and use a fast index lookup where one is available for the field.
  *
- * Semantics:
- *   - Writes dispatch eagerly via the existing `createMutateActions` / store
- *     primitives (no buffering, no rollback). Partial state is possible if
- *     a mutator throws midway. Atomic rollback is a follow-up.
- *   - Reads are synchronous snapshots via `createReaderActions`. They use the
- *     FK index fast path where available (O(1) on registered FK fields).
- *
- * The mutate surface is intentionally one-row-at-a-time
- * (`create`/`update`/`delete`). For batches, mutator authors compose
- * `Promise.all(rows.map((r) => tx.mutations.x.create(r)))` — every push
- * stages in the same synchronous tick, the await happens once, and the
- * microtask coalescer in `TransactionQueue` collapses N pushes into one
- * wire commit. Same shape Zero uses: no `insertMany`, just an array map.
+ * The write surface deliberately works one row at a time. To write a batch,
+ * compose the calls yourself — `Promise.all(rows.map((r) => tx.mutations.x.create(r)))`.
+ * Every call stages its write in the same synchronous tick and the engine
+ * coalesces them into a single commit on the wire, so there is no separate
+ * bulk-insert method to learn.
  */
 import { createMutateActions } from './mutateActions.js';
 import { createReaderActions } from './readerActions.js';
 import { AbloValidationError } from '../errors.js';
 /**
- * Build a Transaction for a single mutator invocation. The returned object
- * lazily instantiates per-model actions on first access so we don't pay for
- * models the mutator never touches.
+ * Builds a {@link Transaction} for a single mutator invocation. The returned
+ * object creates each model's actions lazily on first access, so a mutator pays
+ * nothing for the models it never touches.
  */
 export function createTransaction(schema, store, organizationId) {
     const mutateCache = new Map();