@abloatai/humans 0.59.2 → 0.61.0

package/dist/local/client/reactiveEngine.js

@@ -2,9 +2,9 @@
  * The reactive engine assembly (ADR 0016). `Ablo({ ... })` resolves auth and
  * capabilities; `humans().init` constructs the store cluster; the lifecycle
  * — first mint, identity, ready() — lives in `./storeLifecycle.ts`. What
- * remains here is assembly around those parts: the claim stream and
- * participant manager, options validation, the typed model proxies, and the
- * commit/claim/session resources — composed into the reactive client.
+ * remains here is assembly around those parts: the claim and presence streams,
+ * options validation, the typed model proxies, and the
+ * commit and claim resources — composed into the reactive client.
  *
  * Extracted from the factory so the composition root stays a root: resolve,
  * dispatch, return. The remaining assembly converts to decoration of a
@@ -13,17 +13,13 @@
  */
 import { omittedModelError } from '@abloatai/transaction/schema/select';
 import { durableCommitOperationSchema, } from '@abloatai/transaction/commit';
-import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError } from '@abloatai/transaction/errors';
+import { AbloConnectionError, AbloValidationError, claimedError } from '@abloatai/transaction/errors';
 import { batchFence, claimIdFor, fenceTokenFor, modelTarget, streamTarget, subTarget, } from '@abloatai/transaction/coordination';
 import { validateAbloOptions } from './validateAbloOptions.js';
-import { mintSession } from '@abloatai/transaction/auth/sessionMint';
-import { revokeCapability, rotateCapability, } from '@abloatai/transaction/auth/capabilityLifecycle';
-import { modelWireNames } from '@abloatai/transaction/auth/capability';
 import { startStoreLifecycle } from './storeLifecycle.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
 import { awaitClaimGrant } from '@abloatai/transaction/claims';
 import { bindClaimLifetime, claimLifetimeOf, } from '@abloatai/transaction/claims/lifetime';
-import { createParticipantManager } from '../sync/participants.js';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
 import { claimAttemptFailure, emitClaimStatus, } from '@abloatai/transaction/client/resources/modelOperations';
 import { createModelOperations } from './createModelOperations.js';
