@abloatai/ablo 0.34.1 → 0.36.0

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

@@ -0,0 +1,54 @@
+/**
+ * The wire contract for the sync protocol: the HTTP envelope shapes and the
+ * write-path frames, with no dependency on the client runtime. A server — a
+ * route handler, an edge function — can import the envelope producers here
+ * without pulling in the full sync client.
+ *
+ * It has two halves, used across every endpoint:
+ *   - Error responses — {@link errorEnvelope}, {@link ErrorEnvelope}, and
+ *     {@link statusForType} turn any thrown value into the uniform
+ *     `{ type, code, param, message, doc_url, request_id }` body.
+ *   - List responses — {@link listEnvelope} and {@link ListEnvelope} stamp the
+ *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
+ *
+ * The {@link AbloError} hierarchy, {@link docUrlForCode}, and the wire-parsing
+ * helpers are re-exported too, so a single import lets a route throw the right
+ * typed error and serialize it back out.
+ */
+export { errorEnvelopeSchema, errorEnvelope, statusForType, INTERNAL_ERROR_PUBLIC_MESSAGE, } from './errorEnvelope.js';
+export type { ErrorEnvelope } from './errorEnvelope.js';
+export { listEnvelopeSchema, listEnvelope } from './listEnvelope.js';
+export type { ListEnvelope } from './listEnvelope.js';
+export { claimEventSchema } from './claimEvent.js';
+export type { ClaimEvent } from './claimEvent.js';
+export { feedEventSchema, logListResponseSchema, logQuerySchema, } from './feedEvent.js';
+export type { FeedEvent, LogListResponse, LogQuery } from './feedEvent.js';
+export { feedCursorSchema, parseFeedCursor, formatFeedCursor, feedCursorAdvanced, FEED_CURSOR_START, FEED_CURSOR_FORMAT, FEED_CURSOR_EXAMPLE, } from './feedCursor.js';
+export type { FeedCursor } from './feedCursor.js';
+export { bootstrapReasonSchema } from './bootstrapReason.js';
+export type { BootstrapReason } from './bootstrapReason.js';
+export { commitOperationSchema, wireCommitOperationSchema, commitPayloadSchema, commitMessageSchema, } from './frames.js';
+export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
+export type { SupportedProtocolVersion, ProtocolVersionProblem, } from './protocolVersion.js';
+export type { CommitOperation, WireCommitOperation, CommitMessage, MutationResultMessage, } from './frames.js';
+export { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, commitStatusSchema, commitWaitSchema, commitSettlementSchema, commitReceiptSchema, rejectedCommitReceiptSchema, mutationResultPayloadSchema, mutationResultMessageSchema, commitAckSchema, mutationCommitResultSchema, commitOperationControlShape, commitOperationBodySchema, commitRequestSchema, } from './commit.js';
+export type { CommitOperationBody, CommitRequest, CorrelationId, CommitStatus, CommitWait, CommitSettlement, CommitReceiptWire, RejectedCommitReceiptWire, MutationResultPayload, MutationResultMessageWire, CommitAck, MutationCommitResultInput, MutationCommitResult, } from './commit.js';
+export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, deltaSchema, } from './delta.js';
+export type { ParticipantKind, ConfirmationState, SyncDeltaAction, WireDeltaData, ParticipantRef, SyncDeltaWireCore, ClientSyncDelta, ServerSyncDelta, Delta, } from './delta.js';
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloContentionError, AbloClaimedError, CapabilityError, AbloSessionError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, errorCodeSpec, } from '../errors.js';
+export type { ErrorCode, WireErrorCode, RequiredCapability } from '../errors.js';
+export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from './protocol.js';
+export { DEFAULT_CLAIM_TTL_MS, claimTtlSchema, claimTtlMs, claimTargetSchema, claimRequestSchema, claimHeartbeatRequestSchema, listQuerySchema, claimListQuerySchema, claimStateSchema, claimAcquiredResponseSchema, claimQueuedResponseSchema, claimAcquireResponseSchema, claimHeartbeatReplySchema, claimHeartbeatBatchReplySchema, claimListResponseSchema, claimReorderRequestSchema, claimReorderReplySchema, claimReleaseReplySchema, } from './claims.js';
+export type { ClaimTargetBody, ClaimRequest, ClaimHeartbeatRequest, ListQuery, ClaimListQuery, ClaimState, ClaimAcquiredResponse, ClaimQueuedResponse, ClaimAcquireResponse, ClaimHeartbeatReply, ClaimHeartbeatBatchReply, ClaimListResponse, ClaimReorderRequest, ClaimReorderReply, ClaimReleaseReply, } from './claims.js';
+export { modelReadResponseSchema, modelListResponseSchema, } from './modelResponses.js';
+export type { ModelReadResponse, ModelListResponse } from './modelResponses.js';
+export { fieldTypeSchema, fieldMetaSchema, relationTypeSchema, relationMetaSchema, } from './modelShape.js';
+export type { FieldType, FieldMeta, RelationType, RelationMeta, } from './modelShape.js';
+export { modelMutationRequestSchema } from './modelMutations.js';
+export type { ModelMutationRequest } from './modelMutations.js';
+export { projectResponseSchema, projectListResponseSchema, provisionedKeySchema, provisionKeyResponseSchema, conflictAxisWireSchema, schemaModelResponseSchema, schemaReadResponseSchema, logOpSchema, LOG_OP_BY_ACTION, logEventSchema, usageBucketSchema, usageReportResponseSchema, controlKeySchema, controlKeyListResponseSchema, keyMintedResponseSchema, keyRevokedResponseSchema, } from './accountResponses.js';
+export type { ProjectResponse, ProjectListResponse, ProvisionedKey, ProvisionKeyResponse, SchemaModelResponse, SchemaReadResponse, LogOp, LogEvent, UsageBucket, UsageReportResponse, ControlKey, ControlKeyListResponse, KeyMintedResponse, KeyRevokedResponse, } from './accountResponses.js';
+export { WS_INBOUND_FRAMES, wsInboundEnvelopeSchema, isKnownInboundFrame, isSchemaValidatedFrame, } from './inboundFrames.js';
+export type { InboundFrameContract, InboundFrameType, InboundFramePayload, SchemaValidatedFrameType, WsInboundEnvelope, } from './inboundFrames.js';
+export { ephemeralKeyUserSchema, ephemeralKeyRequestSchema, capabilityRequestSchema, capabilityMintResponseSchema, } from './auth.js';
+export type { EphemeralKeyUser, EphemeralKeyRequest, CapabilityRequest, CapabilityMintResponse, } from './auth.js';

