@abloatai/transaction 0.39.0 → 0.41.0

package/dist/wire/index.js

@@ -74,7 +74,11 @@ export { fieldTypeSchema, fieldMetaSchema, relationTypeSchema, relationMetaSchem
 export { modelMutationRequestSchema } from './modelMutations.js';
 // The account routes' responses — projects, the deployed schema, the commit
 // log, usage. What the server, the CLI, and the MCP server agree on.
-export { projectResponseSchema, projectListResponseSchema, provisionedKeySchema, provisionKeyResponseSchema, conflictAxisWireSchema, schemaModelResponseSchema, schemaReadResponseSchema, logOpSchema, LOG_OP_BY_ACTION, logEventSchema, usageBucketSchema, usageReportResponseSchema, controlKeySchema, controlKeyListResponseSchema, keyMintedResponseSchema, keyRevokedResponseSchema, } from './accountResponses.js';
+export { projectResponseSchema, projectListResponseSchema, provisionedKeySchema, provisionKeyResponseSchema, conflictAxisWireSchema, schemaModelResponseSchema, schemaReadResponseSchema, logOpSchema, LOG_OP_BY_ACTION, logEventSchema, usageBucketSchema, usageReportResponseSchema, meterUsageSchema, billingSummarySchema, usageSummaryResponseSchema, controlKeySchema, controlKeyListResponseSchema, keyMintedResponseSchema, keyRevokedResponseSchema, } from './accountResponses.js';
+// The datasource routes' responses — the `ablo connect` surface: register,
+// validate, locate, list, deregister. What the server, the CLI, and the
+// dashboard agree on.
+export { READINESS_ITEMS, READINESS_ADVISORY_ITEMS, isReadinessItem, readinessFailureSchema, readinessAdvisorySchema, datasourceSummarySchema, datasourceListResponseSchema, datasourceValidationResponseSchema, datasourceLocationResponseSchema, datasourceDisconnectedResponseSchema, } from './dataSourceResponses.js';
 // The inbound socket surface: every frame the server can send, and how each
 // one's payload is validated.
 export { WS_INBOUND_FRAMES, wsInboundEnvelopeSchema, isKnownInboundFrame, isSchemaValidatedFrame, } from './inboundFrames.js';

package/dist/wire/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wire/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wire/index.ts"],"names":[],"mappings":"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"}

package/dist/wire/pricing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The pricing vocabulary that crosses the wire: the tier names, the meter
+ * names, and the shape of one rate-card step. Account responses carry these,
+ * so they live in the dependency-free wire layer; the pricing contract
+ * (`../pricing.ts`) derives the rate card, the plans, and the bill arithmetic
+ * from them and re-exports them for its consumers.
+ */
+import { z } from 'zod';
+export declare const planTierSchema: z.ZodEnum<{
+    free: "free";
+    scale: "scale";
+    enterprise: "enterprise";
+}>;
+export type PlanTier = z.infer<typeof planTierSchema>;
+/**
+ * Every meter the engine records, over any transport. This is the closed set
+ * behind the loose `eventName` strings that `UsageRecorder` and the quota gate
+ * pass around.
+ *
+ * Recording and pricing are separate questions. A meter exists so usage can be
+ * gated and attributed; whether it reaches an invoice is `METER_EVENT_AXIS`.
+ * Bootstraps are recorded and quota-gated but deliberately unpriced: a bootstrap
+ * is what a client does once to become useful, and charging for it would price
+ * the act of connecting.
+ */
+export declare const meterEventSchema: z.ZodEnum<{
+    "api.commit_ops": "api.commit_ops";
+    "api.model_reads": "api.model_reads";
+    "api.claim_creates": "api.claim_creates";
+    "api.bootstraps": "api.bootstraps";
+}>;
+export type MeterEvent = z.infer<typeof meterEventSchema>;
+/**
+ * One step of the rate card. `throughOps` is the cumulative ceiling the rate
+ * applies up to, and `null` marks the final, unbounded step. Rates are marginal:
+ * crossing a ceiling reprices the operations above it, never the ones below.
+ */
+export declare const rateBracketSchema: z.ZodObject<{
+    throughOps: z.ZodNullable<z.ZodNumber>;
+    usdPerMillionOps: z.ZodNumber;
+}, z.core.$strip>;
+export type RateBracket = z.infer<typeof rateBracketSchema>;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/wire/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/wire/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc;;;;EAA0C,CAAC;AACtE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;iBAG5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/wire/pricing.js

@@ -0,0 +1,36 @@
+/**
+ * The pricing vocabulary that crosses the wire: the tier names, the meter
+ * names, and the shape of one rate-card step. Account responses carry these,
+ * so they live in the dependency-free wire layer; the pricing contract
+ * (`../pricing.ts`) derives the rate card, the plans, and the bill arithmetic
+ * from them and re-exports them for its consumers.
+ */
+import { z } from 'zod';
+export const planTierSchema = z.enum(['free', 'scale', 'enterprise']);
+/**
+ * Every meter the engine records, over any transport. This is the closed set
+ * behind the loose `eventName` strings that `UsageRecorder` and the quota gate
+ * pass around.
+ *
+ * Recording and pricing are separate questions. A meter exists so usage can be
+ * gated and attributed; whether it reaches an invoice is `METER_EVENT_AXIS`.
+ * Bootstraps are recorded and quota-gated but deliberately unpriced: a bootstrap
+ * is what a client does once to become useful, and charging for it would price
+ * the act of connecting.
+ */
+export const meterEventSchema = z.enum([
+    'api.commit_ops',
+    'api.model_reads',
+    'api.claim_creates',
+    'api.bootstraps',
+]);
+/**
+ * One step of the rate card. `throughOps` is the cumulative ceiling the rate
+ * applies up to, and `null` marks the final, unbounded step. Rates are marginal:
+ * crossing a ceiling reprices the operations above it, never the ones below.
+ */
+export const rateBracketSchema = z.object({
+    throughOps: z.number().int().positive().nullable(),
+    usdPerMillionOps: z.number().nonnegative(),
+});
+//# sourceMappingURL=pricing.js.map

package/dist/wire/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/wire/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;AAGtE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC;IACrC,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;CACjB,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAClD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;CAC3C,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/transaction",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "The headless Ablo transaction client and canonical contracts for reads, commits, settlement, claims, and durable observation.",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,11 @@
       "import": "./dist/errorCodes.js",
       "default": "./dist/errorCodes.js"
     },
+    "./pricing": {
+      "types": "./dist/pricing.d.ts",
+      "import": "./dist/pricing.js",
+      "default": "./dist/pricing.js"
+    },
     "./environment": {
       "types": "./dist/environment.d.ts",
       "import": "./dist/environment.js",

package/src/auth/index.ts

@@ -241,16 +241,25 @@ interface MintUserSessionBase {
  * for organizations whose schemas it does not own has no way to name their
  * models, and a grant is checked against the session's schema at mint time. The
  * server expands the verbs across that schema and stores the same enumerated
- * `model.verb` allowlist either way.
+ * `model.verb` allowlist either way. The third form grants no data operations
+ * at all, for a session that only proves identity to control-plane surfaces —
+ * it involves no schema, so it mints even for an organization that has not
+ * pushed one yet.
  */
 export type MintUserSessionRequest = MintUserSessionBase & {
-  /** The allowlist, named model by model. Provide this or the field below. */
+  /** The allowlist, named model by model. Provide exactly one grant form. */
   readonly operations?: readonly GrantedOperation[];
   /**
    * The allowlist as verbs alone, expanded by the server across the models in
-   * the session's active schema. Provide this or the field above.
+   * the session's active schema. Provide exactly one grant form.
    */
   readonly activeSchemaOperations?: readonly CapabilityOperation[];
+  /**
+   * No data operations: the session proves who the user is to control-plane
+   * surfaces (the dashboard, credential provisioning) and can touch no
+   * application data. Provide exactly one grant form.
+   */
+  readonly controlPlaneOnly?: true;
 };
 
 /**
@@ -278,13 +287,19 @@ export async function mintUserSessionKey(
       { code: 'base_url_missing' },
     );
   }
-  // Exactly one grant form. Both would be two answers to one question; neither
+  // Exactly one grant form. Several would be two answers to one question; none
   // would send an empty allowlist, and an empty allowlist is read as
   // unrestricted rather than as nothing. The server refuses either way; this
   // says so before the round trip, where the caller can see which call did it.
-  if ((options.operations === undefined) === (options.activeSchemaOperations === undefined)) {
+  const grantForms = [
+    options.operations,
+    options.activeSchemaOperations,
+    options.controlPlaneOnly,
+  ].filter((form) => form !== undefined).length;
+  if (grantForms !== 1) {
     throw new AbloAuthenticationError(
-      'Provide either operations or activeSchemaOperations for a user-session mint, not both.',
+      'Provide exactly one of operations, activeSchemaOperations, or controlPlaneOnly ' +
+        'for a user-session mint.',
       { code: 'invalid_body' },
     );
   }
@@ -316,9 +331,11 @@ export async function mintUserSessionKey(
             }
           : {}),
         ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
-        ...(options.operations
-          ? { operations: options.operations }
-          : { activeSchemaOperations: options.activeSchemaOperations }),
+        ...(options.controlPlaneOnly
+          ? { controlPlaneOnly: true }
+          : options.operations
+            ? { operations: options.operations }
+            : { activeSchemaOperations: options.activeSchemaOperations }),
         ttlSeconds: options.ttlSeconds,
         ...(options.label ? { label: options.label } : {}),
       }),

package/src/auth/schemas.ts

@@ -46,9 +46,20 @@ export const EphemeralKeyResponseSchema = z.object({
   branchId: z.string().min(1).nullable().default(null),
   branchRoot: z.boolean().default(false),
   syncGroups: z.array(z.string()),
-  /** Effective operation grant stored on the credential. */
-  operations: z.array(grantedOperationSchema).min(1),
-});
+  /** Effective operation grant stored on the credential. Empty ONLY for a
+   *  control-plane-only session, which grants no data operations by design. */
+  operations: z.array(grantedOperationSchema),
+  /** Echoed for a session minted with the control-plane-only grant form: the
+   *  credential proves identity to control-plane surfaces and can touch no
+   *  application data. */
+  controlPlaneOnly: z.literal(true).optional(),
+}).refine(
+  (response) => response.controlPlaneOnly === true || response.operations.length > 0,
+  {
+    message: 'a data session must carry at least one granted operation',
+    path: ['operations'],
+  },
+);
 
 export type EphemeralKeyResponse = z.infer<typeof EphemeralKeyResponseSchema>;
 

