Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
#!/usr/bin/env node
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// The trail, the periods, and the three charts drawn from them.
//
// node scripts/test-spaces-trail.ts
// TZ=Pacific/Kiritimati node scripts/test-spaces-trail.ts
//
// RUN UNDER SEVERAL TIMEZONES, alongside the journal and calc rigs, for the
// reason those two are: a row key is a LOCAL day, and a date bug that only
// appears east of UTC passes every assertion written in UTC. Kiritimati is
// UTC+14 and Niue is UTC-11 — between them they bracket every hour of the day
// where "which day is it" has two answers.
//
// EVERY ASSERTION HERE IS BEHAVIOURAL. This zone has measured, twice, that a
// source-grep assertion passes straight through a live regression: the literal
// stayed in the file while the dispatch changed underneath it, 826/826 green.
// So these build a document, write rows into it, draw the chart, and assert on
// the numbers and the geometry that come back.
import {
isDay, dayIndex, addDays, daysBetween, weekKey, monthKey, dayRange,
trailKey, parseTrailKey, trailOf, trailIsForeign, seriesRows, slots,
writeRow, backfill, clearTrail,
pruneTrail, trailBytes,
wasCut, spanOf, countOf, TRAIL_BUDGET, TRAIL_MAX,
type Trail, type TrailRow,
} from '../spaces/src/trail.ts'
import { foldDottedMapKeys, DOC_MAPS } from '../spaces/src/docmaps.ts'
import { SPACES_FIELDS, SPACES_NOT_EDIT } from '../spaces/src/docclass.ts'
import { HISTORY_BUDGET, recordRevision, historyBytes } from '../spaces/src/history.ts'
import { observe, recordTrail, estimateField } from '../spaces/src/observe.ts'
import {
periodsOf, periodOf, startPeriod, closePeriod, removePeriod, isLive,
protectedDays, isPeriod,
} from '../spaces/src/periods.ts'
import { chartData, chartKind, CHART_KINDS } from '../spaces/src/charts.ts'
import { parseDoc, docContentKey, docForExport, FORMAT, type SpacesDoc, type Page } from '../spaces/src/model.ts'
import { extractSpace } from '../spaces/src/portable.ts'
import { DEFAULT_FIELDS } from '../spaces/src/fields.ts'
import { SPEC } from '../spaces/src/blocks.ts'
import { SPACES_SHAPE, SyncState } from '../spaces/src/sync/crdt.ts'
// BUNDLED (scripts/test-spaces.mjs): store.ts imports './model' without an
// extension, which node's strip-only TypeScript loader will not follow.
import { Store } from '../spaces/src/store.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}`)
}
const TZ = process.env.TZ ?? Intl.DateTimeFormat().resolvedOptions().timeZone
console.log(`bento/spaces trail (TZ=${TZ})\n`)
// ---------------------------------------------------------------------------
// fixtures
// ---------------------------------------------------------------------------
let seq = 0
const issue = (status: string, estimate?: number): Page => {
const id = `i${++seq}`
const blocks: Page['blocks'] = [
{ id: `${id}-s`, type: 'prop', key: 'status', value: status, html: `Status: ${status}` } as never,
]
if (estimate !== undefined) {
blocks.push({ id: `${id}-e`, type: 'prop', key: 'estimate', value: estimate, html: `Estimate: ${estimate}` } as never)
}
return { id, title: `Issue ${id}`, blocks }
}
function docOf(pages: Page[], extra: Partial<SpacesDoc> = {}): SpacesDoc {
return {
format: FORMAT,
version: 1,
docId: 'doc-rig',
title: 'Rig space',
pages,
theme: { background: '#fff', color: '#000', accent: '#F7A600', fontFamily: 'sans-serif' },
...extra,
} as SpacesDoc
}
/** A tracker: three open, two done, all estimated. */
const tracker = () => {
seq = 0
return docOf([
issue('todo', 3), issue('doing', 5), issue('todo', 2),
issue('done', 8), issue('cancelled', 1),
])
}
// ---------------------------------------------------------------------------
// 1. day arithmetic — the label is the thing, and it has no timezone
// ---------------------------------------------------------------------------
{
ok(isDay('2026-09-11'), 'a real day is a day')
ok(!isDay('2026-13-99'), 'a digit-shaped non-date is rejected, not rolled over')
ok(!isDay('2026-02-30'), 'the 30th of February is rejected')
ok(!isDay('2026-9-1') && !isDay('') && !isDay(undefined), 'loose shapes are rejected')
// THE BUG THIS EXISTS TO CATCH: at UTC+14 and at UTC-11, one label must be
// one number. `new Date('2026-01-01')` is UTC midnight, so anything that
// round-trips a label through a local Date drifts by a day in half the world.
ok(dayIndex('1970-01-01') === 0, 'the epoch label is day 0 whatever TZ this is')
ok(dayIndex('2026-01-01') === 20454, '2026-01-01 is the same ordinal in every timezone')
ok(addDays('2026-01-01', -1) === '2025-12-31', 'a day before new year is the year before')
ok(addDays('2026-02-28', 1) === '2026-03-01', '2026 is not a leap year')
ok(addDays('2024-02-28', 1) === '2024-02-29', '2024 is')
// DST boundaries: 86,400,000 ms is not a day in Berlin in March, and this
// must not care.
ok(addDays('2026-03-28', 1) === '2026-03-29', 'the European DST boundary steps by one')
ok(addDays('2026-11-01', 1) === '2026-11-02', 'the American one steps by one')
ok(daysBetween('2026-01-01', '2026-12-31') === 364, 'a non-leap year is 364 steps end to end')
ok(daysBetween('2026-09-11', '2026-09-10') === -1, 'backwards is negative, not an error')
ok(weekKey('2026-09-07') === weekKey('2026-09-13'), 'Monday and the Sunday after share an ISO week')
ok(weekKey('2026-09-13') !== weekKey('2026-09-14'), 'Monday starts a new one')
ok(monthKey('2026-09-30') === '2026-09' && monthKey('2026-10-01') === '2026-10', 'months split at the 1st')
ok(dayRange('2026-09-01', '2026-09-03').join(',') === '2026-09-01,2026-09-02,2026-09-03', 'a range is inclusive')
ok(dayRange('2026-09-03', '2026-09-01').length === 0, 'a backwards range is empty, and does not throw')
ok(dayRange('nonsense', '2026-09-01').length === 0, 'a malformed range is empty')
}
// ---------------------------------------------------------------------------
// 2. keys
// ---------------------------------------------------------------------------
{
ok(trailKey('2026-09-11') === '2026-09-11', 'the default series is a bare date')
ok(trailKey('2026-09-11', 'apollo') === 'apollo/2026-09-11', 'a series prefixes the key')
const a = parseTrailKey('apollo/2026-09-11')
ok(a?.series === 'apollo' && a.day === '2026-09-11', 'a series key parses back')
const b = parseTrailKey('2026-09-11')
ok(b?.series === '' && b.day === '2026-09-11', 'a bare key is the default series')
ok(parseTrailKey('2026-13-99') === null, 'a key that is not a day is not a key')
ok(parseTrailKey('a/b/2026-09-11') === null, 'a shape from a newer build is left alone')
}
// ---------------------------------------------------------------------------
// 3. observation — one counting rule, the board's
// ---------------------------------------------------------------------------
{
const doc = tracker()
const obs = observe(doc)!
ok(!!obs, 'a space with a status field is observed')
ok(obs.n.todo === 2 && obs.n.doing === 1 && obs.n.done === 1 && obs.n.cancelled === 1,
'counts are per status OPTION id, not per phase group')
ok(obs.e?.todo === 5 && obs.e?.done === 8, 'estimates are summed per option')
ok(obs.x === undefined, 'no unestimated issues, so no x')
// ARCHIVED PAGES ARE EXCLUDED — because viewRows excludes them, which is the
// whole point of using the board's own counter.
const arch = tracker()
arch.pages[0].archived = true
ok(observe(arch)!.n.todo === 1, 'an archived issue leaves the count')
// UNESTIMATED
const mixed = docOf([issue('todo', 3), issue('todo')])
const m = observe(mixed)!
ok(m.n.todo === 2 && m.e?.todo === 3 && m.x === 1, 'an unestimated issue is counted in n and in x')
// NOT A TRACKER. `fieldsOf` falls back to DEFAULT_FIELDS while `doc.fields`
// is absent, so the phase field is found — and the observation is EMPTY,
// because a notes space has no issues. That is what makes tracking implicit
// without turning itself on: no issues, no counts, no row (asserted below).
const notes = docOf([{ id: 'p1', title: 'Notes', blocks: [{ id: 'b1', type: 'p', html: 'hello' }] }])
ok(Object.keys(observe(notes)!.n).length === 0, 'a space with no issues observes nothing')
// a document that DECLARES a schema with no phased field has no notion of
// open at all, and is not observed
const unphased = docOf([issue('todo', 1)], { fields: [{ key: 'tag', label: 'Tag', vt: 'text' }] } as never)
ok(observe(unphased) === null, 'a schema that declares no phase field is not observed at all')
// an unknown status counts under its own literal
const future = docOf([issue('shipped')])
ok(observe(future)!.n.shipped === 1, "a status this build does not know is counted literally")
ok(estimateField(tracker())?.key === 'estimate', 'the estimate field is derived from the schema')
ok(DEFAULT_FIELDS.some((f) => f.key === 'status'), 'the default schema still declares status')
}
// ---------------------------------------------------------------------------
// 4. writing — idempotent within a day, and never on open
// ---------------------------------------------------------------------------
{
const doc = tracker()
ok(doc.trail === undefined, 'a fresh tracker carries no trail key at all')
recordTrail(doc, { today: '2026-09-11' })
recordTrail(doc, { today: '2026-09-11' })
recordTrail(doc, { today: '2026-09-11' })
ok(Object.keys(trailOf(doc)).length === 1, 'three writes on one day produce exactly one key')
ok(trailOf(doc)['2026-09-11'].n.todo === 2, 'and it holds the observation')
// the LAST observation of the day wins
;(doc.pages[0].blocks[0] as { value: string }).value = 'done'
recordTrail(doc, { today: '2026-09-11' })
ok(trailOf(doc)['2026-09-11'].n.todo === 1, "a day's row is the LAST observation of that day")
// NOT A TRACKER, NO ROWS
const notes = docOf([{ id: 'p1', title: 'Notes', blocks: [{ id: 'b1', type: 'p', html: 'x' }] }])
recordTrail(notes, { today: '2026-09-11' })
ok(notes.trail === undefined, 'a notes space writes no rows and gains no key')
// A FOREIGN TRAIL IS NEVER WRITTEN OVER
const foreign = tracker()
;(foreign as Record<string, unknown>).trail = 'something a newer build meant'
ok(trailIsForeign(foreign), 'a non-object trail is foreign')
recordTrail(foreign, { today: '2026-09-11' })
ok(foreign.trail === 'something a newer build meant', 'and it is left exactly as it was found')
}
// ---------------------------------------------------------------------------
// 5. EDITING THE PAST DOES NOT REWRITE IT
// ---------------------------------------------------------------------------
{
const doc = tracker()
recordTrail(doc, { today: '2026-09-09' })
recordTrail(doc, { today: '2026-09-10' })
const before = JSON.stringify(trailOf(doc)['2026-09-09'])
const before10 = JSON.stringify(trailOf(doc)['2026-09-10'])
// change an estimate, close an issue, add an issue — everything a day of work
// does — and then write today.
;(doc.pages[0].blocks[1] as { value: number }).value = 99
;(doc.pages[1].blocks[0] as { value: string }).value = 'done'
doc.pages.push(issue('todo', 13))
recordTrail(doc, { today: '2026-09-11' })
ok(JSON.stringify(trailOf(doc)['2026-09-09']) === before, "yesterday's row is byte-identical after today's edits")
ok(JSON.stringify(trailOf(doc)['2026-09-10']) === before10, 'and so is the day before that')
ok(trailOf(doc)['2026-09-11'].e!.todo === 114, "today's row moved, because today is what changed")
// BACKFILL REFUSES TO OVERWRITE
const row: TrailRow = { n: { todo: 1 } }
ok(backfill(doc, '2026-09-09', row) === false, 'backfill refuses a key that is already there')
ok(JSON.stringify(trailOf(doc)['2026-09-09']) === before, 'and changed nothing when it refused')
ok(backfill(doc, '2026-09-01', row) === true, 'backfill writes an absent past key')
}
// ---------------------------------------------------------------------------
// 6. GAPS DRAW AS GAPS — the load-bearing assertion
// ---------------------------------------------------------------------------
{
const doc = tracker()
const trail: Trail = {
'2026-09-01': { n: { todo: 4 } },
'2026-09-02': { n: { todo: 3 } },
// 03, 04, 05 NOT RECORDED — nobody opened the file
'2026-09-06': { n: { todo: 1 } },
}
doc.trail = trail
const s = slots(trail, '2026-09-01', '2026-09-06')
ok(s.length === 6, 'six days, six slots')
ok(s[2].kind === 'gap' && s[3].kind === 'gap' && s[4].kind === 'gap', 'the three unrecorded days are gaps')
ok(s[2].row === undefined, 'a gap carries no row — there is nothing to carry')
ok(s[0].kind === 'day' && s[0].anchor, 'an observed day is a day')
const period = { label: 'Sprint', from: '2026-09-01', to: '2026-09-06' }
// today is AFTER the window, so nothing is derived live and the whole chart
// comes from the record
const data = chartData(doc, period, 'burndown', '2026-09-20')
ok(data.runs.length === 2, 'a gap BREAKS the line: two runs, not one')
ok(data.runs[0].length === 2 && data.runs[1].length === 1, 'two points before the gap, one after')
ok(data.gaps.length === 1 && data.gaps[0][0] === '2026-09-03' && data.gaps[0][1] === '2026-09-05',
'the gap is reported as its own range, for the hatched band')
// THE FAILURE THIS RIG EXISTS FOR: an absent day must never become a zero.
const values = data.runs.flat().map((p) => p.v[0])
ok(!values.includes(0), 'no zero point was invented for an unrecorded day')
ok(values.length === 3, 'exactly three points — one per recorded day, none per gap')
ok(data.runs.every((r) => r.every((p) => p.kind === 'day')),
'nothing was carried forward: every point is a day someone observed')
// ABSENT IS NOT ZERO, and they must be distinguishable
const withZero = { ...trail, '2026-09-04': { n: {} } as TrailRow }
const zdata = chartData(docOf(doc.pages, { trail: withZero }), period, 'burndown', '2026-09-20')
ok(zdata.runs.flat().some((p) => p.v[0] === 0), 'a day with nothing open IS a point at zero')
ok(zdata.gaps.length === 2, 'and the days either side of it are still two separate gaps')
}
// ---------------------------------------------------------------------------
// 7. THINNED ROWS ARE A THIRD STATE
// ---------------------------------------------------------------------------
{
const doc = tracker()
const trail: Trail = {
'2026-09-01': { n: { todo: 9 } },
'2026-09-08': { n: { todo: 5 }, s: 8 }, // stands for 09-01..09-08
'2026-09-09': { n: { todo: 4 } },
}
doc.trail = trail
const s = slots(trail, '2026-09-01', '2026-09-09')
ok(s[1].kind === 'sample' && !s[1].anchor, 'a covered day is a sample, and not a point')
ok(s[7].kind === 'sample' && s[7].anchor, 'the sample row anchors on its own day')
ok(s.every((x) => x.kind !== 'gap'), 'a span covers its days: no gap inside it')
ok(s[0].anchor && s[0].kind === 'day', 'a span never buries a day that was observed in its own right')
const data = chartData(doc, { label: 's', from: '2026-09-01', to: '2026-09-09' }, 'burndown', '2026-09-30')
ok(data.runs.length === 1, 'a covered span does not break the line')
ok(data.runs[0].map((p) => p.kind).join(',') === 'day,sample,day',
'the sample point is marked as one, so its segment can be drawn dashed')
}
// ---------------------------------------------------------------------------
// 8. the budget — tiers, never fails, never averages
// ---------------------------------------------------------------------------
{
// THE TRAIL'S OWN CEILING, beside history's. 128 KB + 32 KB = the 160 KB
// joint ceiling that was ruled acceptable; each side tiers on its own.
ok(TRAIL_BUDGET === 32 * 1024, `TRAIL_BUDGET is 32 KB (${TRAIL_BUDGET} B)`)
ok(HISTORY_BUDGET + TRAIL_BUDGET <= 160 * 1024,
`history + trail ceilings sum to at most 160 KB (${(HISTORY_BUDGET + TRAIL_BUDGET) / 1024} KB)`)
// a year of daily rows, measured
//
// THE COUNTS VARY PER DAY, and that is not decoration. With a uniform
// fixture the "never averages" assertion below passes VACUOUSLY — the mean
// of two identical rows is that row — and this rig watched a deliberate
// averaging sabotage sail straight through it before the numbers were made
// to move. An assertion nobody has seen fail is not evidence.
const year: Trail = {}
for (let i = 0; i < 365; i++) {
year[addDays('2026-01-01', i)] = {
n: { backlog: 12 + (i % 7), todo: 9 + (i % 5), doing: 4 + (i % 3), review: 2, done: 31 + i, cancelled: 3 },
e: { backlog: 40 + i, todo: 27 + (i % 11), doing: 13, review: 5, done: 96 + i, cancelled: 8 },
x: 4,
}
}
const yearBytes = JSON.stringify(year).length
console.log(` · a year of full daily rows: ${yearBytes} bytes (${(yearBytes / 1024).toFixed(1)} KB), ` +
`${Math.round(yearBytes / 365)} bytes/row`)
const countOnly: Trail = {}
for (const k of Object.keys(year)) countOnly[k] = { n: year[k].n }
console.log(` · counts only: ${JSON.stringify(countOnly).length} bytes ` +
`(${(JSON.stringify(countOnly).length / 1024).toFixed(1)} KB)`)
// TIERING: over the allowance, resolution goes from the distant past first.
const pruned = pruneTrail(year, 20 * 1024)
ok(JSON.stringify(pruned).length <= 20 * 1024, 'pruning brings the trail under its allowance')
ok(Object.keys(pruned).length > 0, 'and it tiers rather than failing to nothing')
ok(Object.keys(pruned).length < 365, 'rows were dropped')
// NEVER AVERAGES: every surviving row's counts equal some original row's.
const originals = new Set(Object.values(year).map((r) => JSON.stringify(r.n)))
const invented = Object.values(pruned).filter((r) => !originals.has(JSON.stringify(r.n)))
ok(invented.length === 0, 'every surviving row is an observation somebody made, never an average')
// the dropped-from-the-front flag
ok(wasCut(pruned), 'the oldest survivor is stamped cut, so the chart says "recording starts here"')
const cutCount = Object.values(pruned).filter((r) => r.cut).length
ok(cutCount === 1, 'exactly one row carries it')
// spans are stamped and are truthful: a row never claims to cover a day
// before the earliest row it replaced
const kept = seriesRows(pruned)
let truthful = true
for (let i = 1; i < kept.length; i++) {
const back = spanOf(kept[i].row) - 1
if (daysBetween(kept[i - 1].day, kept[i].day) < back) truthful = false
}
ok(truthful, 'no span reaches back over another surviving row')
// MONOTONIC: a tighter allowance is never bigger
const sizes = [40 * 1024, 20 * 1024, 8 * 1024, 2 * 1024]
.map((b) => JSON.stringify(pruneTrail(year, b)).length)
ok(sizes.every((v, i) => i === 0 || v <= sizes[i - 1]), 'a tighter allowance never produces a bigger trail')
// THE ROW CAP
ok(Object.keys(pruneTrail(year, 10 * 1024 * 1024, 30)).length <= 30, 'the row cap holds however roomy the budget')
ok(TRAIL_MAX === 400, 'and the default cap is 400 rows')
// A LIVE PERIOD IS NOT THINNED UNDERNEATH ITSELF
const live = new Set(dayRange('2026-12-01', '2026-12-31'))
const guarded = pruneTrail(year, 4 * 1024, TRAIL_MAX, (d) => live.has(d))
const keptLive = Object.keys(guarded).filter((k) => live.has(k))
ok(keptLive.length === 31, "every day of a running period survives, at full resolution")
ok(keptLive.every((k) => guarded[k].s === undefined), 'and none of them was turned into a sample')
}
// ---------------------------------------------------------------------------
// 9. periods
// ---------------------------------------------------------------------------
{
const doc = tracker()
const id = startPeriod(doc, 'pd-1', {
label: 'Sprint 12', from: '2026-09-07', to: '2026-09-20', today: '2026-09-11',
})
ok(id === 'pd-1', 'a period is committed under the id it was given')
const p = periodOf(doc, 'pd-1')!
ok(p.base!.n === 5, 'the baseline is a TOTAL, not a list of page ids')
ok(p.base!.e === 19, 'and the summed estimate')
ok(p.base!.at === '2026-09-11', 'base.at records the day the baseline was ACTUALLY taken')
ok(JSON.stringify(p).indexOf('i1') < 0, 'no page id appears anywhere in a period')
ok(trailOf(doc)['2026-09-11'] !== undefined, "committing inside the window writes today's row")
ok(trailOf(doc)['2026-09-07'] === undefined, 'and fabricates no past key — the days before are gaps')
// malformed periods are not periods
ok(startPeriod(doc, 'pd-x', { label: 'x', from: '2026-09-20', to: '2026-09-07', today: '2026-09-11' }) === null,
'a period whose `to` precedes its `from` is refused')
ok(!isPeriod({ label: 'x', from: '2026-13-99', to: '2026-09-07' }), 'and one with a non-date is not a period')
ok(!isPeriod(null) && !isPeriod('x') && !isPeriod([]), 'neither is anything that is not an object')
const junk = docOf([], { periods: { bad: { from: '2026-09-20', to: '2026-09-01', label: 'x' } } as never })
ok(Object.keys(periodsOf(junk)).length === 0, 'an unreadable period is simply not returned')
ok(junk.periods !== undefined, 'and is left in the file untouched')
ok(isLive(p, '2026-09-25'), 'a period is live while it runs')
ok(isLive(p, '2026-10-10'), 'and for thirty days after')
ok(!isLive(p, '2026-11-30'), 'and not forever')
closePeriod(doc, 'pd-1')
ok(!isLive(periodOf(doc, 'pd-1')!, '2026-09-08'), 'closing one ends it immediately')
const guard = protectedDays(doc, '2026-09-11')
ok(!guard('2026-09-08'), 'a closed period protects nothing')
startPeriod(doc, 'pd-2', { label: 'now', from: '2026-09-07', to: '2026-09-20', today: '2026-09-11' })
const guard2 = protectedDays(doc, '2026-09-11')
ok(guard2('2026-09-08') && !guard2('2026-08-08'), 'a live one protects its own window and nothing else')
removePeriod(doc, 'pd-1')
removePeriod(doc, 'pd-2')
ok(doc.periods === undefined, 'removing the last period deletes the key — never an empty object')
}
// ---------------------------------------------------------------------------
// 10. the charts
// ---------------------------------------------------------------------------
{
const doc = tracker()
const period = { label: 'S', from: '2026-09-01', to: '2026-09-10', base: { at: '2026-09-01', n: 5, e: 19 } }
doc.trail = {
'2026-09-01': { n: { todo: 3, done: 1 }, e: { todo: 10, done: 8 } },
'2026-09-02': { n: { todo: 2, done: 2 }, e: { todo: 6, done: 12 } },
}
const burn = chartData(doc, period, 'burndown', '2026-09-30')
ok(burn.units === 'points', 'rows carrying estimates are charted in points')
ok(burn.runs[0][0].v[0] === 10 && burn.runs[0][1].v[0] === 6, 'a burndown draws the OPEN work remaining')
ok(burn.ideal === 19, 'the ideal line starts at the committed baseline')
ok(burn.bands.length === 1, 'one line')
const up = chartData(doc, period, 'burnup', '2026-09-30')
ok(up.bands.length === 2, 'a burnup draws two lines')
ok(up.runs[0][0].v[0] === 8 && up.runs[0][0].v[1] === 18, 'completed, and total scope')
ok(up.committed?.v === 19 && up.committed.at === '2026-09-01', 'plus the committed scope, and when it was committed')
const cfd = chartData(doc, period, 'cfd', '2026-09-30')
ok(cfd.bands.length === 6, 'a CFD has a band per declared status option')
ok(cfd.bands.map((b) => b.id).join(',') === 'backlog,todo,doing,review,done,cancelled',
'in the schema order the board declares')
ok(cfd.runs[0][0].v[cfd.bands.findIndex((b) => b.id === 'todo')] === 10, 'each band carries its own option')
// counts, when nothing is estimated
const plain = docOf(doc.pages, { trail: { '2026-09-01': { n: { todo: 3, done: 1 } } } })
ok(chartData(plain, period, 'burndown', '2026-09-30').units === 'issues',
'rows with no estimates are charted as issue counts')
// AN OPTION THE SCHEMA NO LONGER DECLARES
const drifted = docOf(doc.pages, { trail: { '2026-09-01': { n: { blocked: 2 } } } })
const d = chartData(drifted, period, 'cfd', '2026-09-30')
ok(d.bands.some((b) => b.unknown && b.id === 'blocked'), 'a band whose option is gone is kept and marked unknown')
// TODAY IS DERIVED, NOT READ
const live = tracker()
live.trail = { '2026-09-11': { n: { todo: 999 }, e: { todo: 999 } } }
const before = chartData(live, { label: 'S', from: '2026-09-10', to: '2026-09-12' }, 'burndown', '2026-09-11')
const todayPoint = before.runs.flat().find((p) => p.day === '2026-09-11')!
ok(todayPoint.live === true, "today's point is marked derived")
ok(todayPoint.v[0] === 10, 'and it is counted from live state, not read from the stored 999')
;(live.pages[0].blocks[1] as { value: number }).value = 100
const after = chartData(live, { label: 'S', from: '2026-09-10', to: '2026-09-12' }, 'burndown', '2026-09-11')
ok(after.runs.flat().find((p) => p.day === '2026-09-11')!.v[0] === 107,
'change an estimate now and today moves immediately — the falsifiable half of the rule')
// the future is not drawn
ok(!after.runs.flat().some((p) => p.day > '2026-09-11'), 'a burndown does not draw the future')
// a period whose window holds nothing
const empty = chartData(tracker(), { label: 'S', from: '2026-01-01', to: '2026-01-10' }, 'burndown', '2026-09-11')
ok(empty.empty === true, 'a window with no observation says so instead of drawing an empty graph')
// MALFORMED ROWS MUST NOT THROW AND MUST NOT MISLEAD
const nasty = docOf(doc.pages, {
trail: {
'2026-09-01': { n: { todo: -5, doing: NaN as never, done: 'x' as never } },
'2026-09-02': { n: { todo: 2 }, s: -3 },
},
})
let threw = false
let nastyData: ReturnType<typeof chartData> | null = null
try { nastyData = chartData(nasty, period, 'cfd', '2026-09-30') } catch { threw = true }
ok(!threw, 'negative, NaN and non-numeric counts do not throw')
ok(nastyData!.runs.flat().every((p) => p.v.every((v) => Number.isFinite(v) && v >= 0)),
'and none of them draws a misleading value')
ok(countOf({ n: { todo: -5 } }, 'todo') === 0, 'a negative count reads as zero')
ok(countOf({ n: {} }, 'toString') === 0, 'a prototype key is not a count')
ok(CHART_KINDS.length === 3 && chartKind('nonsense') === 'burndown', 'an unknown kind falls back rather than blanking')
ok(SPEC.get('chart')?.custom === true, 'the chart block is registered and renders custom')
ok(SPEC.get('chart')?.text !== true, "and carries no inline host — its html is the readable fallback")
}
// ---------------------------------------------------------------------------
// 11. additivity — a round trip changes nothing
// ---------------------------------------------------------------------------
{
const doc = tracker()
recordTrail(doc, { today: '2026-09-11' })
startPeriod(doc, 'pd-1', { label: 'S', from: '2026-09-01', to: '2026-09-20', today: '2026-09-11' })
// a field from a NEWER build, inside a row
;(trailOf(doc)['2026-09-11'] as Record<string, unknown>).futureThing = { deep: [1, 2] }
const json = JSON.stringify(doc)
const res = parseDoc(json)
ok(res.ok, 'a trail-carrying document parses')
if (res.ok) {
ok(JSON.stringify(res.doc.trail) === JSON.stringify(doc.trail), 'the trail round-trips byte-identically')
ok(JSON.stringify(res.doc.periods) === JSON.stringify(doc.periods), 'and so do the periods')
ok(JSON.stringify((res.doc.trail as Trail)['2026-09-11']).includes('futureThing'),
'including a row field this build has never heard of')
}
// THE DOTTED-KEY HAZARD, and its fold — for `periods`, the one doc-level
// map spaces declares. `trail` is not a map and never synced, so no peer can
// ever send `trail.<day>`; a literal key of that name is an unknown field
// like any other and is left exactly where it is.
const damaged = JSON.parse(json) as Record<string, unknown>
damaged['periods.pd-2'] = { label: 'from an older peer', from: '2026-09-01', to: '2026-09-02' }
damaged['trail.2026-09-10'] = { n: { todo: 7 } }
damaged['not.a.map'] = 'left alone'
const folded = parseDoc(JSON.stringify(damaged))
ok(folded.ok, 'a document damaged by an older peer still parses')
if (folded.ok) {
ok(periodOf(folded.doc, 'pd-2')?.label === 'from an older peer', 'the dotted periods key is folded back into the map')
ok(folded.doc['periods.pd-2'] === undefined, 'and the junk key is gone')
ok(folded.doc['trail.2026-09-10'] !== undefined && trailOf(folded.doc)['2026-09-10'] === undefined,
'a dotted trail key is NOT folded — trail is not a synced map')
ok(folded.doc['not.a.map'] === 'left alone', 'a dotted key that is not a declared map is untouched')
}
// the fold never clobbers
const both = { periods: { 'pd-1': { label: 'placed' } }, 'periods.pd-1': { label: 'stray' } } as Record<string, unknown>
foldDottedMapKeys(both)
ok((both.periods as Record<string, { label: string }>)['pd-1'].label === 'placed',
'a folded key never overwrites one already in place')
// nor overwrites a `periods` some newer build gave another shape
const foreign = { periods: 'a newer shape', 'periods.pd-1': { label: 'stray' } } as Record<string, unknown>
foldDottedMapKeys(foreign)
ok(foreign.periods === 'a newer shape' && foreign['periods.pd-1'] !== undefined,
'a foreign periods value is never folded over')
// THE SHAPE: periods per key, trail not at all
ok(DOC_MAPS.length === 1 && DOC_MAPS[0] === 'periods', 'DOC_MAPS is exactly [periods]')
ok(SPACES_SHAPE.maps.has('periods') && !SPACES_SHAPE.maps.has('trail'),
'the sync shape merges periods per key, and does not map trail')
ok(SPACES_SHAPE.skipDoc.has('trail') && SPACES_SHAPE.skipDoc.has('revisions'),
'the sync shape skips trail (and revisions) outright')
ok(SPACES_SHAPE.maps.has('assets'), 'and still declares the maps it always did')
}
// ---------------------------------------------------------------------------
// 12. clearing and stripping
// ---------------------------------------------------------------------------
{
const doc = tracker()
recordTrail(doc, { today: '2026-09-11' })
clearTrail(doc)
ok(doc.trail === undefined, 'clearing deletes the key — never trail: {}')
ok(!('trail' in doc), 'a cleared space is byte-identical to one that never recorded')
// THE CLASSES. No builder strips the trail by hand: the kernel's copy table
// does, from the field map (scripts/test-spaces-copytiers.ts holds every
// tier and sweeps the builders for hand strips).
ok(SPACES_FIELDS.trail === 'history', 'trail is classed history')
ok(SPACES_FIELDS.periods === 'content', 'periods is classed content')
ok(!SPACES_NOT_EDIT.has('trail'), 'trail is NOT in SPACES_NOT_EDIT: it is written while editing')
const shared = tracker()
recordTrail(shared, { today: '2026-09-11' })
startPeriod(shared, 'pd-1', { label: 'S', from: '2026-09-01', to: '2026-09-20', today: '2026-09-11' })
const copy = docForExport(shared)
ok(copy.trail === undefined, 'Copy document JSON carries no trail')
ok(copy.periods !== undefined, 'but keeps the periods — content the chart blocks name')
ok(shared.trail !== undefined, 'and the original is untouched')
// the page extract drops the history class too
const ex = extractSpace(shared, shared.pages[0].id, { docId: 'doc-x', subtree: false, now: '2026-09-11T00:00:00Z' })
ok(ex.doc.trail === undefined, 'a page extract carries no trail')
}
// ---------------------------------------------------------------------------
// 13. two replicas, one day
// ---------------------------------------------------------------------------
{
const base = tracker()
recordTrail(base, { today: '2026-09-09' })
const json = JSON.stringify(base)
const a = new SyncState('actor-a')
const b = new SyncState('actor-b')
const docA = JSON.parse(json) as SpacesDoc
const docB = JSON.parse(json) as SpacesDoc
a.adopt(docA as never)
b.adopt(docB as never)
// A TRAIL ROW MINTS NO OPS. Each replica keeps its own record of what it saw.
const beforeA = JSON.parse(JSON.stringify(docA)) as SpacesDoc
recordTrail(docA, { today: '2026-09-10' })
const opsA = a.diff(beforeA as never, docA as never)
ok(opsA.length === 0, `a trail-only change diffs to zero ops (${opsA.length})`)
b.apply(docB as never, opsA)
ok(trailOf(docB)['2026-09-10'] === undefined, "and B's file never receives A's row")
// a content edit beside a trail row: only the content travels
const before2A = JSON.parse(JSON.stringify(docA)) as SpacesDoc
;(docA.pages[0].blocks[0] as { value: string }).value = 'done'
recordTrail(docA, { today: '2026-09-11' })
const ops2A = a.diff(before2A as never, docA as never)
ok(ops2A.length > 0 && ops2A.every((o) => !JSON.stringify(o).includes('2026-09-11')),
'an edit syncs; the row recorded beside it does not')
b.apply(docB as never, ops2A)
ok((docB.pages[0].blocks[0] as { value: string }).value === 'done', 'B has the edit')
ok(trailOf(docB)['2026-09-11'] === undefined, 'and not the row')
// PERIODS ARE A PER-KEY MAP: two people starting different periods both keep theirs
const bpA = JSON.parse(JSON.stringify(docA)) as SpacesDoc
startPeriod(docA, 'pd-a', { label: 'A', from: '2026-09-11', to: '2026-09-24', today: '2026-09-11' })
const pA = a.diff(bpA as never, docA as never)
const bpB = JSON.parse(JSON.stringify(docB)) as SpacesDoc
startPeriod(docB, 'pd-b', { label: 'B', from: '2026-09-11', to: '2026-09-24', today: '2026-09-11' })
const pB = b.diff(bpB as never, docB as never)
a.apply(docA as never, pB)
b.apply(docB as never, pA)
ok(periodOf(docA, 'pd-a') !== undefined && periodOf(docA, 'pd-b') !== undefined, 'concurrent periods: both survive on A')
ok(periodOf(docB, 'pd-a') !== undefined && periodOf(docB, 'pd-b') !== undefined, 'and on B — per key, not one register')
ok(pA.every((o) => !JSON.stringify(o).includes('"trail')), "the period's backfilled row did not ride along")
}
// ---------------------------------------------------------------------------
// 14. undo — a record is not an editing step, a period is
// ---------------------------------------------------------------------------
{
const doc = tracker()
const store = new Store(doc)
store.checkpoint()
// a row written OUTSIDE a commit, the way the autosave debounce writes it
recordTrail(store.doc, { today: '2026-09-11' })
ok(trailOf(store.doc)['2026-09-11'] !== undefined, 'a row lands outside any commit')
store.commit(() => { store.doc.title = 'Renamed' })
recordTrail(store.doc, { today: '2026-09-12' })
store.undo()
ok(store.doc.title === 'Rig space', 'undo takes back the edit')
ok(trailOf(store.doc)['2026-09-11'] !== undefined && trailOf(store.doc)['2026-09-12'] !== undefined,
'and takes back NEITHER row — a record is not an editing step')
// A PERIOD IS one. It is authored, inside a commit, and ⌘Z must reach it.
store.commit(() => {
startPeriod(store.doc, 'pd-undo', { label: 'S', from: '2026-09-11', to: '2026-09-24', today: '2026-09-11' })
})
ok(periodOf(store.doc, 'pd-undo') !== undefined, 'starting a period is a commit')
store.undo()
ok(periodOf(store.doc, 'pd-undo') === undefined, 'and ⌘Z takes it back, like any other edit')
ok(trailOf(store.doc)['2026-09-11'] !== undefined, 'while the rows it wrote stand')
// REDO keeps the live trail too
store.redo()
ok(periodOf(store.doc, 'pd-undo') !== undefined, 'redo brings the period back')
recordTrail(store.doc, { today: '2026-09-13' })
store.undo(); store.redo()
ok(trailOf(store.doc)['2026-09-13'] !== undefined, 'a row recorded after a redo survives another undo/redo')
// REPLACE FROM JSON with Copy document JSON's output (which drops trail by the
// copy table) must not wipe the trail
const rows = Object.keys(trailOf(store.doc)).sort().join(',')
const pasted = docForExport(store.doc)
ok(pasted.trail === undefined, 'Copy document JSON carries no trail')
store.replaceDoc(JSON.parse(JSON.stringify(pasted)) as SpacesDoc, 'back')
ok(Object.keys(trailOf(store.doc)).sort().join(',') === rows,
'replaceDoc keeps the LIVE trail — Replace from JSON does not wipe it')
// and a pasted doc carrying a DIFFERENT trail cannot overwrite the live one
const forged = JSON.parse(JSON.stringify(store.doc)) as SpacesDoc
forged.trail = { '2020-01-01': { n: { todo: 999 } } }
store.replaceDoc(forged, 'back')
ok(trailOf(store.doc)['2020-01-01'] === undefined && Object.keys(trailOf(store.doc)).sort().join(',') === rows,
'a restored or pasted trail never replaces the live record')
}
// ---------------------------------------------------------------------------
// 14b. the recovery key — a row recorded while editing is unsaved work
// ---------------------------------------------------------------------------
{
const doc = tracker()
const before = docContentKey(doc)
recordTrail(doc, { today: '2026-09-11' })
ok(docContentKey(doc) !== before, 'an edit-time trail row raises the recovery key')
// a row change on its own — no content edit beside it — still moves the key
const k1 = docContentKey(doc)
writeRow(doc, '2026-09-11', { n: { todo: 1 } })
ok(docContentKey(doc) !== k1, 'a trail change alone moves the recovery key')
const same = JSON.parse(JSON.stringify(doc)) as SpacesDoc
ok(docContentKey(same) === docContentKey(doc), 'an identical document keys identically')
}
// ---------------------------------------------------------------------------
// 15. the joint ceiling — history and trail, both at their budgets
// ---------------------------------------------------------------------------
{
// A REAL fixture, not arithmetic on the constants: a tracker saved many
// times with large paragraph rewrites (history.ts tiers it to HISTORY_BUDGET)
// and recorded every day for well over a year (trail.ts tiers it to
// TRAIL_BUDGET). The record the file carries about itself must stay inside
// the 160 KB that was ruled acceptable.
const doc = tracker()
doc.pages[0].blocks.push({ id: 'para', type: 'p', html: 'start' } as never)
const statuses = ['todo', 'doing', 'review', 'done']
for (let i = 0; i < 500; i++) {
const day = addDays('2025-06-01', i)
for (let j = 0; j < doc.pages.length; j++) {
;(doc.pages[j].blocks[0] as { value: string }).value = statuses[(i + j) % statuses.length]
const est = doc.pages[j].blocks.find((b) => (b as { key?: string }).key === 'estimate')
if (est) (est as { value: number }).value = 1 + ((i * 7 + j) % 13)
}
;(doc.pages[0].blocks.find((b) => b.id === 'para') as { html: string }).html =
`day ${i}: ` + Array.from({ length: 160 }, (_, w) => `word${(i * 31 + w) % 997}`).join(' ')
recordTrail(doc, { today: day })
recordRevision(doc)
}
const hb = historyBytes(doc)
const tb = trailBytes(doc)
console.log(` · after 500 days: history ${(hb / 1024).toFixed(1)} KB, trail ${(tb / 1024).toFixed(1)} KB, ` +
`${Object.keys(trailOf(doc)).length} rows`)
ok(hb <= HISTORY_BUDGET, `history stays within HISTORY_BUDGET (${hb} B)`)
ok(tb <= TRAIL_BUDGET, `the trail stays within TRAIL_BUDGET (${tb} B)`)
ok(hb + tb <= 160 * 1024, `history + trail stay within the 160 KB joint ceiling (${((hb + tb) / 1024).toFixed(1)} KB)`)
ok(hb > HISTORY_BUDGET * 0.5 && tb > TRAIL_BUDGET * 0.5,
'and both actually used their budgets, so the ceiling was exercised')
ok(wasCut(trailOf(doc)) || Object.values(trailOf(doc)).some((r) => (r.s ?? 1) > 1),
'the trail tiered (thinned or cut) to get there rather than failing')
}
console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)