package/dist/transaction/wire/index.js

@@ -0,0 +1,83 @@
+/**
+ * The wire contract for the sync protocol: the HTTP envelope shapes and the
+ * write-path frames, with no dependency on the client runtime. A server — a
+ * route handler, an edge function — can import the envelope producers here
+ * without pulling in the full sync client.
+ *
+ * It has two halves, used across every endpoint:
+ *   - Error responses — {@link errorEnvelope}, {@link ErrorEnvelope}, and
+ *     {@link statusForType} turn any thrown value into the uniform
+ *     `{ type, code, param, message, doc_url, request_id }` body.
+ *   - List responses — {@link listEnvelope} and {@link ListEnvelope} stamp the
+ *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
+ *
+ * The {@link AbloError} hierarchy, {@link docUrlForCode}, and the wire-parsing
+ * helpers are re-exported too, so a single import lets a route throw the right
+ * typed error and serialize it back out.
+ */
+export { errorEnvelopeSchema, errorEnvelope, statusForType, INTERNAL_ERROR_PUBLIC_MESSAGE, } from './errorEnvelope.js';
+export { listEnvelopeSchema, listEnvelope } from './listEnvelope.js';
+// The `GET /v1/logs` feed — the two arms, their envelope, and the cursor that
+// carries a position in each.
+export { claimEventSchema } from './claimEvent.js';
+export { feedEventSchema, logListResponseSchema, logQuerySchema, } from './feedEvent.js';
+export { feedCursorSchema, parseFeedCursor, formatFeedCursor, feedCursorAdvanced, FEED_CURSOR_START, FEED_CURSOR_FORMAT, FEED_CURSOR_EXAMPLE, } from './feedCursor.js';
+export { bootstrapReasonSchema } from './bootstrapReason.js';
+// The write-path frame contract: the message shapes shared by the client and
+// the server. The runtime Zod validators sit beside the interfaces and are
+// pinned to them, and they gate every operation and payload on both commit
+// transports.
+export { commitOperationSchema, wireCommitOperationSchema, commitPayloadSchema, commitMessageSchema, } from './frames.js';
+// Protocol versioning: the single integer the client and server compare to
+// confirm they can speak to each other, plus the WebSocket close code used to
+// reject a mismatch. See protocolVersion.ts for the changelog and deploy rules.
+export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
+// Commit settlement backbone. The transport receipt, server execution cache,
+// and normalized client acknowledgement are different envelopes composed from
+// this one discriminated settlement vocabulary.
+export { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, commitStatusSchema, commitWaitSchema, commitSettlementSchema, commitReceiptSchema, rejectedCommitReceiptSchema, mutationResultPayloadSchema, mutationResultMessageSchema, commitAckSchema, mutationCommitResultSchema, 
+// The request side of the same boundary — one definition, which the published
+// OpenAPI reference derives from rather than describing separately.
+commitOperationControlShape, commitOperationBodySchema, commitRequestSchema, } from './commit.js';
+// The read-path delta contract: the shape the server broadcasts to clients as the
+// payload of a `delta` or `sync_response` frame, together with the shared
+// participant vocabulary it carries. Both ends derive their delta type from these
+// schemas, so the client and server cannot drift apart.
+export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, deltaSchema, } from './delta.js';
+// The error surface a wire consumer needs to throw, classify, and serialize.
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloContentionError, AbloClaimedError, CapabilityError, AbloSessionError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, 
+// The table mapping each error code to its HTTP status and retryable flag —
+// plain data a server can use to resolve a code's canonical status the same
+// way the client's error serializer does.
+errorCodeSpec, } from '../errors.js';
+// Protocol timing constants — the 30-second ping cadence and the lease window
+// derived from it, shared by the client heartbeat and the server keepalive,
+// claim leasing, and presence expiry (see protocol.ts) — plus the WebSocket
+// subprotocols used during the authenticated handshake.
+export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from './protocol.js';
+// The claim routes' half of the boundary — requests and responses both, beside
+// the commit body for the same reason: the server answers in these shapes, the
+// client reads them back through the same schemas, and the OpenAPI reference
+// derives from them rather than describing them from memory.
+export { 
+// The lease grammar and its one reading. The server parses TTLs with
+// `claimTtlMs` rather than carrying a second parser — which is how a bare
+// number came to mean seconds on one side and milliseconds on the other.
+DEFAULT_CLAIM_TTL_MS, claimTtlSchema, claimTtlMs, claimTargetSchema, claimRequestSchema, claimHeartbeatRequestSchema, listQuerySchema, claimListQuerySchema, claimStateSchema, claimAcquiredResponseSchema, claimQueuedResponseSchema, claimAcquireResponseSchema, claimHeartbeatReplySchema, claimHeartbeatBatchReplySchema, claimListResponseSchema, claimReorderRequestSchema, claimReorderReplySchema, claimReleaseReplySchema, } from './claims.js';
+// The model read routes' responses — the envelope around a row, which is
+// protocol, around `data`, which is the caller's schema.
+export { modelReadResponseSchema, modelListResponseSchema, } from './modelResponses.js';
+// What a model is made of — the artifact's own field and relation shapes, which
+// the schema read reports and every other layer derives its types from.
+export { fieldTypeSchema, fieldMetaSchema, relationTypeSchema, relationMetaSchema, } from './modelShape.js';
+// The model write routes' body — the record in `data`, the guards beside it.
+export { modelMutationRequestSchema } from './modelMutations.js';
+// The account routes' responses — projects, the deployed schema, the commit
+// log, usage. What the server, the CLI, and the MCP server agree on.
+export { projectResponseSchema, projectListResponseSchema, provisionedKeySchema, provisionKeyResponseSchema, conflictAxisWireSchema, schemaModelResponseSchema, schemaReadResponseSchema, logOpSchema, LOG_OP_BY_ACTION, logEventSchema, usageBucketSchema, usageReportResponseSchema, controlKeySchema, controlKeyListResponseSchema, keyMintedResponseSchema, keyRevokedResponseSchema, } from './accountResponses.js';
+// The inbound socket surface: every frame the server can send, and how each
+// one's payload is validated.
+export { WS_INBOUND_FRAMES, wsInboundEnvelopeSchema, isKnownInboundFrame, isSchemaValidatedFrame, } from './inboundFrames.js';
+// Credential minting — the first call any caller makes, so the contract cannot
+// omit it. Response side lives in `auth/schemas.ts`.
+export { ephemeralKeyUserSchema, ephemeralKeyRequestSchema, capabilityRequestSchema, capabilityMintResponseSchema, } from './auth.js';

