Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

25.9 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// THE TRAIL: what was true on a day, written down because the day is over.
//
// THE RULE THIS FILE IS THE EXCEPTION-THAT-IS-NOT-ONE TO. `calc.ts` opens by
// refusing to store an answer, `fields.ts viewRows` refuses to store the rows
// ("a database that keeps its own copy of the rows is a database that disagrees
// with the document"), and `model.ts tableOf` normalises at read time rather
// than by rewriting. The rule underneath all three is narrower than "everything
// derives", and this is it:
//
//     Never store what the current document already implies.
//     Do store an observation it cannot reproduce.
//
// The past is not a function of the present state. No recomputation over
// today's pages answers "how many points were open on 3 September", because the
// only artefact that ever knew is gone. Four members of that class are already
// in the format — `page.created`/`page.edited`, `Comment.at`, `Page.journal`
// (the date a page IS) and `doc.revisions`. Every one is a
// timestamped observation nobody can recompute. (docs/DECISIONS.md, 2026-09-11)
//
// THE FALSIFIABLE HALF, which the charts hold to: the TODAY point is derived
// from live state, and only strictly-earlier days are read from here. Change an
// estimate now and today's point moves immediately, exactly as calc.ts
// promises. The trail is consulted only for days that have closed, where there
// is nothing left to disagree with.
//
// WHAT A ROW MUST NEVER CONTAIN, and this is a budget rule and a privacy rule
// at once: no page ids, no assignee breakdown, no per-issue anything. A "who
// closed what, when" series is the surveillance shape of this feature, it grows
// with the team, and it is excluded ON PURPOSE so a later session does not add
// it as the obvious next step. What a trail DOES disclose, said plainly because
// the field name does not suggest it: the CADENCE. Which days the file was
// touched, which weeks nothing moved, work on a Sunday. That is why the field
// map classes it `history` (docclass.ts): the kernel's copy table drops it from
// every copy handed to someone else — a reader or view-only copy, the sealed
// reading copy, a link, an audience copy, a template, Copy document JSON and a
// page extract — and keeps it only in the file, a duplicate and an invite. No
// builder strips it by hand; the class does, so a copy rule added later
// covers it without anyone remembering to.
//
// FILE-LOCAL, NEVER SYNCED. The kernel's sync shape skips history-class fields,
// so each replica keeps its own record of what it saw, as each keeps its own
// `revisions`. Two people working on the same day each have a truthful row in
// their own file; neither file is wrong.
//
// THIS FILE IS A LEAF: types only, no runtime imports.
//
// DAY ARITHMETIC IS TIMEZONE-FREE HERE, deliberately and unlike `journal.ts`.
// A row key is a LOCAL day LABEL, minted once at the call site from
// `journal.todayISO()` — the reader's own wall-clock day. Once it is a label,
// turning it back into a local `Date` would reintroduce exactly the ambiguity
// the label exists to have settled (and `new Date('2026-01-01')` is UTC
// midnight, i.e. the previous day for half the planet). So every calculation
// below goes through `dayIndex`, which is UTC ordinal arithmetic on the label
// and cannot drift by a timezone, a DST boundary or a locale.

import type { SpacesDoc } from './model'

/**
 * One day's observation.
 *
 * Keyed by STATUS OPTION ID, not by phase group. There are four groups and six
 * default options; a CFD's bands are the board's columns, which are options —
 * recording groups makes the CFD unbuildable, while recording options keeps it
 * AND keeps burndown, because `FieldOption.group` derives a group from an
 * option at render time. The reverse does not exist. Costs about 1.5× and buys
 * the third chart.
 *
 * Consequence said out loud: the schema can change. An option deleted next
 * month leaves a band in old rows with no label. The chart falls back to the
 * raw id and says it does not know it — the rule `ViewFilter` already states
 * for a value this build has never heard of.
 */
export interface TrailRow {
  /** issues per status option id. Zero-valued options are omitted. */
  n: Record<string, number>
  /** summed estimate per status option id. Absent when nothing is estimated. */
  e?: Record<string, number>
  /** issues counted that carried no estimate, so a points chart can say so. */
  x?: number
  /** days this row stands for after thinning. Absent = 1 = a single day. */
  s?: number
  /** this is the oldest surviving row and older ones were dropped. */
  cut?: true
}

