Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

14.8 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// The document-shape seam: one engine, two document shapes.
//
//   node scripts/test-sync-shape.ts
//
// WHAT THIS IS FOR. scripts/test-sync-equiv.ts proves the parameterized engine
// still mints the bytes every shipped bento/slides file was written with — it
// is a NEGATIVE property, and a parameterization that quietly did nothing
// would sail through it. Nothing yet proved the POSITIVE one: that binding a
// second shape produces an engine that actually works on a document of that
// shape.
//
// This is that check, and it is deliberately small. The full bento/spaces
// convergence rig belongs with the spaces binding; what belongs here is the
// evidence that the seam is real — because the seam is what the whole
// collaboration project rests on, and "it compiles" is not evidence.
//
// It is also where the constructor contract is pinned: the engine takes its
// shape with NO DEFAULT. A default is precisely how a spaces call site ends up
// silently holding slides' shape, and the resulting room cannot be repaired in
// the field.

import { SyncEngine, SyncState, SLIDES_SHAPE, shape } from '../slides/src/sync/crdt.ts'
import type { DocShape } from '../slides/src/sync/crdt.ts'

let failures = 0
let checks = 0
function ok(cond: boolean, msg: string) {
  checks++
  if (!cond) { failures++; console.log(`  FAIL  ${msg}`) }
  else console.log(`  ok    ${msg}`)
}

console.log('bento-sync — the document-shape seam\n')

/** bento/spaces: pages hold blocks. The binding spaces will ship. */
// Built with `shape()`, not by hand. A literal here omitted `text` when that
// field was added and silently disabled the token RGA for this shape — the
// engine now refuses such a shape, and this rig should model what apps do.
const SPACES_SHAPE: DocShape = shape('pages', 'blocks')
class SpacesSync extends SyncEngine {
  constructor(actor: string) { super(actor, SPACES_SHAPE) }
}

const spacesDoc = (blocks: unknown[]) => ({
  format: 'bento/spaces', version: 1, docId: 'd', title: 'S', home: 'p1',
  pages: [{ id: 'p1', title: 'Page one', blocks }],
}) as never

// ---- a second shape produces a WORKING engine ------------------------------
{
  const A = new SpacesSync('alice')
  const B = new SpacesSync('bob')
  const dA = spacesDoc([{ id: 'b1', type: 'p', html: 'hello' }]) as never as Record<string, never>
  A.adopt(dA as never)
  const dB = JSON.parse(JSON.stringify(dA))
  B.adopt(dB)

  // concurrent: alice types into a block, bob adds one
  const beforeA = JSON.parse(JSON.stringify(dA))
  ;(dA as never as { pages: { blocks: { html: string }[] }[] }).pages[0].blocks[0].html = 'hello world'
  const opsA = A.diff(beforeA, dA as never, { text: true })

  const beforeB = JSON.parse(JSON.stringify(dB))
  dB.pages[0].blocks.push({ id: 'b2', type: 'todo', html: 'a task', done: false })
  const opsB = B.diff(beforeB, dB, { text: true })

  ok(opsA.length === 1 && opsA[0].op === 'txt',
    'a text edit on a BLOCK becomes one RGA delta, exactly as it does for an element')
  ok(String(opsA[0].el) === 'p1' + '\u001f' + 'b1',
    `the node key is the composite pageId\u001fblockId — the page, not the slide (got ${JSON.stringify(String(opsA[0].el))})`)
  ok(opsB.length === 1 && opsB[0].op === 'ins' && opsB[0].sl === 'p1',
    'a new block is an insert parented to its page')

  A.apply(dA as never, opsB)
  B.apply(dB, opsA)
  ok(JSON.stringify(dA) === JSON.stringify(dB), 'the two replicas converge')
  const blocks = (dA as never as { pages: { blocks: { html: string }[] }[] }).pages[0].blocks
  ok(blocks.length === 2 && blocks[0].html === 'hello world',
    'and neither edit was lost: the typed text AND the new block survive')
}