package/dist/{wire → transaction/wire}/listEnvelope.d.ts

@@ -8,20 +8,19 @@
  * produces it, so every list across the API reads from one definition. The
  * generic type parameter carries the row type of `data`.
  */
-export interface ListEnvelope<T> {
-    /** Always the literal `'list'`. Lets a generic client recognize a collection
-     *  response without special-casing each endpoint. */
-    readonly object: 'list';
-    /** The page of results. Always present (an empty array when there are none),
-     *  never omitted, so `body.data` is a stable access path. */
-    readonly data: readonly T[];
-    /** Whether more results exist past this page. Drive "load more" off this,
-     *  not off `data.length === limit` (ambiguous on an exact-multiple page). */
-    readonly has_more: boolean;
-    /** Opaque cursor to pass back as `?starting_after=` for the next page, or
-     *  `null` when {@link has_more} is `false`. */
-    readonly next_cursor: string | null;
-}
+import { z } from 'zod';
+/**
+ * Builds the authoritative list-envelope schema for a row schema. Keeping the
+ * item validator generic lets every endpoint share the same envelope contract
+ * without weakening `data` to `unknown[]`.
+ */
+export declare function listEnvelopeSchema<T>(itemSchema: z.ZodType<T>): z.ZodObject<{
+    object: z.ZodLiteral<"list">;
+    data: z.ZodReadonly<z.ZodArray<z.ZodType<T, unknown, z.core.$ZodTypeInternals<T, unknown>>>>;
+    has_more: z.ZodBoolean;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ListEnvelope<T> = Readonly<z.infer<ReturnType<typeof listEnvelopeSchema<T>>>>;
 /**
  * Wraps an already-fetched page of rows in the uniform {@link ListEnvelope}.
  *

package/dist/transaction/wire/listEnvelope.js

@@ -0,0 +1,42 @@
+/**
+ * The envelope every endpoint that returns a collection wraps its results in.
+ * Because the shape is always the same — `{ object: 'list', data, has_more,
+ * next_cursor }` — a consumer can detect and paginate any list the same way,
+ * instead of learning a different payload key for each endpoint.
+ *
+ * The list endpoints emit this shape and the {@link listEnvelope} helper
+ * produces it, so every list across the API reads from one definition. The
+ * generic type parameter carries the row type of `data`.
+ */
+import { z } from 'zod';
+/**
+ * Builds the authoritative list-envelope schema for a row schema. Keeping the
+ * item validator generic lets every endpoint share the same envelope contract
+ * without weakening `data` to `unknown[]`.
+ */
+export function listEnvelopeSchema(itemSchema) {
+    return z.object({
+        object: z.literal('list'),
+        data: z.array(itemSchema).readonly(),
+        has_more: z.boolean(),
+        next_cursor: z.string().nullable(),
+    });
+}
+/**
+ * Wraps an already-fetched page of rows in the uniform {@link ListEnvelope}.
+ *
+ * Pagination stays the caller's job — fetch one more row than the limit to
+ * decide `hasMore`, and derive the cursor from the last row's sort key. This
+ * helper only applies the envelope so no endpoint has to build the shape by
+ * hand. The defaults describe a small, unpaginated collection
+ * (`has_more: false`, `next_cursor: null`); a paginated endpoint passes both
+ * explicitly.
+ */
+export function listEnvelope(data, opts = {}) {
+    return {
+        object: 'list',
+        data,
+        has_more: opts.hasMore ?? false,
+        next_cursor: opts.nextCursor ?? null,
+    };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * The body of a model-scoped write — `POST /v1/models/{model}`,
+ * `PATCH /v1/models/{model}/{id}`, `DELETE /v1/models/{model}/{id}`.
+ *
+ * The record travels in `data`, and everything else is a control field beside
+ * it rather than inside it. That separation is the point: a row with a column
+ * called `claim` or `readAt` is not a reason for a write to stop being guarded,
+ * and a flat body would make the two indistinguishable.
+ *
+ * This lived in `routes/commit.ts` and the published reference described these
+ * routes as taking a bare row — so a client built from the document sent the
+ * record flat, and every field of it went missing at once. The failure surfaced
+ * as `not_null_violation` from the column, which reads as a schema problem
+ * rather than an envelope one. One definition, derived, is what stops that:
+ * the server validates against this and the reference is generated from it.
+ */
+import { z } from 'zod';
+export declare const modelMutationRequestSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    claim: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ModelMutationRequest = z.infer<typeof modelMutationRequestSchema>;

package/dist/transaction/wire/modelMutations.js

@@ -0,0 +1,52 @@
+/**
+ * The body of a model-scoped write — `POST /v1/models/{model}`,
+ * `PATCH /v1/models/{model}/{id}`, `DELETE /v1/models/{model}/{id}`.
+ *
+ * The record travels in `data`, and everything else is a control field beside
+ * it rather than inside it. That separation is the point: a row with a column
+ * called `claim` or `readAt` is not a reason for a write to stop being guarded,
+ * and a flat body would make the two indistinguishable.
+ *
+ * This lived in `routes/commit.ts` and the published reference described these
+ * routes as taking a bare row — so a client built from the document sent the
+ * record flat, and every field of it went missing at once. The failure surfaced
+ * as `not_null_violation` from the column, which reads as a schema problem
+ * rather than an envelope one. One definition, derived, is what stops that:
+ * the server validates against this and the reference is generated from it.
+ */
+import { z } from 'zod';
+import { onStaleModeSchema } from '../coordination/schema.js';
+export const modelMutationRequestSchema = z.object({
+    /** The record. Its shape is your schema's; everything around it is protocol. */
+    data: z.record(z.string(), z.unknown()).nullish(),
+    /**
+     * The row id.
+     *
+     * On `POST` this is where it comes from, and it is **yours to choose** —
+     * Ablo mints none. Derive it as UUID v5 of `"<model>:<Idempotency-Key>"` in
+     * namespace `aa4ba6d4-bf0b-5b38-9c45-116f79a6e548` and a retry after a lost
+     * response inserts the same id, colliding with the original rather than
+     * writing a second row — with no server state to consult, so it holds across
+     * instances and outlives any idempotency record.
+     *
+     * On `PATCH` and `DELETE` the path names the row and this is redundant.
+     */
+    id: z.string().nullish(),
+    /** The claim this write is made under — a claim id you hold. */
+    claim: z.string().nullish(),
+    /** What to do when the row moved since `readAt`. Defaults to rejecting. */
+    onStale: onStaleModeSchema.nullish(),
+    /**
+     * The watermark this write's decision was made against — the `stamp` from
+     * the read. Ablo rejects the write if the row moved in between, which is
+     * what makes read → decide → write safe without a lock across the deciding.
+     */
+    readAt: z.number().nullish(),
+    /**
+     * The fencing token from the claim's grant. Closes the window `readAt` alone
+     * cannot: a lease that lapsed and whose successor came and went.
+     */
+    fenceToken: z.number().nullish(),
+    /** @compat HTTP idempotency belongs in the `Idempotency-Key` header. */
+    idempotencyKey: z.string().optional(),
+});

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

@@ -0,0 +1,85 @@
+/**
+ * What the model read routes answer with — `GET /v1/models/{model}/{id}` and
+ * `GET /v1/models/{model}`.
+ *
+ * `data` is `unknown` here on purpose. The transport that reads these responses
+ * is schema-agnostic: it moves rows for whatever schema the caller declared, so
+ * it validates the envelope around a row and leaves the row itself to the typed
+ * surface above it. Everything outside `data` — the watermark, the claims, the
+ * pagination — is protocol, and protocol is validated here.
+ */
+import { z } from 'zod';
+/**
+ * `GET /v1/models/{model}/{id}`.
+ *
+ * `stamp` is the row's watermark: the log position the read reflects. A write
+ * that guards on this premise (`readAt`) is rejected if the row moved on in
+ * between, which is what makes a read→decide→write sequence safe without a
+ * lock. A missing row answers 404, so `data` is always present here.
+ */
+export declare const modelReadResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"model">;
+    model: z.ZodString;
+    id: z.ZodString;
+    data: z.ZodUnknown;
+    stamp: z.ZodNumber;
+    claims: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        id: z.ZodString;
+        actor: z.ZodString;
+        participantKind: z.ZodPreprocess<z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>>;
+        onBehalfOfId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        onBehalfOfKind: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>>>>;
+        capabilityId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        description: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            queued: "queued";
+        }>>;
+        position: z.ZodOptional<z.ZodNumber>;
+        expiresAt: z.ZodNumber;
+        fenceToken: z.ZodOptional<z.ZodNumber>;
+        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>>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        field: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type ModelReadResponse = z.infer<typeof modelReadResponseSchema>;
+/**
+ * `GET /v1/models/{model}` — the list envelope, with the two fields the model
+ * routes add to it: the model's name and the org-wide watermark the page was
+ * read at.
+ *
+ * The envelope is derived, not restated. A schema-agnostic row is `z.unknown()`,
+ * which the generic helper accepts like any other item schema, so there is no
+ * layer at which the shared fields have to be spelled a second time.
+ */
+export declare const modelListResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"list">;
+    data: z.ZodReadonly<z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    has_more: z.ZodBoolean;
+    next_cursor: z.ZodNullable<z.ZodString>;
+    model: z.ZodString;
+    stamp: z.ZodNumber;
+}, z.core.$strip>;
+export type ModelListResponse = z.infer<typeof modelListResponseSchema>;

