@adrrr/tarmac 0.8.1 → 0.10.0

package/README.md

@@ -13,7 +13,7 @@ documented surfaces only, never an internal format.
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/replay-dark.gif">
   <img src="docs/media/replay-light.gif" width="1100"
-       alt="The tarmac map, live and then replayed. It opens on the live fleet, whose nodes are grouped into a frame per working directory, each labelled with its project. As the scrubber is dragged the frames give way to the flat record: sessions drawn as dials, each arc a context window, background agents as strips of text, with the account's five-hour and seven-day gauges above them. Sessions appear and disappear, the arcs fill and reset, the five-hour window fills and rolls over, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
+       alt="The tarmac map, live and then replayed. It opens on the live fleet: nodes grouped into a frame per working directory, each frame labelled with its project, sessions drawn as dials whose arc is the context window, background agents docked under the cards as strips of text, and the account's five-hour and seven-day gauges in the header. As the scrubber under the fleet is dragged the frames give way to the flat record, every node in a cell of one size, sessions still dials and agents still strips, each with its project and what it has cost. Sessions appear as the day walks past and the grid gains a cell for each, the arcs fill, the five-hour gauge fills and rolls over to zero, and a banner names the minute being replayed until Back to live is pressed and the frames come back.">
 </picture>
 
 [Quickstart](#quickstart) · [The map](#the-map) · [The curves](#the-curves) · [Install](#install) ·
@@ -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 month 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 month 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 month it shows is
+invented in memory, like the rest of it — and the page it serves is badged `demo data`
+throughout.
+
 ```
 $ npx @adrrr/tarmac
 
@@ -76,7 +84,7 @@ listening rules are [there too](docs/MANUAL.md#what-serve-listens-on).
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/map-dark.png">
   <img src="docs/media/map-light.png" width="1100"
-       alt="The tarmac map, live. Four framed groups, one per working directory and labelled with its project: beacon, holding a session halted on a permission prompt; harbor, holding a session busy with its context arc at 90% and a background agent docked under the cards of that frame as a strip named after its prompt; quay, reporting a status tarmac does not know; and atlas, idle at 36%. A frame says only that its nodes were read in the same directory. Nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit above them, and one warning above the fleet names the unrecognised status rather than filing it as idle.">
+       alt="The tarmac map, live. Five framed groups, one per working directory and labelled with its project: auth-service, holding a session halted on a permission prompt at 61%; api-gateway, holding a session busy with its context arc at 93% and a background agent docked under the cards of that frame as a strip named after its prompt; data-pipeline, busy at 69% with an agent of its own; docs-site, holding one session reporting a status tarmac does not know and one idle at 39%; and storefront, idle at 23%. A frame says only that its nodes were read in the same directory. Nothing inside one claims that any node dispatched another. The account's five-hour and seven-day gauges sit in the header, one warning above the fleet names the unrecognised status rather than filing it as idle, and the scrubber for the replay sits under the fleet.">
 </picture>
 
 The tabs in the header swap the table for the same fleet drawn as nodes: one per session, the
@@ -95,10 +103,13 @@ session gets its own frame rather than somebody else's.
 Above the fleet are the account's five-hour and seven-day
 [gauges](docs/MANUAL.md#the-accounts-two-windows). Under it is a scrubber over the day this
 serve has seen. Drag it and the nodes render the fleet as it was at that minute. Press play
-and the day walks past. Replayed, the nodes are drawn flat and unframed. The record keeps a
-project name and never the directory it was read in, and a basename is not a directory. Two
-checkouts of `atlas` answer to the same word, so a frame drawn on it would claim a shared
-directory nobody can check.
+and the day walks past. Replayed, the nodes are drawn flat and unframed, every one of them in a
+cell of one size: a session that appears between two minutes of a scrub moves nothing but the
+nodes after it in the sample's own order, and the banner naming the minute stands in a place the
+page keeps for it. A row the grid gains still pushes what is under it, and on a phone the banner
+wraps where the live line does not. The record keeps a project name and never the directory it
+was read in, and a basename is not a directory. Two checkouts of `atlas` answer to the same
+word, so a frame drawn on it would claim a shared directory nobody can check.
 
 The map follows the rules the table follows. A reading past the freshness threshold is drawn
 thin, amber and dated. A percentage nobody measured is an empty dotted dial, never a ring at
@@ -115,6 +126,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 band per project: four sawtooths that climb through the day and break where the session was recycled, and storefront, a short stroke a day near the baseline. None carries the arrow that marks a climbing line, since the panel counts nothing climbing over this range. Cost is one stacked bar per day in a fixed project order, seven days between $128 and $221. 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,
@@ -220,11 +237,12 @@ and what would have worked. Spellings, edge cases and the two health fields
 ```bash
 npm test                       # typecheck (src + test + scripts), then run the suite
 npm run build                  # flat JavaScript into dist/
-node scripts/demo-fleet.ts     # the invented fleet the captures above are taken of
+node scripts/demo-fleet.ts     # a second invented fleet, served on a port
 ```
 
-Every capture on this page is taken of a fleet that does not exist. A screenshot of a real
-machine carries working directories, prompts and costs, and nothing real enters this repo.
+Every capture on this page is taken of `serve --demo`, a fleet that does not exist. A
+screenshot of a real machine carries working directories, prompts and costs, and nothing real
+enters this repo.
 What CI covers, which Node version develops and which one ships:
 [the manual](docs/MANUAL.md#developing). Capturing the fixtures for a new Claude Code build:
 [the manual](docs/MANUAL.md#capturing-a-new-claude-code-version).

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,244 @@
+// The month 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 every minute the journal and the
+// ring share is the same reading in both — which is the last TWO calendar days, the ring being
+// twenty-four hours long and midnights being where they are. The days before those are that same
+// day again, scaled: see `demoDayFactor`, which is where a month of columns stops being a month
+// of one column.
+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.
+ *
+ * Thirty, which is what the longest range asks for. A week answered both pills with the same
+ * seven columns, so `30d` and `7d` drew the identical picture on the one serve built to show
+ * them full — a range showing what exists is honest of a real journal younger than its
+ * retention, and pointless of a past that is invented anyway. Four times the records, and the
+ * whole month is built in about a third of a second.
+ */
+export const DEMO_JOURNAL_DAYS = 30;
+/** A local day, in milliseconds. Used to count days apart, never to walk from one to the next. */
+const DAY = 86_400_000;
+/**
+ * What a day of the invented past cost, as a multiple of the day the ring holds.
+ *
+ * A month of identical columns at $147 is a chart that says "made up" before the reader has read
+ * the axis. A fleet's week has a shape — weekends nobody works, an ordinary run of weekdays, and
+ * now and then a day something big shipped — and that shape is the thing the cost chart exists
+ * to show, so the invented one has it too.
+ *
+ * Deterministic and stateless: a function of which day it is and nothing else, so two reads of
+ * one demo are one answer and a screenshot can be taken twice. The multiplier off Knuth's
+ * constant is a spread, not randomness — it just has to be unmemorable and stable.
+ *
+ * Never asked about a day the ring reaches into — `demoJournalDay` answers 1 for those without
+ * coming here, and there are two of them, the ring being twenty-four hours long. The one thing
+ * this journal may not do is disagree with the record behind the scrubber about a minute they
+ * both hold. What is left for this to scale is the past nobody can compare against.
+ *
+ * The long day is a weekday, which is what keeps the shape readable: the peaks are then above
+ * every ordinary day and the weekends below every one of them, rather than a Saturday at $220
+ * saying the opposite of what the chart is showing. Seventeen apart is at most two of them in a
+ * month and never none — seventeen days is three weekdays along, so the pair cannot both land on
+ * a weekend.
+ */
+export function demoDayFactor(back, weekday) {
+    if (back <= 0)
+        return 1;
+    const spread = ((back * 2_654_435_761) % 1000) / 1000;
+    if (weekday === 0 || weekday === 6)
+        return 0.55 + 0.12 * spread;
+    if (back % 17 === 6)
+        return 1.5;
+    return 0.85 + 0.38 * spread;
+}
+/**
+ * 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 past carries all five
+ * projects, and each of them costs its own day's scale of one whole day's work — 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 });
+    // What this whole day cost, against the day the ring holds. Decided once for the day rather
+    // than per reading: the reader charges a day what a session's highest reading in it exceeds its
+    // lowest, and a multiplier that moved inside the day would be charged that movement as spending.
+    //
+    // A day the RING reaches into is never scaled, and that is two calendar days rather than one:
+    // `dayStart` is twenty-four hours back, so the ring straddles a midnight on every clock but
+    // midnight itself. Scaled on the older of the two, 719 of the ring's 1440 minutes went into the
+    // journal at another price — the cost chart billing yesterday 14% above what the scrubber shows
+    // for the same minutes, which is the one disagreement this module exists to prevent. `end` is
+    // this day's last moment, so a day the ring reaches into is one that ends at or after its first.
+    const factor = end >= dayStart ? 1 : demoDayFactor(Math.round((midnightOf(dayOf(last)) - midnight) / DAY), d.getDay());
+    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 a whole invented week instead of replaying one day's ramp. Modulo the
+        // week, because that is how long the window IS: a ramp running the length of the journal put
+        // the account four times over its plan by the middle of the month and then flat on the floor
+        // for the three weeks before it, where a real one rolls over every seven days.
+        const cyclesBack = Math.round((dayStart - cycleStart) / CYCLE_MS) % 7;
+        const record = journalRecordOf(ring.record(demoFleetAt(minute, cycleStart, t, undefined, cyclesBack)));
+        if (factor !== 1)
+            for (const s of record.sessions)
+                if (s.costUsd !== null)
+                    s.costUsd = Math.round(s.costUsd * factor * 100) / 100;
+        text += `${JSON.stringify(record)}\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) }),
+    };
+}