edytor 3.0.0 → 5.0.0

package/dist/cloudflare/room/purge.d.ts

@@ -1,4 +1,4 @@
-import type { PurgeReport } from '../../crdt/purge.js';
+import { type PurgeReport } from '../../crdt/purge.js';
 import { type RoomContext } from './context.js';
 export declare class RoomPurge {
     #private;
@@ -8,8 +8,11 @@ export declare class RoomPurge {
     get days(): number | null;
     /** A change was stored at `at`: the purge tick runs a day later at the latest. */
     noteChange(at: number): void;
-    /** The purge task (`AttachedDocument.purge`). */
+    /**
+     * The purge task (`AttachedDocument.purge`): its report, `horizon` the
+     * epoch it purged to (`null`: only ended sessions' deletes).
+     */
     tick(): (PurgeReport & {
-        horizon: number;
+        horizon: number | null;
     }) | null;
 }

package/dist/cloudflare/room/purge.js

@@ -1,10 +1,13 @@
 /**
  * The purge (`room.purge.*`): the daily tick records an epoch (the state
  * vector) when the document changed, and purges what was deleted before
- * the horizon — the newest epoch at least `purgeAfterDays` old — as the
- * room's own transaction (`crdt/purge.ts`), then compacts.
+ * the horizon — the newest epoch at least `purgeAfterDays` old — and what
+ * the sessions whose history ended deleted (`hist.release.end`), as the
+ * room's own transaction (`crdt/purge.ts`), then compacts. With no epoch
+ * due, a tick still purges the ended sessions' deletes.
  */
 import { Y } from '../../crdt/engine.js';
+import { releasesOf } from '../../crdt/purge.js';
 import { asEngineDoc } from '../../crdt/structs.js';
 import { PURGE_ORIGIN, noTimers } from './shared.js';
 import { DEFAULT_RETENTION_DAYS } from '../history.js';
@@ -27,7 +30,10 @@ export class RoomPurge {
         if (this.days !== null)
             this.room.scheduler.schedule('purge', at + DAY, 'earlier');
     }
-    /** The purge task (`AttachedDocument.purge`). */
+    /**
+     * The purge task (`AttachedDocument.purge`): its report, `horizon` the
+     * epoch it purged to (`null`: only ended sessions' deletes).
+     */
     tick() {
         const room = this.room;
         const { scheduler, sql, tables } = room;
@@ -61,6 +67,10 @@ export class RoomPurge {
             if (horizon !== undefined && horizon.at > purged) {
                 result = this.#purgeTo({ at: horizon.at, sv: new Uint8Array(horizon.sv) });
             }
+            else if (releasesOf(asEngineDoc(doc)).size > 0) {
+                // No epoch is due: the ended sessions' deletes go all the same.
+                result = this.#purgeTo(null);
+            }
             // The next epoch to pass the horizon, or the next change, arms it again.
             const next = sql
                 .exec(`SELECT at FROM ${tables.epochs} WHERE at > ? ORDER BY at LIMIT 1`, Math.max(purged, horizon?.at ?? -1))
@@ -72,18 +82,27 @@ export class RoomPurge {
             return result;
         });
     }
-    /** Purge what was deleted before `horizon`, as the room's own transaction, then compact. */
+    /**
+     * Purge what was deleted before `horizon` and what ended sessions deleted
+     * (`null`: only those), as the room's own transaction, then compact. A
+     * purge of ended sessions' deletes that finds none left compacts nothing
+     * and reports `null`.
+     */
     #purgeTo(horizon) {
         const room = this.room;
         const doc = room.requireDoc();
         // A restore past the horizon can no longer be undone (`room.history.undo`).
-        room.history.expireRestore(horizon.at);
+        if (horizon !== null)
+            room.history.expireRestore(horizon.at);
         room.history.closeSlotIfPast();
         let report;
+        let wrote = true;
         room.transacting = true;
         try {
             room.facade.transact(() => {
                 report = crdt.doc.purge(asEngineDoc(doc), room.facade, horizon);
+                const tr = asEngineDoc(doc)._transaction;
+                wrote = !tr.insertSet.isEmpty() || !tr.deleteSet.isEmpty();
             }, PURGE_ORIGIN);
         }
         finally {
@@ -94,30 +113,37 @@ export class RoomPurge {
             room.storage.heal();
             throw error;
         }
-        room.ctx.storage.transactionSync(() => {
-            room.sql.exec(`INSERT OR REPLACE INTO ${room.tables.meta} (key, value) VALUES ('purged', ?)`, horizon.at);
-            room.sql.exec(`DELETE FROM ${room.tables.epochs} WHERE at < ?`, horizon.at);
-        });
-        room.storage.compact();
-        const counters = room.counters.purge;
-        counters.runs++;
-        counters.horizon = horizon.at;
-        for (const key of [
+        if (horizon !== null)
+            room.ctx.storage.transactionSync(() => {
+                room.sql.exec(`INSERT OR REPLACE INTO ${room.tables.meta} (key, value) VALUES ('purged', ?)`, horizon.at);
+                room.sql.exec(`DELETE FROM ${room.tables.epochs} WHERE at < ?`, horizon.at);
+            });
+        const keys = [
             'removed',
             'emptied',
             'marks',
             'records',
-            'candidates',
             'claims',
-            'merged'
-        ])
+            'merged',
+            'released',
+            'suggestions'
+        ];
+        // Nothing an ended session deleted was left: no compaction, no run.
+        if (horizon === null && !wrote)
+            return null;
+        room.storage.compact();
+        const counters = room.counters.purge;
+        counters.runs++;
+        if (horizon !== null)
+            counters.horizon = horizon.at;
+        for (const key of keys)
             counters[key] += report[key];
         room.log({
             edytor: 'purge',
-            horizon: horizon.at,
+            horizon: horizon?.at ?? null,
             bytes: room.counters.compaction.lastBytes,
             ...report
         });
-        return { ...report, horizon: horizon.at };
+        return { ...report, horizon: horizon?.at ?? null };
     }
 }

