@abloatai/humans 0.56.0 → 0.58.0

package/dist/local/sync/createClaimStream.js

@@ -24,10 +24,11 @@
 import { asyncIteratorFrom } from '@abloatai/transaction/utils/asyncIterator';
 import { toMs } from '@abloatai/transaction/utils/duration';
 import { claimDescription, descriptionFromMeta, participantKindFromWire, } from '@abloatai/transaction/coordination/schema';
-import { isTargetTuple, subTarget, streamTarget, wireTarget, } from '@abloatai/transaction/coordination/locator';
-import { declaredMeta } from '@abloatai/transaction/coordination/claimMeta';
+import { isTargetTuple, subTarget, streamTarget, wireTarget, } from '@abloatai/transaction/claims';
+import { bindClaimLifetime, createClaimLifetime, } from '@abloatai/transaction/claims/lifetime';
+import { declaredMeta } from '@abloatai/transaction/claims';
 import { AbloClaimedError, AbloConnectionError } from '@abloatai/transaction/errors';
-import { resolveHeartbeatOptions } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
+import { resolveHeartbeatOptions } from '@abloatai/transaction/claims';
 import { noopLogger } from '@abloatai/transaction/logger';
 /** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
 function claimLabel(type, id, field) {
@@ -47,7 +48,7 @@ export function createClaimStream(config, transport = null) {
     // ── State: others' open claims, keyed by claimId ───────────────
     const activeByClaimId = new Map();
     let claimsSnapshot = Object.freeze([]);
-    // ── State: our own open claims (for re-announce on reconnect) ───
+    // ── State: our own open grants, keyed by the exact claim id ─────
     const ownClaims = new Map();
     // ── State: per-entity wait queues, from `claim_queue` frames ────
     // Keyed `type:id`; the value is the FIFO line of queued claims. Powers
@@ -157,15 +158,18 @@ export function createClaimStream(config, transport = null) {
         unsubs.push(t.subscribe('claim_rejected', (rejection) => {
             if (!rejection.claimId)
                 return;
-            if (ownClaims.has(rejection.claimId)) {
+            const own = ownClaims.get(rejection.claimId);
+            if (own) {
                 const tgt = rejection.target
                     ? claimLabel(rejection.target.entityType, rejection.target.entityId, rejection.target.field)
                     : rejection.claimId;
                 logger.info(`claim: rejected ${tgt}${rejection.heldBy ? ` — held by ${rejection.heldBy}` : ''}`, { claimId: rejection.claimId, reason: rejection.reason });
             }
-            // Drop the rejected own-claim so reconnect doesn't re-announce
-            // a claim the server already rejected (would just spam both
-            // sides with conflicts).
+            own?.lifetime.end(new AbloClaimedError(rejection.message ?? `Claim ${rejection.claimId} was rejected.`, {
+                code: rejection.reason === 'conflict'
+                    ? 'claim_conflict'
+                    : 'claim_lease_unavailable',
+            }));
             ownClaims.delete(rejection.claimId);
             // A holder on another server may have claimed before this client joined
             // the row group, so its one-shot presence frame was missed. A conflict
@@ -193,12 +197,12 @@ export function createClaimStream(config, transport = null) {
         // The frame is validated by the transport's dispatcher against the same
         // schema this parameter's type comes from, so it arrives proven.
         t.subscribe('claim_lost', (lost) => {
-            if (ownClaims.has(lost.claimId)) {
-                const c = ownClaims.get(lost.claimId);
-                logger.info(`claim: lost ${c ? claimLabel(c.entityType, c.entityId, c.field) : lost.claimId} (preempted or expired)`, { claimId: lost.claimId });
+            const own = ownClaims.get(lost.claimId);
+            if (own) {
+                const c = own.claim;
+                logger.info(`claim: lost ${claimLabel(c.entityType, c.entityId, c.field)} (preempted or expired)`, { claimId: lost.claimId });
             }
-            // Drop the lost own-claim so reconnect doesn't re-announce a lease we
-            // no longer hold.
+            own?.lifetime.end(new AbloClaimedError(`Claim ${lost.claimId} was lost because it ${lost.reason === 'expired' ? 'expired' : 'was preempted'}. Re-acquire it before continuing.`, { code: 'claim_lost' }));
             ownClaims.delete(lost.claimId);
             for (const l of lostListeners) {
                 try {
@@ -260,17 +264,27 @@ export function createClaimStream(config, transport = null) {
                     });
                     return;
                 }
-                const c = ownClaims.get(ack.claimId);
-                reject(new AbloClaimedError(`The lease behind ${c ? claimLabel(c.entityType, c.entityId, c.field) : `claim ${ack.claimId}`} is no longer held — it expired or was granted onward while this participant was working. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' }));
+                const own = ownClaims.get(ack.claimId);
+                const c = own?.claim;
+                const error = new AbloClaimedError(`The lease behind ${c ? claimLabel(c.entityType, c.entityId, c.field) : `claim ${ack.claimId}`} is no longer held — it expired or was granted onward while this participant was working. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' });
+                own?.lifetime.end(error);
+                ownClaims.delete(ack.claimId);
+                reject(error);
             });
         }));
-        // (3) On reconnect, re-announce every open self-claim — the
-        //     server's claim state is in-memory and is lost across
-        //     restarts. Without this, peers would see our claims vanish
-        //     whenever the connection blipped.
-        unsubs.push(t.subscribe('connected', () => {
-            for (const [claimId, claim] of ownClaims) {
-                sendBegin(claimId, claim);
+        // (3) A granted handle belongs to this connection's exact grant. The server
+        //     releases the participant's claims when its last socket leaves; trying
+        //     to recreate them on `connected` silently swapped the lease beneath an
+        //     old `data` / `readAt` / fenceToken tuple. End them instead. A caller
+        //     reconnects, re-reads, and takes a fresh handle.
+        unsubs.push(t.subscribe('disconnected', () => {
+            const error = new AbloConnectionError('The connection holding this claim ended. Reconnect and acquire a fresh claim before continuing.');
+            for (const { lifetime } of ownClaims.values()) {
+                lifetime.end(error);
+            }
+            ownClaims.clear();
+            for (const claimId of [...pendingHeartbeats.keys()]) {
+                settleHeartbeat(claimId, ({ reject }) => reject(error));
             }
         }));
     }
@@ -308,14 +322,14 @@ export function createClaimStream(config, transport = null) {
     }
     /**
      * Send one heartbeat and await its ack. Rejects with
-     * {@link AbloConnectionError} (transient — the auto-heartbeat loop retries
-     * on its next tick) when the socket is down or the ack times out, and with
+     * {@link AbloConnectionError} when the socket is down or the ack times out,
+     * and with
      * {@link AbloClaimedError} (definitive) when the server answers that the
      * lease is no longer ours.
      */
     function sendHeartbeat(claimId, claim, options) {
         if (!attached?.isConnected()) {
-            return Promise.reject(new AbloConnectionError(`The heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} was skipped because the connection is down. The keepalive renews held leases automatically on reconnect; the next beat retries.`));
+            return Promise.reject(new AbloConnectionError(`The heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} was skipped because the connection is down. This connection's grant has ended; reconnect and acquire a fresh claim.`));
         }
         return new Promise((resolve, reject) => {
             settleHeartbeat(claimId, ({ reject: rejectPrior }) => {
@@ -371,7 +385,8 @@ export function createClaimStream(config, transport = null) {
             estimatedMs,
             queue: args.queue,
         };
-        ownClaims.set(claimId, claim);
+        const lifetime = createClaimLifetime();
+        ownClaims.set(claimId, { claim, lifetime });
         sendBegin(claimId, claim);
         // Coordination trace (info): the creator can see their human/agent claims.
         logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.description}"` +
@@ -381,11 +396,12 @@ export function createClaimStream(config, transport = null) {
             if (revoked)
                 return;
             revoked = true;
+            lifetime.end();
             ownClaims.delete(claimId);
             sendAbandon(claimId, claim);
             logger.info(`claim: released ${claimLabel(claim.entityType, claim.entityId, claim.field)}`, { claimId });
         };
-        return {
+        return bindClaimLifetime({
             object: 'claim',
             id: claimId,
             status: 'active',
@@ -403,7 +419,7 @@ export function createClaimStream(config, transport = null) {
             [Symbol.asyncDispose]: async () => {
                 revoke();
             },
-        };
+        }, lifetime);
     }
     function resolveTarget(target) {
         if (isTargetTuple(target))
@@ -471,6 +487,9 @@ export function createClaimStream(config, transport = null) {
                     reject(new AbloConnectionError('The claim stream was disposed while this heartbeat was awaiting its reply.'));
                 });
             }
+            const error = new AbloConnectionError('The claim stream was disposed. Acquire a fresh claim before continuing.');
+            for (const { lifetime } of ownClaims.values())
+                lifetime.end(error);
             listeners.clear();
             rejectionListeners.clear();
             lostListeners.clear();

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

@@ -4,4 +4,4 @@
  * as much as a browser does. This path re-exports it so existing importers
  * stay unchanged.
  */
-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/credentialLifecycle';
+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';

package/dist/local/sync/credentialLifecycle.js

@@ -4,4 +4,4 @@
  * as much as a browser does. This path re-exports it so existing importers
  * stay unchanged.
  */
-export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, } from '@abloatai/transaction/transport/credentialLifecycle';
+export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, } from '@abloatai/transaction/transport/connection';

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

@@ -1,4 +1,4 @@
-import type { JoinOptions } from '@abloatai/transaction/resources/modelOperations';
+import type { JoinOptions } from '@abloatai/transaction/client/resources/modelOperations';
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '@abloatai/transaction/types/streams';

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

@@ -20,10 +20,10 @@ 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<{
+        A: "A";
         I: "I";
         U: "U";
         D: "D";
-        A: "A";
         V: "V";
         C: "C";
         G: "G";
@@ -44,10 +44,10 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
         id: z.ZodNumber;
         data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
         actionType: z.ZodEnum<{
+            A: "A";
             I: "I";
             U: "U";
             D: "D";
-            A: "A";
             V: "V";
             C: "C";
             G: "G";

package/dist/local/sync/schemas.js

@@ -8,7 +8,7 @@
 import { z } from 'zod';
 import { globalRuntime } from "../context.js";
 import { AbloValidationError } from "@abloatai/transaction/errors";
-import { syncDeltaWireCoreSchema } from '@abloatai/transaction/wire/delta';
+import { syncDeltaWireCoreSchema } from '@abloatai/transaction/observation';
 // ─── Server Delta Schema ─────────────────────────────────────────────────────
 /**
  * A delta as it arrives in a bootstrap payload.

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/wsFrameHandlers';
+export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, type PendingCommit, type PendingClaim, type PendingSubscription, type WsInboundFrame, type WsSession, type WsFrameHandler, } from '@abloatai/transaction/transport/websocket';

package/dist/local/sync/wsFrameHandlers.js

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

package/dist/local/syncClientTypes.d.ts

@@ -0,0 +1,41 @@
+import type { Model } from './Model.js';
+import type { BootstrapData } from './sync/BootstrapFetcher.js';
+import type { QueuedMutation } from './transactions/mutations/MutationQueue.js';
+import type { CommitTransaction } from './transactions/mutations/commitLane.js';
+export interface SyncObserver {
+    onSync?: (event: SyncEvent) => void;
+}
+export interface SyncEvent {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'rollback';
+    modelType: string;
+    model?: Model;
+    modelId?: string;
+    transactionType?: string;
+}
+export interface SyncState {
+    connectionState: 'connected' | 'disconnected' | 'connecting';
+    pendingMutations: number;
+    lastSyncAt?: Date;
+    error?: Error;
+}
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+export type EventHandler = () => void;
+/** The bootstrap fields applied to the local object pool. */
+export type BootstrapSnapshot = Pick<BootstrapData, 'models' | 'failedModels'> & Partial<Pick<BootstrapData, 'lastSyncId'>>;
+/** A completed queued mutation or explicit commit. */
+export type CompletedTransaction = (Pick<QueuedMutation, 'id' | 'modelId' | 'syncIdNeededForCompletion'> & {
+    lastSyncId?: undefined;
+    operations?: undefined;
+}) | (Pick<CommitTransaction, 'id' | 'lastSyncId' | 'operations'> & {
+    modelId?: undefined;
+    syncIdNeededForCompletion?: undefined;
+});
+/** Normalize an untyped server timestamp for last-write-wins comparison. */
+export declare function toEpochMs(value: unknown): number;

package/dist/local/syncClientTypes.js

@@ -0,0 +1,11 @@
+/** Normalize an untyped server timestamp for last-write-wins comparison. */
+export function toEpochMs(value) {
+    if (!value)
+        return 0;
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'string' || typeof value === 'number') {
+        return new Date(value).getTime();
+    }
+    return 0;
+}

package/dist/local/transactions/databaseCommitOutbox.d.ts

@@ -1,5 +1,5 @@
-import type { DurableWriteStore } from '@abloatai/transaction/durableWrites';
-import type { PendingWrite } from '@abloatai/transaction/transactions/confirmation/pendingWrite';
+import type { DurableWriteStore } from '@abloatai/transaction/commit';
+import type { PendingWrite } from '@abloatai/transaction/commit';
 export interface CommitOutboxDatabase {
     sealTransactionRecord(record: PendingWrite, consumedRecordIds: readonly string[]): Promise<unknown>;
     getPersistedTransactions(): Promise<readonly unknown[]>;

package/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -17,9 +17,10 @@ import type { MutationPersistencePort } from '../../mutationPersistence.js';
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import { type LogPositionPort } from '../../logPosition.js';
 import type { WriteOptions } from '../../interfaces/index.js';
-import type { StaleNotification, ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import type { ReadDependency } from '@abloatai/transaction/coordination/schema';
+import { type CommitOperationResult } from '@abloatai/transaction/commit';
 import { type MutationInput, type QueuedMutation, type UserContext } from './commitPayload.js';
-import { type CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import { type CommitOutboxScope } from '@abloatai/transaction/commit';
 import type { DurableWriteStore } from './durableWriteStore.js';
 import { type LocalMutationPort } from './localMutation.js';
 import { type CommitTransaction } from './commitLane.js';
@@ -150,7 +151,7 @@ export declare class MutationQueue extends EventEmitter {
     private get queueCoalescingContext();
     private get batchProcessingContext();
     private get failureHandlingContext();
-    private get conflictPolicyContext();
+    private get conflictResolutionContext();
     private get processingSchedulerContext();
     private get pendingDrainContext();
     private get durableCommitRestoreContext();
@@ -162,18 +163,6 @@ export declare class MutationQueue extends EventEmitter {
     private computePriorityScore;
     private ensureDerivedFields;
     private entityKey;
-    /** Collision-safe receipt target identity across models sharing a row id. */
-    private receiptTargetKey;
-    /**
-     * Relates stale notifications back to write targets without assuming the
-     * server's canonical model name uses the same spelling as the public schema
-     * key (`Item` versus `items`). Exact `(model,id)` wins; a globally unique id
-     * is the compatibility fallback. An ambiguous same-id cross-model mismatch
-     * is deliberately left unclassified, so it cannot falsely settle a queued
-     * write. A notification with no write-target id (or an explicit group) is a
-     * declared-read conflict and holds the whole batch.
-     */
-    private classifyReceiptNotifications;
     private resolveConfirmation;
     private takeUnsentCreateForModel;
     private cancelUnsentCreateForDelete;
@@ -184,7 +173,6 @@ export declare class MutationQueue extends EventEmitter {
     private config;
     private executingCount;
     private readonly localMutationPort;
-    private commitNotifications;
     /** Zero-row targets returned on a successful atomic commit receipt. */
     private commitMissingIds;
     private readonly deltaConfirmation;
@@ -366,13 +354,12 @@ export declare class MutationQueue extends EventEmitter {
     /** Enqueues a pre-built atomic commit through the commit API coordinator. */
     enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
         reads?: ReadDependency[] | null;
-        track?: TrackDependency[] | null;
     }): Promise<void>;
     private processCommitLane;
     waitForCommitReceipt(clientTxId: string): Promise<{
         lastSyncId: number;
-        notifications?: StaleNotification[];
         missingIds?: string[];
+        operationResults?: CommitOperationResult[];
     }>;
     private isReorderPayload;
     private isPermanentError;