package/src/coordination/events.ts

@@ -76,6 +76,15 @@ export interface ConflictEvent {
     id: string;
     fields: readonly string[];
     writtenBy?: ParticipantKind;
+    /**
+     * The group premise this row breached, when the conflict was found at group
+     * grain. `model`/`id` stay the row that actually moved, so a log line can
+     * say which row moved AND which premise it broke — the two used to be the
+     * same field, and a group conflict logged its group key as the row.
+     */
+    group?: string;
+    /** How the row reached `group` — `self`, `parent`, or `transitive`. */
+    via?: string;
   }[];
 }
 

package/src/coordination/index.ts

@@ -24,6 +24,10 @@ export {
   onStaleModeSchema,
   writeGuardSchema,
   staleNotificationSchema,
+  rowStaleNotificationSchema,
+  groupStaleNotificationSchema,
+  stalePropagationSchema,
+
   readDependencySchema,
   trackDependencySchema,
   // Layer 2 — pessimistic claim / claim-lease
@@ -101,6 +105,9 @@ export type {
   OnStaleMode,
   WriteGuard,
   StaleNotification,
+  RowStaleNotification,
+  GroupStaleNotification,
+  StalePropagation,
   ReadDependency,
   TrackDependency,
   // Layer 2 — pessimistic claim / claim-lease
@@ -179,3 +186,4 @@ export {
   modelTarget,
   streamTarget,
 } from './locator.js';
+

package/src/coordination/schema.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod';
-import { syncGroupInputSchema } from '../schema/roles.js';
+import {
+  syncGroupInputSchema,
+  syncGroupRefSchema,
+  syncGroupSchema,
+} from '../schema/roles.js';
 export { syncGroupInputSchema } from '../schema/roles.js';
 import { isFieldRef, type FieldRef } from '../schema/fieldRef.js';
 import type { ParticipantKind } from '../types/participant.js';
@@ -213,6 +217,28 @@ export const targetRefSchema = z.object({
 });
 export type TargetRef = z.infer<typeof targetRefSchema>;
 
+/**
+ * What a {@link ModelClaim} points at — the target locator as SDK callers see
+ * it, keyed by `model` and `id` rather than the wire schema's `entityType` and
+ * `entityId`. This is the public `ModelTarget` shape.
+ *
+ * Declared beside {@link targetRefSchema} because the two are the same shape in
+ * two spellings, and a member added to one belongs in the other. Both are read
+ * by {@link staleNotificationSchema} and the claim family below, so this has to
+ * precede them.
+ */
+export const modelTargetSchema = z
+  .object({
+    model: z.string(),
+    id: z.string(),
+    field: z.string().optional(),
+    /** Several named parts at once — see {@link targetRefSchema}. */
+    fields: z.array(z.string()).readonly().optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+  })
+  .readonly();
+export type ModelTarget = z.infer<typeof modelTargetSchema>;
+
 /**
  * The same locator in the spelling the wait line and the claim handle use —
  * `{ type, id }` for the entity, the sub-entity half unchanged. It is a
@@ -270,45 +296,153 @@ export type WriteGuard = z.infer<typeof writeGuardSchema>;
  * re-commits. `reject` throws instead, and `overwrite` proceeds silently —
  * neither notifies.
  */
-export const staleNotificationSchema = z.object({
+/**
+ * A log position, as the server reports one.
+ *
+ * Server-PRODUCED watermarks are constrained here; the caller-supplied
+ * {@link writeGuardSchema} `readAt` deliberately is not. The asymmetry is the
+ * trust direction, not an oversight: the server controls what it stamps, so
+ * stating the domain costs nothing, while tightening an inbound field would
+ * reject payloads the wire accepts today.
+ */
+const syncIdSchema = z.number().int().nonnegative();
+
+/**
+ * How a change reached the premise that fired — the three ways a record joins a
+ * sync group, which is the vocabulary `RecordGroupSpec` already routes by
+ * (`selfKind` / `parents` / `transitive`) rather than a fourth name for it.
+ *
+ * Without this a group notification can only say "something in the group you
+ * read moved", and the cheapest correct response to that is to re-read the
+ * whole group. `via` plus the notification's `target` narrows it to the row
+ * that actually moved and how it got there, which is usually a one-row re-read.
+ *
+ *   • `self`       — the row that moved IS the group's scope root.
+ *   • `parent`     — it sits one declared containment edge below the root.
+ *   • `transitive` — the root is ≥2 hops up (`comment → task → project`).
+ */
+export const stalePropagationSchema = z
+  .object({
+    via: z.enum(['self', 'parent', 'transitive']),
+    /**
+     * The intermediate models walked from the moved row up to the scope root,
+     * nearest hop first — the part of the route a reader cannot see from the
+     * two endpoints. Empty on `self` and `parent`, which have no intermediate.
+     *
+     * Model names, not rows: naming the intermediate ROWS would cost a join per
+     * notification, and the route is what explains the reach. `target` already
+     * identifies the row that moved and `group` the premise it broke.
+     */
+    through: z.array(z.string()).readonly(),
+  })
+  .readonly();
+export type StalePropagation = z.infer<typeof stalePropagationSchema>;
+
+/**
+ * What both notification scopes carry. The arms below derive from it rather
+ * than restate it, the same way {@link claimStateSchema} projects the claim
+ * record.
+ */
+const staleNotificationBaseSchema = z.object({
   /** Names this object's type; every returned object carries such a tag. */
-  object: z.literal('stale_notification').optional(),
-  /** Model name of the conflicting row. */
-  model: z.string(),
-  /** Row id. */
-  id: z.string(),
-  /** The watermark the committer reasoned against (its `readAt`). */
-  readAt: z.number(),
-  /**
-   * Newest delta id on the row — the committer's new watermark. Re-capture
-   * context at/after this id to reconcile.
-   */
-  observedSyncId: z.number(),
+  object: z.literal('stale_notification'),
   /**
-   * Fields whose concurrent change collided with this write (intersection of
-   * the committer's written columns and a newer delta's `changed_fields`).
-   * Empty ⇒ a whole-entity change (CREATE/DELETE/legacy delta).
+   * The row that moved, and which part of it — `fields` holds the columns whose
+   * concurrent change collided (empty ⇒ a whole-entity CREATE/DELETE).
+   *
+   * The same shape a claim names its subject with, so one reader handles "who
+   * holds this row" and "this row moved under you" without learning two
+   * vocabularies. In BOTH scopes this is the row that actually changed: a group
+   * notification names the moved row here and the fired premise in `group`.
    */
-  conflictingFields: z.array(z.string()),
+  target: modelTargetSchema,
+  /** The watermark the committer reasoned against (its `readAt`). */
+  readAt: syncIdSchema,
   /**
-   * The live values of `conflictingFields` after the conflict — the piece a
-   * plain stale error omits. It lets the actor reconcile without a follow-up read.
+   * Newest delta id on the premise — the committer's new watermark. Re-capture
+   * context at/after this id to reconcile.
    */
-  currentValues: z.record(z.string(), z.unknown()),
+  observedSyncId: syncIdSchema,
   /** Who wrote the conflicting delta. */
   writtenBy: z.object({
     kind: participantKindSchema,
     id: z.string(),
   }),
+});
+
+/** A premise on one row: that row moved. */
+export const rowStaleNotificationSchema = staleNotificationBaseSchema.extend({
+  scope: z.literal('row'),
+  /**
+   * The live values of `target.fields` after the conflict — the piece a plain
+   * stale error omits. It lets the actor reconcile without a follow-up read.
+   *
+   * Row scope only. Reading live values is cheap for one known row and is what
+   * a group breach cannot promise, so the group arm omits the field rather than
+   * carrying an empty one that reads as "nothing changed".
+   */
+  currentValues: z.record(z.string(), z.unknown()),
+});
+export type RowStaleNotification = z.infer<typeof rowStaleNotificationSchema>;
+
+/** A premise on a whole sync group: something in it moved. */
+export const groupStaleNotificationSchema = staleNotificationBaseSchema.extend({
+  scope: z.literal('group'),
+  /**
+   * The group premise that fired (`report:abc`, `section:s1`).
+   *
+   * Same format schema the premise declares, so the value a caller writes into
+   * `reads[].group` and the value it gets back name a group identically. The
+   * BRANDED view is for values Ablo mints; a notification only echoes the
+   * premise it was handed, and re-parsing it to acquire a brand would be a
+   * second validation of data the commit boundary already checked.
+   */
+  group: syncGroupRefSchema,
+  /**
+   * How `target` reached `group`. Absent when the schema's record-group spec is
+   * unavailable to the commit path, which is the only case where the server
+   * knows a group moved without knowing the route.
+   */
+  propagation: stalePropagationSchema.optional(),
   /**
-   * Set when this notification is for a GROUP premise (e.g. `report:abc`,
-   * `section:s1`) rather than a single row — "something in the group you read
-   * changed." For a group notification `conflictingFields`/`currentValues` are
-   * empty (the change could span many rows); re-read the group at
-   * `observedSyncId` to reconcile. Absent ⇒ a row-scoped notification.
+   * How much of the group moved — the decision "re-read these rows" versus
+   * "give up and take the whole group" needs a size, and a premise that only
+   * says *something* changed forces the expensive branch every time.
+   *
+   * Counts DISTINCT ROWS, not deltas: two writes to one row is one row's worth
+   * of re-reading. `sample` names the most recently changed of them and is
+   * capped, so `truncated` says whether it tells the whole story.
+   *
+   * Absent when the commit path did not measure it (a durable `track` fires per
+   * commit and does not pay for the extra statement).
    */
-  group: z.string().optional(),
+  changed: z
+    .object({
+      count: z.number().int().nonnegative(),
+      sample: z.array(modelTargetSchema).readonly(),
+      truncated: z.boolean(),
+    })
+    .optional(),
 });
+export type GroupStaleNotification = z.infer<
+  typeof groupStaleNotificationSchema
+>;
+
+/**
+ * One advisory, two scopes, told apart by `scope`.
+ *
+ * A real discriminated union rather than a flat object with an optional
+ * `group`, which is what {@link readDependencySchema} already does for the
+ * premise side. While it was flat, the two scopes disagreed about what their
+ * fields meant — `model`/`id` held a row in one and the group key in the other,
+ * and `conflictingFields`/`currentValues` were empty by construction in the
+ * group case — so every consumer had to re-derive the scope from `group`'s
+ * presence and read the prose to know which fields were load-bearing.
+ */
+export const staleNotificationSchema = z.discriminatedUnion('scope', [
+  rowStaleNotificationSchema,
+  groupStaleNotificationSchema,
+]);
 export type StaleNotification = z.infer<typeof staleNotificationSchema>;
 
 /**
@@ -338,7 +472,13 @@ const readRowDependencySchema = z.object({
 });
 
 const readGroupDependencySchema = z.object({
-  group: z.string(),
+  /**
+   * The caller-facing view of the format: `reads: [{ group: 'report:abc' }]`
+   * type-checks inline, `'nonsense'` does not. The
+   * {@link groupStaleNotificationSchema} this premise fires uses the branded
+   * view, because there Ablo is the author.
+   */
+  group: syncGroupRefSchema,
   readAt: z.number(),
   onStale: onStaleModeSchema.optional(),
 });
@@ -361,7 +501,12 @@ export type ReadDependency = z.infer<typeof readDependencySchema>;
  * same reference: a track names its target exactly as a read does, and the
  * three ways it differs are stated here as omissions the compiler holds.
  *
- *   • no `onStale` — a track always notifies; that is what tracking is;
+ *   • `onStale` NARROWED, not dropped — `notify` (the default) reports the
+ *     change on the tracker's next receipt and lets the commit through;
+ *     `reject` refuses that commit while the belief is stale, so an agent
+ *     cannot write on something it has been shown to be out of date about.
+ *     `overwrite` is excluded because it means "apply my write anyway" and a
+ *     track guards no write of its own to apply;
  *   • no `fields` — a track fires at row grain, because the server keeps one
  *     row per tracked target and reports that the target moved, not which
  *     column did (`track_dependencies` has no field axis to store one in);
@@ -373,15 +518,36 @@ export type ReadDependency = z.infer<typeof readDependencySchema>;
  * genuinely cannot carry has to be omitted here on purpose, in one line, rather
  * than by being quietly left out of a copy.
  */
-const trackReadAtSchema = { readAt: z.number().optional() } as const;
+/**
+ * A track's disposition — the premise enum with `overwrite` subtracted, derived
+ * from it rather than spelled again, so a mode added to the convention reaches
+ * a track unless it is deliberately excluded here.
+ */
+export const trackOnStaleSchema = onStaleModeSchema.exclude(['overwrite']);
+export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
+
+/**
+ * What a track does when the caller says nothing — reporting, the behavior every
+ * track had before the disposition existed, so an existing registration is
+ * unchanged.
+ *
+ * Declared here because the value has to agree in three places that cannot
+ * import each other: this schema, the column DEFAULT, and the server's insert.
+ * The two SQL copies are pinned to this one by a test
+ * (`trackOnStaleDomain.test.ts`) rather than by anyone remembering.
+ */
+export const DEFAULT_TRACK_ON_STALE: TrackOnStale = 'notify';
+
+const trackBaseSchema = {
+  readAt: z.number().optional(),
+  onStale: trackOnStaleSchema.optional(),
+} as const;
 
 export const trackDependencySchema = z.union([
   readRowDependencySchema
     .omit({ onStale: true, fields: true, readAt: true })
-    .extend(trackReadAtSchema),
-  readGroupDependencySchema
-    .omit({ onStale: true, readAt: true })
-    .extend(trackReadAtSchema),
+    .extend(trackBaseSchema),
+  readGroupDependencySchema.omit({ onStale: true, readAt: true }).extend(trackBaseSchema),
 ]);
 export type TrackDependency = z.infer<typeof trackDependencySchema>;
 
@@ -725,23 +891,6 @@ export const claimExpiredSchema = z.object({
 export type ClaimExpired = z.infer<typeof claimExpiredSchema>;
 
 
-/**
- * What a {@link ModelClaim} points at — the target locator as SDK callers see
- * it, keyed by `model` and `id` rather than the wire schema's `entityType` and
- * `entityId`. This is the public `ModelTarget` shape.
- */
-export const modelTargetSchema = z
-  .object({
-    model: z.string(),
-    id: z.string(),
-    field: z.string().optional(),
-    /** Several named parts at once — see {@link targetRefSchema}. */
-    fields: z.array(z.string()).readonly().optional(),
-    meta: z.record(z.string(), z.unknown()).optional(),
-  })
-  .readonly();
-export type ModelTarget = z.infer<typeof modelTargetSchema>;
-
 /**
  * The two states a claim can be observed in while it still exists.
  *

package/src/coordination/trace.ts

@@ -50,7 +50,15 @@ export function formatClaim(e: ClaimEvent): string {
 
 /** A notify-instead-of-abort stale write as one readable line. */
 export function formatConflict(e: ConflictEvent): string {
-  const rows = e.rows.map((r) => `${r.model}/${r.id}(${r.fields.join(',')})`).join(', ');
+  const rows = e.rows
+    .map((r) => {
+      // A group conflict reads as "which row moved, and which premise it broke",
+      // because those are two different things and the reader needs both to know
+      // whether to re-read one row or the whole group.
+      const premise = r.group ? ` ${r.via ? `${r.via} → ` : '→ '}${r.group}` : '';
+      return `${r.model}/${r.id}(${r.fields.join(',')})${premise}`;
+    })
+    .join(', ');
   return `conflict: tx ${e.clientTxId} — ${e.rows.length} row(s) changed underneath${rows ? `: ${rows}` : ''}`;
 }