package/dist/transaction/wire/modelResponses.js

@@ -0,0 +1,43 @@
+/**
+ * What the model read routes answer with — `GET /v1/models/{model}/{id}` and
+ * `GET /v1/models/{model}`.
+ *
+ * `data` is `unknown` here on purpose. The transport that reads these responses
+ * is schema-agnostic: it moves rows for whatever schema the caller declared, so
+ * it validates the envelope around a row and leaves the row itself to the typed
+ * surface above it. Everything outside `data` — the watermark, the claims, the
+ * pagination — is protocol, and protocol is validated here.
+ */
+import { z } from 'zod';
+import { modelClaimSchema } from '../coordination/schema.js';
+import { listEnvelopeSchema } from './listEnvelope.js';
+/**
+ * `GET /v1/models/{model}/{id}`.
+ *
+ * `stamp` is the row's watermark: the log position the read reflects. A write
+ * that guards on this premise (`readAt`) is rejected if the row moved on in
+ * between, which is what makes a read→decide→write sequence safe without a
+ * lock. A missing row answers 404, so `data` is always present here.
+ */
+export const modelReadResponseSchema = z.object({
+    object: z.literal('model'),
+    model: z.string(),
+    id: z.string(),
+    data: z.unknown(),
+    stamp: z.number(),
+    /** Who holds this row right now — empty when no claim store is configured. */
+    claims: z.array(modelClaimSchema).readonly(),
+});
+/**
+ * `GET /v1/models/{model}` — the list envelope, with the two fields the model
+ * routes add to it: the model's name and the org-wide watermark the page was
+ * read at.
+ *
+ * The envelope is derived, not restated. A schema-agnostic row is `z.unknown()`,
+ * which the generic helper accepts like any other item schema, so there is no
+ * layer at which the shared fields have to be spelled a second time.
+ */
+export const modelListResponseSchema = listEnvelopeSchema(z.unknown()).extend({
+    model: z.string(),
+    stamp: z.number(),
+});

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

