@abloatai/ablo 0.27.0 → 0.28.0

package/dist/commit/contract.js

@@ -0,0 +1,187 @@
+/**
+ * The transport-independent v2 commit contract.
+ *
+ * A commit is a caller's atomic write intent. It contains ordered operations,
+ * a stable idempotency key, and explicit write preconditions. HTTP and
+ * WebSocket transports wrap these schemas; they do not redefine their data.
+ * Every public data type in this module is inferred from the Zod schema that
+ * validates it at a trust boundary.
+ */
+import { z } from 'zod';
+import { ERROR_CODES } from '../errorCodes.js';
+/** Current version of the transport-independent commit contract. */
+export const COMMIT_CONTRACT_VERSION = 2;
+// ── Opaque identifiers ───────────────────────────────────────────────────
+/** Stable identity of one logical commit. Reused unchanged for every retry. */
+export const idempotencyKeySchema = z.string().min(1).max(255).brand();
+/** Server-issued identity of a durable commit execution. */
+export const commitIdSchema = z.uuid().brand();
+/** Stable identity of one operation within a commit. */
+export const operationIdSchema = z.string().min(1).max(255).brand();
+/** Identity of a pessimistic claim whose generation fences a write. */
+export const claimIdSchema = z.string().min(1).max(255).brand();
+/**
+ * Internal committed-log offset. Decimal strings preserve PostgreSQL BIGINT
+ * precision across JavaScript and JSON boundaries.
+ */
+export const syncOffsetSchema = z
+    .string()
+    .regex(/^(0|[1-9]\d*)$/, 'Expected a non-negative decimal sync offset')
+    .brand();
+/** Opaque resumable cursor returned to clients; consumers must not inspect it. */
+export const syncCursorSchema = z.string().min(1).max(4096).brand();
+// ── JSON values ──────────────────────────────────────────────────────────
+/** JSON-safe value accepted by a persisted or fingerprinted commit payload. */
+export const jsonValueSchema = z.json();
+/** JSON object accepted for entity values, patches, and structured details. */
+export const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
+const nonEmptyJsonObjectSchema = jsonObjectSchema.refine((value) => Object.keys(value).length > 0, 'Expected at least one changed field');
+// ── Intent ───────────────────────────────────────────────────────────────
+/** Model and row addressed by an operation. */
+export const entityRefSchema = z.strictObject({
+    model: z.string().min(1).max(255),
+    id: z.string().min(1).max(1024),
+});
+const fieldPathSchema = z.string().min(1).max(1024);
+/**
+ * A condition that must still hold when an operation is applied. Preconditions
+ * are data rather than option flags so they are included in the request
+ * fingerprint and can be reported precisely when a commit conflicts.
+ */
+export const writePreconditionSchema = z.discriminatedUnion('type', [
+    z.strictObject({
+        type: z.literal('unchanged_since'),
+        cursor: syncOffsetSchema,
+        fields: z.array(fieldPathSchema).min(1).max(256).optional(),
+    }),
+    z.strictObject({
+        type: z.literal('version_matches'),
+        version: z.number().int().nonnegative(),
+    }),
+    z.strictObject({
+        type: z.literal('claim_fence'),
+        claimId: claimIdSchema,
+        generation: z.number().int().positive(),
+    }),
+]);
+const operationBaseShape = {
+    operationId: operationIdSchema,
+    target: entityRefSchema,
+    preconditions: z.array(writePreconditionSchema).max(16).default([]),
+};
+/**
+ * One ordered entity change within a commit. The discriminant makes illegal
+ * combinations unrepresentable: only create carries `value`, only patch
+ * carries `changes`, and destructive actions carry neither.
+ */
+export const commitOperationSchema = z.discriminatedUnion('type', [
+    z.strictObject({
+        ...operationBaseShape,
+        type: z.literal('create'),
+        value: jsonObjectSchema,
+    }),
+    z.strictObject({
+        ...operationBaseShape,
+        type: z.literal('patch'),
+        changes: nonEmptyJsonObjectSchema,
+    }),
+    z.strictObject({
+        ...operationBaseShape,
+        type: z.literal('delete'),
+    }),
+    z.strictObject({
+        ...operationBaseShape,
+        type: z.literal('archive'),
+    }),
+    z.strictObject({
+        ...operationBaseShape,
+        type: z.literal('unarchive'),
+    }),
+]);
+/** Semantic lineage included in the durable intent and its fingerprint. */
+export const commitMetadataSchema = z.strictObject({
+    label: z.string().min(1).max(255).optional(),
+    causedByTaskId: z.string().min(1).max(255).optional(),
+});
+const commitIntentShape = {
+    schemaVersion: z.literal(COMMIT_CONTRACT_VERSION),
+    operations: z.array(commitOperationSchema).min(1).max(500),
+    metadata: commitMetadataSchema.optional(),
+};
+/** The portion of a request that is fingerprinted, preserving operation order. */
+export const commitIntentSchema = z.strictObject(commitIntentShape);
+/** A caller's stable idempotency identity plus the intent it identifies. */
+export const commitRequestSchema = z.strictObject({
+    ...commitIntentShape,
+    idempotencyKey: idempotencyKeySchema,
+});
+/** Returns the exact semantic value that an idempotency fingerprint covers. */
+export function commitIntentOf(request) {
+    const { idempotencyKey, ...intent } = request;
+    void idempotencyKey;
+    return intent;
+}
+// ── Result ───────────────────────────────────────────────────────────────
+const registeredWireErrorCodes = Object.entries(ERROR_CODES)
+    .filter(([, spec]) => spec.surface === 'wire')
+    .map(([code]) => code);
+const policyErrorCodeSchema = z.custom((value) => typeof value === 'string' && /^policy:.+$/.test(value), 'Expected a registered error code or policy:<reason>');
+/** Machine-readable failure code carried by a rejected v2 commit. */
+export const commitErrorCodeSchema = z.union([
+    z.enum(registeredWireErrorCodes),
+    policyErrorCodeSchema,
+]);
+/** Structured capability a rejected commit would require on retry. */
+export const requiredCapabilitySchema = z.strictObject({
+    scope: z.string().min(1),
+    constraints: z.record(z.string(), z.union([z.string(), z.array(z.string())])).optional(),
+    issuer: z.string().min(1).optional(),
+    ttlSeconds: z.number().int().positive().optional(),
+    nonce: z.string().min(1).optional(),
+});
+/** Structured terminal error for a commit that did not apply. */
+export const commitErrorSchema = z.strictObject({
+    code: commitErrorCodeSchema,
+    message: z.string().min(1),
+    field: fieldPathSchema.optional(),
+    requiredCapability: requiredCapabilitySchema.optional(),
+    details: jsonObjectSchema.optional(),
+});
+/** One failed precondition and the smallest current state needed to reconcile. */
+export const commitConflictSchema = z.strictObject({
+    operationId: operationIdSchema,
+    target: entityRefSchema,
+    fields: z.array(fieldPathSchema).max(256),
+    currentValues: jsonObjectSchema,
+    observedAt: syncOffsetSchema,
+});
+const commitReceiptBaseShape = {
+    object: z.literal('commit_receipt'),
+    schemaVersion: z.literal(COMMIT_CONTRACT_VERSION),
+    idempotencyKey: idempotencyKeySchema,
+    commitId: commitIdSchema,
+};
+/**
+ * Terminal result of a commit execution. Expected outcomes are a discriminated
+ * union, so committed, conflicted, and rejected results cannot expose fields
+ * belonging to another state.
+ */
+export const commitReceiptSchema = z.discriminatedUnion('status', [
+    z.strictObject({
+        ...commitReceiptBaseShape,
+        status: z.literal('committed'),
+        syncCursor: syncCursorSchema,
+        operationCount: z.number().int().min(1).max(500),
+    }),
+    z.strictObject({
+        ...commitReceiptBaseShape,
+        status: z.literal('conflicted'),
+        syncCursor: syncCursorSchema,
+        conflicts: z.array(commitConflictSchema).min(1).max(500),
+    }),
+    z.strictObject({
+        ...commitReceiptBaseShape,
+        status: z.literal('rejected'),
+        error: commitErrorSchema,
+    }),
+]);

