@abloatai/ablo 0.26.0 → 0.27.0

package/dist/client/resourceTypes.d.ts

@@ -1,14 +1,8 @@
 /**
- * The shared resource-type surface of the client — `ModelRead`, `ModelClient`,
- * the `Commit*` / `Claim*` shapes, the session-mint params/resource, and the
- * `HttpClaimApi` derivation.
- *
- * Extracted from `Ablo.ts` so `ApiClient.ts` / `httpClient.ts` /
- * `sessionMint.ts` can take the wire-facing types WITHOUT importing the
- * factory module that runtime-imports them back (the 4-cycle cluster madge
- * flagged). This module is type-only — ZERO runtime imports — so importing it
- * can never create a cycle. `Ablo.ts` re-exports everything here, so existing
- * import paths keep resolving.
+ * The shared resource types of the client: {@link ModelRead}, {@link ModelClient},
+ * the commit and claim shapes, the session-mint params and resource, and the
+ * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
+ * imports.
  */
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
@@ -19,16 +13,14 @@ import type { Claim, ClaimStream, ClaimWaitOptions, Duration, HeldClaim } from '
 import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
 import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, ServerReadOptions } from './createModelProxy.js';
 /**
- * Operations available on each model in the sync engine.
- *
- * Naming aligns with Stripe / OpenAI / Anthropic conventions:
- *   `retrieve({ id })` — async single-row server read
- *   `list({ where })` — async collection server read
- *   `get(id)` / `getAll(...)` / `getCount(...)` — local graph snapshots
+ * The operations available on each model in the sync engine:
+ *   `retrieve({ id })` — an async single-row server read
+ *   `list({ where })` — an async collection server read
+ *   `get(id)` / `getAll(...)` / `getCount(...)` — synchronous local-cache reads
  *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
- *   `claim({ id })` — durable claim handle for coordinated writes
+ *   `claim({ id })` — a durable claim handle for coordinated writes
  */
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, HeldClaim, ModelOperations, } from './createModelProxy.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelRead<T = Record<string, unknown>> {
@@ -109,12 +101,12 @@ export interface CommitCreateOptions {
     readonly operations?: readonly CommitOperationInput[];
     readonly wait?: CommitWait;
     /**
-     * Batch-level read dependencies (the STORM "did anything I looked at change?"
-     * layer). Declare the rows (`{model,id,readAt,fields?}`) or sync groups
-     * (`{group,readAt}`, e.g. `deck:abc`) this batch was premised on; the server
-     * validates none moved since `readAt` and fires the entry's `onStale` over the
-     * batch. Distinct from the write-target `readAt` — this guards what you READ,
-     * not what you write.
+     * Batch-level read dependencies — the "did anything I looked at change?" guard.
+     * Declare the rows (`{ model, id, readAt, fields? }`) or sync groups
+     * (`{ group, readAt }`, for example `deck:abc`) this batch was premised on; the
+     * server checks that none moved since `readAt` and fires the entry's `onStale`
+     * over the batch. This is distinct from the write-target `readAt`: it guards what
+     * you read, not what you write.
      */
     readonly reads?: readonly ReadDependency[] | null;
 }
