@abloatai/humans 0.57.0 → 0.58.0

package/src/local/transactions/mutations/commitLane.ts

@@ -1,13 +1,13 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
-import type { ReadDependency, TrackDependency, OnStaleMode, StaleNotification } from '@abloatai/transaction/coordination/schema';
+import type { ReadDependency } from '@abloatai/transaction/coordination/schema';
 import type {
   CommitOperationResult,
   MutationCommitResult,
-} from '@abloatai/transaction/wire/commit';
+} from '@abloatai/transaction/commit';
 import type {
   DurableCommitEnvelope,
   DurableCommitOperation,
-} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+} from '@abloatai/transaction/commit';
 import type { SealDurableCommitInput } from './commitTransport.js';
 import { transientRetryDelayMs } from './failureHandling.js';
 
@@ -21,10 +21,8 @@ export interface CommitTransaction {
     input?: Record<string, unknown>;
     transactionId?: string;
     readAt?: number | null;
-    onStale?: OnStaleMode | null;
   }[];
   reads?: ReadDependency[] | null;
-  track?: TrackDependency[] | null;
   status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed';
   createdAt: number;
   attempts: number;
@@ -50,7 +48,6 @@ export interface CommitLaneContext {
     retryBackoff: { baseMs: number; capMs: number };
   };
   readonly commitLane: CommitTransaction[];
-  readonly commitNotifications: Map<string, StaleNotification[]>;
   readonly commitMissingIds: Map<string, string[]>;
   readonly commitProcessing: boolean;
   readonly setCommitProcessing: (value: boolean) => void;
