@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/index.js

@@ -0,0 +1,20 @@
+/**
+ * The Ablo settlement core (ADR 0013).
+ *
+ * The transaction layer that the reactive client is a consumer of, not the
+ * other way round. The root barrel is deliberate: it exports the seam —
+ * {@link TransactionLayer} — plus exactly the vocabulary its signatures
+ * reference and the error hierarchy callers catch. Everything else stays on
+ * subpaths; every addition here is a decision
+ * (docs/plans/transaction-layer-barrel-design.md).
+ */
+// The client entry point (ADR 0016). The bare import constructs the
+// coordination layer over request/response transport; the reactive
+// materialiser is the consumer package's entry point, layered above it.
+export { Ablo } from './ablo.js';
+export { LogPosition, logPositionSchema, parseLogPosition } from './logPosition.js';
+// The error hierarchy callers catch.
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloContentionError, AbloClaimedError, AbloSessionError, toAbloError, } from './errors.js';
+// Pre-seam leaf surfaces, kept for compatibility with the first extraction.
+export * from './errorCodes.js';
+export * from './environment.js';

package/dist/transaction/keys/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
+ * place so every component that issues or checks a key agrees on the format.
+ *
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
+ * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
+ * so a browser bundle never pulls in `node:crypto`.
+ *
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
+ * mistyped or forged key locally, without a database round-trip. Older keys
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
+ * and parse here with `checksummed: false`.
+ */
+import { z } from 'zod';
+import { type KeyEnvironment } from '../environment.js';
+export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral", "publishable"];
+export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
+export declare const API_KEY_ENVS: readonly ["production", "sandbox"];
+export type ApiKeyEnv = KeyEnvironment;
+/** A structurally-valid Ablo API key, parsed into its parts. */
+export interface ParsedApiKey {
+    /** The original plaintext. */
+    raw: string;
+    kind: ApiKeyKind;
+    env: ApiKeyEnv;
+    /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
+    body: string;
+    /** True when this is the new checksummed format (36-char base62 body). */
+    checksummed: boolean;
+}
+/**
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
+ * rejected without any network call; an older key with no checksum parses with
+ * `checksummed: false` and is left for the server to validate by hash.
+ */
+export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export declare function parseApiKey(raw: string): ParsedApiKey | null;
+/**
+ * Read the environment off a STORED display prefix (`keyPrefix`, the first 12
+ * chars — `rk_test_abcd`), rather than off a full plaintext key.
+ *
+ * A key row records its environment nowhere but its prefix, so this is how a
+ * server-side flow that only has the row — rotation, most importantly — recovers
+ * the credential's own mode. Returns null when the prefix is not a recognizable
+ * key spelling, so callers can fail closed rather than fall back to a default.
+ */
+export declare function environmentFromStoredKeyPrefix(prefix: string): KeyEnvironment | null;
+/** True when the key uses the new checksummed format (regardless of validity). */
+export declare function isChecksummedKey(raw: string): boolean;
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export declare function keyChecksumMatches(raw: string): boolean;
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
+    plaintext: string;
+    hash: string;
+    prefix: string;
+};
+/**
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
+ * minted and when one is looked up. A fast hash is the right choice here rather
+ * than a password hash like bcrypt: API keys are long random strings, so there is
+ * no dictionary of guesses to slow down.
+ */
+export declare function hashApiKey(plaintext: string): string;
+/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
+export declare const WEBHOOK_SECRET_PREFIX = "whsec_";
+/**
+ * Mints a webhook signing secret following the Standard Webhooks specification
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
+ * because signing a request with {@link signAbloSourceRequest} needs the live
+ * value. It is therefore kept in a secret store, returned to the customer once at
+ * creation, and never shown again.
+ */
+export declare function generateWebhookSecret(): {
+    plaintext: string;
+    last4: string;
+};

package/dist/transaction/keys/index.js