@@ -33,7 +29,7 @@ import { translateHttpError, } from '@abloatai/transaction/errors';
 import { kReadEvidence, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
 import { contextOnChange } from '../sync/contextOnChange.js';
 export function buildReactiveEngine(inputs) {
-    const { options, internalOptions, url, logger, configuredApiKey, configuredAuthToken, credentialResolver, authCredentials, transport, participantId, kind, presence, cluster, createSibling, } = inputs;
+    const { options, internalOptions, url, logger, configuredApiKey, configuredAuthToken, credentialResolver, authCredentials, transport, participantId, kind, presence, cluster, } = inputs;
     const schema = options.schema;
     const pointReadBaseUrl = resolveBootstrapBaseUrl({
         url,
@@ -109,7 +105,7 @@ export function buildReactiveEngine(inputs) {
     if (configuredApiKey && (internalOptions.kind || internalOptions.agentId)) {
         logger.warn('Ablo: `kind` / `agentId` are ignored when an `apiKey` is configured — ' +
             'the server derives participant identity from the key’s scope. Remove ' +
-            'them (or mint a scoped session via `ablo.sessions.create({ agent })` ' +
+            'them (or mint a scoped session with `Sessions({ schema, apiKey }).create({ agent })` ' +
             'for a distinct agent identity). They apply only to the self-hosted ' +
             '`capabilityToken` path.');
     }
@@ -149,13 +145,6 @@ export function buildReactiveEngine(inputs) {
         },
     });
     const ready = lifecycle.ready;
-    const participantManager = createParticipantManager({
-        ready,
-        transport,
-        presence: presenceStream,
-        claims: claimStream,
-        schema,
-    });
     // 9b. waitForFlush — drains pending mutations using the store's
     //     pendingChanges counter (already maintained by BaseSyncedStore based
     //     on MutationQueue events). Polls every 50ms; uses the existing
@@ -448,16 +437,6 @@ export function buildReactiveEngine(inputs) {
             // reconcile errors so read interest never makes a read reject or stall.
             enterScope: (scope) => store.enterScope(scope),
             pinScope: (scope) => store.pinScope(scope),
-            // `ablo.<model>.join(ids, { ttl })` performs a scoped participant join
-            // on this model's sync group(s). WebSocket only — `join` throws
-            // `AbloConnectionError` if the socket isn't ready.
-            // `ttl` passes straight through — both surfaces spell the lease the
-            // same way now, so there is no rename here to make a field's name
-            // disagree with the value it carries.
-            createJoin: (modelKey, ids, options) => participantManager.join({
-                scope: { [modelKey]: ids },
-                ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
-            }),
         }, readSetContext);
     }
     const commits = {
@@ -532,45 +511,6 @@ export function buildReactiveEngine(inputs) {
             return commitRecordListSchema.parse(body);
         },
     };
-    /**
-     * The control-plane credential: always the original configured secret key.
-     * Never reads `authCredentials` — that holds the exchanged sync credential
-     * (a wide-scope `rk_` on the hosted path), which control-plane routes
-     * rightly refuse (e.g. the user-session mint is sk_-gated). Counterpart to
-     * `getAuthToken()`, which resolves the sync-plane token.
-     *
-     * The secret-key-only rule is enforced on the server; the credential-kind taxonomy
-     * (secret/restricted/ephemeral/publishable) lives in `auth/credentialPolicy`.
-     */
-    async function controlPlaneApiKey() {
-        return resolveApiKeyValue(configuredApiKey);
-    }
-    /**
-     * Resolve the control-plane context a session/agent mint needs (sk_ +
-     * bootstrap base URL + the schema-key→typename map the server gates on).
-     * Shared by `sessions.create` and `agents.create` so the two mint doors
-     * can never drift on how a token is minted. Throws if no `sk_` is present —
-     * minting is a backend-only operation.
-     */
-    async function buildMintContext(resource) {
-        const apiKey = await controlPlaneApiKey();
-        if (!apiKey) {
-            throw new AbloAuthenticationError(`${resource} requires a secret (sk_) API key — call it from your backend, not the browser.`, { code: 'apikey_missing' });
-        }
-        return {
-            apiKey,
-            baseUrl: resolveBootstrapBaseUrl({
-                url,
-                bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
-            }),
-            ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-            // Map every `can` schema-key to the wire typename the server gates on, so a
-            // typename override (`documents` → `Document`) doesn't mint a capability
-            // the server then denies. Derived from this client's schema by the one rule
-            // the HTTP client and the mint route also read. See `MintSessionContext`.
-            modelTypenames: modelWireNames(schema.models),
-        };
-    }
     const engine = {
         ...modelProxies,
         ready,
@@ -594,11 +534,6 @@ export function buildReactiveEngine(inputs) {
             // is the canonical credential; fall back to a configured API key.
             //
             // This is the sync-plane token (bootstrap, WebSocket, query HTTP). Control-plane
-            // calls (sessions.create, datasource registration) never use it — they
-            // present the original secret key via `controlPlaneApiKey()` below. The
-            // split matters: after the startup exchange this resolver returns the
-            // derived wide-scope `rk_`, a credential the control-plane routes
-            // correctly refuse (an agent token must never mint humans).
             return (authCredentials.getAuthToken() ??
                 (await resolveApiKeyValue(configuredApiKey)) ??
                 configuredAuthToken ??
@@ -618,86 +553,6 @@ export function buildReactiveEngine(inputs) {
         nudgeReconnect() {
             store.nudgeReconnect();
         },
-        sessions: {
-            // A backend (holding `sk_`) mints a short-lived scoped token for one end
-            // user or one agent.
-            //
-            // Both arms authenticate with the original secret key
-            // (`controlPlaneApiKey()`), never the wide-scope `rk_` the startup exchange
-            // installed as the sync credential. A derived agent credential silently
-            // replacing the secret key on control-plane calls is how humans would get
-            // minted as agents — and correct attribution is the point.
-            async create(params) {
-                // Both mint paths (`{ user }` → /v1/ephemeral_keys → `ek_`,
-                // `{ agent, can }` → /v1/capabilities → scoped `rk_`) resolve their
-                // control-plane context through the shared `buildMintContext`, so this
-                // client, `agents.create`, and the stateless HTTP client can't drift on
-                // how a token is minted.
-                return mintSession(params, await buildMintContext('sessions.create'));
-            },
-            async revoke({ id }) {
-                const context = await buildMintContext('sessions.revoke');
-                return revokeCapability({
-                    apiKey: context.apiKey,
-                    baseUrl: context.baseUrl,
-                    id,
-                    ...(context.fetch ? { fetch: context.fetch } : {}),
-                });
-            },
-            async rotate({ id, graceSeconds, ttlSeconds }) {
-                const context = await buildMintContext('sessions.rotate');
-                return rotateCapability({
-                    apiKey: context.apiKey,
-                    baseUrl: context.baseUrl,
-                    id,
-                    ...(graceSeconds !== undefined ? { graceSeconds } : {}),
-                    ...(ttlSeconds !== undefined ? { ttlSeconds } : {}),
-                    ...(context.fetch ? { fetch: context.fetch } : {}),
-                });
-            },
-        },
-        // Mint a scoped agent identity and hand back a connected client bound to it —
-        // `sessions.create({ agent })` plus a typed `Ablo({ schema, apiKey })` client,
-        // for agents that run in this (secret-key-holding) process. Omitting `id`
-        // yields a fresh uuid per call, so concurrent agents are distinct participants
-        // that queue behind each other (even when they share a `name`). Humans don't
-        // get a server-built client — ship them a token via `sessions.create({ user })`.
-        agents: {
-            async create(params) {
-                // Distinct participant by default: omit `id` → a fresh uuid, so even two
-                // agents that share a `name` are independent participants and queue
-                // behind one another. `name` is display only (→ userMeta.name); it never
-                // derives the id. Pass an explicit `id` only to re-attach an agent to
-                // its own held claims.
-                const id = params.id ?? globalThis.crypto.randomUUID();
-                const userMeta = params.name !== undefined ? { ...params.userMeta, name: params.name } : params.userMeta;
-                const sessionParams = {
-                    agent: { id },
-                    can: params.can,
-                    ...(params.onBehalfOf ? { onBehalfOf: params.onBehalfOf } : {}),
-                    ...(params.syncGroups ? { syncGroups: params.syncGroups } : {}),
-                    ...(params.ttlSeconds !== undefined ? { ttlSeconds: params.ttlSeconds } : {}),
-                    ...(userMeta ? { userMeta } : {}),
-                };
-                // Re-mint the `rk_` on every resolver call so a long-lived agent client
-                // never hits token expiry; the `sk_` stays in this process — the child
-                // only ever sees its own short-lived `rk_`.
-                const mintToken = async () => (await mintSession(sessionParams, await buildMintContext('agents.create')))
-                    .token;
-                // Mint once up front so a bad key / denied scope throws HERE, not later
-                // inside the child's bootstrap; reuse that first token, re-mint on refresh.
-                let pending = await mintToken();
-                const apiKey = async () => {
-                    if (pending !== null) {
-                        const token = pending;
-                        pending = null;
-                        return token;
-                    }
-                    return mintToken();
-                };
-                return createSibling({ ...internalOptions, apiKey });
-            },
-        },
         async dispose() {
             lifecycle.dispose();
             try {

package/dist/local/client/storeLifecycle.js

@@ -60,7 +60,11 @@ export function startStoreLifecycle(deps) {
     // unambiguously a deliberate server client). User-kind clients in Node (an
     // SSR/RSC module evaluating scaffolded browser code) stay reactive-only.
     if (credentialResolver) {
-        const rawEndpoint = internalOptions.authEndpoint ?? internalOptions.apiKey;
+        const rawEndpoint = internalOptions.session &&
+            typeof internalOptions.session === 'object' &&
+            'endpoint' in internalOptions.session
+            ? internalOptions.session.endpoint
+            : internalOptions.apiKey;
         const absoluteEndpoint = typeof rawEndpoint === 'string' && /^https?:\/\//i.test(rawEndpoint);
         store.startCredentialLifecycle(credentialResolver, {
             /* eslint-disable @typescript-eslint/no-deprecated -- `kind` gates the self-hosted proactive pre-roll; hosted path derives it from the apiKey scope */

package/dist/local/fileUploads.d.ts

@@ -0,0 +1,27 @@
+/** File-upload behavior owned beneath the SyncClient boundary. */
+import type { RuntimeContext } from './RuntimeContext.js';
+import { Model } from './Model.js';
+import { InstanceCache } from './InstanceCache.js';
+import type { MutationQueue } from './transactions/mutations/MutationQueue.js';
+export interface FileUploadOptions {
+    readonly id: string;
+    readonly attachableType: string;
+    readonly attachableId: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface BatchFileUploadOptions {
+    readonly ids: string[];
+    readonly attachableType: string;
+    readonly attachableId: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface FileUploadContext {
+    readonly userId: string | null;
+    readonly organizationId: string | null;
+    readonly mutationQueue: MutationQueue;
+    readonly objectPool: InstanceCache;
+    readonly observability: RuntimeContext['observability'];
+    readonly notifyCreated: (model: Model) => void;
+}
+export declare function uploadFile(context: FileUploadContext, file: File, options: FileUploadOptions): Promise<Model | null>;
+export declare function batchUploadFiles(context: FileUploadContext, files: File[], options: BatchFileUploadOptions): Promise<Model[]>;

package/dist/local/fileUploads.js

@@ -0,0 +1,55 @@
+/** File-upload behavior owned beneath the SyncClient boundary. */
+import { AbloAuthenticationError } from '@abloatai/transaction/errors';
+import { Model } from './Model.js';
+import { InstanceCache, ModelScope } from './InstanceCache.js';
+function authenticatedContext(context) {
+    if (!context.userId || !context.organizationId) {
+        throw new AbloAuthenticationError('Authentication required for file uploads', {
+            code: 'file_upload_auth_required',
+        });
+    }
+    return { userId: context.userId, organizationId: context.organizationId };
+}
+function acceptUploadedModel(context, data) {
+    const model = context.objectPool.createFromData(data);
+    if (!model)
+        return null;
+    context.objectPool.add(model, ModelScope.live);
+    context.notifyCreated(model);
+    return model;
+}
+export async function uploadFile(context, file, options) {
+    const identity = authenticatedContext(context);
+    try {
+        const result = await context.mutationQueue.uploadAttachment(file, {
+            id: options.id,
+            attachableType: options.attachableType,
+            attachableId: options.attachableId,
+            metadata: options.metadata,
+        }, identity);
+        return result
+            ? acceptUploadedModel(context, { id: options.id, ...result })
+            : null;
+    }
+    catch (error) {
+        context.observability.captureMutationFailure({
+            context: 'file-upload',
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+        throw error;
+    }
+}
+export async function batchUploadFiles(context, files, options) {
+    const identity = authenticatedContext(context);
+    const items = options.ids.map((id) => ({
+        id,
+        attachableType: options.attachableType,
+        attachableId: options.attachableId,
+        metadata: options.metadata,
+    }));
+    const results = await context.mutationQueue.batchUploadAttachments(files, items, identity);
+    return results.flatMap((result) => {
+        const model = acceptUploadedModel(context, { ...result });
+        return model ? [model] : [];
+    });
+}

package/dist/local/storeContract.d.ts

@@ -13,7 +13,7 @@ import type { Model } from './Model.js';
 import type { ModelScope } from '@abloatai/transaction/types';
 import type { QueryView, QueryViewOptions } from './views/QueryView.js';
 import type { ViewRegistry } from './views/ViewRegistry.js';
-import type { ParticipantScope } from './sync/participants.js';
+import type { GroupScope } from './sync/scopeGroups.js';
 /**
  * A snapshot of the client's synchronization state, shaped for binding to UI.
  * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
@@ -129,12 +129,12 @@ export interface SyncStoreContract {
      * read subscriptions and write claims always agree on which group they refer
      * to. These are optional and do nothing until the connection is open.
      */
-    enterScope?(scope: ParticipantScope, opts?: {
+    enterScope?(scope: GroupScope, opts?: {
         hydrate?: boolean;
     }): Promise<void>;
-    leaveScope?(scope: ParticipantScope): Promise<void>;
-    pinScope?(scope: ParticipantScope): Promise<void>;
-    unpinScope?(scope: ParticipantScope): Promise<void>;
+    leaveScope?(scope: GroupScope): Promise<void>;
+    pinScope?(scope: GroupScope): Promise<void>;
+    unpinScope?(scope: GroupScope): Promise<void>;
     /**
      * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
      * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,

package/dist/local/stores/syncAction.d.ts

@@ -10,14 +10,14 @@ export declare const syncActionSchema: z.ZodObject<{
     modelName: z.ZodString;
     modelId: z.ZodString;
     action: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
         A: "A";
+        V: "V";
         C: "C";
-        D: "D";
         G: "G";
-        I: "I";
         S: "S";
-        U: "U";
-        V: "V";
     }>;
     data: z.ZodUnknown;
     __class: z.ZodDefault<z.ZodLiteral<"SyncAction">>;

package/dist/local/sync/contextOnChange.js

@@ -37,7 +37,7 @@ export function contextOnChange(transport, pool, reads, listener) {
     // already advanced this exact row in the pool.
     for (const read of rowReads) {
         const resident = pool.peek(read.id);
-        if (!resident || resident.getModelName().toLowerCase() !== read.model.toLowerCase()) {
+        if (resident?.getModelName().toLowerCase() !== read.model.toLowerCase()) {
             continue;
         }
         const observed = pool.watermarks.of(resident);

package/dist/local/sync/createClaimStream.js

@@ -284,7 +284,7 @@ export function createClaimStream(config, transport = null) {
             }
             ownClaims.clear();
             for (const claimId of [...pendingHeartbeats.keys()]) {
-                settleHeartbeat(claimId, ({ reject }) => reject(error));
+                settleHeartbeat(claimId, ({ reject }) => { reject(error); });
             }
         }));
     }

package/dist/local/sync/credentialLifecycle.d.ts

@@ -1,7 +1,6 @@
 /**
- * Moved to the confirmation core with the duplex transport (ADR 0016): keeping
- * a long-lived socket's credential fresh is connection plumbing an agent needs
- * as much as a browser does. This path re-exports it so existing importers
- * stay unchanged.
+ * The shared session subsystem owns renewal for both browser and agent
+ * sessions. This local boundary keeps the reactive store pointed downward at
+ * that one lifecycle implementation.
  */
-export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, type CredentialRefreshOutcome, type CredentialRecoveryOutcome, type CredentialRefreshResult, type CredentialRefresher, type CredentialLifecycleContext, } from '@abloatai/transaction/transport/connection';
+export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, type CredentialRefreshOutcome, type CredentialRecoveryOutcome, type CredentialRefreshResult, type CredentialRefresher, type CredentialLifecycleContext, } from '@abloatai/transaction/sessions';

package/dist/local/sync/credentialLifecycle.js

@@ -1,7 +1,6 @@
 /**
- * Moved to the confirmation core with the duplex transport (ADR 0016): keeping
- * a long-lived socket's credential fresh is connection plumbing an agent needs
- * as much as a browser does. This path re-exports it so existing importers
- * stay unchanged.
+ * The shared session subsystem owns renewal for both browser and agent
+ * sessions. This local boundary keeps the reactive store pointed downward at
+ * that one lifecycle implementation.
  */
-export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, } from '@abloatai/transaction/transport/connection';
+export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, } from '@abloatai/transaction/sessions';

package/dist/local/sync/deltaPipeline.js

@@ -67,7 +67,9 @@ export function deduplicateDeltas(deltas) {
         return deltas;
     let strictlyOrdered = true;
     for (let index = 1; index < deltas.length; index += 1) {
-        if (deltas[index - 1].id >= deltas[index].id) {
+        const previous = deltas[index - 1];
+        const current = deltas[index];
+        if (!previous || !current || previous.id >= current.id) {
             strictlyOrdered = false;
             break;
         }
@@ -277,10 +279,13 @@ export function sliceApplyChanges(changes, maxDeltas) {
     while (index < changes.length) {
         // The indivisible unit starting here: one transaction's run, or a single
         // untransacted change.
-        const transactionId = changes[index].transactionId;
+        const change = changes[index];
+        if (!change)
+            break;
+        const transactionId = change.transactionId;
         let end = index + 1;
         if (transactionId !== undefined) {
-            while (end < changes.length && changes[end].transactionId === transactionId)
+            while (changes[end]?.transactionId === transactionId)
                 end += 1;
         }
         const groupSize = end - index;
@@ -327,9 +332,11 @@ async function flushDeltaBatchInner(ctx, queuedDeltas) {
     if (customDeltas.length > 0) {
         runInAction(() => {
             for (const delta of customDeltas) {
+                if (delta.data === null)
+                    continue;
                 const data = typeof delta.data === 'string'
                     ? JSON.parse(delta.data)
-                    : (delta.data);
+                    : delta.data;
                 // 'C' (Covering) is treated identically to 'I' here — the client
                 // gained permission to see the entity, so we insert it into the
                 // pool as if newly created.
@@ -395,7 +402,7 @@ async function flushDeltaBatchInner(ctx, queuedDeltas) {
         // slice. Slices stay the atomicity unit; the budget only decides where
         // the loop breathes.
         let sliceStartedAt = performance.now();
-        for (let index = 0; index < slices.length; index++) {
+        for (const [index, slice] of slices.entries()) {
             if (index > 0 && performance.now() - sliceStartedAt > APPLY_YIELD_BUDGET_MS) {
                 pipelineDebug.phase = `apply-yield-${index}`;
                 pipelineDebug.applyYields += 1;
@@ -404,7 +411,6 @@ async function flushDeltaBatchInner(ctx, queuedDeltas) {
             }
             pipelineDebug.phase = `apply-slice-${index}`;
             pipelineDebug.applySlices += 1;
-            const slice = slices[index];
             if (hasApplyPlugins) {
                 runStage(stagePlugins, 'apply', { changes: slice });
             }

package/dist/local/sync/schemas.d.ts

@@ -18,19 +18,19 @@ import type { RuntimeContext } from "../RuntimeContext.js";
  */
 export declare const ServerDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
     actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
         A: "A";
+        V: "V";
         C: "C";
-        D: "D";
         G: "G";
-        I: "I";
         S: "S";
-        U: "U";
-        V: "V";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;
-    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
 }, z.core.$loose>;
 export type ValidatedServerDelta = z.infer<typeof ServerDeltaSchema>;
 export declare const BootstrapResponseSchema: z.ZodObject<{
@@ -42,19 +42,19 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
     models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodString, z.ZodNull]>, z.ZodTransform<unknown[], string | unknown[] | null>>>>;
     deltas: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
+        data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
         actionType: z.ZodEnum<{
+            I: "I";
+            U: "U";
+            D: "D";
             A: "A";
+            V: "V";
             C: "C";
-            D: "D";
             G: "G";
-            I: "I";
             S: "S";
-            U: "U";
-            V: "V";
         }>;
         modelName: z.ZodString;
         modelId: z.ZodString;
-        data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
     }, z.core.$loose>>>;
     deltaCount: z.ZodOptional<z.ZodNumber>;
     failedModels: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/local/sync/scopeGroups.d.ts

@@ -0,0 +1,11 @@
+import type { ClaimTarget } from '@abloatai/transaction/types/streams';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+/** A schema-shaped selector used to narrow connection groups and presence reads. */
+export type GroupScope = ClaimTarget | readonly ClaimTarget[] | string | readonly string[] | {
+    readonly syncGroup: string;
+} | {
+    readonly syncGroups: readonly string[];
+} | Record<string, string | readonly string[] | undefined>;
+/** Resolve an application-shaped scope into the wire groups owned by the schema. */
+export declare function resolveScopeGroups(scope: GroupScope | undefined, schema?: Schema): string[];
+export declare function groupFromEntityRef(ref: ClaimTarget, schema?: Schema): string;

package/dist/local/sync/scopeGroups.js

@@ -0,0 +1,75 @@
+import { scopeKindOf } from '@abloatai/transaction/schema/model';
+/** Resolve an application-shaped scope into the wire groups owned by the schema. */
+export function resolveScopeGroups(scope, schema) {
+    if (!scope)
+        return [];
+    if (typeof scope === 'string')
+        return [scope];
+    if (Array.isArray(scope)) {
+        const groups = [];
+        for (const entry of scope) {
+            if (typeof entry === 'string')
+                groups.push(entry);
+            else if (isEntityScope(entry))
+                groups.push(groupFromEntityRef(entry, schema));
+        }
+        return groups;
+    }
+    const direct = scope;
+    if (isEntityScope(scope))
+        return [groupFromEntityRef(scope, schema)];
+    if (typeof direct.syncGroup === 'string')
+        return [direct.syncGroup];
+    if (Array.isArray(direct.syncGroups)) {
+        return direct.syncGroups.filter((group) => typeof group === 'string');
+    }
+    const groups = [];
+    for (const [key, value] of Object.entries(scope)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const id of value) {
+                if (typeof id === 'string')
+                    groups.push(groupFromSchemaKey(key, id, schema));
+            }
+        }
+        else if (typeof value === 'string') {
+            groups.push(groupFromSchemaKey(key, value, schema));
+        }
+    }
+    return groups;
+}
+export function groupFromEntityRef(ref, schema) {
+    const match = findModelForEntityRef(ref, schema);
+    const kind = match
+        ? groupKindForModel(match.def, match.key)
+        : ref.type.toLowerCase();
+    return `${kind}:${ref.id}`;
+}
+function groupFromSchemaKey(schemaKey, id, schema) {
+    const def = schema?.models[schemaKey];
+    const kind = def ? groupKindForModel(def, schemaKey) : schemaKey.toLowerCase();
+    return `${kind}:${id}`;
+}
+function groupKindForModel(def, key) {
+    return scopeKindOf(def, key) ?? (def.typename ?? key).toLowerCase();
+}
+function findModelForEntityRef(ref, schema) {
+    if (!schema?.models)
+        return null;
+    const wanted = ref.type.toLowerCase();
+    for (const [key, def] of Object.entries(schema.models)) {
+        const typename = def.typename ?? key;
+        if (typename.toLowerCase() === wanted || key.toLowerCase() === wanted) {
+            return { key, def };
+        }
+    }
+    return null;
+}
+function isEntityScope(scope) {
+    return (typeof scope === 'object' &&
+        scope !== null &&
+        !Array.isArray(scope) &&
+        typeof scope.type === 'string' &&
+        typeof scope.id === 'string');
+}

package/dist/local/sync/wsFrameHandlers.d.ts

@@ -5,4 +5,4 @@
  * the transport object. This path re-exports it so existing importers stay
  * unchanged.
  */
-export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, type PendingCommit, type PendingClaim, type PendingSubscription, type WsInboundFrame, type WsSession, type WsFrameHandler, } from '@abloatai/transaction/transport/websocket';
+export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, type PendingCommit, type PendingSubscription, type WsInboundFrame, type WsSession, type WsFrameHandler, } from '@abloatai/transaction/transport/websocket';

package/dist/local/transactions/localMutation.js

@@ -16,9 +16,9 @@ export function createLocalMutationPort(emit) {
     };
     return {
         updates,
-        applyCreate: (model, transaction) => track('optimistic:create', model, transaction),
-        applyUpdate: (model, transaction) => track('optimistic:update', model, transaction),
-        applyDelete: (model, transaction) => track('optimistic:delete', model, transaction),
+        applyCreate: (model, transaction) => { track('optimistic:create', model, transaction); },
+        applyUpdate: (model, transaction) => { track('optimistic:update', model, transaction); },
+        applyDelete: (model, transaction) => { track('optimistic:delete', model, transaction); },
         rollback: (transaction, reason, error) => {
             const optimistic = updates.get(transaction.id);
             if (!optimistic)