@abloatai/transaction 0.47.0 → 0.49.0

package/src/auth/capabilityLifecycle.ts

@@ -4,7 +4,7 @@ import {
   hasWireCode,
   translateHttpError,
 } from '../errors.js';
-import { capabilityScopeSchema } from './capability.js';
+import { effectiveAuthoritySchema } from './capability.js';
 import type {
   RotateSessionParams,
   SessionRevocation,
@@ -27,7 +27,8 @@ export const capabilityRotationResponseSchema = z.object({
   token: z.string().trim().min(1),
   expiresAt: z.iso.datetime().nullable(),
   organizationId: z.string().min(1),
-  scope: capabilityScopeSchema,
+  branchRoot: z.boolean().default(false),
+  scope: effectiveAuthoritySchema,
   rotatedFrom: z.object({
     capabilityId: z.string().min(1),
     expiresAt: z.iso.datetime(),

package/src/auth/identity.ts

@@ -34,6 +34,7 @@ import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { CredentialProvider } from './credentialResult.js';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './apiKey.js';
 import type { DeliveryPartitionRoute } from './deliveryPartition.js';
+import type { EffectiveAuthority } from './capability.js';
 
 export interface IdentityResolveInput {
   readonly options: {
@@ -71,6 +72,8 @@ export interface ResolvedIdentity {
   readonly syncGroups: readonly string[] | undefined;
   readonly participantKind: ParticipantKind;
   readonly deliveryPartition: DeliveryPartitionRoute | null;
+  /** Effective authority confirmed by the server (or explicit self-hosted configuration). */
+  readonly authority: EffectiveAuthority;
   /** Set only on the hosted-cloud path; the caller keeps it to stop refreshes on shutdown. */
   readonly refreshScheduler: RefreshScheduler | null;
 }
@@ -195,6 +198,16 @@ export async function resolveParticipantIdentity(
         syncGroups: options.syncGroups,
         participantKind: kind,
         deliveryPartition: null,
+        authority: {
+          organizationId: accountScope,
+          projectId: accountScope,
+          branchId: internalOptions.branchId ?? null,
+          participantKind: kind,
+          participantId: userId,
+          operations: [],
+          syncGroups: options.syncGroups ?? [],
+          deliveryPartition: null,
+        },
         refreshScheduler: null,
       };
     }
@@ -246,6 +259,7 @@ async function resolveViaIdentity(
     syncGroups: mergedSyncGroups,
     participantKind: identity.participantKind,
     deliveryPartition: identity.deliveryPartition,
+    authority: identity.authority,
     refreshScheduler: null,
   };
 }
@@ -322,7 +336,7 @@ async function resolveHosted(input: HostedInput): Promise<ResolvedIdentity> {
     accountScope: exchange.scope.organizationId,
     projectId: exchange.scope.projectId ?? exchange.scope.organizationId,
     branchId: exchange.scope.branchId,
-    branchRoot: exchange.scope.branchRoot,
+    branchRoot: exchange.branchRoot,
     // teamIds isn't needed because the server already encoded
     // team-level access into scope.syncGroups.
     teamIds: undefined,
@@ -330,6 +344,7 @@ async function resolveHosted(input: HostedInput): Promise<ResolvedIdentity> {
     syncGroups: exchange.scope.syncGroups,
     participantKind: input.kind,
     deliveryPartition: exchange.scope.deliveryPartition,
+    authority: exchange.scope,
     refreshScheduler,
   };
 }

package/src/auth/index.ts

@@ -74,6 +74,7 @@ export {
   capabilityOperationSchema,
   capabilityCanSchema,
   capabilityCanSchemaFor,
+  effectiveAuthoritySchema,
   capabilityScopeSchema,
   capabilityRequestSchema,
   capabilityMintResponseSchema,
@@ -88,6 +89,7 @@ export type {
   CapabilityOperation,
   CapabilityCan,
   CapabilityGrant,
+  EffectiveAuthority,
   CapabilityScope,
   CapabilityMintResponse,
   CapabilityRequest,

package/src/auth/schemas.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { participantKindSchema } from '../coordination/schema.js';
 import {
   capabilityMintResponseSchema,
+  effectiveAuthoritySchema,
   grantedOperationSchema,
   type CapabilityMintResponse,
 } from './capability.js';
@@ -26,6 +27,8 @@ export const IdentityResolveResponseSchema = z.object({
   branchRoot: z.boolean().default(false),
   syncGroups: z.array(z.string()),
   deliveryPartition: deliveryPartitionRouteSchema.nullable().default(null),
+  /** Canonical server-confirmed authority of the authenticated credential. */
+  authority: effectiveAuthoritySchema,
   userMeta: z.record(z.string(), z.unknown()),
 });
 

package/src/auth/sessionMint.ts

@@ -93,7 +93,6 @@ export async function mintSession<S extends SchemaRecord>(
         organizationId: res.organizationId,
         projectId: res.projectId,
         branchId: res.branchId,
-        branchRoot: res.branchRoot,
         syncGroups: res.syncGroups,
         operations: res.operations,
         participantKind: 'user',

package/src/branches.ts

@@ -87,6 +87,28 @@ export const branchParentCompatibilitySchema = z.enum([
 ]);
 export type BranchParentCompatibility = z.infer<typeof branchParentCompatibilitySchema>;
 
+/**
+ * The one ownership/storage vocabulary for durable branch data.
+ * Missing configuration is explicit (`unbound`), never inferred as hosted.
+ */
+export const branchStorageSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('unbound') }).strict(),
+  z.object({
+    kind: z.literal('customer'),
+    transport: z.enum(['direct', 'endpoint']),
+    status: z.enum(['unverified', 'active', 'rejected']),
+  }).strict(),
+  z.object({
+    kind: z.literal('internal'),
+    implementation: z.enum(['log', 'tables']),
+  }).strict(),
+  z.object({
+    kind: z.literal('blocked'),
+    reason: z.literal('orphaned_external_marker'),
+  }).strict(),
+]);
+export type BranchStorage = z.infer<typeof branchStorageSchema>;
+
 export const branchStatusSchemaSummarySchema = z
   .object({
     active: z.boolean(),
@@ -101,8 +123,8 @@ export const branchStatusSchemaSummarySchema = z
 
 export const branchStatusDataSourceSchema = z
   .object({
-    kind: z.enum(['hosted', 'direct', 'endpoint']),
-    status: z.enum(['unverified', 'active', 'rejected']).nullable(),
+    connection: z.enum(['direct', 'endpoint']),
+    status: z.enum(['unverified', 'active', 'rejected']),
     host: z.string().nullable(),
     database: z.string().nullable(),
     cursor: z.string().nullable(),
@@ -111,7 +133,8 @@ export const branchStatusDataSourceSchema = z
     last_success_at: z.string().nullable(),
     last_error: z.string().nullable(),
   })
-  .strict();
+  .strict()
+  .nullable();
 
 export const branchStatusBlockerSchema = z
   .object({
@@ -127,6 +150,7 @@ export const branchStatusResponseSchema = z
     branch: branchResponseSchema,
     ready: z.boolean(),
     schema: branchStatusSchemaSummarySchema,
+    storage: branchStorageSchema,
     data_source: branchStatusDataSourceSchema,
     blockers: z.array(branchStatusBlockerSchema).readonly(),
   })

package/src/commitRecordRuntime.ts

@@ -0,0 +1,245 @@
+import {
+  DEFAULT_TRACK_ON_STALE,
+  type CommitReadSetEntry,
+  type ReadDependency,
+  type ReadSetEntry,
+  type TrackDependency,
+} from './coordination/schema.js';
+import {
+  commitRecordIdentity,
+  publishCommitRecord,
+  type ReadSetContext,
+} from './readSetContext.js';
+import {
+  commitRecordSchema,
+  type CommitOperationBody,
+  type CommitReceiptWire,
+} from './wire/commit.js';
+
+interface HttpCommitObservation {
+  readonly receipt: CommitReceiptWire;
+  readonly method: string;
+  readonly path: string;
+  readonly body: unknown;
+}
+
+interface WebSocketCommitObservation {
+  readonly receipt: CommitReceiptWire;
+  readonly operations: readonly {
+    readonly type: string;
+    readonly model: string;
+    readonly id: string;
+    readonly input?: Record<string, unknown>;
+    readonly claimId?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: CommitOperationBody['onStale'] | null;
+    readonly fenceToken?: number | null;
+  }[];
+  readonly reads?: readonly ReadDependency[] | null;
+  readonly track?: readonly TrackDependency[] | null;
+}
+
+function commitEntry(dependency: ReadDependency): CommitReadSetEntry {
+  return {
+    target: 'group' in dependency
+      ? { scope: 'group', group: dependency.group }
+      : {
+          scope: 'row',
+          model: dependency.model,
+          id: dependency.id,
+          ...(dependency.fields ? { fields: dependency.fields } : {}),
+        },
+    watermark: dependency.readAt,
+    lifetime: 'commit',
+    onStale: dependency.onStale ?? 'reject',
+  };
+}
+
+function persistedEntry(
+  dependency: TrackDependency,
+  defaultWatermark: number,
+): ReadSetEntry {
+  return {
+    target: 'group' in dependency
+      ? { scope: 'group', group: dependency.group }
+      : { scope: 'row', model: dependency.model, id: dependency.id },
+    watermark: dependency.readAt ?? defaultWatermark,
+    lifetime: 'persisted',
+    onStale: dependency.onStale ?? DEFAULT_TRACK_ON_STALE,
+  };
+}
+
+function bodyRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function retainedOperations(operations: readonly CommitOperationBody[]) {
+  return operations.map(({ data: _data, ...operation }) => ({
+    ...operation,
+    data: { retention: 'redacted' as const },
+  }));
+}
+
+function commitEvidence(
+  receipt: CommitReceiptWire,
+  operations: readonly CommitOperationBody[],
+  transport: 'http' | 'websocket',
+) {
+  return {
+    attempts: [{
+      id: receipt.clientTxId,
+      observedAt: receipt.createdAt,
+      transport,
+      kind: 'execution' as const,
+    }],
+    actor: {
+      kind: receipt.authority.participantKind,
+      id: receipt.authority.participantId,
+    },
+    // A receipt does not prove which live claim grant the server matched.
+    // Durable server records populate this from the claim gate instead.
+    claims: [],
+  };
+}
+
+function operationFromModelRequest(
+  observation: HttpCommitObservation,
+  body: Record<string, unknown>,
+): CommitOperationBody[] {
+  const segments = observation.path.split('/').filter(Boolean);
+  const modelIndex = segments.indexOf('models');
+  if (modelIndex < 0) return [];
+  const model = decodeURIComponent(segments[modelIndex + 1] ?? '');
+  const pathId = segments[modelIndex + 2];
+  const action = observation.method === 'POST'
+    ? 'create'
+    : observation.method === 'DELETE'
+      ? 'delete'
+      : 'update';
+  return [{
+    action,
+    model,
+    ...(pathId ? { id: decodeURIComponent(pathId) } : typeof body.id === 'string' ? { id: body.id } : {}),
+    ...(body.data && typeof body.data === 'object'
+      ? { data: body.data as Record<string, unknown> }
+      : {}),
+    ...(typeof body.readAt === 'number' ? { readAt: body.readAt } : {}),
+    ...(typeof body.onStale === 'string'
+      ? { onStale: body.onStale as CommitOperationBody['onStale'] }
+      : {}),
+    ...(typeof body.fenceToken === 'number' ? { fenceToken: body.fenceToken } : {}),
+    ...(typeof body.claim === 'string' ? { claimId: body.claim } : {}),
+  }];
+}
+
+/** @internal Joins exact HTTP request and receipt projections. */
+export function recordHttpCommitReceipt(
+  context: ReadSetContext | undefined,
+  observation: HttpCommitObservation,
+): void {
+  if (!context?.getStore()) return;
+  const body = bodyRecord(observation.body);
+  const operations = Array.isArray(body.operations)
+    ? body.operations as CommitOperationBody[]
+    : operationFromModelRequest(observation, body);
+  const reads = Array.isArray(body.reads) ? body.reads as ReadDependency[] : [];
+  const track = Array.isArray(body.track) ? body.track as TrackDependency[] : [];
+  const readSet: ReadSetEntry[] = reads.map(commitEntry);
+  for (const operation of operations) {
+    if (typeof operation.readAt !== 'number' || !operation.id) continue;
+    readSet.push(commitEntry({
+      model: operation.model,
+      id: operation.id,
+      readAt: operation.readAt,
+      onStale: operation.onStale ?? 'reject',
+    }));
+  }
+  readSet.push(...track.map((entry) => persistedEntry(entry, observation.receipt.lastSyncId)));
+
+  const record = commitRecordSchema.parse({
+    id: commitRecordIdentity(context, observation.receipt.clientTxId).id,
+    createdAt: observation.receipt.createdAt,
+    status: observation.receipt.status,
+    statusAt: observation.receipt.statusAt,
+    lastSyncId: observation.receipt.lastSyncId,
+    ...(observation.receipt.correlationId
+      ? { correlationId: observation.receipt.correlationId }
+      : {}),
+    readSet,
+    operations: retainedOperations(operations),
+    ...commitEvidence(observation.receipt, operations, 'http'),
+    authority: observation.receipt.authority,
+    receipt: {
+      clientTxId: observation.receipt.clientTxId,
+      serverTxId: observation.receipt.serverTxId,
+      ops: observation.receipt.ops,
+      ...(observation.receipt.notifications
+        ? { notifications: observation.receipt.notifications }
+        : {}),
+      ...(observation.receipt.missingIds
+        ? { missingIds: observation.receipt.missingIds }
+        : {}),
+    },
+  });
+  publishCommitRecord(context, record);
+}
+
+/** @internal Joins an exact commit frame and its authoritative WS receipt. */
+export function recordWebSocketCommitReceipt(
+  context: ReadSetContext | undefined,
+  observation: WebSocketCommitObservation,
+): void {
+  if (!context?.getStore()) return;
+  const operations: CommitOperationBody[] = observation.operations.map((operation) => ({
+    action: operation.type.toLowerCase() as CommitOperationBody['action'],
+    model: operation.model,
+    id: operation.id,
+    ...(operation.input ? { data: operation.input } : {}),
+    ...(operation.claimId ? { claimId: operation.claimId } : {}),
+    ...(typeof operation.readAt === 'number' ? { readAt: operation.readAt } : {}),
+    ...(operation.onStale ? { onStale: operation.onStale } : {}),
+    ...(typeof operation.fenceToken === 'number'
+      ? { fenceToken: operation.fenceToken }
+      : {}),
+  }));
+  const readSet: ReadSetEntry[] = (observation.reads ?? []).map(commitEntry);
+  for (const operation of operations) {
+    if (typeof operation.readAt !== 'number' || !operation.id) continue;
+    readSet.push(commitEntry({
+      model: operation.model,
+      id: operation.id,
+      readAt: operation.readAt,
+      onStale: operation.onStale ?? 'reject',
+    }));
+  }
+  readSet.push(...(observation.track ?? []).map((entry) =>
+    persistedEntry(entry, observation.receipt.lastSyncId)));
+  const record = commitRecordSchema.parse({
+    id: commitRecordIdentity(context, observation.receipt.clientTxId).id,
+    createdAt: observation.receipt.createdAt,
+    status: observation.receipt.status,
+    statusAt: observation.receipt.statusAt,
+    lastSyncId: observation.receipt.lastSyncId,
+    ...(observation.receipt.correlationId
+      ? { correlationId: observation.receipt.correlationId }
+      : {}),
+    readSet,
+    operations: retainedOperations(operations),
+    ...commitEvidence(observation.receipt, operations, 'websocket'),
+    authority: observation.receipt.authority,
+    receipt: {
+      clientTxId: observation.receipt.clientTxId,
+      serverTxId: observation.receipt.serverTxId,
+      ops: observation.receipt.ops,
+      ...(observation.receipt.notifications
+        ? { notifications: observation.receipt.notifications }
+        : {}),
+      ...(observation.receipt.missingIds
+        ? { missingIds: observation.receipt.missingIds }
+        : {}),
+    },
+  });
+  publishCommitRecord(context, record);
+}

package/src/coordination/index.ts

@@ -22,6 +22,17 @@ export {
   targetRefSchema,
   // Layer 3 — optimistic stale-context
   onStaleModeSchema,
+  MAX_READ_SET_ENTRIES,
+  readSetWatermarkSchema,
+  readSetRowTargetSchema,
+  readSetGroupTargetSchema,
+  commitReadSetTargetSchema,
+  persistedReadSetRowTargetSchema,
+  persistedReadSetTargetSchema,
+  commitReadSetEntrySchema,
+  persistedReadSetEntrySchema,
+  readSetEntrySchema,
+  readSetSchema,
   writeGuardSchema,
   staleNotificationSchema,
   rowStaleNotificationSchema,
@@ -29,7 +40,10 @@ export {
   stalePropagationSchema,
 
   readDependencySchema,
+  readDependencyListSchema,
+  readSetProjectionEntryCount,
   trackDependencySchema,
+  trackDependencyListSchema,
   // Layer 2 — pessimistic claim / claim-lease
   claimStatusSchema,
   wireClaimStatusSchema,
@@ -103,6 +117,15 @@ export type {
   TargetRef,
   // Layer 3 — optimistic stale-context
   OnStaleMode,
+  ReadSetWatermark,
+  ReadSetRowTarget,
+  ReadSetGroupTarget,
+  CommitReadSetTarget,
+  PersistedReadSetTarget,
+  CommitReadSetEntry,
+  PersistedReadSetEntry,
+  ReadSetEntry,
+  ReadSet,
   WriteGuard,
   StaleNotification,
   RowStaleNotification,
@@ -179,6 +202,7 @@ export type {
 } from './locator.js';
 export {
   batchFence,
+  claimIdFor,
   fenceTokenFor,
   isTargetTuple,
   subTarget,
@@ -186,4 +210,3 @@ export {
   modelTarget,
   streamTarget,
 } from './locator.js';
-

package/src/coordination/locator.ts

@@ -198,3 +198,20 @@ export function fenceTokenFor(
     ? fence.token
     : null;
 }
+
+/**
+ * The claim identity an operation carries when it writes the row named by a
+ * held claim. Like the fence token, a claim id cannot travel to another row.
+ */
+export function claimIdFor(
+  source: EntityLocator | null | undefined,
+  claimId: string | null | undefined,
+  model: string,
+  id: string | null,
+): string | null {
+  if (source == null || claimId == null || id === null) return null;
+  const target = modelTarget(source);
+  return model.toLowerCase() === target.model.toLowerCase() && id === target.id
+    ? claimId
+    : null;
+}