Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

kernel: revision-acknowledged save queue (#579)

nyblnetd1bfce906307
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 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 itself
diff --git a/kernel/src/documentvalue.ts b/kernel/src/documentvalue.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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)