@abloatai/transaction 0.56.0 → 0.58.0

package/src/schema/subject.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+/**
+ * Row/subject authorization for one model.
+ *
+ * A row is authorized exactly when the authenticated request carries the sync
+ * group `${group}:${row[field]}`. Both values are plain schema data so the rule
+ * survives serialization and can be compiled by every storage plane.
+ */
+export const subjectRuleSchema = z.strictObject({
+  field: z.string().regex(
+    /^[a-zA-Z_][a-zA-Z0-9_]*$/,
+    'subject.field must name a model field',
+  ),
+  group: z.string().regex(
+    /^[a-z][a-z0-9_]*$/,
+    'subject.group must be a lowercase identifier, e.g. "workspace"',
+  ),
+});
+
+export type SubjectRule = z.infer<typeof subjectRuleSchema>;
+
+/** The exact trusted group a row must match, or null for a malformed row. */
+export function subjectGroupForRow(
+  rule: SubjectRule,
+  row: Readonly<Record<string, unknown>>,
+): string | null {
+  const value = row[rule.field];
+  return typeof value === 'string' && value.length > 0
+    ? `${rule.group}:${value}`
+    : null;
+}
+
+/** Fail-closed row check shared by endpoint adapters and in-memory log folds. */
+export function subjectAuthorized(
+  rule: SubjectRule | undefined,
+  row: Readonly<Record<string, unknown>>,
+  groups: readonly string[] | null | undefined,
+): boolean {
+  if (!rule) return true;
+  const required = subjectGroupForRow(rule, row);
+  return required !== null && (groups ?? []).includes(required);
+}

package/src/server/adapter.ts

@@ -21,10 +21,11 @@ import type {
   SourceOperation,
   SourceRequestContext,
 } from '../source/index.js';
-import type { ServerSyncDelta } from '../wire/delta.js';
+import type { ServerSyncDelta } from '../observation/contract.js';
 import type { BootstrapModel } from './readConfig.js';
 import type { CommitContext, CommitExecutionResult } from './commit.js';
 import type { StorageMode } from './storageMode.js';
+import type { SubjectRule } from '../schema/subject.js';
 
 /**
  * A canonical database row: one record, keyed by column name. The value type is
@@ -141,6 +142,7 @@ export type ReadRequest =
       readonly sourceModel?: string;
       /** `__typename` stamped on each returned row. */
       readonly typename: string;
+      readonly subject?: SubjectRule;
       readonly query: SourceListQuery;
       readonly scope?: SourceRequestContext;
       /** Runs the query against a hosted database: compile, take the tenant pool, apply row-level security, unpack the rows. */

package/src/server/commit.ts

@@ -13,11 +13,11 @@
  * commit time and the shape of a stored or broadcast delta share one definition
  * rather than being kept in step by hand.
  */
