@tldraw/sync-core 5.3.0-next.fc37bd96825b → 5.3.1

package/src/lib/TLSyncRoom.ts

@@ -31,6 +31,7 @@ import { interval } from './interval'
 import {
 	getTlsyncProtocolVersion,
 	TLIncompatibilityReason,
+	TLObjectStoreAccess,
 	TLSocketClientSentEvent,
 	TLSocketServerSentDataEvent,
 	TLSocketServerSentEvent,
@@ -120,6 +121,69 @@ export interface RoomSnapshot {
 	schema?: SerializedSchema
 }
 
+/**
+ * Authorizes a single record write from a client: any per-record, per-session rule the host wants
+ * to enforce server-side — veto writes the session isn't allowed to make, or rewrite the record on
+ * create. The session's `meta` carries whatever the rule needs (identity, roles, …); for example,
+ * force a comment's `authorId` to the signed-in user so nobody can post in someone else's name.
+ *
+ * Called on **create**, **update**, and **delete** of records whose `typeName` it's registered for
+ * (see {@link TLRecordAuthorizers}), and only for client pushes — never for server-initiated writes.
+ *
+ * `prev` and `next` are always at the **server's** schema version: client writes are migrated
+ * before the authorizer runs, so guarding or stamping a field never requires knowing what older
+ * clients call it. On create, the record you return is what gets stored (after validation) — no
+ * migration runs afterwards, so stamped fields can't be clobbered.
+ *
+ * Return `null` to reject the write — it's skipped and the client self-corrects, exactly like the
+ * `objectAccess` gate. Otherwise the write is allowed, and:
+ *
+ * - on **create**, the record you return is what gets stored, so stamp identity fields here (e.g.
+ *   set `authorId` from `session.meta`);
+ * - on **update** and **delete**, only allow-vs-reject is used (the returned record's contents are
+ *   ignored), so use them to veto changes to immutable fields or unauthorized deletes — return
+ *   `next`/`prev` to allow, `null` to reject.
+ *
+ * ⚠︎ Runs synchronously inside the commit transaction, on the same path as every document edit — it
+ * must be fast and do **no** I/O. `next`/`prev` are client-controlled records, so treat their
+ * contents as untrusted; prefer returning `null` to reject over throwing, though a throw is
+ * caught, logged, and treated as a rejection (fail closed) rather than crashing the push. For
+ * expensive, async checks (e.g. resolving mentions against who can access a file), react after the
+ * fact via `onCommittedChanges`.
+ *
+ * @public
+ */
+export type TLRecordAuthorizer<Rec extends UnknownRecord, SessionMeta> = (
+	args: {
+		/** The session performing the write: its host-provided `meta` (e.g. the authenticated user
+		 *  id) and the canvas-lane `isReadonly` state, for hosts whose object-lane policy follows
+		 *  canvas access. */
+		session: { sessionId: string; isReadonly: boolean; meta: SessionMeta }
+	} & (
+		| { type: 'create'; prev: null; next: Rec }
+		| { type: 'update'; prev: Rec; next: Rec }
+		| { type: 'delete'; prev: Rec; next: null }
+	)
+) => Rec | null
+
+/**
+ * A map from record `typeName` to a {@link TLRecordAuthorizer} for that record type. Only listed
+ * types are authorized; every other record writes through untouched, so this stays off the hot path
+ * for the vast majority of writes (shape drags etc.).
+ *
+ * Each authorizer is typed to its record — e.g. `next` in the `comment` entry is a `TLComment` — so
+ * renaming a field on the record makes the authorizer that reads it fail to compile, rather than
+ * silently stamp or guard the wrong field.
+ *
+ * Presence records are never authorized (presence is per-session and ephemeral); registering the
+ * presence typeName is a construction-time error.
+ *
+ * @public
+ */
+export type TLRecordAuthorizers<R extends UnknownRecord, SessionMeta> = {
+	[K in R['typeName']]?: TLRecordAuthorizer<Extract<R, { typeName: K }>, SessionMeta>
+}
+
 /**
  * A collaborative workspace that manages multiple client sessions and synchronizes
  * document changes between them. The room serves as the authoritative source for
@@ -236,22 +300,74 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 	readonly serializedSchema: SerializedSchema
 
 	readonly documentTypes: Set<string>
+	/**
+	 * Record types served by the object-store lane. Object records ride the same wire messages
+	 * as document records but are gated by the session's `objectAccess` instead of `isReadonly`,
+	 * and are excluded from `documentTypes` so hosts can persist them in a separate lane.
+	 */
+	readonly objectTypes: Set<string>
 	readonly presenceType: RecordType<R, any> | null
 	private log?: TLSyncLog
 	public readonly schema: StoreSchema<R, any>
 	private onPresenceChange?(): void
+	private onCommittedChanges?(args: { diff: TLSyncForwardDiff<R>; documentClock: number }): void
+	private readonly authorizeRecord?: TLRecordAuthorizers<R, SessionMeta>
 	private readonly sessionIdleTimeout: number
 
+	/**
+	 * The authorizer registered for a record type, widened to the room's record union. Each entry in
+	 * `authorizeRecord` is typed to its specific record; the cast here is the one place we can't
+	 * statically correlate a runtime `typeName` with its record type, so it lives in the library
+	 * rather than in every consumer.
+	 */
+	private authorizerFor(typeName: R['typeName']): TLRecordAuthorizer<R, SessionMeta> | undefined {
+		const authorize = this.authorizeRecord?.[typeName] as
+			| TLRecordAuthorizer<R, SessionMeta>
+			| undefined
+		if (!authorize) return undefined
+		// Fail closed: an authorizer that throws rejects the write (and is logged) rather than
+		// aborting the whole push. Authorizers are security-sensitive, so a bug must never let a
+		// write through.
+		return (args) => {
+			try {
+				return authorize(args)
+			} catch (e) {
+				this.log?.error?.('record authorizer threw; rejecting the write', e)
+				return null
+			}
+		}
+	}
+
 	constructor(opts: {
 		log?: TLSyncLog
 		schema: StoreSchema<R, any>
 		onPresenceChange?(): void
+		/**
+		 * Called once after a client push commits, with the committed document diff. Fires for
+		 * local and remote pushes. Use this to react to document changes (e.g. persist certain
+		 * record types to a separate lane, or project them to an external store) as soon as they
+		 * commit. Best-effort — do not throw; do not block.
+		 */
+		onCommittedChanges?(args: { diff: TLSyncForwardDiff<R>; documentClock: number }): void
+		/**
+		 * Record type names to serve through the object-store lane instead of the document lane.
+		 * Each must be a document-scoped type registered in the schema. Object-lane writes are
+		 * gated per session by `objectAccess` rather than `isReadonly`.
+		 */
+		objectTypes?: readonly string[]
+		/**
+		 * Per-type authorizers for client record writes (create, update, delete): veto or, on
+		 * create, rewrite. See {@link TLRecordAuthorizers}.
+		 */
+		authorizeRecord?: TLRecordAuthorizers<R, SessionMeta>
 		storage: TLSyncStorage<R>
 		clientTimeout?: number
 	}) {
 		this.schema = opts.schema
 		this.log = opts.log
 		this.onPresenceChange = opts.onPresenceChange
+		this.onCommittedChanges = opts.onCommittedChanges
+		this.authorizeRecord = opts.authorizeRecord
 		this.storage = opts.storage
 		this.sessionIdleTimeout = opts.clientTimeout ?? SESSION_IDLE_TIMEOUT
 
@@ -264,9 +380,20 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		// do a json serialization cycle to make sure the schema has no 'undefined' values
 		this.serializedSchema = JSON.parse(JSON.stringify(this.schema.serialize()))
 
+		this.objectTypes = new Set(opts.objectTypes ?? [])
+		for (const typeName of this.objectTypes) {
+			const type = getOwnProperty(this.schema.types, typeName)
+			assert(type, `TLSyncRoom: object type '${typeName}' is not registered in the schema`)
+			assert(
+				type.scope === 'document',
+				`TLSyncRoom: object type '${typeName}' must have scope 'document', got '${type.scope}'`
+			)
+		}
+
+		// object-lane types are partitioned out of the document lane
 		this.documentTypes = new Set(
 			Object.values<RecordType<R, any>>(this.schema.types)
-				.filter((t) => t.scope === 'document')
+				.filter((t) => t.scope === 'document' && !this.objectTypes.has(t.typeName))
 				.map((t) => t.typeName)
 		)
 
@@ -282,6 +409,15 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 
 		this.presenceType = presenceTypes.values().next()?.value ?? null
 
+		// The presence lane never consults authorizers, so a presence key in `authorizeRecord`
+		// would be a silent no-op — fail loudly at construction instead.
+		if (this.presenceType && this.authorizeRecord) {
+			assert(
+				!getOwnProperty(this.authorizeRecord, this.presenceType.typeName),
+				`TLSyncRoom: authorizeRecord['${this.presenceType.typeName}'] is a presence type; presence records are not authorized`
+			)
+		}
+
 		const { documentClock } = this.storage.transaction((txn) => {
 			this.schema.migrateStorage(txn)
 		})
@@ -442,6 +578,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			cancellationTime: Date.now(),
 			meta: session.meta,
 			isReadonly: session.isReadonly,
+			objectAccess: session.objectAccess,
 			requiresLegacyRejection: session.requiresLegacyRejection,
 			supportsStringAppend: session.supportsStringAppend,
 		})
