@abloatai/ablo 0.32.0 → 0.34.0

package/dist/coordination/index.d.ts

@@ -9,7 +9,7 @@
  * Exports are listed by name rather than re-exported wholesale, so every symbol
  * that becomes part of this package's public API is a deliberate choice.
  */
-export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
+export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
 export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../policy/types.js';
-export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, ClaimHeartbeatPayload, ClaimHeartbeatAckPayload, ClaimHeartbeatBatchPayload, ClaimHeartbeatBatchAckPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';
+export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, TrackDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, ClaimHeartbeatPayload, ClaimHeartbeatAckPayload, ClaimHeartbeatBatchPayload, ClaimHeartbeatBatchAckPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';

package/dist/coordination/index.js

@@ -14,7 +14,7 @@ export {
 // Shared primitives
 targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, 
 // Layer 3 — optimistic stale-context
-onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, 
+onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, 
 // Layer 2 — pessimistic claim / claim-lease
 claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, 
 // Read interest — area-of-interest navigation

package/dist/coordination/schema.d.ts

@@ -181,6 +181,26 @@ export declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
     }>>;
 }, z.core.$strip>]>;
 export type ReadDependency = z.infer<typeof readDependencySchema>;
+/**
+ * A durable read-dependency — what a participant is watching so that a later
+ * change to it opens a {@link StaleNotification}. It is the persisted sibling of
+ * a {@link ReadDependency}: the same reference shape, minus the disposition (a
+ * track always notifies — that is what tracking is), with an optional `readAt`
+ * that defaults to the watermark of the commit that registered it. The row form
+ * watches one object; the group form watches a whole sync group ("anything in
+ * `deck:abc`"). Where a `ReadDependency` is checked once at commit and discarded,
+ * a `TrackDependency` is kept and re-checked against every future delta. See
+ * `packages/sync-engine/docs/groups.md` for how it drives change propagation.
+ */
+export declare const trackDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
+    model: z.ZodString;
+    id: z.ZodString;
+    readAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    readAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+export type TrackDependency = z.infer<typeof trackDependencySchema>;
 /**
  * The lifecycle of a claim. When absent on the wire it means `'active'` (an
  * additive back-compat default). The server stamps `'active'` on `claim_begin`

package/dist/coordination/schema.js

@@ -183,6 +183,28 @@ export const readDependencySchema = z.union([
         onStale: onStaleModeSchema.optional(),
     }),
 ]);
+/**
+ * A durable read-dependency — what a participant is watching so that a later
+ * change to it opens a {@link StaleNotification}. It is the persisted sibling of
+ * a {@link ReadDependency}: the same reference shape, minus the disposition (a
+ * track always notifies — that is what tracking is), with an optional `readAt`
+ * that defaults to the watermark of the commit that registered it. The row form
+ * watches one object; the group form watches a whole sync group ("anything in
+ * `deck:abc`"). Where a `ReadDependency` is checked once at commit and discarded,
+ * a `TrackDependency` is kept and re-checked against every future delta. See
+ * `packages/sync-engine/docs/groups.md` for how it drives change propagation.
+ */
+export const trackDependencySchema = z.union([
+    z.object({
+        model: z.string(),
+        id: z.string(),
+        readAt: z.number().optional(),
+    }),
+    z.object({
+        group: z.string(),
+        readAt: z.number().optional(),
+    }),
+]);
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 2 — pessimistic claims and leases
 // ─────────────────────────────────────────────────────────────────────────

package/dist/errorCodes.d.ts

