@abloatai/ablo 0.25.0 → 0.27.0

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,16 +152,17 @@ 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
     // it needs the same argument bag the policy used for the initial exchange.
+    const participantKind = input.kind === 'agent' ? 'agent' : 'system';
     const exchangeArgs = {
         baseUrl,
-        participantKind: (input.kind === 'agent' ? 'agent' : 'system'),
+        participantKind,
         participantId: input.options.agentId ?? input.options.user?.id,
         wideScope: true,
         ttlSeconds: 3600,
@@ -178,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

@@ -0,0 +1,10 @@
+/**
+ * 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';
+export declare function registerModelsFromSchema(schema: Schema, registry: ModelRegistry): void;

package/dist/client/modelRegistration.js

@@ -0,0 +1,301 @@
+/**
+ * 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';
+import { Model } from '../Model.js';
+import { LoadStrategy, PropertyType } from '../types/index.js';
+// ── Auto model registration from schema ───────────────────────────────────
+export function registerModelsFromSchema(schema, registry) {
+    registry.startBatch();
+    for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
+        // Use typename as the model name — this is the wire-format name that
+        // the server sends in bootstrap responses and sync deltas. The pool's
+        // typeIndex, the ModelRegistry, and getModelName() all use this name.
+        // Schema key (camelCase plural) is only for the consumer-facing proxy API.
+        const modelName = modelDef.typename ?? schemaKey;
+        // Collect JSON sub-property fields to generate ${field}Json getters
+        const jsonSubFields = [];
+        for (const [fieldName, zodType] of Object.entries(modelDef.shape)) {
+            const inner = unwrapZodType(zodType);
+            if (isZodObject(inner)) {
+                jsonSubFields.push({ fieldName, subSchema: inner });
+            }
+        }
+        // Create a dynamic Model subclass with JSON sub-property getters.
+        //
+        // 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 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)),
+        ];
+        const computed = modelDef.computed;
+        const DynamicModel = createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, isLazy);
+        // Respect the schema's load strategy so lazy models skip IDB hydration + bootstrap
+        const loadStrategy = modelDef.load === 'lazy' || modelDef.load === 'manual'
+            ? LoadStrategy.lazy
+            : LoadStrategy.instant;
+        registry.registerModel(modelName, DynamicModel, {
+            loadStrategy,
+            fields: modelDef.fields,
+            autoFill: modelDef.autoFill,
+            requiredFields: modelDef.requiredFields,
+        });
+        // Collect the fields that should get a local-database secondary index.
+        //
+        // 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) {
+                indexedFields.add(relDef.foreignKey);
+            }
+        }
+        // Register fields as properties (from Zod shape).
+        for (const [fieldName, rawZodType] of Object.entries(modelDef.shape)) {
+            const zodType = rawZodType;
+            const isOptional = zodType.isOptional?.() ?? false;
+            // 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 —
+            // 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, {
+                type: PropertyType.property,
+                indexed: isIndexed,
+                optional: isOptional,
+                observability,
+            });
+        }
+        // Register relations
+        for (const [relName, relDef] of Object.entries(modelDef.relations)) {
+            if (relDef.type === 'belongsTo') {
+                registry.registerReference(modelName, relName, {
+                    referencedModel: () => {
+                        const targetModel = registry.getModelByName(relDef.target);
+                        return targetModel ?? DynamicModel;
+                    },
+                    indexed: true,
+                });
+            }
+            else if (relDef.type === 'hasMany') {
+                // Generate a getter on the parent model that returns all children
+                // matching the FK via Model.getStore().getByForeignKey(). The FK
+                // index on the target model is registered by deriveSyncPlanFromSchema.
+                const targetName = relDef.target;
+                const foreignKey = relDef.foreignKey;
+                const orderByField = relDef._orderBy;
+                // Resolve the target typename from the schema (might differ from the key)
+                const targetDef = schema.models[targetName];
+                const targetTypename = targetDef?.typename ?? targetName;
+                Object.defineProperty(DynamicModel.prototype, relName, {
+                    get() {
+                        const store = Model.getStore();
+                        if (!store)
+                            return [];
+                        const results = store.getByForeignKey(targetTypename, foreignKey, this.id);
+                        if (orderByField && results.length > 1) {
+                            return [...results].sort((a, b) => {
+                                // `orderByField` is a runtime string from the schema's
+                                // hasMany({ orderBy }) — Models have dynamic typed
+                                // fields produced by createDynamicModelClass, so the
+                                // static type doesn't carry an index signature for
+                                // arbitrary field reads. `Reflect.get` is the typed
+                                // bridge — returns `unknown`, narrowed below.
+                                const va = Reflect.get(a, orderByField);
+                                const vb = Reflect.get(b, orderByField);
+                                if (typeof va === 'number' && typeof vb === 'number')
+                                    return va - vb;
+                                if (typeof va === 'string' && typeof vb === 'string')
+                                    return va.localeCompare(vb);
+                                return 0;
+                            });
+                        }
+                        return results;
+                    },
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+    }
+    registry.endBatch();
+}
+// ── JSON sub-property helpers ─────────────────────────────────────────────
+/**
+ * Unwrap a Zod schema through .optional(), .nullable(), .default(),
+ * .readonly() to find the innermost type. Needed to detect whether a
+ * field.json() call wraps a ZodObject (has sub-properties) or a plain
+ * type (ZodUnknown, ZodArray, etc.).
+ *
+ * Uses Zod's public `.unwrap()` API per wrapper type — no `_def`
+ * digging. Bounded loop guards against pathological self-referential
+ * wrappers.
+ */
+function unwrapZodType(schema) {
+    let current = schema;
+    for (let i = 0; i < 10; i++) {
+        if (current instanceof z.ZodOptional) {
+            current = current.unwrap();
+            continue;
+        }
+        if (current instanceof z.ZodNullable) {
+            current = current.unwrap();
+            continue;
+        }
+        if (current instanceof z.ZodDefault) {
+            // Zod v4 unwraps a default via `.unwrap()`, the same runtime function older
+            // versions exposed as `removeDefault`.
+            current = current.unwrap();
+            continue;
+        }
+        if (current instanceof z.ZodReadonly) {
+            current = current.unwrap();
+            continue;
+        }
+        break;
+    }
+    return current;
+}
+/** Type guard: is this a ZodObject with a .shape property? */
+function isZodObject(schema) {
+    return schema instanceof z.ZodObject;
+}
+/** Create a Model subclass for a schema-defined model */
+function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, lazyObservable = false) {
+    const ModelClass = class extends Model {
+        _modelName = modelName;
+        constructor(data) {
+            super(data);
+            // 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, 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;
+            // 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;
+                }
+            }
+            // 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.
+            //
+            // 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.
+            //
+            // 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();
+            }
+            this._isConstructing = false;
+        }
+        getModelName() {
+            return this._modelName;
+        }
+    };
+    // Generate `${field}Json` getters for JSON fields that have sub-properties.
+    //
+    // 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: 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`;
+        Object.defineProperty(ModelClass.prototype, getterName, {
+            get() {
+                const raw = this[fieldName];
+                // Cache check: same raw value → same parsed result
+                const cache = this[cacheKey];
+                if (cache && cache.raw === raw)
+                    return cache.parsed;
+                // Parse: handle string (from DB/wire), object (already parsed), null/undefined
+                let input;
+                try {
+                    if (typeof raw === 'string') {
+                        input = JSON.parse(raw);
+                    }
+                    else if (raw && typeof raw === 'object') {
+                        input = raw;
+                    }
+                    else {
+                        input = {};
+                    }
+                }
+                catch {
+                    input = {};
+                }
+                // Apply Zod parse for type coercion + defaults. safeParse so
+                // malformed metadata doesn't crash — falls back to all defaults.
+                const result = subSchema.safeParse(input);
+                const parsed = result.success ? result.data : subSchema.safeParse({}).data ?? {};
+                this[cacheKey] = { raw, parsed };
+                return parsed;
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    // Install schema-declared computed getters on the prototype.
+    // Each getter receives `this` (the model instance) and returns the computed value.
+    if (computed) {
+        for (const [name, fn] of Object.entries(computed)) {
+            Object.defineProperty(ModelClass.prototype, name, {
+                get() {
+                    return fn(this);
+                },
+                enumerable: true,
+                configurable: true,
+            });
+        }
+    }
+    return ModelClass;
+}