@adrrr/tarmac 0.8.1 → 0.9.0

package/README.md

@@ -26,10 +26,18 @@ documented surfaces only, never an internal format.
 npx @adrrr/tarmac              # one-shot fleet table
 npx @adrrr/tarmac --watch      # the same table, redrawn every 5s until ^C
 npx @adrrr/tarmac serve        # the same fleet in the browser
+npx @adrrr/tarmac serve --demo # an invented fleet with a week of history, to see it full
 npx @adrrr/tarmac install      # chain the status line: unlocks ctx, model, effort and cost
 npx @adrrr/tarmac uninstall    # hand your status line back
 ```
 
+On a fresh machine the first three of those are one session and no history, which is not much
+of a dashboard. `serve --demo` is the same dashboard over eight invented sessions, a day of
+their record and a week of journal under that, so the map, the replay and every range of the
+curves have something in them. It reads no fleet and writes nothing — the week it shows is
+invented in memory, like the rest of it — and the page it serves is badged `demo data`
+throughout.
+
 ```
 $ npx @adrrr/tarmac
 
@@ -115,6 +123,12 @@ The third tab draws what moved rather than what is: context per session, cost pe
 the account's two windows, over the last 24 hours out of the ring or over 7 and 30 days out of
 the journal, if you keep one. `<canvas>` and the page's own script, no library.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/media/curves-dark.png">
+  <img src="docs/media/curves-light.png" width="1100"
+       alt="The curves page of the demo fleet, on the 7d range out of the invented journal. Context is a row of small multiples, one line per session, each a sawtooth that climbs through the day and breaks where the session was recycled, the two still climbing labelled with an arrow. Cost is one stacked bar per day in a fixed project order, the current day shorter than the six complete ones. Quota is the seven-day line climbing over the five-hour window's highs. A banner above names one unrecognised status, and the header is badged demo data.">
+</picture>
+
 A context line breaks where its session did, so a recycle at three in the morning reads as a
 break and not as a cliff, and a minute nobody read is a hole rather than a fall to zero. The
 lines that gained fifteen points or more in the last three hours are drawn full and labelled,

package/dist/args.js

@@ -4,7 +4,6 @@
 // Unknown options and unknown commands are ERRORS. A typo silently ignored is how someone
 // ends up believing they pointed tarmac at a directory it never read.
 import { parseHistoryDays, parsePort, parseTrustHost } from './config.js';
-const COMMANDS = new Set(['list', 'serve', 'install', 'uninstall', 'help']);
 // `| undefined` is load-bearing, not decoration: without it the compiler types the lookup
 // below as always-present and the `if (!key) throw` guard reads as dead code — which is how
 // a future cleanup deletes the one thing standing between a typo and a silently ignored flag.
@@ -19,6 +18,7 @@ const OPTIONS = {
     '--json': 'json',
     '--watch': 'watch',
     '--yes': 'yes',
+    '--demo': 'demo',
     '--help': 'help',
     '--version': 'version',
     // The one short spelling this parser knows, and it is here because it is what people type
@@ -26,7 +26,7 @@ const OPTIONS = {
     // `-h` for help would be the next request and the one after that.
     '-v': 'version',
 };
-const FLAGS = new Set(['json', 'watch', 'yes', 'help', 'version']);
+const FLAGS = new Set(['json', 'watch', 'yes', 'demo', 'help', 'version']);
 /** Options that ACCUMULATE rather than overwrite — passed twice, both values are kept. */
 const LISTS = new Set(['trustHost']);
 /**
@@ -40,7 +40,7 @@ const LISTS = new Set(['trustHost']);
  */
 const ACCEPTS = {
     list: new Set(['staleAfter', 'snapshotsDir', 'home', 'claudeBin', 'json', 'watch', 'help', 'version']),
-    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'historyDays', 'home', 'claudeBin', 'help', 'version']),
+    serve: new Set(['port', 'staleAfter', 'snapshotsDir', 'trustHost', 'historyDays', 'home', 'claudeBin', 'demo', 'help', 'version']),
     install: new Set(['home', 'yes', 'help', 'version']),
     uninstall: new Set(['home', 'yes', 'help', 'version']),
     help: new Set(['help', 'version']),
@@ -51,6 +51,18 @@ function ownersOf(key) {
 }
 /** Every flag this parser knows, so a documentation check can enumerate rather than guess. */
 export const OPTION_FLAGS = Object.keys(OPTIONS);
