@abloatai/ablo 0.26.0 → 0.27.0

package/dist/schema/serialize.d.ts

@@ -1,32 +1,30 @@
 /**
- * Schema ⇄ JSON
+ * Schema ⇄ JSON.
  *
- * A `Schema` is serializable except for client-only closures (Zod
- * validators + computed getters). `serializeSchema` emits the plain-data
- * JSON form; `parseSchema` reconstructs a working `Schema` from it.
+ * A `Schema` is fully serializable apart from its client-only closures — the
+ * Zod validators and computed getters. {@link serializeSchema} emits the
+ * plain-data JSON form and {@link parseSchema} reconstructs a working `Schema`
+ * from it: one `Schema` type with two representations.
  *
- * This is the GraphQL `printSchema` / `buildSchema` model: one `Schema`
- * type, two representations. A hosted multi-tenant server obtains a tenant's
- * `Schema` by `parseSchema(json)` instead of an in-process import — the JSON
- * is what travels over the control plane (`ablo push`) and is stored
- * per `(tenant, version)`.
+ * A hosted, multi-tenant server loads a tenant's schema with `parseSchema(json)`
+ * rather than importing it in process. The JSON is what `ablo push` sends and
+ * what the server stores per tenant and version.
  *
  * What round-trips:
- *   - all model routing/scoping metadata (typename, tableName, load,
- *     mutable, the canonical `tenancy` descriptor, bootstrap hints, scope,
- *     grants, entityRoles, the `conflict` disposition map, persist, autoFill,
- *     requiredFields, lazyObservable).
- *     NOTE: the authoring sugar (`policy`/`groups`) is normalized away at
- *     `model()`-build; only the canonical wire fields cross here. `conflict`
- *     is already canonical pure data, so it crosses verbatim.
- *   - relations (incl. resolved `foreignKeyColumn`)
- *   - field metadata (names + type tags), from which validators are rebuilt
- *   - identity roles (already pure data)
+ *   - all model routing and scoping metadata: typename, tableName, load,
+ *     mutable, the `tenancy` descriptor, bootstrap hints, scope, grants,
+ *     entityRoles, 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.
+ *   - relations, including the resolved `foreignKeyColumn`
+ *   - field metadata (names and type tags), from which validators are rebuilt
+ *   - identity roles
  *
- * What does NOT round-trip (client-only, server never needs it):
- *   - `computed` getters (closures) — dropped
- *   - exact Zod refinements — rebuilt as permissive validators from
- *     `FieldMeta` (the server does no field-shape validation anyway)
+ * What does not round-trip, because the server never needs it:
+ *   - computed getters, which are closures and are dropped
+ *   - exact Zod refinements, which are rebuilt as permissive validators from
+ *     {@link FieldMeta}; the server does no field-shape validation
  */
 import type { FieldMeta } from './field.js';
 import type { Tenancy } from './tenancy.js';
@@ -34,10 +32,8 @@ import type { ModelResidency } from './residency.js';
 import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule, ConflictAxis } from './model.js';
 import type { RelationType } from './relation.js';
 import { type Schema, type IdentityRole, type EntityRole } from './schema.js';
