@abloatai/ablo 0.36.0 → 0.37.1

package/dist/transaction/wire/delta.js

@@ -1,147 +0,0 @@
-/**
- * The delta wire contract: the object the server broadcasts to a client as the
- * payload of a `delta` or `sync_response` frame. Both the client SDK and the
- * server derive their delta types from the schemas here, so the two ends share
- * one definition and cannot drift apart. This is the delta's home in the wire
- * layer, alongside the other protocol shapes in `wire/`.
- *
- * The wire delta is a projection of the stored `sync_deltas` row (the
- * `syncDeltaRowSchema` in `../log/syncDeltaRow.ts`) and differs from it
- * in three ways: it omits `organizationId` (the tenant-isolation predicate is
- * never broadcast), it uses the full action vocabulary (see
- * {@link syncDeltaActionSchema}) rather than plain create, update, and delete, and
- * it carries attribution as nested {@link ParticipantRef}s instead of flat columns.
- *
- * The schemas layer a shared core plus per-side extensions:
- *   - {@link syncDeltaWireCoreSchema} — the fields both sides agree on.
- *   - {@link clientSyncDeltaSchema} — the core plus the fields only the client reads.
- *   - {@link serverSyncDeltaSchema} — the core plus the audit attribution the server
- *     adds to each broadcast, which the client ignores.
- *
- * The participant vocabulary the delta carries is declared once elsewhere and
- * re-served here: the actor union lives in `types/participant.ts` and its
- * runtime validator in `coordination/schema.ts`. Only `confirmationState` has
- * its home in this module, since the approval stage of a committed change is
- * delta attribution and nothing else. All three mirror Postgres enums.
- */
-import { z } from 'zod';
-import { correlationIdSchema } from './commit.js';
-import { participantKindSchema } from '../coordination/schema.js';
-// ── Shared participant vocabulary (declared once; re-served on this subpath) ──
-/** `participant_kind` — who a delta is attributed to. Declared in
- *  `coordination/schema.ts`; re-exported so the wire subpath serves the
- *  vocabulary its delta shapes carry. */
-export { participantKindSchema } from '../coordination/schema.js';
-/** `confirmation_state` — the approval stage a committed change was in. */
-export const confirmationStateSchema = z.enum([
-    'auto',
-    'previewed',
-    'approved',
-    'required_human_approval',
-    'auto_historical',
-]);
-// ── The delta wire shapes ─────────────────────────────────────────────────────
-/**
- * The full set of action codes a wire delta can carry — a broader vocabulary than
- * the stored row's create, update, and delete. Each is a single character: `I`
- * insert, `U` update, `D` delete, `A` archive, `V` revive (unarchive), `C` covering
- * (the row just became visible to this subscriber), `G` group added, and `S` group
- * removed.
- */
-export const syncDeltaActionSchema = z.enum(['I', 'U', 'D', 'A', 'V', 'C', 'G', 'S']);
-/**
- * The payload carried on a wire delta: the post-mutation row as an object, a
- * serialized string (used by the group-change frames on `G` and `S` deltas), or
- * `null` on deletes. This is wider than the stored row's payload — which is only a
- * row or null — because the group-change frames encode their payload as a string.
- */
-export const wireDeltaDataSchema = z
-    .union([z.record(z.string(), z.unknown()), z.string()])
-    .nullable();
-/**
- * A participant reference as carried on a broadcast delta. The server expands the
- * flat `actor_id` and `actor_kind` stored columns into this nested `{ kind, id }`
- * shape. The type is the canonical {@link ParticipantRef} from
- * `types/participant.ts`; the pin below fails to compile if this schema and the
- * canonical shape ever drift.
- */
-export const participantRefSchema = z.object({
-    kind: participantKindSchema,
-    id: z.string(),
-});
-const _participantRefContract = true;
-void _participantRefContract;
-/**
- * The fields the server and client agree on for a broadcast delta — the shared core
- * both projections extend. `transactionId` is typed as the client sees it (an
- * optional string); {@link serverSyncDeltaSchema} widens it to nullable. There is no
- * `organizationId` here (it is never broadcast) and no attribution — those fields
- * differ between the two sides 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(),
-    /** Opaque source-batch identity present only on decoded customer-WAL echoes. */
-    correlationId: correlationIdSchema.optional(),
-    createdAt: z.string(),
-});
-/**
- * The client's view of a wire delta: the shared core plus the fields only the
- * client reads. Inferring this schema gives the SDK's `SyncDelta` type.
- */
-export const clientSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
-    /** @deprecated The actor id as a flat string; superseded by the server's nested
-     *  `actor`. The client does not read it — it exists only so the wire shape round-trips. */
-    createdBy: z.string().optional(),
-    /** A payload slot the client reads locally, such as group-change metadata. */
-    metadata: wireDeltaDataSchema.optional(),
-    /** Echo-matching id the client correlates against its optimistic mutation. */
-    clientMutationId: z.string().optional(),
-});
-/**
- * The server's view of a wire delta: the shared core plus the audit attribution the
- * server adds to each broadcast. The client structurally ignores these fields. This
- * projection also narrows `transactionId` to nullable, matching the stored column.
- */
-export const serverSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
-    /** The plane project the delta was committed on (`''` = the org's default
-     *  project). Server-only: the broadcaster uses it to fan a mixed-project batch
-     *  out ONLY to same-project subscribers. It rides on the frame but the client's
-     *  `clientSyncDeltaSchema` (a non-strict object) strips it — a client only ever
-     *  receives its own project's deltas, so the value is redundant to it. */
-    projectId: z.string(),
-    transactionId: z.string().nullable(),
-    /** @deprecated Duplicates `actor`; read `actor` instead. */
-    createdBy: participantRefSchema.nullable(),
-    /** The participant who performed the action. */
-    actor: participantRefSchema.nullable(),
-    /** The participant on whose authority the actor acted; equal to `actor` for direct human commits. */
-    onBehalfOf: participantRefSchema.nullable(),
-    /** Foreign key to the authorizing capability; non-null for agent and system commits. */
-    capabilityId: z.string().nullable(),
-    confirmationState: confirmationStateSchema.nullable(),
-});
-/**
- * The transaction-layer seam's transport-neutral projection of a broadcast
- * delta. It removes delivery plumbing (`syncGroups`, `transactionId`, and
- * `correlationId`) while retaining the row change and optional audit
- * attribution. `TransactionLayer.observe()` yields this shape.
- */
-export const deltaSchema = syncDeltaWireCoreSchema
-    .omit({
-    syncGroups: true,
-    transactionId: true,
-    correlationId: true,
-})
-    .extend({
-    actor: participantRefSchema.nullable().optional(),
-    onBehalfOf: participantRefSchema.nullable().optional(),
-    capabilityId: z.string().nullable().optional(),
-    confirmationState: confirmationStateSchema.nullable().optional(),
-});