@@ -72,7 +69,6 @@ export interface CommitLaneContext {
 
 export interface CommitReceiptContext {
   readonly commitStore: Map<string, CommitTransaction>;
-  readonly commitNotifications: Map<string, StaleNotification[]>;
   readonly commitMissingIds: Map<string, string[]>;
   readonly replicationLagErrors: Map<string, Error>;
   readonly on: (event: string, listener: (payload: object) => void) => void;
@@ -84,16 +80,9 @@ export function waitForCommitReceipt(
   clientTxId: string,
 ): Promise<{
   lastSyncId: number;
-  notifications?: StaleNotification[];
   missingIds?: string[];
   operationResults?: CommitOperationResult[];
 }> {
-  const drainNotifications = (): StaleNotification[] | undefined => {
-    const notifications = ctx.commitNotifications.get(clientTxId);
-    if (!notifications) return undefined;
-    ctx.commitNotifications.delete(clientTxId);
-    return notifications.length > 0 ? notifications : undefined;
-  };
   const drainMissingIds = (): string[] | undefined => {
     const ids = ctx.commitMissingIds.get(clientTxId);
     if (!ids) return undefined;
@@ -104,7 +93,6 @@ export function waitForCommitReceipt(
     const missingIds = drainMissingIds();
     return {
       lastSyncId,
-      notifications: drainNotifications(),
       ...(transaction.operationResults
         ? { operationResults: transaction.operationResults }
         : {}),
@@ -157,7 +145,6 @@ export async function processCommitLane(ctx: CommitLaneContext): Promise<void> {
           sourceMutationIds: tx.sourceMutationIds,
           commitOptions: {
             ...(tx.reads ? { reads: tx.reads } : {}),
-            ...(tx.track ? { track: tx.track } : {}),
           },
           createdAt: tx.createdAt,
           sealedAt: tx.sealedAt,
@@ -170,7 +157,6 @@ export async function processCommitLane(ctx: CommitLaneContext): Promise<void> {
         tx.durableEnvelope = await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
         tx.lastSyncId = result.lastSyncId;
         if (result.operationResults?.length) tx.operationResults = [...result.operationResults];
-        if (result.notifications?.length) ctx.commitNotifications.set(tx.id, result.notifications);
         if (result.missingIds?.length) ctx.commitMissingIds.set(tx.id, result.missingIds);
         ctx.commitLane.shift();
         if (result.status === 'queued') {

package/src/local/transactions/mutations/commitPayload.ts

@@ -13,9 +13,8 @@ import { globalRuntime } from '../../context.js';
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import { MutationOperationType } from '@abloatai/transaction/types';
 import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
-import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
 import type { MutationOptions, WriteOptions } from '../../interfaces/index.js';
-import type { CommitEnvelopeMember } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import type { CommitEnvelopeMember } from '@abloatai/transaction/commit';
 
 export interface UserContext {
   userId: string;
@@ -198,10 +197,7 @@ export const TX_TYPE_TO_MUTATION_OP: Record<QueuedMutation['type'], MutationOper
 };
 
 export function hasStaleWriteOptions(options?: WriteOptions): boolean {
-  return (
-    options?.readAt !== undefined ||
-    options?.onStale !== undefined
-  );
+  return options?.readAt !== undefined;
 }
 
 /** Options whose identity/audit semantics forbid merging two caller writes. */
@@ -217,7 +213,6 @@ export function hasCommitCoalescingBarrier(options?: WriteOptions): boolean {
 
 export interface WriteOperationFields {
   readAt?: number | null;
-  onStale?: OnStaleMode | null;
   fenceToken?: number | null;
   claimId?: string;
   options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
@@ -225,7 +220,7 @@ export interface WriteOperationFields {
 
 /**
  * Copies a transaction's `writeOptions` onto the wire operation. The
- * stale-context guards (`readAt` and `onStale`) sit at the operation's root,
+ * stale-context guard (`readAt`) sits at the operation's root,
  * while `idempotencyKey` and `label` go in its `options` slot — the
  * `mutation_log` cache key and audit tag. This is the one place caller-supplied
  * write options cross onto the wire.
@@ -240,9 +235,6 @@ export function applyWriteOptions<T extends object>(
   if (writeOptions.readAt !== undefined) {
     operation.readAt = writeOptions.readAt;
   }
-  if (writeOptions.onStale !== undefined) {
-    operation.onStale = writeOptions.onStale;
-  }
   if (writeOptions.fenceToken !== undefined) {
     operation.fenceToken = writeOptions.fenceToken;
   }

package/src/local/transactions/mutations/commitTransport.ts

@@ -1,6 +1,6 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { MutationExecutor } from '../../interfaces/index.js';
-import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import type { ReadDependency } from '@abloatai/transaction/coordination/schema';
 import {
   AbloConnectionError,
   AbloError,
@@ -9,7 +9,7 @@ import {
 import {
   mutationCommitResultSchema,
   type MutationCommitResult,
-} from '@abloatai/transaction/wire/commit';
+} from '@abloatai/transaction/commit';
 import {
   createDurableCommitEnvelope,
   commitEnvelopeRecordId,
@@ -17,7 +17,7 @@ import {
   type CommitOutboxScope,
   type DurableCommitEnvelope,
   type DurableCommitOperation,
-} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+} from '@abloatai/transaction/commit';
 import type { DurableWriteStore } from './durableWriteStore.js';
 
 export interface CommitTransportContext {
@@ -39,7 +39,6 @@ export interface SealDurableCommitInput {
   sourceMutationIds?: string[];
   commitOptions?: {
     reads?: readonly ReadDependency[] | null;
-    track?: readonly TrackDependency[] | null;
   };
   createdAt: number;
   sealedAt: number;
@@ -63,9 +62,6 @@ export async function sealDurableCommit(
       ...(input.commitOptions?.reads !== undefined
         ? { reads: input.commitOptions.reads === null ? null : [...input.commitOptions.reads] }
         : {}),
-      ...(input.commitOptions?.track !== undefined
-        ? { track: input.commitOptions.track === null ? null : [...input.commitOptions.track] }
-        : {}),
     },
     ...(ctx.commitOutboxScope ? { scope: ctx.commitOutboxScope } : {}),
     createdAt: input.createdAt,

package/src/local/transactions/mutations/durableCommitRestore.ts

@@ -1,9 +1,9 @@
 import { AbloIdempotencyError, AbloValidationError } from '@abloatai/transaction/errors';
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { CommitTransaction } from './commitLane.js';
-import type { DurableCommitEnvelope, CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import type { DurableCommitEnvelope, CommitOutboxScope } from '@abloatai/transaction/commit';
 import type { DurableWriteStore } from './durableWriteStore.js';
-import { durableCommitEnvelopeSchema } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import { durableCommitEnvelopeSchema } from '@abloatai/transaction/commit';
 
 export interface DurableCommitRestoreContext {
   readonly config: { enablePersistence: boolean };
@@ -95,9 +95,6 @@ export async function restoreDurableCommits(ctx: DurableCommitRestoreContext): P
           ...(envelope.commitOptions.reads
             ? { reads: [...envelope.commitOptions.reads] }
             : {}),
-          ...(envelope.commitOptions.track
-            ? { track: [...envelope.commitOptions.track] }
-            : {}),
           status: 'pending',
           createdAt: envelope.createdAt,
           sealedAt: envelope.sealedAt,

package/src/local/transactions/mutations/durableWriteStore.ts

@@ -6,16 +6,16 @@
  *
  * The port and its config live in the core's `durableWrites` module (a behavior
  * contract, not a persisted shape); the records that cross it are owned by
- * `transactions/confirmation/pendingWrite`.
+ * `commit/confirmation/pendingWrite`.
  */
 
 export {
   durableWriteStoreSchema,
   durableWritesConfigSchema,
-} from '@abloatai/transaction/durableWrites';
+} from '@abloatai/transaction/commit';
 export type {
   DurableWriteStore,
   DurableWritesConfig,
-} from '@abloatai/transaction/durableWrites';
-export { pendingWriteSchema } from '@abloatai/transaction/transactions/confirmation/pendingWrite';
-export type { PendingWrite } from '@abloatai/transaction/transactions/confirmation/pendingWrite';
+} from '@abloatai/transaction/commit';
+export { pendingWriteSchema } from '@abloatai/transaction/commit';
+export type { PendingWrite } from '@abloatai/transaction/commit';

package/src/local/transactions/mutations/failurePolicy.ts

@@ -25,7 +25,7 @@ export function isDefinitiveRejection(error: Error): boolean {
   return status !== undefined && status >= 400 && status < 500 && status !== 429;
 }
 
-export interface ConflictPolicyContext {
+export interface ConflictResolutionContext {
   readonly config: Pick<MutationQueueConfig, 'conflictResolution'>;
   readonly store: MutationStore;
   readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string) => Promise<void>;
@@ -34,7 +34,7 @@ export interface ConflictPolicyContext {
 }
 
 export async function handleConflict(
-  ctx: ConflictPolicyContext,
+  ctx: ConflictResolutionContext,
   transaction: QueuedMutation,
   serverData: MutationInput,
 ): Promise<void> {

package/src/local/transactions/mutations/mutationPersistence.ts

@@ -1,7 +1,7 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { MutationPersistencePort } from '../../mutationPersistence.js';
 import type { MutationQueueConfig } from './MutationQueue.js';
-import type { CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import type { CommitOutboxScope } from '@abloatai/transaction/commit';
 import type { QueuedMutation } from './commitPayload.js';
 import { MutationStore } from './MutationStore.js';
 import { normalizeModelKey } from './commitPayload.js';

package/src/local/transactions/mutations/pendingDrain.ts

@@ -2,8 +2,8 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { QueuedMutation } from './commitPayload.js';
 import type { MutationStore } from './MutationStore.js';
 import type { OptimisticUpdateEntry } from './localMutation.js';
-import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
-import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import type { MutationCommitResult } from '@abloatai/transaction/commit';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
 import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 
 export interface PendingDrainContext {

package/src/local/transactions/mutations/replayValidation.ts

@@ -23,14 +23,12 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import {
   commitEnvelopeMemberSchema,
   commitOutboxScopeSchema,
-} from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
-import { onStaleModeSchema } from '@abloatai/transaction/coordination/schema';
+} from '@abloatai/transaction/commit';
 
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
 const persistedWriteOptionsSchema = z
   .object({
     readAt: z.number().nullable().optional(),
-    onStale: onStaleModeSchema.nullable().optional(),
     idempotencyKey: z.string().optional(),
     label: z.string().optional(),
     // Aligned with the `WriteOptions` type: a claimed write persisted locally

package/src/local/transactions/persistedTransaction.ts

@@ -1,5 +1,3 @@
-import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
-
 type ModelData = Record<string, unknown>;
 
 /** One mutation retained in the durable local transaction journal. */
@@ -10,7 +8,6 @@ interface PersistedMutation {
   timestamp: string;
   writeOptions?: {
     readAt?: number | null;
-    onStale?: OnStaleMode | null;
   };
 }
 

package/src/plugin.ts

@@ -19,9 +19,9 @@ import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 import type { ErrorCodeSpec } from '@abloatai/transaction/errorCodes';
 import type { Logger } from '@abloatai/transaction/logger';
 import type { CoordinationObservability } from '@abloatai/transaction/observability';
-import type { WsTransport } from '@abloatai/transaction/transport/wsTransport';
+import type { WsTransport } from '@abloatai/transaction/transport/websocket';
 import type { AuthCredentialSource } from '@abloatai/transaction/auth/credentialSource';
-import type { SyncDeltaWireCore } from '@abloatai/transaction/wire/delta';
+import type { SyncDeltaWireCore } from '@abloatai/transaction/observation';
 import type { ModelData } from '@abloatai/transaction/types/modelData';
 
 /**

package/src/presenceStream.ts

@@ -23,8 +23,8 @@
  *       `leave`.
  */
 
-import type { WsTransport } from '@abloatai/transaction/transport/wsTransport';
-import type { PresenceUpdate } from '@abloatai/transaction/transport/wsTransport';
+import type { WsTransport } from '@abloatai/transaction/transport/websocket';
+import type { PresenceUpdate } from '@abloatai/transaction/transport/websocket';
 import type {
   Activity,
   Peer,

package/src/react/createAbloReact.ts

@@ -36,7 +36,7 @@ import {
   type UseAbloModelResult,
 } from './useAblo.js';
 import type { AbloClient as Ablo } from '../client.js';
-import type { ModelOperations } from '../local/client/createModelProxy.js';
+import type { ModelOperations } from '../local/client/createModelOperations.js';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
 
 /** What a binding returns: the provider and the hook, with `S` fixed. */

package/src/react/useAblo.ts

@@ -7,7 +7,7 @@ import type { ModelClaim } from '@abloatai/transaction/coordination';
 import {
   getModelClientMeta,
   type ModelOperations,
-} from '../local/client/createModelProxy.js';
+} from '../local/client/createModelOperations.js';
 import { Model } from '../local/Model.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { ResolveSchema } from '@abloatai/transaction/types/global';
@@ -138,7 +138,7 @@ function snapshotValue<T>(value: T): T {
  * // With the Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
- * const doc = await ablo.records.get({ id }); // async server read
+ * const doc = await ablo.records.get({ id }); // observational async server read
  *
  * // Reactive selector (a synchronous local snapshot). The selector's reads
  * // are typed as snapshot rows — data fields + computeds, no relation

package/src/surface.ts

@@ -14,7 +14,7 @@
  * written by hand, since prose cannot be type-checked.
  */
 
-import type { ModelOperations, LocalReadOptions } from './local/client/createModelProxy.js';
+import type { ModelOperations, LocalReadOptions } from './local/client/createModelOperations.js';
 import type { AbloOptions } from './Ablo.js';
 
 // ── compile-time exact-equality (no runtime, no casts) ─────────────────────
@@ -33,7 +33,7 @@ type Expect<T extends true> = T;
  */
 export const PUBLIC_MODEL_VERBS = [
   'get',
-  'retrieve',
+  'read',
   'list',
   'listAll',
   'local',
@@ -41,7 +41,6 @@ export const PUBLIC_MODEL_VERBS = [
   'update',
   'delete',
   'claim',
-  'track',
   'join',
   'onChange',
 ] as const;

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

@@ -1,29 +0,0 @@
-/**
- * Captures a local {@link Snapshot} of a chosen set of entities, along with a
- * watermark, so a caller can detect when that state has gone stale. This is
- * what an LLM caller threads into a prompt: `stamp` flows into later writes as
- * `readAt`, so the server rejects a mutation premised on data that has since
- * changed; `signal` is an `AbortSignal` that fires as soon as any captured
- * entity receives a delta, so a mid-generation invalidation can abort the token
- * stream instead of producing output against stale context.
- *
- * It reads the current entity state from the in-memory pool, reads the engine's
- * current `lastSyncId` as the watermark, and subscribes to delta frames on the
- * existing sync connection — no second connection.
- */
-import type { InstanceCache } from '../InstanceCache.js';
-import type { Schema } from '@abloatai/transaction/schema/schema';
-import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { Snapshot } from '@abloatai/transaction/types/streams';
-export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends keyof TSchema['models'] & string = keyof TSchema['models'] & string> {
-    pool: InstanceCache;
-    /** Live transport for delta subscriptions. May be null if the engine
-     *  hasn't connected yet — the snapshot still resolves with current
-     *  pool state, but `signal` won't fire until reconnect. */
-    transport: SyncWebSocket | null;
-    /** Returns the engine's current `lastSyncId`. Read at snapshot time
-     *  to stamp the watermark; not re-read after. */
-    getLastSyncId: () => number;
-    entities: Readonly<Record<K, string | readonly string[]>>;
-}
-export declare function createSnapshot<TSchema extends Schema, K extends keyof TSchema['models'] & string>(args: CreateSnapshotArgs<TSchema, K>): Snapshot<TSchema, K>;

package/dist/local/sync/createSnapshot.js

@@ -1,116 +0,0 @@
-/**
- * Captures a local {@link Snapshot} of a chosen set of entities, along with a
- * watermark, so a caller can detect when that state has gone stale. This is
- * what an LLM caller threads into a prompt: `stamp` flows into later writes as
- * `readAt`, so the server rejects a mutation premised on data that has since
- * changed; `signal` is an `AbortSignal` that fires as soon as any captured
- * entity receives a delta, so a mid-generation invalidation can abort the token
- * stream instead of producing output against stale context.
- *
- * It reads the current entity state from the in-memory pool, reads the engine's
- * current `lastSyncId` as the watermark, and subscribes to delta frames on the
- * existing sync connection — no second connection.
- */
-import { AbloValidationError } from '@abloatai/transaction/errors';
-import { modelAsRow } from '../Model.js';
-/**
- * The snapshot result exposes `stamp`, `signal`, and `onChange` at its top
- * level, alongside one bucket per model. If a schema declares a model with one
- * of these names, the two would collide, so snapshot creation throws instead.
- */
-const RESERVED_SNAPSHOT_KEYS = new Set([
-    'stamp',
-    'signal',
-    'onChange',
-]);
-export function createSnapshot(args) {
-    const { pool, transport, getLastSyncId, entities } = args;
-    // ── Validate keys ────────────────────────────────────────────────
-    for (const key of Object.keys(entities)) {
-        if (RESERVED_SNAPSHOT_KEYS.has(key)) {
-            throw new AbloValidationError(`engine.snapshot: model key "${key}" collides with a reserved ` +
-                `snapshot field (stamp / signal / onChange). Rename the model ` +
-                'in your schema.', { code: 'snapshot_reserved_key' });
-        }
-    }
-    // ── Watermark ────────────────────────────────────────────────────
-    const stamp = getLastSyncId();
-    // ── Capture data + watched set ───────────────────────────────────
-    const watched = new Set(); // `${type}:${id}`
-    const data = {};
-    for (const [type, idOrIds] of Object.entries(entities)) {
-        const ids = Array.isArray(idOrIds)
-            ? idOrIds
-            : [idOrIds];
-        const bucket = {};
-        for (const id of ids) {
-            const m = pool.get(id);
-            // Only include if the model actually has the requested type —
-            // pool keys models globally by id, so `pool.get(id)` could
-            // return a different model that happens to share the id (rare,
-            // but type guards keep the surface honest).
-            if (m &&
-                typeof m.getModelName === 'function' &&
-                m.getModelName() === type) {
-                bucket[id] = modelAsRow(m);
-            }
-            watched.add(`${type}:${id}`);
-        }
-        data[type] = bucket;
-    }
-    // ── Invalidation wiring ──────────────────────────────────────────
-    const listeners = new Set();
-    const controller = new AbortController();
-    const fireChange = (change) => {
-        if (!controller.signal.aborted) {
-            controller.abort(new Error('snapshot invalidated — underlying entity received a delta'));
-        }
-        for (const l of listeners) {
-            try {
-                l(change);
-            }
-            catch {
-                /* listener errors don't break siblings */
-            }
-        }
-    };
-    let unsubDelta = null;
-    if (transport) {
-        unsubDelta = transport.subscribe('delta', (delta) => {
-            const key = `${delta.modelName}:${delta.modelId}`;
-            if (!watched.has(key))
-                return;
-            // Every delta to a captured entity is reported as 'semantic' severity.
-            fireChange({
-                model: delta.modelName,
-                id: delta.modelId,
-                severity: 'semantic',
-            });
-        });
-    }
-    // ── Build the flat result ────────────────────────────────────────
-    const result = {
-        stamp,
-        signal: controller.signal,
-        onChange: (listener) => {
-            listeners.add(listener);
-            // The caller unsubscribes its own listener via the returned function.
-            // The underlying delta subscription lives for the snapshot's lifetime;
-            // there is no explicit dispose because a snapshot is short-lived (one
-            // LLM call's worth) and the subscription is cheap.
-            return () => {
-                listeners.delete(listener);
-                // Once the last listener is gone and the abort has fired, drop the
-                // delta subscription too — nothing is listening anymore.
-                if (listeners.size === 0 && controller.signal.aborted && unsubDelta) {
-                    unsubDelta();
-                    unsubDelta = null;
-                }
-            };
-        },
-    };
-    for (const [modelName, bucket] of Object.entries(data)) {
-        result[modelName] = bucket;
-    }
-    return result;
-}