@@ -0,0 +1,207 @@
+/**
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
+ * place so every component that issues or checks a key agrees on the format.
+ *
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
+ * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
+ * so a browser bundle never pulls in `node:crypto`.
+ *
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
+ * mistyped or forged key locally, without a database round-trip. Older keys
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
+ * and parse here with `checksummed: false`.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { KEY_ENVIRONMENTS, KEY_PREFIX_ENVIRONMENTS, environmentFromKeyPrefix, environmentToKeyPrefix, } from '../environment.js';
+// ── Vocabulary ──────────────────────────────────────────────────────────
+// The four key kinds:
+//   secret (sk_)      — backend and server-to-server use, including agents. Full
+//                       authority; never expose one in a browser.
+//   restricted (rk_)  — a scoped server key, such as an agent session token or a
+//                       narrowed capability.
+//   ephemeral (ek_)   — a short-lived, backend-minted session credential scoped to
+//                       one user, safe to hand to that user's browser. Carries
+//                       `participantKind: 'user'` and its baked-in sync groups.
+//   publishable (pk_) — a long-lived, browser-safe, organization-scoped read-only
+//                       key. It is used directly as the bearer token — never
+//                       exchanged, never expires, nothing to refresh. It grants
+//                       read access to the organization's data and cannot write or
+//                       reach any control-plane operation.
+export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral', 'publishable'];
+// A key's environment is the CREDENTIAL axis, not the plane axis: the format
+// below spells it as one of two prefixes, so a plane name outside those two has
+// no representation here and must not reach `generateApiKey`.
+export const API_KEY_ENVS = KEY_ENVIRONMENTS;
+const PREFIX_BY_KIND = {
+    secret: 'sk',
+    restricted: 'rk',
+    ephemeral: 'ek',
+    publishable: 'pk',
+};
+const KIND_BY_PREFIX = {
+    sk: 'secret',
+    rk: 'restricted',
+    ek: 'ephemeral',
+    pk: 'publishable',
+};
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/** Random base62 chars before the checksum. */
+const KEY_BODY_LEN = 30;
+/** base62(CRC32): 62^6 (~5.7e10) > 2^32, so a CRC32 always fits in 6 chars. */
+const CHECKSUM_LEN = 6;
+/** A new checksummed body is exactly this long and pure base62. */
+const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
+/** `<sk|rk|ek|pk>_<live|test>_<body>`; the body charset covers base62 as well as the legacy base64url form. */
+const KEY_RE = /^(sk|rk|ek|pk)_(live|test)_([0-9A-Za-z\-_]+)$/;
+const BASE62_RE = /^[0-9A-Za-z]+$/;
+// ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(s) {
+    let c = 0xffffffff;
+    for (let i = 0; i < s.length; i++) {
+        // `& 0xff` bounds the index to the 256-entry table — the ?? 0 is unreachable.
+        c = ((CRC32_TABLE[(c ^ s.charCodeAt(i)) & 0xff] ?? 0) ^ (c >>> 8)) >>> 0;
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** 6-char base62 encoding of the CRC32 of `payload`. */
+function checksum6(payload) {
+    let n = crc32(payload);
+    let out = '';
+    for (let i = 0; i < CHECKSUM_LEN; i++) {
+        out = BASE62.charAt(n % 62) + out;
+        n = Math.floor(n / 62);
+    }
+    return out;
+}
+/** `len` cryptographically-random base62 chars (rejection-sampled, no bias). */
+function randomBase62(len) {
+    let out = '';
+    while (out.length < len) {
+        for (const b of randomBytes(len * 2)) {
+            if (b < 248) {
+                out += BASE62.charAt(b % 62);
+                if (out.length === len)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+function bodyIsChecksummed(body) {
+    return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
+}
+/**
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
+ * rejected without any network call; an older key with no checksum parses with
+ * `checksummed: false` and is left for the server to validate by hash.
+ */
+export const apiKeySchema = z.string().transform((raw, ctx) => {
+    const m = KEY_RE.exec(raw);
+    if (!m) {
+        ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+        return z.NEVER;
+    }
+    const [, prefix, env, body] = m;
+    const kind = prefix === undefined ? undefined : KIND_BY_PREFIX[prefix];
+    // Unreachable on a KEY_RE match (all three groups are non-optional and the
+    // prefix alternation is exactly the KIND_BY_PREFIX key set) — narrows the
+    // regex-group lookups for the checks below.
+    if (kind === undefined || env === undefined || body === undefined) {
+        ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+        return z.NEVER;
+    }
+    const checksummed = bodyIsChecksummed(body);
+    if (checksummed && checksum6(raw.slice(0, -CHECKSUM_LEN)) !== body.slice(KEY_BODY_LEN)) {
+        ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
+        return z.NEVER;
+    }
+    return {
+        raw,
+        kind,
+        env: environmentFromKeyPrefix(env),
+        body,
+        checksummed,
+    };
+});
+// ── Derived validators (thin wrappers over the same spec) ───────────────
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export function parseApiKey(raw) {
+    const r = apiKeySchema.safeParse(raw);
+    return r.success ? r.data : null;
+}
+/**
+ * Read the environment off a STORED display prefix (`keyPrefix`, the first 12
+ * chars — `rk_test_abcd`), rather than off a full plaintext key.
+ *
+ * A key row records its environment nowhere but its prefix, so this is how a
+ * server-side flow that only has the row — rotation, most importantly — recovers
+ * the credential's own mode. Returns null when the prefix is not a recognizable
+ * key spelling, so callers can fail closed rather than fall back to a default.
+ */
+export function environmentFromStoredKeyPrefix(prefix) {
+    const spelling = /^(?:sk|rk|ek|pk)_([a-z]+)_/.exec(prefix)?.[1];
+    const env = KEY_PREFIX_ENVIRONMENTS.find((candidate) => candidate === spelling);
+    return env === undefined ? null : environmentFromKeyPrefix(env);
+}
+/** True when the key uses the new checksummed format (regardless of validity). */
+export function isChecksummedKey(raw) {
+    const body = KEY_RE.exec(raw)?.[3];
+    return body !== undefined && bodyIsChecksummed(body);
+}
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export function keyChecksumMatches(raw) {
+    const body = KEY_RE.exec(raw)?.[3];
+    if (body === undefined || !bodyIsChecksummed(body))
+        return false;
+    return checksum6(raw.slice(0, -CHECKSUM_LEN)) === body.slice(KEY_BODY_LEN);
+}
+// ── Mint + hash (node:crypto) ───────────────────────────────────────────
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export function generateApiKey(env = 'production', kind = 'secret') {
+    const body = randomBase62(KEY_BODY_LEN);
+    const payload = `${PREFIX_BY_KIND[kind]}_${environmentToKeyPrefix(env)}_${body}`;
+    const plaintext = `${payload}${checksum6(payload)}`;
+    return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
+}
+/**
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
+ * minted and when one is looked up. A fast hash is the right choice here rather
+ * than a password hash like bcrypt: API keys are long random strings, so there is
+ * no dictionary of guesses to slow down.
+ */
+export function hashApiKey(plaintext) {
+    return createHash('sha256').update(plaintext).digest('hex');
+}
+/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
+export const WEBHOOK_SECRET_PREFIX = 'whsec_';
+/**
+ * Mints a webhook signing secret following the Standard Webhooks specification
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
+ * because signing a request with {@link signAbloSourceRequest} needs the live
+ * value. It is therefore kept in a secret store, returned to the customer once at
+ * creation, and never shown again.
+ */
+export function generateWebhookSecret() {
+    const plaintext = `${WEBHOOK_SECRET_PREFIX}${randomBytes(32).toString('base64')}`;
+    return { plaintext, last4: plaintext.slice(-4) };
+}

package/dist/transaction/log/syncDeltaRow.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
+ * one committed change. The row is split into two 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 a portable
+ *     payload shape; it is not a statement that the row is physically stored in
+ *     the customer's database.
+ *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
+ *
+ * {@link syncDeltaRowSchema} composes both into the full stored row.
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
+ * Keeping those axes separate prevents a portable schema slice from being cited
+ * incorrectly as a physical-residency guarantee.
+ *
+ * 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';
+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";
+    exact: "exact";
+    inferred: "inferred";
+}>;
+export type BackfillProvenance = z.infer<typeof backfillProvenanceSchema>;
+/**
+ * Everything a client needs to materialize the change, plus the tenant key. This
+ * is the portable shape an authoritative WAL change or endpoint event carries.
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
+ * sync log; it is not written atomically with a direct application-row mutation.
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
+ * appended, so they are optional at the ingestion boundary.
+ */
+export declare const syncDeltaCoreSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    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>;
+    sourceChangeId: z.ZodOptional<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>;
+    delegationChainRootUserId: z.ZodOptional<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>;
+/** The complete `sync_deltas` row: core and attribution combined. */
+export declare const syncDeltaRowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    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>;
+    sourceChangeId: z.ZodOptional<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>;
+    delegationChainRootUserId: z.ZodOptional<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 SyncDeltaRow = z.infer<typeof syncDeltaRowSchema>;
+/** Which slices contain retained customer row data versus control metadata. */
+export declare const DELTA_DATA_CLASSIFICATION: {
+    readonly core: "customer-data";
+    readonly attribution: "control-metadata";
+};
+/**
+ * Where the current runtime physically persists each slice. Both live in
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
+ * payloads (and optional previous payloads), so `control` here must not be read
+ * as "metadata only."
+ */
+export declare const DELTA_PHYSICAL_STORAGE: {
+    readonly core: "control";
+    readonly attribution: "control";
+};

package/dist/transaction/log/syncDeltaRow.js

@@ -0,0 +1,95 @@
+/**
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
+ * one committed change. The row is split into two 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 a portable
+ *     payload shape; it is not a statement that the row is physically stored in
+ *     the customer's database.
+ *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
+ *
+ * {@link syncDeltaRowSchema} composes both into the full stored row.
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
+ * Keeping those axes separate prevents a portable schema slice from being cited
+ * incorrectly as a physical-residency guarantee.
+ *
+ * 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, syncDeltaActionSchema, } 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 shape an authoritative WAL change or endpoint event carries.
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
+ * sync log; it is not written atomically with a direct application-row mutation.
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
+ * appended, so they are optional at the ingestion boundary.
+ */
+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; its eight values are owned by the wire delta contract. */
+    actionType: syncDeltaActionSchema,
+    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(),
+    /**
+     * Stable identity of the authoritative WAL row or endpoint event. It is
+     * nullable for hosted/legacy rows and is never exposed as the optimistic
+     * client transaction id.
+     */
+    sourceChangeId: z.string().min(1).nullable().optional(),
+});
+// ── 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(),
+});
+// ── Full stored row, classification, and physical storage ─────────────────────
+/** The complete `sync_deltas` row: core and attribution combined. */
+export const syncDeltaRowSchema = syncDeltaCoreSchema.extend(deltaAttributionSchema.shape);
+/** Which slices contain retained customer row data versus control metadata. */
+export const DELTA_DATA_CLASSIFICATION = {
+    core: 'customer-data',
+    attribution: 'control-metadata',
+};
+/**
+ * Where the current runtime physically persists each slice. Both live in
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
+ * payloads (and optional previous payloads), so `control` here must not be read
+ * as "metadata only."
+ */
+export const DELTA_PHYSICAL_STORAGE = {
+    core: 'control',
+    attribution: 'control',
+};

package/dist/{sync/syncPosition.d.ts → transaction/logPosition.d.ts}

@@ -30,18 +30,18 @@
  * necessarily lands above our acknowledgement and still rejects as stale.
  *
  * The validation schema is the state shape: the class holds exactly one
- * {@link SyncPositionSnapshot} and merges monotonically into it, so snapshot
- * and restore share that shape and {@link parseSyncPosition} is the single gate
+ * {@link LogPositionSnapshot} and merges monotonically into it, so snapshot
+ * and restore share that shape and {@link parseLogPosition} is the single gate
  * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
  * being a known failure mode.
  */
 import { z } from 'zod';
-export declare const syncPositionSchema: z.ZodObject<{
+export declare const logPositionSchema: z.ZodObject<{
     persisted: z.ZodNumber;
     applied: z.ZodNumber;
     acked: z.ZodNumber;
 }, z.core.$strip>;
-export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
+export type LogPositionSnapshot = z.infer<typeof logPositionSchema>;
 /**
  * Only the `persisted` cursor is stored durably; `applied` and `acked` are
  * not. On resume the object pool is rebuilt from the persisted state, so the
@@ -54,15 +54,15 @@ export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
  * Validates an untrusted value, such as one loaded from disk, into a position
  * snapshot, or returns null when it does not match the schema.
  */
-export declare function parseSyncPosition(value: unknown): SyncPositionSnapshot | null;
+export declare function parseLogPosition(value: unknown): LogPositionSnapshot | null;
 /**
  * The live sync position: one instance per client. Three producers each
  * advance their own cursor, and consumers read the result.
  */
-export declare class SyncPosition {
+export declare class LogPosition {
     #private;
     /** Returns a copy of the current state in the schema's shape. */
-    snapshot(): SyncPositionSnapshot;
+    snapshot(): LogPositionSnapshot;
     get persisted(): number;
     get applied(): number;
     get acked(): number;
@@ -79,5 +79,19 @@ export declare class SyncPosition {
     /** Records that the server acknowledged one of this client's commits at the given position. */
     noteAck(lastSyncId: number | undefined): void;
     /** Restores from an already-validated snapshot, for example on resume from disk. The merge is monotonic. */
-    restore(snapshot: SyncPositionSnapshot): void;
+    restore(snapshot: LogPositionSnapshot): void;
 }
+/** @deprecated Renamed to {@link logPositionSchema}. Removed in 0.36.0. */
+export declare const syncPositionSchema: z.ZodObject<{
+    persisted: z.ZodNumber;
+    applied: z.ZodNumber;
+    acked: z.ZodNumber;
+}, z.core.$strip>;
+/** @deprecated Renamed to {@link LogPositionSnapshot}. Removed in 0.36.0. */
+export type SyncPositionSnapshot = LogPositionSnapshot;
+/** @deprecated Renamed to {@link parseLogPosition}. Removed in 0.36.0. */
+export declare const parseSyncPosition: typeof parseLogPosition;
+/** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
+export declare const SyncPosition: typeof LogPosition;
+/** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
+export type SyncPosition = LogPosition;