-import type { ParticipantKind, ConfirmationState } from '../log/syncDeltaRow.js';
-import type { ParticipantRef } from '../wire/delta.js';
-import type { CommitExecutionResultInput } from '../wire/commit.js';
-import type { CommitOperationResult } from '../wire/commit.js';
-import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ParticipantKind, ConfirmationState } from '../observation/persistence/syncDeltaRow.js';
+import type { ParticipantRef } from '../observation/contract.js';
+import type { CommitExecutionResultInput } from '../commit/contract.js';
+import type { CommitOperationResult } from '../commit/contract.js';
+import type { ReadDependency } from '../coordination/schema.js';
 import type { EffectiveAuthority } from '../auth/capability.js';
 
 export interface CommitContext {
@@ -81,18 +81,10 @@ export interface CommitContext {
   /**
    * The premise for the whole batch. The committer declares the rows or groups
    * it read to form this batch; the engine checks that none of them changed since
-   * each entry's `readAt` timestamp and applies that entry's `onStale` disposition
-   * across the batch. This differs from the per-operation `readAt` guard, which
+   * each entry's `readAt` timestamp and rejects the batch if one moved. This differs from the per-operation `readAt` guard, which
    * validates only the rows being written. Omit it to check the write targets alone.
    */
   reads?: ReadDependency[] | null;
-  /**
-   * Durable premises 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;
 }
 
 /**

package/src/server/index.ts

@@ -26,7 +26,7 @@ export {
   commitExecutionResultSchema,
   commitRecordSchema,
   type CommitRecord,
-} from '../wire/commit.js';
+} from '../commit/contract.js';
 export { storageModeSchema, type StorageMode } from './storageMode.js';
 export type {
   ColumnOverride,

package/src/server/readConfig.ts

@@ -19,6 +19,8 @@
  * Plain data, no database driver — it feeds the read side of the data adapter
  * contract, and your query builder reads it to load a model's initial rows.
  */
+import type { SubjectRule } from '../schema/subject.js';
+
 
 /** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
 export interface ColumnOverride {
@@ -88,6 +90,8 @@ export interface ReadModelShape {
   readonly orgColumn?: string;
   /** Parent-table scoping for rows with no tenancy column of their own. */
   readonly scopedVia?: ParentScope;
+  /** Credential-bound row authorization compiled by every read plane. */
+  readonly subject?: SubjectRule;
   /** Client-facing field name → physical DB column for declared fields. */
   readonly fieldColumns?: Readonly<Record<string, string>>;
   /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */

package/src/source/{adapter.ts → adapters/adapter.ts}

@@ -24,13 +24,13 @@
  * you want to override one of those while the adapter serves the rest.
  */
 
-import type { SourceListQuery, SourceRequestContext } from './types.js';
+import type { SourceListQuery, SourceRequestContext } from '../types.js';
 import type {
   AdapterCapabilities,
   ChangeSet,
-  EventsPage,
-  Migration,
 } from './contract.js';
+import type { Migration } from './migration.js';
+import type { EventsPage } from '../outbox/index.js';
 import type { DatabaseAdapterProfile } from './adapterProfile.js';
 
 /**
@@ -83,8 +83,12 @@ export interface MutationAdapter {
  */
 export interface DataSourceAdapter extends MutationAdapter {
   readonly capabilities: AdapterCapabilities & { readonly outboxEvents: true };
-  /** Reads outbox events after `cursor` (`null` starts from the beginning), up to `limit` events. */
+  /** Pure read of events after `cursor`; `null` starts at the beginning. */
   events(cursor: string | null, limit: number): Promise<EventsPage>;
+  /** Bounded cleanup through a consumer position Ablo has durably committed. */
+  acknowledgeEvents(acknowledgedThrough: string): Promise<void>;
 }
 
-export type { AdapterCapabilities, ChangeSet, Migration, OutboxEvent, EventsPage } from './contract.js';
+export type { AdapterCapabilities, ChangeSet } from './contract.js';
+export type { Migration } from './migration.js';
+export type { EventsPage, OutboxEvent } from '../outbox/index.js';

package/src/source/{adapterFactory.ts → adapters/adapterFactory.ts}

@@ -6,7 +6,7 @@
  * binding, observation, and advertised guarantees.
  */
 
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError } from '../../errors.js';
 import type { MutationAdapter } from './adapter.js';
 import { databaseAdapterProfileSchema } from './adapterProfile.js';
 

package/src/source/{conformance.ts → adapters/conformance.ts}

@@ -302,4 +302,4 @@ export function runDataSourceTests(
   }
 }
 
-export { memoryDataSource } from './adapters/memory.js';
+export { memoryDataSource } from './memory.js';

package/src/source/{contract.ts → adapters/contract.ts}

@@ -5,8 +5,8 @@
  * failing deep inside a transaction, and each TypeScript type is inferred from the
  * one schema that validates it.
  *
- * These schemas describe the adapter's own contract: the change set it commits,
- * the outbox row it stores, and the table migrations it ships. The operation
+ * These schemas describe the adapter's mutation contract: the change set it
+ * commits and the capabilities it advertises. The operation
  * vocabulary is not restated here — `operationSchema` is projected from the
  * core's `commitOperationSchema`, so an action or field added to the commit
  * contract reaches a data source by construction. The assertion at the end of
@@ -16,11 +16,11 @@
  */
 
 import { z } from 'zod';
-import { correlationIdSchema } from '../wire/commit.js';
+import { correlationIdSchema } from '../../commit/contract.js';
 import {
   commitOperationSchema,
   commitOperationTypeSchema,
-} from '../coordination/schema.js';
+} from '../../coordination/schema.js';
 import {
   ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH,
   ABLO_SOURCE_ECHO_MAX_OPERATIONS,
@@ -28,7 +28,8 @@ import {
   type SourceCommitEcho,
   type SourceCommitEchoMarker,
   type SourceOperation,
-} from './types.js';
+} from '../types.js';
+import type { SourceRequestContext } from '../types.js';
 
 const jsonObject = z.record(z.string(), z.unknown());
 
