Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

type: sync doc-level keys by the field-class allowlist; comments and signatures still sync (#704)

nyblnetf5e228966521
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 80b52d7a..80db59fe 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -10296,3 +10296,53 @@ peer could have planted it over the wire while the field was still unknown-and-
applied. The new build stops syncing it, but the value already in the file is
not evidence of anything; validate or discard it on adoption rather than trust
it because it is "already there".
+
+
+## 2026-10-15 — bento/type binds its field classes to sync; comments and signatures still sync
+
+bento/type's sync shape (`type/src/sync/crdt.ts` `TYPE_SHAPE`) now binds the
+field-class map (`type/src/docclass.ts`). Doc-level keys therefore sync by the
+kernel's allowlist: only content keys, `maps`, and the history keys named in
+`syncHistory` are emitted. An undeclared key is applied but never re-emitted.
+
+Two history keys are named, `comments` and `signatures`. They sync as whole
+registers, exactly as before binding.
+
+- **`comments`** — a maintainer ruling (2026-10-15): comments sync live to
+ everyone in the room, readers included. Keeping them a whole `comments`
+ register makes the wire byte-identical to 1.2.7's, so a room mixing builds
+ converges. Moving them into `maps` for per-thread merging is NOT
+ mixed-version safe: a 1.2.7 peer writes the per-key ops as literal top-level
+ `comments.<id>` keys and loses the threads. That needs its own version-gated
+ migration, if it is ever wanted.
+- **`signatures`** — not a ruling. It preserves today's behaviour. Signatures
+ are classed 'history' only as an interim: they are dropped from view-only
+ copies until signing commits to the history rather than containing it (the
+ maintainer's 2026-10-15 ruling (3), which makes them content again). Before
+ binding they synced like any other key, and binding with `comments` alone
+ would silently have stopped a signature reaching the other people in the
+ room. When they return to 'content', `historySyncKeys` rejects them in
+ `syncHistory` AT COMPILE TIME, so that change is forced to remove them.
+
+`revisions` never syncs. Each replica keeps its own timeline, and it is in
+`skipDoc`.
+
+The 2026-10-11 residual (a key newly protected after being unknown-and-applied
+must have its existing value treated as untrusted) does not arise here. Every
+non-content type field is either in `skipDoc` and never synced (identity,
+modes, capability, revisions) or still named in `syncHistory`. Binding protects
+no field that synced before.
+
+Verified in `scripts/test-sync-type.ts`, against type's engine and a peer built
+from 1.2.7's exact shape:
+- comments and signatures are emitted, revisions and an undeclared key are not;
+- comments cross both ways between the two builds as one register;
+- the bound peer's silence on an undeclared key is not a delete.
+
+Mutations, all red by exit code:
+- unbinding the map;
+- dropping either key from `syncHistory`;
+- moving comments into `maps`.
+
+Naming a content key, an identity key, or a misspelled key in `syncHistory`
+fails tsc.
diff --git a/scripts/test-sync-type.ts b/scripts/test-sync-type.ts
index 21b009eb..be4b026a 100644
--- a/scripts/test-sync-type.ts
+++ b/scripts/test-sync-type.ts
@@ -29,7 +29,8 @@
// The engine is the kernel's, bound to ('body', null, 'text'). Nothing here is
// type app code beyond the binding and the model's own helpers.
-import { SyncEngine } from '../kernel/src/sync/crdt.ts';
+import { SyncEngine, shape, DOC_NODE } from '../kernel/src/sync/crdt.ts';
+import { emptyDoc } from '../type/src/model.ts';
import { mulberry32, baseDoc, randomMutation, type Doc } from './lib/sync-fixtures-type.ts';
import { parseDoc, spliceText, type Block } from '../type/src/model.ts';
@@ -303,5 +304,87 @@ console.log('\n=== what that looks like on one paragraph ===');
console.log(` held the correct offset, so no register winner could have been right.`);
}
+
+// ════════════════════════════════════════════════════════════════════════════
+// DOC-LEVEL KEYS SYNC BY ALLOWLIST (TYPE_SHAPE is bound to TYPE_FIELDS).
+//
+// Before binding, every doc key outside skipDoc synced. Now only content keys,
+// `maps`, and the history keys named in syncHistory are emitted. comments syncs
+// to everyone (maintainer ruling 2026-10-15); signatures keeps syncing because
+// it always has. The 1.2.7 peer below is the SAME shape() call minus the class
+// map and syncHistory — what 1.2.7 shipped — so the mixed-version rows are the
+// real wire question, not a stand-in for it.
+{
+ const OLD_SHAPE = shape('body', null, 'text', ['footnotes']);
+ class OldSync extends SyncEngine { constructor(a: string) { super(a, OLD_SHAPE); } }
+ const H = (t: string) => console.log(`\n ${t}`);
+ const clone = <T,>(x: T): T => JSON.parse(JSON.stringify(x));
+ const mk = (): Record<string, unknown> => {
+ const d = emptyDoc() as unknown as Record<string, unknown>;
+ d.body = [{ id: 'p1', kind: 'para', text: 'Payment within 60 days.' }];
+ return d;
+ };
+ // doc-level keys a diff EMITS: set ops with no element and no slide
+ const docKeys = (ops: unknown[]): string[] => (ops as Array<{ op: string; el?: string; sl?: string; k: string }>)
+ .filter(o => o.op === 'set' && !o.el && !o.sl).map(o => o.k);
+ const COMMENT = { c1: { id: 'c1', text: 'check clause 4', author: 'Bob', at: 'x', replies: [],
+ anchor: { block: 'p1', from: 0, to: 7 } } };
+ const SIG = [{ alg: 'ES256', pub: 'P', name: 'Alice', content: 'C', prev: '', sig: 'S' }];
+
+ H('with the map bound, what a type replica emits');
+ {
+ const A = new TypeSync('a'); const B = new TypeSync('b');
+ const dA = mk(); const dB = mk(); A.adopt(dA as never); B.adopt(dB as never);
+ const before = clone(dA);
+ dA.comments = COMMENT; dA.signatures = SIG;
+ dA.revisions = [{ id: 'r1', at: 'x', label: 'Revision 1', body: [] }];
+ dA.mystery = 'UNDECLARED';
+ const ops = A.diff(before as never, dA as never, { text: true });
+ const keys = docKeys(ops);
+ ok(keys.includes('comments'), 'comments IS emitted — synced to the room (ruling 2026-10-15)');
+ ok(keys.includes('signatures'), 'signatures IS emitted — as before binding');
+ ok(!keys.includes('revisions'), 'revisions is NOT emitted — each replica keeps its own timeline');
+ ok(!keys.some(k => k === 'mystery' || k.startsWith('mystery.')),
+ 'an UNDECLARED key is NOT emitted — the allowlist, not the denylist');
+ const hist = ['revisions', 'comments', 'signatures'];
+ ok(keys.filter(k => hist.includes(k.split('.')[0])).every(k => k === 'comments' || k === 'signatures'),
+ 'no history key other than comments and signatures leaves this replica');
+ B.apply(dB as never, ops);
+ ok(JSON.stringify(dB.comments) === JSON.stringify(COMMENT), 'a bound peer receives the comment');
+ ok(JSON.stringify(dB.signatures) === JSON.stringify(SIG), 'and the signature');
+ ok(dB.revisions === undefined || (dB.revisions as unknown[]).length === 0, 'and not the revisions');
+ }
+
+ H('MIXED VERSION: a bound replica and a 1.2.7-shaped replica');
+ {
+ // new → old
+ const N = new TypeSync('new'); const O = new OldSync('old');
+ const dN = mk(); const dO = mk(); N.adopt(dN as never); O.adopt(dO as never);
+ let before = clone(dN);
+ dN.comments = COMMENT;
+ const nops = N.diff(before as never, dN as never, { text: true });
+ ok(docKeys(nops).includes('comments') && !docKeys(nops).some(k => k.startsWith('comments.')),
+ 'comments goes on the wire as ONE `comments` register — 1.2.7\'s shape, not per-key');
+ O.apply(dO as never, nops);
+ ok(JSON.stringify(dO.comments) === JSON.stringify(COMMENT), 'a 1.2.7 peer receives a comment from a bound peer');
+ ok(!Object.keys(dO).some(k => k.startsWith('comments.')), 'and writes no dotted junk key into its document');
+
+ // old → new
+ const N2 = new TypeSync('new2'); const O2 = new OldSync('old2');
+ const dN2 = mk(); const dO2 = mk(); N2.adopt(dN2 as never); O2.adopt(dO2 as never);
+ before = clone(dO2);
+ dO2.comments = COMMENT; dO2.mystery = 'from old';
+ N2.apply(dN2 as never, O2.diff(before as never, dO2 as never, { text: true }));
+ ok(JSON.stringify(dN2.comments) === JSON.stringify(COMMENT), 'a bound peer receives a comment from a 1.2.7 peer');
+ ok(dN2.mystery === 'from old', 'an undeclared key from the old peer is applied');
+ // The bound peer holds `mystery` but never emits it; merging its state back
+ // into the old peer must not DELETE the old peer's copy.
+ O2.mergeSnapshot(dO2 as never, N2.outboundDoc(clone(dN2)) as never, N2.toJSON() as never);
+ ok(dO2.mystery === 'from old', 'the bound peer\'s silence on an undeclared key is not a delete');
+ ok(JSON.stringify(dO2.comments) === JSON.stringify(COMMENT), 'and the comment survives the round trip');
+ }
+ void DOC_NODE;
+}
+
console.log(`\n${checks - failures}/${checks} checks passed`);
if (failures) process.exit(1);
diff --git a/type/src/sync/crdt.ts b/type/src/sync/crdt.ts
index 405ccca8..aacefd75 100644
--- a/type/src/sync/crdt.ts
+++ b/type/src/sync/crdt.ts
@@ -13,7 +13,8 @@
export * from '../../../kernel/src/sync/crdt.ts';
-import { SyncEngine, shape } from '../../../kernel/src/sync/crdt.ts';
+import { SyncEngine, shape, historySyncKeys } from '../../../kernel/src/sync/crdt.ts';
+import { TYPE_FIELDS } from '../docclass.ts';
import type { DocShape } from '../../../kernel/src/sync/crdt.ts';
/**
@@ -53,7 +54,29 @@ import type { DocShape } from '../../../kernel/src/sync/crdt.ts';
* declared: 34 of 120 fuzz seeds converged on a document with a dangling note.
* Per-key, as `assets` and `blobs` have always been, both survive.
*/
-export const TYPE_SHAPE: DocShape = shape('body', null, 'text', ['footnotes']);
+/**
+ * Doc-level keys sync by ALLOWLIST: the field-class map (docclass.ts) is bound,
+ * so this replica emits only content keys (plus `maps`), refuses non-content
+ * keys inbound whatever the sender claims, and never re-emits a key it does not
+ * declare. skipDoc stays the floor in both directions.
+ *
+ * The history keys that still sync, as whole registers:
+ * comments Maintainer ruling 2026-10-15: comments sync live to everyone
+ * in the room, readers included, as they did before binding.
+ * Still a whole `comments` register, so the wire is byte-
+ * identical to 1.2.7's and a mixed-version room converges.
+ * signatures NOT a ruling — this preserves today's behaviour. Signatures
+ * are 'history' only as an interim (they leave view-only copies
+ * until signing commits to the history rather than containing
+ * it); before binding they synced like any other key. Once they
+ * return to 'content', historySyncKeys refuses them here at
+ * COMPILE time, so this line cannot be forgotten.
+ * `revisions` never syncs: each replica keeps its own timeline (skipDoc).
+ */
+const SYNC_HISTORY = ['comments', 'signatures'] as const;
+
+export const TYPE_SHAPE: DocShape = shape('body', null, 'text', ['footnotes'],
+ TYPE_FIELDS, historySyncKeys(TYPE_FIELDS, SYNC_HISTORY));
/** The engine bound to bento/type. */
export class SyncState extends SyncEngine {