package/dist/cloudflare/room/replicas.d.ts

@@ -28,14 +28,16 @@ export declare class ReplicaRegistry {
      * stripped from its frame (the rest of the frame is applied: never
      * refused whole). Written: its user's ids, and its own replica (the
      * dialed or bound one), which claims an unowned id or a fresh one, as
-     * `bind` would. A socket with no replica claims fresh ids it writes.
+     * `bind` would. A socket with no replica claims fresh ids it writes, and
+     * any socket a fresh id that binds itself to its user in the frame
+     * (`bound`: a suggestion's writer).
      * Any other id is relayed — another replica's structs, which a restore
      * from a lagging snapshot may have lost: kept, and left unowned (`''`,
      * claimable only by its own dial), when the room holds none of that id's
      * clocks and no user owns it; stripped otherwise (logged `replica`).
      * Ownership never moves to a relayer.
      */
-    attribute({ user, replica }: Attachment, writers: Set<number>, sv: Map<number, number>, orphans: Set<number>): Set<number>;
+    attribute({ user, replica }: Attachment, writers: Set<number>, sv: Map<number, number>, orphans: Set<number>, bound?: Set<number>): Set<number>;
     /**
      * Bind the sender's replicas whose `c/<n>` a frame set to another actor
      * to its verified user (`room.attribution.trust`): one room write after the frame's, which

package/dist/cloudflare/room/replicas.js

@@ -75,14 +75,16 @@ export class ReplicaRegistry {
      * stripped from its frame (the rest of the frame is applied: never
      * refused whole). Written: its user's ids, and its own replica (the
      * dialed or bound one), which claims an unowned id or a fresh one, as
-     * `bind` would. A socket with no replica claims fresh ids it writes.
+     * `bind` would. A socket with no replica claims fresh ids it writes, and
+     * any socket a fresh id that binds itself to its user in the frame
+     * (`bound`: a suggestion's writer).
      * Any other id is relayed — another replica's structs, which a restore
      * from a lagging snapshot may have lost: kept, and left unowned (`''`,
      * claimable only by its own dial), when the room holds none of that id's
      * clocks and no user owns it; stripped otherwise (logged `replica`).
      * Ownership never moves to a relayer.
      */
-    attribute({ user, replica }, writers, sv, orphans) {
+    attribute({ user, replica }, writers, sv, orphans, bound = new Set()) {
         const room = this.room;
         const claimed = [];
         const relayed = [];
@@ -93,7 +95,10 @@ export class ReplicaRegistry {
                 continue;
             const held = (sv.get(client) ?? 0) > 0;
             const fresh = owner === undefined && !held;
-            if (client === replica ? fresh || owner === '' : replica === null && fresh) {
+            // A fresh id the frame binds to its user by itself (a suggestion's writer) is the user's.
+            if (client === replica
+                ? fresh || owner === ''
+                : (replica === null || bound.has(client)) && fresh) {
                 claimed.push({ replica: client, user });
                 if (owner === '')
                     orphans.add(client);

package/dist/cloudflare/room/suggest.d.ts

@@ -0,0 +1,7 @@
+import type { YDoc } from '../../crdt/index.js';
+import type { Decoded } from './context.js';
+/** What a frame of a suggest-only socket may not write: the clients to strip, the deletes to drop. */
+export declare const suggestOnly: (doc: YDoc, { structs, ds }: Decoded, skip: Set<number>, owns: (client: number) => boolean, replica: number | null) => {
+    strip: Set<number>;
+    deletes: Decoded["ds"];
+};

package/dist/cloudflare/room/suggest.js

@@ -0,0 +1,143 @@
+/**
+ * The suggest-only rule (`room.access.suggest`, `sugg.room.suggest`): what a
+ * frame of a socket whose user may only suggest may write. Every struct must
+ * be a suggestion's, under a client id of that user that is not the socket's
+ * own replica (its writes are suggestion writers'):
+ *
+ * - a suggestion record (an attr of the root `suggest`), and what a record
+ *   of its user holds (its attrs, its writer's id lists and operations);
+ * - its own binding and profile (the attribution root: the trust rules
+ *   check them);
+ * - text in a block's backing text (an insertion; a split's boundary; a
+ *   merge's claim of a block its user made; a mark next to its user's own
+ *   text), and an atom's attrs of an atom its user made;
+ * - a block its user made (its registry entry, attrs, children's slots) and
+ *   a home slot naming such a block in any block's sequence;
+ * - a hold record naming only its user's units (deleting its own text).
+ *
+ * Anything else strips the client from the frame, as a forged mark does, and
+ * a delete of an item another user wrote is dropped. Residuals: a mark both of
+ * whose ends touch its user's text covers what lies between them, and its user
+ * may delete its own accepted text directly (the room reads no record's
+ * decisions). Pure reads of the room document and the frame.
+ */
+import { Y } from '../../crdt/engine.js';
+import { ATTRIBUTION_ROOT, BLOCK_NODE, CONTENT_NODE, INLINE_NODE, REGISTRY_KEY, SUGGEST_ROOT, TEXT_DELETES_ROOT } from '../../crdt/schema.js';
+import { isId } from './forged.js';
+import { heldClock, runsOf, storedStruct, structAt } from './updates.js';
+/** What a frame of a suggest-only socket may not write: the clients to strip, the deletes to drop. */
+export const suggestOnly = (doc, { structs, ds }, skip, owns, replica) => {
+    const frame = runsOf(structs);
+    const strip = new Set();
+    /** The struct at `id`, the room's or the frame's. */
+    const at = (id) => (storedStruct(doc, id.client, id.clock) ?? structAt(frame.get(id.client) ?? [], id.clock));
+    /**
+     * Where the item at `id` sits: its map key (`null` in a sequence) and its
+     * parent, read from the item or, for an encoded one that names neither,
+     * from an origin of it (left, else right: one sequence, or one key).
+     */
+    const placeIn = (id) => {
+        const seen = new Set();
+        for (let next = id; next !== null;) {
+            const held = storedStruct(doc, next.client, next.clock);
+            if (held)
+                return held instanceof Y.Item ? { key: held.parentSub, parent: held.parent } : null;
+            const item = structAt(frame.get(next.client) ?? [], next.clock);
+            if (!(item instanceof Y.Item) || seen.has(item))
+                return null;
+            seen.add(item);
+            if (item.parent !== null || item.parentSub !== null)
+                return { key: item.parentSub, parent: item.parent };
+            next = item.origin ?? item.rightOrigin;
+        }
+        return null;
+    };
+    /** The node (and its item) a place's parent names: a root's name, or a nested node's. */
+    const nodeOf = (parent) => {
+        if (typeof parent === 'string')
+            return { root: parent };
+        if (isId(parent)) {
+            const item = at(parent);
+            return { name: item?.content?.type?.name, item: item?.id };
+        }
+        const node = parent;
+        if (!node)
+            return {};
+        if (!node._item) {
+            const root = [...doc.share].find(([, type]) => type === parent)?.[0];
+            return { root };
+        }
+        return { name: node.name, item: node._item.id };
+    };
+    const registry = () => doc.share.get(REGISTRY_KEY)?._map;
+    /** A block `id` whose node a client of this user made (in the room or the frame). */
+    const ownBlock = (id) => {
+        if (typeof id !== 'string')
+            return false;
+        const stored = registry()?.get(id);
+        if (stored)
+            return owns(stored.id.client);
+        return structs.some((s) => s instanceof Y.Item &&
+            owns(s.id.client) &&
+            placeIn(s.id)?.key === id &&
+            nodeOf(placeIn(s.id)?.parent).root === REGISTRY_KEY);
+    };
+    const allowed = (s) => {
+        const place = placeIn(s.id);
+        if (place === null)
+            return false;
+        const parent = nodeOf(place.parent);
+        const value = s.content.getContent?.()[0];
+        if (parent.root === SUGGEST_ROOT || parent.root === ATTRIBUTION_ROOT)
+            return true;
+        if (parent.name === 'suggestion')
+            return !!parent.item && owns(parent.item.client);
+        if (parent.root === TEXT_DELETES_ROOT) {
+            const ids = s.content.ids ?? [];
+            return ids.every((v, i) => i % 3 !== 0 || owns(v));
+        }
+        if (parent.name === CONTENT_NODE) {
+            // A mark (a format item: its key and value).
+            if (s.content.key !== undefined) {
+                const { origin, rightOrigin } = s;
+                const near = [origin, rightOrigin];
+                return near.some((id) => isId(id) && owns(id.client));
+            }
+            return value?.m === undefined || ownBlock(value.m);
+        }
+        if (parent.name === INLINE_NODE)
+            return !!parent.item && owns(parent.item.client);
+        if (parent.root === REGISTRY_KEY) {
+            // A top-level home slot of its own block, or its own block's entry (never another's).
+            if (place.key === null)
+                return ownBlock(value?.b);
+            const stored = registry()?.get(place.key);
+            return !stored || owns(stored.id.client);
+        }
+        if (parent.name === BLOCK_NODE) {
+            if (s.content.priority !== undefined)
+                return false;
+            if (place.key === null && value?.b !== undefined)
+                return ownBlock(value.b);
+            return !!parent.item && owns(parent.item.client);
+        }
+        return false;
+    };
+    for (const s of structs) {
+        const { client, clock } = s.id;
+        if (!(s instanceof Y.Item) || skip.has(client) || strip.has(client))
+            continue;
+        if (storedStruct(doc, client, clock) !== null)
+            continue;
+        if (client === replica || !owns(client) || !allowed(s))
+            strip.add(client);
+    }
+    // Deletes of what another user wrote are dropped.
+    const deletes = Y.createIdSet();
+    for (const [client, ranges] of ds.clients)
+        if (!owns(client))
+            for (const { clock, len } of ranges.getIds())
+                if (clock < heldClock(doc, client))
+                    deletes.add(client, clock, len);
+    return { strip, deletes };
+};

package/dist/cloudflare/room/updates.d.ts

@@ -77,10 +77,9 @@ export declare const heldDeletes: (doc: YDoc, ds: Decoded["ds"]) => Decoded["ds"
 export declare const withoutPending: <T>(doc: YDoc, read: () => T) => T;
 /**
  * The live document as one update: its healed state — the engine
- * merged what each keystroke wrote and collected deleted content, sparing
- * the text a replica may copy again (`keepCopies`) —, without what
- * waits (`withoutPending`). Memory never runs ahead of storage, so it
- * holds exactly what the stored records hold, collected.
+ * merged what each keystroke wrote and collected deleted content —,
+ * without what waits (`withoutPending`). Memory never runs ahead of
+ * storage, so it holds exactly what the stored records hold, collected.
  */
 export declare const liveState: (doc: YDoc) => Uint8Array;
 /** A fresh room document (`prepareRoomDoc`'s collection rules). */

package/dist/cloudflare/room/updates.js

@@ -5,7 +5,7 @@
  */
 import * as encoding from 'lib0-v14/encoding';
 import { Y } from '../../crdt/engine.js';
-import { asEngineDoc, keepFromCollection, structAt as storeStructAt } from '../../crdt/structs.js';
+import { keepFromCollection, structAt as storeStructAt } from '../../crdt/structs.js';
 import { ROOM_ORIGIN } from './shared.js';
 import { crdt } from './context.js';
 export const stateVector = (doc) => Y.decodeStateVector(Y.encodeStateVector(doc));
@@ -295,19 +295,17 @@ export const withoutPending = (doc, read) => {
 };
 /**
  * The live document as one update: its healed state — the engine
- * merged what each keystroke wrote and collected deleted content, sparing
- * the text a replica may copy again (`keepCopies`) —, without what
- * waits (`withoutPending`). Memory never runs ahead of storage, so it
- * holds exactly what the stored records hold, collected.
+ * merged what each keystroke wrote and collected deleted content —,
+ * without what waits (`withoutPending`). Memory never runs ahead of
+ * storage, so it holds exactly what the stored records hold, collected.
  */
 export const liveState = (doc) => withoutPending(doc, () => Y.encodeStateAsUpdate(doc));
 /**
  * A room document's collection rules, before any update applies: it keeps
- * what an editing replica keeps, and the content the last restore
- * deleted while its undo stands (`keep`, `room.history.undo`).
+ * the content the last restore deleted while its undo stands (`keep`,
+ * `room.history.undo`).
  */
 const prepareRoomDoc = (doc, keep) => {
-    crdt.doc.keepCopies(asEngineDoc(doc));
     keepFromCollection(doc, (it) => !(keep()?.intersects(it.id.client, it.id.clock, it.length) ?? false));
 };
 /** A fresh room document (`prepareRoomDoc`'s collection rules). */

package/dist/cloudflare/routeDocumentSocket.d.ts

@@ -4,15 +4,24 @@ export type DocumentNamespace = {
         fetch(request: Request): Promise<Response>;
     };
 };
+/**
+ * What a user may do in a document: `read`; `comment` (read, and comment:
+ * the room writes a thread's anchor); `suggest` (read, comment, and write
+ * suggestions, which a writer accepts or rejects); `write` (everything,
+ * deciding suggestions included).
+ */
+export type DocumentAccessLevel = 'read' | 'comment' | 'suggest' | 'write';
 /**
  * What the host verified. `userId` owns every Yjs client id the socket
  * writes under; `replica` is the client's `doc.clientID` (read it from a
  * query parameter with {@link requestedReplica}; omitted, the socket's
- * first presence entry binds it); `readOnly` refuses every write.
+ * first presence entry binds it); `access` what the user may do (default
+ * `write`; `readOnly: true` is `access: 'read'`).
  */
 export type DocumentIdentity = {
     userId: string;
     replica?: number | null;
+    access?: DocumentAccessLevel;
     readOnly?: boolean;
     /**
      * When the credential expires, ms since the epoch (a token's `exp` ×

package/dist/cloudflare/routeDocumentSocket.js

@@ -119,13 +119,15 @@ const authorized = async (request, documentId, authorize, refuse, options) => {
         return refuse(CLOSE.expired, 'expired');
     return identity;
 };
+/** What `identity` may do: its `access`, else `read` for `readOnly`, else `write`. */
+const accessOf = (identity) => identity.access ?? (identity.readOnly ? 'read' : 'write');
 /** A refusal as an HTTP status (a probe, a history request). */
 const statusOf = (code, reason) => new Response(reason, { status: PROBE_STATUS[code] ?? 403 });
 /** The verified identity as the headers the room trusts. */
 const identityHeaders = (identity) => {
     const headers = new Headers({
         [IDENTITY_HEADERS.user]: encodeURIComponent(identity.userId),
-        [IDENTITY_HEADERS.access]: identity.readOnly ? 'read' : 'write'
+        [IDENTITY_HEADERS.access]: accessOf(identity)
     });
     const replica = identity.replica ?? null;
     if (replica !== null)
@@ -173,7 +175,7 @@ async function routeHistory(request, rooms, documentId, authorize, options) {
     const identity = await authorized(request, documentId, authorize, statusOf, options);
     if (identity instanceof Response)
         return identity;
-    if ((op === 'restore' || op === 'undo') && identity.readOnly) {
+    if ((op === 'restore' || op === 'undo') && accessOf(identity) !== 'write') {
         return new Response('read-only', { status: 403 });
     }
     const headers = identityHeaders(identity);
@@ -247,7 +249,7 @@ async function routeComments(request, rooms, documentId, authorize, options) {
     const identity = await authorized(request, documentId, authorize, statusOf, options);
     if (identity instanceof Response)
         return identity;
-    if (op === 'post' && identity.readOnly)
+    if (op === 'post' && accessOf(identity) === 'read')
         return new Response('read-only', { status: 403 });
     let body = null;
     if (op === 'post') {

package/dist/components/Content.svelte

@@ -43,7 +43,15 @@
 	const placeholder = $derived(edytor.placeholderAt(id));
 
 	/** An empty content's one text (`partsOf`: a content starts with a text). */
-	const EMPTY: Segment = { kind: 'text', key: START, text: '', runs: [] };
+	const EMPTY: Segment = {
+		kind: 'text',
+		key: START,
+		text: '',
+		runs: [],
+		segOrd: 0,
+		start: 0,
+		end: 0
+	};
 
 	/** Whether this view renders an atom of `part`'s kind (its record has a snippet). */
 	const rendersAtom = (part: AtomPart) => Boolean(edytor.inlineBlocks.get(part.type)?.snippet);

package/dist/crdt/anchors.js

@@ -1,5 +1,6 @@
-/** The children index order (`childrenIndex`): rank, then id. */
-const before = (a, b) => (a.rank === b.rank ? a.id < b.id : a.rank < b.rank);
+import { bySlot } from './placement/display.js';
+/** The children list's own order (`bySlot`): rank, then id. */
+const before = (a, b) => bySlot(a, b) < 0;
 /**
  * Where an endpoint whose block `dead` vanished lands: a displayable stop next
  * to the slot `dead` (or its topmost dead ancestor) occupied. `dead === null`

package/dist/crdt/attribution/attribution.d.ts

@@ -17,10 +17,13 @@
  *     `u/<actorId>`          → profile `{name?, color?}` — one record per
  *                              stable application actor, referenced by id.
  *
- *   Published once per attach (inside an `ATTRIBUTION_ORIGIN`
- *   transaction) and readable through `actors`/`actorOf`. These records
- *   also travel inside `encode()` output, so `loadDocument` restores the
- *   dictionary without republishing.
+ *   Published with the replica's first write: inside the first local
+ *   transaction that writes under its client id (the engine's
+ *   `beforeCommit`, fork patch YP30), so a replica that only reads writes
+ *   nothing, and every struct it writes travels with its binding. Readable
+ *   through `actors`/`actorOf`. These records also travel inside `encode()`
+ *   output, so `loadDocument` restores the dictionary without
+ *   republishing.
  *
  *   LEGACY RECORDS — documents saved by early builds carry `a/` per-edit
  *   records under the same root. They are plain replicated state, preserved
@@ -35,11 +38,14 @@ import { type BlockAttribution } from './block.js';
 /** Reserved replicated root for all attribution metadata (`SCHEMA.roots.attribution`). */
 export { ATTRIBUTION_ROOT };
 /**
- * Origin of every metadata write this module performs (`u/`/`c/`
- * dictionary publishes only — per-edit record writes are retired). Kept
- * out of undo capture; tooling classifies it as bookkeeping.
+ * Origin of the profile writes this module performs on its own
+ * (`setProfile`; the binding joins the transaction of the replica's first
+ * write, whatever its origin). Kept out of undo capture; tooling classifies
+ * it as bookkeeping.
  */
 export declare const ATTRIBUTION_ORIGIN: unique symbol;
+export declare const ACTOR_PREFIX = "u/";
+export declare const CLIENT_PREFIX = "c/";
 /** The stable application-level author identity (mirrors `DocumentActor`). */
 export type AttributionActor = {
     id: string;
@@ -57,14 +63,23 @@ export type ActorProfile = {
  * records identically and stay correct as old replicas append records.
  */
 export type DocumentAttribution = {
-    /** actorId → profile — the replicated actor dictionary (`u/` records). */
+    /**
+     * actorId → profile — the replicated actor dictionary (`u/` records): the
+     * actors whose replicas wrote, each published with its replica's first
+     * write (or `setProfile`).
+     */
     readonly actors: ReadonlyMap<string, ActorProfile>;
-    /** Resolve an item's inserting replica (clientID) to an actor id (`c/` records). */
+    /**
+     * Resolve an item's inserting replica (clientID) to an actor id (`c/`
+     * records). A replica's binding is written with its first write, so every
+     * client id that wrote a struct resolves; one that never wrote does not.
+     */
     actorOf(client: number): string | undefined;
     /**
-     * Re-publish the local actor's profile record (`u/<actorId>` — LWW).
-     * Attribution is never relabeled: historical records keep the stable
-     * actor id; only the resolvable profile changes.
+     * Re-publish the local actor's profile record (`u/<actorId>` — LWW), a
+     * write of this replica (its binding goes with it, as with any first
+     * write). Attribution is never relabeled: historical records keep the
+     * stable actor id; only the resolvable profile changes.
      */
     setProfile(profile: ActorProfile): void;
     /**
@@ -94,6 +109,13 @@ export type AttributionController = {
 type AttachOptions = {
     actor: AttributionActor;
 };
+/**
+ * The actor `doc`'s own replica writes for: its binding (`c/<clientID>`),
+ * else, before its first write, the actor its attribution controller was
+ * attached with (`undefined`: a raw doc). The provider's `saved` reads it.
+ */
+export declare const writerOf: (doc: EngineDoc) => string | undefined;
+export declare const sanitizeProfile: (value: unknown) => ActorProfile;
 /** The display profile of `actor`: its name and color, those it has. */
 export declare const profileOf: (actor: AttributionActor) => ActorProfile;
 /**