@abloatai/ablo 0.35.0 → 0.36.0

package/dist/transaction/wire/feedEvent.js

@@ -13,7 +13,7 @@
  * sequence; {@link FeedCursor} is what carries both positions.
  */
 import { z } from 'zod';
-import { logEventSchema } from './accountResponses.js';
+import { logEventSchema, logOpSchema } from './accountResponses.js';
 import { claimEventSchema } from './claimEvent.js';
 import { listEnvelopeSchema } from './listEnvelope.js';
 /**
@@ -27,6 +27,32 @@ export const feedEventSchema = z.discriminatedUnion('object', [
 ]);
 /** `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

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

@@ -122,8 +122,8 @@ export declare const commitPayloadSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>]>>>>;
     track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        model: z.ZodString;
         id: z.ZodString;
+        model: z.ZodString;
         readAt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
         group: z.ZodString;
@@ -176,8 +176,8 @@ export declare const commitMessageSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>]>>>>;
         track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-            model: z.ZodString;
             id: z.ZodString;
+            model: z.ZodString;
             readAt: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             group: z.ZodString;

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

@@ -298,7 +298,12 @@ export declare const WS_INBOUND_FRAMES: {
         readonly validation: "schema";
         readonly payload: z.ZodObject<{
             claimId: z.ZodString;
-            reason: z.ZodString;
+            reason: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+                conflict: "conflict";
+                expired: "expired";
+                coordination_unavailable: "coordination_unavailable";
+                preempted: "preempted";
+            }>>>;
             target: z.ZodOptional<z.ZodObject<{
                 entityType: z.ZodString;
                 entityId: z.ZodString;
@@ -423,7 +428,12 @@ export declare const WS_INBOUND_FRAMES: {
             }, z.core.$strip>>;
             policyReason: z.ZodOptional<z.ZodString>;
             position: z.ZodNumber;
-            reason: z.ZodOptional<z.ZodString>;
+            reason: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+                conflict: "conflict";
+                expired: "expired";
+                coordination_unavailable: "coordination_unavailable";
+                preempted: "preempted";
+            }>>>>;
         }, z.core.$strip>;
     };
     readonly claim_granted: {

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

@@ -21,8 +21,8 @@ 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 } from './feedEvent.js';
-export type { FeedEvent, LogListResponse } from './feedEvent.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';
@@ -38,13 +38,17 @@ export type { ParticipantKind, ConfirmationState, SyncDeltaAction, WireDeltaData
 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 { claimTargetSchema, claimRequestSchema, claimHeartbeatRequestSchema, listQuerySchema, claimListQuerySchema, claimStateSchema, claimAcquiredResponseSchema, claimQueuedResponseSchema, claimAcquireResponseSchema, claimHeartbeatReplySchema, claimHeartbeatBatchReplySchema, claimListResponseSchema, } from './claims.js';
-export type { ClaimTargetBody, ClaimRequest, ClaimHeartbeatRequest, ListQuery, ClaimListQuery, ClaimState, ClaimAcquiredResponse, ClaimQueuedResponse, ClaimAcquireResponse, ClaimHeartbeatReply, ClaimHeartbeatBatchReply, ClaimListResponse, } from './claims.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, } from './auth.js';
-export type { EphemeralKeyUser, EphemeralKeyRequest, CapabilityRequest, } from './auth.js';
+export { ephemeralKeyUserSchema, ephemeralKeyRequestSchema, capabilityRequestSchema, capabilityMintResponseSchema, } from './auth.js';
+export type { EphemeralKeyUser, EphemeralKeyRequest, CapabilityRequest, CapabilityMintResponse, } from './auth.js';

package/dist/transaction/wire/index.js

@@ -20,7 +20,7 @@ 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 } from './feedEvent.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
@@ -59,10 +59,19 @@ export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_S
 // 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 { claimTargetSchema, claimRequestSchema, claimHeartbeatRequestSchema, listQuerySchema, claimListQuerySchema, claimStateSchema, claimAcquiredResponseSchema, claimQueuedResponseSchema, claimAcquireResponseSchema, claimHeartbeatReplySchema, claimHeartbeatBatchReplySchema, claimListResponseSchema, } from './claims.js';
+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';
@@ -71,4 +80,4 @@ export { projectResponseSchema, projectListResponseSchema, provisionedKeySchema,
 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, } from './auth.js';
+export { ephemeralKeyUserSchema, ephemeralKeyRequestSchema, capabilityRequestSchema, capabilityMintResponseSchema, } from './auth.js';

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/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(),
+});

package/dist/transactions/mutations/MutationQueue.d.ts

@@ -14,6 +14,7 @@
 import { EventEmitter } from 'events';
 import type { Database } from '../../Database.js';
 import { Model } from '../../Model.js';
+import type { RuntimeContext } from '../../RuntimeContext.js';
 import { LogPosition } from '../../transaction/logPosition.js';
 import type { WriteOptions } from '../../interfaces/index.js';
 import type { OnStaleMode, StaleNotification, ReadDependency, TrackDependency } from '../../transaction/coordination/schema.js';
@@ -74,6 +75,8 @@ interface ConflictResolution {
 interface MutationQueueConfig {
     /** Shared client position (see logPosition.ts). One per client. */
     position?: LogPosition;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
     maxBatchSize: number;
     batchDelay: number;
     maxRetries: number;
@@ -124,6 +127,7 @@ export declare class MutationQueue extends EventEmitter {
     private lastPermanentErrorSig?;
     private _mutationExecutor;
     private get mutationExecutor();
+    private readonly runtime;
     private executionQueue;
     private isProcessing;
     private processTimer?;
@@ -561,6 +565,8 @@ export declare class MutationQueue extends EventEmitter {
         config: {
             /** Shared client position (see logPosition.ts). One per client. */
             position?: LogPosition;
+            /** The owning client's runtime. Defaults to the module-global bridge. */
+            runtime?: RuntimeContext;
             maxBatchSize: number;
             batchDelay: number;
             maxRetries: number;