@abloatai/ablo 0.34.1 → 0.36.0

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

@@ -0,0 +1,562 @@
+/**
+ * Every frame the server can send, in one list.
+ *
+ * Before this existed, "what frames are there" was answerable only by reading
+ * the dispatch table, the transport's event map, and each handler's defensive
+ * narrowing together — three places that agreed by convention. This registry is
+ * the single answer, and it carries how each frame's payload is validated.
+ *
+ * A frame is validated one of two ways. Most carry a `payload` schema and are
+ * parsed here, before the handler runs, so a handler receives a value whose
+ * shape is already proven. The rest are marked `handler` because their
+ * validation is genuinely load-bearing elsewhere — a delta is checked once
+ * downstream against the schema the materialiser holds, and a commit receipt
+ * has to tolerate an older server's spelling before it can be parsed. Each of
+ * those says where its check lives, so `handler` is a citation and never an
+ * excuse.
+ *
+ * A frame type absent from this registry is rejected. That is deliberate: the
+ * server and this package ship from one repository, so an unrecognised frame
+ * means the two have drifted, and failing loudly beats materialising a change
+ * nobody validated. Application-level collaboration events are the exception —
+ * they are registered by the consumer at construction time, not by the
+ * protocol, and are dispatched separately.
+ */
+import { z } from 'zod';
+/**
+ * The envelope itself: a type and a payload. `catchall` keeps the extra keys,
+ * because the oldest delta form puts a delta's own fields at the top level
+ * instead of under `payload`, and the dispatcher still has to recognise it.
+ */
+export declare const wsInboundEnvelopeSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$catchall<z.ZodUnknown>>;
+export type WsInboundEnvelope = z.infer<typeof wsInboundEnvelopeSchema>;
+/** How one frame's payload is checked. */
+export type InboundFrameContract = 
+/** Parsed against `payload` before the handler runs. */
+{
+    readonly validation: 'schema';
+    readonly payload: z.ZodType;
+}
+/**
+ * Checked inside the handler. `where` says which handler, and `checkedBy`
+ * names the schema it parses with — as the schema itself, not its name in
+ * prose, so renaming or deleting it fails the build here instead of leaving
+ * a citation pointing at nothing. Frames whose check is a hand-narrowing or
+ * lives in another package have no symbol to point at and carry only `where`.
+ */
+ | {
+    readonly validation: 'handler';
+    readonly where: string;
+    readonly checkedBy?: z.ZodType;
+};
+/**
+ * The protocol's inbound surface. Adding a frame to the server means adding it
+ * here, which is the point — the compiler cannot enforce that, but the throw on
+ * an unrecognised type does.
+ */
+export declare const WS_INBOUND_FRAMES: {
+    readonly ping: {
+        readonly validation: "handler";
+        readonly where: "dispatchWsFrame — ignored, no payload";
+    };
+    readonly pong: {
+        readonly validation: "handler";
+        readonly where: "dispatchWsFrame — ignored, no payload";
+    };
+    readonly delta: {
+        readonly validation: "handler";
+        readonly where: "the materialiser parses each delta as it applies it";
+        readonly checkedBy: z.ZodObject<{
+            id: z.ZodNumber;
+            actionType: z.ZodEnum<{
+                I: "I";
+                U: "U";
+                D: "D";
+                A: "A";
+                V: "V";
+                C: "C";
+                G: "G";
+                S: "S";
+            }>;
+            modelName: z.ZodString;
+            modelId: z.ZodString;
+            data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+            previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+            syncGroups: z.ZodArray<z.ZodString>;
+            transactionId: z.ZodOptional<z.ZodString>;
+            correlationId: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodString;
+            createdBy: z.ZodOptional<z.ZodString>;
+            metadata: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+            clientMutationId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    readonly sync_response: {
+        readonly validation: "handler";
+        readonly where: "the reactive engine validates it while advancing its resume cursor";
+    };
+    readonly bootstrap_response: {
+        readonly validation: "handler";
+        readonly where: "the reactive engine validates the bootstrap payload as it applies it";
+    };
+    readonly mutation_result: {
+        readonly validation: "handler";
+        readonly where: "handleMutationResult — it lifts the frame's notifications and missingIds alongside the payload before this can parse";
+        readonly checkedBy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"queued">;
+            correlationId: z.ZodString;
+            object: z.ZodLiteral<"commit_receipt">;
+            id: z.ZodOptional<z.ZodString>;
+            clientTxId: z.ZodString;
+            serverTxId: z.ZodString;
+            success: z.ZodLiteral<true>;
+            lastSyncId: z.ZodNumber;
+            ops: z.ZodNumber;
+            notifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
+                model: z.ZodString;
+                id: z.ZodString;
+                readAt: z.ZodNumber;
+                observedSyncId: z.ZodNumber;
+                conflictingFields: z.ZodArray<z.ZodString>;
+                currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                writtenBy: z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        user: "user";
+                        agent: "agent";
+                        system: "system";
+                    }>;
+                    id: z.ZodString;
+                }, z.core.$strip>;
+                group: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            status: z.ZodLiteral<"confirmed">;
+            correlationId: z.ZodOptional<z.ZodString>;
+            object: z.ZodLiteral<"commit_receipt">;
+            id: z.ZodOptional<z.ZodString>;
+            clientTxId: z.ZodString;
+            serverTxId: z.ZodString;
+            success: z.ZodLiteral<true>;
+            lastSyncId: z.ZodNumber;
+            ops: z.ZodNumber;
+            notifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
+                model: z.ZodString;
+                id: z.ZodString;
+                readAt: z.ZodNumber;
+                observedSyncId: z.ZodNumber;
+                conflictingFields: z.ZodArray<z.ZodString>;
+                currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                writtenBy: z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        user: "user";
+                        agent: "agent";
+                        system: "system";
+                    }>;
+                    id: z.ZodString;
+                }, z.core.$strip>;
+                group: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            missingIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>], "status">;
+    };
+    readonly claim_ack: {
+        readonly validation: "handler";
+        readonly where: "handleClaimAck narrows field by field, because a rejection carries a typed capability error it has to re-raise as CapabilityError";
+    };
+    readonly subscription_ack: {
+        readonly validation: "handler";
+        readonly where: "handleSubscriptionAck";
+        readonly checkedBy: z.ZodObject<{
+            success: z.ZodBoolean;
+            syncGroups: z.ZodArray<z.ZodString>;
+            error: z.ZodOptional<z.ZodObject<{
+                code: z.ZodString;
+                message: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly presence_update: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            kind: z.ZodEnum<{
+                enter: "enter";
+                update: "update";
+                leave: "leave";
+            }>;
+            userId: z.ZodString;
+            syncGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            timestamp: z.ZodOptional<z.ZodNumber>;
+            status: z.ZodString;
+            timezone: z.ZodOptional<z.ZodString>;
+            customStatus: z.ZodOptional<z.ZodString>;
+            activity: z.ZodOptional<z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>>;
+                action: z.ZodString;
+                detail: z.ZodOptional<z.ZodString>;
+                loadFactor: z.ZodOptional<z.ZodNumber>;
+                acceptingNewWork: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            isAgent: z.ZodOptional<z.ZodBoolean>;
+            participantKind: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
+                user: "user";
+                agent: "agent";
+                system: "system";
+            }>>>;
+            activeClaims: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>>;
+                claimId: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                declaredAt: z.ZodNumber;
+                expiresAt: z.ZodNumber;
+                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>>;
+                fenceToken: z.ZodOptional<z.ZodNumber>;
+                acquiredAt: z.ZodOptional<z.ZodNumber>;
+                status: z.ZodOptional<z.ZodEnum<{
+                    active: "active";
+                    committed: "committed";
+                    expired: "expired";
+                    canceled: "canceled";
+                }>>;
+                error: z.ZodOptional<z.ZodObject<{
+                    code: z.ZodString;
+                    message: z.ZodOptional<z.ZodString>;
+                    heldBy: z.ZodOptional<z.ZodString>;
+                    heldByClaimId: z.ZodOptional<z.ZodString>;
+                    heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+                    heldByClaim: z.ZodOptional<z.ZodObject<{
+                        entityType: z.ZodString;
+                        entityId: 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>>;
+                        claimId: z.ZodString;
+                        description: z.ZodOptional<z.ZodString>;
+                        declaredAt: z.ZodNumber;
+                        expiresAt: z.ZodNumber;
+                        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>>;
+                    }, z.core.$strip>>;
+                    policyReason: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+            delegatedFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$catchall<z.ZodUnknown>>;
+    };
+    readonly claim_expired: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly claim_rejected: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: 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;
+                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>>;
+            heldBy: z.ZodOptional<z.ZodString>;
+            heldByKind: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
+                user: "user";
+                agent: "agent";
+                system: "system";
+            }>>>;
+            heldByClaimId: z.ZodOptional<z.ZodString>;
+            heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+            heldByClaim: z.ZodOptional<z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>>;
+                claimId: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                declaredAt: z.ZodNumber;
+                expiresAt: z.ZodNumber;
+                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>>;
+            }, z.core.$strip>>;
+            policyReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    readonly claim_acquired: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: z.ZodString;
+            fenceToken: z.ZodOptional<z.ZodNumber>;
+            target: z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>;
+        }, z.core.$strip>;
+    };
+    readonly claim_queued: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: z.ZodString;
+            target: z.ZodOptional<z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>>;
+            heldBy: z.ZodOptional<z.ZodString>;
+            heldByKind: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
+                user: "user";
+                agent: "agent";
+                system: "system";
+            }>>>;
+            heldByClaimId: z.ZodOptional<z.ZodString>;
+            heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+            heldByClaim: z.ZodOptional<z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>>;
+                claimId: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                declaredAt: z.ZodNumber;
+                expiresAt: z.ZodNumber;
+                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>>;
+            }, z.core.$strip>>;
+            policyReason: z.ZodOptional<z.ZodString>;
+            position: z.ZodNumber;
+            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: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: z.ZodString;
+            fenceToken: z.ZodOptional<z.ZodNumber>;
+            target: z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>;
+        }, z.core.$strip>;
+    };
+    readonly claim_lost: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: z.ZodString;
+            reason: z.ZodEnum<{
+                expired: "expired";
+                preempted: "preempted";
+            }>;
+            target: z.ZodObject<{
+                entityType: z.ZodString;
+                entityId: 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>;
+        }, z.core.$strip>;
+    };
+    readonly claim_queue: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            target: z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, z.core.$strip>;
+            queue: z.ZodArray<z.ZodObject<{
+                object: z.ZodLiteral<"claim">;
+                id: z.ZodString;
+                status: z.ZodLiteral<"queued">;
+                target: z.ZodObject<{
+                    field: z.ZodOptional<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>>;
+                    fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    type: z.ZodString;
+                    id: z.ZodString;
+                }, z.core.$strip>;
+                description: z.ZodDefault<z.ZodString>;
+                heldBy: z.ZodOptional<z.ZodString>;
+                participantKind: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
+                    user: "user";
+                    agent: "agent";
+                    system: "system";
+                }>>>;
+                position: z.ZodNumber;
+                expiresAt: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly claim_heartbeat_ack: {
+        readonly validation: "schema";
+        readonly payload: z.ZodObject<{
+            claimId: z.ZodString;
+            status: z.ZodEnum<{
+                queued: "queued";
+                held: "held";
+                lost: "lost";
+            }>;
+            expiresAt: z.ZodOptional<z.ZodNumber>;
+            position: z.ZodOptional<z.ZodNumber>;
+            queueDepth: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    };
+};
+/** Every frame type the protocol declares. */
+export type InboundFrameType = keyof typeof WS_INBOUND_FRAMES;
+/**
+ * The validated payload type of each schema-checked frame, read straight off
+ * the registry. A handler that takes one of these gets the shape the
+ * dispatcher proved, with no second declaration to keep in step and no cast at
+ * the point of use.
+ */
+export type InboundFramePayload = {
+    [K in InboundFrameType]: (typeof WS_INBOUND_FRAMES)[K] extends {
+        readonly payload: infer P extends z.ZodType;
+    } ? z.infer<P> : never;
+};
+/** The frame types the dispatcher parses before calling a handler. */
+export type SchemaValidatedFrameType = {
+    [K in InboundFrameType]: (typeof WS_INBOUND_FRAMES)[K] extends {
+        readonly validation: 'schema';
+    } ? K : never;
+}[InboundFrameType];
+/** Whether the protocol declares this frame type at all. */
+export declare function isKnownInboundFrame(type: string): type is InboundFrameType;
+/**
+ * Whether this frame's payload is parsed before dispatch. Declared as a
+ * predicate, and declared here, because the fact it asserts is a fact about the
+ * registry directly above it: the two cannot be edited apart.
+ */
+export declare function isSchemaValidatedFrame(type: InboundFrameType): type is SchemaValidatedFrameType;