+/** Every command it knows, from the same matrix, and for the same reason one level up. */
+export const COMMAND_NAMES = Object.keys(ACCEPTS);
+/**
+ * Is `name` a command? Asked of the matrix, because a second list written beside it is a list
+ * that drifts: a name in that one and not in this one was not refused, it was accepted with
+ * nothing behind it, and the next flag read `.has` off `undefined` (#149).
+ *
+ * Own keys only — `in` would make `toString` a command.
+ */
+function isCommand(name) {
+    return Object.hasOwn(ACCEPTS, name);
+}
 /**
  * Does `command` read `flag`? Exported for the test that holds `--help` to this matrix:
  * asking the parser is the only way to check that does not go through the wording of an
@@ -61,12 +73,13 @@ export function accepts(command, flag) {
     return key !== undefined && ACCEPTS[command].has(key);
 }
 export function parseArgs(argv) {
-    const out = { command: 'list', port: null, staleAfter: null, snapshotsDir: null, trustHost: [], historyDays: null, home: null, claudeBin: 'claude', json: false, watch: false, yes: false, help: false, version: false };
+    const out = { command: 'list', port: null, staleAfter: null, snapshotsDir: null, trustHost: [], historyDays: null, home: null, claudeBin: 'claude', json: false, watch: false, yes: false, demo: false, help: false, version: false };
     let i = 0;
-    if (argv[0] && !argv[0].startsWith('-')) {
-        if (!COMMANDS.has(argv[0]))
-            throw new Error(`unknown command: ${argv[0]}`);
-        out.command = argv[0];
+    const first = argv[0];
+    if (first && !first.startsWith('-')) {
+        if (!isCommand(first))
+            throw new Error(`unknown command: ${first}`);
+        out.command = first;
         i = 1;
     }
     for (; i < argv.length; i++) {
@@ -77,6 +90,11 @@ export function parseArgs(argv) {
         if (!ACCEPTS[out.command].has(key))
             throw new Error(`${flag} is not an option of \`tarmac ${out.command}\` — it belongs to: ${ownersOf(key)}`);
         if (FLAGS.has(key)) {
+            // A boolean has no value to read, so it refuses one rather than deciding what it meant:
+            // `--yes=false` taken as `--yes` skips the confirmation the operator just declined, and
+            // a parser this strict about a typo has no business guessing at truthiness (#155).
+            if (inline !== null)
+                throw new Error(`${flag} takes no value`);
             out[key] = true;
             continue;
         }

package/dist/cli.js

@@ -12,6 +12,8 @@ import os from 'node:os';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { parseArgs } from './args.js';
 import { collectFleet } from './collect.js';
+import { demoCollector, demoDayStart, demoHistory } from './demo.js';
+import { createDemoHistoryStore } from './demo-history.js';
 import { readConfigFile, resolveConfig } from './config.js';
 import { createFleetServer, listenFleetServer } from './server.js';
 import { install, uninstall, paths, planInstall, planUninstall, installedSnapshotsDir, wrapperIsOurs } from './install.js';
@@ -27,6 +29,7 @@ const USAGE = `tarmac — fleet observability for Claude Code
         one-shot fleet table — with --watch, redrawn every 5s until ^C
   tarmac serve      [--home DIR] [--port N] [--stale-after D] [--snapshots-dir DIR]
                     [--claude-bin PATH] [--trust-host HOST] [--history-days N]
+                    [--demo]
         local dashboard
   tarmac install    [--home DIR] [--yes]
         chain the statusline
@@ -55,6 +58,12 @@ const USAGE = `tarmac — fleet observability for Claude Code
                    which is the command that samples: one JSON line a minute, no session
                    name and no working directory, about 2 MB a day at eight sessions,
                    and writing stops at 256 MB whatever N says
+  --demo           serve an invented fleet of eight sessions, with a day of history behind
+                   it and a week of journal under that, instead of this machine's. On
+                   \`serve\` only. This machine's fleet is never read and nothing is written:
+                   no \`claude\`, no snapshots, no temp sweep, and no journal file whatever
+                   --history-days says. The port and the trusted hosts are still resolved
+                   as usual, and the page says on itself that it is a demo
 
   Those five settings can also be set, in decreasing order of precedence, by the
   environment (TARMAC_STALE_AFTER, TARMAC_PORT, TARMAC_SNAPSHOTS_DIR, TARMAC_TRUST_HOST,
@@ -135,7 +144,11 @@ try {
         // writes, not where a reader's environment would have put it. Recomputing it here made
         // `XDG_STATE_HOME` in one process and not the other a silent split.
         const frozen = installedSnapshotsDir(p);
-        if (frozen === null && wrapperIsOurs(p))
+        // Not under `--demo`, and for the reason the settings block is not: this line names the
+        // wrapper's path and the snapshot directory, which are two real paths out of a real home,
+        // and a terminal capture of a demo is exactly the artefact `--demo` exists to produce. It
+        // is also advice about a directory this run will never open.
+        if (frozen === null && wrapperIsOurs(p) && !args.demo)
             console.error(`tarmac: ${p.wrapper} is ours but does not say where it writes — falling back to ${p.snapshots}`);
         const config = resolveConfig({
             flags: { staleAfter: args.staleAfter, port: args.port, snapshotsDir: args.snapshotsDir, trustHosts: args.trustHost, historyDays: args.historyDays },
@@ -152,13 +165,27 @@ try {
             // Beside the snapshots, never among them: `reap.ts`, the wrapper's own sweep and the
             // legacy purge in `install.ts` all decide by name inside that directory.
             const historyDir = historyDirFor(snapshotsDir);
-            // Unattended for hours, so it opens by saying what it decided and on whose authority.
-            process.stdout.write(renderSettings(config, p.config, historyDir));
+            // `--demo` serves an invented fleet, and everything it SUPPRESSES is here: a settings
+            // block naming a snapshot directory it will never open, a journal whatever
+            // `--history-days` says, and a sweep of somebody's temp files. A demo that journalled
+            // would write an invented fleet into a real record of a real one; a demo that swept
+            // would delete a file to show a picture. What it ADDS is one collector and one ring,
+            // both below.
+            //
+            // Unattended for hours, so a real serve opens by saying what it decided and on whose
+            // authority.
+            if (!args.demo)
+                process.stdout.write(renderSettings(config, p.config, historyDir));
             // One journal, one owner (#133). The retention is a property of the DIRECTORY and the
             // process applying it was whichever `serve` started last, so a `--history-days 1` run to
             // try the setting out swept the thirty days another serve was keeping. A second serve
             // journals nothing now, and serves everything else exactly as it did.
-            const days = config.historyDays.value;
+            const days = args.demo ? null : config.historyDays.value;
+            // Said rather than dropped in silence. `serve` opens by naming what it decided and on
+            // whose authority, and a retention someone typed that this run is going to ignore is
+            // exactly the kind of thing that discipline exists for.
+            if (args.demo && config.historyDays.value !== null)
+                console.log(`tarmac: --demo writes no journal, so the ${config.historyDays.value}-day retention is ignored`);
             const { lock, heldBy } = days === null ? { lock: null, heldBy: null } : acquireJournalLock({ dir: historyDir });
             // On stdout, under the settings block it corrects: that block has just named a retention
             // and a directory, and a reader piping it must not be left holding the half of it that
@@ -194,18 +221,38 @@ try {
             // it says what it did rather than doing it quietly, this being the user's directory. It
             // is no longer the only deletion a `serve` makes: a journal that was asked for applies
             // its retention on `listening`, and says that too. Nothing else here removes anything.
-            const { reaped, failed } = reapOrphanedTemps(snapshotsDir);
-            if (reaped > 0)
-                console.log(`tarmac: reaped ${reaped} orphaned snapshot temp file(s)`);
-            if (failed > 0)
-                console.error(`tarmac: could not remove ${failed} orphaned temp file(s) under ${snapshotsDir}`);
+            if (!args.demo) {
+                const { reaped, failed } = reapOrphanedTemps(snapshotsDir);
+                if (reaped > 0)
+                    console.log(`tarmac: reaped ${reaped} orphaned snapshot temp file(s)`);
+                if (failed > 0)
+                    console.error(`tarmac: could not remove ${failed} orphaned temp file(s) under ${snapshotsDir}`);
+            }
+            // The invented day ends now, so the last minute of it is the fleet the live view shows.
+            const demoDay = args.demo ? demoDayStart() : null;
             const server = createFleetServer({
-                collect: () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null }),
+                collect: demoDay === null
+                    ? () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null })
+                    : demoCollector(demoDay, Date.now, staleAfterMs),
+                // A day of it, already in the ring: the flat charts a first run opens on are the whole
+                // of what #150 is about, and a demo whose record started a minute ago has the same
+                // ones. `undefined` is "keep your own", which is what every other serve gets.
+                history: demoDay === null ? undefined : demoHistory(demoDay),
+                demo: demoDay !== null,
                 trustedHosts: config.trustHosts.value,
                 // No key anywhere is no store, which is no directory and no file: the default is that
                 // nothing of this fleet is written down, and it is the default that is the product.
                 // No lock is no store either, and for the same reason: no store, no sweep, no line.
-                store: days === null || lock === null ? null : createHistoryStore({ dir: historyDir, days, lock }),
+                //
+                // A demo gets a store all the same, and it is the one thing about `--demo` that is not a
+                // suppression: a week of invented days, in memory, answering the range reads through the
+                // seam a real journal answers them through (#156). It writes nothing and opens nothing —
+                // `days` is null above, so no directory was taken and no lock was asked for.
+                store: demoDay !== null
+                    ? createDemoHistoryStore({ dayStart: demoDay })
+                    : days === null || lock === null
+                        ? null
+                        : createHistoryStore({ dir: historyDir, days, lock }),
             });
             // A port nobody chose is not worth failing over: this walks past a busy 4477 and says
             // where it landed. A port that WAS chosen refuses instead, and the refusal leaves
@@ -218,6 +265,13 @@ try {
                 process.exit(1);
             });
             console.log(servingLine(bound));
+            // On stdout, under the line naming the port, and said in the terminal as well as on the
+            // page: whoever opens that URL sees the badge, and whoever left the process running in
+            // another window has only this.
+            // "No fleet", not "nothing": the settings this serve is running on were resolved the
+            // ordinary way, config file included. What was never opened is the fleet.
+            if (demoDay !== null)
+                console.log('tarmac: demo data — an invented fleet. No fleet on this machine was read.');
         }
         else {
             const collect = () => collectFleet({ claudeBin: args.claudeBin, snapshotsDir, staleAfterMs, snapshotsDirSource: config.snapshotsDir.source, installed: frozen !== null });

package/dist/collect.js

@@ -5,7 +5,7 @@ import { readSnapshots } from './snapshots.js';
 import { buildFleet } from './fleet.js';
 export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(), staleAfterMs, snapshotsDirSource = 'default', installed = false, }) {
     const { sessions, health: discovery } = await discoverSessions({ claudeBin });
-    const { snapshots, dirError, unreadable, duplicates, dirMissing } = readSnapshots(snapshotsDir, { now });
+    const { snapshots, dirError, unreadable, notFiles, duplicates, dirMissing } = readSnapshots(snapshotsDir, { now });
     const fleet = buildFleet({ sessions, snapshots, now, discovery, staleAfterMs });
     // Both blind spots travel with the data: a directory we could not read and files we
     // could not parse are OUR failures to report, not silence to render as "all clear".
@@ -28,6 +28,7 @@ export async function collectFleet({ claudeBin, snapshotsDir, now = Date.now(),
                 ? `ENOENT: ${snapshotsDir} does not exist — the installed wrapper writes there`
                 : dirError;
     fleet.health.snapshotsUnreadable = unreadable;
+    fleet.health.snapshotsNotFiles = notFiles;
     fleet.health.snapshotsDuplicates = duplicates;
     fleet.health.snapshotsDir = snapshotsDir;
     return fleet;

package/dist/demo-history.js

@@ -0,0 +1,184 @@
+// The week of journal `serve --demo` shows, invented in memory.
+//
+// Why it ships. `/history` was the one page of the demo that showed the product switched off:
+// "History is off.", the 7d and 30d pills greyed out, nothing for the range charts or the
+// scrubber to draw — on exactly the surface they were built for (#156). A demo serve has a past
+// now, and it is a past nothing wrote down.
+//
+// Where it plugs in, and why THERE. It is a `HistoryStore`, the same object a real journal hands
+// the server, so the range route asks it the question it asks any store and never learns where
+// the days came from. Underneath, the days go through `readRange` — the one place that turns
+// records into hours, project costs and window turnovers — via the day seam that reader takes.
+// So there is no second aggregation and no second rendering path: what the demo shows is what a
+// real journal of the same records would show, arrived at by the same code.
+//
+// What it may not do, held by `test/demo-history.test.ts` and by the end-to-end check in
+// `test/demo.test.ts`: touch a disk. Nothing here opens, creates or removes a file. The
+// directory it names is under the invented home, for the same reason every other demo path is,
+// and it exists to be reported and never to be opened.
+//
+// One story, not two. Every record is `demoFleetAt` played through the same `record` a real
+// sampler calls and then through the store's own allowlist, so the last day of the journal and
+// the ring behind the scrubber are the same readings, minute for minute.
+import { demoFleetAt, DEMO_HOME, DEMO_MINUTES } from './demo.js';
+import { createHistory } from './history.js';
+import { readRange } from './history-range.js';
+import { journalRecordOf } from './history-store.js';
+/**
+ * How many local days of it there are, today included.
+ *
+ * Seven and not thirty. A month is four times the work for a page that says what it covers
+ * anyway, and a `30d` that answers the week it has is a range showing what exists — which beats
+ * one invented badly, and is what a real journal younger than its retention already does.
+ */
+export const DEMO_JOURNAL_DAYS = 7;
+/**
+ * Where the journal would live if there were one. Named because a store names its directory,
+ * never opened by anything here — and under the invented home, so a capture of a demo carries
+ * no path off the machine that took it.
+ */
+export const DEMO_HISTORY_DIR = `${DEMO_HOME}/.local/state/tarmac/history`;
+const MINUTE = 60_000;
+/**
+ * How long the invented day is, as a span rather than as a slot count.
+ *
+ * `DEMO_MINUTES` is one more than the ring holds, so that the record dates itself by its own
+ * oldest reading. The DAY it plays is the 24 hours those minutes cover, and this is the period
+ * the past repeats on.
+ *
+ * It decides the SHAPE of the past and never its density — a record is written every minute
+ * whatever this says. A period shorter than the day plays the fleet arriving and going home
+ * more than once between two midnights, which charges a fraction of a day's work to each of
+ * them and can leave an actor born late in the day out of the week entirely. The suite holds
+ * the consequence rather than the number: every full day of the invented week costs the same
+ * and carries all five projects, which is true of a whole day repeated and of nothing else.
+ *
+ * What is NOT held, because it cannot be seen: whether an older cycle replays the day's last
+ * minute or stops one short of it. Both tile the past exactly and both leave every day the same
+ * length, the same cost and the same fleet. This is the day the ring covers, which makes it the
+ * defensible choice rather than the pinned one.
+ */
+const CYCLE_MS = (DEMO_MINUTES - 1) * MINUTE;
+const pad = (n) => String(n).padStart(2, '0');
+/** The local day a moment falls on, `YYYY-MM-DD` — the name a journal file carries. */
+const dayOf = (t) => {
+    const d = new Date(t);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+};
+/** Local midnight of a named day, which is the inverse of the name above. */
+function midnightOf(date) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (m === null)
+        return null;
+    const t = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])).getTime();
+    return Number.isFinite(t) ? t : null;
+}
+/**
+ * The oldest day this journal answers for, today included: the same calendar arithmetic a real
+ * retention uses, so the demo's week is a week the way a reader's is and not 168 hours.
+ */
+const oldestDay = (now, days) => {
+    const d = new Date(now);
+    return dayOf(new Date(d.getFullYear(), d.getMonth(), d.getDate() - (days - 1)).getTime());
+};
+/**
+ * The newest minute this journal has, which is the newest minute the RING has: the moment the
+ * serve started, and the fleet the live view shows for as long as it is open.
+ *
+ * The journal stops there rather than at the clock that asked, for the reason the demo runs no
+ * sampler at all — the record it was handed is the record it keeps. Bounded by `now` instead, a
+ * serve open for three hours invented three hours of minutes past the end of its own day: past
+ * the last segment every actor has, so their costs climbed for ever, and past the newest minute
+ * of the ring, so the two stopped telling one story an hour in. It also made the answer depend
+ * on when it was asked, which is the one thing a demo may not do.
+ */
+const endOfPast = (dayStart) => dayStart + (DEMO_MINUTES - 1) * MINUTE;
+/**
+ * Which repetition of the invented day a moment falls in, given the day the ring is anchored on.
+ *
+ * The last one is the ring's own, unshifted, which is what makes the newest journal day and the
+ * record behind the scrubber the same readings rather than two accounts of one fleet. Anything
+ * earlier is that same day again, a whole number of days back — a fleet that arrives, works and
+ * goes home, five projects at a time, for a week.
+ *
+ * The floor at zero is the ring's own last minute, `DEMO_MINUTES - 1`, which is a whole cycle
+ * after `dayStart` and belongs to the cycle that started there rather than to the next one.
+ * Nothing is ever asked past it: `endOfPast` above is where the journal stops.
+ */
+const cycleStartFor = (t, dayStart) => dayStart - Math.max(0, Math.ceil((dayStart - t) / CYCLE_MS)) * CYCLE_MS;
+/**
+ * One local day of the invented journal, as the file of that name would have read, or `null`
+ * for a day this journal does not cover.
+ *
+ * The readings sit on the RING's minute grid rather than on the hour, so the day that overlaps
+ * the ring carries the ring's own minutes and the two can be compared reading for reading.
+ *
+ * A function of `dayStart` and nothing else, the clock that asks included: a demo whose past
+ * grew while somebody looked at it would be a screenshot nobody could re-take.
+ */
+export function demoJournalDay(date, dayStart) {
+    const midnight = midnightOf(date);
+    if (midnight === null)
+        return null;
+    const last = endOfPast(dayStart);
+    if (date < oldestDay(last, DEMO_JOURNAL_DAYS) || date > dayOf(last))
+        return null;
+    // The next local midnight, which is 23, 24 or 25 hours along — calendar arithmetic, never a
+    // 24-hour block, so the morning a clock shifts does not lose or double an hour of the day.
+    const d = new Date(midnight);
+    const end = Math.min(new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime() - 1, last);
+    const from = Math.ceil((midnight - dayStart) / MINUTE);
+    const to = Math.floor((end - dayStart) / MINUTE);
+    if (to < from)
+        return null;
+    // The sampler's own path: `record` is what a real serve calls once a minute, and the sample it
+    // hands back is what the journal writes. The ring it fills on the way is thrown away with this
+    // call — what is wanted is the reduction, and a second copy of that reduction here would be
+    // the one thing this module exists not to be.
+    const ring = createHistory({ since: dayStart, cadence: MINUTE });
+    let text = '';
+    for (let k = from; k <= to; k++) {
+        const t = dayStart + k * MINUTE;
+        const cycleStart = cycleStartFor(t, dayStart);
+        const minute = Math.round((t - cycleStart) / MINUTE);
+        // How many cycles before the newest day this reading belongs to — what lets the seven-day
+        // window climb across the whole invented week instead of replaying one day's ramp.
+        const cyclesBack = Math.round((dayStart - cycleStart) / CYCLE_MS);
+        text += `${JSON.stringify(journalRecordOf(ring.record(demoFleetAt(minute, cycleStart, t, undefined, cyclesBack))))}\n`;
+    }
+    return text;
+}
+/**
+ * The store `serve --demo` hands the server in place of a real journal.
+ *
+ * Everything a writing store does is a no-op here, and none of them is ever called: a demo runs
+ * no sampler, so nothing appends, and it takes no directory, so nothing sweeps. They are written
+ * out rather than thrown from, because a store that threw would turn a tick into a 500 the day
+ * something did call one.
+ */
+export function createDemoHistoryStore({ dayStart }) {
+    return {
+        dir: DEMO_HISTORY_DIR,
+        days: DEMO_JOURNAL_DAYS,
+        heartbeat() {
+            // No directory, no lock, nothing to keep alive.
+        },
+        append() {
+            // A demo serve records nothing, and this is the guarantee rather than the consequence.
+        },
+        prune: () => ({ removed: 0, failed: 0 }),
+        // Zeroes that are measurements: there is no file and no byte, which is a fact and not an
+        // absence. `capped` is false for the same reason — nothing here can fill.
+        stats: () => ({ files: 0, bytes: 0, misses: 0, stopped: null, capped: false }),
+        read: (range, now) => 
+        // `now` decides which calendar days the range covers, as it does for a real journal; what
+        // is IN each of them is the serve's own frozen past. So a demo left open loses a day off
+        // the front at each midnight — six of seven the next morning, and nothing at all a week
+        // in, which is the empty page this exists to remove, reached quietly. The alternative is
+        // to date the range on the frozen past too, and then a serve open for three days draws a
+        // week that ended three days ago under a live view dated now. Neither is right for a
+        // process meant to be opened, looked at and closed; this one at least degrades the way a
+        // real journal that stopped being written does.
+        readRange({ dir: DEMO_HISTORY_DIR, range, now, readDay: async (date) => demoJournalDay(date, dayStart) }),
+    };
+}