@sudobility/screenwriter_types 0.1.1

package/dist/sync/index.d.ts

@@ -0,0 +1,382 @@
+import { z } from 'zod';
+/** Spec 03 §2. Subprotocol string is `fadewright-sync.v1`. */
+export declare const SYNC_PROTOCOL_VERSION = 1;
+export declare const SYNC_SUBPROTOCOL = "fadewright-sync.v1";
+export declare const SYNC_PATH = "/api/v1/sync";
+export declare const SYNC_HEARTBEAT_MS = 25000;
+export declare const SYNC_MAX_FRAME_BYTES = 1048576;
+export declare const SYNC_AUTH_TIMEOUT_MS = 5000;
+/** Numeric message-type codes (spec 03 §2.3). Frame = channelId, messageType, payload. */
+export declare const SYNC_MESSAGE_TYPES: {
+    readonly auth: 0;
+    readonly authOk: 1;
+    readonly authError: 2;
+    readonly reauth: 3;
+    readonly ping: 4;
+    readonly pong: 4;
+    readonly subscribe: 10;
+    readonly subscribed: 11;
+    readonly subscribeError: 12;
+    readonly unsubscribe: 13;
+    readonly syncStep1: 20;
+    readonly syncStep2: 21;
+    readonly update: 22;
+    readonly ack: 23;
+    readonly reject: 24;
+    readonly awareness: 30;
+    readonly epochChanged: 40;
+    readonly roleChanged: 41;
+    readonly documentDeleted: 42;
+    readonly normalized: 43;
+    readonly serverShutdown: 50;
+};
+export type SyncMessageName = keyof typeof SYNC_MESSAGE_TYPES;
+/** Close codes (spec 03 §2.6). */
+export declare const SYNC_CLOSE_CODES: {
+    readonly NORMAL: 1000;
+    readonly GOING_AWAY: 1001;
+    readonly MALFORMED_FRAME: 4400;
+    readonly AUTH_TIMEOUT_OR_INVALID: 4401;
+    readonly ACCOUNT_DISABLED_OR_DEVICE_REVOKED: 4403;
+    readonly PROTOCOL_UNSUPPORTED: 4406;
+    readonly HEARTBEAT_TIMEOUT: 4408;
+    /** Document epoch changed (snapshot open / version restore): resubscribe at the new epoch. */
+    readonly EPOCH_CHANGED: 4409;
+    readonly FRAME_TOO_LARGE: 4413;
+    readonly RATE_LIMITED: 4429;
+};
+export type SyncCloseCode = (typeof SYNC_CLOSE_CODES)[keyof typeof SYNC_CLOSE_CODES];
+export declare const SYNC_AUTH_SCHEMES: readonly ["firebase", "apikey", "link"];
+export declare const SYNC_AUTH_ERROR_CODES: readonly ["UNAUTHENTICATED", "ACCOUNT_DISABLED", "DEVICE_REVOKED", "LINK_EXPIRED", "CLIENT_TOO_OLD", "SERVER_TOO_OLD"];
+export declare const SYNC_SUBSCRIBE_ERROR_CODES: readonly ["NOT_FOUND", "FORBIDDEN", "DOCUMENT_DELETED", "EPOCH_MISMATCH", "DOCUMENT_LOCKED", "CLIENT_TOO_OLD"];
+export declare const SYNC_REJECT_CODES: readonly ["FORBIDDEN", "EPOCH_MISMATCH", "UPDATE_INVALID", "PAYLOAD_TOO_LARGE", "SCHEMA_VIOLATION"];
+export declare const SYNC_SUBSCRIBE_MODES: readonly ["edit", "view"];
+export declare const SYNC_EPOCH_REASONS: readonly ["snapshot-open", "import-over", "version-restore", "schema-migration"];
+export declare const authPayloadSchema: z.ZodObject<{
+    scheme: z.ZodEnum<{
+        link: "link";
+        firebase: "firebase";
+        apikey: "apikey";
+    }>;
+    token: z.ZodString;
+    deviceId: z.ZodString;
+    installId: z.ZodString;
+    clientVersion: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    unlockToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const authOkPayloadSchema: z.ZodObject<{
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    serverSchemaVersion: z.ZodNumber;
+    heartbeatMs: z.ZodNumber;
+    maxFrameBytes: z.ZodNumber;
+}, z.core.$strip>;
+export declare const authErrorPayloadSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        CLIENT_TOO_OLD: "CLIENT_TOO_OLD";
+        DEVICE_REVOKED: "DEVICE_REVOKED";
+        UNAUTHENTICATED: "UNAUTHENTICATED";
+        ACCOUNT_DISABLED: "ACCOUNT_DISABLED";
+        LINK_EXPIRED: "LINK_EXPIRED";
+        SERVER_TOO_OLD: "SERVER_TOO_OLD";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const reauthPayloadSchema: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$strip>;
+export declare const pingPayloadSchema: z.ZodObject<{
+    t: z.ZodNumber;
+}, z.core.$strip>;
+export declare const subscribePayloadSchema: z.ZodObject<{
+    channelId: z.ZodNumber;
+    documentId: z.ZodString;
+    epoch: z.ZodNumber;
+    stateVector: z.ZodOptional<z.ZodString>;
+    mode: z.ZodEnum<{
+        view: "view";
+        edit: "edit";
+    }>;
+    snapshotId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const subscribedPayloadSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        writer: "writer";
+        commenter: "commenter";
+        viewer: "viewer";
+        none: "none";
+    }>;
+    epoch: z.ZodNumber;
+    markPermissions: z.ZodUnknown;
+    schemaVersion: z.ZodNumber;
+}, z.core.$strip>;
+export declare const subscribeErrorPayloadSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        FORBIDDEN: "FORBIDDEN";
+        NOT_FOUND: "NOT_FOUND";
+        EPOCH_MISMATCH: "EPOCH_MISMATCH";
+        DOCUMENT_LOCKED: "DOCUMENT_LOCKED";
+        CLIENT_TOO_OLD: "CLIENT_TOO_OLD";
+        DOCUMENT_DELETED: "DOCUMENT_DELETED";
+    }>;
+    detail: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const unsubscribePayloadSchema: z.ZodObject<{
+    channelId: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ackPayloadSchema: z.ZodObject<{
+    clientSeq: z.ZodNumber;
+    serverSeq: z.ZodNumber;
+}, z.core.$strip>;
+export declare const rejectPayloadSchema: z.ZodObject<{
+    clientSeq: z.ZodNumber;
+    code: z.ZodEnum<{
+        FORBIDDEN: "FORBIDDEN";
+        EPOCH_MISMATCH: "EPOCH_MISMATCH";
+        PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+        UPDATE_INVALID: "UPDATE_INVALID";
+        SCHEMA_VIOLATION: "SCHEMA_VIOLATION";
+    }>;
+    detail: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const epochChangedPayloadSchema: z.ZodObject<{
+    newEpoch: z.ZodNumber;
+    reason: z.ZodEnum<{
+        "snapshot-open": "snapshot-open";
+        "import-over": "import-over";
+        "version-restore": "version-restore";
+        "schema-migration": "schema-migration";
+    }>;
+    byUserId: z.ZodString;
+    snapshotId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const roleChangedPayloadSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        writer: "writer";
+        commenter: "commenter";
+        viewer: "viewer";
+        none: "none";
+    }>;
+    markPermissions: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const documentDeletedPayloadSchema: z.ZodObject<{
+    byUserId: z.ZodString;
+    recoverableUntil: z.ZodString;
+}, z.core.$strip>;
+export declare const normalizedPayloadSchema: z.ZodObject<{
+    serverSeq: z.ZodNumber;
+    contentHashes: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export declare const serverShutdownPayloadSchema: z.ZodObject<{
+    reconnectAfterMs: z.ZodNumber;
+}, z.core.$strip>;
+export declare const syncFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"auth">;
+    payload: z.ZodObject<{
+        scheme: z.ZodEnum<{
+            link: "link";
+            firebase: "firebase";
+            apikey: "apikey";
+        }>;
+        token: z.ZodString;
+        deviceId: z.ZodString;
+        installId: z.ZodString;
+        clientVersion: z.ZodString;
+        schemaVersion: z.ZodNumber;
+        unlockToken: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"authOk">;
+    payload: z.ZodObject<{
+        userId: z.ZodString;
+        sessionId: z.ZodString;
+        serverSchemaVersion: z.ZodNumber;
+        heartbeatMs: z.ZodNumber;
+        maxFrameBytes: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"authError">;
+    payload: z.ZodObject<{
+        code: z.ZodEnum<{
+            CLIENT_TOO_OLD: "CLIENT_TOO_OLD";
+            DEVICE_REVOKED: "DEVICE_REVOKED";
+            UNAUTHENTICATED: "UNAUTHENTICATED";
+            ACCOUNT_DISABLED: "ACCOUNT_DISABLED";
+            LINK_EXPIRED: "LINK_EXPIRED";
+            SERVER_TOO_OLD: "SERVER_TOO_OLD";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"reauth">;
+    payload: z.ZodObject<{
+        token: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"ping">;
+    payload: z.ZodObject<{
+        t: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"pong">;
+    payload: z.ZodObject<{
+        t: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"subscribe">;
+    payload: z.ZodObject<{
+        channelId: z.ZodNumber;
+        documentId: z.ZodString;
+        epoch: z.ZodNumber;
+        stateVector: z.ZodOptional<z.ZodString>;
+        mode: z.ZodEnum<{
+            view: "view";
+            edit: "edit";
+        }>;
+        snapshotId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"subscribed">;
+    payload: z.ZodObject<{
+        documentId: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            writer: "writer";
+            commenter: "commenter";
+            viewer: "viewer";
+            none: "none";
+        }>;
+        epoch: z.ZodNumber;
+        markPermissions: z.ZodUnknown;
+        schemaVersion: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"subscribeError">;
+    payload: z.ZodObject<{
+        code: z.ZodEnum<{
+            FORBIDDEN: "FORBIDDEN";
+            NOT_FOUND: "NOT_FOUND";
+            EPOCH_MISMATCH: "EPOCH_MISMATCH";
+            DOCUMENT_LOCKED: "DOCUMENT_LOCKED";
+            CLIENT_TOO_OLD: "CLIENT_TOO_OLD";
+            DOCUMENT_DELETED: "DOCUMENT_DELETED";
+        }>;
+        detail: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"unsubscribe">;
+    payload: z.ZodObject<{
+        channelId: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"syncStep1">;
+    payload: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"syncStep2">;
+    payload: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"update">;
+    payload: z.ZodObject<{
+        epoch: z.ZodNumber;
+        clientSeq: z.ZodNumber;
+        update: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"ack">;
+    payload: z.ZodObject<{
+        clientSeq: z.ZodNumber;
+        serverSeq: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"reject">;
+    payload: z.ZodObject<{
+        clientSeq: z.ZodNumber;
+        code: z.ZodEnum<{
+            FORBIDDEN: "FORBIDDEN";
+            EPOCH_MISMATCH: "EPOCH_MISMATCH";
+            PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+            UPDATE_INVALID: "UPDATE_INVALID";
+            SCHEMA_VIOLATION: "SCHEMA_VIOLATION";
+        }>;
+        detail: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"awareness">;
+    payload: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"epochChanged">;
+    payload: z.ZodObject<{
+        newEpoch: z.ZodNumber;
+        reason: z.ZodEnum<{
+            "snapshot-open": "snapshot-open";
+            "import-over": "import-over";
+            "version-restore": "version-restore";
+            "schema-migration": "schema-migration";
+        }>;
+        byUserId: z.ZodString;
+        snapshotId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"roleChanged">;
+    payload: z.ZodObject<{
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            writer: "writer";
+            commenter: "commenter";
+            viewer: "viewer";
+            none: "none";
+        }>;
+        markPermissions: z.ZodUnknown;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"documentDeleted">;
+    payload: z.ZodObject<{
+        byUserId: z.ZodString;
+        recoverableUntil: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodNumber;
+    type: z.ZodLiteral<"normalized">;
+    payload: z.ZodObject<{
+        serverSeq: z.ZodNumber;
+        contentHashes: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    channelId: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"serverShutdown">;
+    payload: z.ZodObject<{
+        reconnectAfterMs: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+export type SyncFrame = z.infer<typeof syncFrameSchema>;
+export type SyncFrameOf<T extends SyncFrame['type']> = Extract<SyncFrame, {
+    type: T;
+}>;
+export * from './permissions.js';

package/dist/sync/index.js

@@ -0,0 +1,262 @@
+import { z } from 'zod';
+/** Spec 03 §2. Subprotocol string is `fadewright-sync.v1`. */
+export const SYNC_PROTOCOL_VERSION = 1;
+export const SYNC_SUBPROTOCOL = 'fadewright-sync.v1';
+export const SYNC_PATH = '/api/v1/sync';
+export const SYNC_HEARTBEAT_MS = 25_000;
+export const SYNC_MAX_FRAME_BYTES = 1_048_576;
+export const SYNC_AUTH_TIMEOUT_MS = 5_000;
+/** Numeric message-type codes (spec 03 §2.3). Frame = channelId, messageType, payload. */
+export const SYNC_MESSAGE_TYPES = {
+    auth: 0,
+    authOk: 1,
+    authError: 2,
+    reauth: 3,
+    ping: 4,
+    pong: 4,
+    subscribe: 10,
+    subscribed: 11,
+    subscribeError: 12,
+    unsubscribe: 13,
+    syncStep1: 20,
+    syncStep2: 21,
+    update: 22,
+    ack: 23,
+    reject: 24,
+    awareness: 30,
+    epochChanged: 40,
+    roleChanged: 41,
+    documentDeleted: 42,
+    normalized: 43,
+    serverShutdown: 50,
+};
+/** Close codes (spec 03 §2.6). */
+export const SYNC_CLOSE_CODES = {
+    NORMAL: 1000,
+    GOING_AWAY: 1001,
+    MALFORMED_FRAME: 4400,
+    AUTH_TIMEOUT_OR_INVALID: 4401,
+    ACCOUNT_DISABLED_OR_DEVICE_REVOKED: 4403,
+    PROTOCOL_UNSUPPORTED: 4406,
+    HEARTBEAT_TIMEOUT: 4408,
+    /** Document epoch changed (snapshot open / version restore): resubscribe at the new epoch. */
+    EPOCH_CHANGED: 4409,
+    FRAME_TOO_LARGE: 4413,
+    RATE_LIMITED: 4429,
+};
+// ─── Vocabularies ───────────────────────────────────────────────────────────
+export const SYNC_AUTH_SCHEMES = ['firebase', 'apikey', 'link'];
+export const SYNC_AUTH_ERROR_CODES = [
+    'UNAUTHENTICATED',
+    'ACCOUNT_DISABLED',
+    'DEVICE_REVOKED',
+    'LINK_EXPIRED',
+    'CLIENT_TOO_OLD',
+    'SERVER_TOO_OLD',
+];
+export const SYNC_SUBSCRIBE_ERROR_CODES = [
+    'NOT_FOUND',
+    'FORBIDDEN',
+    'DOCUMENT_DELETED',
+    'EPOCH_MISMATCH',
+    'DOCUMENT_LOCKED',
+    'CLIENT_TOO_OLD',
+];
+export const SYNC_REJECT_CODES = [
+    'FORBIDDEN',
+    'EPOCH_MISMATCH',
+    'UPDATE_INVALID',
+    'PAYLOAD_TOO_LARGE',
+    'SCHEMA_VIOLATION',
+];
+export const SYNC_SUBSCRIBE_MODES = ['edit', 'view'];
+export const SYNC_EPOCH_REASONS = [
+    'snapshot-open',
+    'import-over',
+    'version-restore',
+    'schema-migration',
+];
+const roleOrNone = z.enum([
+    'owner',
+    'admin',
+    'writer',
+    'commenter',
+    'viewer',
+    'none',
+]);
+const bytes = z.instanceof(Uint8Array);
+const uint = z.number().int().min(0);
+// ─── Payload schemas (JSON UTF-8 payloads) ──────────────────────────────────
+export const authPayloadSchema = z.object({
+    scheme: z.enum(SYNC_AUTH_SCHEMES),
+    token: z.string(),
+    deviceId: z.string(),
+    installId: z.string(),
+    clientVersion: z.string(),
+    schemaVersion: uint,
+    /** Unlock-session token (`POST /documents/:did/unlock-session`) for opening locked documents. */
+    unlockToken: z.string().optional(),
+});
+export const authOkPayloadSchema = z.object({
+    userId: z.string(),
+    sessionId: z.string(),
+    serverSchemaVersion: uint,
+    heartbeatMs: uint,
+    maxFrameBytes: uint,
+});
+export const authErrorPayloadSchema = z.object({
+    code: z.enum(SYNC_AUTH_ERROR_CODES),
+    message: z.string(),
+});
+export const reauthPayloadSchema = z.object({ token: z.string() });
+export const pingPayloadSchema = z.object({ t: z.number() });
+export const subscribePayloadSchema = z.object({
+    channelId: uint.min(1),
+    documentId: z.string(),
+    epoch: uint,
+    /** base64 state vector */
+    stateVector: z.string().optional(),
+    mode: z.enum(SYNC_SUBSCRIBE_MODES),
+    snapshotId: z.string().optional(),
+});
+export const subscribedPayloadSchema = z.object({
+    documentId: z.string(),
+    role: roleOrNone,
+    epoch: uint,
+    markPermissions: z.unknown(),
+    schemaVersion: uint,
+});
+export const subscribeErrorPayloadSchema = z.object({
+    code: z.enum(SYNC_SUBSCRIBE_ERROR_CODES),
+    detail: z.unknown().optional(),
+});
+export const unsubscribePayloadSchema = z.object({ channelId: uint.min(1) });
+export const ackPayloadSchema = z.object({
+    clientSeq: uint,
+    serverSeq: uint,
+});
+export const rejectPayloadSchema = z.object({
+    clientSeq: uint,
+    code: z.enum(SYNC_REJECT_CODES),
+    detail: z.unknown().optional(),
+});
+export const epochChangedPayloadSchema = z.object({
+    newEpoch: uint,
+    reason: z.enum(SYNC_EPOCH_REASONS),
+    byUserId: z.string(),
+    snapshotId: z.string().optional(),
+});
+export const roleChangedPayloadSchema = z.object({
+    role: roleOrNone,
+    markPermissions: z.unknown(),
+});
+export const documentDeletedPayloadSchema = z.object({
+    byUserId: z.string(),
+    recoverableUntil: z.string(),
+});
+export const normalizedPayloadSchema = z.object({
+    serverSeq: uint,
+    contentHashes: z.record(z.string(), z.string()),
+});
+export const serverShutdownPayloadSchema = z.object({
+    reconnectAfterMs: uint,
+});
+// ─── Frame schemas: decoded `{channelId, type, payload}` ────────────────────
+const ctl = z.literal(0);
+const chan = uint.min(1);
+export const syncFrameSchema = z.discriminatedUnion('type', [
+    z.object({
+        channelId: ctl,
+        type: z.literal('auth'),
+        payload: authPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('authOk'),
+        payload: authOkPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('authError'),
+        payload: authErrorPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('reauth'),
+        payload: reauthPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('ping'),
+        payload: pingPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('pong'),
+        payload: pingPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('subscribe'),
+        payload: subscribePayloadSchema,
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('subscribed'),
+        payload: subscribedPayloadSchema,
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('subscribeError'),
+        payload: subscribeErrorPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('unsubscribe'),
+        payload: unsubscribePayloadSchema,
+    }),
+    z.object({ channelId: chan, type: z.literal('syncStep1'), payload: bytes }),
+    z.object({ channelId: chan, type: z.literal('syncStep2'), payload: bytes }),
+    z.object({
+        channelId: chan,
+        type: z.literal('update'),
+        payload: z.object({ epoch: uint, clientSeq: uint, update: bytes }),
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('ack'),
+        payload: ackPayloadSchema,
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('reject'),
+        payload: rejectPayloadSchema,
+    }),
+    z.object({ channelId: chan, type: z.literal('awareness'), payload: bytes }),
+    z.object({
+        channelId: chan,
+        type: z.literal('epochChanged'),
+        payload: epochChangedPayloadSchema,
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('roleChanged'),
+        payload: roleChangedPayloadSchema,
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('documentDeleted'),
+        payload: documentDeletedPayloadSchema,
+    }),
+    z.object({
+        channelId: chan,
+        type: z.literal('normalized'),
+        payload: normalizedPayloadSchema,
+    }),
+    z.object({
+        channelId: ctl,
+        type: z.literal('serverShutdown'),
+        payload: serverShutdownPayloadSchema,
+    }),
+]);
+export * from './permissions.js';

package/dist/sync/permissions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Spec 03 §3.2 write matrix as data, projected from spec 05's role matrix onto Y.Doc keys.
+ * The server checks inbound updates against it; `markPermissionsFor` is what `subscribed` and
+ * `roleChanged` send so a client can disable UI instead of being rejected.
+ */
+import type { Role } from '../tenancy/index.js';
+/** Top-level Y.Doc keys a commenter may change (notes and replies, R6). */
+export declare const COMMENTER_WRITABLE_KEYS: readonly string[];
+/** Inline marks a commenter may add or remove inside element text: note anchors `n:<NoteId>` and the highlighter. */
+export declare const isCommenterMark: (name: string) => boolean;
+/** What a role may produce (courtesy for the UI; the server check is the authority). */
+export interface MarkPermissions {
+    /** Text, attributes, structure, tags, revisions, settings: everything an owner/admin/writer writes. */
+    edit: boolean;
+    /** Notes and replies (`notes` + `n:` marks). */
+    comment: boolean;
+    /** Highlighter (`hl` marks). */
+    highlight: boolean;
+}
+export declare function markPermissionsFor(role: Role | 'none'): MarkPermissions;
+/** Roles that may send `update` frames at all (a commenter's are filtered by the matrix). */
+export declare const canSendUpdates: (role: Role) => boolean;

package/dist/sync/permissions.js

@@ -0,0 +1,11 @@
+/** Top-level Y.Doc keys a commenter may change (notes and replies, R6). */
+export const COMMENTER_WRITABLE_KEYS = ['notes'];
+/** Inline marks a commenter may add or remove inside element text: note anchors `n:<NoteId>` and the highlighter. */
+export const isCommenterMark = (name) => name === 'hl' || name.startsWith('n:');
+export function markPermissionsFor(role) {
+    const edit = role === 'owner' || role === 'admin' || role === 'writer';
+    const comment = edit || role === 'commenter';
+    return { edit, comment, highlight: comment };
+}
+/** Roles that may send `update` frames at all (a commenter's are filtered by the matrix). */
+export const canSendUpdates = (role) => role !== 'viewer';