/**
 * `doc.trail`: observation key → what was true that day. A MAP, not an array.
 *
 * A MAP for two reasons:
 *
 *  1. "One row per day" becomes an invariant of the SHAPE rather than a rule
 *     somebody has to enforce. A second write on a day overwrites the first, so
 *     a day's row is the last observation of that day — which is also the one a
 *     burndown wants.
 *  2. A row is addressable, so a write is idempotent.
 *
 * KEY: `YYYY-MM-DD`, or `<seriesId>/<YYYY-MM-DD>` when a period charts its own
 * scope. The bare form IS the default series. Shipped now rather than later
 * because the trail is PRE-AGGREGATED: the series is the only mechanism by
 * which two different scopes can ever be charted, and retrofitting it would
 * make every existing bare key mean "the default series" by archaeology.
 */
export type Trail = Record<string, TrailRow>

// ---- days -----------------------------------------------------------------

const SHAPE = /^\d{4}-\d{2}-\d{2}$/

/**
 * A REAL day label, not merely a digit-shaped string.
 *
 * `2026-13-99` matches the shape and is not a day; every formatter rolls it
 * over into some OTHER real day and shows a confident wrong answer. The round
 * trip is the check. UTC, not local — see the timezone note at the top: this is
 * arithmetic on a label, and a label has no timezone.
 */
export function isDay(v: unknown): v is string {
  if (typeof v !== 'string' || !SHAPE.test(v)) return false
  const [y, m, d] = v.split('-').map(Number)
  const at = new Date(Date.UTC(y, m - 1, d))
  return at.getUTCFullYear() === y && at.getUTCMonth() === m - 1 && at.getUTCDate() === d
}

const DAY_MS = 86400000

/** Days since the epoch, from the LABEL. Pure, and the same number in Kiritimati
 *  and in Niue — which is the whole point. */
export function dayIndex(iso: string): number {
  const [y, m, d] = iso.split('-').map(Number)
  return Math.round(Date.UTC(y, m - 1, d) / DAY_MS)
}

const pad = (n: number) => String(n).padStart(2, '0')

/** The label `n` days after `iso`. */
export function addDays(iso: string, n: number): string {
  return fromIndex(dayIndex(iso) + n)
}

export function fromIndex(i: number): string {
  const at = new Date(i * DAY_MS)
  return `${at.getUTCFullYear()}-${pad(at.getUTCMonth() + 1)}-${pad(at.getUTCDate())}`
}

/** Inclusive day count from `a` to `b`; negative when `b` precedes `a`. */
export const daysBetween = (a: string, b: string): number => dayIndex(b) - dayIndex(a)

/** Every day label from `from` to `to`, inclusive. Empty when `to` precedes
 *  `from` — a period whose `to` precedes its `from` must not throw and must not
 *  draw something misleading, so it draws nothing. Capped, because the range
 *  comes out of a file somebody mailed you. */
export function dayRange(from: string, to: string, cap = 4000): string[] {
  if (!isDay(from) || !isDay(to)) return []
  const n = daysBetween(from, to)
  if (n < 0) return []
  const out: string[] = []
  for (let i = 0; i <= Math.min(n, cap - 1); i++) out.push(addDays(from, i))
  return out
}

/** The ISO-8601 week a day sits in, as a sortable `YYYY-Www` bucket key.
 *  Monday-based, because that is what "one row per week" means everywhere the
 *  sprint word is used. */
export function weekKey(iso: string): string {
  const i = dayIndex(iso)
  // 1970-01-01 was a Thursday: (i + 3) makes Monday 0.
  const monday = i - ((((i + 3) % 7) + 7) % 7)
  return `w${monday}`
}

/** The month a day sits in. */
export const monthKey = (iso: string): string => iso.slice(0, 7)

// ---- keys ------------------------------------------------------------------

/** The key a row is filed under. */
export const trailKey = (day: string, series?: string): string =>
  series ? `${series}/${day}` : day

export interface TrailAddr { series: string; day: string }

/**
 * A key back into its parts, or null when it is not one this build can read.
 *
 * A key from a NEWER build (a second slash, a shape nobody here knows) is not
 * an error and is never rewritten — it is simply not drawn, and it round-trips
 * untouched like every other unknown thing in this format.
 */
export function parseTrailKey(k: string): TrailAddr | null {
  const at = k.lastIndexOf('/')
  const day = at < 0 ? k : k.slice(at + 1)
  const series = at < 0 ? '' : k.slice(0, at)
  if (!isDay(day)) return null
  if (series.includes('/')) return null
  return { series, day }
}