// ---- the shape is per-instance, not per-module -----------------------------
// The failure this prevents is one engine quietly serving both apps with one
// binding, which is unrecoverable once a room exists.
{
  const s = new SyncState('a')
  const p = new SpacesSync('a')
  ok(s.S === SLIDES_SHAPE, 'the slides binding carries the slides shape')
  ok(p.S === SPACES_SHAPE, 'the spaces binding carries the spaces shape')
  ok(s.S !== p.S, 'two engines alive at once do not share one shape')
  ok(SLIDES_SHAPE.skipDoc.has('slides') && SPACES_SHAPE.skipDoc.has('pages'),
    'each shape skips its own container — syncing it as a value would make the whole document one register')
}

// ---- restoring a saved state yields the SAME binding -----------------------
// `static fromJSON` used to construct the base class literally, so a subclass
// restored as something else. For an app binding that means a saved spaces
// file reopening with slides' shape.
{
  const p = new SpacesSync('a')
  const d = spacesDoc([{ id: 'b1', type: 'p', html: 'x' }])
  p.adopt(d)
  const back = SpacesSync.fromJSON('a', p.toJSON())
  ok(back instanceof SpacesSync, 'a restored spaces engine is a spaces engine')
  ok(back.S === SPACES_SHAPE, '…and still carries the spaces shape')
  const slides = SyncState.fromJSON('a', new SyncState('a').toJSON())
  ok(slides instanceof SyncState && slides.S === SLIDES_SHAPE,
    'and the slides binding restores as itself, unchanged')
}

// ---- the slides shape is untouched by any of this --------------------------
{
  ok(SLIDES_SHAPE.parents === 'slides' && SLIDES_SHAPE.children === 'elements',
    'slides still means slides → elements')
  // EXACT pin — any change to the skip set must be deliberate and land here.
  // `revisions` and `trail` joined it with the field-classification ruling
  // (kernel/src/docfields.ts, class 'history'): in-file version history is
  // file-local and never synced. `docId`, `readonly` and `template` joined it
  // because skipDoc is also the RECEIVE filter: identity and file modes are
  // never adopted from a peer. Everything else is the shipped engine's set.
  ok([...SLIDES_SHAPE.skipDoc].sort().join(',') === 'collab,docId,format,modified,policy,readonly,revisions,slides,template,trail,version',
    'and its skip set is exactly the shipped engine set plus history, identity and modes')
}

