@abloatai/ablo 0.7.0 → 0.9.0

package/dist/schema/sync-delta-row.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Canonical Zod description of the `sync_deltas` STORAGE ROW, decomposed by the
+ * subsystem it belongs to and the database plane it lives in.
+ *
+ * `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. `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} is the full stored row (core ∪ attribution ∪
+ * provenance). {@link DELTA_PLANES} 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`).
+ */
+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>;
+/** `backfill_provenance` */
+export declare const backfillProvenanceSchema: z.ZodEnum<{
+    unknown: "unknown";
+    exact: "exact";
+    inferred: "inferred";
+}>;
+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).
+ */
+export declare const syncDeltaCoreSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
+    actionType: z.ZodString;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    syncGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    organizationId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    transactionId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SyncDeltaCore = z.infer<typeof syncDeltaCoreSchema>;
+export declare const deltaAttributionSchema: z.ZodObject<{
+    createdBy: z.ZodNullable<z.ZodString>;
+    actorId: z.ZodNullable<z.ZodString>;
+    actorKind: z.ZodNullable<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>;
+    onBehalfOfId: z.ZodNullable<z.ZodString>;
+    onBehalfOfKind: z.ZodNullable<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>;
+    capabilityId: z.ZodNullable<z.ZodString>;
+    confirmationState: z.ZodNullable<z.ZodEnum<{
+        auto: "auto";
+        previewed: "previewed";
+        approved: "approved";
+        required_human_approval: "required_human_approval";
+        auto_historical: "auto_historical";
+    }>>;
+    backfillProvenance: z.ZodNullable<z.ZodEnum<{
+        unknown: "unknown";
+        exact: "exact";
+        inferred: "inferred";
+    }>>;
+}, z.core.$strip>;
+export type DeltaAttribution = z.infer<typeof deltaAttributionSchema>;
+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). */
+export declare const syncDeltaRowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
+    actionType: z.ZodString;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    syncGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    organizationId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    transactionId: z.ZodNullable<z.ZodString>;
+    createdBy: z.ZodNullable<z.ZodString>;
+    actorId: z.ZodNullable<z.ZodString>;
+    actorKind: z.ZodNullable<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>;
+    onBehalfOfId: z.ZodNullable<z.ZodString>;
+    onBehalfOfKind: z.ZodNullable<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>;
+    capabilityId: z.ZodNullable<z.ZodString>;
+    confirmationState: z.ZodNullable<z.ZodEnum<{
+        auto: "auto";
+        previewed: "previewed";
+        approved: "approved";
+        required_human_approval: "required_human_approval";
+        auto_historical: "auto_historical";
+    }>>;
+    backfillProvenance: z.ZodNullable<z.ZodEnum<{
+        unknown: "unknown";
+        exact: "exact";
+        inferred: "inferred";
+    }>>;
+    causedByTaskId: z.ZodNullable<z.ZodString>;
+}, 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.
+ */
+export declare const DELTA_PLANES: {
+    readonly core: "tenant";
+    readonly attribution: "control";
+    readonly provenance: "control";
+};

package/dist/schema/sync-delta-row.js

@@ -0,0 +1,102 @@
+/**
+ * Canonical Zod description of the `sync_deltas` STORAGE ROW, decomposed by the
+ * subsystem it belongs to and the database plane it lives in.
+ *
+ * `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. `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} is the full stored row (core ∪ attribution ∪
+ * provenance). {@link DELTA_PLANES} 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`).
+ */
+import { z } from 'zod';
+// ── Enums (mirror the Postgres enums; @@map name in the comment) ──────────────
+/** `participant_kind` */
+export const participantKindSchema = z.enum(['user', 'agent', 'system']);
+/** `confirmation_state` */
+export const confirmationStateSchema = z.enum([
+    'auto',
+    'previewed',
+    'approved',
+    'required_human_approval',
+    'auto_historical',
+]);
+/** `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 — `tenant` plane (the sync-protocol slice) ───────────────────────────
+/**
+ * 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).
+ */
+export const syncDeltaCoreSchema = z.object({
+    /** Monotonic sync id; assigned control-plane on append (absent on a marker). */
+    id: z.union([z.bigint(), z.number()]).optional(),
+    /** `action_type` — single char: `I` | `U` | `D`. */
+    actionType: z.string().min(1).max(1),
+    modelName: z.string().min(1),
+    modelId: z.string().min(1),
+    data: deltaDataSchema,
+    previousData: deltaDataSchema.optional(),
+    /** Sync-group routing keys; computed control-plane (`buildDeltaSyncGroups`). */
+    syncGroups: z.array(z.string()).optional(),
+    /** The TRUSTED committing org — the coarse tenant-isolation boundary. */
+    organizationId: z.string().nullable(),
+    /** ISO timestamp; control-plane-assigned at append. */
+    createdAt: z.string().optional(),
+    transactionId: z.string().nullable(),
+});
+// ── Attribution — `control` plane (→ agent_capability_roots) ──────────────────
+export const deltaAttributionSchema = z.object({
+    /** Legacy single-actor column, derived during the dual-write window. */
+    createdBy: z.string().nullable(),
+    actorId: z.string().nullable(),
+    actorKind: participantKindSchema.nullable(),
+    onBehalfOfId: z.string().nullable(),
+    onBehalfOfKind: participantKindSchema.nullable(),
+    capabilityId: z.string().nullable(),
+    confirmationState: confirmationStateSchema.nullable(),
+    backfillProvenance: backfillProvenanceSchema.nullable(),
+});
+// ── Provenance — `control` plane (→ tasks) ────────────────────────────────────
+export const deltaProvenanceSchema = z.object({
+    /** FK to `Task.id` — the LLM turn that produced this commit. */
+    causedByTaskId: z.string().nullable(),
+});
+// ── Full stored row + plane map ───────────────────────────────────────────────
+/** The complete `sync_deltas` row as stored today (core ∪ attribution ∪ provenance). */
+export const syncDeltaRowSchema = syncDeltaCoreSchema
+    .extend(deltaAttributionSchema.shape)
+    .extend(deltaProvenanceSchema.shape);
+/**
+ * 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.
+ */
+export const DELTA_PLANES = {
+    core: 'tenant',
+    attribution: 'control',
+    provenance: 'control',
+};