@@ -44,15 +45,15 @@ export type OperationType = z.infer<typeof operationTypeSchema>;
  * A single operation within a change set, and the runtime validator for it.
  *
  * The field set is projected from `commitOperationSchema` — an operation
- * reaching a data source is a commit operation minus the two fields the core
- * settles internally (`bypass`, `fenceToken`). The two `min(1)` overrides are
+ * reaching a data source is a commit operation minus the fencing field the
+ * core settles internally. The two `min(1)` overrides are
  * deliberate and local: this is a customer-implemented boundary, so an empty
  * model name or row id is rejected here rather than forwarded. Stating them as
  * an extension keeps the tightening visible as a choice instead of hiding it
  * inside a second copy of the shape.
  */
 export const operationSchema = commitOperationSchema
-  .omit({ bypass: true, fenceToken: true })
+  .omit({ fenceToken: true })
   .extend({
     model: z.string().min(1),
     id: z.string().min(1).nullish(),
@@ -149,62 +150,17 @@ export const changeSetSchema = z.object({
   correlationId: correlationIdSchema,
   intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
   echo: sourceCommitEchoSchema.optional(),
+  scope: z.object({
+    participantId: z.string().optional(),
+    participantKind: z.enum(['user', 'agent', 'system']).optional(),
+    organizationId: z.string().optional(),
+    branchId: z.string().optional(),
+    projectId: z.string().optional(),
+    syncGroups: z.array(z.string()).optional(),
+  }).optional() satisfies z.ZodType<SourceRequestContext | undefined>,
 });
 export type ChangeSet = z.infer<typeof changeSetSchema>;
 
-/**
- * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
- * transaction as the underlying row change — the transactional-outbox pattern — so
- * a change and its event commit together or not at all. The `events()` feed later
- * reads these rows back and hands them to Ablo, and `cursor` is the monotonic
- * ordering key Ablo round-trips to resume where it left off.
- */
-export const outboxEventSchema = z.object({
-  /** Stable, globally-unique id — Ablo's replay-protection key. */
-  id: z.string().min(1),
-  model: z.string().min(1),
-  entityId: z.string().min(1),
-  type: operationTypeSchema,
-  /** The changed row, in the key shape `SourceEvent.data` defines: the model's
-   *  declared schema fields, never the table's physical column names. */
-  data: jsonObject.nullish(),
-  organizationId: z.string().nullish(),
-  /** Legacy source transaction id. Never use this field to settle a queued commit. */
-  clientTxId: z.string().nullish(),
-  /** Scoped server-authored identity that correlates this event to a queued commit. */
-  correlationId: correlationIdSchema.nullish(),
-  /** Stable identity of this operation within the correlated source commit. */
-  transactionId: z
-    .string()
-    .min(1)
-    .max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH)
-    .nullish(),
-  occurredAt: z.number().nullish(),
-  /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
-  cursor: z.string().min(1),
-});
-export type OutboxEvent = z.infer<typeof outboxEventSchema>;
-
-/** A page of outbox events returned by `events()`. */
-export const eventsPageSchema = z.object({
-  events: z.array(outboxEventSchema),
-  nextCursor: z.string().nullable(),
-});
-export type EventsPage = z.infer<typeof eventsPageSchema>;
-
-/**
- * A table-creation migration an adapter ships, so you never hand-write the
- * `ablo_idempotency` and `ablo_outbox` tables yourself. An adapter returns these
- * from its `migrations()` method.
- */
-export const migrationSchema = z.object({
-  /** Stable name, used as the migration filename + applied-ledger key. */
-  name: z.string().min(1),
-  /** The forward SQL. */
-  up: z.string().min(1),
-});
-export type Migration = z.infer<typeof migrationSchema>;
-
 /** Describes what an adapter's backend supports, so callers check a capability rather than infer it from behavior. */
 export const adapterCapabilitiesSchema = z.object({
   /** `commit` is atomic across all operations in the change set. */
@@ -244,6 +200,13 @@ const _echoContractInSync: [_AssertEchoMatchesWire, _AssertWireMatchesEcho] = [
 ];
 void _echoContractInSync;
 
+// Compatibility façade. New implementation code follows the owned subsystem
+// downward from `outbox/index.ts` and imports migrations from `migration.ts`.
+export { eventsPageSchema, outboxEventSchema } from '../outbox/contract.js';
+export type { EventsPage, OutboxEvent } from '../outbox/contract.js';
+export { migrationSchema } from './migration.js';
+export type { Migration } from './migration.js';
+
 type _AssertEchoMarkerMatchesWire = SourceCommitEchoMarkerWire extends SourceCommitEchoMarker
   ? true
   : never;

package/src/source/adapters/drizzle.ts

@@ -41,23 +41,37 @@ import type {
   AdapterReadRequest,
   DataSourceAdapter,
   Row,
-} from '../adapter.js';
-import { defineDatabaseAdapter } from '../adapterFactory.js';
-import { postgresAdapterProfile } from '../adapterProfile.js';
-import type { ChangeSet, EventsPage, Migration, Operation } from '../contract.js';
-import { outboxEventSchema } from '../contract.js';
-import { adapterTableMigrations } from '../migrations.js';
+} from './adapter.js';
+import { defineDatabaseAdapter } from './adapterFactory.js';
+import { postgresAdapterProfile } from './adapterProfile.js';
+import type { ChangeSet, Operation } from './contract.js';
+import type { Migration } from './migration.js';
+import { adapterTableMigrations } from './migrations.js';
 import {
   assertSourceIdempotencyIntent,
   assertSourceIdempotencyRetention,
   SOURCE_IDEMPOTENCY_RETENTION,
   sourceChangeIntentHash,
-} from '../idempotency.js';
+} from './idempotency.js';
 import type { Schema, SchemaRecord } from '../../schema/schema.js';
 import { toSchemaJSON } from '../../schema/serialize.js';
 import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
 import { tenancyColumn } from '../../schema/tenancy.js';
 import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  rethrowStrictCreateConflict,
+  sourceSyncGroups,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from './subjectAuthorization.js';
+import {
+  decodeDatabaseOutboxEvent,
+  ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE,
+  type EventsPage,
+} from '../outbox/index.js';
 
 /** The subset of a Drizzle database/transaction handle the adapter calls. */
 export interface DrizzleLike {
@@ -214,11 +228,18 @@ export function drizzleDataSource<S extends SchemaRecord>(
       const table = sql.identifier(mc.table);
       if (req.kind === 'load') {
         const rows = rowsOf(await db.execute(sql`SELECT * FROM ${table} WHERE id = ${req.id} LIMIT 1`));
-        return rows.map((r) => toFields(mc, r));
+        return authorizeSourceRead(schema, req, rows.map((r) => toFields(mc, r)));
       }
       const limit = req.query?.limit ?? 1000;
-      const rows = rowsOf(await db.execute(sql`SELECT * FROM ${table} LIMIT ${limit}`));
-      return rows.map((r) => toFields(mc, r));
+      const rule = sourceSubjectRule(schema, req.model);
+      const subjects = sourceSubjectValues(rule, req.scope?.syncGroups);
+      if (subjects?.length === 0) return [];
+      const rows = rowsOf(await db.execute(subjects
+        ? sql`SELECT * FROM ${table}
+              WHERE ${sql.identifier(columnFor(mc, rule!.field))} = ANY(${subjects})
+              LIMIT ${limit}`
+        : sql`SELECT * FROM ${table} LIMIT ${limit}`));
+      return authorizeSourceRead(schema, req, rows.map((r) => toFields(mc, r)));
     },
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
@@ -238,19 +259,46 @@ export function drizzleDataSource<S extends SchemaRecord>(
           return { rows: cachedRow.response as Row[] };
         }
 
+        await lockSourceSubjectCreates(schema, change, async (_operation, key) => {
+          await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
+        });
+
+        await authorizeSourceChange(schema, change, async (operation) => {
+          if (!operation.id) return null;
+          const mc = modelColumns(operation.model);
+          const found = rowsOf(
+            await tx.execute(
+              sql`SELECT * FROM ${sql.identifier(mc.table)} WHERE id = ${operation.id} LIMIT 1 FOR UPDATE`,
+            ),
+          )[0];
+          return found ? toFields(mc, found) : null;
+        });
+
         const rows: Row[] = [];
         for (const [index, op] of change.operations.entries()) {
-          const row = await applyOperation(tx, op);
+          let row: Row;
+          try {
+            row = await applyOperation(tx, op);
+          } catch (error) {
+            if (op.type === 'CREATE') rethrowStrictCreateConflict(error, op);
+            throw error;
+          }
           rows.push(row);
           const entityId = String(row.id ?? rowId(op));
+          const syncGroups = sourceSyncGroups(schema, op.model, row);
+          const syncGroupsSql = sql`ARRAY[${sql.join(
+            syncGroups.map((group) => sql`${group}`),
+            sql`, `,
+          )}]::text[]`;
           await tx.execute(sql`
             INSERT INTO ablo_outbox (
-              id, model, entity_id, type, data,
+              id, model, entity_id, type, data, event_version, sync_groups,
               correlation_id, transaction_id, occurred_at
             )
             VALUES (
               ${`${change.correlationId}:${index}`}, ${op.model}, ${entityId}, ${op.type},
-              ${op.type === 'DELETE' ? null : JSON.stringify(row)}::jsonb,
+              ${op.type === 'DELETE' ? null : JSON.stringify(row)}::jsonb, 2,
+              ${syncGroupsSql},
               ${change.correlationId}, ${op.transactionId ?? null}, ${Date.now()}
             )`);
         }
@@ -270,29 +318,27 @@ export function drizzleDataSource<S extends SchemaRecord>(
       });
     },
 
