@abloatai/ablo 0.26.0 → 0.27.0

package/dist/client/identity.d.ts

@@ -1,26 +1,21 @@
 /**
- * Participant identity + scope resolution for `Ablo()`.
+ * Resolves a participant's identity and scope when an {@link Ablo} client is
+ * constructed, following whichever of three authentication paths the caller's
+ * options select:
  *
- * Three branches, mirroring the three auth paths the SDK supports:
+ *   1. **Hosted cloud** — the caller passed an `apiKey`. The client exchanges it
+ *      for a capability token and scope, then starts a scheduler that re-mints the
+ *      token before it expires, so the rotation is invisible to the caller.
+ *   2. **Self-derived** — the caller passed a bearer or capability token but not
+ *      an identity. The client asks the identity endpoint to recover the
+ *      participant id and scope from the token.
+ *   3. **Explicit** — a self-hosted caller passed the organization id and a user
+ *      or agent id directly. No server round-trip; the client trusts the caller.
  *
- *   1. **Hosted-cloud** — caller passed `apiKey`. SDK exchanges it
- *      server-side for a capability token + scope blob, then sets
- *      up a refresh scheduler that re-mints transparently before
- *      expiry.
- *   2. **Self-derived** — caller passed an authToken / capability
- *      token but the SDK doesn't yet know the identity. Calls
- *      `resolveIdentity` against the bootstrap endpoint to recover
- *      `participantId` + scope from the token.
- *   3. **Legacy explicit** — self-hosted callers that pass
- *      `organizationId` + `user.id` (or `agentId`) directly. No
- *      server round-trip; SDK trusts the caller.
- *
- * Extracted from `Ablo.ts` so each branch is testable in isolation
- * and the constructor body reads as a single named call rather than
- * a 100+-line if/elif/else with three different side-effect chains.
+ * Each branch is a separate function below, so it can be read and tested on its own.
  */
 import { type RefreshScheduler } from '../auth/index.js';