package/dist/schema/sync-delta-wire.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Canonical Zod contract for the WIRE delta — the broadcast object that travels
+ * server → client (the `delta` / `sync_response` frame payload). This is the
+ * "same contract across both" seam: the SDK client and the sync-server each
+ * derive their `SyncDelta` type from THESE schemas via `z.infer`, instead of
+ * hand-maintaining two interfaces that drift (they had: the server typed
+ * `actionType` as `string` and `createdBy` as a nested ref; the client typed
+ * `actionType` as the 8-value union and `createdBy` as a flat string — a silent
+ * divergence the client never noticed because it ignores attribution).
+ *
+ * Distinct from {@link import('./sync-delta-row.js').syncDeltaRowSchema} — that
+ * is the STORED ROW (has `organizationId`, flat `actor_id`/`actor_kind`
+ * columns, single-char action). The wire delta is a PROJECTION: no
+ * `organizationId` (the server-trusted isolation predicate is never broadcast),
+ * the full Linear action vocabulary, and attribution hydrated into nested
+ * {@link ParticipantRef}s.
+ *
+ * Shape (per the "shared core + layer extensions" decision):
+ *   - {@link syncDeltaWireCoreSchema} — the fields BOTH sides agree on.
+ *   - {@link clientSyncDeltaSchema}    — core + the SDK-only extras.
+ *   - {@link serverSyncDeltaSchema}    — core + the audit attribution the server
+ *                                        enriches each broadcast with (the client
+ *                                        structurally ignores these).
+ *
+ * Monorepo is on Zod v4.
+ */
+import { z } from 'zod';
+/**
+ * `action_type` on the WIRE — the full Linear-compatible vocabulary a broadcast
+ * carries (vs the stored row's core CRUD). `I`nsert, `U`pdate, `D`elete,
+ * `A`rchive, `V` reVive/unarchive, `C`overing (gained visibility), `G`roupAdded,
+ * `S` groupRemoved.
+ */
+export declare const syncDeltaActionSchema: z.ZodEnum<{
+    A: "A";
+    I: "I";
+    U: "U";
+    D: "D";
+    C: "C";
+    G: "G";
+    S: "S";
+    V: "V";
+}>;
+export type SyncDeltaAction = z.infer<typeof syncDeltaActionSchema>;
+/**
+ * A wire delta payload: the post-mutation row object, a control-frame STRING
+ * (e.g. a serialized group-change payload on `G`/`S` deltas), or `null` (on
+ * deletes). Wider than the stored `data` (row-or-null) precisely because the
+ * group/permission frames serialize a string.
+ */
+export declare const wireDeltaDataSchema: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+export type WireDeltaData = z.infer<typeof wireDeltaDataSchema>;
+/**
+ * A nested participant reference as carried on a BROADCAST delta. The server
+ * hydrates the flat `actor_id`/`actor_kind` stored columns into this.
+ */
+export declare const participantRefSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type ParticipantRef = z.infer<typeof participantRefSchema>;
+/**
+ * The fields BOTH server and client agree on for a broadcast delta — the shared
+ * contract. `transactionId` is modelled as the client sees it (optional string);
+ * the server projection widens it to nullable. No `organizationId` (never
+ * broadcast). No `createdBy`/attribution here — those types differ per layer and
+ * live in the extensions below.
+ */
+export declare const syncDeltaWireCoreSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    actionType: z.ZodEnum<{
+        A: "A";
+        I: "I";
+        U: "U";
+        D: "D";
+        C: "C";
+        G: "G";
+        S: "S";
+        V: "V";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    syncGroups: z.ZodArray<z.ZodString>;
+    transactionId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type SyncDeltaWireCore = z.infer<typeof syncDeltaWireCoreSchema>;
+/**
+ * Client projection — core + the SDK-only fields the client reads locally.
+ * `z.infer` of this is the SDK's `SyncDelta` (see `sync/SyncWebSocket.ts`).
+ */
+export declare const clientSyncDeltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    actionType: z.ZodEnum<{
+        A: "A";
+        I: "I";
+        U: "U";
+        D: "D";
+        C: "C";
+        G: "G";
+        S: "S";
+        V: "V";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    syncGroups: z.ZodArray<z.ZodString>;
+    transactionId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    createdBy: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    clientMutationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ClientSyncDelta = z.infer<typeof clientSyncDeltaSchema>;
+/**
+ * Server projection — core + the audit attribution the server enriches each
+ * broadcast with (for the audit pane). The client ignores all of it. Overrides
+ * `transactionId` to nullable (the server's stored-column reality).
+ */
+export declare const serverSyncDeltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    actionType: z.ZodEnum<{
+        A: "A";
+        I: "I";
+        U: "U";
+        D: "D";
+        C: "C";
+        G: "G";
+        S: "S";
+        V: "V";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    syncGroups: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+    transactionId: z.ZodNullable<z.ZodString>;
+    createdBy: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    actor: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    onBehalfOf: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    capabilityId: z.ZodNullable<z.ZodString>;
+    confirmationState: z.ZodNullable<z.ZodEnum<{
+        auto: "auto";
+        previewed: "previewed";
+        approved: "approved";
+        required_human_approval: "required_human_approval";
+        auto_historical: "auto_historical";
+    }>>;
+    causedByTaskId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ServerSyncDelta = z.infer<typeof serverSyncDeltaSchema>;

package/dist/schema/sync-delta-wire.js

@@ -0,0 +1,102 @@
+/**
+ * Canonical Zod contract for the WIRE delta — the broadcast object that travels
+ * server → client (the `delta` / `sync_response` frame payload). This is the
+ * "same contract across both" seam: the SDK client and the sync-server each
+ * derive their `SyncDelta` type from THESE schemas via `z.infer`, instead of
+ * hand-maintaining two interfaces that drift (they had: the server typed
+ * `actionType` as `string` and `createdBy` as a nested ref; the client typed
+ * `actionType` as the 8-value union and `createdBy` as a flat string — a silent
+ * divergence the client never noticed because it ignores attribution).
+ *
+ * Distinct from {@link import('./sync-delta-row.js').syncDeltaRowSchema} — that
+ * is the STORED ROW (has `organizationId`, flat `actor_id`/`actor_kind`
+ * columns, single-char action). The wire delta is a PROJECTION: no
+ * `organizationId` (the server-trusted isolation predicate is never broadcast),
+ * the full Linear action vocabulary, and attribution hydrated into nested
+ * {@link ParticipantRef}s.
+ *
+ * Shape (per the "shared core + layer extensions" decision):
+ *   - {@link syncDeltaWireCoreSchema} — the fields BOTH sides agree on.
+ *   - {@link clientSyncDeltaSchema}    — core + the SDK-only extras.
+ *   - {@link serverSyncDeltaSchema}    — core + the audit attribution the server
+ *                                        enriches each broadcast with (the client
+ *                                        structurally ignores these).
+ *
+ * Monorepo is on Zod v4.
+ */
+import { z } from 'zod';
+import { participantKindSchema, confirmationStateSchema } from './sync-delta-row.js';
+/**
+ * `action_type` on the WIRE — the full Linear-compatible vocabulary a broadcast
+ * carries (vs the stored row's core CRUD). `I`nsert, `U`pdate, `D`elete,
+ * `A`rchive, `V` reVive/unarchive, `C`overing (gained visibility), `G`roupAdded,
+ * `S` groupRemoved.
+ */
+export const syncDeltaActionSchema = z.enum(['I', 'U', 'D', 'A', 'V', 'C', 'G', 'S']);
+/**
+ * A wire delta payload: the post-mutation row object, a control-frame STRING
+ * (e.g. a serialized group-change payload on `G`/`S` deltas), or `null` (on
+ * deletes). Wider than the stored `data` (row-or-null) precisely because the
+ * group/permission frames serialize a string.
+ */
+export const wireDeltaDataSchema = z
+    .union([z.record(z.string(), z.unknown()), z.string()])
+    .nullable();
+/**
+ * A nested participant reference as carried on a BROADCAST delta. The server
+ * hydrates the flat `actor_id`/`actor_kind` stored columns into this.
+ */
+export const participantRefSchema = z.object({
+    kind: participantKindSchema,
+    id: z.string(),
+});
+/**
+ * The fields BOTH server and client agree on for a broadcast delta — the shared
+ * contract. `transactionId` is modelled as the client sees it (optional string);
+ * the server projection widens it to nullable. No `organizationId` (never
+ * broadcast). No `createdBy`/attribution here — those types differ per layer and
+ * live in the extensions below.
+ */
+export const syncDeltaWireCoreSchema = z.object({
+    id: z.number(),
+    actionType: syncDeltaActionSchema,
+    modelName: z.string().min(1),
+    modelId: z.string().min(1),
+    data: wireDeltaDataSchema,
+    previousData: wireDeltaDataSchema.optional(),
+    syncGroups: z.array(z.string()),
+    transactionId: z.string().optional(),
+    createdAt: z.string(),
+});
+/**
+ * Client projection — core + the SDK-only fields the client reads locally.
+ * `z.infer` of this is the SDK's `SyncDelta` (see `sync/SyncWebSocket.ts`).
+ */
+export const clientSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
+    /** @deprecated Flat actor id; superseded by the server's nested `actor`. The
+     *  client never reads it — kept only so the wire shape round-trips. */
+    createdBy: z.string().optional(),
+    /** Client-only payload slot (e.g. legacy group-change metadata). */
+    metadata: wireDeltaDataSchema.optional(),
+    /** Echo-matching id the client correlates against its optimistic mutation. */
+    clientMutationId: z.string().optional(),
+});
+/**
+ * Server projection — core + the audit attribution the server enriches each
+ * broadcast with (for the audit pane). The client ignores all of it. Overrides
+ * `transactionId` to nullable (the server's stored-column reality).
+ */
+export const serverSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
+    transactionId: z.string().nullable(),
+    /** @deprecated Mirrors `actor` 1:1. */
+    createdBy: participantRefSchema.nullable(),
+    /** Who DID the action. */
+    actor: participantRefSchema.nullable(),
+    /** On WHOSE AUTHORITY they acted (equals `actor` for human-direct commits). */
+    onBehalfOf: participantRefSchema.nullable(),
+    /** FK to AgentCapabilityRoot.capabilityId; non-null for agent/system commits. */
+    capabilityId: z.string().nullable(),
+    confirmationState: confirmationStateSchema.nullable(),
+    /** FK to AgentTurn.id — the prompt that caused this delta. */
+    causedByTaskId: z.string().nullable(),
+});