package/dist/transaction/wire/errorEnvelope.d.ts

@@ -1,72 +0,0 @@
-/**
- * Turns any thrown value into the canonical error envelope and an HTTP status,
- * so every error response carries the same
- * `{ type, code, param, message, doc_url, request_id }` shape no matter which
- * route or transport produced it. This is the counterpart to the wire-parsing
- * helpers in the errors module, which turn a received envelope back into a typed
- * error.
- *
- * It has no dependency on the client runtime, so a server-side handler can
- * import it on its own to format error responses. A typed {@link AbloError}
- * passes through with its code and status intact; anything else becomes a
- * generic 500. A service that needs to classify database-driver failures can
- * layer that on top before falling back to this baseline.
- */
-import { z } from 'zod';
-/**
- * The fixed, public-facing message returned for an unclassified 500. A raw
- * `err.message` can carry driver text, connection strings, or stack fragments,
- * so it is never placed on the wire; a caller that needs those details logs the
- * original error server-side before formatting the response.
- */
-export declare const INTERNAL_ERROR_PUBLIC_MESSAGE = "An internal error occurred.";
-/**
- * The canonical error envelope schema. Every HTTP error response and every
- * structured frame error carries these keys. `catchall` preserves typed domain
- * details such as `missingIds`, `conflicts`, or `retryAfterSeconds` as additive
- * top-level members, so newer producers remain compatible with older readers.
- */
-export declare const errorEnvelopeSchema: z.ZodObject<{
-    type: z.ZodString;
-    code: z.ZodOptional<z.ZodString>;
-    param: z.ZodOptional<z.ZodString>;
-    message: z.ZodString;
-    doc_url: z.ZodOptional<z.ZodString>;
-    request_id: z.ZodOptional<z.ZodString>;
-    errors: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
-        code: z.ZodOptional<z.ZodString>;
-        message: z.ZodString;
-        param: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>>>;
-}, z.core.$catchall<z.ZodUnknown>>;
-export type ErrorEnvelope = Readonly<z.infer<typeof errorEnvelopeSchema>>;
-/** Maps an {@link AbloError} subclass name to its default HTTP status. Each
- *  subclass is chosen to match the status — a validation error is a 400, a
- *  permission error a 403 — so a throw site picks the right class and code and
- *  the status follows. An explicit `httpStatus` is supplied only when it
- *  diverges, such as a 404 on the base class or a 503 on a server error. */
-export declare function statusForType(type: string): number;
-/**
- * Converts any thrown value into the canonical {@link ErrorEnvelope} and an HTTP
- * status. A typed {@link AbloError} is serialized through its own `toJSON`, so
- * its code, param, doc_url, and structured details survive, and its status comes
- * from an explicit `httpStatus` or, failing that, {@link statusForType}.
- * Anything else becomes a 500 `internal_error` envelope — never a bare framework
- * "Internal Server Error" body, and never a raw error string leaked onto the
- * wire as an unregistered code.
- *
- * When `requestId` is supplied and the error does not already carry one, it is
- * stamped into the body so the response and the `x-request-id` header agree for
- * support correlation.
- *
- * A service that recognizes failures this module cannot — a database driver's
- * integrity or privilege errors, say — classifies them into an {@link AbloError}
- * before calling here, and that error then travels the same serialization and
- * status precedence as every other one. This module deliberately takes no
- * classifier callback: it would cross a package boundary, where an argument the
- * built copy does not declare is dropped in silence rather than refused.
- */
-export declare function errorEnvelope(err: unknown, requestId?: string): {
-    body: ErrorEnvelope;
-    status: number;
-};