-import type { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import type { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import type { SyncLogger } from '../interfaces/index.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { ApiKeySetter } from './auth.js';
@@ -42,7 +37,7 @@ export interface IdentityResolveInput {
     readonly kind: 'user' | 'agent' | 'system';
     readonly configuredApiKey: string | ApiKeySetter | null;
     readonly configuredAuthToken: string | null;
-    readonly bootstrapHelper: BootstrapHelper;
+    readonly bootstrapHelper: BootstrapFetcher;
     readonly auth: AuthCredentialSource;
     readonly logger: SyncLogger;
 }
@@ -53,7 +48,7 @@ export interface ResolvedIdentity {
     readonly capabilityToken: string | undefined;
     readonly syncGroups: readonly string[] | undefined;
     readonly participantKind: 'user' | 'agent' | 'system';
-    /** Non-null on the hosted-cloud path; caller stores it for shutdown. */
+    /** Set only on the hosted-cloud path; the caller keeps it to stop refreshes on shutdown. */
     readonly refreshScheduler: RefreshScheduler | null;
 }
 export declare function resolveParticipantIdentity(input: IdentityResolveInput): Promise<ResolvedIdentity>;

package/dist/client/identity.js

@@ -1,23 +1,18 @@
 /**
- * Participant identity + scope resolution for `Ablo()`.
+ * Resolves a participant's identity and scope when an {@link Ablo} client is
+ * constructed, following whichever of three authentication paths the caller's
+ * options select:
  *
- * Three branches, mirroring the three auth paths the SDK supports:
+ *   1. **Hosted cloud** — the caller passed an `apiKey`. The client exchanges it
+ *      for a capability token and scope, then starts a scheduler that re-mints the
+ *      token before it expires, so the rotation is invisible to the caller.
+ *   2. **Self-derived** — the caller passed a bearer or capability token but not
+ *      an identity. The client asks the identity endpoint to recover the
+ *      participant id and scope from the token.
+ *   3. **Explicit** — a self-hosted caller passed the organization id and a user
+ *      or agent id directly. No server round-trip; the client trusts the caller.
  *
- *   1. **Hosted-cloud** — caller passed `apiKey`. SDK exchanges it
- *      server-side for a capability token + scope blob, then sets
- *      up a refresh scheduler that re-mints transparently before
- *      expiry.
- *   2. **Self-derived** — caller passed an authToken / capability
- *      token but the SDK doesn't yet know the identity. Calls
- *      `resolveIdentity` against the bootstrap endpoint to recover
- *      `participantId` + scope from the token.
- *   3. **Legacy explicit** — self-hosted callers that pass
- *      `organizationId` + `user.id` (or `agentId`) directly. No
- *      server round-trip; SDK trusts the caller.
- *
- * Extracted from `Ablo.ts` so each branch is testable in isolation
- * and the constructor body reads as a single named call rather than
- * a 100+-line if/elif/else with three different side-effect chains.
+ * Each branch is a separate function below, so it can be read and tested on its own.
  */
 import { AbloAuthenticationError } from '../errors.js';
 import { exchangeApiKey } from '../auth/index.js';
@@ -29,22 +24,21 @@ import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './auth.js';
 export async function resolveParticipantIdentity(input) {
     const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, auth, logger, } = input;
     const apiKeyValue = await resolveApiKeyValue(configuredApiKey);
-    // Single source of truth for the http(s) base — coerces ws/wss → http/https
-    // even when `bootstrapBaseUrl` is an explicit override (see auth.ts).
+    // Resolve the http(s) base URL, coercing ws/wss to http/https even when
+    // `bootstrapBaseUrl` is an explicit override (see auth.ts).
     const baseUrl = resolveBootstrapBaseUrl({
         url,
         bootstrapBaseUrl: options.bootstrapBaseUrl,
     });
-    // `internalOptions.organizationId` + a caller-supplied participant id is the
-    // legacy explicit path: the caller already knows its own identity, so no
-    // server round-trip is needed.
+    // An organization id plus a caller-supplied participant id is the explicit path:
+    // the caller already knows its own identity, so no server round-trip is needed.
     const hasExplicitIdentity = internalOptions.organizationId != null &&
         (kind === 'agent' ? options.agentId != null : options.user?.id != null);
-    // The connect-time credential ROUTING decision lives in `credentialPolicy`:
-    // classify the apiKey (sk_/ek_/rk_/pk_) and route. The hosted exchange is the
-    // one mint the policy performs (delegating to the injected `exchangeApiKey`);
-    // every other route just hands back the bearer to use. We then switch on the
-    // resolved `kind` below to wire up scope + the refresh scheduler.
+    // The credential-routing decision lives in `credentialPolicy`: it classifies the
+    // apiKey by prefix (`sk_`/`ek_`/`rk_`/`pk_`) and picks a route. The hosted
+    // exchange is the one mint the policy performs (via the injected
+    // `exchangeApiKey`); every other route simply returns the bearer to use. The
+    // switch below applies scope and sets up the refresh scheduler for each case.
     const cred = await resolveCredential({
         apiKeyValue,
         configuredApiKey,
@@ -68,12 +62,12 @@ export async function resolveParticipantIdentity(input) {
     });
     switch (cred.kind) {
         case 'publishable':
-            // `pk_` — a long-lived, browser-safe, READ-ONLY project key. Used DIRECTLY
-            // as the bearer and NEVER exchanged for a short-lived capability — so it
-            // never expires and there is nothing to refresh. The sync-server's
-            // `apiKeyProvider` resolves the org + read-only scope from the key itself;
-            // we still call `/auth/identity` (authenticated by the `pk_` bearer) to
-            // learn the account scope + syncGroups for the bootstrap cache.
+            // `pk_` is a long-lived, browser-safe, read-only project key. It is used
+            // directly as the bearer and is never exchanged for a short-lived
+            // capability, so it never expires and there is nothing to refresh. The
+            // server resolves the organization and read-only scope from the key itself;
+            // we still call `/auth/identity` with the `pk_` bearer to learn the account
+            // scope and sync groups for the bootstrap cache.
             return resolveViaIdentity({
                 bearer: cred.getBearer,
                 baseUrl,
@@ -105,8 +99,8 @@ export async function resolveParticipantIdentity(input) {
                 auth,
             });
         case 'explicit': {
-            // Legacy explicit (self-hosted, pre-Phase-3 — caller knows its own
-            // organizationId + user/agentId).
+            // Explicit self-hosted identity: the caller supplied its own organization id
+            // and user or agent id.
             const userId = kind === 'agent' ? options.agentId : options.user.id;
             const accountScope = internalOptions.organizationId;
             bootstrapHelper.setCacheScope(accountScope);
@@ -125,24 +119,21 @@ export async function resolveParticipantIdentity(input) {
     }
 }
 /**
- * Shared `/auth/identity` resolution for the `pk_` (publishable) and pre-minted
- * (`ek_`/`rk_` or explicit cap token) routes: the bearer is used as-is, the
- * server resolves the identity, and caller-passed syncGroups are MERGED with the
- * server-resolved set.
+ * Resolves identity through the `/auth/identity` endpoint for the publishable
+ * (`pk_`) and pre-minted (`ek_`/`rk_` or explicit capability token) routes. The
+ * bearer is used as-is, the server resolves the identity, and any caller-passed
+ * sync groups are merged with the server-resolved set.
  */
 async function resolveViaIdentity(input) {
     const { bearer, baseUrl, options, bootstrapHelper, auth } = input;
     const identity = await resolveIdentity({ baseUrl, authToken: bearer });
-    // Merge caller-passed syncGroups with server-resolved ones rather than letting
-    // the server's response silently overwrite. Browser consumers (apps/web's
-    // SyncEngineProvider) compose `['default', 'org:${orgId}', 'user:${userId}',
-    // ...team:]` from the resolved session and pass it via `<AbloProvider
-    // syncGroups>`; before this merge, the self-derived path dropped that set on
-    // the floor in favor of `/auth/identity`'s response, which is empty for
-    // cookie-auth users today (apps/sync-server/src/routes/auth.ts only populates
-    // from `effectiveSyncGroups`, the cap-narrowed list). Empty syncGroups →
-    // server bootstrap falls back to `['default']` → no deltas fan out → live
-    // updates appear only on hard reload.
+    // Merge the caller's sync groups with the server-resolved set rather than
+    // letting the server response overwrite them. A client may compose groups such
+    // as `['default', 'org:<id>', 'user:<id>', 'team:<id>']` from the resolved
+    // session and pass them in; the identity endpoint can return an empty set (for
+    // example, for cookie-authenticated users), and an empty set makes the server
+    // bootstrap fall back to `['default']`, so no deltas fan out and live updates
+    // appear only on a hard reload. Merging keeps the caller's groups intact.
     const callerGroups = options.syncGroups ?? [];
     const mergedSyncGroups = callerGroups.length > 0
         ? [...new Set([...callerGroups, ...identity.syncGroups])]
@@ -161,9 +152,9 @@ async function resolveViaIdentity(input) {
     };
 }
 async function resolveHosted(input) {
-    // Pure managed-cloud shape: `Ablo({schema, apiKey})`. The credential policy
-    // already exchanged the apiKey (delegating to `exchangeApiKey`); here we apply
-    // the returned scope + userMeta and stand up the refresh scheduler.
+    // The managed-cloud shape, `Ablo({ schema, apiKey })`. The credential policy has
+    // already exchanged the apiKey via `exchangeApiKey`; here we apply the returned
+    // scope and set up the refresh scheduler.
     const { exchange } = input.cred;
     const baseUrl = input.baseUrl;
     // The refresh path re-runs `exchangeApiKey` with a freshly-resolved apiKey, so
@@ -179,12 +170,10 @@ async function resolveHosted(input) {
     input.bootstrapHelper.setCacheScope(exchange.scope.organizationId);
     input.bootstrapHelper.setSyncGroups(exchange.scope.syncGroups);
     input.auth.setAuthToken(exchange.token);
-    // Cap tokens have a server-set TTL (3600s by default). Without
-    // proactive refresh the WS would either get force-closed at expiry
-    // or fail its next reconnect with 401. The scheduler re-mints
-    // transparently before that fires; the consumer never sees the
-    // rotation. Rationale + tradeoffs in
-    //   `packages/sync-engine/src/auth/refreshScheduler.ts`
+    // Capability tokens carry a server-set TTL (3600s by default). Without proactive
+    // refresh, the socket would be force-closed at expiry, or the next reconnect
+    // would fail with a 401. The scheduler re-mints ahead of that, so the consumer
+    // never sees the rotation.
     const refreshScheduler = createRefreshScheduler({
         initialExpiresAtMs: Date.parse(exchange.expiresAt),
         refresh: async () => {

package/dist/client/modelRegistration.d.ts

@@ -1,13 +1,9 @@
 /**
- * Schema → Model-class registration — `registerModelsFromSchema` walks the
- * declarative schema and populates the `ModelRegistry`: a dynamic `Model`
- * subclass per model (`createDynamicModelClass`, with `${field}Json` getters,
- * computed getters, and opt-in MobX field observability), property/relation
- * registration, and IDB index selection.
- *
- * Extracted from `Ablo.ts` — the factory calls `registerModelsFromSchema`
- * right after `createInternalComponents` builds the registry. The zod unwrap
- * helpers stay module-local.
+ * Registers model classes from a declarative schema. {@link registerModelsFromSchema}
+ * walks the schema and populates the model registry: for each model it builds a
+ * dynamic {@link Model} subclass (with `${field}Json` getters, computed getters,
+ * and opt-in field-level reactivity) and registers the model's properties,
+ * relations, and any local-database indexes.
  */
 import type { Schema } from '../schema/schema.js';
 import type { ModelRegistry } from '../ModelRegistry.js';

package/dist/client/modelRegistration.js

@@ -1,13 +1,9 @@
 /**
- * Schema → Model-class registration — `registerModelsFromSchema` walks the
- * declarative schema and populates the `ModelRegistry`: a dynamic `Model`
- * subclass per model (`createDynamicModelClass`, with `${field}Json` getters,
- * computed getters, and opt-in MobX field observability), property/relation
- * registration, and IDB index selection.
- *
- * Extracted from `Ablo.ts` — the factory calls `registerModelsFromSchema`
- * right after `createInternalComponents` builds the registry. The zod unwrap
- * helpers stay module-local.
+ * Registers model classes from a declarative schema. {@link registerModelsFromSchema}
+ * walks the schema and populates the model registry: for each model it builds a
+ * dynamic {@link Model} subclass (with `${field}Json` getters, computed getters,
+ * and opt-in field-level reactivity) and registers the model's properties,
+ * relations, and any local-database indexes.
  */
 import { z } from 'zod';
 import { baseFieldsSchema } from '../schema/schema.js';
@@ -32,25 +28,22 @@ export function registerModelsFromSchema(schema, registry) {
         }
         // Create a dynamic Model subclass with JSON sub-property getters.
         //
-        // Field-level MobX observability is ON BY DEFAULT. A reactive read like
-        // `useAblo((a) => a.documents.get(id))` must re-render when a remote delta
-        // mutates the row IN PLACE (the common collaborative case); without
-        // per-field observability that update fires no reaction and the UI silently
-        // goes stale. Models opt OUT with an explicit `lazyObservable: false` —
-        // appropriate only for very large read-only list models where per-field
-        // atoms cost more than the QueryView's entry-replaced reactivity already
-        // provides. json fields register as `observable.ref` (see
-        // `registerModelsFromSchema`), so the default is ~one atom per scalar field
-        // per loaded row — cheap — not a deep atom tree per blob.
+        // Field-level reactivity is on by default. A reactive read must re-render when
+        // a remote delta mutates a row in place, which is the common collaborative
+        // case; without per-field reactivity that update fires no reaction and the UI
+        // silently goes stale. A model opts out with `lazyObservable: false`, which
+        // suits only very large read-only list models where per-field atoms cost more
+        // than the coarser entry-replaced reactivity already provides. JSON fields
+        // register as reference-tracked, so the default is about one atom per scalar
+        // field per loaded row — cheap — not a deep atom tree per blob.
         const isLazy = modelDef.lazyObservable !== false;
         // Base provenance fields (`organizationId`, `createdBy`) live in
-        // `baseFieldsSchema`, not the per-model `shape`. The server stamps + emits
-        // them (camelCased on the wire), but hydration (`Model.assignFieldsFromData`)
-        // only assigns keys that already exist as an own/prototype property — so
-        // without a slot here, `deck.createdBy` / `deck.organizationId` silently read
-        // `undefined` (this is why the profile decks tab showed nothing: it filters
-        // `decks.filter(d => d.createdBy === userId)`). `id`/`createdAt`/`updatedAt`
-        // are already seeded by the base Model constructor, so they're excluded.
+        // `baseFieldsSchema`, not in the per-model `shape`. The server stamps and emits
+        // them (camelCased on the wire), but hydration only assigns keys that already
+        // exist as own or prototype properties — so without a slot here, reads like
+        // `row.createdBy` or `row.organizationId` would silently be `undefined`.
+        // `id`, `createdAt`, and `updatedAt` are already seeded by the base Model
+        // constructor, so they are excluded.
         const fieldNames = [
             ...Object.keys(modelDef.shape),
             ...Object.keys(baseFieldsSchema.shape).filter((f) => f !== 'id' && f !== 'createdAt' && f !== 'updatedAt' && !(f in modelDef.shape)),
@@ -67,18 +60,14 @@ export function registerModelsFromSchema(schema, registry) {
             autoFill: modelDef.autoFill,
             requiredFields: modelDef.requiredFields,
         });
-        // Collect the set of fields that should get an IDB secondary index.
-        //
-        // Matches Linear's opt-in model (see wzhudev/reverse-linear-sync-engine):
-        // `@Reference(..., { indexed: true })`. Only `belongsTo` relations that
-        // explicitly set `{ index: true }` in their options get an IDB secondary
-        // index. Every other FK (and every scalar) is resolved via in-memory
-        // ObjectPool scans, which are fast enough at org-scope sizes (~10k rows)
-        // and reactive via MobX.
+        // Collect the fields that should get a local-database secondary index.
         //
-        // Auto-indexing every belongsTo was wrong: it bloated write amplification
-        // for the vast majority of FKs that are never queried by fk. Indexing
-        // every scalar (like the legacy Go backend did) is even worse.
+        // Only `belongsTo` relations that explicitly set `{ index: true }` are indexed.
+        // Every other foreign key, and every scalar, is resolved by in-memory scans,
+        // which are fast enough at organization-scope sizes (on the order of 10k rows)
+        // and stay reactive. Indexing is opt-in deliberately: auto-indexing every
+        // foreign key inflates write amplification for the many keys never queried by
+        // id, and indexing every scalar is worse still.
         const indexedFields = new Set();
         for (const relDef of Object.values(modelDef.relations)) {
             if (relDef.type === 'belongsTo' && relDef.foreignKey && relDef.options?.index === true) {
@@ -89,16 +78,15 @@ export function registerModelsFromSchema(schema, registry) {
         for (const [fieldName, rawZodType] of Object.entries(modelDef.shape)) {
             const zodType = rawZodType;
             const isOptional = zodType.isOptional?.() ?? false;
-            // A field is indexed if it's the FK of a `belongsTo({ index: true })`
-            // relation. Legacy `description === 'indexed'` still works for
-            // consumers using `field.*().indexed()`.
+            // A field is indexed if it is the foreign key of a
+            // `belongsTo({ index: true })` relation. A `description === 'indexed'` tag
+            // also works, for consumers using the `field.*().indexed()` builder.
             const isIndexed = indexedFields.has(fieldName) || zodType.description === 'indexed';
-            // JSON-typed fields (per the schema's wire-type tag) are opaque
-            // blobs from MobX's perspective — chart specs, ProseMirror docs,
-            // style maps. Deep observability on them recursively walks every
-            // nested property and creates an atom for each leaf, producing a
-            // microtask storm on every commit/streaming update. `ref` tracks
-            // only reassignment, which is how blob consumers actually use them.
+            // JSON-typed fields (per the schema's wire-type tag) are opaque blobs —
+            // chart specs, rich-text documents, style maps. Deep reactivity on them
+            // would walk every nested property and create an atom per leaf, producing a
+            // storm of updates on each commit or streaming change. Reference tracking
+            // watches only reassignment, which is how blob consumers actually use them.
             const wireType = modelDef.fields?.[fieldName]?.type;
             const observability = wireType === 'json' ? 'ref' : undefined;
             registry.registerProperty(modelName, fieldName, {
@@ -185,9 +173,8 @@ function unwrapZodType(schema) {
             continue;
         }
         if (current instanceof z.ZodDefault) {
-            // v4 deprecates removeDefault in favor of unwrap, but the
-            // installed @types declarations only expose removeDefault on
-            // ZodDefault. Use it — it's the same runtime function.
+            // Zod v4 unwraps a default via `.unwrap()`, the same runtime function older
+            // versions exposed as `removeDefault`.
             current = current.unwrap();
             continue;
         }
@@ -209,46 +196,40 @@ function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed,
         _modelName = modelName;
         constructor(data) {
             super(data);
-            // Gate `propertyChanged`-via-`observe` tracking during initial
-            // hydration. M1 installs a MobX `observe()` listener per schema
-            // property that forwards writes to `propertyChanged()` so direct
-            // assignments like `layer.position = newPos` still round-trip
-            // through the transaction queue. During construction we're writing
-            // wire data, NOT user edits — flagging this as "constructing" lets
-            // the listener early-return on those writes so `modifiedProperties`
-            // doesn't get polluted with every field of every hydrated model.
+            // Suppress change tracking during initial hydration. `makeObservable()`
+            // installs a listener per schema property that forwards writes to the
+            // transaction queue, so direct assignments like `row.position = next` still
+            // round-trip. During construction we are writing wire data, not user edits,
+            // so this flag lets that listener skip these writes and keeps the set of
+            // modified properties from filling up with every field of every hydrated row.
             //
-            // The listener is installed by `makeObservable()` below (inside
-            // M1), so writes that happen BEFORE that line won't fire it; this
-            // flag is defensive in case a subclass or call path reorders the
-            // steps later.
+            // The listener is installed by `makeObservable()` below, so writes before
+            // that line never reach it; this flag is defensive in case a subclass or call
+            // path later reorders the steps.
             this._isConstructing = true;
-            // MobX 6 requires fields to exist as own properties BEFORE makeObservable().
-            // Model base only sets id/createdAt/updatedAt. Schema fields (title, userId, etc.)
-            // must be initialized here so M1's annotations can find them.
+            // Reactive fields must exist as own properties before `makeObservable()` runs.
+            // The base Model sets only id, createdAt, and updatedAt, so schema fields
+            // (title, userId, and so on) are initialized here for the annotations to find.
             for (const field of fieldNames) {
                 if (!(field in this)) {
                     this[field] = data?.[field] ?? undefined;
                 }
             }
-            // Per-field MobX observability opt-in via `lazyObservable: true` on
-            // the model definition. Defaults to plain objects — reactivity comes
-            // from the QueryView "entry replaced" pattern, which is cheap for
-            // read-only list UIs but invisible to in-place field mutations.
+            // When field-level reactivity is enabled (the default; a model turns it off
+            // with `lazyObservable: false`), make each field observable. Without it,
+            // reactivity comes only from the coarser entry-replaced pattern, which is
+            // cheap for read-only lists but invisible to in-place field mutations.
             //
-            // Multiplayer editors need live field-level reactivity so remote
-            // deltas AND local drag/resize/rename mutations surface through
-            // `observer()` components without the whole pool entry being
-            // replaced. Without observability, `layer.position.x = 500` emits
-            // nothing and the UI lags until some unrelated state change triggers
-            // a pass (toolbar close, deselect).
+            // Collaborative editors need field-level reactivity so both remote deltas and
+            // local edits surface through observer components without the whole cache
+            // entry being replaced. Otherwise an in-place mutation such as
+            // `row.position.x = 500` emits nothing and the UI lags until an unrelated
+            // change triggers a pass.
             //
-            // Delegates to `Model.makeObservable()` (the inherited method) so
-            // MobX annotations are derived from the same registry that M1 reads.
-            // That means computed getters, reference collections, custom
-            // getters/setters, and property-change tracking all integrate
-            // correctly — reimplementing `makeObservable` inline here would miss
-            // those seams.
+            // This delegates to the inherited `Model.makeObservable()` so the annotations
+            // come from the same registry the rest of the model reads, keeping computed
+            // getters, reference collections, custom getters and setters, and change
+            // tracking all consistent; reimplementing it inline here would miss those.
             if (lazyObservable) {
                 this.makeObservable();
             }
@@ -258,15 +239,14 @@ function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed,
             return this._modelName;
         }
     };
-    // Generate ${field}Json getters for JSON fields with sub-properties.
+    // Generate `${field}Json` getters for JSON fields that have sub-properties.
     //
-    // The getter reads the raw JSON string from the instance (set via
-    // updateFromData), parses it, applies Zod defaults, and caches by
-    // raw value. This replaces the hand-coded metadataObject + sub-property
-    // getter pattern that 11+ Ablo models currently repeat.
+    // Each getter reads the raw JSON from the instance, parses it, applies the
+    // sub-schema's defaults, and caches the result keyed by the raw value.
     //
-    // Example: field named 'metadata' with sub-schema { icon: z.string().default('presentation') }
-    // → model.metadataJson returns { icon: 'presentation', ... } (typed, cached)
+    // Example: a field named `metadata` with sub-schema
+    // `{ icon: z.string().default('presentation') }` yields a `metadataJson` getter
+    // returning `{ icon: 'presentation', ... }` — typed and cached.
     for (const { fieldName, subSchema } of jsonSubFields) {
         const getterName = `${fieldName}Json`;
         const cacheKey = `__${fieldName}JsonCache`;