// ---- stamping WITHOUT the token history ------------------------------------
// bento/spaces will not stamp `txt`: a space is typed prose, and the token
// history costs ×25.8 of the text when it is typed (×0.2 when pasted — the RGA
// only engages for text somebody typed while a session ran). What must be true
// for that to be a safe choice, and is asserted here rather than assumed:
//
//   1. slides is untouched — the default still emits `txt`, byte for byte;
//   2. omitting it actually shrinks the stamp, by the order claimed;
//   3. a state restored WITHOUT it still CONVERGES. Only the granularity
//      degrades: last-writer-wins per block instead of per character.
//
// (3) is the one that would sink the idea, so it is measured, not argued.
{
  const doc = spacesDoc([{ id: 'b1', type: 'p', html: '' }]) as never as
    { pages: { blocks: { html: string }[] }[] }
  const A = new SpacesSync('alice')
  A.adopt(doc as never)
  // TYPE it, in runs, which is what mints tokens
  const text = 'the quick brown fox jumps over a lazy dog and keeps on going '.repeat(6)
  for (let c = 0; c < text.length; c += 40) {
    const before = JSON.parse(JSON.stringify(doc))
    doc.pages[0].blocks[0].html = text.slice(0, c + 40)
    A.diff(before, doc as never, { text: true })
  }

  const withText = JSON.stringify(A.toJSON())
  const without = JSON.stringify(A.toJSON({ text: false, unsafeOmitTextHistory: true }))
  ok(withText.includes('"txt"'), 'the default stamp carries the token history')
  ok(!without.includes('"txt"'), 'and `text: false` leaves it out entirely')
  ok(without.length * 5 < withText.length,
    `omitting it is worth having: ${withText.length} B → ${without.length} B ` +
    `(×${(withText.length / without.length).toFixed(1)} smaller)`)

  // the slides binding must be byte-identical to what it always emitted
  const sl = new SyncState('a')
  sl.adopt({ slides: [{ id: 's1', elements: [{ id: 'e1', type: 'text', html: 'x' }] }] } as never)
  ok(JSON.stringify(sl.toJSON()).includes('"txt":'),
    'the slides binding still stamps txt by default — every field file was written that way')

  // (3) CONVERGENCE, from a stamp with no token history
  // DIFFERENT actor ids: two replicas sharing one is not a configuration the
  // engine supports (it skips its own ops on apply), and a test that gets that
  // wrong reports a divergence the field would never see.
  const reopen = (actor: string, stamp: string) => {
    const d = JSON.parse(JSON.stringify(doc))
    const st = SpacesSync.fromJSON(actor, JSON.parse(stamp))
    return { d, st }
  }
  const X = reopen('xavier', without)
  const Y = reopen('yasmin', without)
  const editX = JSON.parse(JSON.stringify(X.d))
  X.d.pages[0].blocks[0].html = text + ' — and X adds this'
  const opsX = X.st.diff(editX, X.d, { text: true })
  const editY = JSON.parse(JSON.stringify(Y.d))
  Y.d.pages[0].blocks.push({ id: 'b2', type: 'p', html: 'Y adds a block' })
  const opsY = Y.st.diff(editY, Y.d, { text: true })

  X.st.apply(X.d, opsY)
  Y.st.apply(Y.d, opsX)
  ok(JSON.stringify(X.d) === JSON.stringify(Y.d),
    'two replicas restored from a txt-less stamp still CONVERGE')
  ok(X.d.pages[0].blocks.length === 2 && X.d.pages[0].blocks[0].html.endsWith('X adds this'),
    'and neither edit was lost — different blocks still merge')
  // NOT a fallback to whole-value sets, as first assumed: the differ RE-SEEDS a
  // generation from the current content, and two replicas that both re-seed
  // from the same content derive the same seed — so they still merge per
  // character. Measured on a shared paragraph: "Friday"→"Monday" from one and
  // an appended sentence from the other, both kept, byte-identical on both
  // sides, from a stamp 10.9× smaller.
  ok(opsX.length === 1 && opsX[0].op === 'txt',
    `a re-seeded generation still merges per character (op was ${opsX[0]?.op})`)

  // ------------------------------------------------------------------------
  // AND THE PRECONDITION THAT MAKES IT SAFE, pinned because getting it wrong
  // is not a degradation — it is a SPLIT BRAIN.
  //
  // A replica that re-seeds meets a peer still holding the ORIGINAL generation
  // (a live session keeps the tokens in memory), the two generations duel as
  // units, and the loser's edit disappears — measured: the two documents do
  // NOT converge. So a lean stamp is only safe when EVERY participant is lean.
  //
  // The session layer must therefore treat "restored without txt" as
  // `needs a snapshot`, not as `resume` — rejoin by taking a peer's snapshot
  // (mergeSnapshot) rather than replaying from where the file left off. That
  // rule does not exist yet because spaces has no session; this assertion is
  // here so it cannot be forgotten when it is written.
  {
    const full = JSON.parse(JSON.stringify(A.toJSON()))
    const lean = JSON.parse(JSON.stringify(A.toJSON({ text: false, unsafeOmitTextHistory: true })))
    ok(!!full.txt && !lean.txt, 'the two stamps differ only in the token history')
    const keptGeneration = Object.keys(full.txt ?? {}).length
    ok(keptGeneration > 0,
      `a typed paragraph has a generation to lose (${keptGeneration} node(s) with token history)`)
  }
}