package/dist/transaction/wire/errorEnvelope.js

@@ -1,123 +0,0 @@
-/**
- * Turns any thrown value into the canonical error envelope and an HTTP status,
- * so every error response carries the same
- * `{ type, code, param, message, doc_url, request_id }` shape no matter which
- * route or transport produced it. This is the counterpart to the wire-parsing
- * helpers in the errors module, which turn a received envelope back into a typed
- * error.
- *
- * It has no dependency on the client runtime, so a server-side handler can
- * import it on its own to format error responses. A typed {@link AbloError}
- * passes through with its code and status intact; anything else becomes a
- * generic 500. A service that needs to classify database-driver failures can
- * layer that on top before falling back to this baseline.
- */
-import { z } from 'zod';
-import { AbloError, docUrlForCode } from '../errors.js';
-import { errorCodeSpec } from '../errorCodes.js';
-/**
- * The fixed, public-facing message returned for an unclassified 500. A raw
- * `err.message` can carry driver text, connection strings, or stack fragments,
- * so it is never placed on the wire; a caller that needs those details logs the
- * original error server-side before formatting the response.
- */
-export const INTERNAL_ERROR_PUBLIC_MESSAGE = 'An internal error occurred.';
-const errorEnvelopeItemSchema = z.object({
-    code: z.string().optional(),
-    message: z.string(),
-    param: z.string().optional(),
-}).readonly();
-/**
- * The canonical error envelope schema. Every HTTP error response and every
- * structured frame error carries these keys. `catchall` preserves typed domain
- * details such as `missingIds`, `conflicts`, or `retryAfterSeconds` as additive
- * top-level members, so newer producers remain compatible with older readers.
- */
-export const errorEnvelopeSchema = z
-    .object({
-    type: z.string(),
-    code: z.string().optional(),
-    param: z.string().optional(),
-    message: z.string(),
-    doc_url: z.string().optional(),
-    request_id: z.string().optional(),
-    errors: z.array(errorEnvelopeItemSchema).readonly().optional(),
-})
-    .catchall(z.unknown());
-/** Maps an {@link AbloError} subclass name to its default HTTP status. Each
- *  subclass is chosen to match the status — a validation error is a 400, a
- *  permission error a 403 — so a throw site picks the right class and code and
- *  the status follows. An explicit `httpStatus` is supplied only when it
- *  diverges, such as a 404 on the base class or a 503 on a server error. */
-export function statusForType(type) {
-    switch (type) {
-        case 'AbloAuthenticationError':
-            return 401;
-        case 'AbloPermissionError':
-            return 403;
-        case 'AbloValidationError':
-            return 400;
-        case 'AbloRateLimitError':
-            return 429;
-        case 'AbloIdempotencyError':
-        case 'AbloStaleContextError':
-        case 'AbloClaimedError':
-            return 409;
-        case 'AbloConnectionError':
-            return 503;
-        case 'AbloServerError':
-            return 500;
-        default:
-            return 500;
-    }
-}
-/**
- * Converts any thrown value into the canonical {@link ErrorEnvelope} and an HTTP
- * status. A typed {@link AbloError} is serialized through its own `toJSON`, so
- * its code, param, doc_url, and structured details survive, and its status comes
- * from an explicit `httpStatus` or, failing that, {@link statusForType}.
- * Anything else becomes a 500 `internal_error` envelope — never a bare framework
- * "Internal Server Error" body, and never a raw error string leaked onto the
- * wire as an unregistered code.
- *
- * When `requestId` is supplied and the error does not already carry one, it is
- * stamped into the body so the response and the `x-request-id` header agree for
- * support correlation.
- *
- * A service that recognizes failures this module cannot — a database driver's
- * integrity or privilege errors, say — classifies them into an {@link AbloError}
- * before calling here, and that error then travels the same serialization and
- * status precedence as every other one. This module deliberately takes no
- * classifier callback: it would cross a package boundary, where an argument the
- * built copy does not declare is dropped in silence rather than refused.
- */
-export function errorEnvelope(err, requestId) {
-    const typed = err instanceof AbloError ? err : undefined;
-    if (typed !== undefined) {
-        // Status precedence: an explicit httpStatus wins; else the code's canonical
-        // status from the registry (so `new AbloError('…', { code: 'entity_not_found' })`
-        // is a 404 without the throw site repeating it); else the subclass default.
-        const status = typed.httpStatus ??
-            (typed.code ? errorCodeSpec(typed.code)?.httpStatus : undefined) ??
-            statusForType(typed.type);
-        const body = typed.toJSON();
-        return {
-            body: requestId && body.request_id === undefined ? { ...body, request_id: requestId } : body,
-            status,
-        };
-    }
-    // Unknown throw: mask it. An unclassified 500 can carry database, driver, or
-    // other internal detail, so the raw message is never echoed here — this
-    // envelope is served directly to browsers. The original error stays with the
-    // caller for logging.
-    return {
-        body: {
-            type: 'AbloServerError',
-            code: 'internal_error',
-            message: INTERNAL_ERROR_PUBLIC_MESSAGE,
-            doc_url: docUrlForCode('internal_error'),
-            ...(requestId ? { request_id: requestId } : {}),
-        },
-        status: 500,
-    };
-}