@@ -552,8 +689,9 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		socket: TLRoomSocket<R>
 		meta: SessionMeta
 		isReadonly: boolean
+		objectAccess?: TLObjectStoreAccess
 	}) {
-		const { sessionId, socket, meta, isReadonly } = opts
+		const { sessionId, socket, meta, isReadonly, objectAccess } = opts
 		const existing = this.sessions.get(sessionId)
 		this.sessions.set(sessionId, {
 			state: RoomSessionState.AwaitingConnectMessage,
@@ -563,6 +701,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			sessionStartTime: Date.now(),
 			meta,
 			isReadonly: isReadonly ?? false,
+			objectAccess: objectAccess ?? 'write',
 			// this gets set later during handleConnectMessage
 			requiresLegacyRejection: false,
 			supportsStringAppend: true,
@@ -582,6 +721,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		socket: TLRoomSocket<R>
 		meta: SessionMeta
 		isReadonly: boolean
+		objectAccess?: TLObjectStoreAccess
 		serializedSchema: SerializedSchema
 		presenceId: string | null
 		presenceRecord: UnknownRecord | null
@@ -593,6 +733,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			socket,
 			meta,
 			isReadonly,
+			objectAccess,
 			serializedSchema,
 			presenceId,
 			presenceRecord,
@@ -615,6 +756,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			outstandingDataMessages: [],
 			meta,
 			isReadonly,
+			objectAccess: objectAccess ?? 'write',
 			requiresLegacyRejection,
 			supportsStringAppend,
 		})
@@ -927,6 +1069,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				supportsStringAppend: session.supportsStringAppend,
 				meta: session.meta,
 				isReadonly: session.isReadonly,
+				objectAccess: session.objectAccess,
 				requiresLegacyRejection: session.requiresLegacyRejection,
 			})
 			this._unsafe_sendMessage(session.sessionId, msg)
