Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
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.mdindex 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 isnot evidence of anything; validate or discard it on adoption rather than trustit 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.tsindex 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.tsindex 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 {