@abloatai/transaction 0.56.0 → 0.57.0

package/src/resources/httpResources.ts

@@ -19,9 +19,12 @@ import type {
   CommitRecordList,
   CommitRecordListOptions,
   CommitRecordWhere,
+  CommitOperationBody,
+  ModelOperationAction,
 } from '../wire/commit.js';
 import type { LogListResponse, LogQuery } from '../wire/feedEvent.js';
 import type { ModelListEvidence } from '../wire/modelResponses.js';
+import { AbloValidationError } from '../errors.js';
 // Re-exported, not redeclared. `wire/commit.ts` owns the commit-status vocabulary
 // and derives the waitable subset from it; this module serves that name to SDK
 // consumers. Restating the subset here as its own union produced a type that
@@ -63,6 +66,7 @@ import type {
   AwaitedClaimMethod,
   ModelTrackParams,
   ModelTrackResult,
+  ModelCreateManyParams,
   ServerReadOptions,
 } from './modelOperations.js';
 
@@ -77,12 +81,7 @@ import type {
  *   `claim({ id })` — a durable claim handle for coordinated writes
  */
 
-export type ModelOperationAction =
-  | 'create'
-  | 'update'
-  | 'delete'
-  | 'archive'
-  | 'unarchive';
+export type { ModelOperationAction };
 
 
 /** @internal Transport envelope; the public typed client returns the row. */
@@ -130,20 +129,119 @@ export interface HttpTransportList<T = Record<string, unknown>> {
  * and a complete one the same value, so the caller with 500 matching rows got
  * 20 and no way to find out.
  */
-export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'>;
+export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'> &
+  AsyncIterable<T>;
 
 /**
- * Attach the page state to the rows. Non-enumerable so the result stays
- * indistinguishable from a plain array everywhere the properties aren't read.
+ * How far a `for await` over a list will walk before it gives up.
+ *
+ * A cursor that stops advancing would otherwise spin forever. The bound is
+ * high enough that no real collection reaches it and low enough that a broken
+ * server is a failed read rather than a hung process.
+ */
+const AUTO_PAGE_LIMIT = 10_000;
+const LIST_ALL_PAGE_LIMIT = 100;
+
+const nextPageFor = new WeakMap<object, (cursor: string) => Promise<ModelList<unknown>>>();
+
+export interface ModelListWalkOptions {
+  readonly maxPages?: number;
+  readonly signal?: AbortSignal;
+}
+
+async function* walkModelList<T>(
+  first: ModelList<T>,
+  options: ModelListWalkOptions = {},
+): AsyncGenerator<T> {
+  const maxPages = options.maxPages ?? AUTO_PAGE_LIMIT;
+  if (!Number.isInteger(maxPages) || maxPages < 1) {
+    throw new AbloValidationError('maxPages must be a positive integer.', {
+      code: 'invalid_options',
+      param: 'maxPages',
+    });
+  }
+
+  let current = first;
+  for (let visited = 0; visited < maxPages; visited += 1) {
+    options.signal?.throwIfAborted();
+    for (let i = 0; i < current.length; i += 1) {
+      options.signal?.throwIfAborted();
+      yield current[i] as T;
+    }
+    const cursor = current.nextCursor;
+    const fetchNext = nextPageFor.get(current) as
+      | ((nextCursor: string) => Promise<ModelList<T>>)
+      | undefined;
+    if (!current.hasMore || cursor === null || fetchNext === undefined) return;
+    const next = await fetchNext(cursor);
+    if (next.nextCursor === cursor) {
+      throw new AbloValidationError(
+        `Walking this list received the same continuation cursor twice (${JSON.stringify(cursor)}). ` +
+          'The collection may be incomplete, so traversal stopped with an error.',
+        { code: 'malformed_response', param: 'nextCursor' },
+      );
+    }
+    current = next;
+  }
+  throw new AbloValidationError(
+    `Walking this list passed ${maxPages} pages without reaching the end. ` +
+      `Narrow the read with \`where\` or raise \`maxPages\` deliberately.`,
+    { code: 'invalid_options', param: 'maxPages' },
+  );
+}
+
+/** Collect a complete list through the same guarded cursor loop as async iteration. */
+export async function collectModelList<T>(
+  first: ModelList<T>,
+  options: ModelListWalkOptions = {},
+): Promise<T[]> {
+  const rows: T[] = [];
+  for await (const row of walkModelList(first, {
+    maxPages: options.maxPages ?? LIST_ALL_PAGE_LIMIT,
+    signal: options.signal,
+  })) rows.push(row);
+  return rows;
+}
+
+/**
+ * Attach the page state to the rows, and make the list walk its own pages.
+ *
+ * `hasMore` and `nextCursor` are non-enumerable, so the result stays
+ * indistinguishable from a plain array everywhere they are not read: it maps,
+ * filters, spreads, and `JSON.stringify`s exactly as the rows always did.
+ *
+ * The async iterator is the answer to the question that shape raises. A list
+ * read is a page — the server applies a default size and caps the largest —
+ * and a page of 20 looks precisely like a complete answer of 20, so every
+ * caller either checked `hasMore` or, far more often, reasoned about a
+ * truncated set without knowing it. Hand-rolled page walkers were the common
+ * result, and each one re-derived the same cursor loop and the same
+ * non-advancing-cursor guard.
+ *
+ * So iterate the value to get the page, and `for await` it to get the
+ * collection:
+ *
+ * ```ts
+ * const page = await ablo.issue.list({ where: { teamId } });
+ * for (const issue of page) …            // the 20 rows that came back
+ * for await (const issue of page) …      // every issue, paged as it goes
+ * ```
  */
 export function modelList<T>(
   rows: readonly T[],
   page: Pick<HttpTransportList<unknown>, 'hasMore' | 'nextCursor'>,
+  /** Reads the page after `cursor`. Omitted where no transport can follow. */
+  fetchNext?: (cursor: string) => Promise<ModelList<T>>,
 ): ModelList<T> {
-  return Object.defineProperties([...rows], {
+  const list = Object.defineProperties([...rows], {
     hasMore: { value: page.hasMore, enumerable: false },
     nextCursor: { value: page.nextCursor, enumerable: false },
+    [Symbol.asyncIterator]: { value: () => walkModelList(list), enumerable: false },
   }) as ModelList<T>;
+  if (fetchNext) {
+    nextPageFor.set(list, fetchNext as (cursor: string) => Promise<ModelList<unknown>>);
+  }
+  return list;
 }
 
 export type IfClaimedPolicy = 'return' | 'fail';
@@ -206,21 +304,8 @@ export interface ClaimCreateOptions {
   readonly onStatus?: (event: ClaimAttemptEvent) => void;
 }
 
-export interface CommitOperationInput {
-  readonly action: ModelOperationAction;
-  /** The model name — matches `ablo.<model>` and the schema's `model()`. */
-  readonly model: string;
-  readonly id?: string | null;
-  readonly data?: Record<string, unknown> | null;
-  readonly where?: Record<string, unknown> | null;
-  readonly transactionId?: string | null;
-  /** Claim identity derived from a held claim; not an application id. */
-  readonly claimId?: string | null;
-  readonly readAt?: number | null;
-  readonly onStale?: OnStaleMode | null;
-  /** Fencing token (Option B) from the batch's claim handle; server-validated. */
-  readonly fenceToken?: number | null;
-}
+/** Public commit operation inferred from the canonical request-body schema. */
+export type CommitOperationInput = CommitOperationBody;
 
 export interface CommitCreateOptions {
   readonly idempotencyKey?: string | null;
@@ -402,6 +487,12 @@ export interface HttpTransportModel<
    * returned, not the input.
    */
   create(params: ModelMutationOptions & { readonly data: Record<string, unknown>; readonly id?: string | null }): Promise<T>;
+  /**
+   * Creates many rows as one atomic commit and returns them, in the caller's
+   * order. One rejected row declines the batch. The rows are the server's own,
+   * carried back on the commit rather than read again afterwards.
+   */
+  createMany(params: ModelCreateManyParams<Record<string, unknown>>): Promise<T[]>;
   update(params: ModelMutationOptions & { readonly id: string; readonly data: Record<string, unknown> }): Promise<CommitReceipt>;
   /**
    * Update under contention with a function of the latest state —

package/src/resources/modelCreate.ts

@@ -0,0 +1,73 @@
+/** Canonical create identity and result correlation shared by every client. */
+
+import { v5 as uuidv5 } from 'uuid';
+import { AbloConnectionError } from '../errors.js';
+import type { CommitOperationResult } from '../wire/commit.js';
+
+/** Resolve the two supported single-create id spellings. The sibling wins. */
+export function resolveCreateId(
+  explicitId: string | null | undefined,
+  data: unknown,
+): string | undefined {
+  if (typeof explicitId === 'string' && explicitId.length > 0) return explicitId;
+  const inData =
+    typeof data === 'object' && data !== null
+      ? (data as { readonly id?: unknown }).id
+      : undefined;
+  return typeof inData === 'string' && inData.length > 0 ? inData : undefined;
+}
+
+/** Stable across transports and client instances when an idempotency key is supplied. */
+export function createModelId(
+  modelName: string,
+  idempotencyKey?: string | null,
+): string {
+  if (idempotencyKey) {
+    return uuidv5(
+      `${modelName}:${idempotencyKey}`,
+      'aa4ba6d4-bf0b-5b38-9c45-116f79a6e548',
+    );
+  }
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Return server-authored create rows in input order.
+ *
+ * Fresh receipts carry operationResults. Durable idempotency replays redact
+ * row data, so that path verifies every expected id with a point read. It may
+ * fail under a write-only policy, but it can never report a partial collection
+ * as success.
+ */
+export async function resolveCreatedRows<T>(input: {
+  readonly modelName: string;
+  readonly ids: readonly string[];
+  readonly operationResults?: readonly CommitOperationResult[];
+  readonly readRow: (id: string) => Promise<T | undefined>;
+}): Promise<T[]> {
+  if (input.operationResults?.length === input.ids.length) {
+    const byId = new Map(
+      input.operationResults.map((result) => [
+        (result.row as { readonly id?: unknown }).id,
+        result.row,
+      ]),
+    );
+    const ordered = input.ids.map((id) => byId.get(id));
+    if (ordered.every((row): row is Record<string, unknown> => row !== undefined)) {
+      return ordered as T[];
+    }
+  }
+
+  const rows = await Promise.all(input.ids.map((id) => input.readRow(id)));
+  const missing = input.ids.filter((_id, index) => rows[index] === undefined);
+  if (missing.length > 0) {
+    throw new AbloConnectionError(
+      `${input.modelName} create confirmed, but ${missing.length} of ${input.ids.length} ` +
+        'server rows could not be recovered from its receipt or verified by id.',
+      { code: 'commit_no_result', details: { missingIds: missing } },
+    );
+  }
+  return rows as T[];
+}

package/src/resources/modelOperations.ts

@@ -15,7 +15,7 @@ import type { ResolveClaimMeta } from '../types/global.js';
 import type { AbloError } from '../errors.js';
 import type { StaleNotification, TrackDependency } from '../coordination/schema.js';
 import type { FieldRef, FieldSelector } from '../schema/fieldRef.js';
-import type { BaseModelFields } from '../schema/schema.js';
+import type { BaseModelFields, Clearable } from '../schema/schema.js';
 import type { ClaimHeartbeatPlan } from '../coordination/claimHeartbeatLoop.js';
 import type { Duration } from '../utils/duration.js';
 import type {
@@ -232,6 +232,14 @@ export interface ServerReadOptions<T> {
   expand?: readonly string[];
 }
 
+/** Options for an explicit complete collection traversal. */
+export interface ListAllOptions<T> extends Omit<ServerReadOptions<T>, 'cursor'> {
+  /** Maximum pages to read before refusing an unexpectedly broad traversal. @default 100 */
+  maxPages?: number;
+  /** Stops traversal between page requests and row yields. */
+  signal?: AbortSignal;
+}
+
 /** Options for the single-row async server read `get({ id })`. A subset of
  *  {@link ServerReadOptions} — `where`/`limit`/`orderBy` are fixed by the id. */
 export type ServerRetrieveOptions = Pick<ServerReadOptions<unknown>, 'type' | 'expand'>;
@@ -588,6 +596,21 @@ export interface ModelCreateParams<T, CreateInput>
   readonly claim?: Claim<T> | ClaimTargetOptions<CreateInput> | null;
 }
 
+/**
+ * Creating many rows at once: the same verb, handed a list.
+ *
+ * One atomic commit, so the batch lands whole or not at all, and the rows come
+ * back in the order they were given. There is no `id` beside `data` here the
+ * way there is for a single create, since one id cannot address many rows;
+ * write it into each row instead, which the create input has always allowed.
+ */
+export type ModelCreateManyParams<CreateInput> = Pick<
+  ModelWriteOptions,
+  'idempotencyKey' | 'reads' | 'track'
+> & {
+  readonly data: readonly CreateInput[];
+};
+
 export interface ModelUpdateParams<T, Fields = T>
   extends ModelWriteOptions {
   readonly id: string;
@@ -595,8 +618,12 @@ export interface ModelUpdateParams<T, Fields = T>
    * Patch only fields declared by the model's Zod input shape. Hydrated rows
    * also carry framework fields, relations, methods, and computed values; none
    * of those are writable data.
+   *
+   * Send a field to change it, omit it to leave it, send `null` to clear it —
+   * see {@link Clearable}. `undefined` is not a clear: it is dropped from the
+   * payload and the old value survives.
    */
-  readonly data: Partial<ClaimableFields<Fields>>;
+  readonly data: Clearable<ClaimableFields<Fields>>;
   readonly claim?: Claim<T> | ClaimTargetOptions<Fields> | null;
 }
 

package/src/resources/writeOptionsSchema.ts

@@ -107,3 +107,31 @@ const _writeOptionsContractInSync: AssertExact<
   keyof WriteOptionsContract
 > = true;
 void _writeOptionsContractInSync;
+
+/**
+ * Refuse a per-model write that does not name its row.
+ *
+ * `update` and `delete` address the row through the URL, so an absent `id`
+ * used to be spelled into the path by `encodeURIComponent` as the literal
+ * string `"undefined"`. The request was well-formed, it matched no row, and it
+ * came back as an ordinary receipt: `delete({ where: { id } })` reported
+ * success and deleted nothing. `{ where }` is the shape the commit protocol
+ * takes one layer down, so reaching for it here is an easy and quiet mistake.
+ *
+ * The typed surface already rejects it at compile time. This is the same
+ * refusal for callers who reach the transport without those types.
+ */
+export function assertWriteTarget(
+  action: 'update' | 'delete',
+  modelName: string,
+  id: unknown,
+): void {
+  if (typeof id === 'string' && id.length > 0) return;
+  const namedAFilter =
+    typeof id === 'object' && id !== null && 'where' in (id as Record<string, unknown>);
+  throw new AbloValidationError(
+    `A ${modelName} ${action} has to name the row it acts on: ${action}({ id })` +
+      (namedAFilter ? ', not a `where` filter.' : '.'),
+    { code: 'invalid_body', param: 'id' },
+  );
+}

package/src/schema/audit.ts

@@ -0,0 +1,121 @@
+import type { ModelJSON, SchemaJSON } from './serialize.js';
+import { resolveTenancy } from './tenancy.js';
+
+export interface SchemaAuditFinding {
+  readonly code: 'scope_routing_without_access_policy';
+  readonly severity: 'error';
+  readonly model: string;
+  readonly message: string;
+  readonly fix: string;
+}
+
+interface RoutingAnchor {
+  readonly description: string;
+  readonly column: string;
+  readonly parentTable?: string;
+}
+
+function tableName(key: string, model: ModelJSON): string {
+  return model.tableName ?? key;
+}
+
+function fieldColumn(model: ModelJSON, field: string): string {
+  return model.fields[field]?.column ?? field;
+}
+
+function camelToSnake(value: string): string {
+  return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+function reachesScope(
+  key: string,
+  models: SchemaJSON['models'],
+  seen: ReadonlySet<string> = new Set(),
+): boolean {
+  if (seen.has(key)) return false;
+  const model = models[key];
+  if (!model) return false;
+  if (model.scope) return true;
+  const nextSeen = new Set(seen).add(key);
+  return Object.values(model.relations).some(
+    (relation) => relation.type === 'belongsTo' && reachesScope(relation.target, models, nextSeen),
+  );
+}
+
+function routingAnchors(
+  model: ModelJSON,
+  models: SchemaJSON['models'],
+): readonly RoutingAnchor[] {
+  const anchors: RoutingAnchor[] = [];
+
+  if (model.scope) {
+    anchors.push({ description: `scope root ${String(model.scope)}`, column: 'id' });
+  }
+
+  for (const role of model.entityRoles ?? []) {
+    anchors.push({
+      description: `entity role ${role.kind}`,
+      column: fieldColumn(model, role.source.field),
+    });
+  }
+
+  for (const [relationName, relation] of Object.entries(model.relations)) {
+    if (relation.type !== 'belongsTo' || !reachesScope(relation.target, models)) continue;
+    const target = models[relation.target];
+    if (!target) continue;
+    anchors.push({
+      description: `parent scope ${relationName}`,
+      column: relation.foreignKeyColumn,
+      parentTable: tableName(relation.target, target),
+    });
+  }
+
+  return anchors;
+}
+
+function policyMatches(anchor: RoutingAnchor, model: ModelJSON): boolean {
+  const tenancy = resolveTenancy(model);
+  if (tenancy.kind === 'source') return true;
+  if (tenancy.kind === 'column') {
+    return tenancy.column === anchor.column || tenancy.column === camelToSnake(anchor.column);
+  }
+  if (tenancy.kind === 'parent') {
+    return tenancy.via.localKey === anchor.column &&
+      (anchor.parentTable === undefined || tenancy.via.parentTable === anchor.parentTable);
+  }
+  return false;
+}
+
+/**
+ * Finds mutable models whose sync-group routing is narrower than their row-read
+ * policy. A correctly filtered list or routed stream is not evidence that a
+ * foreign row is unreadable; only the policy is the authorization boundary.
+ */
+export function auditSchemaAccessPolicies(schema: SchemaJSON): readonly SchemaAuditFinding[] {
+  const findings: SchemaAuditFinding[] = [];
+
+  for (const [key, model] of Object.entries(schema.models)) {
+    if (model.mutable === false || model.routingOnly === true) continue;
+    const mismatched = routingAnchors(model, schema.models)
+      .filter((anchor) => !policyMatches(anchor, model));
+    if (mismatched.length === 0) continue;
+
+    const policy = resolveTenancy(model);
+    const routedBy = mismatched.map(({ description, column }) => `${description} (${column})`).join(', ');
+    findings.push({
+      code: 'scope_routing_without_access_policy',
+      severity: 'error',
+      model: key,
+      message:
+        `Model "${key}" routes changes by ${routedBy}, but its row-access policy is ` +
+        `by ${policy.kind}. Sync groups route delivery; they do not authorize reads. ` +
+        `A filtered list or correctly routed live stream is not an authorization proof.`,
+      fix:
+        `Make policy follow the same customer/workspace boundary on every reachable model, ` +
+        `use policy: { by: 'source' } with one Ablo organization per hard tenant, or set ` +
+        `groups.routingOnly: true to explicitly acknowledge an intentionally broader read policy.`,
+    });
+  }
+
+  return findings;
+}

package/src/schema/ddl.ts

@@ -27,6 +27,7 @@ import type { SchemaJSON, ModelJSON } from './serialize.js';
 import type { MigrationStep, BackfillValue, FieldType } from './diff.js';
 import type { FieldMeta } from './field.js';
 import { resolveTenancy, tenancyColumn } from './tenancy.js';
+import type { SubjectRule } from './subject.js';
 
 export interface ProvisionPlan {
   /** The Postgres schema the tables live in (`app_<id>` or `public`). */
@@ -119,6 +120,22 @@ export function sqlType(fieldType: ModelJSON['fields'][string]['type']): string
 
 const BASE_COLUMNS = new Set(['id']);
 
+function subjectPredicate(model: ModelJSON, rule: SubjectRule): string {
+  const meta = model.fields[rule.field];
+  if (!meta) {
+    throw new AbloValidationError(`subject field ${JSON.stringify(rule.field)} is not declared`, {
+      code: 'schema_definition_invalid',
+      param: 'subject.field',
+    });
+  }
+  const column = meta.column ?? camelToSnake(rule.field);
+  const prefix = `${rule.group}:`.replace(/'/g, "''");
+  return (
+    `COALESCE(NULLIF(current_setting('app.current_subject_groups', true), ''), '[]')::jsonb ` +
+    `? ('${prefix}' || ${q(column)}::text)`
+  );
+}
+
 // ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
 
 /**
@@ -324,7 +341,20 @@ export function generateProvisionPlan(
       statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
       statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
       const policy = `${table}_tenant_isolation`;
-      const predicate = `${q(orgCol)} = current_setting('app.current_org_id', true)`;
+      const predicates = [
+        `${q(orgCol)} = current_setting('app.current_org_id', true)`,
+        ...(model.subject ? [subjectPredicate(model, model.subject)] : []),
+      ];
+      const predicate = predicates.length === 1
+        ? predicates[0]!
+        : predicates.map((part) => `(${part})`).join(' AND ');
+      statements.push(`DROP POLICY IF EXISTS ${q(policy)} ON ${qt};`);
+      statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
+    } else if (model.subject) {
+      statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
+      statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
+      const policy = `${table}_subject_isolation`;
+      const predicate = subjectPredicate(model, model.subject);
       statements.push(`DROP POLICY IF EXISTS ${q(policy)} ON ${qt};`);
       statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
     }
@@ -585,5 +615,45 @@ export function generateMigrationPlan(
     }
   }
 
+  // Subject authorization is metadata rather than a field diff. Reconcile when
+  // that metadata changes, or when the protected field's physical column
+  // changes. An identical empty migration must remain a true no-op.
+  for (const [key, model] of Object.entries(next.models)) {
+    if ((model.plane ?? 'tenant') === 'control') continue;
+    const previousModel = prev?.models[key];
+    const subjectChanged = JSON.stringify(previousModel?.subject) !== JSON.stringify(model.subject);
+    const subjectColumnChanged = steps.some((step) =>
+      'model' in step && step.model === key &&
+      step.kind === 'alter_field' &&
+      (step.field === model.subject?.field || step.field === previousModel?.subject?.field) &&
+      step.changes.column !== undefined
+    );
+    if (!subjectChanged && !subjectColumnChanged) continue;
+    const table = model.tableName ?? key;
+    const qt = qtFor(table);
+    const orgCol = tenancyColumn(resolveTenancy(model));
+    const tenantPolicy = `${table}_tenant_isolation`;
+    const subjectPolicy = `${table}_subject_isolation`;
+    if (orgCol || model.subject) {
+      statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
+      statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
+      statements.push(`DROP POLICY IF EXISTS ${q(tenantPolicy)} ON ${qt};`);
+      statements.push(`DROP POLICY IF EXISTS ${q(subjectPolicy)} ON ${qt};`);
+      const parts = [
+        ...(orgCol ? [`${q(orgCol)} = current_setting('app.current_org_id', true)`] : []),
+        ...(model.subject ? [subjectPredicate(model, model.subject)] : []),
+      ];
+      const predicate = parts.length === 1
+        ? parts[0]!
+        : parts.map((part) => `(${part})`).join(' AND ');
+      const policy = orgCol ? tenantPolicy : subjectPolicy;
+      statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
+    } else if (previousModel?.subject) {
+      statements.push(`DROP POLICY IF EXISTS ${q(subjectPolicy)} ON ${qt};`);
+      statements.push(`ALTER TABLE ${qt} NO FORCE ROW LEVEL SECURITY;`);
+      statements.push(`ALTER TABLE ${qt} DISABLE ROW LEVEL SECURITY;`);
+    }
+  }
+
   return { appSchema: targetSchema, statements, concurrent };
 }

package/src/schema/index.ts

@@ -154,12 +154,16 @@ export {
   type InsertValue,
   type UpsertValue,
   type UpdateValue,
+  type Clearable,
   type DeleteId,
   type DefineSchemaOptions,
   type Casing,
   type CasingConvention,
   type CasingFn,
   composeEntitySyncGroups,
+  syncGroupsForRow,
+  InvalidRecordSubjectError,
+  type RecordSyncGroupSpec,
   intersectRequestedWithAllowed,
   type IdentityRole,
   type IdentityContext,
@@ -210,6 +214,18 @@ export {
   type RelationJSON,
 } from './serialize.js';
 
+export {
+  auditSchemaAccessPolicies,
+  type SchemaAuditFinding,
+} from './audit.js';
+
+export {
+  subjectRuleSchema,
+  subjectGroupForRow,
+  subjectAuthorized,
+  type SubjectRule,
+} from './subject.js';
+
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels, omitModels, omittedModelError } from './select.js';
 

package/src/schema/model.ts

@@ -21,6 +21,7 @@
 import { z } from 'zod';
 import type { RelationDef } from './relation.js';
 import type { EntityRole, GroupsInput } from './roles.js';
+import type { SubjectRule } from './subject.js';
 import { getFieldMeta, inferFieldMetaFromZod, type FieldMeta } from './field.js';
 // Tenancy lives in `tenancy.ts`. Authoring uses the `policy` option
 // (`PolicyInput`), which `resolvePolicy` normalizes into the canonical `Tenancy`
@@ -152,6 +153,14 @@ export interface ModelOptions {
    */
   policy?: PolicyInput;
 
+  /**
+   * Credential-bound row authorization below organization tenancy. The named
+   * row field must match a trusted credential group: `{ field: 'workspaceId',
+   * group: 'workspace' }` authorizes only rows whose `workspaceId` has a
+   * matching `workspace:<id>` group on the request.
+   */
+  subject?: SubjectRule;
+
   /**
    * Which database a model's rows live in. `tenant` (the default) is tenant data
    * that provisioning places in the customer's own database; `control` is Ablo's own
@@ -176,6 +185,8 @@ export interface ModelOptions {
    * - `roles` — explicit record-to-group roles keyed on a plain field, for routing
    *   that does not follow a relation, such as fanning a message into a recipient's
    *   inbox. Accepts one role or many.
+   * - `routingOnly: true` — explicitly acknowledges that these delivery groups
+   *   are intentionally narrower than the model's independently safe read policy.
    *
    * ```ts
    * // archiveMember: { userId, archiveId }
@@ -353,6 +364,8 @@ export interface ModelDef<
   /** The canonical tenancy descriptor for this model, normalized from the `policy`
    *  option at build time. See {@link ModelOptions.policy}. */
   readonly tenancy: Tenancy;
+  /** Credential-bound row authorization. See {@link ModelOptions.subject}. */
+  readonly subject?: SubjectRule;
   /** Which database this model's rows live in — `tenant` (default) can be a
    *  customer's own database; `control` is Ablo's. See {@link ModelOptions.plane}. */
   readonly plane?: ModelResidency;
@@ -362,6 +375,8 @@ export interface ModelDef<
   readonly grants?: GrantsRef;
   /** Explicit record-to-group roles, normalized to an array. See {@link ModelOptions.groups}. */
   readonly entityRoles?: readonly EntityRole[];
+  /** Explicit acknowledgement that sync groups are routing, not row access. */
+  readonly routingOnly?: true;
   /** The write-conflict disposition per committer kind, carried as plain data. See
    *  {@link ModelOptions.conflict}. */
   readonly conflict?: ConflictAxis;
@@ -445,11 +460,13 @@ export function model<
     // Normalize the `policy` option into the canonical tenancy descriptor (defaults
     // to a row-local organization column).
     tenancy: resolvePolicy(options?.policy),
+    subject: options?.subject,
     plane: options?.plane ?? DEFAULT_RESIDENCY,
     // Unpack the `groups` option into the individual routing fields the server reads.
     scope: options?.groups?.root,
     grants: options?.groups?.grants,
     entityRoles: normalizeEntityRoles(options?.groups?.roles),
+    routingOnly: options?.groups?.routingOnly,
     // The conflict disposition is already plain data, so it passes through unchanged.
     conflict: options?.conflict,
     mutable: options?.mutable ?? true,