package/dist/transaction/wire/inboundFrames.js

@@ -0,0 +1,116 @@
+/**
+ * Every frame the server can send, in one list.
+ *
+ * Before this existed, "what frames are there" was answerable only by reading
+ * the dispatch table, the transport's event map, and each handler's defensive
+ * narrowing together — three places that agreed by convention. This registry is
+ * the single answer, and it carries how each frame's payload is validated.
+ *
+ * A frame is validated one of two ways. Most carry a `payload` schema and are
+ * parsed here, before the handler runs, so a handler receives a value whose
+ * shape is already proven. The rest are marked `handler` because their
+ * validation is genuinely load-bearing elsewhere — a delta is checked once
+ * downstream against the schema the materialiser holds, and a commit receipt
+ * has to tolerate an older server's spelling before it can be parsed. Each of
+ * those says where its check lives, so `handler` is a citation and never an
+ * excuse.
+ *
+ * A frame type absent from this registry is rejected. That is deliberate: the
+ * server and this package ship from one repository, so an unrecognised frame
+ * means the two have drifted, and failing loudly beats materialising a change
+ * nobody validated. Application-level collaboration events are the exception —
+ * they are registered by the consumer at construction time, not by the
+ * protocol, and are dispatched separately.
+ */
+import { z } from 'zod';
+import { commitReceiptSchema } from './commit.js';
+import { clientSyncDeltaSchema } from './delta.js';
+import { claimAcquiredSchema, claimExpiredSchema, claimGrantedSchema, claimHeartbeatAckPayloadSchema, claimLostSchema, claimQueuedSchema, claimQueueSchema, claimRejectionSchema, presenceUpdateSchema, subscriptionAckPayloadSchema, } from '../coordination/schema.js';
+/**
+ * The envelope itself: a type and a payload. `catchall` keeps the extra keys,
+ * because the oldest delta form puts a delta's own fields at the top level
+ * instead of under `payload`, and the dispatcher still has to recognise it.
+ */
+export const wsInboundEnvelopeSchema = z
+    .object({
+    type: z.string().optional(),
+    payload: z.unknown().optional(),
+})
+    .catchall(z.unknown());
+/**
+ * The protocol's inbound surface. Adding a frame to the server means adding it
+ * here, which is the point — the compiler cannot enforce that, but the throw on
+ * an unrecognised type does.
+ */
+export const WS_INBOUND_FRAMES = {
+    // ── Keepalive ──────────────────────────────────────────────────────────
+    ping: { validation: 'handler', where: 'dispatchWsFrame — ignored, no payload' },
+    pong: { validation: 'handler', where: 'dispatchWsFrame — ignored, no payload' },
+    // ── Materialisation ────────────────────────────────────────────────────
+    delta: {
+        validation: 'handler',
+        // Not parsed at dispatch because a delta frame carries a batch: each entry
+        // is validated on its own so one malformed delta is dropped rather than
+        // sinking the batch around it.
+        where: 'the materialiser parses each delta as it applies it',
+        checkedBy: clientSyncDeltaSchema,
+    },
+    sync_response: {
+        validation: 'handler',
+        // No `checkedBy`: the schema lives in the reactive engine
+        // (`sync/schemas.ts`), which consumes this package. The core cannot name a
+        // symbol from its own consumer, and inverting the dependency to make this
+        // citation checkable would put materialisation vocabulary in the core —
+        // the exact thing the seam exists to keep out.
+        where: 'the reactive engine validates it while advancing its resume cursor',
+    },
+    bootstrap_response: {
+        validation: 'handler',
+        // No `checkedBy`, for the same reason as `sync_response` above.
+        where: 'the reactive engine validates the bootstrap payload as it applies it',
+    },
+    // ── Commit ─────────────────────────────────────────────────────────────
+    mutation_result: {
+        validation: 'handler',
+        where: 'handleMutationResult — it lifts the frame\'s notifications and missingIds alongside the payload before this can parse',
+        checkedBy: commitReceiptSchema,
+    },
+    // ── Requests we made ───────────────────────────────────────────────────
+    claim_ack: {
+        validation: 'handler',
+        where: 'handleClaimAck narrows field by field, because a rejection carries a typed capability error it has to re-raise as CapabilityError',
+    },
+    subscription_ack: {
+        validation: 'handler',
+        // Not parsed at dispatch because the handler must first claim the oldest
+        // pending request: a payload that failed here would otherwise leave that
+        // request hanging until its timeout instead of being rejected with a cause.
+        where: 'handleSubscriptionAck',
+        checkedBy: subscriptionAckPayloadSchema,
+    },
+    // ── Coordination ───────────────────────────────────────────────────────
+    presence_update: { validation: 'schema', payload: presenceUpdateSchema },
+    claim_expired: { validation: 'schema', payload: claimExpiredSchema },
+    claim_rejected: { validation: 'schema', payload: claimRejectionSchema },
+    claim_acquired: { validation: 'schema', payload: claimAcquiredSchema },
+    claim_queued: { validation: 'schema', payload: claimQueuedSchema },
+    claim_granted: { validation: 'schema', payload: claimGrantedSchema },
+    claim_lost: { validation: 'schema', payload: claimLostSchema },
+    claim_queue: { validation: 'schema', payload: claimQueueSchema },
+    claim_heartbeat_ack: {
+        validation: 'schema',
+        payload: claimHeartbeatAckPayloadSchema,
+    },
+};
+/** Whether the protocol declares this frame type at all. */
+export function isKnownInboundFrame(type) {
+    return Object.prototype.hasOwnProperty.call(WS_INBOUND_FRAMES, type);
+}
+/**
+ * Whether this frame's payload is parsed before dispatch. Declared as a
+ * predicate, and declared here, because the fact it asserts is a fact about the
+ * registry directly above it: the two cannot be edited apart.
+ */
+export function isSchemaValidatedFrame(type) {
+    return WS_INBOUND_FRAMES[type].validation === 'schema';
+}