Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
kernel: revision-acknowledged save queue (#579)
nyblnetd1bfce906307
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 257e8d86..a1424b83 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -661,6 +661,15 @@ jobs:# throw when storage does.run: node scripts/test-storage.ts+ - name: Save queue rig+ # kernel/src/savequeue.ts serializes writes against one file handle and+ # acknowledges each by revision, so an edit made WHILE an async write is in+ # flight is never marked saved and lost (the setDirty-after-write race+ # every app had). The rig pins serialization, the detached snapshot,+ # isCurrent() going stale on any later edit or same-id replacement, the+ # document-swap discard, and that a failed write never poisons the queue.+ run: node scripts/test-savequeue.ts+- name: App registry rig# scripts/apps.mjs drives what a release builds, stages and signs. A# release SIGNS, and the key never reaches CI, so the pipeline itselfdiff --git a/kernel/src/documentvalue.ts b/kernel/src/documentvalue.tsnew file mode 100644index 00000000..5f48b32d--- /dev/null+++ b/kernel/src/documentvalue.ts@@ -0,0 +1,26 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+//+// Pure operations on a JSON document VALUE — the shared vocabulary the save+// queue (and, later, the shared history engine) speak. Split out of the Codex+// document-state work in #535; this PR takes only what the save queue needs+// (`copy`), and `equal` joins it when the conditional-history engine lands.+//+// A document is plain JSON: nested containers plus immutable leaves. `copy`+// deep-copies the CONTAINERS so a detached snapshot can never be mutated through+// the live tree, while leaving primitive leaves shared (an asset data-URI string+// is immutable, so copying it per edit would only cost memory). It also never+// walks the prototype chain — `Object.entries` reads own enumerable keys only —+// so a hostile `__proto__` entry in an imported document copies as an ordinary+// key and cannot pollute `Object.prototype`.++/** True for a plain (non-array) object we should recurse into. */+const object = (v: unknown): v is Record<string, unknown> =>+ !!v && typeof v === 'object' && !Array.isArray(v)++/** A structural deep copy: containers cloned, primitive leaves shared. */+export function copy<T>(v: T): T {+ if (Array.isArray(v)) return v.map(copy) as T+ if (object(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, copy(x)])) as T+ return v+}diff --git a/kernel/src/savequeue.ts b/kernel/src/savequeue.tsnew file mode 100644index 00000000..79fc2784--- /dev/null+++ b/kernel/src/savequeue.ts@@ -0,0 +1,57 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+//+// A revision-acknowledged SAVE QUEUE — the fix for a race every app had: it+// cleared the dirty flag after an ASYNC file write, so an edit made WHILE the+// write was in flight was marked saved and then lost (slides' setDirty(false)+// after writeUpdatedFile; spaces and dash the same shape). The queue serializes+// every write against one file handle and captures a DETACHED snapshot of the+// document the instant before each write, then hands back an `isCurrent()` the+// caller checks AT ACKNOWLEDGEMENT time — so the dirty flag is only cleared when+// nothing has changed since the bytes that were actually written.+//+// Split out of the Codex document-state work in #535. Deliberately minimal: NO+// UI, dirty flag, encryption, undo or app-model policy lives here — those stay+// the app's. It knows only about a monotonic revision and the document identity.++import type { KernelDoc } from './doc.ts'+import { copy } from './documentvalue.ts'++/** Apps supply a monotonic revision that advances on EVERY mutation, including+ * typing within an undo group and remote edits. Selection changes need not count.+ * All writes that use/adopt the same file handle must share one queue. */+export interface SaveHost<D extends KernelDoc> {+ getDocument(): D+ getRevision(): number+}+export interface SavedRevision<D, T> {+ value: T+ doc: D+ /** Check at acknowledgement time, not just when the write resolves. */+ isCurrent(): boolean+}++/** Serialize manual/automatic writes and capture a detached revision immediately+ * before each write. No UI, dirty flag, encryption, undo or app-model policy here.+ * A rejected write never poisons the queue; a queued request for another document+ * is discarded. The writer must await completion of its actual file write. */+export class SaveQueue<D extends KernelDoc> {+ private tail: Promise<unknown> = Promise.resolve()+ private host: SaveHost<D>+ constructor(host: SaveHost<D>) { this.host = host }++ run<T>(prepare: () => void, write: (doc: D) => Promise<T>): Promise<SavedRevision<D, T> | undefined> {+ const identity = this.host.getDocument().docId+ const task = this.tail.then(async () => {+ if (this.host.getDocument().docId !== identity) return undefined+ prepare()+ // Preparation may stamp collaboration state, but must not switch documents.+ if (this.host.getDocument().docId !== identity) return undefined+ const live = this.host.getDocument(), revision = this.host.getRevision(), doc = copy(live)+ const value = await write(doc)+ return { value, doc, isCurrent: () => this.host.getDocument() === live && this.host.getRevision() === revision }+ })+ this.tail = task.catch(() => {})+ return task+ }+}diff --git a/scripts/test-savequeue.ts b/scripts/test-savequeue.tsnew file mode 100644index 00000000..fe396c60--- /dev/null+++ b/scripts/test-savequeue.ts@@ -0,0 +1,123 @@+#!/usr/bin/env node+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+// kernel/src/savequeue.ts + documentvalue.ts — the revision-acknowledged save.+//+// node scripts/test-savequeue.ts+//+// WHAT THIS PROVES. Every app cleared its dirty flag AFTER an async file write,+// so an edit made WHILE the write was in flight was marked saved and lost. The+// SaveQueue serializes writes against one handle, snapshots the document the+// instant before each write, and exposes isCurrent() the caller checks at+// acknowledgement time — so "saved" is only claimed for a document nothing has+// changed since. These checks pin that contract, and copy()'s detachment ++// prototype safety underneath it.++import { copy } from '../kernel/src/documentvalue.ts'+import { SaveQueue } from '../kernel/src/savequeue.ts'++let failures = 0, checks = 0+function ok(what: string, cond: unknown): void {+ checks+++ if (cond) return+ failures+++ console.error(` FAIL ${what}`)+}+const tick = (ms = 0): Promise<void> => new Promise((r) => setTimeout(r, ms))+// deno-lint-ignore no-explicit-any+type Doc = { docId: string } & Record<string, any>+const host = (get: () => Doc, rev: () => number) => ({ getDocument: get, getRevision: rev })++// ————— copy(): containers cloned, leaves shared, no prototype pollution —————+{+ const src = { a: 1, s: 'x', nest: { list: [{ id: 'e', t: 'v' }] } }+ const c = copy(src)+ ok('copy is a different object', c !== src && c.nest !== src.nest && c.nest.list !== src.nest.list)+ c.nest.list[0].t = 'changed'+ ok('mutating the copy does not touch the source', src.nest.list[0].t === 'v')+ ok('a primitive leaf is shared by value', copy('shared') === 'shared')+ // A hostile __proto__ (as JSON.parse produces it — an own key) must copy as an+ // ORDINARY key via Object.fromEntries, never onto Object.prototype.+ const hostile = JSON.parse('{"__proto__":{"polluted":true},"ok":1}')+ copy(hostile)+ ok('copy() does not pollute Object.prototype', ({} as Record<string, unknown>).polluted === undefined)+}++// ————— writes are serialized against one queue —————+{+ const doc: Doc = { docId: 'd', title: 'x' }+ const q = new SaveQueue(host(() => doc, () => 0))+ const order: string[] = []+ const p1 = q.run(() => {}, async () => { order.push('w1-start'); await tick(20); order.push('w1-end'); return 1 })+ const p2 = q.run(() => {}, async () => { order.push('w2-start'); return 2 })+ await Promise.all([p1, p2])+ ok('the second write waits for the first to finish', order.join(',') === 'w1-start,w1-end,w2-start')+}++// ————— the write sees a DETACHED snapshot, not the live doc —————+{+ const doc: Doc = { docId: 'd', title: 'orig' }+ const q = new SaveQueue(host(() => doc, () => 0))+ let seen = ''+ await q.run(() => {}, async (snap) => { doc.title = 'edited during the write'; await tick(5); seen = snap.title; return 0 })+ ok('the snapshot handed to write is detached from later live edits', seen === 'orig')+}++// ————— isCurrent(): true when unchanged, false after any later edit —————+{+ let doc: Doc = { docId: 'd', title: 'a' }; let rev = 0+ const q = new SaveQueue(host(() => doc, () => rev))+ const saved = await q.run(() => {}, async () => true)+ ok('isCurrent() is true right after a clean save', saved!.isCurrent())+ rev+++ ok('a later revision bump makes it stale', !saved!.isCurrent())+ // a same-id REPLACEMENT of the document object also invalidates it (identity,+ // not just docId — a replaceDoc keeps the id but is a new tree)+ const saved2 = await q.run(() => {}, async () => true)+ ok('current again after re-saving', saved2!.isCurrent())+ doc = { ...doc }+ ok('a same-id replacement object invalidates acknowledgement', !saved2!.isCurrent())+}++// ————— a write queued for a document that is swapped out is discarded —————+{+ let doc: Doc = { docId: 'd', title: 'a' }+ const q = new SaveQueue(host(() => doc, () => 0))+ const slow = q.run(() => {}, async () => { await tick(20); return 'slow' })+ let wrote2 = false+ const second = q.run(() => {}, async () => { wrote2 = true; return 'x' })+ doc = { docId: 'other', title: 'a' } // identity changes before `second` runs+ const res2 = await second+ ok('a queued write whose document was swapped returns undefined', res2 === undefined)+ ok('…and its write never ran', !wrote2)+ await slow+}++// ————— prepare() may stamp state but must not switch documents —————+{+ let doc: Doc = { docId: 'd', title: 'a' }+ const q = new SaveQueue(host(() => doc, () => 0))+ let wrote = false+ const res = await q.run(() => { doc = { docId: 'switched', title: 'a' } }, async () => { wrote = true; return 'x' })+ ok('a prepare that switches documents discards the write', res === undefined)+ ok('…and the write never ran', !wrote)+}++// ————— a rejected write (or prepare) never poisons the queue —————+{+ const doc: Doc = { docId: 'd', title: 'a' }+ const q = new SaveQueue(host(() => doc, () => 0))+ let threwWrite = false+ try { await q.run(() => {}, async () => { throw new Error('write boom') }) } catch { threwWrite = true }+ ok('a failed write rejects to its caller', threwWrite)+ const after = await q.run(() => {}, async () => 'ok')+ ok('the queue still works after a failed write', after!.value === 'ok')+ let threwPrep = false+ try { await q.run(() => { throw new Error('prep boom') }, async () => 'x') } catch { threwPrep = true }+ ok('a failed prepare rejects to its caller', threwPrep)+ const after2 = await q.run(() => {}, async () => 'ok2')+ ok('the queue still works after a failed prepare', after2!.value === 'ok2')+}++console.log(failures ? `\ntest-savequeue: ${failures} FAILED of ${checks}` : `test-savequeue: ${checks} checks OK`)+process.exit(failures ? 1 : 0)