@abloatai/transaction 0.56.0 → 0.58.0

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`
@@ -28,11 +29,6 @@ import { getFieldMeta, inferFieldMetaFromZod, type FieldMeta } from './field.js'
 import { resolvePolicy, type Tenancy, type ScopedViaRef, type PolicyInput } from './tenancy.js';
 export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
 import { DEFAULT_RESIDENCY, type ModelResidency } from './residency.js';
-// The write-conflict disposition. It is plain data (the `onStale` vocabulary) so it
-// round-trips through schema serialization, and the engine interprets it when a
-// commit is applied.
-import type { ConflictAxis } from '../policy/types.js';
-export type { ConflictAxis } from '../policy/types.js';
 
 /** Normalize the `entityRoles` option (single | array | undefined) to an array. */
 function normalizeEntityRoles(
@@ -152,6 +148,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 +180,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 }
@@ -186,29 +192,6 @@ export interface ModelOptions {
    */
   groups?: GroupsInput;
 
-  /**
-   * Write-conflict disposition, set per committer kind — decides what happens when a
-   * commit collides with another participant's claim or with a stale snapshot of this
-   * model. This is independent of {@link policy} (read access) and {@link groups}
-   * (delta routing). It is a map keyed by the committer's kind (`user`, `agent`, or
-   * `system`), with these outcomes as values:
-   *
-   * - `'overwrite'` — the write wins; that committer is never blocked.
-   * - `'reject'`    — the write is refused; that committer yields.
-   * - `'notify'`    — hold the write and hand the current value back so the committer
-   *                   re-reads and re-applies (for stale writes only).
-   *
-   * A kind you omit falls back to the engine default: reject, while honoring
-   * `onStale: 'notify'`. The value is plain data that travels with the schema to the
-   * server, where the engine interprets it. For example:
-   *
-   * ```ts
-   * // "a human's edit always wins (never blocked); an agent yields"
-   * conflict: { user: 'overwrite', agent: 'reject' }
-   * ```
-   */
-  conflict?: ConflictAxis;
-
   /**
    * Whether clients may create, update, and delete this model's rows through the
    * commit protocol. Defaults to true: declaring a model in your schema is the
@@ -353,6 +336,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,9 +347,8 @@ export interface ModelDef<
   readonly grants?: GrantsRef;
   /** Explicit record-to-group roles, normalized to an array. See {@link ModelOptions.groups}. */
   readonly entityRoles?: readonly EntityRole[];
-  /** The write-conflict disposition per committer kind, carried as plain data. See
-   *  {@link ModelOptions.conflict}. */
-  readonly conflict?: ConflictAxis;
+  /** Explicit acknowledgement that sync groups are routing, not row access. */
+  readonly routingOnly?: true;
   /** Whether wire-level CREATE/UPDATE/DELETE is allowed. See {@link ModelOptions.mutable}. */
   readonly mutable?: boolean;
   /** Defer MobX setup until first observer access. See {@link ModelOptions.lazyObservable}. */
@@ -445,13 +429,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),
-    // The conflict disposition is already plain data, so it passes through unchanged.
-    conflict: options?.conflict,
+    routingOnly: options?.groups?.routingOnly,
     mutable: options?.mutable ?? true,
     lazyObservable: options?.lazyObservable,
     computed: options?.computed,

package/src/schema/openapi.ts

@@ -25,6 +25,7 @@ import type { FieldMeta } from './field.js';
 // Pulled from the endpoints module to keep this schema file free of the client's
 // error-handling and credential dependencies.
 import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
+import { docUrlForCode } from '../errors.js';
 // The commit body is DERIVED from the schema the server validates against —
 // one definition site, so the documented surface cannot drift from the
 // enforced one.
@@ -35,7 +36,7 @@ import {
   commitRecordSchema,
   commitRecordListSchema,
   commitRecordWhereSchema,
-} from '../wire/commit.js';
+} from '../commit/contract.js';
 import { CURSOR_PARAM, CURSOR_PARAM_ALIAS } from '../wire/listEnvelope.js';
 import {
   claimRequestSchema,
@@ -51,12 +52,26 @@ import {
   claimReorderRequestSchema,
   claimReorderReplySchema,
   claimReleaseReplySchema,
-} from '../wire/claims.js';
+} from '../claims/contract.js';
 import { errorEnvelopeSchema } from '../wire/errorEnvelope.js';
+// The lifecycle promise and the rate-limit fields are contract, not prose about
+// contract: the document renders the same constants the server emits, so the
+// published policy cannot describe a signal the runtime does not send.
+import {
+  API_DEPRECATION_HEADER,
+  API_LIFECYCLE,
+  API_SUNSET_HEADER,
+  API_VERSION_HEADER,
+} from '../wire/apiLifecycle.js';
+import {
+  RATE_LIMIT_HEADER,
+  RATE_LIMIT_POLICY_HEADER,
+  RETRY_AFTER_HEADER,
+} from '../wire/rateLimit.js';
 import { modelReadResponseSchema, modelListResponseSchema } from '../wire/modelResponses.js';
 import { modelMutationRequestSchema } from '../wire/modelMutations.js';
-import { logListResponseSchema, logQuerySchema } from '../wire/feedEvent.js';
-import { logDeliveryResponseSchema } from '../wire/deltaDelivery.js';
+import { logListResponseSchema, logQuerySchema } from '../observation/feedContract.js';
+import { logDeliveryResponseSchema } from '../observation/deliveryContract.js';
 import { schemaReadResponseSchema } from '../wire/accountResponses.js';
 import {
   ephemeralKeyRequestSchema,
@@ -400,6 +415,106 @@ const claimIdParam = (): Json => ({
  */
 const commitBody = (): Json => jsonBody(derive(commitRequestSchema, 'input'));
 
+/**
+ * The response headers every operation carries, declared once under
+ * `components/headers` and referenced from each response.
+ *
+ * A header a caller is expected to act on has to be IN the document to be
+ * actionable: a generated client surfaces what the spec declares and drops what
+ * it does not, so an undeclared `RateLimit` is a header the caller never sees
+ * and therefore never paces against. Declaring them here rather than at each
+ * response is what keeps one description of each — the reason the names are
+ * imported rather than typed out.
+ */
+const RESPONSE_HEADER_COMPONENTS: Readonly<Record<string, Json>> = {
+  AbloVersion: {
+    description:
+      'The date-stamped contract version this response was served under. Record ' +
+      'the value your integration was built against; a change means something ' +
+      'observable was added.',
+    schema: { type: 'string', examples: ['2026-08-15'] },
+  },
+  RateLimitPolicy: {
+    description:
+      'The standing allowance for this credential kind, as a Structured Fields ' +
+      'List: `"secret";q=600;w=12`. It does not move between responses, so read ' +
+      'it once and pace against it.',
+    schema: { type: 'string', examples: ['"secret";q=600;w=12'] },
+  },
+  RateLimit: {
+    description:
+      'This caller\u2019s live position in the allowance: `r` units left, `t` ' +
+      'seconds until they refill. Present once the request is attributed to a ' +
+      'credential.',
+    schema: { type: 'string', examples: ['"secret";r=412;t=8'] },
+  },
+  RetryAfter: {
+    description: 'Whole seconds to wait before retrying. Sent with 429 and 503.',
+    schema: { type: 'integer', minimum: 1, examples: [8] },
+  },
+  RequestId: {
+    description:
+      'Correlation id for this request, repeated in the error envelope\u2019s ' +
+      '`request_id`. Quote it in a support request.',
+    schema: { type: 'string', examples: ['req_52bb7f46-17bc-4f2d-9988-89d1398d2990'] },
+  },
+  Deprecation: {
+    description:
+      'Present only on a route being withdrawn: an sf-Date of when the ' +
+      'deprecation took effect (RFC 9745). The route still answers normally.',
+    schema: { type: 'string', examples: ['@1774483200'] },
+  },
+  Sunset: {
+    description:
+      'Present only on a route being withdrawn: the HTTP-date it stops ' +
+      'answering (RFC 8594). Never less than the published notice window after ' +
+      `\`${API_DEPRECATION_HEADER}\`.`,
+    schema: { type: 'string', examples: ['Tue, 08 Sep 2026 00:00:00 GMT'] },
+  },
+};
+
+const headerRef = (name: string): Json => ({ $ref: `#/components/headers/${name}` });
+
+/** Carried by every response, whatever its status. */
+const UNIVERSAL_RESPONSE_HEADERS: Readonly<Record<string, Json>> = {
+  [API_VERSION_HEADER]: headerRef('AbloVersion'),
+  'X-Request-Id': headerRef('RequestId'),
+  [RATE_LIMIT_POLICY_HEADER]: headerRef('RateLimitPolicy'),
+  [RATE_LIMIT_HEADER]: headerRef('RateLimit'),
+  [API_DEPRECATION_HEADER]: headerRef('Deprecation'),
+  [API_SUNSET_HEADER]: headerRef('Sunset'),
+};
+
+/** Statuses where a wait is what resolves the failure, so `Retry-After` is sent. */
+const RETRY_AFTER_STATUSES = new Set(['429', '503']);
+
+/**
+ * Stamp the documented headers onto every response of every operation.
+ *
+ * Runs after the responses are built — including the canonical error ones — so
+ * a response added later cannot quietly ship without them.
+ */
+function attachResponseHeaders(paths: Json): void {
+  for (const rawPathItem of Object.values(paths)) {
+    const pathItem = rawPathItem as Json;
+    for (const [method, rawOperation] of Object.entries(pathItem)) {
+      if (!HTTP_METHODS.has(method)) continue;
+      const operation = rawOperation as Json;
+      const responses = (operation.responses ?? {}) as Json;
+      for (const [status, rawResponse] of Object.entries(responses)) {
+        const response = rawResponse as Json;
+        response.headers = {
+          ...UNIVERSAL_RESPONSE_HEADERS,
+          ...(RETRY_AFTER_STATUSES.has(status)
+            ? { [RETRY_AFTER_HEADER]: headerRef('RetryAfter') }
+            : {}),
+          ...((response.headers as Json | undefined) ?? {}),
+        };
+      }
+    }
+  }
+}
+
 /** The envelope shared by both specs — same server, same auth, same version. */
 function envelope(options: SchemaToOpenApiOptions, description: string, paths: Json, schemas: Record<string, Json>): Json {
   return {
@@ -407,18 +522,28 @@ function envelope(options: SchemaToOpenApiOptions, description: string, paths: J
     info: {
       title: options.title ?? 'Ablo API',
       version: options.version ?? 'development',
-      description,
+      // The lifecycle policy travels WITH the routes it governs. An agent
+      // deciding whether to integrate needs to know the surface will not move
+      // under it, and a policy published somewhere else is one it has to go
+      // find — so the document that describes the calls describes the promise.
+      description: `${description}\n\n${API_LIFECYCLE}`,
       license: {
         name: 'Apache License 2.0',
         identifier: 'Apache-2.0',
       },
+      contact: {
+        name: 'Ablo Support',
+        url: 'https://github.com/Abloatai/ablo/issues',
+        email: 'support@abloatai.com',
+      },
     },
     servers: [{ url: options.serverUrl ?? `${ABLO_HOSTED_HTTP_BASE_URL}/api` }],
     security: [{ bearerAuth: [] }],
     components: {
       securitySchemes: {
-        bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_… / rk_…).' },
+        bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_\u2026 / rk_\u2026).' },
       },
+      headers: { ...RESPONSE_HEADER_COMPONENTS },
       schemas,
     },
     paths,
@@ -436,6 +561,41 @@ const ERROR_RESPONSES: Readonly<Record<string, string>> = {
   '503': 'A required service is temporarily unavailable.',
 };
 
+/**
+ * One real instance of the error shape every operation shares.
+ *
+ * This lives beside the canonical error responses rather than on the schema:
+ * OpenAPI consumers select examples from an operation's media type, and an
+ * example buried on a component does not tell them which response carries it.
+ * Stamping the same representative validation failure on every operation also
+ * means a newly added route cannot regress the published example coverage.
+ */
+const ERROR_RESPONSE_EXAMPLE: Readonly<Json> = {
+  type: 'AbloValidationError',
+  code: 'invalid_request',
+  param: 'body',
+  message: 'The request did not satisfy the published contract.',
+  doc_url: docUrlForCode('invalid_request'),
+  request_id: 'req_52bb7f46-17bc-4f2d-9988-89d1398d2990',
+};
+
+function canonicalErrorResp(description: string): Json {
+  return {
+    description,
+    content: {
+      'application/json': {
+        schema: schemaRef('ErrorEnvelope'),
+        examples: {
+          validation: {
+            summary: 'Typed validation failure',
+            value: ERROR_RESPONSE_EXAMPLE,
+          },
+        },
+      },
+    },
+  };
+}
+
 /**
  * Every route passes failures through the same server error funnel. Publish
  * that fact on every operation so generated transports decode all HTTP errors
@@ -450,11 +610,10 @@ function attachCanonicalErrors(paths: Json): void {
       const operation = rawOperation as Json;
       const responses = { ...(operation.responses as Json | undefined) };
       for (const [status, description] of Object.entries(ERROR_RESPONSES)) {
-        responses[status] = namedResp(description, 'ErrorEnvelope');
+        responses[status] = canonicalErrorResp(description);
       }
-      responses.default = namedResp(
+      responses.default = canonicalErrorResp(
         'An HTTP error not otherwise listed; decoded through the canonical envelope.',
-        'ErrorEnvelope',
       );
       operation.responses = responses;
     }
@@ -950,6 +1109,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
 
   applyOperationIds(paths, ABLO_OPERATION_IDS);
   attachCanonicalErrors(paths);
+  attachResponseHeaders(paths);
 
   return envelope(
     options,
@@ -1078,6 +1238,7 @@ export function schemaToOpenApi<S extends SchemaRecord>(
   operationIds['GET /v1/commits/{id}'] = 'getCommit';
   applyOperationIds(paths, operationIds);
   attachCanonicalErrors(paths);
+  attachResponseHeaders(paths);
 
   Object.assign(schemas, abloComponentSchemas());
 

package/src/schema/roles.ts

@@ -219,6 +219,8 @@ export const groupsInputSchema = z.object({
   root: scopeSchema.optional(),
   grants: grantsRefSchema.optional(),
   roles: z.union([entityRoleSchema, z.array(entityRoleSchema)]).optional(),
+  /** Acknowledge that these groups are delivery routing, not row access. */
+  routingOnly: z.literal(true).optional(),
 });
 export type GroupsInput = z.infer<typeof groupsInputSchema>;
 
