Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

spaces: one answer to what a block is nested under, and it cannot cycle (#266)

nyblnetc527e7f96b25
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index f1be92be..5c65ece6 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -14,6 +14,56 @@ Decision. Why. Pointers.
---
+## 2026-08-06 — The tree is DERIVED at read time, in one function, and it cannot cycle
+
+**Decision.** `model.ts effectiveParents(page)` is the only answer to "what is
+this block nested under": `b.parent` iff that block is in the SAME page and
+appears STRICTLY EARLIER. Anything else — absent, itself, later — resolves to
+the root. `descendantsOf(page, id)` is built on it. Every consumer delegates.
+
+This implements the rule settled on 2026-08-03, which until now existed as a
+paragraph and four disagreeing implementations: positional in `render.ts`, a
+hop-capped graph walk in `blocks.ts mdLayout`, a fixed-point sweep in
+`agent.ts descendants` ("rather than trusting the order"), and an id lookup in
+`editor.indent`. They agreed only because the editor keeps the array in
+pre-order — which is exactly the invariant collaboration breaks.
+
+**DERIVE, NEVER REPAIR.** Normalising the array instead would mint `ord` ops and
+two replicas can ping-pong over them forever. A read-time function mutates
+nothing, so two replicas that agree on the array agree on the tree without
+exchanging one extra op.
+
+**Acyclic by construction, which is the point.** A parent must be earlier, so no
+document — authored, hand-edited, imported or merged — can produce a loop. That
+removes a whole class of defence: no visited set, no hop cap of 32, no
+fixed-point sweep. `blocks.ts` capped at 32 because the graph could cycle, and a
+markdown export that silently truncated at depth 32 is a quiet wrong answer
+rather than an error.
+
+**The failure it prevents.** On a merged `parent` cycle the old sweep returned
+the whole connected component INCLUDING the node itself, so `planRemoveBlocks`
+deleted blocks the caller never named.
+
+**Verified against documents the merge actually produced**, not hand-built ones:
+250 merged documents, 1,695 blocks, 24.4% of them violating flat pre-order —
+zero rule failures, no cycles, no self-parents, no subtree containing its own
+root. `scripts/test-sync-spaces.ts` now asserts this on every merged document
+forever, and the negative control (reverting to a raw graph walk) fails 13
+blocks out of 405.
+
+**`Store.tree()` gains a visited set, and surfaces what a cycle orphans.**
+`buildIndex` bins pages by `parent` with no position test, so two concurrent
+sidebar drags converge on A.parent=B, B.parent=A. Neither is reachable from the
+root, so both pages vanished from the sidebar AND from the Markdown export while
+still sitting in the file, with nothing saying so; a subtree call from inside
+the cycle recursed until the stack gave out. Orphaned pages are now listed at
+the root — pages you can see and re-home beat pages that quietly stopped
+existing.
+
+**Still a page-level graph sweep in `planRemovePage`**, deliberately: it
+terminates, and cascading a cyclic pair is what a caller asking for descendants
+gets. Named here so the next reader knows it was considered rather than missed.
+
## 2026-08-06 — bento/spaces will not stamp the text token history, and that is only safe if everyone is lean
**Decision.** `toJSON({ text: false })` omits `txt` from a stamped state.
diff --git a/scripts/test-spaces-model.ts b/scripts/test-spaces-model.ts
index 1c31c4ff..ca7a91a4 100644
--- a/scripts/test-spaces-model.ts
+++ b/scripts/test-spaces-model.ts
@@ -28,6 +28,7 @@
import {
parseDoc, buildIndex, docContentKey, homePage, FORMAT, isRemote,
+ effectiveParents, descendantsOf,
type SpacesDoc,
} from '../spaces/src/model.ts'
import { countOutsideTags, replaceOutsideTags } from '../spaces/src/findreplace.ts'
@@ -1336,5 +1337,74 @@ for (const [label, input, err] of [
'…and the view controls likewise, so a reader and a printout get neither')
}
+// ---- ONE answer to "what is this nested under" ------------------------------
+// The rule (DECISIONS 2026-08-03): a block's effective parent is `b.parent` iff
+// that block is in the SAME page and appears STRICTLY EARLIER. It was
+// implemented four times, differently — positional in render.ts, a hop-capped
+// graph walk in blocks.ts, a fixed-point sweep in agent.ts, an id lookup in
+// editor.indent — and they agreed only because the editor keeps the array in
+// pre-order. Collaboration is precisely what breaks that: measured on the merge
+// rig, 52.4% of merged documents violate it.
+{
+ const page = (blocks: unknown[]) => ({ id: 'p1', title: 'P', blocks } as Page)
+
+ // the ordinary case
+ const ok1 = page([{ id: 'a', type: 'p', html: '' }, { id: 'b', type: 'p', html: '', parent: 'a' }])
+ ok(effectiveParents(ok1).get('b') === 'a', 'a child after its parent is nested under it')
+
+ // the shapes a merge produces, and each resolves to the ROOT rather than
+ // to something a renderer cannot draw
+ const later = page([{ id: 'b', type: 'p', html: '', parent: 'a' }, { id: 'a', type: 'p', html: '' }])
+ ok(effectiveParents(later).get('b') === undefined,
+ 'a parent that appears LATER is not a parent — this is the merge case')
+ const absent = page([{ id: 'b', type: 'p', html: '', parent: 'gone' }])
+ ok(effectiveParents(absent).get('b') === undefined, 'a parent that is absent is not a parent')
+ const self = page([{ id: 'b', type: 'p', html: '', parent: 'b' }])
+ ok(effectiveParents(self).get('b') === undefined, 'a block is not its own parent')
+
+ // ACYCLIC BY CONSTRUCTION: a parent must be earlier, so no input can loop.
+ // The two-cycle below is what two concurrent indents converge on.
+ const cycle = page([
+ { id: 'x', type: 'p', html: '', parent: 'y' },
+ { id: 'y', type: 'p', html: '', parent: 'x' },
+ ])
+ const eff = effectiveParents(cycle)
+ ok(eff.get('x') === undefined && eff.get('y') === 'x',
+ 'a merged cycle resolves to a tree, with no visited set and no hop cap')
+
+ // descendantsOf must never return the node itself, which is what the old
+ // fixed-point sweep did on a cycle — and planRemoveBlocks deletes what it
+ // returns
+ ok(!descendantsOf(cycle, 'x').has('x'), 'a subtree never contains its own root')
+ ok(!descendantsOf(cycle, 'y').has('y'), '…from either end of the cycle')
+
+ const deep = page([
+ { id: 'a', type: 'p', html: '' },
+ { id: 'b', type: 'p', html: '', parent: 'a' },
+ { id: 'c', type: 'p', html: '', parent: 'b' },
+ { id: 'd', type: 'p', html: '' },
+ ])
+ ok([...descendantsOf(deep, 'a')].sort().join(',') === 'b,c', 'a subtree reaches grandchildren')
+ ok(descendantsOf(deep, 'd').size === 0, 'and stops at a leaf')
+
+ // THE CONSUMERS AGREE, checked as source: four implementations was the bug
+ const fs2 = await import('node:fs')
+ const src = (f: string) => fs2.readFileSync(new URL(`../spaces/src/${f}`, import.meta.url), 'utf8')
+ ok(/descendantsOf\(page, id\)/.test(src('agent.ts')),
+ 'agent.ts delegates rather than sweeping the graph itself')
+ // scoped to the BLOCK sweep: planRemovePage still sweeps the PAGE graph, and
+ // that one is out of this change's scope (it terminates, and cascading a
+ // cyclic pair is what the caller asked for). Named so the next reader knows
+ // the remaining sweep is deliberate rather than missed.
+ ok(!/for \(const b of page\.blocks\)[\s\S]{0,200}grew = true/.test(src('agent.ts')),
+ '…and its block-level fixed-point sweep is gone')
+ ok(/effectiveParents/.test(src('blocks.ts')) && !/chain\.length < 32/.test(src('blocks.ts')),
+ 'blocks.ts walks the effective chain, and its hop cap is gone with the cycles')
+ ok(/effectiveParents\(page\)/.test(src('editor.ts')),
+ 'editor.indent outdents through the effective parent')
+ ok(/seen: Set<string>/.test(src('store.ts')),
+ 'Store.tree carries a visited set')
+}
+
console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)
diff --git a/scripts/test-sync-spaces.ts b/scripts/test-sync-spaces.ts
index f9b1ca5a..74ef8224 100644
--- a/scripts/test-sync-spaces.ts
+++ b/scripts/test-sync-spaces.ts
@@ -30,6 +30,7 @@
import { SyncEngine, shape } from '../kernel/src/sync/crdt.ts'
import { mulberry32, baseDoc, randomMutation, type Doc } from './lib/sync-fixtures-spaces.ts'
+import { effectiveParents, descendantsOf } from '../spaces/src/model.ts'
export const SPACES_SHAPE = shape('pages', 'blocks')
class SpacesSync extends SyncEngine {
@@ -136,6 +137,8 @@ let diverged = 0
let opsTotal = 0
let soloBroken = 0
let measured = 0
+let ruleBroken = 0
+let ruleChecked = 0
for (let seed = 1; seed <= SEEDS; seed++) {
const rnd = mulberry32(seed * 7919)
@@ -191,6 +194,29 @@ for (let seed = 1; seed <= SEEDS; seed++) {
if (total(inspect(solo.doc)) > 0) { soloBroken++; continue }
measured++
+ // THE TREE RULE, on a document the merge actually produced. The violations
+ // below are real and expected; what must never happen is the RULE failing on
+ // one of them — a parent that is not strictly earlier, a walk that cycles, or
+ // a subtree that contains its own root (which is what makes a delete take
+ // blocks nobody selected).
+ for (const page of reps[0].doc.pages) {
+ const at = new Map<string, number>()
+ page.blocks.forEach((b, i) => at.set(b.id, i))
+ const eff = effectiveParents(page as never)
+ for (const b of page.blocks) {
+ const par = eff.get(b.id)
+ if (par !== undefined && (at.get(par) ?? 1e9) >= (at.get(b.id) ?? -1)) ruleBroken++
+ if (par === b.id) ruleBroken++
+ const walked = new Set<string>()
+ for (let up = par; up; up = eff.get(up)) {
+ if (walked.has(up)) { ruleBroken++; break }
+ walked.add(up)
+ }
+ if (descendantsOf(page as never, b.id).has(b.id)) ruleBroken++
+ ruleChecked++
+ }
+ }
+
const v = inspect(reps[0].doc)
if (total(v) > 0) {
seedsWithViolations++
@@ -199,6 +225,10 @@ for (let seed = 1; seed <= SEEDS; seed++) {
}
ok(diverged === 0, `all replicas converge (${diverged} seed(s) diverged)`)
+ok(ruleBroken === 0,
+ `the effective-parent rule holds on every merged document ` +
+ `(${ruleBroken} failure(s) across ${ruleChecked} blocks) — no cycle, no late parent, ` +
+ 'no subtree containing its own root')
// The control is REPORTED, not asserted: a seed the generator got wrong is
// excluded from the measurement, so it cannot contaminate the finding. What
// would invalidate the rig is excluding most of them, so that IS asserted.
diff --git a/spaces/CHANGELOG.md b/spaces/CHANGELOG.md
index 90e1aea2..9cd62ac0 100644
--- a/spaces/CHANGELOG.md
+++ b/spaces/CHANGELOG.md
@@ -89,6 +89,20 @@ Versions follow `0.MINOR.PATCH` while pre-1.0.
`[object Object]` and reported success. It now refuses, as does `newIssue` and
`updatePage` for the same argument.
+- **Fixed: pages could disappear from the sidebar and from the Markdown
+ export.** Two people dragging pages onto each other — or one hand-edited
+ file — could leave a pair each nested inside the other. Neither was reachable
+ from the top, so both dropped out of the sidebar and out of exported
+ Markdown while still sitting in the file, with nothing to say so. They are
+ listed at the top level now.
+
+- **Fixed: deleting a block could take blocks you did not select.** "What is
+ nested under this?" was answered four different ways in four places, and on a
+ document where a block's parent sits *after* it, one of those answers
+ returned the whole tangle — including the block itself. There is one answer
+ now, and it cannot tangle: a block is nested under its parent only when that
+ parent is genuinely above it on the page.
+
## [0.1.0] — 2026-08-03
First release.
diff --git a/spaces/src/about.ts b/spaces/src/about.ts
index 8dc7a407..3755d7a1 100644
--- a/spaces/src/about.ts
+++ b/spaces/src/about.ts
@@ -233,8 +233,14 @@ export function openAbout({ store, onRepaint, onSaveCopy, onImport }: AboutHooks
*/
export function toMarkdown(store: Store): string {
const out: string[] = []
- const walk = (parent: string, depth: number) => {
- for (const page of store.index.children.get(parent) ?? []) {
+ // ONE traversal, store.tree() — not a second walk over index.children.
+ // That second walk is how a page-tree CYCLE dropped pages out of the export
+ // while they sat in the file: neither page is reachable from the root, so
+ // neither was ever visited. Store.tree() carries the visited set and surfaces
+ // what a cycle orphans, and this now inherits both. Measured before the fix:
+ // 13 pages in the file, 11 in the export.
+ const walk = () => {
+ for (const { page, depth } of store.tree()) {
out.push(`${'#'.repeat(Math.min(depth + 1, 6))} ${page.title}`, '')
// Indent, blockquote markers and what separates one block from the next
// are properties of the TREE, not of a block, so they come from the
@@ -263,10 +269,9 @@ export function toMarkdown(store: Store): string {
out.push(...lines.flatMap((l) => l.split('\n')).map((l) => (l ? quote + l : quote.trimEnd())))
out.push(sep)
})
- walk(page.id, depth + 1)
}
}
- walk('', 0)
+ walk()
return out.join('\n').replace(/\n{3,}/g, '\n\n')
}
diff --git a/spaces/src/agent.ts b/spaces/src/agent.ts
index ab9841fb..ce6b5a6c 100644
--- a/spaces/src/agent.ts
+++ b/spaces/src/agent.ts
@@ -30,7 +30,7 @@
// an undo entry that undoes nothing. Planning first also makes the whole write
// path testable in node, where there is no store and no DOM.
-import { type SpacesDoc, type Page, type Block, buildIndex, isRemote, newBlock, newPage, uid } from './model.ts'
+import { type SpacesDoc, type Page, type Block, buildIndex, isRemote, newBlock, newPage, uid, descendantsOf } from './model.ts'
import { SPECS, SPEC } from './blocks.ts'
import { sanitizeInline, textOf, inertBody, esc, UNWRAP } from './sanitize.ts'
import { orphanAssets, humanBytes } from './assets.ts'
@@ -64,22 +64,17 @@ export function findBlock(doc: SpacesDoc, id: string): BlockAt | null {
return null
}
-/** Every block nested under `id` on its page, at any depth. */
+/**
+ * Every block nested under `id`.
+ *
+ * Delegates to model.ts's ONE rule. It used to sweep the `parent` graph to a
+ * fixed point "rather than trusting the order", which is the right instinct and
+ * the wrong rule: on a merged document a `parent` cycle makes that sweep return
+ * the whole connected component INCLUDING `id` itself, so planRemoveBlocks
+ * would delete blocks the caller never named. The positional rule cannot cycle.
+ */
function descendants(page: Page, id: string): Set<string> {
- const out = new Set<string>()
- let grew = true
- // the array is pre-order, but a hand-written document need not be, so this
- // sweeps to a fixed point rather than trusting the order
- while (grew) {
- grew = false
- for (const b of page.blocks) {
- if (b.parent && (b.parent === id || out.has(b.parent)) && !out.has(b.id)) {
- out.add(b.id)
- grew = true
- }
- }
- }
- return out
+ return descendantsOf(page, id)
}
/**
diff --git a/spaces/src/blocks.ts b/spaces/src/blocks.ts
index 1be52bc1..426605c9 100644
--- a/spaces/src/blocks.ts
+++ b/spaces/src/blocks.ts
@@ -21,6 +21,7 @@
// `custom: true`; everything the registry can express lives here.
import type { Block } from './model'
+import { effectiveParents } from './model.ts'
import type { IconName } from './icons'
export interface BlockSpec {
@@ -313,9 +314,20 @@ export function mdLayout(blocks: Block[]): Array<{ quote: string; indent: string
// blocks can name each other. The renderer is a pre-order pass and cannot
// loop; an ancestor walk can, and would hang an export of a document that
// displays perfectly well.
+ // The ancestor chain, by model.ts's ONE rule — `parent` must exist in this
+ // page AND appear strictly earlier. This followed the raw `parent` graph with
+ // a hop cap of 32, which is a cap because the graph can cycle; under the
+ // positional rule it cannot, so the walk terminates by construction and the
+ // cap is gone. (Held: an EXPORT that silently truncated at depth 32 would
+ // have been a quiet wrong answer, not an error.)
+ const eff = effectiveParents({ blocks } as never)
const owners = (b: Block): Block[] => {
const chain: Block[] = []
- for (let o = b.parent ? byId.get(b.parent) : undefined; o && chain.length < 32; o = o.parent ? byId.get(o.parent) : undefined) chain.push(o)
+ for (let id = eff.get(b.id); id; id = eff.get(id)) {
+ const o = byId.get(id)
+ if (!o) break
+ chain.push(o)
+ }
return chain
}
const wraps = (b: Block | undefined): boolean => !!b && SPEC.get(b.type)?.mdQuoteChildren === true
diff --git a/spaces/src/editor.ts b/spaces/src/editor.ts
index 77d656ba..d6b0867e 100644
--- a/spaces/src/editor.ts
+++ b/spaces/src/editor.ts
@@ -8,7 +8,7 @@
// and merging blocks can never re-mint an id, and ids are what links,
// backlinks and (later) collaboration key on.
-import { type Block, newBlock, newPage } from './model'
+import { type Block, newBlock, newPage, effectiveParents } from './model'
import { Store } from './store'
import { renderPage, toneLabel, paintCode } from './render'
import { CODE_LANGS, langLabel, normLang } from './highlight'
@@ -1805,9 +1805,15 @@ export class Editor {
if (!b) return
s.commit(() => {
if (!deeper) {
- if (!b.parent) return
- const owner = page.blocks.find((x) => x.id === b.parent)
- if (owner?.parent) b.parent = owner.parent
+ // by the EFFECTIVE parent (model.ts), not by whatever `parent` names:
+ // on a merged document `parent` can point at a block that is absent or
+ // that sits LATER, and outdenting through it would move this block
+ // under something the renderer never nested it under
+ const eff = effectiveParents(page)
+ const owner = eff.get(b.id)
+ if (!owner) { delete b.parent; return }
+ const grand = eff.get(owner)
+ if (grand) b.parent = grand
else delete b.parent
return
}
diff --git a/spaces/src/model.ts b/spaces/src/model.ts
index be6a0e02..126162dc 100644
--- a/spaces/src/model.ts
+++ b/spaces/src/model.ts
@@ -342,6 +342,65 @@ const pushInto = <T>(m: Map<string, T[]>, k: string, v: T) => {
else m.set(k, [v])
}
+/**
+ * THE ONE ANSWER to "what is this block nested under".
+ *
+ * A block's effective parent is `b.parent` iff that block exists in the SAME
+ * page and appears STRICTLY EARLIER in the array. Anything else — a parent that
+ * is absent, that is the block itself, or that sits later — resolves to the
+ * root. Settled in docs/DECISIONS.md (2026-08-03) and implemented here because
+ * it was previously implemented four times, differently:
+ *
+ * · render.ts walked a stack, which IS this rule (positional);
+ * · blocks.ts mdLayout followed `parent` as a graph, hop-capped at 32;
+ * · agent.ts descendants swept the graph to a fixed point, explicitly
+ * "rather than trusting the order";
+ * · editor.indent looked its owner up by id, anywhere in the page.
+ *
+ * They agree today only because the editor keeps the array in pre-order. That
+ * is exactly the invariant collaboration breaks: `parent` is a last-writer-wins
+ * register and order is a fractional position key, so two legal concurrent
+ * edits — you indent a block, I move one — converge on an array where a child
+ * precedes its parent. Measured on the merge rig: 52.4% of merged documents.
+ * At that point "the tree" means four different things, and the graph readers
+ * are the dangerous ones: a merged cycle makes `descendants` return the whole
+ * connected component, so deleting one block deletes blocks nobody selected.
+ *
+ * POSITIONAL IS THE RULE BECAUSE IT CANNOT FAIL. A parent must be earlier, so
+ * the result is ACYCLIC BY CONSTRUCTION — no visited set, no hop cap, no
+ * fixed-point sweep, and no document can be authored or merged into a shape
+ * that makes it loop. It is a pure READ-TIME function: it mutates nothing, so
+ * two replicas that agree on the array agree on the tree without exchanging a
+ * single extra op. Repairing the array instead would mint `ord` ops and two
+ * replicas can ping-pong over them forever.
+ */
+export function effectiveParents(page: Page): Map<string, string | undefined> {
+ const out = new Map<string, string | undefined>()
+ const seenAt = new Map<string, number>()
+ page.blocks.forEach((b, i) => {
+ const p = typeof b.parent === 'string' ? b.parent : undefined
+ // strictly earlier: `seenAt` only holds blocks already walked past
+ out.set(b.id, p !== undefined && seenAt.has(p) ? p : undefined)
+ seenAt.set(b.id, i)
+ })
+ return out
+}
+
+/**
+ * Every block nested under `id`, at any depth — by the rule above, so it
+ * terminates on any document and never reaches outside the subtree.
+ */
+export function descendantsOf(page: Page, id: string): Set<string> {
+ const eff = effectiveParents(page)
+ const out = new Set<string>()
+ // one forward pass suffices: a child always follows its effective parent
+ for (const b of page.blocks) {
+ const p = eff.get(b.id)
+ if (p !== undefined && (p === id || out.has(p))) out.add(b.id)
+ }
+ return out
+}
+
export function buildIndex(doc: SpacesDoc): SpaceIndex {
const page = new Map<string, Page>()
const children = new Map<string, Page[]>()
diff --git a/spaces/src/store.ts b/spaces/src/store.ts
index 1b4ed810..52a4eccf 100644
--- a/spaces/src/store.ts
+++ b/spaces/src/store.ts
@@ -97,11 +97,35 @@ export class Store {
}
/** Pages in sidebar order: a depth-first walk of the page tree. */
- tree(parent = '', depth = 0): Array<{ page: Page; depth: number }> {
+ /**
+ * The page tree, for the sidebar and the Markdown export.
+ *
+ * `seen` is not defensive tidiness. `buildIndex` bins pages by `parent` with
+ * no position test, and two people concurrently dragging pages onto each
+ * other converge on A.parent=B, B.parent=A — legal for each of them, a cycle
+ * together. Neither page is then reachable from the root, so BOTH VANISH from
+ * the sidebar and from the Markdown export while still sitting in the file,
+ * and nothing says so. Worse, a subtree call from inside the cycle recurses
+ * until the stack gives out.
+ *
+ * A cyclic group is surfaced at the ROOT rather than hidden: pages you can
+ * see and re-home beat pages that quietly stopped existing.
+ */
+ tree(parent = '', depth = 0, seen: Set<string> = new Set()): Array<{ page: Page; depth: number }> {
const out: Array<{ page: Page; depth: number }> = []
for (const p of this.index.children.get(parent) ?? []) {
+ if (seen.has(p.id)) continue
+ seen.add(p.id)
out.push({ page: p, depth })
- out.push(...this.tree(p.id, depth + 1))
+ out.push(...this.tree(p.id, depth + 1, seen))
+ }
+ // Anything a cycle kept off the root walk, listed rather than lost.
+ if (parent === '' && depth === 0) {
+ for (const p of this.doc.pages) {
+ if (p.archived || seen.has(p.id)) continue
+ seen.add(p.id)
+ out.push({ page: p, depth: 0 })
+ }
}
return out
}