-/** Current schema-JSON envelope version. Bump on a breaking change to the
- * JSON shape itself (not the user's schema). v2 replaced the per-model
- * `syncGroupFormat` template string with structured `scope`/`grants`/
- * `entityRoles` (relation-driven sync groups). */
+/** Current schema-JSON envelope version. Bump this on a breaking change to the
+ * JSON shape itself — not to a user's schema. */
 declare const SCHEMA_JSON_VERSION: 3;
 /** A relation in JSON form. Mirrors the serializable members of {@link RelationDef}. */
 export interface RelationJSON {
@@ -56,14 +52,15 @@ export interface ModelJSON {
     readonly typename: string;
     readonly tableName?: string;
     readonly tenancy: Tenancy;
-    /** Database plane. Optional for back-compat: absent in artifacts written before
-     *  the plane axis → read as `tenant` (the default). See `./plane.ts`. */
+    /** 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}. */
     readonly plane?: ModelResidency;
     readonly scope?: boolean | string;
     readonly grants?: GrantsRef;
     readonly entityRoles?: readonly EntityRole[];
-    /** Axis 3 — declared write-conflict disposition per committer kind. Pure data;
-     *  absent in pre-conflict-axis artifacts → undefined → engine default. */
+    /** The declared write-conflict disposition per committer kind. When absent,
+     *  the engine falls back to its default. */
     readonly conflict?: ConflictAxis;
     readonly bootstrapLimit?: number;
     readonly bootstrapOrderBy?: string;

package/dist/schema/serialize.js

@@ -1,40 +1,36 @@
 /**
- * Schema ⇄ JSON
+ * Schema ⇄ JSON.
  *
- * A `Schema` is serializable except for client-only closures (Zod
- * validators + computed getters). `serializeSchema` emits the plain-data
- * JSON form; `parseSchema` reconstructs a working `Schema` from it.
+ * A `Schema` is fully serializable apart from its client-only closures — the
+ * Zod validators and computed getters. {@link serializeSchema} emits the
+ * plain-data JSON form and {@link parseSchema} reconstructs a working `Schema`
+ * from it: one `Schema` type with two representations.
  *
- * This is the GraphQL `printSchema` / `buildSchema` model: one `Schema`
- * type, two representations. A hosted multi-tenant server obtains a tenant's
- * `Schema` by `parseSchema(json)` instead of an in-process import — the JSON
- * is what travels over the control plane (`ablo push`) and is stored
- * per `(tenant, version)`.
+ * A hosted, multi-tenant server loads a tenant's schema with `parseSchema(json)`
+ * rather than importing it in process. The JSON is what `ablo push` sends and
+ * what the server stores per tenant and version.
  *
  * What round-trips:
- *   - all model routing/scoping metadata (typename, tableName, load,
- *     mutable, the canonical `tenancy` descriptor, bootstrap hints, scope,
- *     grants, entityRoles, the `conflict` disposition map, persist, autoFill,
- *     requiredFields, lazyObservable).
- *     NOTE: the authoring sugar (`policy`/`groups`) is normalized away at
- *     `model()`-build; only the canonical wire fields cross here. `conflict`
- *     is already canonical pure data, so it crosses verbatim.
- *   - relations (incl. resolved `foreignKeyColumn`)
- *   - field metadata (names + type tags), from which validators are rebuilt
- *   - identity roles (already pure data)
+ *   - all model routing and scoping metadata: typename, tableName, load,
+ *     mutable, the `tenancy` descriptor, bootstrap hints, scope, grants,
+ *     entityRoles, 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.
+ *   - relations, including the resolved `foreignKeyColumn`
+ *   - field metadata (names and type tags), from which validators are rebuilt
+ *   - identity roles
  *
- * What does NOT round-trip (client-only, server never needs it):
- *   - `computed` getters (closures) — dropped
- *   - exact Zod refinements — rebuilt as permissive validators from
- *     `FieldMeta` (the server does no field-shape validation anyway)
+ * What does not round-trip, because the server never needs it:
+ *   - computed getters, which are closures and are dropped
+ *   - exact Zod refinements, which are rebuilt as permissive validators from
+ *     {@link FieldMeta}; the server does no field-shape validation
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 import { baseFieldsSchema, } from './schema.js';
-/** Current schema-JSON envelope version. Bump on a breaking change to the
- * JSON shape itself (not the user's schema). v2 replaced the per-model
- * `syncGroupFormat` template string with structured `scope`/`grants`/
- * `entityRoles` (relation-driven sync groups). */
+/** Current schema-JSON envelope version. Bump this on a breaking change to the
+ * JSON shape itself — not to a user's schema. */
 const SCHEMA_JSON_VERSION = 3;
 // ── Serialize ────────────────────────────────────────────────────────────────
 function relationToJSON(rel) {
@@ -168,14 +164,14 @@ function modelFromJSON(json) {
         persist: json.persist,
         tableName: json.tableName,
         tenancy: json.tenancy,
-        // Absent in pre-plane-axis artifacts → default `tenant` (matches the model
-        // builder default + the provisioning fallback), so the round-trip is stable.
+        // 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,
-        // Axis 3 — pure data; absent in pre-conflict-axis artifacts → undefined →
-        // the commit path falls through to the function registry / engine default.
+        // Absent in older artifacts → undefined, so the commit path falls through to
+        // the function registry or the engine default.
         conflict: json.conflict,
         mutable: json.mutable,
         lazyObservable: json.lazyObservable,

package/dist/schema/sugar.d.ts

@@ -1,35 +1,20 @@
 /**
- * Claim-first shorthand for `model(...)` — the Modal-inspired DX layer.
+ * A concise, claim-first way to declare a model. Each verb is shorthand for a
+ * {@link model} call with two decisions already made, so a reader learns the two
+ * facts that matter most about an entity before scanning its fields:
  *
- * The factory verbs encode the two orthogonal axes that matter for
- * safety and bootstrap behavior:
+ *   - Writability: `mutable.*` lets clients send create, update, and delete
+ *     operations over the commit protocol. `readOnly.*` means the server owns the
+ *     model — its changes stream to clients as deltas, but clients cannot mutate it.
+ *   - Load strategy: `.instant` loads the model at bootstrap, `.lazy` loads it on
+ *     first access, and `.manual` loads it only when you query it explicitly.
  *
- *   - **Writability** (axis 1): `mutable.*` means clients may send
- *     CREATE/UPDATE/DELETE over the `commit` wire protocol.
- *     `readOnly.*` means the model is server-managed — deltas stream
- *     to clients but clients cannot mutate.
- *   - **Load strategy** (axis 2): `.instant` loads at bootstrap,
- *     `.lazy` loads on first access, `.manual` requires explicit
- *     queries.
+ * The two-token form (`mutable.lazy({...})`) states the safety claim in the first
+ * token and the load shape in the second. The plain {@link model} factory remains
+ * available; these verbs are a convenience layered over it.
  *
- * The two-token form (`mutable.lazy({...})`) reads the safety claim
- * in the first token and the load shape in the second — you know both
- * key facts about the entity before scanning its fields.
- *
- * This is additive: the original `model(...)` factory keeps working.
- * New entities should prefer the verbs; existing entities can migrate
- * entity-by-entity.
- *
- * Example:
+ * @example
  * ```ts
- * // Before — 7 options to read before the fields make sense
- * tasks: model({ title: z.string() }, { ... }, {
- *   typename: 'Task', tableName: 'tasks', mutable: true,
- *   load: 'lazy', lazyObservable: true, computed: tasksComputed,
- * }),
- *
- * // After — claim reads off the verb; options carry only the
- * // fields that actually diverge from defaults
  * tasks: mutable.lazy({ title: z.string() }, {
  *   typename: 'Task', tableName: 'tasks',
  *   relations: { ... },
@@ -57,14 +42,14 @@ export interface SugarOptions<R extends RelationRecord = RelationRecord, C exten
      */
     typename?: string;
     /**
-     * Actual Postgres table name. Override when Prisma's `@@map` diverges
-     * from the naive snake_case of the typename (e.g. `Member` maps to
-     * `'member'` singular, not `'members'`).
+     * The physical table name. Override it when the table name differs from the
+     * snake_case of the typename — for example, a `Member` type stored in a table
+     * named `'member'` rather than `'members'`.
      */
     tableName?: string;
     /**
-     * Row-access policy (tenant isolation / RLS) — who may *read* a row.
-     * Discriminated union on `by` (`column` | `parent` | `none`). See
+     * The row-access policy for tenant isolation — the rule deciding who may read a
+     * row. A discriminated union on `by` (`column`, `parent`, or `none`). See
      * {@link ModelOptions.policy}.
      */
     policy?: ModelOptions['policy'];

package/dist/schema/sugar.js

@@ -1,35 +1,20 @@
 /**
- * Claim-first shorthand for `model(...)` — the Modal-inspired DX layer.
+ * A concise, claim-first way to declare a model. Each verb is shorthand for a
+ * {@link model} call with two decisions already made, so a reader learns the two
+ * facts that matter most about an entity before scanning its fields:
  *
- * The factory verbs encode the two orthogonal axes that matter for
- * safety and bootstrap behavior:
+ *   - Writability: `mutable.*` lets clients send create, update, and delete
+ *     operations over the commit protocol. `readOnly.*` means the server owns the
+ *     model — its changes stream to clients as deltas, but clients cannot mutate it.
+ *   - Load strategy: `.instant` loads the model at bootstrap, `.lazy` loads it on
+ *     first access, and `.manual` loads it only when you query it explicitly.
  *
- *   - **Writability** (axis 1): `mutable.*` means clients may send
- *     CREATE/UPDATE/DELETE over the `commit` wire protocol.
- *     `readOnly.*` means the model is server-managed — deltas stream
- *     to clients but clients cannot mutate.
- *   - **Load strategy** (axis 2): `.instant` loads at bootstrap,
- *     `.lazy` loads on first access, `.manual` requires explicit
- *     queries.
+ * The two-token form (`mutable.lazy({...})`) states the safety claim in the first
+ * token and the load shape in the second. The plain {@link model} factory remains
+ * available; these verbs are a convenience layered over it.
  *
- * The two-token form (`mutable.lazy({...})`) reads the safety claim
- * in the first token and the load shape in the second — you know both
- * key facts about the entity before scanning its fields.
- *
- * This is additive: the original `model(...)` factory keeps working.
- * New entities should prefer the verbs; existing entities can migrate
- * entity-by-entity.
- *
- * Example:
+ * @example
  * ```ts
- * // Before — 7 options to read before the fields make sense
- * tasks: model({ title: z.string() }, { ... }, {
- *   typename: 'Task', tableName: 'tasks', mutable: true,
- *   load: 'lazy', lazyObservable: true, computed: tasksComputed,
- * }),
- *
- * // After — claim reads off the verb; options carry only the
- * // fields that actually diverge from defaults
  * tasks: mutable.lazy({ title: z.string() }, {
  *   typename: 'Task', tableName: 'tasks',
  *   relations: { ... },
@@ -86,8 +71,8 @@ export const mutable = {
  */
 export const readOnly = {
     instant: (shape, opts) => 
-    // Reactive by default (like every variant now): a remote delta that mutates
-    // a row in place must re-render reactive reads. Opt out per-model with
+    // Reactive by default, like every variant: a remote delta that mutates a row
+    // in place must re-render reactive reads. Opt out per-model with
     // `lazyObservable: false` for very large read-only lists where per-field
     // atoms cost more than the QueryView's entry-replaced reactivity.
     build(shape, opts, { mutable: false, load: 'instant', lazyObservable: true }),

package/dist/schema/{sync-delta-row.d.ts → syncDeltaRow.d.ts}

@@ -1,48 +1,25 @@
 /**
- * Canonical Zod description of the `sync_deltas` STORAGE ROW, decomposed by the
- * subsystem it belongs to and the database plane it lives in.
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
+ * one committed change. The row is split into three slices by the concern each one
+ * serves:
  *
- * `sync_deltas` fuses five control-plane subsystems onto one denormalized row
- * (see `docs/plans/sync-delta-zod-decomposition.md`). This module is **P0** of
- * that decomposition: it DESCRIBES the existing columns as Zod schemas — no DB
- * change, no rewiring — so the subsystem + plane boundaries become explicit and
- * type-enforced:
+ *   - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
+ *     needs to reconstruct the change, plus the tenant key. This is the portable
+ *     part, and the only part written atomically with the application row.
+ *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
+ *   - {@link deltaProvenanceSchema} — which AI task, if any, produced it.
  *
- *   - {@link syncDeltaCoreSchema}    — the SYNC-PROTOCOL slice. `tenant` plane:
- *                                      the only part that must be written
- *                                      atomically with the app row, and the shape
- *                                      a BYO outbox marker carries (the portable
- *                                      slice).
- *   - {@link deltaAttributionSchema} — who / on whose authority. `control` plane.
- *   - {@link deltaProvenanceSchema}  — which AI task caused it. `control` plane.
+ * {@link syncDeltaRowSchema} composes all three into the full stored row.
+ * {@link DELTA_RESIDENCY} records which database each slice lives in, so
+ * provisioning can derive that boundary from the schema instead of hand-coding it.
  *
- * {@link syncDeltaRowSchema} is the full stored row (core ∪ attribution ∪
- * provenance). {@link DELTA_RESIDENCY} declares each slice's plane so provisioning
- * (P1) can derive "what a customer DB gets" from the schema, not hand-code it.
- *
- * Distinct from the WIRE `SyncDelta` (`sync/SyncWebSocket.ts`, client-facing) and
- * `SourceDelta` (`source/index.ts`, source-mode input) — those are projections of
- * this row. Field names mirror those + `AuditChainRow` (`@ablo/audit-chain`).
- *
- * Monorepo is on Zod v4 — `.extend(...).shape` (not deprecated `.merge`).
+ * This is the stored shape. The delta broadcast to clients is a narrower projection
+ * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
+ * the field names here mirror those on that wire delta.
  */
 import { z } from 'zod';
-/** `participant_kind` */
-export declare const participantKindSchema: z.ZodEnum<{
-    user: "user";
-    agent: "agent";
-    system: "system";
-}>;
-export type ParticipantKind = z.infer<typeof participantKindSchema>;
-/** `confirmation_state` */
-export declare const confirmationStateSchema: z.ZodEnum<{
-    auto: "auto";
-    previewed: "previewed";
-    approved: "approved";
-    required_human_approval: "required_human_approval";
-    auto_historical: "auto_historical";
-}>;
-export type ConfirmationState = z.infer<typeof confirmationStateSchema>;
+export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
+export type { ParticipantKind, ConfirmationState } from '../wire/delta.js';
 /** `backfill_provenance` */
 export declare const backfillProvenanceSchema: z.ZodEnum<{
     unknown: "unknown";
@@ -51,11 +28,11 @@ export declare const backfillProvenanceSchema: z.ZodEnum<{
 }>;
 export type BackfillProvenance = z.infer<typeof backfillProvenanceSchema>;
 /**
- * Everything a client needs to materialize the change, plus the tenant key. The
- * portable slice: the only part written atomically with the app row, and the
- * shape a BYO outbox marker carries. `id` / `createdAt` / `syncGroups` are
- * control-plane-assigned at enrich/append time, so they're optional here (an
- * outbox marker doesn't have them yet).
+ * Everything a client needs to materialize the change, plus the tenant key. This
+ * is the portable slice: the only part written atomically with the application
+ * row, and the shape an outbox marker in a customer's own database carries. `id`,
+ * `createdAt`, and `syncGroups` are assigned by the server when the delta is
+ * appended, so they are optional here — an outbox marker does not have them yet.
  */
 export declare const syncDeltaCoreSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
@@ -104,7 +81,7 @@ export declare const deltaProvenanceSchema: z.ZodObject<{
     causedByTaskId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type DeltaProvenance = z.infer<typeof deltaProvenanceSchema>;
-/** The complete `sync_deltas` row as stored today (core ∪ attribution ∪ provenance). */
+/** The complete `sync_deltas` row: core, attribution, and provenance combined. */
 export declare const syncDeltaRowSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
     actionType: z.ZodString;
@@ -147,10 +124,10 @@ export declare const syncDeltaRowSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SyncDeltaRow = z.infer<typeof syncDeltaRowSchema>;
 /**
- * Each slice's database plane. The durable answer to "what does a BYO customer DB
- * get?" — only `tenant`-plane slices. Provisioning (P1) reads this instead of
- * hand-coding the boundary; the BYO outbox writes the `tenant` slice and the
- * relay enriches the `control` slices in Ablo's own database.
+ * Maps each slice to the database it belongs in. A customer's own database holds
+ * only the `tenant` slice; the `control` slices are enriched and stored in the
+ * host's own database. Provisioning reads this map to decide which columns a given
+ * database receives, rather than hand-coding the boundary.
  */
 export declare const DELTA_RESIDENCY: {
     readonly core: "tenant";

package/dist/schema/syncDeltaRow.js

@@ -0,0 +1,89 @@
+/**
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
+ * one committed change. The row is split into three slices by the concern each one
+ * serves:
+ *
+ *   - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
+ *     needs to reconstruct the change, plus the tenant key. This is the portable
+ *     part, and the only part written atomically with the application row.
+ *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
+ *   - {@link deltaProvenanceSchema} — which AI task, if any, produced it.
+ *
+ * {@link syncDeltaRowSchema} composes all three into the full stored row.
+ * {@link DELTA_RESIDENCY} records which database each slice lives in, so
+ * provisioning can derive that boundary from the schema instead of hand-coding it.
+ *
+ * This is the stored shape. The delta broadcast to clients is a narrower projection
+ * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
+ * the field names here mirror those on that wire delta.
+ */
+import { z } from 'zod';
+import { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
+// ── Enumerations that mirror the corresponding Postgres enum types ────────────
+// `participant_kind` and `confirmation_state` are shared with the wire delta and
+// live at the wire layer (see `../wire/delta.js`); they are re-exported here so
+// code that imports them from `schema` keeps resolving.
+export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
+/** `backfill_provenance` */
+export const backfillProvenanceSchema = z.enum(['exact', 'inferred', 'unknown']);
+/** A delta payload: the full post-mutation row (or null for deletes). */
+const deltaDataSchema = z.record(z.string(), z.unknown()).nullable();
+// ── Core — the sync-protocol slice ────────────────────────────────────────────
+/**
+ * Everything a client needs to materialize the change, plus the tenant key. This
+ * is the portable slice: the only part written atomically with the application
+ * row, and the shape an outbox marker in a customer's own database carries. `id`,
+ * `createdAt`, and `syncGroups` are assigned by the server when the delta is
+ * appended, so they are optional here — an outbox marker does not have them yet.
+ */
+export const syncDeltaCoreSchema = z.object({
+    /** Monotonically increasing sync id, assigned by the server when the delta is appended; absent on an outbox marker. */
+    id: z.union([z.bigint(), z.number()]).optional(),
+    /** The `action_type` column: a single character, `I` (insert), `U` (update), or `D` (delete). */
+    actionType: z.string().min(1).max(1),
+    modelName: z.string().min(1),
+    modelId: z.string().min(1),
+    data: deltaDataSchema,
+    previousData: deltaDataSchema.optional(),
+    /** Routing keys that decide which subscribers receive this delta; computed by the server at append time. */
+    syncGroups: z.array(z.string()).optional(),
+    /** The committing organization id — the coarse-grained tenant-isolation boundary. */
+    organizationId: z.string().nullable(),
+    /** ISO 8601 timestamp, assigned by the server when the delta is appended. */
+    createdAt: z.string().optional(),
+    transactionId: z.string().nullable(),
+});
+// ── Attribution — who made the change, and on whose authority ─────────────────
+export const deltaAttributionSchema = z.object({
+    /** The acting participant, recorded as a single column for compatibility; the structured pair below is the richer form. */
+    createdBy: z.string().nullable(),
+    actorId: z.string().nullable(),
+    actorKind: participantKindSchema.nullable(),
+    onBehalfOfId: z.string().nullable(),
+    onBehalfOfKind: participantKindSchema.nullable(),
+    capabilityId: z.string().nullable(),
+    delegationChainRootUserId: z.string().nullable().optional(),
+    confirmationState: confirmationStateSchema.nullable(),
+    backfillProvenance: backfillProvenanceSchema.nullable(),
+});
+// ── Provenance — which AI task produced the change ────────────────────────────
+export const deltaProvenanceSchema = z.object({
+    /** Foreign key to the task record for the AI turn that produced this commit; null when no task applies. */
+    causedByTaskId: z.string().nullable(),
+});
+// ── Full stored row and its residency map ─────────────────────────────────────
+/** The complete `sync_deltas` row: core, attribution, and provenance combined. */
+export const syncDeltaRowSchema = syncDeltaCoreSchema
+    .extend(deltaAttributionSchema.shape)
+    .extend(deltaProvenanceSchema.shape);
+/**
+ * Maps each slice to the database it belongs in. A customer's own database holds
+ * only the `tenant` slice; the `control` slices are enriched and stored in the
+ * host's own database. Provisioning reads this map to decide which columns a given
+ * database receives, rather than hand-coding the boundary.
+ */
+export const DELTA_RESIDENCY = {
+    core: 'tenant',
+    attribution: 'control',
+    provenance: 'control',
+};