// ---------------------------------------------------------------------------
// PINNED (finding, 2026-09-17): the reunion path the section above PRESCRIBES
// for a lean stamp — "rejoin by taking a peer's snapshot (mergeSnapshot)" —
// LOSES an edit to a DIFFERENT block. A txt edit advances the node's text
// generation but not its html LWW register; a text:false stamp drops the
// generation, so mergeSnapshot has no stamped carrier for the edit and keeps
// the base value. This is a NEGATIVE CONTROL: it asserts the loss so the loss
// is not silent, and so the day the engine carries a stamped html register
// through a lean stamp, THESE assertions flip and must be inverted.
// docs/DECISIONS.md 2026-09-17. No shipping path stamps lean — this is latent.
{
  const clone = <T,>(v: T): T => JSON.parse(JSON.stringify(v))
  const threeBlocks = () => spacesDoc([
    { id: 'b0', type: 'p', html: 'zero' },
    { id: 'b1', type: 'p', html: 'one' },
    { id: 'b2', type: 'p', html: 'two' },
  ]) as never as { pages: { blocks: { id: string; html: string }[] }[] }
  const editBlock = (eng: SpacesSync, d: { pages: { blocks: { html: string }[] }[] }, i: number, html: string) => {
    const n = clone(d); n.pages[0].blocks[i].html = html
    eng.diff(d as never, n as never, { text: true })
    d.pages[0].blocks[i].html = html
  }

  const origin = new SpacesSync('origin'); origin.adopt(threeBlocks() as never)
  // the saved file both forks open — LEAN, spaces' would-be size optimisation
  const saved = JSON.stringify(origin.toJSON({ text: false, unsafeOmitTextHistory: true }))

  const X = SpacesSync.fromJSON('xavier', JSON.parse(saved))
  const Y = SpacesSync.fromJSON('yasmin', JSON.parse(saved))
  const dx = threeBlocks(), dy = threeBlocks()
  editBlock(X, dx, 1, 'one — FROM-X')   // X edits block b1
  editBlock(Y, dy, 2, 'two — FROM-Y')   // Y edits block b2 — a DIFFERENT block
  // X reunites by taking Y's LEAN snapshot (the prescribed rejoin for lean stamps)
  X.mergeSnapshot(dx as never, clone(dy) as never, Y.toJSON({ text: false, unsafeOmitTextHistory: true }))
  ok(dx.pages[0].blocks[1].html === 'one — FROM-X', "X keeps its own edit through the reunion")
  ok(!dx.pages[0].blocks[2].html.includes('FROM-Y'),
    `KNOWN LOSS: a lean-stamp snapshot reunion drops the peer's DIFFERENT-block edit ` +
    `(b2 is ${JSON.stringify(dx.pages[0].blocks[2].html)}) — invert when the engine fix lands`)

  // the SAME reunion with a FULL snapshot keeps it — proving the loss is the
  // dropped token history, not the merge.
  const X2 = SpacesSync.fromJSON('xavier', JSON.parse(saved))
  const dx2 = threeBlocks()
  editBlock(X2, dx2, 1, 'one — FROM-X')
  X2.mergeSnapshot(dx2 as never, clone(dy) as never, Y.toJSON())
  ok(dx2.pages[0].blocks[2].html.includes('FROM-Y'),
    'a FULL (text:true) snapshot of the very same edit is KEPT — the loss is the missing history, not mergeSnapshot')
}

// ---- the guard: a lean stamp is REFUSED without acknowledgement -------------
// The wall that keeps a future size optimisation from wiring stampInto to the
// silent loss above.
{
  const A = new SpacesSync('a'); A.adopt(spacesDoc([{ id: 'b1', type: 'p', html: 'x' }]) as never)
  let threw = false
  try { A.toJSON({ text: false }) } catch { threw = true }
  ok(threw, 'toJSON({ text: false }) REFUSES without unsafeOmitTextHistory — the footgun hits a wall, not a silent loss')
  let ok2 = false
  try { A.toJSON({ text: false, unsafeOmitTextHistory: true }); ok2 = true } catch { /* */ }
  ok(ok2, 'and the acknowledged form is allowed — the rigs, and a future engine fix, opt in explicitly')
}

console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)