// ---- reading ---------------------------------------------------------------

const isObj = (v: unknown): v is Record<string, unknown> =>
  !!v && typeof v === 'object' && !Array.isArray(v)

/**
 * A `trail` that is not an object — some future build gave the name a different
 * shape. It is LEFT ALONE and never written over, which is the rule history
 * states for `revisions` and the rule additivity requires: a field this build
 * cannot read is a field it must not destroy.
 */
export const trailIsForeign = (doc: SpacesDoc): boolean =>
  doc.trail !== undefined && !isObj(doc.trail)

/** The trail in force. `{}` when there is none, and never a key created as a
 *  side effect of asking. */
export function trailOf(doc: SpacesDoc): Trail {
  const raw = doc.trail
  if (!isObj(raw)) return {}
  const out: Trail = {}
  for (const k of Object.keys(raw)) {
    const row = raw[k]
    // `Object.hasOwn` semantics by construction: Object.keys is own-enumerable
    // only, so `trail.toString` from a hand-edited file is never reached.
    if (isObj(row) && isObj(row.n)) out[k] = row as TrailRow
  }
  return out
}

/** One row's total issue count. Malformed and negative entries count as zero —
 *  a row out of a mailed file may say anything, and none of it may throw. */
export function rowTotal(row: TrailRow): number {
  let n = 0
  for (const k of Object.keys(row.n ?? {})) {
    const v = row.n[k]
    if (typeof v === 'number' && Number.isFinite(v) && v > 0) n += v
  }
  return n
}

/** A row's count for one option id, clamped to a real, non-negative number. */
export const countOf = (row: TrailRow, option: string): number => {
  const m = row.n ?? {}
  if (!Object.hasOwn(m, option)) return 0
  const v = m[option]
  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0
}

/** A row's summed estimate for one option id, or undefined when this row holds
 *  no estimates at all — which is different from an estimate of zero. */
export function estimateOf(row: TrailRow, option: string): number | undefined {
  const m = row.e
  if (!isObj(m)) return undefined
  if (!Object.hasOwn(m, option)) return 0
  const v = (m as Record<string, unknown>)[option]
  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0
}

/** Does this row carry estimates at all? */
export const hasEstimates = (row: TrailRow): boolean => isObj(row.e)

/** How many days a row stands for. Absent = 1. */
export function spanOf(row: TrailRow): number {
  const s = row.s
  return typeof s === 'number' && Number.isFinite(s) && s >= 1 ? Math.floor(s) : 1
}

/** Every row of one series, oldest first. */
export function seriesRows(trail: Trail, series = ''): Array<{ day: string; row: TrailRow }> {
  const out: Array<{ day: string; row: TrailRow }> = []
  for (const k of Object.keys(trail)) {
    const addr = parseTrailKey(k)
    if (!addr || addr.series !== series) continue
    out.push({ day: addr.day, row: trail[k] })
  }
  out.sort((a, b) => (a.day < b.day ? -1 : a.day > b.day ? 1 : 0))
  return out
}

/** The series ids present in a trail. '' is the default series. */
export function seriesIds(trail: Trail): string[] {
  const seen = new Set<string>()
  for (const k of Object.keys(trail)) {
    const addr = parseTrailKey(k)
    if (addr) seen.add(addr.series)
  }
  return [...seen].sort()
}

// ---- writing ---------------------------------------------------------------

/**
 * Write one day's row, in place. Returns false when nothing was written.
 *
 * ONLY EVER TODAY'S KEY. There is no code path here that recomputes a past key
 * — not "recompute the last 7 days", not "repair inconsistent rows". That is
 * the guarantee behind "editing the past does not rewrite it": change an
 * estimate today and yesterday's row cannot move, because nothing addresses it.
 * The one other way a past key is created is `backfill`, below, which refuses
 * to overwrite.
 */
export function writeRow(doc: SpacesDoc, day: string, row: TrailRow, series?: string): boolean {
  if (trailIsForeign(doc) || !isDay(day)) return false
  const trail: Trail = isObj(doc.trail) ? (doc.trail as Trail) : {}
  trail[trailKey(day, series)] = row
  doc.trail = trail
  return true
}

/**
 * Write a PAST key, only if it is absent. Returns false when one was already
 * there.
 *
 * A row, once written, is immutable for the rest of the file's life. The only
 * callers are committing a period whose window includes today and (if
 * somebody writes one) a one-time import from `doc.revisions`.
 */