@@ -977,6 +1120,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				serverClock: txn.getClock(),
 				diff: { ...presenceDiff.value, ...docDiff },
 				isReadonly: session.isReadonly,
+				objectAccess: session.objectAccess,
 			} satisfies Extract<TLSocketServerSentEvent<R>, { type: 'connect' }>
 		}) // no id needed because this only reads, no writes.
 
@@ -1038,7 +1182,11 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			storage: MinimalDocStore<R>,
 			changes: ActualChanges,
 			id: string,
-			_state: R
+			_state: R,
+			authorize?: (prev: R | null, next: R) => R | null,
+			// The existing document if the caller already fetched it; `null` for fetched-and-absent,
+			// `undefined` for not fetched. Saves a second SELECT + JSON.parse on the push hot path.
+			prevDoc?: R | null
 		): Result<void, void> => {
 			const res = session
 				? this.schema.migratePersistedRecord(_state, session.serializedSchema, 'up')
@@ -1046,10 +1194,19 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			if (res.type === 'error') {
 				throw new TLSyncError(res.reason, TLSyncErrorCloseEventReason.CLIENT_TOO_OLD)
 			}
-			const { value: state } = res
+			let { value: state } = res
 
 			// Get the existing document, if any
-			const doc = storage.get(id) as R | undefined
+			const doc =
+				prevDoc !== undefined ? (prevDoc ?? undefined) : (storage.get(id) as R | undefined)
+
+			// Authorize on the up-migrated record; on create the authorizer's return is stored as-is,
+			// so no later migration can clobber stamped fields.
+			if (authorize) {
+				const result = authorize(doc ?? null, state)
+				if (!result) return Result.ok(undefined) // vetoed: skip the op, the client self-corrects
+				if (!doc) state = result // create: store the authorizer's (stamped) record
+			}
 
 			if (doc) {
 				// If there's an existing document, replace it with the new state
@@ -1077,10 +1234,13 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			storage: MinimalDocStore<R>,
 			changes: ActualChanges,
 			id: string,
-			patch: ObjectDiff
+			patch: ObjectDiff,
+			authorize?: (prev: R, next: R) => R | null,
+			// The existing document if the caller already fetched it (see `addDocument`).
+			prevDoc?: R
 		) => {
 			// if it was already deleted, there's no need to apply the patch
-			const doc = storage.get(id) as R | undefined
+			const doc = prevDoc ?? (storage.get(id) as R | undefined)
 			if (!doc) return
 
 			const recordType = assertExists(getOwnProperty(this.schema.types, doc.typeName))
@@ -1097,6 +1257,8 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				// If the versions are compatible, apply the patch and propagate the patch op
 				const diff = applyAndDiffRecord(doc, patch, recordType, legacyAppendMode)
 				if (diff) {
+					// Authorize on the committed candidate — the record that will actually be stored.
+					if (authorize && !authorize(doc, diff[1])) return
 					storage.set(id, diff[1])
 					propagateOp(changes, id, [RecordOpType.Patch, diff[0]], doc, diff[1])
 				}
@@ -1116,6 +1278,8 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				// replace the state with the upgraded version and propagate the patch op
 				const diff = diffAndValidateRecord(doc, upgraded.value, recordType, legacyAppendMode)
 				if (diff) {
+					// Authorize on the committed candidate — the upgraded record, not a raw preview.
+					if (authorize && !authorize(doc, upgraded.value)) return
 					storage.set(id, upgraded.value)
 					propagateOp(changes, id, [RecordOpType.Patch, diff], doc, upgraded.value)
 				}
@@ -1158,33 +1322,173 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 						}
 					}
 				}