@@ -0,0 +1,78 @@
+/**
+ * What a model is made of — its fields and its edges.
+ *
+ * These shapes travel twice: they are what `ablo push` serializes into the
+ * schema artifact, and what `GET /api/schema` reports back about the artifact
+ * that is deployed. Two crossings, one definition, and the definition lives
+ * here because `wire/` is the leaf every other layer may depend on.
+ *
+ * They were TypeScript interfaces, so the schema-read route could not send them
+ * without hand-writing a second copy of the record it was refusing to send — the
+ * shadow type wearing the fix's clothes. Declared as Zod and derived back into
+ * TypeScript, there is nowhere for a second copy to live.
+ *
+ * **Vocabulary ownership.** `type` is a CLOSED enum: the engine owns the set of
+ * types it can store and serialize, so a value outside it is a bug, not an
+ * extension. `enumValues` is an OPEN list: the values belong to the application
+ * that declared them, and the protocol never interprets one.
+ */
+import { z } from 'zod';
+/**
+ * The engine's type vocabulary — closed, and owned by the engine.
+ *
+ * Each member maps to storage and serialization behaviour, so this is the whole
+ * set by construction. A schema's own richer types (a `z.email()`, a branded id)
+ * narrow one of these; they do not add a member.
+ */
+export declare const fieldTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    date: "date";
+    enum: "enum";
+    json: "json";
+}>;
+export type FieldType = z.infer<typeof fieldTypeSchema>;
+/** One field of a model, as the schema artifact records it. */
+export declare const fieldMetaSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+        enum: "enum";
+        json: "json";
+    }>;
+    isOptional: z.ZodBoolean;
+    isIndexed: z.ZodBoolean;
+    column: z.ZodOptional<z.ZodString>;
+    enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type FieldMeta = z.infer<typeof fieldMetaSchema>;
+/**
+ * How one model points at another. Closed, like {@link fieldTypeSchema}: the
+ * engine resolves exactly these three when it plans a read.
+ */
+export declare const relationTypeSchema: z.ZodEnum<{
+    belongsTo: "belongsTo";
+    hasMany: "hasMany";
+    hasOne: "hasOne";
+}>;
+export type RelationType = z.infer<typeof relationTypeSchema>;
+/**
+ * One edge of a model — what a caller may expand, and what it expands into.
+ *
+ * Reported alongside the fields because half the answer is not an answer: an
+ * agent asking what a model looks like wants its shape AND its edges, and
+ * shipping only the scalars invites the second question immediately.
+ */
+export declare const relationMetaSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        belongsTo: "belongsTo";
+        hasMany: "hasMany";
+        hasOne: "hasOne";
+    }>;
+    target: z.ZodString;
+    foreignKey: z.ZodString;
+}, z.core.$strip>;
+export type RelationMeta = z.infer<typeof relationMetaSchema>;