package/dist/commit/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Stable commit-contract entry point. Import from `@abloatai/ablo/commit`
+ * when validating, persisting, or fingerprinting v2 commit data.
+ */
+export { COMMIT_CONTRACT_VERSION, idempotencyKeySchema, commitIdSchema, operationIdSchema, claimIdSchema, syncOffsetSchema, syncCursorSchema, jsonValueSchema, jsonObjectSchema, entityRefSchema, writePreconditionSchema, commitOperationSchema, commitMetadataSchema, commitIntentSchema, commitRequestSchema, commitIntentOf, commitErrorCodeSchema, requiredCapabilitySchema, commitErrorSchema, commitConflictSchema, commitReceiptSchema, } from './contract.js';
+export type { IdempotencyKey, CommitId, OperationId, ClaimId, SyncOffset, SyncCursor, JsonValue, JsonObject, EntityRef, WritePrecondition, CommitOperationInput, CommitOperation, CommitMetadata, CommitIntentInput, CommitIntent, CommitRequestInput, CommitRequest, CommitErrorCode, RequiredCapability, CommitError, CommitConflict, CommitReceiptInput, CommitReceipt, CommittedCommitReceipt, ConflictedCommitReceipt, RejectedCommitReceipt, } from './contract.js';

package/dist/commit/index.js