-				if (message.diff && !session?.isReadonly) {
+				// Per-op write gate: document-lane records are gated by `isReadonly`, object-lane
+				// records by `objectAccess`. Denied ops are skipped (the client is corrected by the
+				// resulting discard/rebase push_result, exactly as whole-diff readonly skips were).
+				// Server-initiated pushes (no session) are always allowed.
+				const canWrite = (typeName: string) =>
+					!session ||
+					(this.objectTypes.has(typeName) ? session.objectAccess !== 'read' : !session.isReadonly)
+
+				if (message.diff) {
 					// The push request was for the document scope.
 					for (const [id, op] of objectMapEntriesIterable(message.diff!)) {
 						switch (op[0]) {
 							case RecordOpType.Put: {
+								// The write gate is checked before type validation so that a denied
+								// session's ops are skipped without rejection, matching the previous
+								// whole-diff readonly behavior.
+								if (!canWrite(op[1].typeName)) continue
 								// Try to add the document.
 								// If we're putting a record with a type that we don't recognize, fail
-								if (!this.documentTypes.has(op[1].typeName)) {
+								if (
+									!this.documentTypes.has(op[1].typeName) &&
+									!this.objectTypes.has(op[1].typeName)
+								) {
 									throw new TLSyncError(
 										'invalid record',
 										TLSyncErrorCloseEventReason.INVALID_RECORD
 									)
 								}
-								addDocument(txn, docChanges, id, op[1])
+								const record = op[1]
+								// A put must not change the record's typeName. Two reasons, and the first
+								// applies whether or not authorizers are configured: the write gate above
+								// keyed off the *incoming* typeName, so a swap between lanes (document <->
+								// object) would let a session denied on one lane write through the other by
+								// relabeling an existing record. The second is that the authorizer lookup
+								// also keys off the incoming typeName while the replace path validates
+								// against the stored one, so a swap would consult the wrong authorizer (or
+								// none). Skip it like a veto; the client self-corrects.
+								// `undefined` (no session) means the guard didn't fetch, so addDocument will.
+								const prevRecord = session ? ((txn.get(id) as R | undefined) ?? null) : undefined
+								if (session && prevRecord && prevRecord.typeName !== record.typeName) {
+									this.log?.warn?.(
+										'skipping put that changes typeName',
+										`${prevRecord.typeName} -> ${record.typeName}`,
+										id,
+										'session:',
+										session.sessionId
+									)
+									continue
+								}
+								// Per-type authorizer: stamp/veto the write from the session's identity.
+								// Client pushes only; runs inside `addDocument`, on the up-migrated record.
+								let authorize: ((prev: R | null, next: R) => R | null) | undefined
+								if (session && this.authorizeRecord) {
+									const authorizePut = this.authorizerFor(record.typeName)
+									if (authorizePut) {
+										authorize = (prevRec, next) => {
+											const result = authorizePut(
+												prevRec
+													? {
+															session: {
+																sessionId: session.sessionId,
+																isReadonly: session.isReadonly,
+																meta: session.meta,
+															},
+															type: 'update',
+															prev: prevRec,
+															next,
+														}
+													: {
+															session: {
+																sessionId: session.sessionId,
+																isReadonly: session.isReadonly,
+																meta: session.meta,
+															},
+															type: 'create',
+															prev: null,
+															next,
+														}
+											)
+											if (!result) {
+												this.log?.warn?.(
+													'authorizer vetoed put',
+													record.typeName,
+													id,
+													'session:',
+													session.sessionId
+												)
+												return null
+											}
+											// create: store the stamped record; update: allow/veto only
+											return prevRec ? next : result
+										}
+									}
+								}
+								// The guard above already fetched this, so don't hit storage again.
+								addDocument(txn, docChanges, id, record, authorize, prevRecord)
 								break
 							}
 							case RecordOpType.Patch: {
-								// Try to patch the document. If it fails, stop here.
-								patchDocument(txn, docChanges, id, op[1])
+								const doc = txn.get(id) as R | undefined
+								// if it was already deleted, there's no need to apply the patch
+								if (!doc) continue
+								if (!canWrite(doc.typeName)) continue
+								// Per-type authorizer (update, allow/veto only): runs inside `patchDocument`
+								// on the committed candidate, never on a raw client-version preview.
+								const authorizePatch = session && this.authorizerFor(doc.typeName)
+								const authorize = authorizePatch
+									? (prev: R, next: R) => {
+											const result = authorizePatch({
+												session: {
+													sessionId: session.sessionId,
+													isReadonly: session.isReadonly,
+													meta: session.meta,
+												},
+												type: 'update',
+												prev,
+												next,
+											})
+											if (!result) {
+												this.log?.warn?.(
+													'authorizer vetoed patch',
+													doc.typeName,
+													id,
+													'session:',
+													session.sessionId
+												)
+											}
+											return result
+										}
+									: undefined
+								// Try to patch the document. If it fails, stop here. The write gate above
+								// already fetched the record, so pass it through.
+								patchDocument(txn, docChanges, id, op[1], authorize, doc)
 								break
 							}
 							case RecordOpType.Remove: {
-								const doc = txn.get(id)
+								const doc = txn.get(id) as R | undefined
 								if (!doc) {
 									// If the doc was already deleted, don't do anything, no need to propagate a delete op
 									continue
 								}
+								if (!canWrite(doc.typeName)) continue
+								// Per-type authorizer (delete): veto deletes the session isn't allowed to make,
+								// e.g. deleting someone else's comment. Allow/veto only.
+								const authorizeRemove = session && this.authorizerFor(doc.typeName)
+								if (
+									authorizeRemove &&
+									!authorizeRemove({
+										session: {
+											sessionId: session.sessionId,
+											isReadonly: session.isReadonly,
+											meta: session.meta,
+										},
+										type: 'delete',
+										prev: doc,
+										next: null,
+									})
+								) {
+									this.log?.warn?.(
+										'authorizer vetoed delete',
+										doc.typeName,
+										id,
+										'session:',
+										session.sessionId
+									)
+									continue
+								}
 
 								// Delete the document and propagate the delete op
 								// delete automatically creates tombstones
@@ -1272,6 +1576,17 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				this.onPresenceChange?.()
 			})
 		}
+
+		if (result.docChanges.diffs && this.onCommittedChanges) {
+			const diff = result.docChanges.diffs.diff
+			queueMicrotask(() => {
+				try {
+					this.onCommittedChanges?.({ diff, documentClock })
+				} catch (e) {
+					this.log?.error?.('onCommittedChanges threw', e)
+				}
+			})
+		}
 	}
 
 	/**

package/src/lib/TLSyncStorage.ts

@@ -83,7 +83,22 @@ export interface TLSyncStorage<R extends UnknownRecord> {
 
 	onChange(callback: (arg: TLSyncStorageOnChangeCallbackProps) => unknown): () => void
 
+	/** A snapshot of the document lane only — never contains object-store lane records. */
 	getSnapshot?(): RoomSnapshot
+
+	/**
+	 * A snapshot of the object-store lane (see `objectTypes` on the storage), for hosts that
+	 * persist object-lane records separately from the document. Same entry shape as
+	 * `RoomSnapshot['documents']` so a lane can be persisted and re-seeded via a merged snapshot.
+	 */
+	getObjectsSnapshot?(): RoomSnapshot['documents']
+
+	/**
+	 * The same entries for the given ids, for callers that need a handful of records rather than the
+	 * whole (parsed) lane. Ids with no object-lane record are omitted — document-lane ids included —
+	 * and duplicates yield one entry.
+	 */
+	getObjectsByIds?(ids: Iterable<string>): RoomSnapshot['documents']
 }
 
 /**

package/src/lib/protocol.ts

@@ -24,6 +24,17 @@ export function getTlsyncProtocolVersion() {
 	return TLSYNC_PROTOCOL_VERSION
 }
 
+/**
+ * Access level for object-store lane record types (see `objectTypes` on the room).
+ *
+ * Object-lane records (e.g. comments) are gated by this per-session value instead of the
+ * document-lane `isReadonly` flag, so a session can be allowed to write objects without
+ * being allowed to edit the document ("can comment but not edit"), or vice versa.
+ *
+ * @public
+ */
+export type TLObjectStoreAccess = 'read' | 'write'
+
 /**
  * Constants defining the different types of protocol incompatibility reasons.
  *
@@ -108,6 +119,12 @@ export type TLSocketServerSentEvent<R extends UnknownRecord> =
 			diff: NetworkDiff<R>
 			serverClock: number
 			isReadonly: boolean
+			/**
+			 * Write access for object-store lane record types, when the room has an object lane.
+			 * Optional and additive: servers without an object lane (or older servers) omit it, and
+			 * older clients ignore it — no protocol version bump needed.
+			 */
+			objectAccess?: TLObjectStoreAccess
 	  }
 	| {
 			type: 'incompatibility_error'

package/src/test/TLSocketRoom.test.ts

@@ -48,8 +48,13 @@ function createMockSocket(overrides: Partial<WebSocketMinimal> = {}): WebSocketM
 }
 
 // Connect a session and complete the connect handshake