@@ -123,19 +115,18 @@ export interface CommitReceipt {
     readonly status: CommitWait;
     readonly lastSyncId?: number;
     /**
-     * Stale-context notifications (notify-instead-of-abort, non-coercion). Present
-     * only when this commit guarded a write with `onStale: 'notify' and
-     * the premise moved concurrently — the conflicting field's current value,
-     * handed back as data instead of a forced `AbloStaleContextError`. The engine
-     * surfaces state; the intelligent actor (agent or human) decides how to
-     * resolve. Also fires on `conflict:notified`.
+     * Stale-context notifications: present only when this commit guarded a write with
+     * `onStale: 'notify'` and the premise moved concurrently. Each carries the
+     * conflicting field's current value, handed back as data rather than raising an
+     * `AbloStaleContextError`, so the caller — an agent or a human — decides how to
+     * resolve it.
      */
     readonly notifications?: readonly StaleNotification[];
     /**
-     * Ids of UPDATE/DELETE targets in this commit that matched ZERO rows (the row
-     * doesn't exist, or is outside the caller's org). Present (non-empty) only
-     * when a write missed. Typed resource wrappers turn this into a loud
-     * `AbloNotFoundError`; a raw `commits.create` caller can inspect it directly.
+     * Ids of update or delete targets in this commit that matched no rows, because
+     * the row does not exist or is outside the caller's organization. Present and
+     * non-empty only when a write missed. The typed resource wrappers turn this into
+     * an `AbloNotFoundError`; a raw `commits.create` caller can inspect it directly.
      */
     readonly missingIds?: readonly string[];
 }
