@abloatai/humans 0.59.1 → 0.60.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/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/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.d.ts

@@ -73,7 +73,6 @@ export interface DeltaPipelineContext {
          *  {@link handleGroupHandlerFailure}). */
         clear(): void;
     };
-    getStateFields(modelName: string): string[];
     isCustomEntity(modelName: string): boolean;
     createCustomEntity(modelName: string, modelId: string, data: Record<string, unknown>): Model | null;
     deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
@@ -94,8 +93,17 @@ export interface DeltaPipelineContext {
  * It never throws, because it runs inside the pipeline's fire-and-forget path.
  */
 export declare function handleGroupHandlerFailure(ctx: DeltaPipelineContext, delta: SyncDelta, error: unknown): void;
-/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
-export declare function deduplicateDeltas(ctx: DeltaPipelineContext, deltas: SyncDelta[]): SyncDelta[];
+/**
+ * Deduplicate repeated delivery of the same log entry.
+ *
+ * A row may legitimately change several times in one receive frame. Those
+ * changes are ordered facts, even when a small subset of fields (such as
+ * `status`) happens to remain equal. Collapsing by entity or a partial state
+ * signature can therefore discard the newest row image while the cursor still
+ * advances past it. Only an identical positive sync id proves duplicate
+ * delivery; non-positive ids carry no usable log identity and stay untouched.
+ */
+export declare function deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
 /**
  * Performs per-delta bookkeeping and enqueues the delta. Returns `true` when
  * the delta was pushed onto `pendingDeltas` — a regular batchable insert,

package/dist/local/sync/deltaPipeline.js

@@ -52,90 +52,37 @@ export function handleGroupHandlerFailure(ctx, delta, error) {
         // Best-effort: the reconnect/bootstrap cycle self-heals on next connect.
     }
 }
-/** Builds a small signature of a delta's state fields, used to detect no-op duplicate deltas. */
-function extractStateSignature(ctx, delta) {
-    if (!delta.data || typeof delta.data !== 'object')
-        return null;
-    const data = typeof delta.data === 'string'
-        ? JSON.parse(delta.data)
-        : (delta.data);
-    // Generic state fields — subclasses can override getStateFields() for model-specific fields
-    const fieldsToCheck = ctx.getStateFields(delta.modelName);
-    const signature = {
-        actionType: delta.actionType,
-        modelName: delta.modelName,
-    };
-    for (const field of fieldsToCheck) {
-        if (field in data)
-            signature[field] = data[field];
-    }
-    return signature;
-}
-function isSameState(a, b) {
-    if (!a || !b)
-        return false;
-    const keys = Object.keys(a);
-    if (keys.length !== Object.keys(b).length)
-        return false;
-    return keys.every((k) => a[k] === b[k]);
-}
-/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
-export function deduplicateDeltas(ctx, deltas) {
-    // The dominant live-publication shape is a frame of independent entity
-    // creates. When every entity key occurs once, reconciliation cannot remove
-    // or reorder anything: preserve the already commit-ordered input directly
-    // and avoid allocating a bucket array, state signature, and two sorts per
-    // delta. The first duplicate falls through to the full transition logic.
-    const uniqueEntities = new Set();
-    let hasDuplicateEntity = false;
-    for (const delta of deltas) {
-        const key = `${delta.modelName}:${delta.modelId}`;
-        if (uniqueEntities.has(key)) {
-            hasDuplicateEntity = true;
+/**
+ * Deduplicate repeated delivery of the same log entry.
+ *
+ * A row may legitimately change several times in one receive frame. Those
+ * changes are ordered facts, even when a small subset of fields (such as
+ * `status`) happens to remain equal. Collapsing by entity or a partial state
+ * signature can therefore discard the newest row image while the cursor still
+ * advances past it. Only an identical positive sync id proves duplicate
+ * delivery; non-positive ids carry no usable log identity and stay untouched.
+ */
+export function deduplicateDeltas(deltas) {
+    if (deltas.length < 2 || deltas.some((delta) => delta.id <= 0))
+        return deltas;
+    let strictlyOrdered = true;
+    for (let index = 1; index < deltas.length; index += 1) {
+        if (deltas[index - 1].id >= deltas[index].id) {
+            strictlyOrdered = false;
             break;
         }
-        uniqueEntities.add(key);
     }
-    if (!hasDuplicateEntity)
+    if (strictlyOrdered)
         return deltas;
-    const byEntity = new Map();
-    for (const d of deltas) {
-        const key = `${d.modelName}:${d.modelId}`;
-        if (!byEntity.has(key))
-            byEntity.set(key, []);
-        byEntity.get(key).push(d);
-    }
-    const result = [];
-    for (const entityDeltas of byEntity.values()) {
-        const sorted = entityDeltas.sort((a, b) => a.id - b.id);
-        // DELETE wins — it's the final state
-        const del = sorted.find((d) => d.actionType === 'D');
-        if (del) {
-            result.push(del);
-            continue;
-        }
-        // Keep deltas that represent different states
-        const unique = [];
-        let prev = null;
-        for (const d of sorted) {
-            const sig = extractStateSignature(ctx, d);
-            if (!isSameState(prev, sig)) {
-                unique.push(d);
-                prev = sig;
-            }
-        }
-        if (unique.length > 0) {
-            result.push(...unique);
-        }
-        else {
-            // `sorted` is never empty (every byEntity bucket gets at least one
-            // delta pushed) — the guard only narrows the indexed access.
-            const last = sorted.at(-1);
-            if (last)
-                result.push(last);
-        }
-    }
-    return result.sort((a, b) => a.id - b.id);
+    const seen = new Set();
+    return [...deltas]
+        .sort((a, b) => a.id - b.id)
+        .filter((delta) => {
+        if (seen.has(delta.id))
+            return false;
+        seen.add(delta.id);
+        return true;
+    });
 }
 /**
  * Performs per-delta bookkeeping and enqueues the delta. Returns `true` when

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/mutations/failureHandling.js

@@ -1,5 +1,5 @@
-import { AbloError } from '@abloatai/transaction/errors';
 import { extractStatusCode } from './commitPayload.js';
+import { reportPermanentMutationFailure } from './failureReporting.js';
 export function transientRetryDelayMs(error, attempt, retryBackoff) {
     const { baseMs, capMs } = retryBackoff;
     let base = baseMs;
@@ -16,85 +16,12 @@ export async function handleFailure(ctx, transaction, error) {
     transaction.attempts++;
     // Check whether this is a permanent error that should not be retried.
     if (ctx.isPermanentError(error)) {
-        // Logged at warn: a permanent error means the server rejected the write,
-        // so the developer should see the reason in the console. The typed
-        // AbloError fields (`type`, `code`, `httpStatus`) are included so the
-        // cause is visible — for example a foreign-key violation
-        // (AbloValidationError) versus expired authentication
-        // (AbloAuthenticationError).
-        try {
-            const abloErr = error instanceof AbloError ? error : undefined;
-            const details = {
-                txId: transaction.id.slice(0, 8),
-                type: transaction.type,
-                model: transaction.modelName,
-                modelId: transaction.modelId.slice(0, 12),
-                errorType: abloErr?.type ?? error?.name,
-                errorCode: abloErr?.code,
-                httpStatus: abloErr?.httpStatus,
-                requestId: abloErr?.requestId,
-                message: error?.message,
-                inputKeys: transaction.data ? Object.keys(transaction.data) : undefined,
-            };
-            // A `create` whose id already exists is the benign idempotency case:
-            // "this row is already there." It's the least alarming permanent
-            // error, so it doesn't warrant a `warn` — `info` keeps it visible
-            // without crying wolf. Everything else (FK violation, auth expiry,
-            // server 500) stays at `warn`.
-            const isBenignIdempotent = transaction.type === 'create' &&
-                (abloErr?.code === 'unique_violation' ||
-                    abloErr?.type === 'AbloIdempotencyError');
-            // Demote exact repeats (same write rejected for the same reason on
-            // each reconnect replay) to `debug` so the loop logs once.
-            const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
-            const isRepeat = sig === ctx.getLastPermanentErrorSignature();
-            ctx.setLastPermanentErrorSignature(sig);
-            const logger = ctx.runtime.logger;
-            // Two registers from one call site, split by log level (the default
-            // logger is gated at `warn`, so `debug` stays hidden unless
-            // ABLO_LOG_LEVEL=debug is set to inspect the engine):
-            //   - the default-visible line speaks the application developer's
-            //     language: their verb (such as `update`), their model, the typed
-            //     error's own message, and the wire `code` for searching. It uses
-            //     no engine jargon and prints no JSON dump, which would alarm
-            //     without helping.
-            //   - the forensic `details` ride a companion `debug` line for anyone
-            //     debugging the engine internals.
-            const revertNote = ctx.config.enableOptimistic
-                ? ' The local change was reverted.'
-                : '';
-            const reason = abloErr?.message ? ` — ${abloErr.message}` : '';
-            const code = abloErr?.code ? ` (code: ${abloErr.code})` : '';
-            const requestRef = abloErr?.requestId
-                ? ` [request_id: ${abloErr.requestId}]`
-                : '';
-            // An optimistic write resolves before the server answers, so a later
-            // rejection has no caller left to return to and this log is the only
-            // place it appears. That reads to an application developer as their own
-            // save silently failing — the write showed, then vanished — and sends
-            // them into their editor instead of here. Name the subscription that
-            // hands them the same typed error, so the application can say what
-            // happened rather than only the console.
-            const channelNote = ctx.config.enableOptimistic
-                ? ' To surface this in your app, subscribe with `ablo.onMutationFailure(…)`.'
-                : '';
-            const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}${requestRef}.${revertNote}${channelNote}`;
-            if (isRepeat) {
-                // Same write rejected for the same reason on each reconnect replay —
-                // log the forensics once, stay quiet after.
-                logger.debug('write rejected again (same reason)', details);
-            }
-            else if (isBenignIdempotent) {
-                // Already-exists on a `create` is expected on replay, not a problem.
-                logger.info(`Your ${transaction.type} to "${transaction.modelName}" was skipped — this row already exists.`);
-                logger.debug('idempotent skip — details', details);
-            }
-            else {
-                logger.warn(headline);
-                logger.debug('write rejection — details', details);
-            }
-        }
-        catch { }
+        reportPermanentMutationFailure({
+            runtime: ctx.runtime,
+            enableOptimistic: ctx.config.enableOptimistic,
+            getLastPermanentErrorSignature: ctx.getLastPermanentErrorSignature,
+            setLastPermanentErrorSignature: ctx.setLastPermanentErrorSignature,
+        }, transaction, error);
         // Mark as failed immediately and rollback
         ctx.store.updateStatus(transaction.id, 'failed');
         if (ctx.config.enableOptimistic) {
@@ -108,7 +35,8 @@ export async function handleFailure(ctx, transaction, error) {
         return;
     }
     transaction.firstTransientFailureAt ??= Date.now();
-    const insideAvailabilityWindow = Date.now() - transaction.firstTransientFailureAt < ctx.config.availabilityRetryWindowMs;
+    const insideAvailabilityWindow = Date.now() - transaction.firstTransientFailureAt <
+        ctx.config.availabilityRetryWindowMs;
     if (transaction.attempts < ctx.config.maxRetries || insideAvailabilityWindow) {
         // Exponential backoff with full jitter on every transient retry:
         // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses