@abloatai/ablo 0.26.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/context.d.ts

@@ -1,9 +1,11 @@
 /**
- * Module-level context accessor
+ * Module-level accessor for the sync engine's shared context.
  *
- * Set once during SDK initialization via `initSyncEngine(context)`.
- * All internal SDK files access dependencies through `getContext()`.
- * This avoids threading context through every constructor.
+ * The context is set once, during initialization, by {@link initSyncEngine}.
+ * Code throughout the package reaches its shared dependencies — logger,
+ * observability, online-status detector, configuration, and the mutation
+ * executor — through {@link getContext} instead of receiving them through every
+ * constructor.
  */
 import type { SyncEngineContext } from './SyncEngineContext.js';
 /**

package/dist/context.js

@@ -1,9 +1,11 @@
 /**
- * Module-level context accessor
+ * Module-level accessor for the sync engine's shared context.
  *
- * Set once during SDK initialization via `initSyncEngine(context)`.
- * All internal SDK files access dependencies through `getContext()`.
- * This avoids threading context through every constructor.
+ * The context is set once, during initialization, by {@link initSyncEngine}.
+ * Code throughout the package reaches its shared dependencies — logger,
+ * observability, online-status detector, configuration, and the mutation
+ * executor — through {@link getContext} instead of receiving them through every
+ * constructor.
  */
 import { noopLogger, noopObservability, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from './SyncEngineContext.js';
 let _context = null;

package/dist/coordination/index.d.ts

@@ -1,13 +1,15 @@
 /**
- * `@abloatai/ablo/coordination` — the canonical wire schema for the three
- * coordination layers (presence, pessimistic claims, optimistic stale-context).
- * See `./schema.ts` for the model and the per-layer schemas.
+ * The `@abloatai/ablo/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
  *
- * Explicit named list (not `export *`): every addition to schema.ts must be a
- * deliberate export decision here, so new symbols don't silently become public
- * API of the published package.
+ * 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, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
+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 { 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, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.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';

package/dist/coordination/index.js

@@ -1,11 +1,13 @@
 /**
- * `@abloatai/ablo/coordination` — the canonical wire schema for the three
- * coordination layers (presence, pessimistic claims, optimistic stale-context).
- * See `./schema.ts` for the model and the per-layer schemas.
+ * The `@abloatai/ablo/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
  *
- * Explicit named list (not `export *`): every addition to schema.ts must be a
- * deliberate export decision here, so new symbols don't silently become public
- * API of the published package.
+ * 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.
  */
 // Runtime schemas + helpers.
 export { 
@@ -14,16 +16,16 @@ targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participant
 // Layer 3 — optimistic stale-context
 onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, 
 // Layer 2 — pessimistic claim / claim-lease
-claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, 
+claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, 
 // Read interest — area-of-interest navigation
 updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, 
 // Commit operation — carries the optimistic write-guard
 commitOperationTypeSchema, commitOperationSchema, 
 // Layer 1 — presence
 presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
-// Conflict-policy runtime — the engine detects, the policy decides. Lives in
-// `../policy/types.js` (a dependency-free leaf: its only imports are types),
-// exported here so a server-side consumer reaches the coordination vocabulary
-// AND its default resolution through one leaf subpath instead of the root
-// barrel (which would evaluate the whole browser client stack in Node).
+// Conflict-policy runtime — the engine detects a conflict, and the policy
+// decides what to do about it. These are re-exported here so that server-side
+// code can reach both the coordination vocabulary and its default conflict
+// resolution from this one subpath, without importing the full client from the
+// package root.
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';