+    async acknowledgeEvents(acknowledgedThrough: string): Promise<void> {
+      await db.transaction(async (tx) => {
+        await tx.execute(sql`
+          DELETE FROM ablo_outbox
+           WHERE cursor IN (
+             SELECT cursor FROM ablo_outbox
+              WHERE cursor <= ${acknowledgedThrough}
+              ORDER BY cursor ASC LIMIT ${ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE}
+           )`);
+      });
+    },
+
     async events(cursor: string | null, limit: number): Promise<EventsPage> {
       const after = cursor ?? '0';
       const rows = rowsOf(
         await db.execute(sql`
-          SELECT cursor, id, model, entity_id, type, data, organization_id,
+          SELECT cursor, id, model, entity_id, type, data, event_version, sync_groups, organization_id,
                  client_tx_id, correlation_id, transaction_id, occurred_at
           FROM ablo_outbox WHERE cursor > ${after} ORDER BY cursor ASC LIMIT ${limit}`),
       );
-      const events = rows.map((r) =>
-        outboxEventSchema.parse({
-          id: r.id,
-          model: r.model,
-          entityId: r.entity_id,
-          type: r.type,
-          data: r.data ?? null,
-          organizationId: r.organization_id ?? null,
-          clientTxId: r.client_tx_id ?? null,
-          correlationId: r.correlation_id ?? null,
-          transactionId: r.transaction_id ?? null,
-          occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
-          cursor: String(r.cursor),
-        }),
-      );
+      const events = rows.map(decodeDatabaseOutboxEvent);
       return { events, nextCursor: events.at(-1)?.cursor ?? null };
     },
   });

package/src/source/{idempotency.ts → adapters/idempotency.ts}

@@ -12,11 +12,11 @@
 
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
-import { AbloValidationError } from '../errors.js';
+import { AbloValidationError } from '../../errors.js';
 import {
   COMMIT_CORRELATION_ID_MAX_LENGTH,
   correlationIdSchema,
-} from '../wire/commit.js';
+} from '../../commit/contract.js';
 import type { ChangeSet, Operation } from './contract.js';
 
 const SOURCE_ECHO_TRANSACTION_ID_PREFIX = 'ablo_echo_tx_v1:';

package/src/source/adapters/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Customer-database adapter subsystem.
+ *
+ * Start here and descend through the behavioral adapter port, mutation
+ * contract, profiles, migrations, idempotency, authorization, conformance,
+ * and concrete ORM bindings.
+ */
+export * from './adapter.js';
+export * from './adapterFactory.js';
+export * from './adapterProfile.js';
+export * from './contract.js';
+export * from './migration.js';
+export * from './migrations.js';
+export * from './idempotency.js';
+export * from './subjectAuthorization.js';
+export * from './conformance.js';
+export * from './memory.js';
+export * from './prisma.js';
+export * from './drizzle.js';
+export * from './kysely.js';