Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
docfields: whole-document restore for the version-history module (applyRestore) (#701)
nyblnetb75f073b5a6b
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 760728ad..6013eb52 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -118,6 +118,14 @@ jobs:- name: Field-classification rigrun: node scripts/test-field-class.ts+ - name: Whole-document restore rig (undo / version restore / crash recovery)+ # applyRestore decides per field from its class, with per-field overrides,+ # and the restore DIRECTION matters: a version restore ('back') keeps a+ # live field; crash recovery ('recover') reconciles a live history field+ # with the newer snapshot. Recover hooks (newestListWins for unsigned+ # lists) vs the default (signed-safe). Absent never wipes on recover.+ run: node scripts/test-restore.ts+- name: Typecheck convert (standalone)# convert/ is a library beside the apps (the CLI and bento.page/import# use it; no shell does), so no app's tsc -b reaches it. Its own flags,diff --git a/kernel/src/docfields.ts b/kernel/src/docfields.tsindex 5801f3a5..1945313f 100644--- a/kernel/src/docfields.ts+++ b/kernel/src/docfields.ts@@ -36,6 +36,165 @@ export function keepLiveIdentity(restored: Obj, live: Obj): void {}}+// --- whole-document restore: undo / redo / version restore / crash recovery ---+// The class-driven generalisation of keepLiveIdentity. keepLiveIdentity pins a+// hard-coded identity list live; applyRestore decides PER FIELD from its class,+// with per-field overrides, because a field's COPY class and its RESTORE+// behaviour can diverge (type's comments are class 'history' for copy reasons+// but must be undoable/restorable). It is additive: apps keep keepLiveIdentity+// until they adopt this.++/** How a field behaves under undo/redo and whole-document restore.+ * - 'follows': take the restored / incoming value, like ordinary content.+ * - 'live': keep the LIVE value; the restored value is ignored. */+export type KeepLive = 'live' | 'follows'++/** Default by class: content (and an unknown field) FOLLOWS; identity,+ * capability, mode and history stay LIVE — a restore never rolls back identity+ * or modes, and history is file-local bookkeeping a version restore must not+ * discard. Apps override per field (type's comments → 'follows'). */+export function defaultKeepLive(cls: FieldClass | undefined): KeepLive {+ return cls === undefined || cls === 'content' ? 'follows' : 'live'+}++/** Which way a restore goes.+ * - 'back': undo/redo and version restore — going BACK in time. A 'live'+ * field keeps the live value (identity and history don't roll back).+ * - 'recover': crash recovery — `incoming` is a NEWER copy of THIS document.+ * A 'live' HISTORY field is reconciled with it (a revision made+ * just before the crash must survive), the rest still keep live. */+export type RestoreDirection = 'back' | 'recover'++/** A per-field recover hook: given the live value, the incoming value and the+ * two whole-doc times, return the value to keep. Consulted ONLY for a 'live'+ * history field under 'recover', and ONLY when `incoming` HAS the field — a key+ * absent from the snapshot keeps the live value before any hook runs, so a hook+ * never sees `incoming === undefined`.+ *+ * `at` is EPOCH MILLISECONDS on both sides, which the CALLER normalises so a+ * hook never compares a number against a string: `live` = the live doc's+ * modified time as ms (`Date.parse(doc.modified)`), `incoming` = the snapshot's+ * own time (already ms). Either is `undefined` when unknown — an old file with+ * no `modified` gives `live: undefined`, which a hook should treat as OLDER. */+export type RecoverHook = (+ live: unknown, incoming: unknown, at: { live?: number; incoming?: number },+) => unknown++export interface RestoreRules {+ readonly classes: Record<string, FieldClass>+ /** Per-field keep-live override, beside the class default (e.g. comments+ * 'follows' though class history). */+ readonly keepLive?: Readonly<Record<string, KeepLive>>+ /** Per-field recover hook — used only for a 'live' history field on 'recover'.+ * A field with no hook follows incoming when present, keeps live when absent. */+ readonly recover?: Readonly<Record<string, RecoverHook>>+}++/** Resolve a whole-document restore and return the doc to INSTALL.+ * Over the union of live + incoming keys:+ * - a 'follows' field takes `incoming` ('back': absent means dropped; 'recover':+ * an absent key never wipes a live value — a snapshot may be a projection);+ * - a 'live' field keeps the live value, EXCEPT a 'live' history field on+ * 'recover', which uses its recover hook, or (no hook) follows incoming when+ * present and keeps live when absent.+ * `at` carries the whole-doc timestamps (live.modified vs the snapshot's time),+ * passed to recover hooks; it is not otherwise inspected here. */+/** Keys that address an object's PROTOTYPE. A recovery snapshot is foreign input+ * (JSON from a shared-origin IndexedDB on file://), and `JSON.parse` gives it an+ * OWN `__proto__` key — then `out[k] = I[k]` would swap the restored doc's+ * prototype (a `readonly` getter could read true). Never processed. */+const PROTO_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype'])++/** Classes whose keepLive is ALWAYS 'live' — a restore may never adopt a+ * snapshot's identity, modes or capabilities (its room, docId, lock). A+ * keepLive override naming one is ignored here and refused by+ * validateRestoreRules / restoreOverrides. */+const FLOOR_CLASSES: ReadonlySet<FieldClass> = new Set(['identity', 'mode', 'capability'])++/** Own-property read — a null-prototype class map must not fall through to+ * Object.prototype (where `classes['constructor']` would read a function). */+const ownGet = <V>(o: Record<string, V> | undefined, k: string): V | undefined =>+ o && Object.hasOwn(o, k) ? o[k] : undefined++export function applyRestore<T extends object>(+ live: T, incoming: T, direction: RestoreDirection, rules: RestoreRules,+ at: { live?: number; incoming?: number } = {},+): T {+ const L = live as Obj, I = incoming as Obj+ const out: Obj = {}+ for (const k of new Set([...Object.keys(L), ...Object.keys(I)])) {+ if (PROTO_KEYS.has(k)) continue // never assign a prototype key from an untrusted snapshot+ const cls = ownGet(rules.classes, k)+ // The floor: identity / mode / capability ALWAYS keep live; a keepLive+ // override is honoured only for content / history / unknown.+ const override = cls && FLOOR_CLASSES.has(cls) ? undefined : ownGet(rules.keepLive, k)+ const kl = override ?? defaultKeepLive(cls)+ if (kl === 'follows') {+ if (I[k] !== undefined) out[k] = I[k]+ else if (direction === 'recover' && L[k] !== undefined) out[k] = L[k] // absent never wipes on recover+ continue+ }+ // 'live'+ if (direction === 'recover' && cls === 'history') {+ // A missing key keeps live BEFORE any hook runs — so absent-never-wipes+ // does not depend on each hook remembering it, and a hook never sees an+ // undefined incoming.+ const hook = I[k] !== undefined ? ownGet(rules.recover, k) : undefined+ if (hook) { const v = hook(L[k], I[k], at); if (v !== undefined) out[k] = v; continue }+ if (I[k] !== undefined) out[k] = I[k]+ else if (L[k] !== undefined) out[k] = L[k] // absent never wipes a history field on recover+ continue+ }+ if (L[k] !== undefined) out[k] = L[k]+ }+ return out as T+}++/** Throw if a keepLive override names an identity / mode / capability field with+ * anything but 'live' — the override floor, checked once when rules are built+ * (the compile-time half is `restoreOverrides`). applyRestore also enforces it,+ * so a slipped override is SAFE, not merely caught. */+export function validateRestoreRules(rules: RestoreRules): void {+ const kl = rules.keepLive+ if (!kl) return+ for (const k of Object.keys(kl)) {+ if (PROTO_KEYS.has(k)) continue+ const cls = ownGet(rules.classes, k)+ if (cls && FLOOR_CLASSES.has(cls) && ownGet(kl, k) !== 'live') {+ throw new Error(`keepLive override for "${k}" (class ${cls}) must be 'live' — identity, mode and capability fields never follow a restore`)+ }+ }+}++/** Build a keepLive override map with a COMPILE-TIME guarantee that only content+ * or history fields are named — naming an identity / mode / capability field is+ * a type error (the override floor's compile half; applyRestore and+ * validateRestoreRules enforce it at runtime). */+export function restoreOverrides<M extends Record<string, FieldClass>>(+ _classes: M,+ overrides: Partial<Record<FieldsOfClass<M, 'content'> | FieldsOfClass<M, 'history'>, KeepLive>>,+): Record<string, KeepLive> {+ return overrides as Record<string, KeepLive>+}++/** A recover hook for a revision-style list: keep whichever whole list holds the+ * most recent entry (by its `at`), ties to LIVE; the lists are NEVER merged, so+ * a signer's trim survives. OPTIONAL and for an UNSIGNED list only — a SIGNED+ * list must use the default (follow incoming), because a tie can otherwise pair+ * a signature with history it never signed (bento/type's finding). */+export const newestListWins: RecoverHook = (live, incoming) => {+ const newest = (x: unknown): string =>+ Array.isArray(x) ? x.reduce<string>((m, e) => {+ const a = (e as { at?: unknown })?.at+ return typeof a === 'string' && a > m ? a : m+ }, '') : ''+ const lv = Array.isArray(live) ? live : undefined+ const iv = Array.isArray(incoming) ? incoming : undefined+ if (!iv) return lv+ if (!lv) return iv+ return newest(iv) > newest(lv) ? iv : lv // tie → live+}+// --- capabilities / secrets (stripped on export) ----------------------------/** Top-level fields that carry a write/owner capability or secret. A copy that@@ -325,7 +484,15 @@ export const DEFAULT_NOT_EDIT: ReadonlySet<string> = new Set(['modified', 'previ/** A stable key over the fields that count as unsaved work, for crash-recovery* comparison. ABSENT fields never change the key (skipped, never null-padded),- * so a document without a newer field keys identically on an older build. */+ * so a document without a newer field keys identically on an older build.+ *+ * THE RULE for what counts: a field an app writes only at SAVE TIME belongs in+ * its notEdit set; anything written while EDITING counts. History counts by+ * default (a revision made or a trail row recorded mid-edit is unsaved work and+ * must survive a crash); an app exempts only what it writes at save time (e.g.+ * a revisions list appended in the save queue → notEdit), or a reopened+ * download-save shows a phantom recovery banner. Fail-safe: a missed exemption+ * costs a spurious banner, a wrong default costs data. */export function docContentKey(doc: object, classes: Record<string, FieldClass>, notEdit: ReadonlySet<string> = DEFAULT_NOT_EDIT,): string {diff --git a/scripts/test-restore.ts b/scripts/test-restore.tsnew file mode 100644index 00000000..e95d58e5--- /dev/null+++ b/scripts/test-restore.ts@@ -0,0 +1,197 @@+#!/usr/bin/env node+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+// Whole-document restore: applyRestore (kernel/src/docfields.ts).+//+// node scripts/test-restore.ts+//+// The class-driven generalisation of keepLiveIdentity for undo/redo, version+// restore and crash recovery. A field's behaviour is decided per field from its+// class, with per-field overrides, and the RESTORE DIRECTION matters:+// - 'back' (undo/redo, version restore): going back in time — a 'live' field+// keeps the live value, so identity and history don't roll back.+// - 'recover' (crash recovery): the incoming snapshot is a NEWER copy of THIS+// document — a 'live' history field is reconciled with it (a+// revision made just before the crash must survive).+// Overrides: type's comments are class 'history' (copy reasons) but must be+// undoable/restorable, so they are keepLive 'follows'. Recover hooks: a field+// may bind one (newestListWins for an UNSIGNED list); a signed list uses the+// default (follow incoming), or a tie can pair a signature with history it never+// signed.+//+// Mutations (edit kernel/src/docfields.ts, re-run — each reds a row):+// - applyRestore, make a 'live' field follow on 'back' : identity/history roll back+// - applyRestore, drop the recover history reconciliation : a newer revision is lost on recover+// - applyRestore, drop "absent never wipes on recover" : a missing key wipes live+// - newestListWins, tie `>` → `>=` : a trim is lost (tie takes incoming)+// - applyRestore, drop the PROTO_KEYS skip : a null-proto map lets a snapshot swap the prototype+// - applyRestore, honour the override for a floor class : collab/readonly/docId follow a snapshot++import { applyRestore, defaultKeepLive, newestListWins, validateRestoreRules, restoreOverrides } from '../kernel/src/docfields.ts'+import type { RestoreRules, RecoverHook } from '../kernel/src/docfields.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 eq = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)+type Rec = Record<string, unknown>++const CLASSES = {+ title: 'content', body: 'content',+ docId: 'identity', collab: 'capability', readonly: 'mode', template: 'mode',+ revisions: 'history', trail: 'history', comments: 'history',+} satisfies Record<string, FieldClass>+// comments: history class (copy), but restorable/undoable → keepLive 'follows'+const RULES: RestoreRules = { classes: CLASSES, keepLive: { comments: 'follows' } }++const live = (): Rec => ({+ title: 'live title', body: 'live body',+ docId: 'LIVE-ID', collab: { key: 'LIVE' }, readonly: false, template: false,+ revisions: [{ id: 'r1', at: '2026-01-01' }, { id: 'r2', at: '2026-02-01' }],+ comments: { t1: 'live' }, mystery: 'live-x',+})+const incoming = (over: Rec = {}): Rec => ({+ title: 'incoming title', body: 'incoming body',+ docId: 'OLD-ID', collab: { key: 'OLD' }, readonly: true, template: true,+ revisions: [{ id: 'r1', at: '2026-01-01' }],+ comments: { t1: 'incoming' }, mystery: 'incoming-x', ...over,+})++H('defaultKeepLive: content/unknown follow; identity/mode/capability/history live')+{+ ok(defaultKeepLive('content') === 'follows', 'content follows')+ ok(defaultKeepLive(undefined) === 'follows', 'an unknown field follows')+ ok(defaultKeepLive('identity') === 'live' && defaultKeepLive('capability') === 'live', 'identity + capability live')+ ok(defaultKeepLive('mode') === 'live' && defaultKeepLive('history') === 'live', 'mode + history live')+}++H('back (version restore): content follows; identity/mode/capability + history stay live')+{+ const r = applyRestore(live(), incoming(), 'back', RULES) as Rec+ ok(r.title === 'incoming title', 'content follows the version')+ ok(r.docId === 'LIVE-ID', 'identity stays live (a restore never rolls back docId)')+ ok((r.collab as Rec)?.key === 'LIVE', 'capability stays live')+ ok(r.readonly === false, 'mode stays live')+ ok(eq(r.revisions, live().revisions), 'history (revisions) stays LIVE — a version restore does not discard newer revisions')+ ok((r.comments as Rec)?.t1 === 'incoming', 'comments (keepLive override) FOLLOW the version')+ ok(r.mystery === 'incoming-x', 'an unknown field follows')+}++H('recover (crash): the newer snapshot wins content AND history; identity still live')+{+ const r = applyRestore(live(), incoming(), 'recover', RULES) as Rec+ ok(r.title === 'incoming title', 'content follows the newer snapshot')+ ok(r.docId === 'LIVE-ID', 'identity is still kept live on recover (same document)')+ ok(eq(r.revisions, incoming().revisions), 'history follows the snapshot on recover — a revision made just before the crash survives')+ ok((r.comments as Rec)?.t1 === 'incoming', 'comments follow the snapshot on recover')+}++H('absent never wipes on recover; but a back restore reflects the version exactly')+{+ const inc = incoming(); delete inc.revisions; delete inc.comments; delete inc.mystery+ const r = applyRestore(live(), inc, 'recover', RULES) as Rec+ ok(eq(r.revisions, live().revisions), 'a history field ABSENT from the snapshot keeps the live value (never wiped)')+ ok((r.comments as Rec)?.t1 === 'live', 'a follows field absent on recover keeps live')+ ok(r.mystery === 'live-x', 'an unknown field absent on recover keeps live')+ // version restore is exact: a field the version lacks is dropped+ const inc2 = incoming(); delete inc2.comments+ const r2 = applyRestore(live(), inc2, 'back', RULES) as Rec+ ok(!('comments' in r2), 'on back, a follows field the version lacks is dropped (the version had none)')+}++H('recover hooks: newestListWins (unsigned lists) vs the default (signed-safe)')+{+ const RH: RestoreRules = { classes: CLASSES, recover: { revisions: newestListWins } }+ // snapshot OLDER than live → keep the live list (a skewed older snapshot can't drop days/revisions)+ const older = applyRestore(live(), incoming(), 'recover', RH) as Rec+ ok(eq(older.revisions, live().revisions), 'newestListWins keeps the live list when the snapshot is older')+ // snapshot NEWER → take it+ const incNew = incoming({ revisions: [{ id: 'r1', at: '2026-01-01' }, { id: 'r2', at: '2026-02-01' }, { id: 'r3', at: '2026-03-01' }] })+ ok(((applyRestore(live(), incNew, 'recover', RH) as Rec).revisions as unknown[]).length === 3,+ 'newestListWins takes the snapshot when it is newer (all three revisions)')+ // trim + re-sign makes a TIE on the newest `at`. newestListWins keeps live (the+ // untrimmed list), which for a SIGNED list would be wrong — hence the default.+ const liveFull: Rec = { ...live(), revisions: [{ id: 'r1', at: '2026-01-01' }, { id: 'r2', at: '2026-02-01' }, { id: 'r3', at: '2026-03-01' }] }+ const incTrim = incoming({ revisions: [{ id: 'r3', at: '2026-03-01' }] }) // trimmed + re-signed; same newest at+ ok(((applyRestore(liveFull, incTrim, 'recover', RH) as Rec).revisions as unknown[]).length === 3,+ 'newestListWins resolves a tie to LIVE (never merges) — which is why a SIGNED list must NOT bind it')+ // the DEFAULT (no hook) follows the snapshot: the self-consistent trimmed+signed unit+ const def = (applyRestore(liveFull, incTrim, 'recover', { classes: CLASSES }) as Rec).revisions as Array<Rec>+ ok(def.length === 1 && def[0].id === 'r3', 'the default follows the snapshot — the self-consistent unit a signed list needs')+}++H('a recover hook is called ONLY when the snapshot HAS the field')+{+ let calls = 0+ const blind: RecoverHook = (_l, inc) => { calls++; return inc } // returns incoming (undefined if absent) blindly+ const RB: RestoreRules = { classes: CLASSES, recover: { revisions: blind } }+ // snapshot LACKS revisions → the hook must NOT run, live is kept untouched+ const inc = incoming(); delete inc.revisions+ const r = applyRestore(live(), inc, 'recover', RB) as Rec+ ok(calls === 0, 'the hook is not called when the snapshot lacks the field')+ ok(eq(r.revisions, live().revisions), 'and the live value is kept (a blind hook could not wipe it)')+ // snapshot HAS revisions → the hook runs+ applyRestore(live(), incoming(), 'recover', RB)+ ok(calls === 1, 'the hook runs when the snapshot has the field')+}++H('at is epoch-ms on both sides — a hook never compares a number to a string')+{+ // the caller normalises: live = Date.parse(doc.modified), incoming = snapshot.at (ms)+ const laterWins: RecoverHook = (lv, inc, at) => {+ ok(typeof at.incoming === 'number' && typeof at.live === 'number', 'the hook receives numeric times on both sides')+ return (at.incoming ?? 0) > (at.live ?? -Infinity) ? inc : lv+ }+ const RT: RestoreRules = { classes: CLASSES, recover: { revisions: laterWins } }+ const liveTime = Date.parse('2026-02-01T00:00:00Z') // doc.modified normalised by the caller+ const snapNewer = Date.now() // Snapshot.at is ms+ const r1 = applyRestore(live(), incoming({ revisions: [{ id: 'z', at: 'x' }] }), 'recover', RT, { live: liveTime, incoming: snapNewer }) as Rec+ ok((r1.revisions as Array<Rec>)[0].id === 'z', 'a newer snapshot time wins, compared as numbers')+ const r2 = applyRestore(live(), incoming({ revisions: [{ id: 'z', at: 'x' }] }), 'recover', RT, { live: snapNewer, incoming: liveTime }) as Rec+ ok(eq(r2.revisions, live().revisions), 'an older snapshot time keeps live, compared as numbers')+}++H('a recovery snapshot cannot swap the prototype (__proto__ / constructor)')+{+ // JSON.parse gives an OWN __proto__ key — the snapshot is untrusted input+ const poison = JSON.parse('{"title":"x","__proto__":{"polluted":true},"constructor":{"c":1}}')+ const r = applyRestore(live(), poison, 'recover', RULES) as Rec+ ok(Object.getPrototypeOf(r) === Object.prototype, 'plain class map: the restored doc keeps a clean prototype')+ ok((r as Rec).polluted === undefined, 'no polluted field inherited')+ ok(({} as Rec).polluted === undefined, 'Object.prototype itself is untouched')+ // NULL-PROTO class map: the case that was safe only by an inherited lookup before+ const nullClasses = Object.assign(Object.create(null), CLASSES) as Record<string, FieldClass>+ const r2 = applyRestore(live(), poison, 'recover', { classes: nullClasses }) as Rec+ ok(Object.getPrototypeOf(r2) === Object.prototype, 'null-proto class map: still no prototype swap')+ ok((r2 as Rec).polluted === undefined, 'and no field leaks through')+}++H('the override floor: identity / mode / capability never follow a snapshot')+{+ // a hostile/buggy override trying to make capability + modes + identity follow+ const bad: RestoreRules = { classes: CLASSES, keepLive: { collab: 'follows', readonly: 'follows', docId: 'follows' } as Record<string, 'follows'> }+ const r = applyRestore(live(), incoming(), 'recover', bad) as Rec+ ok((r.collab as Rec)?.key === 'LIVE', 'a follows on collab (capability) is IGNORED — the room stays live')+ ok(r.readonly === false, 'a follows on readonly (mode) is ignored — the lock stays live')+ ok(r.docId === 'LIVE-ID', 'a follows on docId (identity) is ignored')+ const threw = (fn: () => void) => { try { fn(); return false } catch { return true } }+ ok(threw(() => validateRestoreRules(bad)), 'validateRestoreRules refuses a non-live override on a floor-class field')+ ok(!threw(() => validateRestoreRules(RULES)), 'and accepts a valid override (comments follows)')+}++// COMPILE-TIME floor: restoreOverrides constrains override keys to content/+// history fields. These must each be a type error (scripts are not type-checked+// in CI, so they document + locally verify; the real enforcement is at the app+// call sites — type/spaces build their rules with restoreOverrides under tsc).+// @ts-expect-error collab is capability, not content/history+restoreOverrides(CLASSES, { collab: 'follows' })+// @ts-expect-error docId is identity+restoreOverrides(CLASSES, { docId: 'live' })+// @ts-expect-error readonly is mode+restoreOverrides(CLASSES, { readonly: 'live' })+ok(restoreOverrides(CLASSES, { comments: 'follows' }).comments === 'follows',+ 'restoreOverrides accepts a history field and constrains the rest at compile time')++console.log(`\n${checks - failures}/${checks} checks passed`)+process.exit(failures ? 1 : 0)