package/dist/transaction/wire/modelShape.js

@@ -0,0 +1,74 @@
+/**
+ * What a model is made of — its fields and its edges.
+ *
+ * These shapes travel twice: they are what `ablo push` serializes into the
+ * schema artifact, and what `GET /api/schema` reports back about the artifact
+ * that is deployed. Two crossings, one definition, and the definition lives
+ * here because `wire/` is the leaf every other layer may depend on.
+ *
+ * They were TypeScript interfaces, so the schema-read route could not send them
+ * without hand-writing a second copy of the record it was refusing to send — the
+ * shadow type wearing the fix's clothes. Declared as Zod and derived back into
+ * TypeScript, there is nowhere for a second copy to live.
+ *
+ * **Vocabulary ownership.** `type` is a CLOSED enum: the engine owns the set of
+ * types it can store and serialize, so a value outside it is a bug, not an
+ * extension. `enumValues` is an OPEN list: the values belong to the application
+ * that declared them, and the protocol never interprets one.
+ */
+import { z } from 'zod';
+/**
+ * The engine's type vocabulary — closed, and owned by the engine.
+ *
+ * Each member maps to storage and serialization behaviour, so this is the whole
+ * set by construction. A schema's own richer types (a `z.email()`, a branded id)
+ * narrow one of these; they do not add a member.
+ */
+export const fieldTypeSchema = z.enum([
+    'string',
+    'number',
+    'boolean',
+    'date',
+    'enum',
+    'json',
+]);
+/** One field of a model, as the schema artifact records it. */
+export const fieldMetaSchema = z.object({
+    /** Sync-engine type tag, which maps to storage and serialization hints. */
+    type: fieldTypeSchema,
+    /** Whether the field was marked optional via `.optional()` or `.nullable()`. */
+    isOptional: z.boolean(),
+    /** Whether the field was marked indexed via `.indexed()`. */
+    isIndexed: z.boolean(),
+    /**
+     * Physical database column name override. When absent, SQL layers derive the
+     * column from the field name using the active casing convention.
+     */
+    column: z.string().optional(),
+    /**
+     * For enums: the allowed values.
+     *
+     * The application's vocabulary, carried verbatim — an open list, because the
+     * protocol has no opinion about what a caller's statuses are called.
+     */
+    enumValues: z.array(z.string()).readonly().optional(),
+});
+/**
+ * How one model points at another. Closed, like {@link fieldTypeSchema}: the
+ * engine resolves exactly these three when it plans a read.
+ */
+export const relationTypeSchema = z.enum(['belongsTo', 'hasMany', 'hasOne']);
+/**
+ * One edge of a model — what a caller may expand, and what it expands into.
+ *
+ * Reported alongside the fields because half the answer is not an answer: an
+ * agent asking what a model looks like wants its shape AND its edges, and
+ * shipping only the scalars invites the second question immediately.
+ */
+export const relationMetaSchema = z.object({
+    type: relationTypeSchema,
+    /** The schema key of the model on the other end. */
+    target: z.string(),
+    /** The field on the owning side that carries the link. */
+    foreignKey: z.string(),
+});