export function backfill(doc: SpacesDoc, day: string, row: TrailRow, series?: string): boolean {
  if (trailIsForeign(doc) || !isDay(day)) return false
  const trail = trailOf(doc)
  if (Object.hasOwn(trail, trailKey(day, series))) return false
  return writeRow(doc, day, row, series)
}

/**
 * Remove the trail. NO KEY, never `trail: {}`.
 *
 * A space that was tracked and then cleared is byte-identical to one that never
 * was — the rule `ViewFilter`, `ViewSource` and the view layout all follow, and
 * the reason "Clear trail" can be offered as a real control rather than as a
 * hide.
 */
export function clearTrail(doc: SpacesDoc): void {
  delete doc.trail
}

// ---- the budget ------------------------------------------------------------
//
// THE TRAIL HAS ITS OWN CEILING, beside history's. `history.ts` keeps
// `HISTORY_BUDGET` (128 KB) for `doc.revisions`; the trail keeps
// `TRAIL_BUDGET` (32 KB) for itself. Together the record a space carries about
// itself is at most 160 KB, the joint ceiling that was ruled acceptable — and
// each side tiers on its own, so neither needs to know what the other is.
//
// 32 KB holds about six months of full daily rows (a year measured 61.5 KB at
// ~172 B/row with estimates, 31.9 KB counts-only). Past it the oldest rows thin
// to weekly, then monthly, then drop — the distant past loses resolution first.

/** The trail's byte ceiling. With `HISTORY_BUDGET` it makes the 160 KB joint
 *  ceiling (scripts/test-spaces-trail.ts asserts the sum with a fixture). */
export const TRAIL_BUDGET = 32 * 1024
/** Rows kept at most, whatever their size. */
export const TRAIL_MAX = 400

const bytes = (v: unknown): number => (v === undefined ? 0 : JSON.stringify(v).length)

/** What the trail currently costs, in serialized bytes. */
export const trailBytes = (doc: SpacesDoc): number => bytes(doc.trail)

// ---- pruning ---------------------------------------------------------------

/**
 * Bring a trail back under `TRAIL_BUDGET`, TIERING rather than failing —
 * following PREVIEW_BUDGET and HISTORY_BUDGET.
 *
 *   Tier 1  under both ceilings: every day kept, full resolution.
 *   Tier 2  thin the oldest rows to one per ISO week.
 *   Tier 3  thin the oldest rows to one per month.
 *   Tier 4  drop the oldest outright, and stamp `cut` on the new oldest.
 *
 * Resolution goes from the DISTANT PAST first: this quarter stays daily while
 * last spring becomes weekly.
 *
 * THINNING SELECTS, IT NEVER AVERAGES. An averaged row is a number nobody
 * observed — the same lie as interpolating a gap, written to disk. The survivor
 * of a bucket is its LAST row, stamped `s` with the span it now stands for:
 * from the earliest row it replaced through its own day. Days outside that span
 * were never observed and stay gaps, so thinning cannot invent coverage.
 *
 * `protect` names days that must not be thinned — the rows of a period that is
 * still running. A sprint must not have its own chart thinned underneath it.
 */
export function pruneTrail(
  trail: Trail,
  allowance = TRAIL_BUDGET,
  max = TRAIL_MAX,
  protect: (day: string) => boolean = () => false,
): Trail {
  let out: Trail = { ...trail }
  const over = (t: Trail): boolean =>
    bytes(t) > allowance || Object.keys(t).length > max
  if (!over(out)) return out

  for (const bucket of [weekKey, monthKey] as const) {
    out = thin(out, bucket, protect)
    if (!over(out)) return out
  }

  // Tier 4 — drop the oldest outright, per series, oldest first.
  const keys = Object.keys(out)
    .map((k) => ({ k, addr: parseTrailKey(k) }))
    .filter((e): e is { k: string; addr: TrailAddr } => !!e.addr)
    .sort((a, b) => (a.addr.day < b.addr.day ? -1 : a.addr.day > b.addr.day ? 1 : 0))
  let cutAny = false
  for (const e of keys) {
    if (!over(out)) break
    if (protect(e.addr.day)) continue
    // never drop the last row of a series: a chart with no point at all says
    // less than one with a single point and a "recording starts here" edge
    if (seriesRows(out, e.addr.series).length <= 1) continue
    delete out[e.k]
    cutAny = true
  }
  if (cutAny) out = stampCut(out)
  return out
}