package/dist/transaction/wire/feedCursor.d.ts

@@ -1,60 +0,0 @@
-/**
- * The resume position for `GET /v1/logs`.
- *
- * The feed merges two independently-sequenced sources — the settlement log and
- * the claim-event log — so one opaque cursor has to carry two positions. They
- * cannot share a sequence: allocating claim positions from `next_sync_id` would
- * put ephemeral leases into the log that clients materialize rows from and that
- * WAL-echo promotion and compaction operate over, where a claim-churn storm
- * would be indistinguishable from committed change.
- *
- * Encoded `"<log>.<claims>"`, and a bare `"<log>"` still parses — cursors are
- * persisted by callers, and every one issued before this existed is a plain
- * delta id. Those resume at claim position 0, which is correct: a caller who
- * never asked for claim events has no claim position to preserve.
- *
- * **A malformed cursor is an error, never a position.** The previous reader was
- * `parseInt(raw, 10)` with `NaN ? 0 : n`, so a truncated or garbled cursor
- * silently resumed from the beginning of the log and replayed it in full. That
- * is the worst available failure: it looks like a working follow, and the
- * damage scales with how long the log has been running. Parsing returns null
- * and the route answers `invalid_request`.
- */
-import { z } from 'zod';
-export declare const feedCursorSchema: z.ZodObject<{
-    log: z.ZodNumber;
-    claims: z.ZodNumber;
-}, z.core.$strip>;
-export type FeedCursor = z.infer<typeof feedCursorSchema>;
-/**
- * The cursor grammar, in one place, so the parser and the error that rejects a
- * bad one cannot describe it differently. A reader who is told what shape was
- * expected can fix the call; a reader told only that theirs was wrong cannot.
- */
-export declare const FEED_CURSOR_FORMAT = "<log>[.<claims>]";
-/** A cursor that shows the grammar rather than only naming it. */
-export declare const FEED_CURSOR_EXAMPLE = "4210.17";
-/** The cursor a caller resumes from when they send none. */
-export declare const FEED_CURSOR_START: FeedCursor;
-/**
- * Reads a wire cursor. Returns null when the string is not one — the caller
- * turns that into `invalid_request` rather than guessing a position.
- *
- * Deliberately strict: only digits and at most one separator. `Number()` alone
- * would accept `'1e3'`, `'0x10'`, `' 42 '`, and `''`, each of which would
- * resume somewhere the caller did not ask for.
- */
-export declare function parseFeedCursor(raw: string): FeedCursor | null;
-/** Writes a wire cursor. Always both positions, so the shape never varies. */
-export declare function formatFeedCursor(cursor: FeedCursor): string;
-/**
- * Whether `next` is ahead of `prev` on either axis — the guard a follow loop
- * needs so a stale or duplicated page cannot rewind it.
- *
- * It lives here because the alternative is what every caller reaches for first:
- * comparing the cursor STRINGS as numbers. `Number('42.10')` is `42.1`, which
- * compares as *behind* `42.9` and re-serializes as `'42.1'` — a cursor that
- * silently skips eight claim positions and looks like it worked. A cursor is
- * opaque to its holder; only this module takes it apart.
- */
-export declare function feedCursorAdvanced(prev: FeedCursor, next: FeedCursor): boolean;