@@ -161,7 +161,7 @@ export declare const ERROR_CODES: {
     readonly model_claimed: ErrorCodeSpec;
     readonly model_claimed_timeout: ErrorCodeSpec;
     readonly model_claim_not_configured: ErrorCodeSpec;
-    readonly model_watch_not_configured: ErrorCodeSpec;
+    readonly model_join_not_configured: ErrorCodeSpec;
     readonly stale_context: ErrorCodeSpec;
     readonly contention_exhausted: ErrorCodeSpec;
     readonly update_aborted: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -157,7 +157,7 @@ export const ERROR_CODES = {
     model_claimed: wire('claim', 409, false, 'Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own.'),
     model_claimed_timeout: wire('claim', 409, false, 'Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it.'),
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
-    model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
+    model_join_not_configured: client('claim', 'join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
     // Not retryable at the transport: the rejected request carries its frozen
     // `readAt`, so resending the identical payload can never succeed. Recovery

package/dist/interfaces/index.d.ts

@@ -6,7 +6,7 @@
  * session-error detection, online-status checks, and the transport that carries
  * mutations to your backend. The SDK ships sensible no-op defaults where it can.
  */
-import type { ReadDependency, ParticipantKind } from '../coordination/schema.js';
+import type { ReadDependency, TrackDependency, ParticipantKind } from '../coordination/schema.js';
 import type { CommitStatus, MutationCommitResultInput } from '../wire/commit.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
@@ -232,6 +232,18 @@ export interface MutationOptions {
      * footprints, §4 the read-set) for the governing convention.
      */
     reads?: ReadDependency[] | null;
+    /**
+     * Durable read-dependencies — what this write (or the record it produces) should
+     * keep watching. Unlike `reads`, which is checked once at commit and discarded,
+     * each `track` entry is persisted and re-checked against every future delta; a
+     * later matching change opens a `StaleNotification` for the tracking participant,
+     * delivered at their next commit or live to a held claim. Each entry is a row
+     * (`{ model, id }`) or a sync group (`{ group }`), optionally pinned to a `readAt`
+     * baseline (defaults to this commit's watermark).
+     *
+     * See `packages/sync-engine/docs/groups.md` for how `track` drives propagation.
+     */
+    track?: TrackDependency[] | null;
 }
 /**
  * The subset of {@link MutationOptions} that travels with each write as it is

package/dist/react/AbloProvider.d.ts

@@ -15,7 +15,7 @@ import { type SyncStoreContract } from './context.js';
  *   - **One component, one import.** Consumers write the provider
  *     once at the root; nothing else needs to plumb the engine.
  *   - **Multiplayer is default.** React consumers are always browsers doing
- *     multiplayer UI, so `useWatch()` / `useAblo()` are always
+ *     multiplayer UI, so `useJoin()` / `useAblo()` are always
  *     available. No opt-in prop.
  *   - **Declarative props for app glue.** `preventUnsavedChanges`,
  *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
@@ -110,11 +110,11 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
 export type { EngineParticipant, ParticipantScope, ParticipantStatus };
 /**
- * Options for `useWatch`. The hook reuses the engine's single
+ * Options for `useJoin`. The hook reuses the engine's single
  * WebSocket and opens a scoped claim on it when `scope` is provided:
  * one TCP connection, N logical sub-syncgroup participants.
  */
-export interface UseWatchOptions {
+export interface UseJoinOptions {
     readonly scope?: ParticipantScope;
     readonly ttlSeconds?: number | string | null;
     /** Tear down + don't re-join while true. */
@@ -145,7 +145,7 @@ export interface UseWatchOptions {
 }
 /** @deprecated Use `ParticipantStatus`. */
 export type MeshParticipantStatus = ParticipantStatus;
-export interface UseWatchReturn {
+export interface UseJoinReturn {
     readonly participant: EngineParticipant | null;
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: readonly Peer[];
@@ -159,7 +159,7 @@ export interface UseWatchReturn {
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
- * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * `useJoin` is the React form of `ablo.<model>.join` — scope-level
  * read-interest + presence; returns the reactive participant facade
  * (peers/claims/status).
  *
@@ -168,10 +168,10 @@ export interface UseWatchReturn {
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
+export declare function useJoin(opts: UseJoinOptions): UseJoinReturn;
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useWatch}, this does
+ * connection, bridged to React. Unlike {@link useJoin}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -184,7 +184,7 @@ export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — when some OTHER mount already owns the scope's
  * read interest (scope `leave` is not reference-counted, so a second
- * `useWatch` on the same scope would warm-drop the owner's
+ * `useJoin` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts

package/dist/react/AbloProvider.js

@@ -211,7 +211,7 @@ const EMPTY_INTENTS = Object.freeze([]);
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
- * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * `useJoin` is the React form of `ablo.<model>.join` — scope-level
  * read-interest + presence; returns the reactive participant facade
  * (peers/claims/status).
  *
@@ -220,7 +220,7 @@ const EMPTY_INTENTS = Object.freeze([]);
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export function useWatch(opts) {
+export function useJoin(opts) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const { paused = false } = opts;
@@ -353,7 +353,7 @@ export function useWatch(opts) {
 }
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useWatch}, this does
+ * connection, bridged to React. Unlike {@link useJoin}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -366,7 +366,7 @@ export function useWatch(opts) {
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — when some OTHER mount already owns the scope's
  * read interest (scope `leave` is not reference-counted, so a second
- * `useWatch` on the same scope would warm-drop the owner's
+ * `useJoin` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts
@@ -377,7 +377,7 @@ export function useWatch(opts) {
 export function usePeers(scope) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
-    // Resolve scope → groups through the schema (same idiom as useWatch).
+    // Resolve scope → groups through the schema (same idiom as useJoin).
     // The stringified, sorted key is the stable effect dependency.
     const scopeKey = JSON.stringify(resolveParticipantSyncGroups(scope, engine?.schema).sort());
     const groups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
@@ -394,7 +394,7 @@ export function usePeers(scope) {
         // Plain useState + onChange — presence changes on join/leave/activity
         // only (never on cursor traffic, a separate channel), so this fires
         // rarely; a frame of stale presence is harmless (same rationale as
-        // useWatch's peers bridge).
+        // useJoin's peers bridge).
         setPeers(compute());
         return presence.onChange(() => { setPeers(compute()); });
     }, [engine, scopeKey]);

package/dist/react/index.d.ts

@@ -41,10 +41,10 @@
  * client:
  *
  *   useAblo((ablo) => ablo.<model>.claim.state(...))  — reactive coordination reads
- *   useWatch({ scope })                               — join a scope to get its peers and claims
+ *   useJoin({ scope })                                — join a scope to get its peers and claims
  */
 export type { DefaultSyncShape, ResolveSchema, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
-export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseWatchOptions, type UseWatchReturn, type MeshParticipantStatus, } from './AbloProvider.js';
+export { AbloProvider, useJoin, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseJoinOptions, type UseJoinReturn, type MeshParticipantStatus, } from './AbloProvider.js';
 export { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 export type { SyncStoreContract } from './context.js';

package/dist/react/index.js

@@ -41,10 +41,10 @@
  * client:
  *
  *   useAblo((ablo) => ablo.<model>.claim.state(...))  — reactive coordination reads
- *   useWatch({ scope })                               — join a scope to get its peers and claims
+ *   useJoin({ scope })                                — join a scope to get its peers and claims
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
-export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
+export { AbloProvider, useJoin, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
 export { ClientSideSuspense, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 // ── Status + errors + identity ─────────────────────────────────────

package/dist/schema/index.d.ts

@@ -30,7 +30,7 @@ export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncD
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, type ConflictAxis, } from './model.js';
 export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwrite, agentsReject, agentsNotify, systemOverwrite, systemReject, systemNotify, type ConflictRule, } from './coordination.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type Row, type InferModel, type InferCreate, type InferRow, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, intersectRequestedWithAllowed, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, type TenantContextMapping, type TenantContextSource, RESERVED_TENANT_CONTEXT_GUCS, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type Row, type InferModel, type InferCreate, type InferRow, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, intersectRequestedWithAllowed, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, type SessionSettings, type SessionSettingSource, RESERVED_SESSION_SETTINGS, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels, omitModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';

package/dist/schema/index.js

@@ -56,7 +56,7 @@ export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwr
 // sensible defaults for everything else.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, RESERVED_TENANT_CONTEXT_GUCS, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, RESERVED_SESSION_SETTINGS, } from './schema.js';
 // Schema ⇄ JSON — serialize a schema for transport and rebuild it on the far side.
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.

package/dist/schema/schema.d.ts

@@ -30,36 +30,32 @@ export type CasingConvention = 'snake_case' | 'camelCase';
 export type CasingFn = (jsField: string) => string;
 /** `defineSchema`'s casing option. Identity when unset. */
 export type Casing = CasingConvention | CasingFn;
-/** Options for `defineSchema`. */
 /**
- * A server-authored context value that can fill a customer's row-level-security
- * GUC. Deliberately a closed set — every member is resolved by Ablo from the
- * authenticated `ek_` and the plane, never from client-supplied data — so a
- * mapping can forward the tenant identity Ablo already trusts but can never
+ * A server-authored identity value that can fill one of a customer's Postgres
+ * session settings. Deliberately a closed set — every member is resolved by Ablo
+ * from the authenticated `ek_` and the plane, never from client-supplied data —
+ * so a mapping can forward the tenant identity Ablo already trusts but can never
  * widen a writer's scope. Mirrors the fields the engine sets on the direct-write
  * connection (`app.current_org_id`, `app.current_project_id`, …).
  */
-export type TenantContextSource = 'orgId' | 'projectId' | 'environment' | 'sandboxId' | 'participantId' | 'participantKind';
+export type SessionSettingSource = 'orgId' | 'projectId' | 'environment' | 'sandboxId' | 'participantId' | 'participantKind';
 /**
- * Maps a Postgres session GUC the customer's RLS policies read to the Ablo
- * context value that fills it. See {@link DefineSchemaOptions.tenantContext} and
- * ADR 0011.
+ * A map from a Postgres session-setting name the customer's RLS policies read to
+ * the Ablo identity that fills it — e.g. `{ 'app.current_org': 'orgId' }`. The
+ * setting name is the key (it takes exactly one source), so a duplicate is
+ * unrepresentable rather than validated away. See
+ * {@link DefineSchemaOptions.sessionSettings} and ADR 0011.
  */
-export interface TenantContextMapping {
-    /** The GUC name the customer's policies read, e.g. `app.current_app_org_id`. */
-    readonly guc: string;
-    /** Which server-authored context value fills it. */
-    readonly from: TenantContextSource;
-}
+export type SessionSettings = Readonly<Record<string, SessionSettingSource>>;
 /**
- * GUCs Ablo already sets on its direct-write connection. A `tenantContext`
- * mapping FORWARDS Ablo's trusted context into a customer's own policy GUC — it
- * may never reassign one of these, which would let a schema push relax the
- * engine's own scoping, timeouts, or `row_security`. Shared with the engine's
- * direct-write seam so authoring-time validation and the runtime guard read one
- * list. See ADR 0011.
+ * Session settings Ablo already sets on its direct-write connection. A
+ * `sessionSettings` entry FORWARDS Ablo's trusted context into a setting the
+ * customer's own policies read — it may never reassign one of these, which would
+ * let a schema push relax the engine's own scoping, timeouts, or `row_security`.
+ * Shared with the engine's direct-write seam so authoring-time validation and
+ * the runtime guard read one list. See ADR 0011.
  */
-export declare const RESERVED_TENANT_CONTEXT_GUCS: readonly string[];
+export declare const RESERVED_SESSION_SETTINGS: readonly string[];
 export interface DefineSchemaOptions {
     /**
      * How to translate camelCase JS field names into database column
@@ -90,26 +86,27 @@ export interface DefineSchemaOptions {
      */
     readonly identityRoles?: readonly IdentityRole[];
     /**
-     * Declares how Ablo's direct-write connection carries tenant context into the
-     * GUCs your row-level-security policies read (ADR 0011). Before every direct
-     * write, Ablo already sets a fixed bundle (`app.current_org_id`,
-     * `app.current_project_id`, …) with `SET LOCAL`. If your policies read a
-     * differently-named GUC that your own app sets per-connection — e.g. a
-     * restrictive policy on `current_setting('app.current_app_org_id')` — declare
-     * the mapping here so Ablo forwards its trusted context into that GUC too, and
-     * your RLS governs Ablo's writes:
+     * Extra Postgres session settings Ablo's direct-write connection applies from
+     * your authenticated identity, so your row-level-security policies read them
+     * (ADR 0011). Before every direct write, Ablo already `SET LOCAL`s a fixed
+     * bundle (`app.current_org_id`, `app.current_project_id`, …). If your policies
+     * read a differently-named setting your own app sets per-connection — e.g. a
+     * restrictive policy on `current_setting('app.current_org')` — map that
+     * setting to the identity that fills it, and Ablo sets it too:
      *
      * ```ts
      * defineSchema({ ... }, {
-     *   tenantContext: [{ guc: 'app.current_app_org_id', from: 'orgId' }],
+     *   sessionSettings: { 'app.current_org': 'orgId' },
      * })
      * ```
      *
-     * Do NOT carve a policy exception for the writer role — that exempts exactly
-     * the writes you want governed. Leave unset when your policies read the GUCs
-     * Ablo already sets (or when a table has no RLS). Empty array when unset.
+     * The key is the setting name your policies read; the value is a closed set of
+     * identities Ablo authenticates, so a mapping can narrow what the writer sees
+     * but never widen it. Do NOT carve a policy exception for the writer role —
+     * that exempts exactly the writes you want governed. Leave unset when your
+     * policies read the settings Ablo already applies (or when a table has no RLS).
      */
-    readonly tenantContext?: readonly TenantContextMapping[];
+    readonly sessionSettings?: SessionSettings;
 }
 /** A record of model names → model definitions */
 export type SchemaRecord = Record<string, ModelDef>;
@@ -165,12 +162,12 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
      */
     readonly identityRoles: readonly IdentityRole[];
     /**
-     * Tenant-context GUC mappings registered via `defineSchema({...},
-     * { tenantContext })` (ADR 0011). The engine's direct-write path reads this to
-     * `SET LOCAL` each declared GUC from server-authored context before applying
-     * DML, so the customer's RLS governs Ablo's writes. Empty array when unset.
+     * Session settings registered via `defineSchema({...}, { sessionSettings })`
+     * (ADR 0011). The engine's direct-write path reads this to `SET LOCAL` each
+     * named setting from server-authored context before applying DML, so the
+     * customer's RLS governs Ablo's writes. Empty object when unset.
      */
-    readonly tenantContext: readonly TenantContextMapping[];
+    readonly sessionSettings: SessionSettings;
     /**
      * Set only on a projection produced by `selectModels`/`omitModels`: the
      * content hash of the FULL source schema the subset was cut from. A subset

package/dist/schema/schema.js

@@ -45,14 +45,14 @@ function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
 /**
- * GUCs Ablo already sets on its direct-write connection. A `tenantContext`
- * mapping FORWARDS Ablo's trusted context into a customer's own policy GUC — it
- * may never reassign one of these, which would let a schema push relax the
- * engine's own scoping, timeouts, or `row_security`. Shared with the engine's
- * direct-write seam so authoring-time validation and the runtime guard read one
- * list. See ADR 0011.
+ * Session settings Ablo already sets on its direct-write connection. A
+ * `sessionSettings` entry FORWARDS Ablo's trusted context into a setting the
+ * customer's own policies read — it may never reassign one of these, which would
+ * let a schema push relax the engine's own scoping, timeouts, or `row_security`.
+ * Shared with the engine's direct-write seam so authoring-time validation and
+ * the runtime guard read one list. See ADR 0011.
  */
-export const RESERVED_TENANT_CONTEXT_GUCS = [
+export const RESERVED_SESSION_SETTINGS = [
     'statement_timeout',
     'lock_timeout',
     'row_security',
@@ -221,45 +221,39 @@ export function defineSchema(models, options) {
         resolvedModels[name] = { ...def, typename, tableName, persist };
     }
     validateSyncGroupSchema(resolvedModels);
-    validateTenantContext(options?.tenantContext ?? []);
+    validateSessionSettings(options?.sessionSettings ?? {});
     return {
         // Cast back to S: we only added values to optional fields that were
         // already part of ModelDef, so the shape is structurally unchanged.
         models: resolvedModels,
         validators: validators,
         identityRoles: options?.identityRoles ?? [],
-        tenantContext: options?.tenantContext ?? [],
+        sessionSettings: options?.sessionSettings ?? {},
     };
 }
 /**
- * Reject tenant-context mappings that couldn't do what the author intends —
+ * Reject session-setting mappings that couldn't do what the author intends —
  * caught here at definition time rather than silently dropped on the write path.
- * A mapping must name a non-empty customer GUC, must not reassign one of the
- * engine's reserved GUCs, and each GUC may be mapped at most once.
+ * Each key must name a non-empty setting the customer's policies read, and must
+ * not reassign one Ablo already manages. Uniqueness needs no check: the map is
+ * keyed by the setting name, so a duplicate is unrepresentable.
  */
-function validateTenantContext(mappings) {
-    const seen = new Set();
-    for (const { guc } of mappings) {
-        const name = guc.trim();
+function validateSessionSettings(settings) {
+    for (const setting of Object.keys(settings)) {
+        const name = setting.trim();
         if (name === '') {
-            throw new AbloValidationError(`[defineSchema] tenantContext: a mapping has an empty \`guc\`. Name the ` +
-                `Postgres setting your row-level-security policies read, e.g. ` +
-                `\`{ guc: 'app.current_app_org_id', from: 'orgId' }\`.`, { code: 'schema_definition_invalid', param: 'tenantContext' });
+            throw new AbloValidationError(`[defineSchema] sessionSettings: a key is empty. Name the Postgres ` +
+                `setting your row-level-security policies read, e.g. ` +
+                `\`{ 'app.current_org': 'orgId' }\`.`, { code: 'schema_definition_invalid', param: 'sessionSettings' });
         }
-        if (RESERVED_TENANT_CONTEXT_GUCS.includes(name)) {
-            throw new AbloValidationError(`[defineSchema] tenantContext: \`${name}\` is a setting Ablo already ` +
+        if (RESERVED_SESSION_SETTINGS.includes(name)) {
+            throw new AbloValidationError(`[defineSchema] sessionSettings: \`${name}\` is a setting Ablo already ` +
                 `manages on its write connection, so a mapping can't reassign it — ` +
                 `that would let a schema relax the engine's own scoping. Point your ` +
-                `policies at a GUC your app owns (e.g. \`app.current_app_org_id\`) and ` +
-                `map Ablo's trusted context into that instead. Reserved: ` +
-                `${RESERVED_TENANT_CONTEXT_GUCS.join(', ')}.`, { code: 'schema_definition_invalid', param: `tenantContext.${name}` });
+                `policies at a setting your app owns (e.g. \`app.current_org\`) and ` +
+                `map Ablo's trusted identity into that instead. Reserved: ` +
+                `${RESERVED_SESSION_SETTINGS.join(', ')}.`, { code: 'schema_definition_invalid', param: `sessionSettings.${name}` });
         }
-        if (seen.has(name)) {
-            throw new AbloValidationError(`[defineSchema] tenantContext: \`${name}\` is mapped more than once. ` +
-                `A GUC takes exactly one source — keep the mapping you mean and drop ` +
-                `the duplicate.`, { code: 'schema_definition_invalid', param: `tenantContext.${name}` });
-        }
-        seen.add(name);
     }
 }
 /**

package/dist/schema/select.js

@@ -52,7 +52,7 @@ export function selectModels(schema, keys) {
         models: models,
         validators: validators,
         identityRoles: schema.identityRoles,
-        tenantContext: schema.tenantContext,
+        sessionSettings: schema.sessionSettings,
         // Record the full source's hash so the drift check can recognize this subset
         // as current against a server running that full schema. Prefer the source's
         // OWN `sourceSchemaHash` when it is itself a projection, so a subset-of-a-

package/dist/schema/serialize.d.ts

@@ -31,7 +31,7 @@ import type { Tenancy } from './tenancy.js';
 import type { ModelResidency } from './residency.js';
 import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule, ConflictAxis } from './model.js';
 import type { RelationType } from './relation.js';
-import { type Schema, type IdentityRole, type EntityRole, type TenantContextMapping } from './schema.js';
+import { type Schema, type IdentityRole, type EntityRole, type SessionSettings } from './schema.js';
 /** Current schema-JSON envelope version. Bump this on a breaking change to the
  * JSON shape itself — not to a user's schema. */
 declare const SCHEMA_JSON_VERSION: 3;
@@ -75,8 +75,8 @@ export interface SchemaJSON {
     readonly v: typeof SCHEMA_JSON_VERSION;
     readonly models: Record<string, ModelJSON>;
     readonly identityRoles: readonly IdentityRole[];
-    /** Optional so schemas pushed before ADR 0011 still parse (defaults to `[]`). */
-    readonly tenantContext?: readonly TenantContextMapping[];
+    /** Optional so schemas pushed before ADR 0011 still parse (defaults to `{}`). */
+    readonly sessionSettings?: SessionSettings;
 }
 /**
  * Project a `Schema` to its JSON form. Drops the client-only closures

package/dist/schema/serialize.js

@@ -93,7 +93,9 @@ export function toSchemaJSON(schema) {
         v: SCHEMA_JSON_VERSION,
         models,
         identityRoles: schema.identityRoles,
-        ...(schema.tenantContext.length > 0 ? { tenantContext: schema.tenantContext } : {}),
+        ...(Object.keys(schema.sessionSettings).length > 0
+            ? { sessionSettings: schema.sessionSettings }
+            : {}),
     };
 }
 /** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
@@ -205,7 +207,7 @@ export function fromSchemaJSON(json) {
         models: models,
         validators: validators,
         identityRoles: json.identityRoles,
-        tenantContext: json.tenantContext ?? [],
+        sessionSettings: json.sessionSettings ?? {},
     };
 }
 /** Parse a `Schema` from a JSON string (inverse of {@link serializeSchema}). */

package/dist/server/commit.d.ts

@@ -17,7 +17,7 @@ import type { ParticipantKind, ConfirmationState } from '../schema/syncDeltaRow.
 import type { ParticipantRef } from '../wire/delta.js';
 import type { CommitExecutionResultInput } from '../wire/commit.js';
 import type { Environment } from '../environment.js';
-import type { ReadDependency } from '../coordination/schema.js';
+import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
 export interface CommitContext {
     participantId: string;
     /**
@@ -97,6 +97,13 @@ export interface CommitContext {
      * validates only the rows being written. Omit it to check the write targets alone.
      */
     reads?: ReadDependency[] | null;
+    /**
+     * Durable read-dependencies to persist for this commit's participant. Each entry
+     * is kept in `track_dependencies` and re-checked against every future delta; a
+     * later match opens a `StaleNotification` delivered out of band. Distinct from
+     * `reads`, which is checked once here and discarded.
+     */
+    track?: TrackDependency[] | null;
 }
 /**
  * The server execution receipt persisted in `mutation_log`. Its runtime schema

package/dist/surface.d.ts

@@ -19,7 +19,7 @@
  * tuple, so it is the one list of model-verb names a generated summary can
  * describe.
  */
-export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "getAll", "getCount", "create", "update", "delete", "claim", "watch", "onChange"];
+export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "getAll", "getCount", "create", "update", "delete", "claim", "track", "join", "onChange"];
 /**
  * The option keys accepted by `list`, `getAll`, and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named

package/dist/surface.js

@@ -30,7 +30,8 @@ export const PUBLIC_MODEL_VERBS = [
     'update',
     'delete',
     'claim',
-    'watch',
+    'track',
+    'join',
     'onChange',
 ];
 // ── the read/list query option surface ─────────────────────────────────────