Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
kernel/sync: a sync override for a history-class doc key (syncHistory) (#687)
nyblnetd043b0cdc87f
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex bcfa11da..76f4eac8 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -2284,6 +2284,16 @@ jobs:# the shipped denylist. skipDoc is the floor under both.run: node scripts/test-sync-allowlist.ts+ - name: Sync override for a history-class key (shape().syncHistory)+ # A field's copy class and its sync decision can diverge: type classes+ # `comments` history (dropped from reader/export copies) but comments+ # must still flow live. syncHistory names such a key — emitted and+ # accepted though non-content, with its 1.2.7 wire shape unchanged so a+ # bound build stays mixed-version-compatible with an unbound one.+ # Restricted to history-class keys at runtime (shape throws) and at+ # compile time (historySyncKeys); skipDoc is still the floor.+ run: node scripts/test-sync-history-override.ts+- name: Slides sync allowlist rig# Slides binds its field-class map (slides/src/docclass.ts) into# SLIDES_SHAPE: every key that synced before is still content, adiff --git a/kernel/src/sync/crdt.ts b/kernel/src/sync/crdt.tsindex a7406e28..64190b98 100644--- a/kernel/src/sync/crdt.ts+++ b/kernel/src/sync/crdt.ts@@ -43,7 +43,7 @@* this and nothing more: a container of parented nodes, each with an `id`,* under two keys named by the DocShape below. Every app's model satisfies it.*/-import type { FieldClass } from '../docfields.ts'+import type { FieldClass, FieldsOfClass } from '../docfields.ts'type BentoDoc = objecttype Slide = { id: string }@@ -149,6 +149,25 @@ export interface DocShape {* are never emitted and never applied in either mode.*/readonly classes?: Readonly<Record<string, FieldClass>>+ /**+ * HISTORY-class doc keys that nonetheless SYNC, as whole-value registers. The+ * allowlist decides sync by `classes`, but a field's copy class and its sync+ * decision can diverge: bento/type classes `comments` as history so reader and+ * export copies drop them (the #663 copy ruling), yet comments must still flow+ * between live collaborators. Naming such a key here emits and accepts it+ * though it is non-content — WITHOUT changing its wire shape, so a build that+ * binds a class map stays mixed-version-compatible with one that does not+ * (both see the same whole `#doc <key>` register).+ *+ * RESTRICTED to history-class keys, two ways: `shape()` throws at runtime if a+ * named key is not classed 'history' (or there is no class map), and the typed+ * `historySyncKeys` helper makes naming an identity / mode / capability /+ * unclassified key a compile error. So this can never become a path around the+ * floor: skipDoc is still checked FIRST in both gates, and an identity, mode or+ * capability key can never be listed here at all. For per-key id-maps use+ * `maps` instead (that one changes the wire shape).+ */+ readonly syncHistory: ReadonlySet<string>}/** Derived, never authored: the volatile set is the same for every app apart@@ -159,6 +178,7 @@ export const shape = (text = 'html',maps: readonly string[] = [],classes?: Readonly<Record<string, FieldClass>>,+ syncHistory: readonly string[] = [],): DocShape => {// file-local, never synced — each replica keeps its own timeline. (When an app// passes `classes`, PR2 ALSO refuses any non-content / unknown doc key inbound@@ -173,10 +193,41 @@ export const shape = (const skipDoc = new Set([parents, 'modified', 'collab', 'format', 'version', 'policy', 'revisions', 'trail', 'docId', 'readonly', 'template'])// `assets` and `blobs` are per-key for every app and always have been —// unioned rather than defaulted so an app naming its own map cannot drop them.- const out: DocShape = { parents, children, text, skipDoc, maps: new Set(['assets', 'blobs', ...maps]) }+ // syncHistory may name ONLY history-class keys — the runtime half of the+ // restriction (the typed helper is the compile half). A key not classed+ // 'history', or named with no class map at all, is refused here so it can+ // never widen what syncs beyond a history field an app chose to share.+ // BELT AND BRACES: also refuse a key that is in skipDoc. The class check+ // trusts the app's own map, and nothing pins collab/revisions to their class —+ // an app that MIS-classes a never-synced key as 'history' and names it here+ // would pass the class check, leaving only the gate ORDER (skipDoc first) to+ // protect it. Refusing skipDoc ∩ syncHistory at bind time makes a never-synced+ // field safe regardless of gate order: it can't be named at all.+ for (const k of syncHistory) {+ if (skipDoc.has(k)) {+ throw new Error(`DocShape.syncHistory names "${k}", which is in the never-synced set (skipDoc); a floor field can never be shared, whatever its class`)+ }+ if (!classes || classes[k] !== 'history') {+ throw new Error(`DocShape.syncHistory names "${k}", which is ${classes ? `classed ${classes[k] ?? 'nothing'}` : 'bound with no class map'}; only history-class keys may sync this way`)+ }+ }+ const out: DocShape = { parents, children, text, skipDoc, maps: new Set(['assets', 'blobs', ...maps]), syncHistory: new Set(syncHistory) }return classes ? { ...out, classes } : out}+/** Build the `syncHistory` list for `shape()` with a COMPILE-TIME guarantee+ * that every key is history-class in `classes`. `FieldsOfClass<M,'history'>` is+ * the union of M's history keys, so naming an identity / mode / capability or+ * unclassified key is a type error here — the compile half of the restriction+ * that `shape()` also enforces at runtime. Usage:+ * shape('body', null, 'text', ['footnotes'], TYPE_FIELDS,+ * historySyncKeys(TYPE_FIELDS, ['comments'])) */+export function historySyncKeys<M extends Record<string, FieldClass>>(+ _classes: M, keys: readonly FieldsOfClass<M, 'history'>[],+): readonly string[] {+ return keys as readonly string[]+}+/** The parent array of a document, and the child array of a parent. Indexed* access through the descriptor: `d['slides']` is the same lookup `d.slides`* was, so these are byte-neutral by construction. */@@ -601,8 +652,9 @@ export class SyncEngine {* name) on any path it mints? Content-class keys and per-key maps only; never* a skipDoc key, a known non-content key, or an UNKNOWN key. */outboundDocKey(k: string): boolean {- if (this.S.skipDoc.has(k)) return false+ if (this.S.skipDoc.has(k)) return false // floor first — syncHistory can't reach itif (this.S.maps.has(k)) return true+ if (this.S.syncHistory.has(k)) return true // a history key the app chose to sharereturn !this.S.classes || this.S.classes[k] === 'content'}@@ -615,8 +667,9 @@ export class SyncEngine {* knows as non-content; for an unknown key, per APPLY_UNKNOWN_DOC_KEYS. With* no class map this is exactly the shipped skipDoc refusal. */private ignoreInboundDocKey(k: string): boolean {- if (this.S.skipDoc.has(k)) return true+ if (this.S.skipDoc.has(k)) return true // floor first — syncHistory can't reach itif (this.S.maps.has(k) || !this.S.classes) return false+ if (this.S.syncHistory.has(k)) return false // a history key the app chose to shareconst c = this.S.classes[k]if (c === undefined) return !APPLY_UNKNOWN_DOC_KEYSreturn c !== 'content'diff --git a/scripts/test-sync-history-override.ts b/scripts/test-sync-history-override.tsnew file mode 100644index 00000000..0324fefb--- /dev/null+++ b/scripts/test-sync-history-override.ts@@ -0,0 +1,165 @@+#!/usr/bin/env node+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+// Sync override: a history-class doc key that still syncs (shape().syncHistory).+//+// node scripts/test-sync-history-override.ts+//+// The doc-level allowlist (#683) syncs by copy-class: only `content` keys flow.+// But a field's copy class and its sync decision can diverge. bento/type classes+// `comments` as `history` so reader and export copies drop them, yet comments+// must still flow between live collaborators. `shape().syncHistory` names such a+// key: it emits and accepts though non-content, WITHOUT changing the wire shape+// (still a whole `#doc <key>` register), so a build that binds a class map stays+// mixed-version-compatible with one that does not.+//+// The restriction, both halves: syncHistory may name ONLY history-class keys.+// `shape()` throws at RUNTIME otherwise (the rows below, run in CI), and+// `historySyncKeys` makes naming an identity / mode / capability / unclassified+// key a COMPILE error — enforced at every app call site under tsc (type's opt-in+// build fails if it lists a non-history key), and shown by the type-only lines+// at the end of this file (scripts aren't type-checked in CI, so those document+// and locally verify the constraint; the runtime rows are the CI guarantee).+// skipDoc is still checked FIRST, so this can never reopen a never-synced field.+//+// Mutations (edit kernel/src/sync/crdt.ts, re-run — each turns a row red):+// - outboundDocKey, drop `syncHistory.has(k) → true` : comments stop being emitted+// - ignoreInboundDocKey, drop `syncHistory.has(k) → false`: comments refused inbound+// - shape(), drop the history-class throw : runtime-refusal rows red+// - shape(), drop the skipDoc-in-syncHistory throw : the bind-time floor rows red+// - outboundDocKey, move syncHistory ABOVE the skipDoc check : the gate-order floor rows red+// - historySyncKeys, loosen the key type : the @ts-expect-error lines fail tsc++import { SyncEngine, shape, historySyncKeys } from '../slides/src/sync/crdt.ts'+import type { DocShape } from '../slides/src/sync/crdt.ts'+import type { FieldClass } from '../kernel/src/docfields.ts'++let failures = 0, checks = 0+const ok = (c: boolean, m: string) => { checks++; if (!c) { failures++; console.log(` FAIL ${m}`) } else console.log(` ok ${m}`) }+const H = (s: string) => console.log(`\n=== ${s} ===`)+const clone = <T>(x: T): T => JSON.parse(JSON.stringify(x))+type Rec = Record<string, unknown>++// A type-like class map. `comments` is history (the #663 copy ruling), and so is+// `revisions`; `signatures` is content; identity/mode/capability as usual.+const TFIELDS = {+ title: 'content', body: 'content', comments: 'history', revisions: 'history',+ signatures: 'content', docId: 'identity', collab: 'capability',+ readonly: 'mode', template: 'mode',+} satisfies Record<string, FieldClass>++// NEW build: binds the map AND shares comments.+const SHARED: DocShape = shape('body', null, 'text', [], TFIELDS, historySyncKeys(TFIELDS, ['comments']))+// bound but does NOT share comments (the control).+const BOUND: DocShape = shape('body', null, 'text', [], TFIELDS)+// a 1.2.7-shaped peer: no class map at all, comments is just a plain register.+const OLD: DocShape = shape('body', null, 'text')+class Shared extends SyncEngine { constructor(a: string) { super(a, SHARED) } }+class Bound extends SyncEngine { constructor(a: string) { super(a, BOUND) } }+class Old extends SyncEngine { constructor(a: string) { super(a, OLD) } }++const doc = (over: Rec = {}): Rec => ({+ format: 'bento/type', version: 1, docId: 'd-mine', title: 't',+ body: [{ id: 'b1', text: 'hi' }], comments: {} as Rec, ...over,+})+const docSets = (ops: Array<Rec>) =>+ ops.filter(o => o.op === 'set' && o.el === undefined && o.sl === undefined).map(o => String(o.k))++// a peer's ops for a doc change, from a distinct actor each call+let n = 0+const opsFrom = (Engine: new (a: string) => SyncEngine, change: Rec): Array<Rec> => {+ const P = new Engine(`peer${n++}`); const d = doc(); P.adopt(d as never)+ const before = clone(d); Object.assign(d, change)+ return P.diff(before, d as never, { text: true }) as never+}++H('with the override, a history key (comments) is emitted and accepted')+{+ const A = new Shared('a'); const d = doc(); A.adopt(d as never)+ const before = clone(d); (d.comments as Rec).T1 = { text: 'hello' }+ const emitted = docSets(A.diff(before, d as never, { text: true }) as never)+ ok(emitted.includes('comments'), 'a diff EMITS comments though it is history-class')+ ok(emitted.every(k => !k.includes('.')), 'and as a WHOLE register (no dotted key — wire shape unchanged)')+ const B = new Shared('b'); const bd = doc(); B.adopt(bd as never)+ B.apply(bd as never, opsFrom(Shared, { comments: { T9: { text: 'hi' } } }) as never)+ ok(JSON.stringify((bd.comments as Rec).T9) === JSON.stringify({ text: 'hi' }), 'and a peer\'s comments are APPLIED inbound')+}++H('without the override, the same history key does NOT sync')+{+ const A = new Bound('a'); const d = doc(); A.adopt(d as never)+ const before = clone(d); (d.comments as Rec).T1 = { text: 'hello' }+ ok(!docSets(A.diff(before, d as never, { text: true }) as never).includes('comments'),+ 'a bound build that does not share comments never emits them')+ const B = new Bound('b'); const bd = doc(); B.adopt(bd as never)+ B.apply(bd as never, opsFrom(Old, { comments: { T9: { text: 'hi' } } }) as never)+ ok((bd.comments as Rec).T9 === undefined, 'and refuses comments inbound')+}++H('MIXED VERSION: a shared-build peer and a 1.2.7 peer see the same comments')+{+ // NEW -> OLD+ const NEW = new Shared('new'); const OLDP = new Old('old')+ const dN = doc(); const dO = doc(); NEW.adopt(dN as never); OLDP.adopt(dO as never)+ const bN = clone(dN); (dN.comments as Rec).T1 = { text: 'from new' }+ const opsN = NEW.diff(bN, dN as never, { text: true })+ ok(docSets(opsN as never).includes('comments') && docSets(opsN as never).every(k => !k.includes('.')),+ 'the shared build emits comments as a whole register — the 1.2.7 wire')+ OLDP.apply(dO as never, opsN as never)+ ok(JSON.stringify((dO.comments as Rec).T1) === JSON.stringify({ text: 'from new' }), 'the 1.2.7 peer receives it (no stray dotted key)')+ ok(Object.keys(dO).every(k => !k.includes('.')), 'and no "comments.T1" literal key was created')+ // OLD -> NEW+ const bO = clone(dO); (dO.comments as Rec).T2 = { text: 'from old' }+ NEW.apply(dN as never, OLDP.diff(bO, dO as never, { text: true }) as never)+ ok(JSON.stringify((dN.comments as Rec).T2) === JSON.stringify({ text: 'from old' }), 'and the shared build receives the 1.2.7 peer\'s comments')+}++H('the skipDoc floor is checked first at the gate too (defence in depth)')+{+ // shape() refuses a skipDoc key in syncHistory at bind time (below). But the+ // gate is the second line: even a FORGED shape that got a skipDoc key past the+ // bind guard must still be refused, because skipDoc is checked FIRST in both+ // gates. Force `revisions` in past the guard and prove the gate holds. (This+ // is the row security's "override above the floor" gate-order mutation reds.)+ const FORGED: DocShape = shape('body', null, 'text', [], TFIELDS)+ ;(FORGED.syncHistory as Set<string>).add('revisions')+ class Forged extends SyncEngine { constructor(a: string) { super(a, FORGED) } }+ const A = new Forged('a'); const d = doc({ revisions: [{ id: 'r1' }] }); A.adopt(d as never)+ const before = clone(d); (d.revisions as unknown[]).push({ id: 'r2' })+ ok(!docSets(A.diff(before, d as never, { text: true }) as never).includes('revisions'),+ 'a skipDoc key forced into syncHistory is still never emitted (gate order)')+ const B = new Forged('b'); const bd = doc(); B.adopt(bd as never)+ B.apply(bd as never, [{ op: 'set', k: 'revisions', v: [{ id: 'EVIL' }], a: 'evil', s: 1, l: 9000 }] as never)+ ok((bd as Rec).revisions === undefined, 'and is still refused inbound (gate order)')+}++H('syncHistory may name ONLY history-class keys — runtime refusal')+{+ const throws = (fn: () => void) => { try { fn(); return false } catch { return true } }+ ok(throws(() => shape('body', null, 'text', [], TFIELDS, ['collab'])), 'a capability key is refused')+ ok(throws(() => shape('body', null, 'text', [], TFIELDS, ['docId'])), 'an identity key is refused')+ ok(throws(() => shape('body', null, 'text', [], TFIELDS, ['readonly'])), 'a mode key is refused')+ ok(throws(() => shape('body', null, 'text', [], TFIELDS, ['nope'])), 'an unclassified key is refused')+ ok(throws(() => shape('body', null, 'text', [], undefined, ['comments'])), 'naming a key with no class map is refused')+ // belt and braces: a skipDoc key is refused at bind time regardless of its+ // class — the guard must not trust the app's map to keep a floor field out.+ ok(throws(() => shape('body', null, 'text', [], TFIELDS, ['revisions'])),+ 'a skipDoc key (revisions) is refused at bind time though it is history-class')+ const MISCLASSED = { ...TFIELDS, collab: 'history' } satisfies Record<string, FieldClass>+ ok(throws(() => shape('body', null, 'text', [], MISCLASSED, ['collab'])),+ 'a skipDoc key MIS-classed history + named is refused — the floor does not trust the class map')+ ok(!throws(() => shape('body', null, 'text', [], TFIELDS, ['comments'])), 'a history key is accepted')+}++// COMPILE-TIME half: these must each be a type error, or tsc fails on the unused+// directive. (Runtime no-ops; the assertion is that the file type-checks.)+// @ts-expect-error collab is capability, not history+historySyncKeys(TFIELDS, ['collab'])+// @ts-expect-error docId is identity, not history+historySyncKeys(TFIELDS, ['docId'])+// @ts-expect-error not a key of the map+historySyncKeys(TFIELDS, ['nope'])+ok(true, 'the @ts-expect-error lines above hold the compile-time restriction (checked by tsc)')++console.log(`\n${checks - failures}/${checks} checks passed`)+process.exit(failures ? 1 : 0)