package/dist/transaction/wire/feedCursor.js

@@ -1,82 +0,0 @@
-/**
- * The resume position for `GET /v1/logs`.
- *
- * The feed merges two independently-sequenced sources — the settlement log and
- * the claim-event log — so one opaque cursor has to carry two positions. They
- * cannot share a sequence: allocating claim positions from `next_sync_id` would
- * put ephemeral leases into the log that clients materialize rows from and that
- * WAL-echo promotion and compaction operate over, where a claim-churn storm
- * would be indistinguishable from committed change.
- *
- * Encoded `"<log>.<claims>"`, and a bare `"<log>"` still parses — cursors are
- * persisted by callers, and every one issued before this existed is a plain
- * delta id. Those resume at claim position 0, which is correct: a caller who
- * never asked for claim events has no claim position to preserve.
- *
- * **A malformed cursor is an error, never a position.** The previous reader was
- * `parseInt(raw, 10)` with `NaN ? 0 : n`, so a truncated or garbled cursor
- * silently resumed from the beginning of the log and replayed it in full. That
- * is the worst available failure: it looks like a working follow, and the
- * damage scales with how long the log has been running. Parsing returns null
- * and the route answers `invalid_request`.
- */
-import { z } from 'zod';
-export const feedCursorSchema = z.object({
-    /** Last delta id delivered. */
-    log: z.number().int().nonnegative(),
-    /** Last claim-event seq delivered. */
-    claims: z.number().int().nonnegative(),
-});
-/**
- * The cursor grammar, in one place, so the parser and the error that rejects a
- * bad one cannot describe it differently. A reader who is told what shape was
- * expected can fix the call; a reader told only that theirs was wrong cannot.
- */
-export const FEED_CURSOR_FORMAT = '<log>[.<claims>]';
-/** A cursor that shows the grammar rather than only naming it. */
-export const FEED_CURSOR_EXAMPLE = '4210.17';
-/** The cursor a caller resumes from when they send none. */
-export const FEED_CURSOR_START = { log: 0, claims: 0 };
-/**
- * Reads a wire cursor. Returns null when the string is not one — the caller
- * turns that into `invalid_request` rather than guessing a position.
- *
- * Deliberately strict: only digits and at most one separator. `Number()` alone
- * would accept `'1e3'`, `'0x10'`, `' 42 '`, and `''`, each of which would
- * resume somewhere the caller did not ask for.
- */
-export function parseFeedCursor(raw) {
-    const match = /^(\d+)(?:\.(\d+))?$/.exec(raw);
-    if (!match)
-        return null;
-    const parsed = feedCursorSchema.safeParse({
-        log: Number(match[1]),
-        claims: match[2] === undefined ? 0 : Number(match[2]),
-    });
-    if (!parsed.success)
-        return null;
-    // Beyond 2^53 the positions stop round-tripping through JSON's number type,
-    // and a cursor that cannot round-trip is not a cursor.
-    if (!Number.isSafeInteger(parsed.data.log) ||
-        !Number.isSafeInteger(parsed.data.claims)) {
-        return null;
-    }
-    return parsed.data;
-}
-/** Writes a wire cursor. Always both positions, so the shape never varies. */
-export function formatFeedCursor(cursor) {
-    return `${cursor.log}.${cursor.claims}`;
-}
-/**
- * Whether `next` is ahead of `prev` on either axis — the guard a follow loop
- * needs so a stale or duplicated page cannot rewind it.
- *
- * It lives here because the alternative is what every caller reaches for first:
- * comparing the cursor STRINGS as numbers. `Number('42.10')` is `42.1`, which
- * compares as *behind* `42.9` and re-serializes as `'42.1'` — a cursor that
- * silently skips eight claim positions and looks like it worked. A cursor is
- * opaque to its holder; only this module takes it apart.
- */
-export function feedCursorAdvanced(prev, next) {
-    return next.log > prev.log || next.claims > prev.claims;
-}