Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

docfields: whole-document restore for the version-history module (applyRestore) (#701)

nyblnetb75f073b5a6b
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 760728ad..6013eb52 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -118,6 +118,14 @@ jobs:
- name: Field-classification rig
run: 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.ts
index 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.ts
new file mode 100644
index 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)