/** Collapse each bucket to its last row, oldest bucket first, stopping as soon
 *  as the trail fits. */
function thin(trail: Trail, bucket: (day: string) => string, protect: (day: string) => boolean): Trail {
  const out: Trail = { ...trail }
  for (const series of seriesIds(out)) {
    const rows = seriesRows(out, series)
    const groups = new Map<string, Array<{ day: string; row: TrailRow }>>()
    for (const r of rows) {
      const b = bucket(r.day)
      const list = groups.get(b)
      if (list) list.push(r)
      else groups.set(b, [r])
    }
    for (const [, list] of groups) {
      if (list.length < 2) continue
      if (list.some((r) => protect(r.day))) continue
      const keep = list[list.length - 1]
      const first = list[0]
      for (const r of list) if (r !== keep) delete out[trailKey(r.day, series || undefined)]
      // the span it now stands for: from the earliest row it replaced through
      // its own day, never further. Anything either side stays a gap.
      const span = Math.max(spanOf(keep.row), daysBetween(first.day, keep.day) + spanOf(first.row))
      const next: TrailRow = { ...keep.row }
      if (span > 1) next.s = span
      out[trailKey(keep.day, series || undefined)] = next
    }
  }
  return stampCut(out)
}

/** `cut` marks the oldest surviving row of each series, so a chart draws its
 *  left edge as "recording starts here" instead of implying the project began
 *  at that value. Re-derived, never accumulated: a row that stops being the
 *  oldest loses the flag. */
function stampCut(trail: Trail): Trail {
  const out: Trail = { ...trail }
  for (const series of seriesIds(out)) {
    const rows = seriesRows(out, series)
    rows.forEach((r, i) => {
      const key = trailKey(r.day, series || undefined)
      const wantCut = i === 0 && rows.length > 0
      const had = r.row.cut === true
      if (wantCut === had) return
      const next = { ...r.row }
      if (wantCut) next.cut = true
      else delete next.cut
      out[key] = next
    })
  }
  return out
}

/** Was anything ever dropped from the front of this series? */
export const wasCut = (trail: Trail, series = ''): boolean =>
  seriesRows(trail, series)[0]?.row.cut === true

// ---- crash recovery: the per-day union -------------------------------------

/**
 * The trail's RECOVER HOOK (kernel docfields.ts `RecoverHook`): what a crash
 * recovery keeps when the open file and the recovered snapshot BOTH carry a
 * trail. Bound in store.ts `RESTORE_RULES` for direction 'recover' only — the
 * kernel never consults it on undo, redo, a version restore or a paste, which
 * all keep the live trail outright.
 *
 * Neither side is simply newer. The recovery snapshot holds rows written while
 * editing that the file never got (main.ts recordToday writes outside any
 * save), and the file may hold days written AFTER the snapshot (it was saved
 * from another tab, or the snapshot is stale). Taking either whole map loses
 * observations nobody can recompute, so it is a UNION BY DAY:
 *
 *   1. a key on ONE side only is kept — it is an observation the other side
 *      never made;
 *   2. a key on BOTH sides goes to the side whose WHOLE DOCUMENT is later
 *      (`at`, epoch ms): incoming when `at.incoming > at.live`; a tie keeps
 *      live; an unknown live time (a file with no `modified`) counts as OLDER,
 *      so a known incoming time wins it; an unknown incoming time never wins;
 *   3. no day is counted twice. A thinned row stands for the `s` days ENDING on
 *      its own key, so a bucket row from one side and single-day rows inside
 *      its span from the other would both claim those days. Rows are walked
 *      newest-anchor first, per series, and a row whose own day lies inside the
 *      span of a row already kept is dropped. (That is "drop a single day inside
 *      a kept bucket", generalised: two overlapping buckets resolve the same
 *      way, and no two kept rows of a series ever cover the same day.) Day
 *      arithmetic is `dayIndex` on the LABEL and only ever within one series —
 *      never `new Date(label)`, and `sprint/2026-09-11` never meets
 *      `2026-09-11`;
 *   4. the result goes through `pruneTrail`, so a union can never exceed the
 *      budget either side was held to.
 *
 * A side that is not a trail object (a newer build's shape — `trailIsForeign`)
 * is never written over: an open foreign trail stays, and a foreign incoming
 * one does not replace a readable live one. Keys this build cannot parse are
 * carried by rules 1 and 2 untouched, and never take part in rule 3.
 */