@@ -314,6 +316,57 @@ export function composeEntitySyncGroups(
   return Array.from(out);
 }
 
+/** The row fields needed to derive its durable delivery groups. */
+export interface RecordSyncGroupSpec {
+  readonly subject?: { readonly kind: string; readonly field: string };
+  readonly selfKind?: string;
+  readonly parents: readonly { readonly kind: string; readonly field: string }[];
+}
+
+/** A subject-scoped row cannot be routed safely without its declared subject. */
+export class InvalidRecordSubjectError extends Error {
+  readonly field: string;
+
+  constructor(field: string) {
+    super(`Record lacks non-empty subject field "${field}".`);
+    this.name = 'InvalidRecordSubjectError';
+    this.field = field;
+  }
+}
+
+/**
+ * Derive the exact durable delivery groups for a row.
+ *
+ * Delivery matching is OR-based, so a declared subject is an exclusive
+ * authorization route: self, parent, entity-role, writer, and transitive groups
+ * must not become alternate ways to receive the row. Additional groups are
+ * accepted here so every producer applies that rule in this one place.
+ */
+export function syncGroupsForRow(
+  spec: RecordSyncGroupSpec | undefined,
+  record: Readonly<Record<string, unknown>>,
+  additionalGroups: readonly string[] = [],
+): string[] {
+  if (spec?.subject) {
+    const value = record[spec.subject.field];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new InvalidRecordSubjectError(spec.subject.field);
+    }
+    return [syncGroup(spec.subject.kind, value)];
+  }
+
+  const groups = new Set<string>(additionalGroups);
+  if (!spec) return [...groups];
+  if (spec.selfKind && typeof record.id === 'string' && record.id.length > 0) {
+    groups.add(syncGroup(spec.selfKind, record.id));
+  }
+  for (const parent of spec.parents) {
+    const value = record[parent.field];
+    if (value) groups.add(syncGroup(parent.kind, String(value)));
+  }
+  return [...groups];
+}
+
 /**
  * Narrow a client's requested sync-group set to the groups it is actually
  * allowed to subscribe to. This helper is fully generic — it never inspects the

package/src/schema/schema.ts

@@ -13,11 +13,11 @@
  *       status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *       workspaceId: z.string().optional(),
  *     }, {
- *       workspace: relation.belongsTo('workspaces', 'workspaceId'),
+ *       relations: { workspace: relation.belongsTo('workspaces', 'workspaceId') },
  *     }),
  *   });
  *
- *   type Item = InferModel<typeof schema, 'items'>;
+ *   type Item = Model<typeof schema, 'items'>;
  */
 
 import { z } from 'zod';