@@ -0,0 +1,5 @@
+/**
+ * Stable commit-contract entry point. Import from `@abloatai/ablo/commit`
+ * when validating, persisting, or fingerprinting v2 commit data.
+ */
+export { COMMIT_CONTRACT_VERSION, idempotencyKeySchema, commitIdSchema, operationIdSchema, claimIdSchema, syncOffsetSchema, syncCursorSchema, jsonValueSchema, jsonObjectSchema, entityRefSchema, writePreconditionSchema, commitOperationSchema, commitMetadataSchema, commitIntentSchema, commitRequestSchema, commitIntentOf, commitErrorCodeSchema, requiredCapabilitySchema, commitErrorSchema, commitConflictSchema, commitReceiptSchema, } from './contract.js';

package/dist/core/StoreManager.d.ts

@@ -21,6 +21,8 @@ import { LoadStrategy } from '../types/index.js';
  */
 export declare class StoreManager {
     private stores;
+    /** Strict-durability wrapper for the client write journal and commit outbox. */
+    private transactionStore;
     private syncactionStore;
     private db;
     private isInitialized;

package/dist/core/StoreManager.js

@@ -22,6 +22,8 @@ import { AbloValidationError } from '../errors.js';
  */
 export class StoreManager {
     stores = new Map();
+    /** Strict-durability wrapper for the client write journal and commit outbox. */
+    transactionStore = null;
     syncactionStore = null;
     db = null;
     isInitialized = false;
@@ -46,6 +48,12 @@ export class StoreManager {
         for (const modelName of allModels) {
             await this.createStoreForModel(modelName);
         }
+        // Special stores are created during the IDB upgrade, but unlike model
+        // stores they have no registry metadata and therefore need an explicit
+        // runtime wrapper. Outbox acknowledgement must mean disk-backed, so this
+        // store opts into strict durability rather than the cache stores' relaxed
+        // mode.
+        this.transactionStore = new ObjectStore(this.db, '__transactions', '__transactions', { loadStrategy: LoadStrategy.instant }, 'strict');
         // Initialize SyncactionStore
         this.syncactionStore = new SyncActionStore(this.db);
         await this.syncactionStore.initialize();
@@ -142,6 +150,9 @@ export class StoreManager {
      * Get ObjectStore for a model
      */
     getStore(modelName) {
+        if (modelName === '__transactions') {
+            return this.transactionStore ?? undefined;
+        }
         return this.stores.get(modelName);
     }
     /**
@@ -295,6 +306,7 @@ export class StoreManager {
         for (const store of this.stores.values()) {
             store.markAsClosing();
         }
+        this.transactionStore?.markAsClosing();
         // SyncActionStore is a standalone store that does not extend ObjectStore
         // and has no markAsClosing equivalent, so it is intentionally skipped here.
         // If closing-state coordination is ever needed for sync actions, add it

package/dist/errorCodes.js

@@ -112,7 +112,7 @@ export const ERROR_CODES = {
     jwt_invalid: wire('auth', 401, false, "The bearer JWT failed validation for a reason the server could not classify further. Check the token's issuer, signature, audience, and expiry."),
     jwt_malformed: wire('auth', 401, false, 'The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent.'),
     jwt_missing_issuer: wire('auth', 401, false, 'The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer.'),
-    jwt_issuer_untrusted: wire('auth', 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Register it via POST /v1/trusted-issuers, or check the token's issuer claim."),
+    jwt_issuer_untrusted: wire('auth', 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Check the token's issuer claim, or register the issuer with your deployment before retrying."),
     jwt_signature_invalid: wire('auth', 401, false, "The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token)."),
     jwt_audience_mismatch: wire('auth', 401, false, "The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with."),
     jwt_missing_subject: wire('auth', 401, false, 'The bearer JWT has no `sub` (subject) claim to identify the user.'),
@@ -161,7 +161,11 @@ export const ERROR_CODES = {
     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).'),
     // ── stale context / idempotency (409) ──────────────────────────────
-    stale_context: wire('conflict', 409, true, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
+    // Not retryable at the transport: the rejected request carries its frozen
+    // `readAt`, so resending the identical payload can never succeed. Recovery
+    // is a caller-level re-read that produces a NEW request with a fresh
+    // watermark — the same shape as `claim_conflict`.
+    stale_context: wire('conflict', 409, false, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
     // Raised by the functional `update(id, current => next)` form once its
     // internal reconcile budget is exhausted, because the row stayed continuously
     // contended. The SDK has already retried; the caller decides whether to back

package/dist/index.d.ts

@@ -55,10 +55,16 @@ export type { MutationExecutor } from './interfaces/index.js';
 export type { ModelUpdater, ContentionOptions } from './client/functionalUpdate.js';
 export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
+export type { AbloReads } from './client/Ablo.js';
 export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
 export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
+export type { CommitOutboxRecord, CommitOutboxStore, } from './transactions/commitOutboxStore.js';
+export { durableCommitEnvelopeSchema, } from './transactions/commitEnvelope.js';
+export type { CommitOutboxScope, DurableCommitEnvelope, } from './transactions/commitEnvelope.js';
+export { durableHttpCommitEnvelopeSchema, } from './transactions/httpCommitEnvelope.js';
+export type { DurableHttpCommitEnvelope, } from './transactions/httpCommitEnvelope.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';

package/dist/index.js

@@ -63,6 +63,8 @@ export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
 // `AbloHttpClient` type, which is the return type of that call.
 export {} from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
+export { durableCommitEnvelopeSchema, } from './transactions/commitEnvelope.js';
+export { durableHttpCommitEnvelopeSchema, } from './transactions/httpCommitEnvelope.js';
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as

package/dist/interfaces/index.d.ts

@@ -200,8 +200,8 @@ export interface CommitResult {
  * - `idempotencyKey` — when set, the server caches the response for 24 hours and
  *   returns the cached result on any retry using the same key. When omitted, the
  *   SDK generates a fresh UUID per mutation, so every call is retry-safe by
- *   default. Pass `{ idempotencyKey: null }` for the rare case where you want a
- *   write that is not retry-safe.
+ *   default. `null` is retained for source compatibility and is treated like
+ *   omission; write retries never opt out of request identity.
  * - `label` — a human-readable tag recorded with the mutation for debugging, such
  *   as "nightly cleanup" or "user click".
  */

package/dist/mutators/UndoManager.d.ts

@@ -250,6 +250,8 @@ export declare class UndoManager<S extends Schema> {
     private readonly store;
     private readonly organizationId;
     private readonly scopes;
+    /** The options each scope was constructed with, for the mismatch warning below. */
+    private readonly creationOptions;
     constructor(schema: S, store: SyncStoreContract, organizationId: string);
     getScope(name: string, options?: UndoScopeOptions): UndoScope<S>;
     clearAll(): void;

package/dist/mutators/UndoManager.js

@@ -569,6 +569,8 @@ export class UndoManager {
     store;
     organizationId;
     scopes = new Map();
+    /** The options each scope was constructed with, for the mismatch warning below. */
+    creationOptions = new Map();
     constructor(schema, store, organizationId) {
         this.schema = schema;
         this.store = store;
@@ -579,6 +581,36 @@ export class UndoManager {
         if (!scope) {
             scope = new UndoScope(this.schema, this.store, this.organizationId, options);
             this.scopes.set(name, scope);
+            this.creationOptions.set(name, options);
+            return scope;
+        }
+        // A scope keeps the options it was created with; later calls cannot change
+        // them. Requesting the shared scope with no options is the normal pattern
+        // and stays silent — but passing options that conflict with the creation
+        // values means one caller believes it configured a scope that another
+        // caller already configured differently, which is how a surface silently
+        // ends up with, say, no stream recording. Surface that instead of letting
+        // it pass.
+        if (options) {
+            const created = this.creationOptions.get(name);
+            const conflicts = [];
+            if (options.recordFromStream !== undefined &&
+                options.recordFromStream !== (created?.recordFromStream ?? false)) {
+                conflicts.push('recordFromStream');
+            }
+            if (options.maxHistory !== undefined && options.maxHistory !== (created?.maxHistory ?? 100)) {
+                conflicts.push('maxHistory');
+            }
+            if (options.conflictPolicy !== undefined &&
+                options.conflictPolicy !== (created?.conflictPolicy ?? DEFAULT_UNDO_CONFLICT_POLICY)) {
+                conflicts.push('conflictPolicy');
+            }
+            if (conflicts.length > 0) {
+                getContext().logger.warn(`The undo scope "${name}" already exists with different options — ` +
+                    `${conflicts.join(', ')} cannot be changed after creation and the requested ` +
+                    `values are ignored. Create the scope with its full options before any ` +
+                    `caller requests it without them, or use a differently named scope.`);
+            }
         }
         return scope;
     }

package/dist/react/useAblo.d.ts

@@ -1,4 +1,4 @@
-import type { Ablo, ModelClaim } from '../client/Ablo.js';
+import type { Ablo, AbloReads, ModelClaim } from '../client/Ablo.js';
 import type { ModelOperations } from '../client/createModelProxy.js';
 import type { SchemaRecord } from '../schema/schema.js';
 import type { ResolveSchema } from '../types/global.js';
@@ -11,8 +11,8 @@ import type { ResolveSchema } from '../types/global.js';
 type DefaultModels = ResolveSchema extends {
     models: infer M;
 } ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
-type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => ModelOperations<T, C>;
-type AbloSelector<R extends SchemaRecord, T> = (ablo: Ablo<R>) => T;
+type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: AbloReads<R>) => ModelOperations<T, C>;
+type AbloSelector<R extends SchemaRecord, T> = (ablo: AbloReads<R>) => T;
 export interface UseAbloModelOptions<T> {
     /**
      * An initial row, usually from a server component or a route loader. The hook
@@ -48,7 +48,9 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * if (!ablo) return <Loading />;
  * const doc = await ablo.documents.retrieve({ id }); // async server read
  *
- * // Reactive selector (a synchronous local snapshot):
+ * // Reactive selector (a synchronous local snapshot). The selector's reads
+ * // are typed as snapshot rows — data fields + computeds, no relation
+ * // accessors — matching what the hook actually returns:
  * const doc = useAblo((ablo) => ablo.documents.get(id)) ?? serverDoc;
  * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
  *

package/dist/react/useAblo.js

@@ -5,6 +5,24 @@ import { getModelClientMeta } from '../client/createModelProxy.js';
 import { Model } from '../Model.js';
 import { useReactive } from './useReactive.js';
 const EMPTY_CLAIMS = Object.freeze([]);
+/**
+ * Restore the caller's schema generics on the context-held engine. React
+ * context erases generics (see `AbloInternalContextValue.engine`), so this is
+ * the one deliberate rebind point: the runtime value is the fully typed
+ * client, and `R` is the compile-time view the calling hook declared.
+ */
+function rebindEngine(engine) {
+    return engine;
+}
+/**
+ * The same rebind viewed through the reactive-read surface — the identical
+ * runtime object, with model reads typed as snapshot rows, because everything
+ * a selector returns is converted through `snapshotValue` before the hook
+ * hands it back.
+ */
+function reactiveReads(engine) {
+    return rebindEngine(engine);
+}
 function readModelResult(engine, modelClient, id, initial) {
     if (!modelClient || id === undefined) {
         return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
@@ -43,7 +61,7 @@ export function useAblo(modelOrSelect, id, options) {
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
         ? engine
-            ? modelOrSelect(engine)
+            ? modelOrSelect(reactiveReads(engine))
             : undefined
         : typeof modelOrSelect === 'function'
             ? undefined
@@ -66,7 +84,11 @@ export function useAblo(modelOrSelect, id, options) {
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
             return undefined;
         }
-        return snapshotValue(modelOrSelect(engine));
+        // The selector runs against the real engine — reads inside it return the
+        // pool's model instances. `snapshotValue` then converts the RESULT to
+        // plain snapshot rows, which is what the selector's `AbloReads`
+        // parameter type already promised.
+        return snapshotValue(modelOrSelect(reactiveReads(engine)));
     });
     const modelResult = useReactive(() => {
         void claimVersion;
@@ -76,5 +98,5 @@ export function useAblo(modelOrSelect, id, options) {
         return selected;
     if (modelOrSelect)
         return modelResult;
-    return engine;
+    return engine === null ? null : rebindEngine(engine);
 }

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 InferModel, type InferCreate, 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, } 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, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';

package/dist/schema/schema.d.ts

@@ -162,8 +162,38 @@ Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & Bas
  * to `slide.layers` would have no effect at runtime.
  */
 export type InferRelations<S extends Schema, R extends RelationRecord> = string extends keyof R ? unknown : {
-    readonly [K in keyof R]: R[K] extends RelationDef<infer Type, infer Target, infer _F, infer _O> ? Target extends keyof S['models'] ? Type extends 'hasMany' ? InferModel<S, Target>[] : Type extends 'hasOne' | 'belongsTo' ? InferModel<S, Target> | undefined : never : never : never;
+    readonly [K in keyof R]: R[K] extends RelationDef<infer Type, infer Target> ? Target extends keyof S['models'] ? Type extends 'hasMany' ? InferModel<S, Target>[] : Type extends 'hasOne' | 'belongsTo' ? InferModel<S, Target> | undefined : never : never : never;
 };
+/**
+ * The row shape a reactive read returns: the model's data fields, base fields,
+ * and schema computed getters — WITHOUT relation accessors and WITHOUT model
+ * methods. Derived from the model definition, exactly like {@link InferModel},
+ * mirroring what `toReactiveSnapshot()` produces at runtime.
+ *
+ * Relations (`hasMany` / `belongsTo`) are store-backed getters that exist only
+ * on the pool's model instances, so a reactive row honestly omits them —
+ * reading `row.layers` is a compile error instead of a silent `undefined`.
+ * Compose relations through a selector or hook instead.
+ *
+ * The same pairing other data layers converged on: Zero's data-only `Row<...>`
+ * with relations added per-query, Prisma's scalar-only model types with
+ * `GetPayload<{ include }>`, mobx-state-tree's `Instance<T>` / `SnapshotOut<T>`.
+ */
+export type InferRow<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, RelationRecord, infer C> ? // Same reserved-field guard as InferModel — see the comment there.
+Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & InferComputed<C> : never;
+/**
+ * The reactive-row companion to {@link Model}. Once your project's
+ * `ablo/register.ts` registers the schema, a single argument is all it takes:
+ *
+ * ```ts
+ * type SlideRow = Row<'slides'>;    // data fields + computeds, no relations
+ * type Slide    = Model<'slides'>;  // the pool's model instance
+ * ```
+ *
+ * Without that registration, or for a second schema, pass the schema
+ * explicitly: `Row<typeof schema, 'slides'>`.
+ */
+export type Row<A, B = never> = [B] extends [never] ? A extends keyof RegisteredSchema['models'] ? InferRow<RegisteredSchema, A> : never : A extends Schema ? InferRow<A, B extends keyof A['models'] ? B : never> : never;
 /**
  * Infer the return types of computed getters.
  * Maps each computed function's return type into a readonly property.

package/dist/stores/ObjectStore.d.ts

@@ -4,6 +4,15 @@
  */
 import type { ModelMetadata } from '../types/index.js';
 import type { ObjectStoreContract } from './ObjectStoreContract.js';
+/**
+ * IDB transaction options type (TypeScript's lib.dom.d.ts may be outdated)
+ * durability: 'relaxed' provides ~16x write performance improvement
+ * by not requiring fsync on each transaction commit.
+ * Safe for optimistic sync engines that can recover from server state.
+ */
+interface IDBTransactionOptionsWithDurability {
+    durability?: 'default' | 'relaxed' | 'strict';
+}
 /**
  * An IndexedDB-backed store holding the records of a single model.
  *
@@ -21,8 +30,11 @@ export declare class ObjectStore implements ObjectStoreContract {
     protected modelName: string;
     protected storeName: string;
     protected metadata: ModelMetadata;
+    private readonly writeDurability;
     private isClosing;
-    constructor(db: IDBDatabase, modelName: string, storeName: string, metadata: ModelMetadata);
+    constructor(db: IDBDatabase, modelName: string, storeName: string, metadata: ModelMetadata, writeDurability?: NonNullable<IDBTransactionOptionsWithDurability['durability']>);
+    /** Insert without replacing an existing key (used by the commit outbox). */
+    add(data: Record<string, unknown>): Promise<void>;
     /**
      * Mark this store as closing to prevent new operations
      */
@@ -100,3 +112,4 @@ export declare class ObjectStore implements ObjectStoreContract {
      */
     performMaintenance(): Promise<void>;
 }
+export {};

package/dist/stores/ObjectStore.js

@@ -19,12 +19,35 @@ export class ObjectStore {
     modelName;
     storeName;
     metadata;
+    writeDurability;
     isClosing = false;
-    constructor(db, modelName, storeName, metadata) {
+    constructor(db, modelName, storeName, metadata, writeDurability = 'relaxed') {
         this.db = db;
         this.modelName = modelName;
         this.storeName = storeName;
         this.metadata = metadata;
+        this.writeDurability = writeDurability;
+    }
+    /** Insert without replacing an existing key (used by the commit outbox). */
+    async add(data) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.reject(new Error('IndexedDB not available (closing or invalid)'));
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readwrite', {
+                    durability: this.writeDurability,
+                });
+                const store = tx.objectStore(this.storeName);
+                const request = store.add(data);
+                tx.oncomplete = () => { resolve(); };
+                tx.onerror = () => { reject(tx.error || new Error('IndexedDB transaction error')); };
+                request.onerror = () => { reject(request.error || new Error('IndexedDB request error')); };
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
     }
     /**
      * Mark this store as closing to prevent new operations
@@ -65,7 +88,7 @@ export class ObjectStore {
             try {
                 // Use relaxed durability for ~16x write performance (safe with optimistic sync)
                 const tx = this.db.transaction([this.storeName], 'readwrite', {
-                    durability: 'relaxed',
+                    durability: this.writeDurability,
                 });
                 const store = tx.objectStore(this.storeName);
                 const request = store.put(data);
@@ -169,7 +192,7 @@ export class ObjectStore {
             try {
                 // Use relaxed durability for ~16x write performance (safe with optimistic sync)
                 const tx = this.db.transaction([this.storeName], 'readwrite', {
-                    durability: 'relaxed',
+                    durability: this.writeDurability,
                 });
                 const store = tx.objectStore(this.storeName);
                 const request = store.delete(id);
@@ -205,7 +228,7 @@ export class ObjectStore {
             try {
                 // Use relaxed durability for ~16x write performance (safe with optimistic sync)
                 const tx = this.db.transaction([this.storeName], 'readwrite', {
-                    durability: 'relaxed',
+                    durability: this.writeDurability,
                 });
                 const store = tx.objectStore(this.storeName);
                 const request = store.clear();

package/dist/stores/ObjectStoreContract.d.ts

@@ -15,6 +15,8 @@
  * a silent failure in a caller.
  */
 export interface ObjectStoreContract {
+    /** Insert a record only when its key is absent. */
+    add(data: Record<string, unknown>): Promise<void>;
     /** Insert or update a record. The record must carry an `id` field. */
     put(data: Record<string, unknown>): Promise<void>;
     /** Look up a record by id. */

package/dist/surface.d.ts

@@ -30,7 +30,7 @@ export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orde
  * The keys of the client constructor options, {@link AbloOptions}. Only
  * `schema` is required; every other key is optional.
  */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "databaseUrl", "persistence", "commitOutbox", "commitOutboxScope", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -58,6 +58,8 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'authEndpoint',
     'databaseUrl',
     'persistence',
+    'commitOutbox',
+    'commitOutboxScope',
     'transport',
     'debug',
     'logLevel',