@abloatai/ablo 0.34.1 → 0.36.0

package/dist/{wire → transaction/wire}/delta.js

@@ -5,9 +5,9 @@
  * 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 (see
- * {@link import('../schema/syncDeltaRow.js').syncDeltaRowSchema}) and differs from
- * it in three ways: it omits `organizationId` (the tenant-isolation predicate is
+ * 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.
@@ -18,16 +18,20 @@
  *   - {@link serverSyncDeltaSchema} — the core plus the audit attribution the server
  *     adds to each broadcast, which the client ignores.
  *
- * The two participant enums below (`participantKind`, `confirmationState`) are the
- * shared vocabulary of the protocol. They live here, at the wire layer, so the
- * stored-row schema can import them downward rather than the wire delta reaching
- * up into the schema DSL for them.
+ * 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';
-// ── Shared participant vocabulary (mirrors the corresponding Postgres enums) ──
-/** `participant_kind` — who a delta is attributed to. */
-export const participantKindSchema = z.enum(['user', 'agent', 'system']);
+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',
@@ -57,12 +61,16 @@ export const wireDeltaDataSchema = z
 /**
  * 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.
+ * 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
@@ -118,6 +126,22 @@ export const serverSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
     /** Foreign key to the authorizing capability; non-null for agent and system commits. */
     capabilityId: z.string().nullable(),
     confirmationState: confirmationStateSchema.nullable(),
-    /** Foreign key to the task for the AI turn whose prompt caused this delta. */
-    causedByTaskId: z.string().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

@@ -0,0 +1,72 @@
+/**
+ * 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/{wire → transaction/wire}/errorEnvelope.js

@@ -12,6 +12,7 @@
  * 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';
 /**
@@ -21,6 +22,28 @@ import { errorCodeSpec } from '../errorCodes.js';
  * 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
@@ -60,16 +83,24 @@ export function statusForType(type) {
  * 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) {
-    if (err instanceof AbloError) {
+    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 = err.httpStatus ??
-            (err.code ? errorCodeSpec(err.code)?.httpStatus : undefined) ??
-            statusForType(err.type);
-        const body = err.toJSON();
+        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,

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

@@ -0,0 +1,60 @@
+/**
+ * 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

@@ -0,0 +1,82 @@
+/**
+ * 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;
+}

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

@@ -0,0 +1,204 @@
+/**
+ * What `GET /v1/logs` returns: one envelope, two arms.
+ *
+ * The feed answers two questions that a caller without a socket cannot
+ * otherwise ask — "what changed" and "who is working on what" — and it answers
+ * them through one endpoint, one envelope, and one cursor grammar rather than
+ * growing a second feed with its own pagination dialect beside the first.
+ *
+ * The arms stay separately sequenced. A claim is a lease, not a settled fact,
+ * and putting one into the log that clients materialize rows from — and that
+ * WAL-echo promotion and compaction operate over — would make a claim-churn
+ * storm indistinguishable from committed change. They share a reading, not a
+ * sequence; {@link FeedCursor} is what carries both positions.
+ */
+import { z } from 'zod';
+import { type LogEvent } from './accountResponses.js';
+import { type ClaimEvent } from './claimEvent.js';
+import { type ListEnvelope } from './listEnvelope.js';
+/**
+ * One entry, from either source. Discriminated on `object`, so a consumer
+ * reading an arm it does not know still parses the page and can skip the entry
+ * — which is what lets the claim arm be added to a running feed at all.
+ */
+export declare const feedEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    object: z.ZodLiteral<"log_event">;
+    id: z.ZodNumber;
+    at: z.ZodString;
+    model: z.ZodString;
+    op: z.ZodEnum<{
+        update: "update";
+        visible: "visible";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+        revive: "revive";
+        group_added: "group_added";
+        group_removed: "group_removed";
+    }>;
+    recordId: z.ZodString;
+    actor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodReadonly<z.ZodObject<{
+    target: z.ZodReadonly<z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        range: z.ZodOptional<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+            startColumn: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        field: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    description: z.ZodString;
+    expiresAt: z.ZodNumber;
+    onBehalfOfId: z.ZodNullable<z.ZodString>;
+    onBehalfOfKind: z.ZodNullable<z.ZodPreprocess<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>>;
+    capabilityId: z.ZodNullable<z.ZodString>;
+    fenceToken: z.ZodOptional<z.ZodNumber>;
+    position: z.ZodOptional<z.ZodNumber>;
+    participantKind: z.ZodPreprocess<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>;
+    actor: z.ZodString;
+    object: z.ZodLiteral<"claim_event">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    claimId: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        committed: "committed";
+        expired: "expired";
+        canceled: "canceled";
+        queued: "queued";
+    }>;
+}, z.core.$strip>>], "object">;
+export type FeedEvent = LogEvent | ClaimEvent;
+/** `GET /v1/logs` — the canonical list envelope over the feed. */
+export declare const logListResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"list">;
+    data: z.ZodReadonly<z.ZodArray<z.ZodType<{
+        object: "log_event";
+        id: number;
+        at: string;
+        model: string;
+        op: "update" | "visible" | "create" | "delete" | "archive" | "revive" | "group_added" | "group_removed";
+        recordId: string;
+        actor: string | null;
+    } | Readonly<{
+        target: Readonly<{
+            model: string;
+            id: string;
+            path?: string | undefined;
+            range?: {
+                startLine: number;
+                endLine: number;
+                startColumn?: number | undefined;
+                endColumn?: number | undefined;
+            } | undefined;
+            field?: string | undefined;
+            fields?: readonly string[] | undefined;
+            meta?: Record<string, unknown> | undefined;
+        }>;
+        description: string;
+        expiresAt: number;
+        onBehalfOfId: string | null;
+        onBehalfOfKind: "user" | "agent" | "system" | null;
+        capabilityId: string | null;
+        participantKind: "user" | "agent" | "system";
+        actor: string;
+        object: "claim_event";
+        seq: number;
+        at: string;
+        claimId: string;
+        status: "active" | "committed" | "expired" | "canceled" | "queued";
+        fenceToken?: number | undefined;
+        position?: number | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<{
+        object: "log_event";
+        id: number;
+        at: string;
+        model: string;
+        op: "update" | "visible" | "create" | "delete" | "archive" | "revive" | "group_added" | "group_removed";
+        recordId: string;
+        actor: string | null;
+    } | Readonly<{
+        target: Readonly<{
+            model: string;
+            id: string;
+            path?: string | undefined;
+            range?: {
+                startLine: number;
+                endLine: number;
+                startColumn?: number | undefined;
+                endColumn?: number | undefined;
+            } | undefined;
+            field?: string | undefined;
+            fields?: readonly string[] | undefined;
+            meta?: Record<string, unknown> | undefined;
+        }>;
+        description: string;
+        expiresAt: number;
+        onBehalfOfId: string | null;
+        onBehalfOfKind: "user" | "agent" | "system" | null;
+        capabilityId: string | null;
+        participantKind: "user" | "agent" | "system";
+        actor: string;
+        object: "claim_event";
+        seq: number;
+        at: string;
+        claimId: string;
+        status: "active" | "committed" | "expired" | "canceled" | "queued";
+        fenceToken?: number | undefined;
+        position?: number | undefined;
+    }>, unknown>>>>;
+    has_more: z.ZodBoolean;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type LogListResponse = ListEnvelope<FeedEvent>;
+/**
+ * The query string on `GET /v1/logs`.
+ *
+ * Values arrive as strings, so this describes the wire spelling rather than the
+ * parsed result — the same reason {@link listQuerySchema} does.
+ *
+ * Scope is NOT here and never will be: the plane, the organization and the sync
+ * groups all come off the credential. A caller cannot widen what it sees by
+ * asking, which is what makes this feed safe to hand an agent.
+ */
+export declare const logQuerySchema: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    op: z.ZodOptional<z.ZodEnum<{
+        update: "update";
+        visible: "visible";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+        revive: "revive";
+        group_added: "group_added";
+        group_removed: "group_removed";
+    }>>;
+    since: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LogQuery = z.infer<typeof logQuerySchema>;
+/**
+ * The claim arm has no producer yet: claim transitions are broadcast today and
+ * recorded nowhere, so there is no sequence to read `seq` from. Until that log
+ * exists the route emits only `log_event`s, and there is deliberately NO
+ * request parameter for selecting arms — a knob that cannot be honoured is how
+ * a contract comes to describe a server that does not exist.
+ *
+ * What is here is the definition the producer will fill: the union parses
+ * today's pages unchanged, and the cursor already carries the second position.
+ */

package/dist/transaction/wire/feedEvent.js

@@ -0,0 +1,65 @@
+/**
+ * What `GET /v1/logs` returns: one envelope, two arms.
+ *
+ * The feed answers two questions that a caller without a socket cannot
+ * otherwise ask — "what changed" and "who is working on what" — and it answers
+ * them through one endpoint, one envelope, and one cursor grammar rather than
+ * growing a second feed with its own pagination dialect beside the first.
+ *
+ * The arms stay separately sequenced. A claim is a lease, not a settled fact,
+ * and putting one into the log that clients materialize rows from — and that
+ * WAL-echo promotion and compaction operate over — would make a claim-churn
+ * storm indistinguishable from committed change. They share a reading, not a
+ * sequence; {@link FeedCursor} is what carries both positions.
+ */
+import { z } from 'zod';
+import { logEventSchema, logOpSchema } from './accountResponses.js';
+import { claimEventSchema } from './claimEvent.js';
+import { listEnvelopeSchema } from './listEnvelope.js';
+/**
+ * One entry, from either source. Discriminated on `object`, so a consumer
+ * reading an arm it does not know still parses the page and can skip the entry
+ * — which is what lets the claim arm be added to a running feed at all.
+ */
+export const feedEventSchema = z.discriminatedUnion('object', [
+    logEventSchema,
+    claimEventSchema,
+]);
+/** `GET /v1/logs` — the canonical list envelope over the feed. */
+export const logListResponseSchema = listEnvelopeSchema(feedEventSchema);
+/**
+ * The query string on `GET /v1/logs`.
+ *
+ * Values arrive as strings, so this describes the wire spelling rather than the
+ * parsed result — the same reason {@link listQuerySchema} does.
+ *
+ * Scope is NOT here and never will be: the plane, the organization and the sync
+ * groups all come off the credential. A caller cannot widen what it sees by
+ * asking, which is what makes this feed safe to hand an agent.
+ */
+export const logQuerySchema = z.object({
+    /**
+     * The `next_cursor` from the previous page, copied back unchanged. Omit it to
+     * start from the most recent entries — this is a tail, so the first page is
+     * the end of the log and `after` walks forward from there.
+     */
+    after: z.string().optional(),
+    /** Entries per page. Clamped server-side; the default is a short tail. */
+    limit: z.string().optional(),
+    /** Only this model's entries. */
+    model: z.string().optional(),
+    /** Only this kind of change. */
+    op: logOpSchema.optional(),
+    /** Only entries at or after this ISO 8601 timestamp. */
+    since: z.string().optional(),
+});
+/**
+ * The claim arm has no producer yet: claim transitions are broadcast today and
+ * recorded nowhere, so there is no sequence to read `seq` from. Until that log
+ * exists the route emits only `log_event`s, and there is deliberately NO
+ * request parameter for selecting arms — a knob that cannot be honoured is how
+ * a contract comes to describe a server that does not exist.
+ *
+ * What is here is the definition the producer will fill: the union parses
+ * today's pages unchanged, and the cursor already carries the second position.
+ */