@@ -27,6 +27,7 @@ import { AbloValidationError } from '../errors.js';
 import type { IdentityRole } from './roles.js';
 import { fieldRef, type FieldRef } from './fieldRef.js';
 import { scopeSchema, grantsRefSchema } from './roles.js';
+import { subjectRuleSchema } from './subject.js';
 
 // Sync-group roles (identity and entity) are defined in `./roles.js` and
 // re-exported here so they can also be imported from this module. See
@@ -49,6 +50,9 @@ export {
   extractEntityIds,
   composeIdentitySyncGroups,
   composeEntitySyncGroups,
+  syncGroupsForRow,
+  InvalidRecordSubjectError,
+  type RecordSyncGroupSpec,
   intersectRequestedWithAllowed,
   syncGroup,
   identityAnchor,
@@ -150,6 +154,7 @@ export const RESERVED_SESSION_SETTINGS: readonly string[] = [
   'app.current_participant_id',
   'app.current_participant_kind',
   'app.current_user_id',
+  'app.current_subject_groups',
 ];
 
 export interface DefineSchemaOptions {
@@ -226,6 +231,13 @@ export const baseFieldsSchema = z.object({
 /**
  * The universal model field names. Audit and application metadata is declared
  * by the application or carried by the commit record, never injected here.
+ *
+ * This is the runtime spelling of {@link baseFieldsSchema}, and the one every
+ * consumer outside this package derives from: the CLI's adopt rule, the MCP
+ * schema linter, and the docs that tell an author which names not to declare.
+ * It is exported from `@abloatai/transaction/schema` for exactly that reason —
+ * when this list last moved (0.52.0, five names down to one) three hand-written
+ * copies stayed behind and went on rejecting correct schemas for five releases.
  */
 export const BASE_FIELDS = [
   'id',
@@ -234,6 +246,18 @@ export const BASE_FIELDS = [
 /** The base fields type — pure data columns. */
 export type BaseModelFields = z.infer<typeof baseFieldsSchema>;
 
+// Invariant equality (no runtime, no casts): true only when both are mutually
+// assignable. `ExpectTrue`'s constraint is what turns a mismatch into an error
+// at THIS declaration, so the tuple and the schema cannot move apart — in
+// either direction, a name in one and not the other fails to compile.
+type BaseFieldsEqual<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type ExpectTrue<T extends true> = T;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type _BaseFieldsExact = ExpectTrue<
+  BaseFieldsEqual<(typeof BASE_FIELDS)[number], keyof BaseModelFields & string>
+>;
+
 /**
  * Methods every model instance carries. These are intersected into
  * {@link InferModel}, the read-side type, but not into the create or update
@@ -327,7 +351,8 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
 
 /**
  * Infer the full model type from a schema.
- * Includes base fields (id, createdAt, updatedAt, etc.)
+ * Includes the base fields, which today means `id` alone: audit timestamps are
+ * ordinary declared fields and appear here only when the model declares them.
  *
  * ```ts
  * type Item = InferModel<typeof schema, 'items'>;
@@ -523,14 +548,34 @@ export type InsertValue<S extends Schema, ModelName extends keyof S['models']> =
 export type UpsertValue<S extends Schema, ModelName extends keyof S['models']> =
   InsertValue<S, ModelName>;
 
+/**
+ * A patch over a row's fields: send a field to change it, omit it to leave it,
+ * send `null` to CLEAR it.
+ *
+ * The third of those is why this is a mapped type rather than `Partial`.
+ * Omitting a field and clearing a field are different intentions that
+ * `Partial` spells the same way, because `undefined` is what an absent key
+ * already means: it is dropped from the payload, so a caller who wrote
+ * `{ assigneeId: undefined }` to unassign kept the old assignee, and the
+ * unassign, the un-project and the cleared due date all did nothing without
+ * erroring. `null` is the value that clears, so `null` is what the type has to
+ * accept — otherwise the only way to write a working clear is to cast the
+ * payload, and a cast is what people reached for.
+ *
+ * Only a field the schema lets be absent is clearable. A required field cannot
+ * be nulled, which is the same rule the column has.
+ */
+export type Clearable<T> = {
+  [K in keyof T]?: undefined extends T[K] ? T[K] | null : T[K];
+};
+
 /**
  * The value type for updating an existing row. `id` is required (identifies
- * the row to update); all other fields are optional (only provided fields
- * are changed).
+ * the row to update); every other field is a {@link Clearable} patch.
  */
 export type UpdateValue<S extends Schema, ModelName extends keyof S['models']> =
   S['models'][ModelName] extends ModelDef<infer Shape>
-    ? { id: string } & Partial<z.input<z.ZodObject<Shape>>>
+    ? { id: string } & Clearable<z.input<z.ZodObject<Shape>>>
     : never;
 
 /**
@@ -708,6 +753,7 @@ export function defineSchema<const S extends SchemaRecord>(
   }
 
   validateSyncGroupSchema(resolvedModels);
+  validateSubjectSchema(resolvedModels);
   validateSessionSettings(options?.sessionSettings ?? {});
 
   return {
@@ -721,6 +767,45 @@ export function defineSchema<const S extends SchemaRecord>(
   };
 }
 
+function validateSubjectSchema(models: Record<string, ModelDef>): void {
+  for (const [name, def] of Object.entries(models)) {
+    if (!def.subject) continue;
+    const parsed = subjectRuleSchema.safeParse(def.subject);
+    if (!parsed.success) {
+      throw new AbloValidationError(
+        `Model "${name}": subject must be { field, group } with valid identifiers.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject` },
+      );
+    }
+    if (!(def.subject.field in def.fields)) {
+      throw new AbloValidationError(
+        `Model "${name}": subject.field "${def.subject.field}" is not a declared field on this model.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject.field` },
+      );
+    }
+    const field = def.shape[def.subject.field];
+    const meta = def.fields[def.subject.field];
+    if (!field || !meta) {
+      throw new AbloValidationError(
+        `Model "${name}": subject.field "${def.subject.field}" is not a declared field on this model.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject.field` },
+      );
+    }
+    const subjectField = field as z.ZodType;
+    const acceptsInvalidValue =
+      subjectField.safeParse('').success ||
+      subjectField.safeParse(null).success ||
+      subjectField.safeParse(undefined).success ||
+      subjectField.safeParse(1).success;
+    if (!['string', 'enum'].includes(meta.type) || meta.isOptional || acceptsInvalidValue) {
+      throw new AbloValidationError(
+        `Model "${name}": subject.field "${def.subject.field}" must be a required, non-empty string field.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject.field` },
+      );
+    }
+  }
+}
+
 /**
  * Reject session-setting mappings that couldn't do what the author intends —
  * caught here at definition time rather than silently dropped on the write path.

package/src/schema/serialize.ts

@@ -13,7 +13,7 @@
  * What round-trips:
  *   - all model routing and scoping metadata: typename, tableName, load,
  *     mutable, the `tenancy` descriptor, bootstrap hints, scope, grants,
- *     entityRoles, the `conflict` disposition map, persist, autoFill,
+ *     entityRoles, the routing-only acknowledgement, the `conflict` disposition map, persist, autoFill,
  *     requiredFields, and lazyObservable. The authoring shorthands (`policy`
  *     and `groups`) are normalized into these canonical fields when the model
  *     is built, so only the canonical fields cross here.
@@ -33,6 +33,7 @@ import type { FieldMeta } from './field.js';
 import { buildFieldRefs } from './schema.js';
 import type { Tenancy } from './tenancy.js';
 import type { ModelResidency } from './residency.js';
+import type { SubjectRule } from './subject.js';
 import type {
   ModelDef,
   RelationRecord,
@@ -40,7 +41,6 @@ import type {
   LoadStrategy,
   PersistOptions,
   AutoFillRule,
-  ConflictAxis,
 } from './model.js';
 import {
   relation,
@@ -80,6 +80,7 @@ export interface ModelJSON {
   readonly typename: string;
   readonly tableName?: string;
   readonly tenancy: Tenancy;
+  readonly subject?: SubjectRule;
   /** The database plane the model's rows live in. Optional for backward
    *  compatibility: when absent (an artifact written before this field existed)
    *  it reads as `tenant`, the default. See {@link ModelResidency}. */
@@ -87,9 +88,7 @@ export interface ModelJSON {
   readonly scope?: boolean | string;
   readonly grants?: GrantsRef;
   readonly entityRoles?: readonly EntityRole[];
-  /** The declared write-conflict disposition per committer kind. When absent,
-   *  the engine falls back to its default. */
-  readonly conflict?: ConflictAxis;
+  readonly routingOnly?: true;
   readonly bootstrapLimit?: number;
   readonly bootstrapOrderBy?: string;
   readonly mutable?: boolean;
@@ -136,11 +135,12 @@ function modelToJSON(def: ModelDef): ModelJSON {
     typename: def.typename ?? '',
     tableName: def.tableName,
     tenancy: def.tenancy,
+    subject: def.subject,
     plane: def.plane,
     scope: def.scope,
     grants: def.grants,
     entityRoles: def.entityRoles,
-    conflict: def.conflict,
+    routingOnly: def.routingOnly,
     bootstrapLimit: def.bootstrapLimit,
     bootstrapOrderBy: def.bootstrapOrderBy,
     mutable: def.mutable,
@@ -272,15 +272,14 @@ function modelFromJSON(json: ModelJSON): ModelDef {
     persist: json.persist,
     tableName: json.tableName,
     tenancy: json.tenancy,
+    subject: json.subject,
     // Absent in older artifacts → default `tenant`, matching the model builder
     // and provisioning defaults so the round-trip stays stable.
     plane: json.plane ?? 'tenant',
     scope: json.scope,
     grants: json.grants,
     entityRoles: json.entityRoles,
-    // Absent in older artifacts → undefined, so the commit path falls through to
-    // the function registry or the engine default.
-    conflict: json.conflict,
+    routingOnly: json.routingOnly,
     mutable: json.mutable,
     lazyObservable: json.lazyObservable,
     // computed getters are closures and intentionally not serialized; a