@@ -158,20 +149,20 @@ export interface ModelMutationOptions extends ClaimedOptions {
     readonly claim?: Claim | ClaimOptions | null;
 }
 /**
- * The HTTP/stateless claim surface. Normal tools usually put `claim` directly
- * on the write (`update({ id, data, claim })`) and let the SDK release it. Use
- * this namespace for multi-step handles and coordination screens.
+ * The stateless HTTP claim surface. Most code puts a `claim` directly on the write
+ * (`update({ id, data, claim })`) and lets the SDK release it; reach for this
+ * namespace for multi-step handles and coordination screens.
  *
- * Same surface as the reactive {@link ClaimApi}, but every read is a server
- * round-trip, so `state`/`queue`/`reorder` are **awaited** here (the WebSocket
- * client resolves them synchronously from its local pool — which is what lets
- * `useAblo((ablo) => ablo.x.claim.state({ id }))` work inside a React render; a
- * stateless client has no pool to read, so the `Promise` is unavoidable).
+ * It is the same surface as the reactive claim API, but because every read is a
+ * server round-trip, `state`, `queue`, and `reorder` are awaited here. The
+ * WebSocket client resolves those synchronously from its local cache, which is what
+ * lets it read a claim's state inside a React render; a stateless client has no
+ * cache to read, so the promise is unavoidable.
  *
- * Mechanically DERIVED from `ClaimReadApi` via {@link AwaitedClaimMethod} so the
- * two transports can never drift: the ONLY difference is the uniform `Promise`
- * wrapper that statelessness forces. `claim({ id })` is identical (already async
- * on both); `state`/`queue`/`reorder`/`release` are the awaited form.
+ * It is derived from `ClaimReadApi` through {@link AwaitedClaimMethod} so the two
+ * transports cannot drift: the only difference is the promise wrapper that
+ * statelessness forces. `claim({ id })` is identical on both (already async);
+ * `state`, `queue`, `reorder`, and `release` are the awaited form.
  */
 export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<HeldClaim<T>>) & {
     [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
@@ -183,7 +174,7 @@ export interface ModelClient<T = Record<string, unknown>> {
      * guards on the following write) and any active `.claims`. A stateless HTTP
      * client can't synthesize the watermark from a local snapshot, so the
      * envelope is load-bearing here (the WebSocket client's `retrieve` returns
-     * `T | undefined` because it reads from the hydrated pool).
+     * `T | undefined` because it reads from its local cache).
      *
      * ```ts
      * const deal = await ablo.deals.retrieve({ id });
@@ -201,10 +192,10 @@ export interface ModelClient<T = Record<string, unknown>> {
      */
     list?(options?: ServerReadOptions<T>): Promise<T[]>;
     /**
-     * Create a row and return it — the confirmed, authoritative server row (with
-     * framework defaults like `createdAt`/`createdBy`), mirroring the WebSocket
-     * client's `create`. A re-create of an existing caller-supplied id is
-     * idempotent and returns the EXISTING row, not the input.
+     * Creates a row and returns the confirmed server row, including framework
+     * defaults such as `createdAt` and `createdBy`. Matches the stateful client's
+     * `create`. Passing an id that already exists is idempotent: the existing row is
+     * returned, not the input.
      */
     create(params: ModelMutationOptions & {
         readonly data: Record<string, unknown>;
@@ -238,27 +229,26 @@ export interface ModelClient<T = Record<string, unknown>> {
 }
 /** A single data operation a scoped **agent** session may perform on a model. */
 export type SessionOperation = 'read' | 'create' | 'update' | 'delete';
-/** Mint params for an **end-user** session — full data authority within the
- *  org (the Stripe `ephemeralKeys.create` / Supabase session shape). Mints an
- *  `ek_` token. `user.id` is your end user's external IdP id (becomes the
- *  session's `participantId`); Ablo does not model your users, so it's an
- *  honest string at the trust boundary. */
+/** Parameters for minting an end-user session — full data authority within the
+ *  organization. Mints an `ek_` token. `user.id` is your end user's id from your
+ *  own identity provider and becomes the session's `participantId`; Ablo does not
+ *  model your users, so it is treated as an opaque string at the trust boundary. */
 export interface CreateUserSessionParams {
     /** Your end user. `id` becomes the token's `participantId`. */
     user: {
         id: string;
     };
-    /** Mint the session into THIS organization instead of the key's own org — the
-     *  Stripe Connect `Stripe-Account` pattern, for a platform serving many tenants
-     *  from one backend. Requires the `sk_` to carry the `ephemeral:mint-any-org`
-     *  scope; omit for the normal single-tenant case. */
+    /** Mint the session into this organization instead of the key's own — for a
+     *  platform that serves many tenants from one backend. Requires the `sk_` key to
+     *  carry the `ephemeral:mint-any-org` scope; omit it for the normal
+     *  single-tenant case. */
     organizationId?: string;
     /** Sync groups this session may subscribe to — typed (`'default'` or
      *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
      *  `@abloatai/ablo/schema`). Omit for the server default:
      *  `[org:<your org>, user:<user.id>]`. */
     syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
     ttlSeconds?: number;
     /** Opaque identity blob echoed back to the client as `ablo.user`. */
     userMeta?: Record<string, unknown>;
@@ -281,7 +271,7 @@ export interface CreateAgentSessionParams<S extends SchemaRecord> {
      *  `@abloatai/ablo/schema`). Omit for the server default: the org
      *  anchor (`org:<your org>`) + the agent's own anchor. */
     syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
     ttlSeconds?: number;
     /** Opaque identity blob echoed back to the client as `ablo.agent`. */
     userMeta?: Record<string, unknown>;
@@ -296,15 +286,15 @@ export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParam
  *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
  *  client rather than a raw token. */
 export interface CreateAgentClientParams<S extends SchemaRecord> {
-    /** Wire participant identity (`agent:<id>`) — what claim exclusion and the
-     *  FIFO queue gate on. OMIT to get a fresh `crypto.randomUUID()`: a distinct,
-     *  independent participant (the default, and what you want for concurrent
-     *  agents). Pass a STABLE string only when one logical agent must re-attach
-     *  to its own held claims across reconnects/restarts. */
+    /** The wire participant identity (`agent:<id>`) that claim exclusion and the
+     *  FIFO queue gate on. Omit it to get a fresh random id — a distinct, independent
+     *  participant, which is the default and what you want for concurrent agents.
+     *  Pass a stable string only when one logical agent must re-attach to its own
+     *  held claims across reconnects or restarts. */
     id?: string;
-    /** Human-readable label for logs / attribution (carried in `userMeta.name`).
-     *  INDEPENDENT of `id`: two agents that share a `name` still receive distinct
-     *  ids and coordinate as SEPARATE participants — `name` never derives or
+    /** A human-readable label for logs and attribution (carried in `userMeta.name`).
+     *  It is independent of `id`: two agents that share a `name` still receive
+     *  distinct ids and coordinate as separate participants — `name` never derives or
      *  collapses identity. */
     name?: string;
     /** Per-model operation allowlist, typed against the schema's model names. */
@@ -313,16 +303,15 @@ export interface CreateAgentClientParams<S extends SchemaRecord> {
      *  `<namespace>:<id>`). Omit for the server default (org anchor + the
      *  agent's own anchor). */
     syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15m); the returned client
-     *  auto-re-mints before expiry, so a long-running agent never handles
-     *  rotation itself. */
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes); the returned client
+     *  re-mints before expiry, so a long-running agent never handles rotation
+     *  itself. */
     ttlSeconds?: number;
     /** Extra opaque identity blob echoed on the session scope. Merged with
      *  `name` (the `name` param wins if you also set `userMeta.name`). */
     userMeta?: Record<string, unknown>;
 }
-/** A minted session token — the Stripe ephemeral-key / Supabase session
- *  resource. `token` is the secret the holder presents as its bearer. */
+/** A minted session. `token` is the secret the holder presents as its bearer. */
 export interface AbloSession {
     object: 'session';
     /** Stable id of the minted credential (for revocation). */

package/dist/client/resourceTypes.js

@@ -1,13 +1,7 @@
 /**
- * The shared resource-type surface of the client — `ModelRead`, `ModelClient`,
- * the `Commit*` / `Claim*` shapes, the session-mint params/resource, and the
- * `HttpClaimApi` derivation.
- *
- * Extracted from `Ablo.ts` so `ApiClient.ts` / `httpClient.ts` /
- * `sessionMint.ts` can take the wire-facing types WITHOUT importing the
- * factory module that runtime-imports them back (the 4-cycle cluster madge
- * flagged). This module is type-only — ZERO runtime imports — so importing it
- * can never create a cycle. `Ablo.ts` re-exports everything here, so existing
- * import paths keep resolving.
+ * The shared resource types of the client: {@link ModelRead}, {@link ModelClient},
+ * the commit and claim shapes, the session-mint params and resource, and the
+ * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
+ * imports.
  */
 export {};

package/dist/client/schemaConfig.d.ts

@@ -1,56 +1,44 @@
 /**
- * Schema-derived engine config — `computeFKDepthPriority` (the Tarjan-SCC
- * create-order derivation) and `deriveConfigFromSchema` (the `SyncEngineConfig`
- * the factory seeds the DI context with).
- *
- * Extracted from `Ablo.ts` as a pure leaf: both functions are deterministic
- * schema → value derivations with no engine state.
+ * Derives engine configuration from a schema. This module holds two pure
+ * functions: {@link computeFKDepthPriority} works out a safe row-insertion
+ * order from the schema's foreign-key relations, and
+ * {@link deriveConfigFromSchema} packages that ordering, together with a few
+ * defaults, into the {@link SyncEngineConfig} a client uses at startup. Both
+ * are deterministic transforms of the schema and hold no engine state.
  */
 import type { Schema } from '../schema/schema.js';
 import type { SyncEngineConfig } from '../interfaces/index.js';
 /**
- * Compute a create-priority map from schema `belongsTo` relations using
- * Tarjan's strongly-connected-components algorithm.
- *
- * The FK graph has an edge `child → parent` for every `belongsTo`. Tarjan
- * runs a single linear DFS that simultaneously (a) detects cycles by
- * grouping mutually-reachable nodes into SCCs and (b) emits those SCCs
- * in reverse topological order of the condensation graph. In this edge
- * convention a "sink" SCC has no outgoing edges — i.e. no parents — so
- * it is an *FK root* (`organizations`, `themes`, etc.). Tarjan emits
- * roots first and leaves last, exactly the order in which rows must be
- * inserted to satisfy FK constraints.
- *
- * Priorities are assigned by emit order: SCC #0 → 10, SCC #1 → 20, …
- * Members of the same SCC share a priority, so insertion order wins the
- * tiebreak inside a cycle (this matters for cyclic schemas like
- * `slideDecks ↔ layouts`, where one direction is the user's chosen
- * "soft" edge — only the consumer's mutator sequence knows which one).
+ * Computes a create-priority map that gives the engine a safe order for
+ * inserting rows, so a child row is never written before the parent its
+ * foreign key references.
  *
- * This algorithm is iteration-order-independent: starting the DFS from
- * any node yields the same SCC partitioning, and SCCs always come out
- * in valid topological order. The previous DFS-with-memoization
- * heuristic broke under cycles by treating the back-edge as depth 0,
- * which made priorities depend on which node the walk happened to
- * enter the cycle at.
+ * Every `belongsTo` relation is an edge from a child model to its parent. This
+ * function runs Tarjan's strongly-connected-components algorithm over that
+ * graph, which does two things at once: it groups any models that reference
+ * each other in a cycle into a single component, and it produces those
+ * components in an order where parents come before children. Each model then
+ * gets a numeric priority from that order, where a lower number means "insert
+ * earlier". Top-level models with no parent — an organization or a theme, say —
+ * come first, and the deepest descendants come last.
  *
- * Schema authors can mark one side of a cycle with
- * `belongsTo(target, fk, { defer: true })`. Those edges are excluded
- * from the dependency graph entirely, which deterministically breaks
- * the cycle and turns the SCC into a chain — the marked child gets a
- * strictly higher priority than its parent instead of being tied with
- * it. Pair with a Postgres `DEFERRABLE INITIALLY DEFERRED` constraint
- * if you want the database side of the cycle to also relax. See
- * {@link BelongsToOptions.defer}.
+ * Models in the same cycle share a priority, so within a cycle the order rows
+ * were queued in breaks the tie. To break a cycle deterministically instead,
+ * mark one side of it with `belongsTo(target, fk, { defer: true })`. A deferred
+ * edge is left out of the graph, which turns the cycle into a chain and gives
+ * the deferred child a strictly higher priority than its parent. Pair it with a
+ * Postgres `DEFERRABLE INITIALLY DEFERRED` constraint if you also want the
+ * database to relax its check. See {@link BelongsToOptions.defer}.
  *
- * The returned map is keyed by {@link ModelDef.typename} (falling back
- * to the schema key), because that is what `Model.getModelName()`
- * returns at transaction time — keying by schema key would silently
- * miss the lookup and every model would fall through to
- * `defaultCreatePriority`.
+ * The returned map is keyed by each model's wire type name
+ * ({@link ModelDef.typename}, falling back to the schema key), because that is
+ * the name the engine looks up at commit time. Keying by the schema key would
+ * miss that lookup, and every model would fall back to the default priority.
  *
+ * The result does not depend on which model the walk starts from, and the
+ * algorithm runs in time linear in the number of models plus relations.
  * Reference: Tarjan, R. (1972), "Depth-first search and linear graph
- * algorithms." Linear in V + E.
+ * algorithms."
  */
 export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<string, number>;
 export declare function deriveConfigFromSchema(schema: Schema): SyncEngineConfig;

package/dist/client/schemaConfig.js

@@ -1,56 +1,44 @@
 /**
- * Schema-derived engine config — `computeFKDepthPriority` (the Tarjan-SCC
- * create-order derivation) and `deriveConfigFromSchema` (the `SyncEngineConfig`
- * the factory seeds the DI context with).
- *
- * Extracted from `Ablo.ts` as a pure leaf: both functions are deterministic
- * schema → value derivations with no engine state.
+ * Derives engine configuration from a schema. This module holds two pure
+ * functions: {@link computeFKDepthPriority} works out a safe row-insertion
+ * order from the schema's foreign-key relations, and
+ * {@link deriveConfigFromSchema} packages that ordering, together with a few
+ * defaults, into the {@link SyncEngineConfig} a client uses at startup. Both
+ * are deterministic transforms of the schema and hold no engine state.
  */
 import { schemaHash } from '../schema/serialize.js';
 // ── Config derivation from schema ─────────────────────────────────────────
 /**
- * Compute a create-priority map from schema `belongsTo` relations using
- * Tarjan's strongly-connected-components algorithm.
- *
- * The FK graph has an edge `child → parent` for every `belongsTo`. Tarjan
- * runs a single linear DFS that simultaneously (a) detects cycles by
- * grouping mutually-reachable nodes into SCCs and (b) emits those SCCs
- * in reverse topological order of the condensation graph. In this edge
- * convention a "sink" SCC has no outgoing edges — i.e. no parents — so
- * it is an *FK root* (`organizations`, `themes`, etc.). Tarjan emits
- * roots first and leaves last, exactly the order in which rows must be
- * inserted to satisfy FK constraints.
- *
- * Priorities are assigned by emit order: SCC #0 → 10, SCC #1 → 20, …
- * Members of the same SCC share a priority, so insertion order wins the
- * tiebreak inside a cycle (this matters for cyclic schemas like
- * `slideDecks ↔ layouts`, where one direction is the user's chosen
- * "soft" edge — only the consumer's mutator sequence knows which one).
+ * Computes a create-priority map that gives the engine a safe order for
+ * inserting rows, so a child row is never written before the parent its
+ * foreign key references.
  *
- * This algorithm is iteration-order-independent: starting the DFS from
- * any node yields the same SCC partitioning, and SCCs always come out
- * in valid topological order. The previous DFS-with-memoization
- * heuristic broke under cycles by treating the back-edge as depth 0,
- * which made priorities depend on which node the walk happened to
- * enter the cycle at.
+ * Every `belongsTo` relation is an edge from a child model to its parent. This
+ * function runs Tarjan's strongly-connected-components algorithm over that
+ * graph, which does two things at once: it groups any models that reference
+ * each other in a cycle into a single component, and it produces those
+ * components in an order where parents come before children. Each model then
+ * gets a numeric priority from that order, where a lower number means "insert
+ * earlier". Top-level models with no parent — an organization or a theme, say —
+ * come first, and the deepest descendants come last.
  *
- * Schema authors can mark one side of a cycle with
- * `belongsTo(target, fk, { defer: true })`. Those edges are excluded
- * from the dependency graph entirely, which deterministically breaks
- * the cycle and turns the SCC into a chain — the marked child gets a
- * strictly higher priority than its parent instead of being tied with
- * it. Pair with a Postgres `DEFERRABLE INITIALLY DEFERRED` constraint
- * if you want the database side of the cycle to also relax. See
- * {@link BelongsToOptions.defer}.
+ * Models in the same cycle share a priority, so within a cycle the order rows
+ * were queued in breaks the tie. To break a cycle deterministically instead,
+ * mark one side of it with `belongsTo(target, fk, { defer: true })`. A deferred
+ * edge is left out of the graph, which turns the cycle into a chain and gives
+ * the deferred child a strictly higher priority than its parent. Pair it with a
+ * Postgres `DEFERRABLE INITIALLY DEFERRED` constraint if you also want the
+ * database to relax its check. See {@link BelongsToOptions.defer}.
  *
- * The returned map is keyed by {@link ModelDef.typename} (falling back
- * to the schema key), because that is what `Model.getModelName()`
- * returns at transaction time — keying by schema key would silently
- * miss the lookup and every model would fall through to
- * `defaultCreatePriority`.
+ * The returned map is keyed by each model's wire type name
+ * ({@link ModelDef.typename}, falling back to the schema key), because that is
+ * the name the engine looks up at commit time. Keying by the schema key would
+ * miss that lookup, and every model would fall back to the default priority.
  *
+ * The result does not depend on which model the walk starts from, and the
+ * algorithm runs in time linear in the number of models plus relations.
  * Reference: Tarjan, R. (1972), "Depth-first search and linear graph
- * algorithms." Linear in V + E.
+ * algorithms."
  */
 export function computeFKDepthPriority(schema) {
     // schemaKey → typename (wire name used at transaction time)
@@ -170,19 +158,19 @@ export function computeFKDepthPriority(schema) {
     return out;
 }
 export function deriveConfigFromSchema(schema) {
-    // Commit payload projection is done directly inside `TransactionQueue`
-    // — see `projectCommitPayload` there. Each model's field metadata
-    // rides on `ModelRegistry` (populated by `registerModelsFromSchema`),
-    // so there's no config-layer shim: the queue asks the registry for
-    // the declared fields and serializes accordingly.
+    // Field-level serialization for commits happens in the transaction queue,
+    // which reads each model's declared fields from the model registry at commit
+    // time. There is no per-field metadata to configure here, so these maps stay
+    // empty.
     return {
         modelCreatePriority: computeFKDepthPriority(schema),
         defaultCreatePriority: 40,
         defaultNonCreatePriority: 50,
         essentialFields: {},
         classNameFallbackMap: {},
-        // Hash this client's schema once so bootstrap can detect drift against the
-        // server's active hash (same `schemaHash` the CLI push + server compute).
+        // Hash this schema once, so startup can detect when it has drifted from the
+        // schema the server currently has active. The server and the `ablo push`
+        // command compute this same hash.
         expectedSchemaHash: schemaHash(schema),
     };
 }

package/dist/client/sessionMint.d.ts

@@ -1,25 +1,29 @@
 import type { SchemaRecord } from '../schema/schema.js';
 import type { AbloSession, CreateSessionParams } from './resourceTypes.js';
-/** The resolved control-plane context a mint needs. `fetch` is optional — the
- *  auth helpers fall back to the runtime global when omitted. */
+/**
+ * The resolved control-plane details a mint needs: a secret key, a base URL,
+ * and an optional `fetch`. When `fetch` is omitted, the auth helpers fall back
+ * to the runtime's global `fetch`.
+ */
 export interface MintSessionContext {
     readonly apiKey: string;
     readonly baseUrl: string;
     readonly fetch?: typeof fetch;
     /**
-     * Schema-key → wire typename map, supplied ONLY by the schema client
-     * (`Ablo`). A capability is scoped by the lowercased TYPENAME the Hub
-     * checks, but `can` is keyed by schema key — so `can: { documents: ['update'] }`
-     * on a model whose `typename` is overridden to `Document` must mint
-     * `document.update`, not `documents.update` (else the Hub denies it with
-     * `capability_scope_denied`). The schemaless `ApiClient` omits this map:
-     * there the `can` key already IS the wire token, so no translation applies.
+     * Maps each schema key to its wire type name. Only the schema-aware client
+     * supplies this. A capability is scoped by the lowercased type name the
+     * server checks, but `can` is keyed by schema key — so
+     * `can: { documents: ['update'] }` on a model whose type name is overridden
+     * to `Document` must mint `document.update`, not `documents.update`, or the
+     * server denies the write with `capability_scope_denied`. The schemaless
+     * client omits this map, because there the `can` key is already the wire
+     * token and needs no translation.
      */
     readonly modelTypenames?: Readonly<Record<string, string>>;
 }
 /**
- * Mint a session token from an already-resolved `sk_` credential + base URL.
- * Discriminates the `{ user }` / `{ agent }` union onto the server's two mint
- * doors and reshapes each flat response into the `AbloSession` resource.
+ * Mints a session token from an already-resolved secret key and base URL.
+ * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
+ * and reshapes the response into an {@link AbloSession}.
  */
 export declare function mintSession<S extends SchemaRecord>(params: CreateSessionParams<S>, ctx: MintSessionContext): Promise<AbloSession>;

package/dist/client/sessionMint.js

@@ -1,37 +1,32 @@
 /**
- * `mintSession` — the ONE implementation behind `sessions.create`, shared by the
- * stateful `Ablo` client and the stateless protocol / HTTP client so the two can
- * never drift on HOW a token is minted.
+ * Mints a session token. This is the single implementation behind
+ * `sessions.create`, shared by the schema-aware client and the schemaless HTTP
+ * client so the two never disagree on how a token is produced.
  *
- * Minting is a pure control-plane HTTP call (no socket, no synced pool): a backend
- * holding a secret `sk_` exchanges it for a short-lived scoped token — `ek_` for an
- * `{ user }` session (full end-user authority) or `rk_` for an `{ agent }` session
- * (scoped to exactly the operations named in `can`). The two arms map to the
- * server's two mint doors:
+ * Minting is a plain control-plane HTTP call — no socket, no synced data. A
+ * backend holding a secret key (`sk_`) exchanges it for a short-lived, scoped
+ * token whose kind depends on the session requested:
  *
- *   `{ user }`  → POST /auth/ephemeral-keys → `ek_`. The user-session door;
- *                 routing this arm through /auth/capability is structurally
- *                 impossible — that route rejects participantKind 'user' outright
- *                 (`invalid_participant_kind`, the 2026-06-11 Pulse cascade where
- *                 the SDK's own blessed pattern 403'd and integrators fell back to
- *                 minting humans as agents).
- *   `{ agent }` → POST /auth/capability → scoped `rk_`. `can: { tasks: ['update'] }`
- *                 serializes to the wire allowlist (`tasks.update`); the Hub matches
- *                 it against every registered alias of the model.
+ *   `{ user }`  → POST /auth/ephemeral-keys, returning an `ek_` key that carries
+ *                 full end-user authority. This is the only route that mints a
+ *                 user session; the capability route rejects a `user`
+ *                 participant with `invalid_participant_kind`.
+ *   `{ agent }` → POST /auth/capability, returning an `rk_` key scoped to exactly
+ *                 the operations named in `can`. For example
+ *                 `can: { tasks: ['update'] }` becomes the wire allowlist entry
+ *                 `tasks.update`, which the server matches against the model's
+ *                 registered names.
  *
- * The caller supplies the resolved control-plane credential + base URL in `ctx`;
- * WHICH key to use (the original `sk_`, never a derived `rk_` the startup exchange
- * may have installed) is the caller's concern — see the two call sites.
- *
- * Type-only imports of `CreateSessionParams` / `AbloSession` keep this module a
- * leaf (no runtime cycle back to `Ablo.ts`): at runtime it depends on `auth` +
- * `schema` only.
+ * The caller supplies the already-resolved secret key and base URL in
+ * {@link MintSessionContext}. Choosing which key to pass — the original secret
+ * key, not a derived key that an earlier exchange may have produced — is the
+ * caller's responsibility.
  */
 import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
 /**
- * Mint a session token from an already-resolved `sk_` credential + base URL.
- * Discriminates the `{ user }` / `{ agent }` union onto the server's two mint
- * doors and reshapes each flat response into the `AbloSession` resource.
+ * Mints a session token from an already-resolved secret key and base URL.
+ * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
+ * and reshapes the response into an {@link AbloSession}.
  */
 export async function mintSession(params, ctx) {
     const { apiKey, baseUrl } = ctx;
@@ -64,10 +59,10 @@ export async function mintSession(params, ctx) {
         };
     }
     const operations = Object.entries(params.can).flatMap(([model, ops]) => {
-        // Translate the schema key the developer used in `can` to the wire
-        // typename the Hub gates on — see `modelTypenames` above. Falls back to
-        // the key when no map is supplied (schemaless client) or the key isn't
-        // in it, preserving the prior behaviour exactly for those callers.
+        // Translate the schema key the developer used in `can` into the wire type
+        // name the server checks — see `modelTypenames` above. Falls back to the
+        // key itself when no map is supplied (the schemaless client) or the key is
+        // absent from it.
         const ns = ctx.modelTypenames?.[model] ?? model;
         return (ops ?? []).map((op) => `${ns.toLowerCase()}.${op}`);
     });