export function trailRecover(
  live: unknown, incoming: unknown, at: { live?: number; incoming?: number },
): unknown {
  if (live === undefined) return incoming
  if (!isObj(live) || !isObj(incoming)) return live
  const incomingWins = at.incoming !== undefined && (at.live === undefined || at.incoming > at.live)
  const merged: Record<string, unknown> = {}
  const put = (k: string, v: unknown): void => {
    if (k === '__proto__' || k === 'constructor' || k === 'prototype') return
    merged[k] = v
  }
  // LIVE's key order first, then the snapshot's new keys: a snapshot holding
  // nothing the file lacks merges to a map byte-identical to the live one, so
  // the recovery check (which compares serialized content) raises no banner
  for (const k of Object.keys(live)) {
    put(k, Object.hasOwn(incoming, k) && incomingWins ? incoming[k] : live[k])
  }
  for (const k of Object.keys(incoming)) {
    if (!Object.hasOwn(live, k)) put(k, incoming[k])
  }

  // 3. one claim per day, per series: newest anchor first
  const bySeries = new Map<string, Array<{ k: string; day: number; span: number }>>()
  for (const k of Object.keys(merged)) {
    const addr = parseTrailKey(k)
    const row = merged[k]
    if (!addr || !isObj(row)) continue
    const list = bySeries.get(addr.series) ?? []
    list.push({ k, day: dayIndex(addr.day), span: spanOf(row as unknown as TrailRow) })
    bySeries.set(addr.series, list)
  }
  for (const [, list] of bySeries) {
    list.sort((a, b) => b.day - a.day)
    const kept: Array<{ from: number; to: number }> = []
    for (const r of list) {
      if (kept.some((c) => r.day >= c.from && r.day <= c.to)) { delete merged[r.k]; continue }
      kept.push({ from: r.day - r.span + 1, to: r.day })
    }
  }

  // 4. the budget
  return pruneTrail(merged as Trail)
}

// ---- drawing slots ---------------------------------------------------------

/**
 * WHAT A DAY IS, for anything that draws the trail.
 *
 *   'day'    observed on that day, at full resolution.
 *   'sample' covered by a thinned row that stands for a span ending later.
 *   'gap'    NOT RECORDED. Nobody opened the file; the weekend; a build that
 *            predates the feature.
 *
 * A GAP IS DRAWN AS A GAP. No interpolation, no carry-forward, no zero — a
 * carried value is the worst of the three because it looks like data, and
 * an interpolated weekend shows work happening on Sunday. Absent and zero must
 * be visually distinct: a day with zero issues in `doing` is a point at zero, a
 * day nobody opened the file is nothing at all.
 */
export type SlotKind = 'day' | 'sample' | 'gap'

export interface Slot {
  day: string
  kind: SlotKind
  /** the row this day reads from — absent for a gap */
  row?: TrailRow
  /** true on the day the row was actually keyed to (a sample's own day) */
  anchor: boolean
}

/**
 * One slot per day between `from` and `to`, inclusive.
 *
 * A thinned row covers the `s` days ending on its own key, and no more. The
 * days it covers are 'sample'; its own day is the anchor, which is where a
 * point is drawn.
 */
export function slots(trail: Trail, from: string, to: string, series = ''): Slot[] {
  const days = dayRange(from, to)
  if (!days.length) return []
  const cover = new Map<string, { row: TrailRow; anchor: boolean; kind: SlotKind }>()
  for (const { day, row } of seriesRows(trail, series)) {
    const span = spanOf(row)
    const kind: SlotKind = span > 1 ? 'sample' : 'day'
    for (let back = 0; back < span; back++) {
      const d = addDays(day, -back)
      // a span never buries a day that was observed in its own right. Thinning
      // deletes the rows it replaces so this cannot arise from our own writes,
      // but the trail arrives in a file anyone can hand-edit.
      if (back > 0 && cover.get(d)?.anchor) continue
      cover.set(d, { row, anchor: back === 0, kind })
    }
  }
  return days.map((day) => {
    const c = cover.get(day)
    return c
      ? { day, kind: c.kind, row: c.row, anchor: c.anchor }
      : { day, kind: 'gap' as const, anchor: false }
  })
}