Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

sync: name the document shape, so one engine can serve two apps (#247)

nyblnetc84284e4cfcd
diff --git a/slides/src/sync/crdt.ts b/slides/src/sync/crdt.ts
index aad5f415..6c99349a 100644
--- a/slides/src/sync/crdt.ts
+++ b/slides/src/sync/crdt.ts
@@ -37,6 +37,81 @@
import type { BentoDoc, Slide, SlideElement } from '../model'
+// ---------------------------------------------------------------------------
+// document shape
+// ---------------------------------------------------------------------------
+
+/**
+ * WHICH KEYS HOLD THE TWO CONTAINER LEVELS.
+ *
+ * The engine's algebra — composite node keys, fractional position keys,
+ * per-(node,key) registers, the token RGA over `html` — has nothing to do with
+ * slides. Only the two property names do: the doc key holding the parent array
+ * (`slides`) and the parent key holding the child array (`elements`).
+ * bento/spaces has the same two levels under different names (`pages`,
+ * `blocks`), so naming them is the whole of what it takes for one engine to
+ * serve both apps.
+ *
+ * BOUND AT MODULE LEVEL, NEVER SERIALIZED, NEVER ON THE WIRE. A room is
+ * single-app by construction (the room id is minted per file), so no frame
+ * ever has to say which shape it came from — and putting a shape tag in
+ * SyncStateJSON would change the bytes of every bento/slides file already on
+ * a disk. That constraint is not a style preference: scripts/test-sync-equiv.ts
+ * asserts byte-identity against the engine as shipped, and a `state-key-order`
+ * mutant exists precisely to prove the comparator notices.
+ *
+ * The WIRE VOCABULARY is deliberately not parameterized. Ops keep saying
+ * `kind:'slide'|'element'` and carrying `sl`/`el` for every app: renaming them
+ * per app buys prettier debug output and costs a second binding on the
+ * highest-consequence bytes in the system.
+ */
+export interface DocShape {
+ /** doc-level key holding the PARENT array: 'slides' | 'pages' */
+ readonly parents: string
+ /** parent-level key holding the CHILD array: 'elements' | 'blocks' */
+ readonly children: string
+ /**
+ * Doc-level keys the differ never syncs.
+ *
+ * MUST contain `parents`, which is why `shape()` below DERIVES it rather
+ * than taking it: the container is synced structurally — per node, with its
+ * own position key — so listing it as an ordinary doc property instead would
+ * collapse the whole document into ONE last-writer-wins register, and every
+ * concurrent edit would destroy every other. Deriving it means no caller can
+ * get it wrong; when this becomes a constructor argument, that has to become
+ * an assertion instead.
+ */
+ readonly skipDoc: ReadonlySet<string>
+}
+
+/** Derived, never authored: the volatile set is the same for every app apart
+ * from the container name, so writing it out twice invites them to drift. */
+const shape = (parents: string, children: string): DocShape => {
+ const skipDoc = new Set([parents, 'modified', 'collab', 'format', 'version'])
+ return { parents, children, skipDoc }
+}
+
+export const SLIDES_SHAPE = shape('slides', 'elements')
+
+/** The shape this module is bound to. Becomes a constructor argument in the
+ * next step; today it is exactly what the file hardcoded before. */
+const S: DocShape = SLIDES_SHAPE
+
+/** The parent array of a document, and the child array of a parent. Indexed
+ * access through the descriptor: `d['slides']` is the same lookup `d.slides`
+ * was, so these are byte-neutral by construction. */
+const P = (d: BentoDoc): Slide[] => (d as unknown as Record<string, Slide[]>)[S.parents]
+const C = (p: Slide): SlideElement[] => (p as unknown as Record<string, SlideElement[]>)[S.children]
+/**
+ * …and the write-back form for the child array.
+ *
+ * There is deliberately no `setP`. The engine mutates the PARENT array only in
+ * place (push/splice/sort), never by assignment — worth knowing, because a
+ * future edit that reassigns it would be replacing the array the caller's
+ * document still points at.
+ */
+const setC = (p: Slide, v: SlideElement[]): void => { (p as unknown as Record<string, SlideElement[]>)[S.children] = v }
+
export const DOC_NODE = '@doc'
/**
@@ -322,11 +397,11 @@ export class SyncState {
* keys) with the null register [0,''] that loses to every real op.
*/
adopt(doc: BentoDoc) {
- const ns = doc.slides.length
- doc.slides.forEach((sl, i) => {
+ const ns = P(doc).length
+ P(doc).forEach((sl, i) => {
if (!this.pos[sl.id]) this.pos[sl.id] = { p: DOC_NODE, o: spreadKey(i, ns), r: [0, ''] }
- const ne = sl.elements.length
- sl.elements.forEach((el, j) => {
+ const ne = C(sl).length
+ C(sl).forEach((el, j) => {
const k = elKey(sl.id, el.id)
if (!this.pos[k]) this.pos[k] = { p: sl.id, o: spreadKey(j, ne), r: [0, ''] }
})
@@ -348,7 +423,7 @@ export class SyncState {
}
// ---- doc-level props
- const SKIP_DOC = new Set(['slides', 'modified', 'collab', 'format', 'version'])
+ const SKIP_DOC = S.skipDoc
const b = before as unknown as Record<string, unknown>
const a = after as unknown as Record<string, unknown>
for (const k of new Set([...Object.keys(b), ...Object.keys(a)])) {
@@ -378,30 +453,30 @@ export class SyncState {
// ---- slides by id; elements by COMPOSITE key (slide + bare id) — the
// same element id on many slides is the morph idiom, each copy is its
// own node. A cross-slide move therefore diffs as del(old)+ins(new).
- const bSlides = new Map(before.slides.map((s) => [s.id, s]))
- const aSlides = new Map(after.slides.map((s) => [s.id, s]))
+ const bSlides = new Map(P(before).map((s) => [s.id, s]))
+ const aSlides = new Map(P(after).map((s) => [s.id, s]))
const bEls = new Map<string, { sl: string; el: SlideElement }>()
const aEls = new Map<string, { sl: string; el: SlideElement }>()
- before.slides.forEach((s) => s.elements.forEach((el) => bEls.set(elKey(s.id, el.id), { sl: s.id, el })))
- after.slides.forEach((s) => s.elements.forEach((el) => aEls.set(elKey(s.id, el.id), { sl: s.id, el })))
+ P(before).forEach((s) => C(s).forEach((el) => bEls.set(elKey(s.id, el.id), { sl: s.id, el })))
+ P(after).forEach((s) => C(s).forEach((el) => aEls.set(elKey(s.id, el.id), { sl: s.id, el })))
// deleted slides (cascade the elements the deleter saw, minus survivors)
for (const [id, sl] of bSlides) {
if (aSlides.has(id)) continue
- const cas = sl.elements.map((e) => elKey(id, e.id)).filter((k) => !aEls.has(k))
+ const cas = C(sl).map((e) => elKey(id, e.id)).filter((k) => !aEls.has(k))
const o = push<DelOp>({ ...this.stamp(), op: 'del', kind: 'slide', id, cas })
this.tombs[id] = [o.l, o.a]
this.stashNode(sl as unknown as Record<string, unknown>, id)
cas.forEach((ek) => {
this.tombs[ek] = [o.l, o.a]
- const node = sl.elements.find((e) => elKey(id, e.id) === ek)
+ const node = C(sl).find((e) => elKey(id, e.id) === ek)
if (node) this.stashNode(node as unknown as Record<string, unknown>, ek)
delete this.limbo[ek]
delete this.txt[ek] // local tomb is the freshest stamp — always out-ranks
})
}
// inserted (or resurrected) slides
- const afterIds = after.slides.map((s) => s.id)
+ const afterIds = P(after).map((s) => s.id)
for (let i = 0; i < afterIds.length; i++) {
const id = afterIds[i]
if (bSlides.has(id)) continue
@@ -412,8 +487,8 @@ export class SyncState {
this.pos[id] = { p: DOC_NODE, o: ord, r: [o.l, o.a] }
delete this.txt[id]
delete this.stash[id] // fresh birth voids parked values (receivers do this in replayStash)
- const ne = sl.elements.length
- sl.elements.forEach((el, j) => {
+ const ne = C(sl).length
+ C(sl).forEach((el, j) => {
const k = elKey(id, el.id)
this.births[k] = [o.l, o.a]
this.pos[k] = { p: id, o: spreadKey(j, ne), r: [o.l, o.a] }
@@ -428,7 +503,7 @@ export class SyncState {
const bp = prev as unknown as Record<string, unknown>
const ap = sl as unknown as Record<string, unknown>
for (const k of new Set([...Object.keys(bp), ...Object.keys(ap)])) {
- if (k === 'elements' || k === 'id') continue
+ if (k === S.children || k === 'id') continue
if (JSON.stringify(bp[k]) === JSON.stringify(ap[k])) continue
const o = push<SetOp>({ ...this.stamp(), op: 'set', sl: id, k, v: clone(ap[k]) })
this.regs[`${id} ${k}`] = [o.l, o.a]
@@ -453,7 +528,7 @@ export class SyncState {
const prev = bEls.get(id)
if (!prev) {
if (this.births[id] && !this.dead(id) && this.pos[id]?.p === sl) continue // came with a fresh slide ins above
- const sib = aSlides.get(sl)!.elements.map((e) => elKey(sl, e.id))
+ const sib = C(aSlides.get(sl)!).map((e) => elKey(sl, e.id))
const ord = this.keyAround(sl, sib, sib.indexOf(id))
const o = push<InsOp>({ ...this.stamp(), op: 'ins', kind: 'element', id, sl, ord, node: clone(el) })
this.births[id] = [o.l, o.a]
@@ -486,7 +561,7 @@ export class SyncState {
// element order within each surviving slide (all ids — see slide pass)
for (const [id, sl] of aSlides) {
if (!bSlides.has(id)) continue
- this.diffOrder(sl.elements.map((e) => elKey(id, e.id)), id, 'element', push)
+ this.diffOrder(C(sl).map((e) => elKey(id, e.id)), id, 'element', push)
}
// remote ops that pended awaiting a seed can resolve against seeds this
@@ -675,14 +750,14 @@ export class SyncState {
}
private findSlide(doc: BentoDoc, id: string): Slide | undefined {
- return doc.slides.find((s) => s.id === id)
+ return P(doc).find((s) => s.id === id)
}
/** composite-key lookup: an element node only ever lives on its key's
* slide (or in limbo) — the same bare id on other slides is other nodes */
private findEl(doc: BentoDoc, key: string): SlideElement | undefined {
const s = this.findSlide(doc, keySlide(key))
const bare = keyEl(key)
- return s?.elements.find((e) => e.id === bare) ?? this.limbo[key]
+ return (s ? C(s) : undefined)?.find((e) => e.id === bare) ?? this.limbo[key]
}
private applySet(doc: BentoDoc, op: SetOp, res: ApplyResult) {
@@ -763,10 +838,10 @@ export class SyncState {
// first ran it, so everyone must.
const src = op.node as Slide
this.insertSlideLevel(doc, op.id, op.ord, src, stamp, res)
- const ne = src.elements.length
- src.elements.forEach((e, j) => this.insertElement(doc, elKey(op.id, e.id), op.id, spreadKey(j, ne), e, stamp, res))
+ const ne = C(src).length
+ C(src).forEach((e, j) => this.insertElement(doc, elKey(op.id, e.id), op.id, spreadKey(j, ne), e, stamp, res))
this.drainPending(doc, op.id)
- src.elements.forEach((e) => this.drainPending(doc, elKey(op.id, e.id)))
+ C(src).forEach((e) => this.drainPending(doc, elKey(op.id, e.id)))
} else {
this.insertElement(doc, op.id, op.sl!, op.ord, op.node as SlideElement, stamp, res)
this.drainPending(doc, op.id)
@@ -787,11 +862,11 @@ export class SyncState {
if (this.dead(id)) return // a delete still out-stamps this insert
const existing = this.findSlide(doc, id)
if (existing) {
- this.assignNode(existing as unknown as Record<string, unknown>, src as unknown as Record<string, unknown>, id, stamp, ['id', 'elements'])
+ this.assignNode(existing as unknown as Record<string, unknown>, src as unknown as Record<string, unknown>, id, stamp, ['id', S.children])
} else {
const sl = clone(src)
- sl.elements = [] // members materialize separately via insertElement
- doc.slides.push(sl)
+ setC(sl, []) // members materialize separately via insertElement
+ P(doc).push(sl)
this.replayStash(sl as unknown as Record<string, unknown>, id, stamp)
}
}
@@ -822,7 +897,7 @@ export class SyncState {
const el = clone(node)
const p = this.pos[id].p
const sl = this.findSlide(doc, p)
- if (sl && !this.dead(p)) sl.elements.push(el)
+ if (sl && !this.dead(p)) C(sl).push(el)
else this.limbo[id] = el
this.replayStash(el as unknown as Record<string, unknown>, id, stamp)
live = el
@@ -935,10 +1010,10 @@ export class SyncState {
if (g && cmpReg(this.tombs[key] ?? [0, ''], g.sd) > 0) delete this.txt[key]
const s = this.findSlide(doc, keySlide(key))
const bare = keyEl(key)
- const i = s ? s.elements.findIndex((e) => e.id === bare) : -1
+ const i = s ? C(s).findIndex((e) => e.id === bare) : -1
if (s && i >= 0) {
- this.stashNode(s.elements[i] as unknown as Record<string, unknown>, key)
- s.elements.splice(i, 1)
+ this.stashNode(C(s)[i] as unknown as Record<string, unknown>, key)
+ C(s).splice(i, 1)
}
}
bump(op.id)
@@ -950,12 +1025,12 @@ export class SyncState {
if (this.dead(eid)) removeElement(eid)
}
if (this.dead(op.id)) {
- const i = doc.slides.findIndex((s) => s.id === op.id)
+ const i = P(doc).findIndex((s) => s.id === op.id)
if (i >= 0) {
- const [gone] = doc.slides.splice(i, 1)
+ const [gone] = P(doc).splice(i, 1)
this.stashNode(gone as unknown as Record<string, unknown>, op.id)
// survivors (concurrently inserted) park in limbo under their key
- for (const el of gone.elements) {
+ for (const el of C(gone)) {
const k = elKey(op.id, el.id)
if (!this.dead(k)) this.limbo[k] = el
}
@@ -1066,13 +1141,13 @@ export class SyncState {
if (a !== b) return a < b ? -1 : 1
return x < y ? -1 : 1
}
- doc.slides.sort((s1, s2) => cmp(s1.id, s2.id))
- const slideById = new Map(doc.slides.map((s) => [s.id, s]))
+ P(doc).sort((s1, s2) => cmp(s1.id, s2.id))
+ const slideById = new Map(P(doc).map((s) => [s.id, s]))
for (const [key, el] of Object.entries(this.limbo)) {
const p = this.pos[key]?.p
if (p && slideById.has(p) && !this.dead(p) && !this.dead(key)) {
const dest = slideById.get(p)!
- if (!dest.elements.some((e) => e.id === el.id)) dest.elements.push(el)
+ if (!C(dest).some((e) => e.id === el.id)) C(dest).push(el)
else dbg(key, `limbo-restore DROP dup x=${(el as any).x}`)
delete this.limbo[key]
this.drainPending(doc, key)
@@ -1081,13 +1156,13 @@ export class SyncState {
// elements never relocate across slides (the composite key pins them to
// one slide for life) — only sort by pos key and dedupe within the slide
// (a node whose data travelled two routes can transiently duplicate)
- for (const sl of doc.slides) {
- sl.elements.sort((e1, e2) => cmp(elKey(sl.id, e1.id), elKey(sl.id, e2.id)))
- sl.elements = sl.elements.filter((e, i) => {
- const dup = i > 0 && e.id === sl.elements[i - 1].id
+ for (const sl of P(doc)) {
+ C(sl).sort((e1, e2) => cmp(elKey(sl.id, e1.id), elKey(sl.id, e2.id)))
+ setC(sl, C(sl).filter((e, i) => {
+ const dup = i > 0 && e.id === C(sl)[i - 1].id
if (dup) dbg(elKey(sl.id, e.id), `remat dedupe DROP x=${(e as any).x}`)
return !dup
- })
+ }))
}
}
@@ -1141,12 +1216,12 @@ export class SyncState {
}
}
// drop nodes that are dead under merged liveness
- for (let i = doc.slides.length - 1; i >= 0; i--) {
- const sl = doc.slides[i]
+ for (let i = P(doc).length - 1; i >= 0; i--) {
+ const sl = P(doc)[i]
if (this.dead(sl.id)) {
- doc.slides.splice(i, 1)
+ P(doc).splice(i, 1)
this.stashNode(sl as unknown as Record<string, unknown>, sl.id)
- for (const el of sl.elements) {
+ for (const el of C(sl)) {
const k = elKey(sl.id, el.id)
if (!this.dead(k)) this.limbo[k] = el
else this.stashNode(el as unknown as Record<string, unknown>, k)
@@ -1154,11 +1229,11 @@ export class SyncState {
res.structure = true
res.changed = true
} else {
- for (let j = sl.elements.length - 1; j >= 0; j--) {
- const k = elKey(sl.id, sl.elements[j].id)
+ for (let j = C(sl).length - 1; j >= 0; j--) {
+ const k = elKey(sl.id, C(sl)[j].id)
if (this.dead(k)) {
- this.stashNode(sl.elements[j] as unknown as Record<string, unknown>, k)
- sl.elements.splice(j, 1)
+ this.stashNode(C(sl)[j] as unknown as Record<string, unknown>, k)
+ C(sl).splice(j, 1)
res.structure = true
res.changed = true
}
@@ -1175,12 +1250,12 @@ export class SyncState {
// keyed composite; remote limbo nodes count — they're invisible but
// their data is real)
const rEls = new Map<string, SlideElement>()
- rdoc.slides.forEach((s) => s.elements.forEach((e) => rEls.set(elKey(s.id, e.id), e)))
+ P(rdoc).forEach((s) => C(s).forEach((e) => rEls.set(elKey(s.id, e.id), e)))
for (const [key, el] of Object.entries(rstate.limbo ?? {})) if (!rEls.has(key)) rEls.set(key, el)
- for (const sl of rdoc.slides) {
+ for (const sl of P(rdoc)) {
if (this.dead(sl.id) || this.findSlide(doc, sl.id)) continue
const copy = clone(sl)
- copy.elements = copy.elements
+ setC(copy, C(copy)
.filter((e) => !this.dead(elKey(sl.id, e.id)))
.map((e) => {
const lb = this.limbo[elKey(sl.id, e.id)]
@@ -1189,8 +1264,8 @@ export class SyncState {
return lb
}
return e
- })
- doc.slides.push(copy)
+ }))
+ P(doc).push(copy)
res.changed = true
res.structure = true
}
@@ -1198,13 +1273,13 @@ export class SyncState {
if (this.dead(key) || this.findEl(doc, key)) continue
const p = this.pos[key]?.p
const host = p ? this.findSlide(doc, p) : undefined
- if (host && !this.dead(host.id)) host.elements.push(clone(el))
+ if (host && !this.dead(host.id)) C(host).push(clone(el))
else this.limbo[key] = clone(el)
res.changed = true
res.structure = true
}
// property registers: the winning side's value lives in its doc
- const rSlides = new Map(rdoc.slides.map((s) => [s.id, s]))
+ const rSlides = new Map(P(rdoc).map((s) => [s.id, s]))
const rNode = (id: string): Record<string, unknown> | undefined =>
id === DOC_NODE
? (rdoc as unknown as Record<string, unknown>)
@@ -1223,7 +1298,7 @@ export class SyncState {
const dst = lNode(id)
if (!src || !dst) continue
const isSlide = rSlides.has(id) || !!this.findSlide(doc, id)
- this.assignNode(dst, src, id, this.births[id], isSlide ? ['id', 'elements'] : ['id'])
+ this.assignNode(dst, src, id, this.births[id], isSlide ? ['id', S.children] : ['id'])
res.changed = true
if (isSlide) res.structure = true
}