-function connectSession(room: TLSocketRoom<any, any>, sessionId: string, socket: WebSocketMinimal) {
-	room.handleSocketConnect({ sessionId, socket })
+function connectSession(
+	room: TLSocketRoom<any, any>,
+	sessionId: string,
+	socket: WebSocketMinimal,
+	opts: { objectAccess?: 'read' | 'write' } = {}
+) {
+	room.handleSocketConnect({ sessionId, socket, ...opts })
 	const connectRequest = {
 		type: 'connect' as const,
 		connectRequestId: `connect-${sessionId}`,
@@ -997,11 +1002,41 @@ describe('28. TLSocketRoom (SR)', () => {
 			expect(snapshot).not.toBeNull()
 			expect(snapshot!.serializedSchema).toBeDefined()
 			expect(snapshot!.isReadonly).toBe(false)
+			expect(snapshot!.objectAccess).toBe('write')
 			expect(snapshot!.presenceId).toBeDefined()
 			expect(snapshot!.requiresLegacyRejection).toBe(false)
 			expect(snapshot!.supportsStringAppend).toBe(true)
 		})
 
+		it('[SR13] round-trips objectAccess through snapshot and resume', () => {
+			const room = new TLSocketRoom({})
+			const socket = createMockSocket()
+			connectSession(room, 'test', socket, { objectAccess: 'read' })
+
+			const snapshot = room.getSessionSnapshot('test')!
+			expect(snapshot.objectAccess).toBe('read')
+
+			// Simulate hibernation: resume in a new room
+			const room2 = new TLSocketRoom({})
+			room2.handleSocketResume({ sessionId: 'test', socket: createMockSocket(), snapshot })
+			expect(room2.getSessions()[0].objectAccess).toBe('read')
+		})
+
+		it('[SR13] resumes legacy snapshots without objectAccess as read (fail closed)', () => {
+			const room = new TLSocketRoom({})
+			const socket = createMockSocket()
+			connectSession(room, 'test', socket)
+
+			const snapshot = room.getSessionSnapshot('test')!
+			// simulate a snapshot persisted before the objectAccess field existed
+			delete snapshot.objectAccess
+
+			const room2 = new TLSocketRoom({})
+			room2.handleSocketResume({ sessionId: 'test', socket: createMockSocket(), snapshot })
+			// such sessions predate the record types gated by objectAccess, so they have nothing to write anyway
+			expect(room2.getSessions()[0].objectAccess).toBe('read')
+		})
+
 		it('[SR13] includes presence record when present', () => {
 			const store = getStore()
 			store.ensureStoreIsUsable()

package/src/test/TLSyncRoom.test.ts

@@ -188,6 +188,7 @@ function makeRoom(
 		clientTimeout?: number
 		log?: { warn?: Mock; error?: Mock }
 		onPresenceChange?(): void
+		onCommittedChanges?(args: { diff: any; documentClock: number }): void
 	} = {}
 ) {
 	const storage = new InMemorySyncStorage<TLRecord>({
@@ -199,6 +200,7 @@ function makeRoom(
 		clientTimeout: opts.clientTimeout,
 		log: opts.log,
 		onPresenceChange: opts.onPresenceChange,
+		onCommittedChanges: opts.onCommittedChanges,
 	})
 	disposables.push(() => room.close())
 	return { storage, room }
@@ -634,6 +636,29 @@ describe('22. Room construction (RC)', () => {
 		expect(clientBMessages[0].data[0].type).toBe('patch')
 	})
 
+	it('fires onCommittedChanges once with the committed document diff after a push', async () => {
+		const onCommittedChanges = vi.fn()
+		const { room } = makeRoom({ onCommittedChanges })
+		connectSession(room, 'session-a')
+
+		const newPage = makePage('committed_page', 'Committed Page')
+		room.handleMessage('session-a', {
+			type: 'push',
+			clientClock: 1,
+			diff: {
+				[newPage.id]: ['put', newPage],
+			},
+		} as TLPushRequest<TLRecord>)
+
+		// the tap fires in a microtask, like onPresenceChange
+		await Promise.resolve()
+
+		expect(onCommittedChanges).toHaveBeenCalledTimes(1)
+		const arg = onCommittedChanges.mock.calls[0][0]
+		expect(arg.diff.puts[newPage.id]).toBeTruthy()
+		expect(typeof arg.documentClock).toBe('number')
+	})
+
 	it('[RC4] handles multiple rapid external changes', async () => {
 		const { room, storage } = makeRoom()
 		const socket = connectSession(room, 'test-session')