# Verified codebase facts

Facts established by reading the tree, each with a `file:line` anchor. **Trust these over
re-deriving them** — that is the entire point of this file. If one turns out to be stale,
correct it in place and note the correction in `STATE.md`.

Append as you verify new things. Do not add anything here you have not actually checked.

Last full verification pass: **2026-07-26**, against `main` @ `18c5a7a`.

---

## Corrections to the original draft plan

These were confidently stated and **wrong**. They are the most valuable entries here.

### `windowCues()` is not a chunker

`common/lib/transcriptWindow.ts:21` —
`windowCues(cues, centerSeconds, { before = 45, after = 45, maxCues = 60 })`. It is a
**center-based** window around a search hit, with `before`/`after` in **seconds**. It
cannot split a transcript into sequential context-sized chunks. Callers:
`export/app/ask/useAskChat.ts:1333`, `export/app/lib/searchAgent.ts:509,742`.

→ A sequential `chunkCuesForContext()` must be written. Put it in the same file; it is pure
and `transcriptWindow.test.ts` already exists.

### No LMDB `maxDbs` bump is needed

`maxDbs` caps the named DBs opened *by one handle*, not the DBs present in the environment.

- `common/controller/buildIndex.ts` — `maxDbs: 17`, now opens **15**: the original 12
  (`sums`, `cues`, `subs`, `mtimes`, `byChannel`, `pageHashes`, `subPageHashes`,
  `channelStats`, `posts`, `postPageHashes`, `channelPostsStats`, `meta`) plus the three
  Phase 2 added (`digests`, `digestPageHashes`, `channelDigestStats`). Still under.
- `common/lib/channelSignature.ts:48` — `maxDbs: 14`, opens **2** (`mtimes`, `meta`).
- `common/controller/duplicateShorts.ts:111` — `maxDbs: 12`, opens **3**.

None of these break. The "17 vs 14 inconsistency" is a red herring.

→ What **was** required and easy to miss: the schema-invalidation block enumerates every
sub-DB by hand with `clearAsync()`. **Done (2026-07-29)** — the three digest sub-DBs are
listed there and `SCHEMA_VERSION` is **13**. The next person to add a sub-DB still has to
add its `clearAsync()` line by hand; nothing enforces it.

### `JobProgressMetric` is not a closed union in practice — **RESOLVED, table was stale**

**This entry is kept only to stop the next session re-doing it. Verified 2026-07-29: all of
it is already done.** The union is extended and every site is correct:

- `common/jobs/registry.ts:17` — `JobProgressMetric` is `"downloads" | "transcripts" |
  "digests"`, and `:25` `JobTaskKind` is `"download" | "transcribe" | "digest"`.
- `editor/app/jobs/components/RunningJobsList.tsx:6-9` **imports** `JobProgressMetric` and
  `JobTaskKind` rather than re-spelling them, so TypeScript now does flag the next member.
  A comment on the union at `registry.ts:14` records that this is why.
- `editor/app/widget/components/MonitorWidget.tsx:628` is a `METRIC_PREFIX` lookup table
  (`Record<JobProgressMetric, string>`), not the two copies of a `metric === "downloads" ? …`
  binary the old table described — so it is exhaustiveness-checked and there is nothing
  left to duplicate.

PLAN.md's Phase 2.5 opens by demanding this fix "first". It is done; start 2.5 at its
second item.

### Queue concurrency is not declared per key

`common/lib/queueKeys.ts` has **no** concurrency map. `common/jobs/registry.ts:158`
hardcodes `concurrency: 1` for every non-empty `queueKey`. A `queueKey` of `""` means "run
immediately, unserialized".

`TRANSCRIPTION_QUEUE` is defined at `common/lib/platform.ts:112` and merely re-exported from
`queueKeys.ts:2-8`. `resolveQueueKey(defaultKey, override)` is at `queueKeys.ts:27-32`:
`undefined` → default, `""` → immediate, else trimmed.

### `resolveCitationSeconds` snaps to snippets, not cues

`export/app/ask/citations.tsx:76` scans `src.snippets` — only the ~5 matched lines per
video (`export/app/lib/askRetrieval.ts:132`). It never sees a cue list, so it cannot be
reused for cue snapping.

→ The right reference for a cue-boundary snap is `findActiveIndex`
(`common/components/TranscriptModal.tsx:473-491`), a hand-rolled binary search over cue
starts.

### There is no vitest or jest

Unit tests are `node:test` run via `tsx --test`. Only `mcp/package.json:12` has a `test`
script (`tsx --test src/*.test.ts`). `common/package.json` has **no `scripts` key at all**;
neither `editor` nor `export` has a `test` script. ~46 `*.test.ts` files across the repo are
unrunnable as a suite today.

*(Amended 2026-09-28, release 13 slice W2: no longer true. Every package with unit tests has a
`test` script — `common` (`pnpm --filter yt-dlp-transcript-common test`), `mcp`, `homepage`,
`export` (added by W2: `tsx --test "app/**/*.test.ts"`, 11 files / 98 tests) and `editor`
(added by W1 in the same release). The list is in `CONTRIBUTING.md`, "Tests", and the gate list
in `plans/tools/implementer-rules.md`. Still no vitest or jest.)*

### `subsCache.ts` has no IndexedDB

- `common/components/subsCache.ts` — memory + react-query only.
- `common/components/summariesCache.ts` — pure react-query, eager over all pages, no IDB, no
  `slugToPage`.
- `common/components/transcriptCache.ts` — the lazy fetch/memo layer (manifest →
  `slugToPage` → page), and it opportunistically warms every entry in a fetched page.
- `common/components/transcriptStore.ts` — the IDB layer. `DB_NAME =
  "yt-dlp-transcript-browser"`, **`DB_VERSION = 4`** (`:15`), `STORE = "transcripts"`. Its
  `onupgradeneeded` (`:43-47`) **deletes and recreates** the store, so a version bump wipes
  the cache.

→ Copy the `transcriptCache` + `transcriptStore` **pair**.
→ `editor/e2e/export-player-platform-cache.spec.ts:115` hardcodes DB version **3** and is
already stale relative to `DB_VERSION = 4`.

### Social-posts incrementality cannot be copied for a per-video artifact

`buildIndex.ts:233` — `scanSource()` does `if (isSocialChannel(cfg)) continue;`. Social
channels never enter the mtime scan at all, which is *why* posts use a per-channel
shard-signature (`buildIndex.ts:1088-1118`) instead of `MtimeRecord`.

→ For a per-video artifact use the mtime mechanism (`digestMs` in `MtimeRecord`). Follow the
posts precedent (`buildIndex.ts:1065-1240`) only for the **page-tree emission shape**.

### Archive gating already has a seam

`common/controller/archiveTranscripts.ts:177` computes
`const requiresRewrite = !build.includeMetadata || build.prettyPrint;` and branches at
`:205-209` to `writeTransformedCues(...)` vs `link(...)` (a hard link straight from the
source tree).

→ Phase 8 extends that predicate and that transform, rather than building a parallel gate.

---

## Naming hazards

**`summaries` is taken.** `exportSummariesDir` (`common/lib/paths.ts:58,151`) →
`/summaries/{manifest,page-NNNN}.json` is the cross-channel browse index of video *metadata*
(`DisplaySummary` records), documented in `common/lib/corpus.ts:35-36` and served by
`common/components/summariesCache.ts`. Nothing to do with AI summaries. Use **`digest`**.

**Never name a sidecar `transcript.<x>.<y>`.** `common/lib/videoStatus.ts:88` —
`export const SUB_FILE_RE = /^transcript\.([^.]+)\.([^.]+)$/;` treats any such file as a
subtitle track. The exclusion list in `readSubTracks` is hardcoded. Use `ai-digest.json`,
`diarization.json`, `attribution.json`. Since one-core phase 3 slice 4b (2026-09-24) a
sidecar is declared with `sidecar(filename, schema)` (`common/lib/sidecar-server.ts`), which
THROWS at declaration — module load — on a name `SUB_FILE_RE` matches;
`sidecar-server.test.ts` enumerates `SIDECAR_FILENAMES`.

**`report` already means three things**: `reportDebouncePreset` in settings, the
`refresh-report` job kind, and `/ask`'s `ReportPanel`. Use `feedback` / `review` instead.

**`tags` means three unrelated things, and the record field is `curatedTags`.**

| Which | Where | What it is |
| --- | --- | --- |
| yt-dlp keywords | `common/lib/transcripts.ts:21` — `TranscriptSummary.tags` | The platform's own keywords from `metadata.info.json`, searchable via the `"tags"` scope. The UI label for this scope is being changed to **"Keywords"** (`QueryLeafView.tsx:46,156-159`); the code token, the URL and the MCP `scopes` enum stay `"tags"`. |
| AI digest topic tags | `common/lib/digests.ts` — `VideoDigest.tags` | Model-generated topics on a digested video. |
| **Curated tags** | `common/lib/curatedTags.ts`; record field **`curatedTags`** | The operator's cross-channel vocabulary ("every stream where X collabs"), published at `/tags.json`. |

Never name the curated field `tags`. Never assume a `tags.json` is the keyword list:
`transcripts/tags.json` and `sites/<id>/tags.json` are curated tags.

**`listed` / `unlisted` mean three unrelated things** (release 14, slice HS):

| Which | Where | What it is |
| --- | --- | --- |
| A video's visibility | `common/lib/availability.ts` (the `"unlisted"` state, `isUnlisted`), `common/lib/transcripts{,-server}.ts`, `common/components/shareUrl.ts`, `common/controller/buildIndex.ts` | The platform's own "unlisted" (reachable by link, not listed on the channel). |
| The hub's list has loaded | `export/app/components/hub/useHubSites.ts` — `listed` | `/hub-sites.json` has been answered and `/hub-summary.json` has settled. |
| **A site the family lists** | `site.json` `listed` (`common/lib/siteSchema.ts` — `isListedSite`, `channelsOnlyOnUnlistedSites`) | Absent = listed; `false` keeps the site off the homepage, the hub and the other sites' footers, and out of the public totals. A PRIVATE site (`audience: "private"`, release 17 XP) is never listed, whatever `listed` says. |

A grep for either word finds all three; read the file before assuming which.

**Never publish a path segment named `.git`.** wrangler's Pages upload drops `**/.git` (and
`**/node_modules`) SILENTLY, and Cloudflare's managed rules block `/.git/` requests. The source
mirror is `/source/archilyzer.git/` for that reason (release 12, below). A mirror named `.git` would
deploy "successfully" and 404.

---

## Reusable helpers (do not rewrite these)

| What | Where | Notes |
| --- | --- | --- |
| Transcript → text for an AI | `common/lib/transcriptToMarkdown.ts:60` | Declared single source of truth. `stampForCue?: (clock, seconds) => string` at `:43` takes precedence over `linkForCue`. |
| Zero-padded `HH:MM:SS` | `common/lib/aiHandoff.ts:54` — `hms(s)` | So the stamper is `(_clock, s) => hms(s)`. No new formatter needed. |
| Read a normalized transcript | `common/controller/normalizeTranscript.ts:161` | `readNormalizedTranscript(cuesPath)`. |
| Freshness check | `normalizeTranscript.ts:193` | `isCuesJsonFresh(videoDir)`. |
| tmp+rename write idiom | `normalizeTranscript.ts:139-141` | `${path}.tmp-${process.pid}` then `rename`. |
| Engine registry + client-safe listing | `common/lib/transcriptionApps.ts:62-81, 248-278` | The pattern for `digestApps.ts`. |
| Inheritance resolve (global → channel) | `common/lib/cookiePolicy.ts:53-66` | Two rules: truthiness-after-trim for free text, type-guard for enums. |
| Child process into a job log | `common/jobs/runChild.ts:22` | `runChildIntoLog(onLog, signal, opts)`. |
| Bounded concurrent pool | `common/jobs/concurrentRunner.ts:29` | `runPool()`; honors `signal` + `drainSignal`. |
| Managed server action | `editor/app/channels/[slug]/whisperActions.ts:45-103` | The `runManagedFunction` template. |
| Paginated page writer | `common/controller/buildIndex.ts:694` | `createPageWriter()` — size budget + sha1 skip-if-unchanged. |
| Health probe | `common/controller/remoteTranscribe.ts:51` | `pingRemoteHealth(worker, timeoutMs)`. |
| ENOENT → friendly message | `common/social/xGalleryDlFetcher.ts:207-213` | `/ENOENT/.test(message) ? "X not found (set X_BIN)" : message`. |
| ETA estimator | `editor/app/jobs/active/buildActiveJobs.ts:38` | `computeEtaSeconds`. |
| Binary search over cue starts | `common/components/TranscriptModal.tsx:473-491` | `findActiveIndex`. |
| Curated-tag model (pure) | `common/lib/curatedTags.ts` | `sanitizeTagsConfig` / `mergeTagDefs` / `effectiveTagsFor` / `compileTagRules` + `evaluateCompiledRules`. Compile ONCE per build, evaluate per video. |
| Curated-tag persistence | `common/lib/curatedTagsStore.ts:198` | `applyTagAssignments` — the ONE write path for every tag writer (editor, ops, umtool); one atomic write per call, and it refuses to pin a tag the vocabulary does not define. |
| A chat cue's author | `common/lib/curatedTags.ts:495` — `chatAuthorOf` | The `<author>: ` prefix; there is no `author` field on `Cue`. |

---

## Transcription engines (Phase 0)

All three are **already selectable** — `common/lib/transcriptionApps.ts:248-252`:

| id | Label | Line | Fields | Notes |
| --- | --- | --- | --- | --- |
| `whisper-cpp` | whisper.cpp (whisper-cli) | 157 | model, customArgs | `DEFAULT_TRANSCRIPTION_APP_ID` (`:254`) |
| `chough` | chough | 179 | model, remoteUrl, chunkSize | writes exactly the `-o` path |
| `parakeet` | parakeet.cpp (overlapping segments) | 216 | model, chunkSize, device | **`supportsPartialStop: true`** (`:222`) — stops after the current window and stitches a partial transcript on SIGTERM, so a long run is interruptible |

Exposed to the settings form via `listTranscriptionApps()` (`:272`), consumed at
`editor/app/settings/page.tsx:45`. Per-worker `appId` means a mixed fleet already works
(`Worker.appId`, `common/lib/workers.ts:102`; this anchor was `settings.ts:837` before 2026-09-23).

**Nothing measures relative speed.** Phase 0 fills that gap — record the numbers below.

> _Benchmark results: not yet measured._

---

## Build pipeline constants

| Constant | Where | Value |
| --- | --- | --- |
| `SCHEMA_VERSION` | `buildIndex.ts:165` | **13** — and curated tags deliberately did NOT bump it (2026-09-21); see below |
| `CUES_FILE_VERSION` | `normalizeTranscript.ts:33` | 2 |
| `CORPUS_SPEC_VERSION` | `common/lib/archive/contract.ts:35` (re-exported `corpus.ts:59`) | **4** (3 → 4 for `/tags.json`, 2026-09-21) |
| `MANIFEST_VERSION` (site summaries) | `common/lib/manifest.ts:36` | 3 |
| `TRANSCRIPTS_MANIFEST_VERSION` | `manifest.ts:43` | 1 |
| `SUBS_MANIFEST_VERSION` | `manifest.ts:59` | 4 |
| `SUMMARIES_PAGE_SIZE` | `manifest.ts:37` | 1000 |
| `DEFAULT_ARCHIVE_MAX_BYTES` | `common/lib/archiveOptions.ts:72` | 25 MB — over it, **all** archives are dropped |

`MtimeRecord` (`buildIndex.ts:146-154`): `metaMs`, `transcriptMs`, `subsMs`,
`availabilityMs`, `isDeleted`, `isUnlisted`, `indexKey`.
Changed-detection comparison at `:455-468`; the single `mtimes.put` at `:631-639`.

`channelSignature.ts` uses a **narrower structural subset** (`:23-27`): only `metaMs`,
`transcriptMs`, `subsMs`, and its hash (`:65-83`) covers only those three. **A new per-video
artifact that does not move one of those three will not invalidate archive/compose caches.**

`compose-site.ts`: `ComposeCache` at `:486-495`; `reconcileChannelTree()` at `:579`, called
three times (`:667` transcripts, `:675` subs, `:686` posts); it passes
`ignoreBasename: "manifest.json"` internally at `:597` because `generatedAt` churns.

Transcript shards ship the **full `cues` array inline** — `buildIndex.ts:830-832`.

### Curated tags invalidate through `meta`, not through mtimes (2026-09-21)

`curatedTags` is DERIVED at build time — `(rule hits ∪ pins) − suppressions` — and **rule
hits are never persisted**. So nothing in the per-video mtime diff can see that a rule was
edited or a video pinned, and the mechanism is four keys in the existing `meta` sub-DB
(`common/controller/curatedTagsIndex.ts:44-52`), checked **unconditionally on every build**:

| Key | Covers | Deliberately excludes |
| --- | --- | --- |
| `curatedRulesHash` | every def's id + `order`, and every **enabled** rule's kind, pattern, channel scope and date range | label / colour / group / hidden — relabelling a tag must not re-page 30,000 videos |
| `curatedAssignHash` | every pin and suppression | — |
| `curatedAssignSigs` | per-key `manual|suppressed` signature | not a hash: it is what makes an assignment-only edit re-derive just the videos that moved |
| `curatedPagesPending` | "records were re-derived, the shared pages have not been written yet" | set when the hashes are recorded WITH changes, cleared only after the shared page build — without it a Ctrl-C between the two would store the hashes and leave the shards stale for ever, since the next build would compare equal and dirty nothing |

`reapplyCuratedTags` (`:279`) runs after the mtime diff: rules changed → every video is a
candidate (cue reads gated per video by channel/date scope); assignments changed → only the
symmetric difference of the signatures, located by a key-only `byChannel` range scan per
affected channel. **It is `async` and yields to the event loop every
`CURATED_REAPPLY_YIELD_EVERY` (200) records walked**, in both loops — a rule edit makes this

- **Key-only LMDB range scans use `getRange({start,end})` WITHOUT `values: false`** (verified 2026-09-22): with that option lmdb-js yields bare keys, not `{key, value}`, so `for (const { key } of …)` reads `undefined`. The first assignment-only re-apply on the real corpus crashed on exactly this (`8db8a3be`); `recencyIndex.ts:111` documents the same convention, and the test fake now yields bare keys under `values: false`.
the one whole-corpus pass in the build, and at ~500 cue-decodes/second an unscoped caption
rule is 2–3 minutes; run synchronously inside the editor that blocked every page render for
the duration (observed live 2026-09-21, `/channels` `/jobs` `/tags` all >25 s). The
whole-corpus scan therefore passes `snapshot: false` to `sums.getRange`, lmdb-js's
long-duration-iterator idiom, so the read transaction is not held open across minutes of
writes. `ReapplyResult.yields` reports the count; it is 0 below the interval. It re-derives out of LMDB — **no video directory is read twice** — and
whatever it changes flips `sharedNeedsBuild`, because the page writer's sha1 skip is what
then leaves the untouched pages untouched — and `curatedPagesPending` is what covers the
build that was interrupted between the two. The per-site fingerprint (`buildIndex.ts:1765`)
includes both hashes, or a tag-only edit would leave a site reporting "up to date" with
yesterday's counts. **No new sub-DB**, so the `clearAsync()` enumeration is unchanged.

**And no `SCHEMA_VERSION` bump — on purpose.** Every prior bump existed because something
would otherwise never be derived at all (v13 populates a new sub-DB; nothing re-derives it
lazily). Curated tags re-derive lazily *by design*: `curatedRulesHash` is absent on an index
built before them, so it can never equal the current hash and the first build re-derives
every record on its own — ~80 s across 30k videos, out of LMDB, and **zero page writes on an
untagged corpus** because an empty derivation leaves each summary byte-identical (tested:
"an UNTAGGED corpus cold-starts to zero changes"). A bump would instead wipe the cache and
re-read 76k video directories to reach exactly the same state.

**The site layer is presentation-only.** `sites/<id>/tags.json` relabels, recolours,
reorders, hides and may add site-only tags; it can never delete a corpus rule or an
assignment. A site-layer RULE is accepted by `mergeTagDefs` (harmless on a published def)
but **never tags a record**: rules are evaluated once at index time over records SHARED by
every site carrying the channel, so there is no per-site record for a per-site hit to live
in. Rules bind only from `transcripts/tags.json` — promote one there to make it fire. The
editor therefore offers no site-side rule editor.

**`CuratedTagDef.label` is OPTIONAL, and that is what makes the overlay work.**
`sanitizeTagsConfig(raw, {layer})` defaults a missing label to the id at the `global` layer
and leaves it ABSENT at the `site` layer (`readSiteTags`/`writeSiteTags` pass `site`, in both
directions, because the file is sanitized on write AND on every read). Without that, a site
row that set only a colour would arrive at `mergeTagDefs` carrying `label: <id>` and rename
the tag on that site — publishing "eva-collab" where the corpus says "Collab". Every reader
therefore renders `label ?? id`; the one place the fallback is baked in is
`publishedTagsFrom`, because `/tags.json` is read, not layered.

**A chat cue's author is a string prefix, not a field.** `common/lib/liveChat.ts:100-105`
emits every live-chat cue as ``text: author ? `${author}: ${text}` : text`` (`:104`) — `Cue` is
`{start, end, text}` (`vtt.ts:1`) and has no `author`. So a `chat-author` rule matches
`chatAuthorOf(text)` (`curatedTags.ts:495`): everything before the FIRST `": "`, and `null`
when there is none (a cue with no author can never match). Anything that wants the author
of a chat line must use this, not a second copy of the split.

### Measured: what a curated rule costs (2026-09-21, real corpus)

`legal-mindset`, 518 videos / 1.37 M caption cues / 1.47 M live-chat cues, the three seed
rules (metadata + chat-author + caption), run offline against the production LMDB (warm):

| Rules | Wall | LMDB decode | Regex |
| --- | --- | --- | --- |
| metadata only | 18 ms | 0 | 4 ms |
| chat-author only | 848 ms | 727 ms | 110 ms |
| caption only | 421 ms | 302 ms | 109 ms |
| all three | 1.28 s | 1.03 s | 232 ms |

**The cost is the cue decode, not the regex** (4:1). A metadata-only vocabulary is free; a
cue-backed rule costs about 2.5 ms per video with cues, so a whole-corpus re-derive at
Jeralyzer's scale (30,886 videos) projects to ~80 s — a rule edit, not a rebuild. Scoping a
rule with `channels`/`dateFrom` skips the decode entirely for everything out of scope.

Hits on that channel: 7 `eva-collab` (metadata), 96 `eva-in-chat` (chat author), 1
`eva-topic` (caption `\belf ?pire\b|elfpyre|legal loli`) — the caption number is a pattern
problem, not a plumbing one: a spoken name rarely appears spelled that way in ASR output.

---

## Digest bake-off (measured 2026-07-26)

Harness: `plans/tools/digest-bakeoff.ts`. Fixed stratified sample in
`plans/bakeoff/sample.json` (8 videos, 7 channels, 13 min - 8 h), never written
to the corpus. Full tables in `plans/bakeoff/round{1,2}.{json,md}`.

Corpus totals captured by the same scan that picked the sample:
**76,354 videos, 73,367 with transcripts, 77,298 audio-hours**; 6,038 videos over
4 h holding 40,153 h (8.2% of videos, 52% of audio). Sweep days below = measured
seconds-per-audio-hour x 77,298 h, one lane, no parallelism.

### Round 1 — screening (short+medium, absolute)

| Candidate | Zero-yield | Chapters/h | Rejection | Max gap | Generic | Sweep days |
| --- | --- | --- | --- | --- | --- | --- |
| `gemma2:9b@8192` | 0/10 | 15.78 | 0% | 14:59 | 2.3% | 288.1 |
| `qwen3:8b@16384` | 1/7 | 15.42 | 23.6% | 39:57 | 11.9% | 204.9 |
| `mistral-nemo:12b@16384` | 1/7 | 10.28 | 28.2% | 31:20 | 7.1% | 447.3 |
| `qwen3:14b@8192` | 2/10 | 16.52 | 4.3% | 47:51 | 6.7% | 541.3 |
| `qwen2.5:7b@16384` (incumbent) | 2/7 | 6.61 | 55% | 41:37 | 11.1% | 59.0 |

qwen3 candidates were run with `think: false`; with thinking on they spend most
of their output budget on a reasoning block the pinned schema then discards.
Two `qwen3:14b` chunks failed with `fetch failed` (ollama dropped the connection
under memory pressure — a 9.3 GB model on an 8 GB card) and are counted as
zero-yield, which inflates that row. It does not change its exclusion at 541 days.

**The incumbent is the fastest by 3.5x and the worst on quality**: it discards 55%
of what it generates and lands at 6.6 chapters/h against a ~15 target.

### Round 2 — the long tail (2 x ~3.5 h videos, both timestamp modes)

| Candidate | Zero-yield | Chapters/h | Rejection | Max gap | Generic | Sweep days |
| --- | --- | --- | --- | --- | --- | --- |
| `gemma2:9b@8192` **chunk-local** | 0/17 (0%) | 12.93 | 14.3% | 24:04 | 10% | 132.4 |
| `qwen2.5:7b@8192` **chunk-local** | 2/17 (11.8%) | 13.37 | 19.1% | 24:13 | 31.2% | **24.2** |
| `qwen2.5:7b@16384` chunk-local | 1/9 (11.1%) | 9.34 | 41.4% | 1:27:48 | 20% | 25.1 |
| `gemma2:9b@8192` absolute | 3/17 (17.7%) | 11.07 | 28% | 1:04:07 | 5.2% | 127.9 |
| `qwen2.5:7b@8192` absolute | 5/17 (29.4%) | 10.35 | 47.5% | 1:05:16 | 18.1% | 27.7 |
| `qwen2.5:7b@16384` absolute (today's default) | 3/9 (33.3%) | 8.19 | 50.4% | 1:27:48 | 17.5% | 26.8 |

**Three findings, all measured, none assumed:**

1. **chunk-local beats absolute for every model tested**, on the metric this stage
   exists to fix. Zero-yield chunks: 33.3% -> 11.1% (qwen2.5@16k), 29.4% -> 11.8%
   (qwen2.5@8k), 17.7% -> 0% (gemma2). Rejection rate falls with it in every case.
   The hypothesis — that the model cannot hold a large absolute offset across a
   long chunk and reverts to counting from zero — is confirmed.

2. **Smaller chunks are a second, independent win, and they are nearly free.**
   Halving the context (16k -> 8k, 1200 -> 600 cues) took qwen2.5 from 9.34 to
   13.37 chapters/h and its max coverage gap from **1:27:48 to 24:13**. The
   expected cost did not materialise: 24.2 vs 25.1 projected days. Twice the calls
   at half the prompt each is the same seconds-per-audio-hour. The plan's working
   assumption that a smaller context roughly doubles sweep cost is **wrong** —
   it is flat.

3. **Sweep days are far lower than the short-video estimate suggested.** Round 1
   measured 59 days on short+medium; Round 2 measures ~25 on the long tail, because
   long videos amortise the fixed per-call overhead. The 77,298-hour corpus is
   dominated by long videos, so ~25 days is the number to plan against.

**Recommendation: `qwen2.5:7b` at `num_ctx` 8192 with `timestampMode:
"chunk-local"`.** It is a strict improvement over today's default on every axis
measured, including throughput (24.2 vs 26.8 days). Its one weakness is title
quality — 31.2% generic, the worst in the table; by hand its titles read
"Introduction and Context" / "Conclusion and Final Thoughts" where gemma2 writes
"Andrew Wilson and His Comparison to a Serial Killer".

**`gemma2:9b@8192` + chunk-local is the quality option**: 0% zero-yield, 10%
generic, comparable density — at 5.5x the wall-clock (132 days). It is the right
engine for a targeted re-run of high-value channels, not for the first full sweep.
Note gemma2 is hard-capped at an 8192 context by the model itself, so it has no
16k row to compare.

Not yet measured: the >4 h `verylong` stratum (Round 2 used the `long` bucket),
and the ~100-video validation run.

---

## Pilot: community-notes (measured 2026-07-26)

39 videos, local lane, `qwen2.5:7b` / `num_ctx` 8192 / `chunk-local`, launched from the
channel page's Digest stage through the real managed-job path.

| | |
| --- | --- |
| Result | **39 generated, 0 failed**, 90 model calls, 140 warnings |
| Chunks | **90 / 90 usable (100%)** |
| Chapters | 435 across 39 videos |
| Warning codes | `out-of-range` 130, `non-monotonic` 9, `seam-duplicate` 1 |
| Generic titles | 103 / 435 (23.7%) |
| Re-run | `countMissingDigests` = 0; batch reports **0 generated, 39 fresh, 0 engine calls, 0.1 s** |

**The defect video is fixed.** `community-notes/v2chrch` (3505 cues) is the 2.3 h video whose
third chunk previously produced NOTHING — nine of eleven starts rejected as out-of-range
because the model had reverted to counting from zero. At 8 k / chunk-local it is 7 chunks,
**7/7 usable, 42 chapters, one out-of-range warning**, covering 00:16:59 → 02:12:55 with no
gap larger than the leading one.

The other two 6-chunk videos behave the same: `v2on7b3` 36 chapters 6/6, `v2apmfn` 20
chapters 6/6.

**Two honest caveats:**

- 130 `out-of-range` rejections remain across the channel. The guard is catching them and
  the chunks still yield, so this is degraded output rather than lost output — but it is not
  zero, and it is the metric to watch in the validation run.
- **Coverage of the opening minutes is weak on long videos.** The first chapter lands at
  00:16:59 (`v2chrch`), 00:15:30 (`v2on7b3`) and **00:41:47** (`v2apmfn`) — the early chunks
  yielded little or nothing, which is the mirror image of the original defect. Not
  investigated in this stage. Worth checking whether these channels open with long
  pre-shows, or whether the first chunk is systematically weaker.

Generic-title rate on real data (23.7%) sits between the bake-off's long-tail sample figure
for this config (31.2%) and gemma2's (10%), which is consistent rather than surprising.

---

## Duplicate detection at corpus scale (measured 2026-07-26)

### Why the first attempt failed (the counts here are correct and are the reason blocking exists)

`duplicate-shorts.ts --all-durations` originally died two different ways:

| Heap | Outcome | Elapsed |
| --- | --- | --- |
| default (~4 GB) | `FATAL ERROR: Ineffective mark-compacts near heap limit` | 87 s |
| `--max-old-space-size=24576` | `RangeError: Invalid array length` at the containment `candidates.push` | 34 s |

Counting the pairs the old generator would build, without building them:

| | Count |
| --- | --- |
| Videos scanned | 76,354 |
| Participants (`duration > 0`) | 76,318 |
| Shorts (≤ 180 s) | 6,970 |
| Duration buckets (2 s) | 11,008 |
| Duration-bucket pairs (same + adjacent) | 9,131,916 |
| **Containment pairs** (short × every video ≥ 1.5× its length) | **497,860,972** |
| Total candidate pairs | 506,992,888 |

Two independent defects, not one:

1. **The containment pass was an unblocked cartesian product** — 98.2% of all
   candidates. V8 throws `RangeError` because a fast-mode object array caps well
   below 500 M elements.
2. **Fingerprints were held for the whole corpus at once.** `fingerprintFrom`
   builds a `Set` of 5-word shingles over the entire transcript (~40 k strings
   for a 3.5 h video), and the duration pass alone made `needed` ≈ the corpus.
   That is what killed the 4 GB run before the array was even reached.

### The conclusion that was wrong

The earlier note here said corpus-wide detection "does not complete on this
corpus" and recorded that "as a cost, not worked around". **That was wrong.**
Neither failure is inherent to corpus-wide detection: blocking fixes (1) and
block-at-a-time streaming fixes (2). Both are now implemented, and corpus-wide
detection completes comfortably in minutes on a default heap.

### Corpus-wide runs, measured (same corpus, 76,354 videos)

`detectDuplicateShorts` now iterates blocks — fingerprint a block, evaluate its
pairs, keep the confirmed matches, release — so peak memory is O(largest block),
and no multi-million-element pair array is ever materialised. `--blocking`
selects the nomination strategy.

| | `--blocking title` | `--blocking duration` |
| --- | --- | --- |
| Wall clock | **206 s** | **2,889 s** (48 min) |
| Peak RSS | **2,001 MB** | **2,450 MB** |
| Blocks | 7,551 title groups (of 67,064 distinct titles) | 11,008 buckets of 2 s |
| Oversized blocks skipped | **0** (cap 40) | **0** (cap 2,000) |
| Nominated pairs | 8,352 | 9,131,476 |
| Confirmed by content | 2,717 | **5,708** |
| Rejected by content | 5,250 | 9,125,768 |
| Untestable suspects | 385 | **0** (by design — see below) |
| Videos fingerprinted | 15,479 | 74,943 |
| Clusters written | 2,994 / 6,044 videos (335 `needsReview`) | 2,917 / 5,955 videos (0 `needsReview`) |
| Cluster kinds | 79 exact, 2,580 near, 335 suspect | 108 exact, 2,809 near |
| Alignment | 1,599 of 2,689 within 5 s | 1,818 of 3,028 within 5 s |

The duration run's 9,131,476 nominated pairs land within 0.005% of the 9,131,916
predicted above — the old counting was right, only the conclusion drawn from it
was wrong.

**Duration blocking yields no suspects, and that is deliberate.** A shared runtime
alone was never evidence (it produced enormous false clusters of unrelated
same-length videos), so when a duration-nominated pair cannot be content-tested it
is dropped, not queued for review. Only title blocking produces suspects, because
only *title + near-identical runtime* is a claim worth a human's attention.

Title-run cluster sizes are overwhelmingly pairs: 2,950×2, 39×3, 3×4, 1×6, 1×9.
2,728 cross-platform, 2,891 cross-channel.

### Measured recall: what title blocking actually misses

Comparing the two runs' clusters directly (title's suspects excluded, since they
are not confirmed):

| | Count |
| --- | --- |
| Clusters with identical membership in both | 2,613 |
| Title-only clusters | 46 |
| Duration-only clusters | 304 |
| Videos in title clusters / in duration clusters | 5,351 / 5,955 |
| **Videos found only by duration** (re-titled mirrors) | **672** |
| Videos found only by title (runtime drift past the bucket) | 68 |

So **title blocking has ~89% of duration blocking's video-level recall at 1/14th
the wall clock**, and the 672 it misses are exactly the re-titled mirrors it
structurally cannot see. `--blocking both` exists for when that 11% matters; the
title default is the right routine choice.

The containment sweep is now budget-capped (`MAX_CONTAINMENT_PAIRS`, 5 M) and
reports itself skipped corpus-wide: `6,970 shorts × 76,318 videos ≈ 531,936,460
pairs`. It still runs, unchanged, at shorts scale. Making it scale is the one
piece genuinely deferred — see STATE.md.

### 63% of title matches were rejected at 0.6 — and most of those rejections were wrong

Of 8,352 pairs nominated by an exact normalized title *and* a compatible runtime,
**5,250 were rejected once their transcripts were compared** at the default 0.6
5-gram Jaccard. Only 2,717 held up.

That was read as "the title-level count was right; the inference that they are
duplicates was not." **Measurement has since shown the opposite: the threshold was
wrong, not the inference.** See the next section.

### MEASURED: the 0.6 near threshold was rejecting real cross-platform mirrors

Re-run corpus-wide, title blocking, everything else identical, only `--near`
changed (2026-07-27):

| | `--near 0.6` (default) | `--near 0.35` |
| --- | --- | --- |
| Nominated pairs | 8,352 | 8,352 |
| **Confirmed by content** | 2,717 | **7,329** |
| Rejected by content | 5,250 | **638** |
| Untestable suspects | 385 | 385 |
| Clusters written | 2,994 / 6,044 videos | **7,450 / 15,030 videos** |
| `needsReview` | 335 | 334 |
| **Timing-aligned mirrors** | 1,599 of 2,689 | **3,952 of 7,221** |
| Wall clock | 206 s | 249 s |

The confirmed set grows **+170%** and is a strict superset: **0 videos** present in
the 0.6 clusters are absent from the 0.35 clusters.

**The 4,456 entirely-new clusters were inspected, not just counted**, and they are
real mirrors. Evidence, in descending order of strength:

- **4,423 of 4,456 (99.3%) are cross-platform AND cross-channel.** 3,954 pair a
  channel with its own platform-suffixed sibling (`the-quartering` ↔
  `the-quartering-rumble`); of the 502 that don't, the sampled ones pair a
  creator's alternate channels (`jeremy-hambly` / `quartering-live` /
  `the-quartering`, `HasanAbiVODs` / `HasanAbiVODsbackup`).
- **4,290 of 4,456 have a byte-identical title** across every copy; 4,023 agree on
  runtime within 2 s; 3,572 share an upload date.
- The score histogram is a tight band at **0.45–0.60** (1,995 at 0.55–0.60, 1,481
  at 0.50–0.55, 665 at 0.45–0.50) — i.e. they pile up *just under* the old cutoff,
  which is the signature of a systematic offset, not of noise.
- The **138 riskiest** (score < 0.42) and the **502 non-sibling** clusters were
  sampled across the whole band. Every one examined is the same recording: same
  title, same runtime to the second, same upload date, mirrored platform.

The mechanism is the one the caveat predicted: the two sides of a cross-platform
mirror are transcribed by **different ASR engines**, and a 5-gram Jaccard is
unforgiving of word-level disagreement. Two transcripts of the same audio from
different engines land at **~0.35–0.60**, not ≥ 0.6. The old default was set for
same-engine text and silently failed the cross-platform case, which is precisely
the case duplicate detection exists to catch.

**Consequence for the digest backfill.** The ceiling on shared-digest savings is
not 2,717 pairs. At 0.35 it is **7,329 confirmed pairs, of which 3,952 are
timing-aligned** enough for a shared digest to be placed correctly — **2.5× the
1,599 previously banked**. Against a corpus of 76,318 videos that is ~5.2% of the
sweep avoidable by sharing rather than ~2.1%.

**CHANGED 2026-07-29: `DEFAULT_NEAR_THRESHOLD` now ships at 0.35**, in its own
commit, after bracketing it at four values — see the next section. Note that the
"consequence for the digest backfill" above was **overstated**: the saving is
real in pair count but nearly absent in audio-hours, which is the unit the sweep
is actually priced in. ~5.2% of pairs is ~1.7 sweep days of 80.

Reproduce with:
`pnpm exec tsx bin/duplicate-shorts.ts --all-durations --blocking title --near 0.35`
(back up `transcripts/duplicates.json` first — the run overwrites it).

### Bracketing the near threshold — 4 runs, identical inputs (measured 2026-07-29)

Corpus-wide, `--all-durations --blocking title`, only `--near` varied. 76,354 videos
scanned, 8,352 pairs nominated in every run.

| `--near` | confirmed | rejected | clusters | videos | aligned | needsReview | wall |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 0.6 | 2,736 | 5,404 | 2,846 | 5,746 | 4,273 | 168 | 124 s |
| 0.45 | 7,147 | 993 | 7,110 | 14,344 | 10,747 | 166 | 199 s |
| **0.35** | **7,483** | **657** | **7,434** | **14,997** | **11,217** | 166 | 225 s |
| 0.25 | 7,542 | 598 | 7,493 | 15,115 | 11,297 | 166 | ~230 s |

Every step down is a **strict superset** — 0 videos lost at any step. Returns collapse:
0.6→0.45 admits **4,264** entirely-new clusters, 0.45→0.35 admits **324**, 0.35→0.25 admits
**59**.

The marginal bands were read, not counted:

| band | new clusters | byte-identical title | runtime ±2 s | cross-platform | SAME-channel |
| --- | --- | --- | --- | --- | --- |
| 0.6 → 0.45 | 4,264 | 96.2% | 91.1% | 99.5% | **3** |
| 0.45 → 0.35 | 324 | 97.2% | 83.3% | 96.0% | **2** |
| 0.35 → 0.25 | 59 | 94.9% | 86.4% | 93.2% | **0** |

The riskiest cases in each band were printed individually. In the 0.6→0.45 band they are all
YouTube↔Rumble pairs agreeing on title (modulo whitespace), runtime to the second, and upload
date. The 0.45→0.35 band contains the only two arguable cases in the whole sweep: a
`HasanAbiVODs` pair with the same title but runtimes 9 minutes apart, and an `omnibased` pair
with identical title/duration/date. Neither is a clear false positive; the first would be
refused by the alignment gate regardless.

**Adopted: 0.35.** The recall knee is at **0.45** — the value to take if a more conservative
assertion is ever wanted.

### The digest sweep, priced in CHUNKS (measured 2026-07-29)

**A chunk — one model call — is the unit of cost. Seconds-per-audio-hour is NOT a
stable unit here and must not be used for any projection.** Chunk density varies
**fourfold** across the corpus, so an s/audio-hour figure measured on one length
mix does not transfer to another. Three separate cost measurements looked
irreconcilable (27 / 90 / 151 s/audio-hour) purely because of this; re-priced per
chunk they agree to within ~2%.

#### The chunk census

Computed free from `statsByPath.cueCount` — present on **all 73,367** transcribed
videos, so it needed no GPU time and no transcript reads. (Corrected 2026-09-28: "all" was
all the CACHE knew of. Until stats schema 6 a video transcribed after its stat was first
cached kept `cueCount: null` — about 2,500 of them on 2026-09-28; see "The stats cache key"
at the end of this file.) At the shipped config
(`maxCues` 600, overlap 40, step 560):

```
chunks(c) = c === 0 ? 0 : c <= 600 ? 1 : 1 + ceil((c - 600) / 560)
```

| band | videos | audio-h | % of audio | chunks | **chunks/audio-h** | % of chunks |
| --- | --- | --- | --- | --- | --- | --- |
| < 15 min | 41,960 | 6,203 | 8.0% | 41,960 | **6.76** | 22.0% |
| 15–60 min | 14,036 | 6,631 | 8.6% | 22,446 | 3.39 | 11.7% |
| 1–2 h | 5,847 | 8,480 | 11.0% | 22,353 | 2.64 | 11.7% |
| 2–4 h | 5,486 | 15,832 | 20.5% | 33,106 | 2.09 | 17.3% |
| 4–8 h | 4,504 | 25,304 | 32.7% | 46,363 | 1.83 | 24.3% |
| > 8 h | 1,534 | 14,850 | 19.2% | 24,888 | **1.68** | 13.0% |
| **total** | **73,367** | **77,298** | | **191,116** | **2.47** | |

**4 h+ videos are 52% of the AUDIO but only 37% of the WORK; sub-hour videos are
16% of audio and 34% of chunks.** Any reasoning that prices this sweep in
audio-hours gets that backwards. Pinned as a regression test in
`controller/digestPlan.test.ts` (it re-derives 191,116 from LMDB and fails if the
plan and the chunker ever drift).

#### Re-pricing every measurement taken so far

| per-chunk cost | source | × 191,116 | previously claimed |
| --- | --- | --- | --- |
| 11.2 s | round 2, idle box, **engine** time | **24.8 d** | 24.2 ✓ |
| 24.7 s | 102-video run, contended, **wall** time | **54.6 d** | 81 ✗ |
| 60.6 s | round 2 gemma2, idle, engine | **134 d** | 132 ✓ |

**The honest range is ~25 days idle to ~55 contended — not 81.** The audio-hour
model reproduces none of the three; the chunk model reproduces all three.

#### The plan output itself

`common/bin/digest-plan.ts --no-freshness`. Total digestable corpus: **77,298
audio-hours over 73,367 videos** (2,987 have no transcript) = **191,116 chunks**,
of which **185,483 chunks / 75,638 audio-hours** remain to generate at `--near`
0.35 → **53.5 sweep days**. Sharing avoids 5,633 chunks (1.6 days).

Per-channel density is now reported, because it is what explains a changing rate
mid-sweep — the queue runs heaviest-first and the heaviest channels are the
CHEAPEST per audio-hour: `HasanAbiVODs3` 1.71 c/h against `chibi-reviews` 6.38.

The audio-hour table below is kept as measured, but its `days` column was computed
at 90 s/audio-hour and is **retracted**.

| `--near` | canonical | mirror-aligned (free) | mirror-unaligned | unclustered | **to generate** | **days** |
| --- | --- | --- | --- | --- | --- | --- |
| 0.6 | 853 h | 494 h | 344 h | 75,607 h | 76,804 h | 80.0 |
| 0.45 | 3,472 h | 1,448 h | 1,866 h | 70,513 h | 75,851 h | 79.0 |
| 0.35 | 4,070 h | 1,661 h | 2,206 h | 69,361 h | 75,638 h | 78.8 |
| 0.25 | 4,137 h | 1,683 h | 2,242 h | 69,236 h | 75,616 h | 78.8 |

**Duplicate sharing is not a meaningful cost lever, and `digestSharing.ts`'s "~11% of the
sweep" header is wrong.** Cluster members are 19% of the corpus by video count but **4.3% of
its audio-hours**: mirrors skew SHORT while the sweep is dominated by unclustered long-form
VODs. Loosening the threshold as far as it goes moves the sweep from 80.0 to 78.8 days.

Note the `mirror-unaligned` column: only ~55% of mirrors pass the alignment gate, so counting
all mirrors as free would overstate the saving by nearly half. The plan splits them.

Heaviest channels (the sweep's work-queue order), audio-hours to generate at 0.35:

| channel | h | days |
| --- | --- | --- |
| HasanAbiVODs3 | 8,331 | 8.7 |
| omnibased | 7,783 | 8.1 |
| HasanAbiVODs | 5,380 | 5.6 |
| rekietalaw | 4,993 | 5.2 |
| destiny | 4,020 | 4.2 |
| shondo-vods | 3,332 | 3.5 |

`HasanAbiVODs3` alone outweighs every duplicate mirror in the corpus combined.

### The id-vs-directory mismatch (measured 2026-07-29)

A slug is `${channelSlug}/${id}` and an id is **not** the on-disk directory name for
**11,175 of 77,106 indexed videos (14.5%)**, concentrated almost entirely in Rumble
re-uploads:

| channel | dir !== id |
| --- | --- |
| the-quartering-rumble | 7,870 (of 7,870 — every video) |
| leaflit-rumble | 838 |
| midwestly | 758 |
| rekietalaw-rumble | 641 |
| omnimirror | 522 |
| cornbreadman | 337 |

Verified directly: for all 7,870 `the-quartering-rumble` entries, `stat.slug ===
channel/id` and `stat.slug !== channel/dir`. `digestBatch` looked the cluster plan up by
DIRECTORY, so every one of those lookups missed silently and the mirror regenerated. See the
`videoDir` field on `DuplicateVideoRef`.

### What this unblocks

Corpus-wide detection is no longer off. `buildDigestClusterPlan` reads
`duplicates.json` and returns an empty plan when it is absent, so the digest batch
stays correct either way — it just re-generates mirrors instead of sharing them.

---

## Digest validation run — 102 videos, real corpus (measured 2026-07-27)

The first digest run at corpus scale rather than on a hand-picked bake-off
sample. Shipped defaults (`qwen2.5:7b` @ 8192, chunk-local, 600 cues,
`PROMPT_VERSION` 2), production build, driven through the channel page's
**Digest channel** button. `community-notes` (39 videos, 33.5 audio-h — the
pilot channel, every digest invalidated by the version bump) plus `friendofrc`
(63 videos, 8.7 audio-h, never digested). Score with:

```
cd common && pnpm exec tsx bin/digest-validate.ts community-notes friendofrc
```

**102 digests, 42.2 audio-hours, 153 chunks, 622 chapters, 0 failures.**

### Quality: better than projected on everything except coverage gap

| Metric | round 2 projection | **validation (102 videos)** | |
| --- | --- | --- | --- |
| Zero-yield chunks | 11.8% (2 of 17) | **0.0% (0 of 153)** | far better |
| Chapters/hour | 13.37 | **14.74** | better |
| Rejection rate | 19.1% | **18.4%** | matches |
| Generic titles | 31.2% | **27.0%** | better |
| Duplicate titles | 3.2% | **0.3%** | far better |
| Worst coverage gap | 00:24:13 | **01:09:48** | **2.9× worse** |

**Zero-yield went to actually zero.** Not one of 153 chunks came back empty.
Round 2's 11.8% came from 2 chunks in a 17-chunk sample; at 9× the chunks the
rate is 0. The chunk-local + 8192 pairing does not produce dead chunks.

**Rejection rate landed within 0.7 points of a 2-video projection**, which is
the strongest evidence available that the bake-off sample was representative on
quality.

**Rejections are now almost entirely one guard:**

| Guard | Count | round 2 |
| --- | --- | --- |
| `out-of-range` | **130** (93%) | 13 |
| `non-monotonic` | 9 | 2 |
| `seam-duplicate` | 1 | 0 |
| `language-drift` | **0** | 7 |

Language drift disappeared across 42 audio-hours (round 2 saw 7 in 7). The range
clamp is doing effectively all of the work, which means it is the guard whose
removal would silently corrupt the corpus.

**The worst coverage gap is the one metric that got worse at scale, and the
per-video panel explains it.** `community-notes/v2fkbw7` (1:58:42, 20 chapters,
gap 1:09:48) recorded **13 `out-of-range` rejections** — the model proposed
chapters for that hour and every one was thrown away by the clamp. So the gap is
not "the model ignored an hour of video", it is "the model's output for that hour
was unusable". Those are different problems with different fixes, and the
distinction is only visible because the artifact records rejections instead of
dropping them. **The median gap is 00:05:19**, so this is a tail, not the norm —
report the median alongside the max.

### Throughput: 3.3× worse than projected — **and ~a third of that was the unit**

**CORRECTED 2026-07-29.** The `~81 days` this section claimed is wrong on this
run's own data. Re-priced against the 153 chunks the run's 102 sidecars actually
record in `provenance.chunks`, it says **54.6 days**:

| | audio-h | wall | chunks | chunks/audio-h | s per audio-h | **s per chunk** |
| --- | --- | --- | --- | --- | --- | --- |
| round 2 (long videos, idle box) | 6.96 | — | — | 2.44 | 27 | **11.2** |
| `community-notes` (avg 51 min/video) | 33.5 | 42.1 min | 90 | 2.69 | 75 | **28.07** |
| `friendofrc` (avg 8 min/video) | 8.7 | 20.8 min | 63 | 7.24 | 143 | **19.81** |
| **combined** | **42.2** | **62.9 min** | **153** | **3.63** | **89.4** | **24.67** |

The 3.33× factors almost exactly: **1.49× sample length mix (3.63 vs 2.44
chunks/audio-h) × 2.20× per-chunk cost = 3.27×**, against 3.33× observed.

**The first cause as previously written was an artifact of the unit, and inverts.**
It said "short videos cost ~2× per audio-hour (143 vs 75 s)". True, and irrelevant:
**per chunk the short-video channel is 29% CHEAPER** (19.81 vs 28.07 s), because a
short video's single chunk is a *partial* chunk — fewer cues to prefill and fewer
chapters to decode. Short videos are not expensive work; they are expensive *per
hour of audio*, which is not a thing the GPU charges for.

So only ONE compounding cause survives, plus a third of the gap being sampling:

1. ~~Short videos cost ~2× per audio-hour~~ — **retracted as a unit artifact.**
   What is true: round 2 sampled only the `long` bucket, whose 2.44 chunks/audio-h
   is well below the corpus's 2.47… and *far* below the validation sample's 3.63.
   The sample mix, not the videos, contributed 1.49× of the 3.33×.
2. **The box was not idle.** `auto-download` and `auto-transcribe` ran throughout
   (load average 10–14, the transcription engine contending for the same GPU). This
   is representative of production but not comparable to the bake-off's conditions.
   This remains the one real cause — but its size is a **hypothesis, not a
   measurement**, because the 2.20× per-chunk residual compares this run's **wall**
   clock against round 2's **engine** time. Those are different quantities, and the
   residual therefore also contains model-load, prefill, and the yield gate's own
   3 s-poll idling. `digestApps.ts` now records load/prefill/decode per call
   precisely so the next measurement can separate them.

**Do not plan against ~80–90 days.** Plan against **~55 days on a shared box and
~25 idle**, and treat closing that gap as the open question. Two things follow that
were not visible before: the yield shipped with a CPU-worker bug (it stopped the
digest lane for `device: "cpu"` transcription competing for zero shaders — fixed,
`digest.yieldToCpuWorkers`), and `gemma2:9b` **offloads 1,029 MB of its 6.43 GB
footprint to CPU** at 8192 ctx on this 8 GB card while `qwen2.5:7b` (5.12 GB) is
fully resident — so gemma2's 134 re-priced days are partly a property of the card,
not the model. Verified via `/api/ps` (`size_vram` < `size`).

### Built, specified, and never run once — a recurring defect class

Four cases found on 2026-07-29, all the same shape: the code exists, reads
correctly, has a settings surface or a caller signature, and **had never executed**.
Worth naming as a class, because a code review cannot see it and every test passed.

| Case | Evidence it never ran |
| --- | --- |
| `updateDuplicateOverride` | zero callers |
| `shareClusterFromCanonical` | zero callers |
| `setProgress` (one path) | referenced nowhere |
| **Digest TAGS** | **0 of 109 sidecars had a tags section** |

The tags case was the largest: `parseTags`, a tags JSON schema, a `sections` branch
in `digestVideo` and a per-section checkbox in `SettingsForm.tsx` had all shipped,
`digest-validate.ts` had no tag metrics, `editor/e2e/digest.spec.ts` had no tags
coverage, and neither bake-off round scored them. It works — 11 videos, 0 warnings,
`parseTags` accepted every live output — and it is now generated, scored and
covered by e2e. See the tags section below.

The pattern to take from it: **a capability with no metric and no e2e is
indistinguishable from a broken one.** The fix is not more review; it is that
anything with a settings surface gets one live run and one assertion.

### Notes for any future bake-off round (not gates now)

- **`BUCKET_BOUNDS` has holes** (`plans/tools/digest-bakeoff.ts:70-75`).
  `bucketFor()` returns `null` for any duration in a gap, so those videos are
  silently unsamplable: **30–45 min**, **90 min – 3 h**, and **4.5 – 6 h** (`long`
  caps at 4.5 h, `verylong` starts at 6 h). The gaps look deliberate — they keep
  the strata well separated — but nothing says so and nothing reports how many
  videos fall in them. The 4.5–6 h hole matters most, since that band is dense in
  this corpus.
- **`sample.json` does not record the strata that produced it.** So a round cannot
  prove what mix it measured, which is exactly the confound that made round 2's
  27 s/audio-hour non-transferable. Any future round should record
  chunks/audio-hour for its sample beside the per-bucket counts.

### Two things the run confirmed about the plumbing

- **The counters agree now.** Before the sweep, `noDigest` reported **39** and
  `countMissingDigests` independently reported **39** for `community-notes` — the
  version bump correctly invalidating every pilot digest. Under the old bucket the
  Digest stage read "All digested" on the same corpus. Snapshot regeneration with
  the added freshness target takes **0.1 s** for a 39-video channel, so the hot
  path did not get meaningfully slower.
- **Progress bars cannot move during a REGENERATION.** `setProgress` uses
  `initial: stat.digestCount` and `target: initial + missing`, but `digestCount`
  counts digests that *exist* — and a regeneration rewrites in place, so the count
  never grows and `pct` sits at 0 for the whole job (observed:
  `{initial:39,current:39,target:72,pct:0}`). Cosmetic, but it makes a long
  re-sweep look wedged. Fixing it means counting digests *at the current identity*
  rather than digests-on-disk.

## Editor surfaces

| Surface | File | Note |
| --- | --- | --- |
| System paths table | `editor/app/settings/page.tsx:17-28` | Hand-curated tuple list, **not** `Object.entries(paths)`. The blurb at `:57-64` is already stale (missing parakeet/gallery-dl). |
| Job kinds | `common/jobs/jobKinds.ts:21-40, 44-255` | ~30 entries. **No entry sets `defaultTier`** — declared but unused so far. |
| Replay handlers | `editor/app/jobs/jobReplayRegistry.ts:75-236` | Bucket kinds re-derive ids from the live snapshot (`:50-57`), never a frozen list. |
| Snapshot buckets | `common/controller/channelSnapshot.ts:57-143` | 21 buckets, all `string[]` of video ids. Readers default `?.length ?? 0`. `undownloadedIds` is deliberately **outside** `buckets` (`:144`). |
| Channel-work sections | `editor/app/components/channelWork/sections.tsx` | `SectionConfig` + `channelWorkSections()` + `sectionsFor(op)`; rendered by `ChannelWorkTable.tsx` (a SERVER component — `primaryAction` is a function). Eight sections: three on `/operations/download`, two on `/operations/transcription`, one on `/operations/digest`, two (`operation: null`) on `/cleanup`. Counters live in `editor/app/lib/actionable/loadActionable.ts`; the review half is `editor/app/review/lib/loadReview.ts`. Unit-tested in `sections.test.ts`. |
| Widget sync payload | `common/views/widgetSync.ts:22` (`WidgetSyncPayload`) | Comment at `:18` states it deliberately stays "a handful of scalars". `buildWidgetSyncPayload(inputs)` (`:174`) is also used for SSR seeding. Served as view `widgetSync`; `/api/widget/sync` is a rewrite (2026-09-23; the route file is gone). |
| Pipeline band | `editor/app/components/dashboard/PipelineBand.tsx:63-114` | Pure props, no fetching. `<Instrument dotClass=…>` encodes state color. |
| Operations board | `editor/app/operations/page.tsx` | `/operations`. Rail + sync row, SSR-seeded, polls `/api/view/autoQueueStatus` every 3 s (`useOperationsStatus.ts:26`; the old path is a rewrite since 2026-09-23). `data-board="operations"` carries `data-hydrated`. (The arbiter bar was here until slice 1.3.) |
| One operation | `editor/app/operations/[id]/page.tsx` | `/operations/<id>`, **routed off `operationCatalog()`** — an unknown id is `notFound()`, a new registry entry needs no route work. Every operation with a lane (`pauseLaneFor`) renders `RunnerOperationView` inside `<section data-lane="transcription"\|"download"\|"digest"\|"backfill">`; since slice 1.3 that is the only lane section on the page. |
| Retired editor routes | `editor/next.config.ts` `redirects()` | `/auto-queue` → `/operations` and `/actionable` → `/operations`, both **temporary (307)**, not permanent — a 308 on a self-hosted admin surface is a support call with no remedy. Query strings pass through. The API paths `/api/auto-queue/{status,control}` and `/api/widget/actionable` did **not** move — since 2026-09-23 `/api/auto-queue/status` and `/api/widget/actionable` are `rewrites()` onto `/api/view/<name>` (`:139-148`). **API paths are rewritten, never redirected.** |

---

## Viewer surfaces

`ModalMode` — `common/components/urlState.ts:13`, currently
`"transcript" | "chat" | "post"`. Parsed at `:63-65` (unrecognized → `"transcript"`),
written at `:126-130`. Referenced in **only three files**: `urlState.ts`,
`PlayerProvider.tsx`, `TranscriptModal.tsx`.

Lazy chat fetch effect — `PlayerProvider.tsx:590-640`, deps `[urlSlug, modalMode]`, with a
ref-based in-flight guard and a comment at `:585-589` explaining why reducer state in the
dep array drops results. It snaps back via `writeUrlParams({ vm: "transcript" })` on missing.
`seekTo` at `:522-530`.

**Styling:** `TranscriptModal.tsx` and `PlayerProvider.tsx` are **not** on semantic theme
tokens. Verified hard-coded: `bg-black/70` (`:199`), `bg-zinc-900/80 ring-white/10` (`:210`),
`text-white` (`:331`), `text-zinc-300` (`:336`), `border-zinc-700 bg-zinc-900` (`:357`),
`bg-blue-950/50` (`:419`). By contrast `export/app/ask/citations.tsx` uses semantic tokens
throughout — the two surfaces are on different systems. Do not mix them.

`export/app/lib/askProvider.ts`: `Provider` union at `:19`, `PROVIDERS` at `:34-59`,
`askStream` switch at `:128-137`, `askOpenAI` at `:336-397`. Provider settings live at
`export/app/ask/ProviderSettings.tsx` (**not** `app/components/`); its `Props` is a 21-field
flat prop bag (`:13-36`).

Two independent search index paths: `common/components/searchIndex.worker.ts` (FlexSearch,
client) and `mcp/src/search.ts` (server). MCP has 11 tools (`mcp/src/server.ts:132`) and a
14-member `ShardSource` interface (`mcp/src/source.ts:119`) implemented three times —
`LocalSource` (`:185`), `RemoteSource` (`:353`), `HubSource` (`:477`).

---

## E2E environment

**`build:hub` clobbers the export e2e fixture in the same worktree (hit 2026-09-12).**
`export`'s `build:hub` runs `compose:hub`, which overwrites `export/public/corpus.json` and
`sw.js` and drops the hub files beside them. An export e2e run after it in the same
worktree then runs against a hub, not a site. Run the export suites first, or restore the
site fixture (`corpus.json` from the duplicates-page worktree, remove the hub files, recopy
`site-sw.js`) before them. All of those paths are gitignored, so nothing shows in `git status`.
**Since release 10 L1 (2026-09-26)** the compose writes land in the worktree's own files, never
through its `export/public` links (`common/bin/_publicFile.ts`), so the restore is the per-path
seed again (`plans/tools/implementer-rules.md`); the export config re-copies `sw.js` itself.

- `editor/playwright.config.ts` — editor on `PORT ?? 3011`, export on `EXPORT_PORT ?? 3010`.
  `E2E_MODE=start` → `pnpm start:test`, otherwise `pnpm dev:test` (`:10-11`).
  `fullyParallel: false`, `workers: 1`, `timeout: 30_000`.
  **AMENDED 2026-10-10 (e2e speed S1):** `start` is the DEFAULT (`E2E_MODE=dev` for `next dev`).
  Before the servers start, `scripts/e2e-stamp.mjs ensure editor` checks the build's stamp
  (`editor/.next/e2e/e2e-stamp.json`) and rebuilds through the heavy slot when the tree moved;
  the test server serves `.next/e2e` (`E2E_NEXT_DIST_DIR`), never `.next`. `CI` keeps `.next`
  and skips the stamp (the sharded image builds its own). umtool likewise (`.next-e2e-start`);
  export and homepage stay `next dev`.
- `editor/e2e/helpers.ts` — `resetData` (`:32`), `writeSettings` (`:49`), `readJson` (`:90`).
- Fake binaries live in `editor/e2e/fixtures/bin/`. The **`SLOWOP` sentinel** (checked
  case-insensitively against cwd or video id) makes an instant fake emit paced progress —
  three independent copies at `fake-whisper.mjs:29-40`, `fake-chough.mjs:25`,
  `fake-ytdlp.mjs:173-183`.
- Binary env vars are wired in `editor/package.json`'s `dev:test` **and** `start:test`
  scripts — a single line duplicated verbatim, differing only in `next dev` vs `next start`.
  **Adding one env var means editing both.**
  **AMENDED 2026-09-28 (release 11 O6-B):** that holds for the paths and binaries. A TEST-ONLY
  variable no longer goes there: it is `E2E_`-prefixed and set in `editor/playwright.config.ts`'
  `E2E_SERVER_ENV` (`:37-44`, the webServer's `env`) — see "Release 11 — slices O1–O6".
- Route-stubbing scaffold: `editor/e2e/export-player-platform-cache.spec.ts:39-111`.

### Known-failing on base — not regressions

**Re-verified 2026-07-26** by stashing all working changes and re-running the suspect specs
against `8c041fd`. Full suite in default dev mode: **21 failed / 363 passed of 384**, and
every one of the 21 is accounted for below. Do not chase these.

| Spec | Count | Evidence |
| --- | --- | --- |
| `actionable.spec` — 2 "queues a job" + the "Needs attention" dashboard card | 3 | fails on base |
| `bulk-actions.spec` raw-job-kind tests | 3 | fails on base (known) |
| `channels-actions.spec:42` | 1 | fails on base (known) |
| `cleanup-actionable.spec` inline "Clean audio" | 1 | fails on base |
| `deploy-page.spec` (all three) | 3 | fails on base — `getByRole('button', {name:'Build & deploy'})` also matches "Build & deploy all sites"; `getByLabel('Deploy after build')` matches 2 checkboxes |
| `new-channel-onboarding.spec` (all five) | 5 | fails on base — `getByLabel('URL')` resolves to 4 elements (a `<label>` wrapping several controls) |
| `settings.spec` social-links | 1 | fails on base (known placeholder collision) |
| `site-scope.spec` dashboard stats | 1 | fails on base |
| `cut-release.spec` (both) | 2 | expected with a dirty working tree — the spec rewrites the real `editor/CHANGELOG.md` and makes a git commit |
| `scheduler.spec:28` — queues due channels | 1 | fails on base (verified 2026-07-29 against `bbaa887`) |
| `sync-break-on-existing-tree.spec` | 1 | **passes in isolation** — order-dependent flake, not a base failure |
| `undownloaded.spec:53` | 1 | **passes in isolation** (all 4 in 22.6 s) — the CPU-contention flake already recorded below, seen again 2026-07-27 |

**Re-verified again 2026-07-27** after Stage B2: **369 passed / 21 failed of 390** (the suite
grew by the 5 new digest specs, all passing). The 21 are the same set, with two differences
worth noting: `cut-release` failed **once** rather than twice, and `undownloaded.spec:53`
appeared in place of the second `cut-release` — it passes in isolation. Export suite:
**141/141**.

**Re-verified again 2026-07-29** after Phases 2/3: **366 passed / 24 failed of 390**. The 24
are the 22 in the table above (`cut-release` failed **both** this time — the working tree was
dirty, which is exactly when it does) plus **two more, each verified passing in isolation**:

| Spec | Isolation result |
| --- | --- |
| `auto-queue.spec:209` — strict priority drains the high-priority channel first | passes (13/13 in 1.8 min) |
| `scheduler.spec:239` — schedule page edits the global controls | passes (all 8 scheduler tests) |

Both are the **CPU-contention flake** already recorded for `undownloaded.spec:53` and
`sync-break-on-existing`: this run shared the box with an unrelated containerized playwright
suite at load ~10. Add them to the "passes in isolation" set rather than the base-failure
set. Export suite the same day: **150/150** (141 + 9 new digest specs). `digest.spec.ts`
(12) and the `settings.spec` digest tests all passed.

The `deploy-page` (×3), `new-channel-onboarding` (×5) and `site-scope` failures — **9 specs**
— are all *strict-mode locator violations* ("resolved to N elements"): specs written against
an earlier form structure that has since gained sibling controls with overlapping accessible
names. They are **a real backlog item, not a regression**, and cheap to fix independently of
any feature work: each needs a tightened locator (`exact: true`, a `getByRole` scoped to the
form, or a `data-testid`), not a behaviour change. Fixing them is worth doing precisely
because 9 permanently-red specs train everyone to ignore the suite's exit code.

> **Superseded 2026-07-30 — every red above is now fixed.** See
> "[The 22 reds: what they actually were](#the-22-reds-what-they-actually-were)" below. Two
> corrections to the paragraph above, both established by running the specs rather than
> reading them: `deploy-page:8` and `site-scope:50` were **not** strict-mode violations (they
> failed with "element(s) not found" against renamed/deleted UI), so the count of true
> collisions was 7, not 9.

`widget.spec`'s "no buttons" assertion fails under `dev:test` because `next dev` injects a
Dev Tools button; it passes under `E2E_MODE=start`. (It passed in this run.)

The `digest.spec.ts` tests all pass — now **12**, the original 9 plus three for the per-video
review panel (renders provenance + warnings, flips to stale after an identity change,
corrections land in the overrides sidecar with the machine file untouched). `settings.spec`
gains two more that also pass: the Digest fieldset round-trips, and an unrelated save does
not reset `timestampMode`/`promptVariant`.

Run `pnpm e2e` in **default dev mode** — `E2E_MODE=start` serves a stale build. Kill stale
dev servers by port between runs.
**AMENDED 2026-10-10 (e2e speed S1):** no longer true — start mode is the default and its build
is stamped; a stale build is rebuilt before the run (see the playwright.config entry above).

### The 22 reds: what they actually were

**Fixed 2026-07-30.** Every one of the permanently-red specs above is now green. The headline:
they were **almost entirely assertion drift, not locator collisions** — the suite was asserting
against UI text and job kinds that the product had since renamed, and each red was diagnosed by
*running* it, not by reading it.

| Was | Actual cause | Fix |
| --- | --- | --- |
| `new-channel-onboarding` ×5 | Real collision. `getByLabel` matches by **substring**, and three other controls wrap descriptions ending "Requires a URL." inside their `<label>`, putting "URL" in their accessible names → 4 elements | `getByLabel("URL", { exact: true })` |
| `deploy-page:29,79` | Real collisions: `name: "Build & deploy"` also matches "Build & deploy all sites" (getByRole's name is a substring match); two identically-labelled "Deploy after build" checkboxes in one `<section>` | `exact: true`; `role="group" aria-label="Build specific sites"` on `BuildSitesPanel` to scope the twin |
| `deploy-page:8` | **Not a collision** — "element(s) not found". `"Build multiple sites"` exists nowhere in the repo; the heading is "Build all sites" | assert the real heading |
| `site-scope:50` | **Not a collision** — the cockpit redesign (`c63f5cb`) deleted the `role="group"` stat tiles entirely | assert the scoped channel-row count |
| `actionable:162,181`, `cleanup-actionable:78`, `channels-actions:42`, `bulk-actions:40,64,88`, `sync-break-on-existing:4` | **Job-kind label drift.** `/jobs` renders `jobKindLabel(kind)`, so asserting the raw kind silently stops matching once a kind gains a label: `whisper-all`→"Transcribe all", `download-missing`→"Download missing", `clean-audio-transcribed`→"Clean audio", `whisper-bucket-downloaded-no-transcript`→"Transcribe downloaded audio", `retry-bucket`→"Retry", `sync`→"Sync" | `data-kind` on the `<tr>` + `jobRowByKind()` in `e2e/helpers.ts` |
| `actionable:200` | The card was renamed "Needs attention" → "Needs work" (`c63f5cb`) | assert the real label |
| `settings:34` | Real collision: `getByPlaceholder(/https:\/\//)` also matched the archive-overflow field | exact placeholder `"https://…"` |
| `cut-release` ×2 | The spec rewrote the **tracked** `editor/CHANGELOG.md` and the action made a **real git commit** | `EDITOR_CHANGELOG_FILE` → gitignored `editor/test-changelog.md`; spec unchecks "Commit changelog" |

Three things that are worth remembering beyond the individual fixes:

- **`sync-break-on-existing` was never an order-dependent flake.** It asserts
  `toContainText("sync")` while the row renders the label `"Sync"` — a case-sensitive miss that
  fails deterministically. The "passes in isolation" note above was wrong.
- **The "queues a job" reds were never the hydration bug.** Each of those tests first asserts an
  inline job pill that only renders once a jobId exists, and that assertion passes — the POST
  demonstrably happens. The natural experiment is inside `channels-actions.spec` itself: its
  `check-availability` test passes *because that kind has no entry in `JOB_KINDS`*, so
  `jobKindLabel` falls back to the raw string.
- **One test was passing vacuously.** `actionable`'s "hides the Needs attention card" asserted
  `toHaveCount(0)` on a label nothing carries — it would have passed no matter what the product
  did. Renaming the label is what exposed it.

### The two e2e routes, and what their numbers mean

| Route | Command | Mode | Retries | Result | Wall |
| --- | --- | --- | --- | --- | --- |
| Serial | `pnpm e2e` | `next dev` | 0 | **390 / 392** (×2 runs) | 23.8 min (1428 s); 29.7 min under heavier load |
| Sharded | `pnpm e2e:sharded --shards 4` | `next start`, 4 containers | 0 (default) | **389–391 / 392** (×4 runs) | 7.1 min (424 s) best, 11.1 min (668 s) under load; **~2.1–3.4×** |

Before this pass the serial suite was **370 / 392**. Every one of the 22 named reds is fixed.
The residual is a **rotating** 1–3 test tail whose membership changes every run — see below;
it is contention, not a fixed set, and the two members that *did* repeat both turned out to be
real test bugs and are now fixed.

The sharded route's failure was `deploy-page:64`'s build-mode toggle, and it is worth writing
down because the obvious diagnosis was wrong. It looks like the **pre-hydration lost click**
this repo has hit repeatedly, but it is not: wrapping the click in a 15 s `toPass` retry did
not fix it, and the failure then moved to the *reload* assertion, which is the tell.

The real cause is an **optimistic write raced by a reload**. `BuildModeToggle` calls
`setMode(next)` — flipping `aria-pressed` immediately — and only *then* runs
`setBuildModeAction` inside `startTransition`. So every assertion on the toggle's own state
passes before `settings.json` has been written, and the test's `page.goto()` reload can read
the pre-click settings. A fast host wins that race; a loaded container loses it. The spec now
polls `test-settings.json` for `buildPipeline.mode === "docker"` before reloading.
*(Amended 2026-09-28, O6c: the toggle and `buildPipeline.mode` are gone, and so is that test; the
lesson below stands.)*

**The general lesson: an optimistic control proves nothing about persistence.** Assert the
persisted artifact, not the widget, before reloading — and treat "passes serially, fails
sharded" as a race indicator rather than a mode difference.

`actionable:114` ("'Update all reports' queues a refresh-report job per channel") had the same
signature and the same moral. `refresh-report` is the **one** kind `/jobs` hides by default
(`DEFAULT_HIDDEN_KINDS` in `app/jobs/jobsFilterStorage.ts`), and `JobsTable` renders every job
while its filter state is still null (`if (!filters) return jobs`), dropping it the moment
localStorage loads. So the test was asserting the visibility of a row the product deliberately
hides, and **passing only because it beat its own hydration** — a race won under `next dev` and
lost under `next start`. It now un-hides the kind via its filter chip first (the chip is always
rendered: `kinds` is derived from all jobs, not the visible ones).

Two of the specs examined in this pass were therefore green for reasons unrelated to what they
claimed to test. **A green suite is evidence only if the assertions can fail.**

### ⚠️ `editor/CHANGELOG.md` was destroyed by the cut-release spec and committed

Not a hypothetical — it already happened, and it is still the state of `main`. The tracked
`editor/CHANGELOG.md` at HEAD is **111 bytes of the spec's own fixture**:

```
# Changelog

## [Unreleased]
- test bullet for cut-release spec

## [9.9.9] - 2024-01-01
- old released bullet
```

The last good version is **`8a87c60`** (a full, detailed changelog). The very next commit to
touch the file, **`691057b`** ("Persist the sweep's SCOPE, not just the fact that one is
armed"), committed the fixture over it — almost certainly because a `cut-release.spec` run had
left it in the working tree and the release entry that commit meant to add went in on top of
fixture content. Everything from `8a87c60` backwards is recoverable:

```bash
git show 8a87c60:editor/CHANGELOG.md > editor/CHANGELOG.md
```

(The entry `691057b` intended to write was never captured and is not recoverable.) This is
**not** restored here — it is a content decision for the maintainer. The spec can no longer do
this: it writes to a gitignored `editor/test-changelog.md` and no longer commits.

Both measured 2026-07-30. **Neither is a clean-box number**: an unrelated project
(`content-engine`) was running its own Playwright suite concurrently at load ~15–23. A second
serial run under heavier load took **29.7 min** for the same 390/2 — so treat these as an
envelope, not a constant.

**The residual failures are a rotating contention tail, not a fixed set.** Across six full runs
the failing membership was different almost every time — `actionable:181` + `pipeline:106`;
`do-not-clean:87` + `shard:303`; `deploy-page:64`; `actionable:114` +
`audio-check-scenarios:198` + `deploy-page:64`; `actionable:114`; `channels:10` +
`audio-check-scenarios:198` + `do-not-clean:87`. **A red here does not mean a regression:
re-run the spec in isolation before believing it.**

Two things came out of that tail worth keeping:

- The first pair were both `ENOTEMPTY: directory not empty` from `resetData()`'s recursive `rm`
  racing a still-running job from the *previous* spec writing back into the tree. Now mitigated
  with `fs.rm`'s native `maxRetries`/`retryDelay` — Node retries exactly that errno set.
- **The ones that repeat are worth chasing; the ones that rotate are not.** `deploy-page:64` and
  `actionable:114` each failed twice in the same route and both turned out to be genuine test
  bugs (below), while the rotating members are timing under external load.

All of this was measured while an unrelated project was running its own Playwright suite on the
same box at load 15–27. Check `/proc/loadavg` and `docker ps` before trusting any number here.

**Mode-dependent specs — do not compare across routes without accounting for these:**

- `widget.spec` "no buttons": **red under `dev:test`** (next dev injects a Dev Tools button),
  **green under `E2E_MODE=start`** — so it is green in the sharded route and red in the serial
  one. This is the one known case where the two routes legitimately disagree.

**The sharded route was completely broken before 2026-07-30** — every shard died with
"Timed out waiting 120000ms from config.webServer" because the export dev server 500s on a
missing `export/public/summaries/manifest.json`, a generated artifact `.dockerignore`
deliberately excludes. Host runs only worked because that file happens to exist in the working
copy. `Dockerfile.test` now seeds an empty-site manifest. The README's old "2.5× on 4 shards"
table described a route that could not start.

---

## Dependencies present / absent

Present: `execa`, `lmdb`, `flexsearch`, `p-limit`, `fs-extra`, `@tanstack/react-query`,
`@tanstack/react-virtual`, `markdown-to-jsx`, `tsx`.

**Absent — do not assume:** any YAML parser, `gray-matter`, `zod`, `vitest`, `jest`.
A frontmatter parser for Phase 1.5 must be hand-rolled (three scalar/list field types).

---

**Re-verified 2026-07-29** after the backfill-readiness work: **368 passed / 22
failed of 390** — one better than the previous run. All 22 are in the table
above. Two were isolated rather than assumed:

| Spec | Isolation result |
| --- | --- |
| `duplicate-shorts.spec:328` | **was a real regression, now fixed.** New review buttons carried `aria-label="confirm duplicate cluster <id>"`, and `getByLabel` matches by SUBSTRING, so the card's own `duplicate cluster <id>` locator resolved to 3 elements. Renamed; 3/3 green. **Third occurrence of this collision in this repo.** |
| `scheduler.spec:28` | fails on base too — verified by checking out `bbaa887` and re-running. Add it to the base-failure set. |

Common tests **374** (was 356). Export playwright **150/150**. `tsc` clean in all
three packages.

**`cut-release.spec` mutates the repo, and it did again**: it rewrote
`editor/CHANGELOG.md` AND created a real `Release editor 9.9.10` commit. Reset
after the run. Budget for this every time the full suite is run with a dirty or
in-progress changelog.

## Smoke test results (2026-07-25)

Run against a real 176-minute podcast transcript (`UndertheTeaVT/data/5JRFDQ7TtZ8`, 3877
cues, ~34k tokens) on the RX 6600.

1. **Ollama silently truncates.** `ollama ps` reported `CONTEXT 4096` — the default. A 10k
   token excerpt was cut without warning and the model summarized whatever fragment
   survived. **`num_ctx` must be set explicitly per request.** 16k is comfortable on this
   GPU (qwen2.5:7b KV cache ≈ 56 KB/token → ~0.9 GB at 16k, atop 4.7 GB of weights).
2. **fabric's stock pattern fails at this model size.** With `create_video_chapters`
   verified applied (via `--dry-run`) *and* an input small enough to fit, qwen2.5:7b ignored
   the `HH:MM:SS TOPIC` contract entirely and returned conversational prose. Twice, at two
   input sizes. It is a long discursive prompt written for frontier models.
3. **Schema-constrained decoding fixes it.** POSTing to `/api/chat` with a JSON schema in
   `format` returned clean parseable output in **15.5 s**.
4. **It still hallucinates timestamps.** That same run emitted `01:10:29` for an input
   spanning only `00:04:45 → 00:15:36` — 55 minutes past the end. **The parser's range,
   monotonicity, and cue-snapping guards are load-bearing, not defensive polish**, and
   clamping must be per-chunk: a whole-video range check would have accepted that value.
5. **GPU offload works** — `100% GPU` on the RX 6600 via Vulkan.

### Environment state as of that run

`ollama-vulkan` 0.32.4 and `fabric-ai` 1.4.375 installed. The ollama systemd unit ships
**inactive and disabled**; no `~/.ollama`, no models. `~/.config/fabric` has no `patterns/`
and no `.env`, so `create_video_chapters` does not exist on disk until `fabric-ai --setup`
clones the pattern repo.

Note: Arch names the binary **`fabric-ai`**, not `fabric`, to avoid colliding with the
unrelated Python `fabric` deployment tool. Moot while fabric is deferred, but relevant if it
is ever added as an engine.

---

## Digest TAGS — first generation ever (measured 2026-07-29)

Tags had never been generated: **0 of 109 sidecars** contained a tags section. See
"Built, specified, and never run once" above. Generated via the real pipeline
(`runDigestBatch` with `sections: ["chapters","tags"]`) on `teamrcn` (7 videos),
`steven-crowder` (2) and `nuxanor-kick` (2).

### It works, and the output is good

**11/11 videos, 0 warnings** — `parseTags` accepted every live output, having
never accepted or rejected anything from a real model before. Scored by the new
tag metrics in `bin/digest-validate.ts`:

| metric | teamrcn (7 tiny videos) | steven-crowder + nuxanor-kick (4 multi-hour) |
| --- | --- | --- |
| tags per video | 4.00 (3–6) | 31.50 (21–40) |
| zero-yield tag chunks | 0/7 | 0/18 |
| empty tag sections | 0% | 0% |
| generic tags | 0% | 1.6% |
| duplicate tags | 0% | 0% |
| cross-video reuse | 7.7% | 2.4% |

Tags are markedly MORE specific than chapters on the same videos — the RC-car
channel produced `losi comp crawler`, `savage flux xs`, `mbx6e` against chapters
titled "Introduction" three times over.

### The surcharge is 5–15%, not ~100% — and the reason decides when to run them

Both the `sections` settings comment ("tags double the call count") and the
pre-run prediction (~55%) were wrong. Measured with the model **unloaded between
runs** (`keep_alive: 0`, which evicts the KV cache — without it whichever section
runs second gets a free ride and reports ~0.1 s prefill):

| run, same video, forced | calls | prompt tokens | engine | prefill | decode |
| --- | --- | --- | --- | --- | --- |
| chapters only | 5 | 20,490 | 119.6 s | 28.0 s | 82.2 s |
| chapters + tags | 10 | 40,980 | 137.9 s | **28.4 s** | 93.6 s |
| tags ALONE (cold) | 5 | 20,490 | 52.6 s | **28.0 s** | 11.7 s |

- **In one combined pass: +4.7% and +15.3%** on the two videos measured.
- **As a separate later pass: 44%** of a whole chapters pass.

The mechanism, proven by the third row rather than assumed: a tag call re-sends the
same transcript as the chapter call before it, so it **hits the engine's cached
prefix and pays essentially no prefill** (+0.4 s across 5 extra calls against
28.0 s for the first 5). Alone, it pays the full 28.0 s. All the marginal cost is
decode, and a tag list is ~30 output tokens where a chapter list is ~250.

**Therefore: if tags are wanted at all, generate them in the SAME pass as
chapters.** Deferring them costs 3–9× more and needs a second corpus-wide pass.

### Quality gap worth knowing before Phase 7 consumes tags

Cross-video reuse is **2.4%** on the multi-hour sample, and `antisemitism` /
`anti-semitism` land as two distinct tags. The tags are individually good but the
**vocabulary does not converge**, so as a search index they are weak without
normalization or clustering. That is Phase 7's problem; it is now measured rather
than assumed, and `isGenericTag` in `digest-validate.ts` catches the
format-describing tags (`youtube`, `podcast`, `commentary`) that match everything
and partition nothing.

## Attribution pilot — text-only lane REJECTED, diarized lane holds (measured 2026-08-08)

The measurement PLAN.md's Stage 2 exists to make: is the text-only attribution
lane worth ~194,000 model calls corpus-wide? **It is not, on this engine.** It
fails the quality threshold by ~15×, and separately costs ~6× more per chunk
than a digest chapter. Both lanes remain unarmed, and that is now a measured
default rather than a cautious one.

Run headless under `tsx` — no editor, no `instrumentation.ts`, no runner armed,
`settings.json` untouched (the lane is enabled via `attributeOneVideo`'s
in-memory `settings` override):

```
cd common
pnpm exec tsx ../plans/tools/attribution-pilot.ts --sample bakeoff --dry-run
pnpm exec tsx ../plans/tools/attribution-pilot.ts --sample bakeoff --label round1-bakeoff
pnpm exec tsx ../plans/tools/attribution-pilot.ts --sample video:ObviousRises-rumble/v6z1o2g \
    --method diarized --label round1-diarized
```

Engine: real ollama at 127.0.0.1:11434, `qwen2.5:7b` @ `numCtx` 8192 — the
operator's configured `digest.apps["ollama-direct"]`, which attribution reuses.
Sample: the FROZEN digest bake-off sample (`plans/bakeoff/sample.json`), so the
per-chunk cost is directly comparable to that bake-off's on the same 8 videos.
**8 videos, 17.7 audio-hours, 40 chunks, 37/40 chunks ok.**

### The headline: cross-chunk identity does not merely degrade, it collapses

| video | chunks | labels | new labels/chunk | top share | near-dup |
| --- | ---: | ---: | ---: | ---: | ---: |
| the-quartering-rumble/v6ve4n0 | 1 | 4 | n/a | 35% | 0% |
| chibi-reviews/VQykVuHd9xQ | 1 | 1 | n/a | **100%** | 0% |
| the-quartering/J0ySGwzP4Nw | 1 | 2 | n/a | 54% | 0% |
| destiny/5nmDzKB23OU | 4 | 16 | 0.33 | 64% | 81% |
| angryjoeshow/RPJqkewZP5I | 3 | 3 | 1.50 | 43% | 0% |
| rekietalaw/EsZhaCfc8HQ | 8 | 90 | **12.57** | 17% | 79% |
| chrissie-mayr/cfLF2o2-0BA | 9 | 242 | **30.25** | 22% | 98% |
| HasanAbiVODs/GjPX_ueTdfc | 13 | 346 | **28.83** | 26% | 52% |

Mean **14.70 new labels per chunk** over the 5 multi-chunk videos, against the
pre-stated "≲ 0.3 = healthy, ≳ 1 = do not sweep" threshold. `singletonLabelRate`
is ~100% on every multi-chunk video: essentially no label survives from one
chunk to the next.

### The mechanism, and it is worse than churn: the model stops emitting labels

On multi-chunk videos `qwen2.5:7b` puts **verbatim transcript text in the
`speaker` field**, truncated at the schema's 60-char `maxLength`. Actual labels
from `chrissie-mayr/cfLF2o2-0BA`:

```
"Robbie and maybe it looked weird not that Ryan wasn't uh"
"fantastic I loved him but uh if it were somebody else can"
"you imagine what would have happened to this movie of Amy"
```

So 242 "speakers" is 242 fragments of the transcript. The schema constrains the
label's LENGTH, not its nature, and `isUselessSpeakerLabel` only rejects
"Speaker N" — neither guard can catch this. The one-chunk videos in the same run
produced perfectly sane labels (`Jeremy`, `Donald Trump`, `Stephen Colbert`;
`Host` / `Guest`), so the failure is not the model's ability to name speakers.

> **CORRECTED 2026-08-08.** This section previously concluded that the failure
> "appears once the prompt carries a `knownSpeakers` roster and grows", i.e. that
> the cross-chunk identity mechanism was the thing breaking. **That is wrong**,
> and the per-chunk data in `plans/attribution-pilot/round1-bakeoff.json` — read
> via `metrics.labelFirstChunk` — says so:
>
> | video | where the collapse starts | evidence |
> | --- | --- | --- |
> | `destiny/5nmDzKB23OU` | **chunk 0 — no roster exists yet** | 15 of its 16 labels first appear in chunk 0, and all 15 are transcript text; the only later label is a clean `Guest` in chunk 2 |
> | `rekietalaw/EsZhaCfc8HQ` | **intermittent, not monotonic** | new labels by chunk: 2, 17, 3, 15, 2, 2, **48**, 1 — chunk 0 is clean (`Bronca`, `SVH`), chunk 7 is clean (`Nick the Dick`), and chunks 1/3/6 collapse in between |
>
> `findTurns` passes `knownSpeakers` only when `labels.length > 0`
> (`controller/attributeOne.ts`), so **chunk 0 runs with no roster at all — and
> still fails.** Prompt length cannot explain a chunk-7 recovery after a
> chunk-6 catastrophe either. The three videos that worked were the three
> SINGLE-CHUNK ones (134/173/315 cues); every full 600-cue chunk is at risk.
>
> The decisive evidence is the labels themselves: dozens sit at **exactly 60
> characters**, the schema's own `maxLength`, several carrying the cue's internal
> newline. This is **schema-adherence collapse on a long prompt** — `speaker` is a
> free string and nothing makes transcript text unrepresentable in it, so the
> model continues the passage into the label field.
>
> This reframes the fix from "make the roster work" to "**close the label
> space**" — the constraint `speakerSchema()` already proves works, since it uses
> an enum of cluster indices precisely because "an enumerated literal alternation
> is the constraint that converts reliably everywhere".

A second failure shape on `angryjoeshow/RPJqkewZP5I`: 12,198 output tokens for
3 surviving marks, **11 `bad-timestamp` warnings**, coverage 24%, 2 mark-free
chunks. Masses of output, nearly all rejected by the parser's own guards.

### Cost: ~6× a digest chapter per chunk, and the projection is 3–6× worse

| quantity | text-only attribution | digest chapters (round 2, same 8 videos) |
| --- | ---: | ---: |
| s/chunk, engine | **66.2** | 11.2 |
| s/chunk, engine excl. model load | 65.4 | — |
| s/chunk, wall (video wall ÷ chunks) | 70.8 | — |
| decode tokens/s | 41.1 | — |
| output tokens, 13-chunk video | **31,266** | order 10² per chunk |

Engine and wall are within 7% of each other here, so this is **not** contention:
it is decode volume. The lane generates roughly an order of magnitude more output
per chunk than a digest, because it degenerates into one entry per transcript
line despite the prompt instructing otherwise.

Projected over the census (74,321 videos / **194,053 chunks** at maxCues 600,
`chunksPerAudioHour` 2.46; sample density 2.26):

**146.8 days idle to 159.0 days contended** — from n = 8 videos / 40 chunks, one
box, one hour. Against PLAN.md's pre-measurement estimate of 25–55 GPU-days. And
this would be a SECOND sweep on the same 8 GB card, additive to a digest sweep
that has completed 0.17% of its own.

Box: loadavg 10.67 → 2.04, free 7.75 → 11.65 GB, 0 unparsed engine log lines.
The box was busy at the start (the operator's own ffmpeg work) and quiet by the
end, and the wall/engine ratio confirms that did not distort the result.

### Diarized lane (n=1): the one-call claim HOLDS

`ObviousRises-rumble/v6z1o2g`, the corpus's only `diarization.json`:

- **1 call per video** — the claim under test, confirmed.
- 9 clusters offered → 9 named, confidences 0.30–0.90, 0 warnings.
- 13.4 s wall / 8.3 s engine excl. load, against 66.2 s/chunk × chunks for the
  same video's text-only path.
- Labels are genuinely good: `Mr. Obvious` at 73.8% of talk time (the host — the
  channel is ObviousRises), plus `Erica Kirk`, `Belle Driver`, `Anonymous
  Critic`, `Property Owner`.

Three clusters were named `Mr. Obvious` and three `Anonymous Critic` — that is
the documented diarizer over-split at threshold 0.9 (13 clusters), and the model
correctly recognised them as one person each. n=1 and one chunk, so this proves
the lane end to end and says nothing about cross-chunk identity, which the
diarized lane does not have to solve.

### What this decides

**Do not run the text-only lane over the corpus on this engine.** Not a
close call: 14.70 new labels per chunk against a 0.3 target, and 147–159 days
against 25–55. The lane is not structurally wrong — it works on single-chunk
videos — so the open question is whether a better instruction-follower (or a
schema/prompt change that makes a transcript fragment unrepresentable as a
label) fixes it. That is a bake-off, not a sweep, and it costs ~16 minutes.

**The diarized lane is the one worth investing in**, which inverts PLAN.md's
sequencing for a second reason beyond cost: only **865** of 78,917 video dirs
still have audio, so diarization can reach ~1.1% of the legacy corpus and is a
going-forward story (capture at transcribe time).

> **CORRECTED 2026-08-08.** "~1.1%" overstates the diarized lane's reach by an
> order of magnitude, because having audio is not sufficient — the lane also
> needs a TRANSCRIPT. Re-measured across all 78,938 video dirs today:
>
> | | |
> | --- | --- |
> | with `transcript.cues.json` | 75,398 |
> | with audio still on disk | **893** |
> | audio **and** transcribed → diarized backfill can run | **87** (0.115% of transcribed) |
> | of those, already diarized | 1 |
> | audio but NOT yet transcribed | **806** |
>
> So the backfill reaches **87 videos, not 865**. The 806 pending videos are the
> ones that matter: audio is deleted once a video is transcribed, so each of them
> loses its audio permanently unless capture is armed first. Diarization is the
> one input that cannot be reconstructed later — text-only attribution can be
> re-run whenever the model improves; deleted audio is gone. The value of this
> lane is almost entirely *going forward*, and the window is still open.

Making diarization runnable — sherpa-onnx is not installed, system python is
3.14.6 against sherpa's cp313 wheels, pyenv has 3.12.12 and `uv` is available —
is now the highest-value next step, not a corpus-wide naming pass.

> **RESOLVED 2026-08-08.** sherpa-onnx IS now installed. `.diarize/env` is a
> durable `uv`-managed Python **3.13.11** venv with **sherpa-onnx 1.13.4** +
> numpy 2.5.1, and `.diarize/models` holds pyannote segmentation-3.0 +
> NeMo TitaNet-small (~148 MB). Both are gitignored; `.diarize/README.md` is
> tracked and carries the rebuild recipe. See "Diarization environment"
> (2026-08-08) below.

### Artifacts and reversibility

`plans/attribution-pilot/round1-bakeoff.{json,md}` + `-quality.md` (verbatim
transcript beside every label claim), same trio for `round1-diarized`. **9
`attribution.json` sidecars** were written into the real corpus (8 text-only + 1
diarized), matching the 9 `attributed` outcomes exactly. The backfill registry
sees them: `attribution-text` reports `present` for the piloted videos and
`missing` for an untouched one, and on the diarized video the text kind reports
`present` via the downgrade rule rather than claiming work. Undo is one command:

```
find transcripts/channels -name attribution.json -delete
```

---

## Diarization environment (2026-08-08) — rebuilt, and it reproduces the record on disk

`scripts/diarize.mjs` and `scripts/diarize-sherpa.py` shipped working on
2026-08-07; what did not survive was the venv, so the code was shipped and
unrunnable. Rebuilt durably at **`.diarize/`** (`env/` + `models/` gitignored,
`README.md` tracked with the recipe):

| | |
| --- | --- |
| interpreter | Python **3.13.11**, `uv venv --python 3.13` |
| packages | **sherpa-onnx 1.13.4**, numpy 2.5.1 |
| models | pyannote segmentation-3.0 (`model.onnx`) + NeMo TitaNet-small (`titanet.onnx`), 148 MB total |

A dedicated interpreter is not a preference: sherpa-onnx publishes wheels only to
cp313 and this box's system Python is 3.14.6. That is why
`settings.diarization.python` is a configurable path.

### The rebuild is byte-identical to the sidecar the spike produced

Re-ran `scripts/diarize.mjs` on `ObviousRises-rumble/v6z1o2g`'s audio to a **temp
path** (nothing written to the corpus) and diffed against the `diarization.json`
generated 2026-08-07 by the now-deleted venv:

| field | on-disk | rebuilt | |
| --- | --- | --- | :-: |
| speakers | 13 | 13 | OK |
| turns | 51 | 51 | OK |
| `audioSeconds` | 766.101 | 766.101 | OK |
| engine version / threshold | 1.13.4 / 0.9 | 1.13.4 / 0.9 | OK |
| **`turns` array** | — | — | **byte-identical** |

So the pipeline is deterministic given the same models and threshold, and this
diff is a real check on the environment rather than a smoke test.

### The clean throughput number, which the spike left open

That run: **124.5 s wall for 766 s of audio = 585 s/audio-hour**, 381% of the
400% available CPU, box at loadavg 2.7.
`plans/diarization-spike-results.md` §8 listed "the clean throughput number" as
still open — every figure there was contended. **This closes it, and changes no
conclusion**: 585 lands inside the spike's estimated 500–700 band, still ~2.6×
slower than the GPU's measured 221 s/audio-hour ASR, so the spike's decision gate
still fires. For scale, the same file took 277.7 s (1305 s/audio-hour) under
load ~30.

### Corpus reach, re-measured across all 78,938 video dirs

| | |
| --- | --- |
| with `transcript.cues.json` | 75,398 |
| with audio still on disk | **893** |
| audio **and** transcribed → diarized backfill can run | **87** (0.115%) |
| of those, already diarized | 1 |
| **audio but NOT yet transcribed** | **806** |

The 806 are the number that matters: audio is deleted once a video is
transcribed, so each loses its audio permanently unless capture is armed first.

`settings.diarization` currently: `enabled` false, `inlineAfterTranscribe` false,
`threshold` 0.9, `threads` 4, `python` `"python3"`, `segModel`/`embModel` empty.
**The three path fields were NOT written** — that is a change to the operator's
`settings.json` and is deliberately left for an explicit go-ahead.

---

## Attribution round 2 (2026-08-08) — the closed-cast schema, and it works

Run via the new `plans/tools/attribution-bakeoff.ts`, which unlike the pilot
**writes no sidecar**: it drives `attributionPrompt` + `attributionTurns` + the
digest app directly and scores in memory. The harness checks its own claim —
`attribution.json` count **9 before, 9 after**. 14 calls (2 cast + 12 chunk),
`qwen2.5:7b` @ 8192, maxCues 600 — identical engine to round 1, so **the schema
is the only variable**.

The design, from the corrected diagnosis above (close the label space, don't fix
the roster): **pass A** discovers the cast in ONE call over evenly-spaced
excerpts; **pass B** assigns turns per chunk with `speaker: { enum: [...cast,
"Unknown"] }` plus `maxItems`, which `turnSchema()` lacks entirely.

### Every pre-stated threshold met

| criterion | bar | round 1 | round 2 | |
| --- | ---: | ---: | ---: | :-: |
| new labels/chunk (mean) | ≤ 0.3 | 14.70 | **0.29** | PASS |
| transcript-text labels (worst video) | 0 | rampant | **0%** | PASS |
| s/chunk engine | < 25 | 66.2 | **24.1** | PASS |
| off-cast labels (grammar held) | 0 | n/a | **0** | PASS |

### The mechanism claim is confirmed outright

**0 off-cast labels out of 213 turns emitted** across 12 chunks. The enum
converted to a grammar and held 100% of the time — a transcript fragment was
literally not expressible. `truncatedLabelRate` 0% against round 1's population
of labels sitting at exactly the 60-char `maxLength`.

On `rekietalaw/EsZhaCfc8HQ`: **2 labels, down from 90**; new/chunk **0.29 vs
12.57**, a 43× reduction on the same video, same engine.

Cost fell with it, as predicted — the decode was the label strings: **8,923
output tokens over 12 chunks**, against round 1's 31,266 on a single 13-chunk
video. Corpus projection **52.4–54.0 days**, down from 147–159.

### Read these caveats with the PASS

1. **The identity headline rests on ONE video.** `destiny/5nmDzKB23OU` produced
   no labels at all, so it reports `n/a`, and the "mean 0.29" is rekietalaw's
   number alone. n=1.
2. **The cost margin is 4%** (24.1 against a bar of 25), and still 2.1× the
   digest lane's 11.2.
3. **Half the sample yielded nothing.** destiny returned **64/64 turns
   `Unknown`** because pass A found only two generic roles (`Host` 0.90,
   `Caller` 0.50) on a two-person debate it could not name. This is the
   bias-toward-dropping design working as intended — round 1 gave that video 15
   transcript fragments as "speakers"; round 2 gives nothing. Both are useless,
   but only one pollutes the corpus.
4. `singletonLabelRate` 50% on rekietalaw (one of two labels appears in a single
   chunk), top share 81%.
5. The `outOfRangeTurns` counter was added mid-run and was **not live** for these
   numbers; turns dropped for landing outside a chunk's range are unaccounted.

### Pass A is independently valuable, and its names are grounded

Every cast name was checked against the transcript. **None was hallucinated:**

| video | cast (confidence) |
| --- | --- |
| destiny/5nmDzKB23OU | Caller (0.50), Host (0.90) |
| rekietalaw/EsZhaCfc8HQ | Nick Ricada (0.90), Scarlett Hampton (0.50), Jacob Frey (0.20), Tim Walls (0.20), Cecil (0.50), Trinity Beholder (0.50), Dick Masterson (0.20) |

`Nick Ricada` appears verbatim in the transcript — it is how the ASR rendered
"Rekieta", so the model copied rather than invented. `Jacob Frey` (11 mentions)
and `Tim Walls` are talked ABOUT, not speakers; the model gave both 0.20, and
**pass B never assigned either a turn**. So an over-broad cast did not translate
into wrong attribution.

Pass A costs **7.9 s per video, 1 call** → **6.8 days** for all 74,329 videos,
against 52.4 for the per-turn lane. If per-turn work is ever judged not worth it,
cast-only ships on its own as "videos featuring X" without claiming who said
which line.

### Artifacts

`plans/attribution-pilot/round2-closed-cast.{json,md}`. No sidecar written, so
there is nothing to undo. `ATTRIBUTION_PROMPT_VERSION` deliberately **not
bumped** — it moves only when a variant is adopted into `attributeOne.ts`, and
bumping it now would invalidate the 9 sidecars on disk for a change that has not
been adopted.

---

## Attribution round 3 (2026-08-08) — the full 8 videos, and the per-turn lane is DEAD

Round 2 passed on 2 videos and was explicitly recorded as n=1 for the identity
headline. The frozen 8-video bake-off sample was run to settle it: 40 chunk calls
+ 8 cast calls, same engine (`qwen2.5:7b` @ 8192), same harness, on a genuinely
quiet box (loadavg **0.16**, GPU 0%, vs round 2's 6.3). `attribution.json` count
**9 before, 9 after**. Report: `plans/attribution-pilot/round3-closed-cast-8.md`.

### Verdict: NOT MET

| criterion | bar | round 1 | round 2 (n=2) | **round 3 (n=8)** | |
| --- | ---: | ---: | ---: | ---: | :-: |
| new labels/chunk | ≤ 0.3 | 14.70 | 0.29 | **0.27** | PASS |
| transcript-text labels | 0 | rampant | 0% | **0%** | PASS |
| off-cast labels | 0 | n/a | 0 | **0** | PASS |
| s/chunk engine | < 25 | 66.2 | 24.1 | **28.6** | **FAIL** |

**Cost is why it dies**, and round 2's 24.1 was a small-sample artifact: output
volume scales with video length, and round 2's two videos were short relative to
the sample. 38,799 output tokens over 40 chunks (970/chunk) against round 2's
8,923 over 12 (744/chunk). Corpus projection **62.9–64.2 days**, worse than round
2's 52.4 and 5.7× the digest lane's 11.2 s/chunk.

### The schema fix is real, and it is not enough

Keep both halves of this. The closed enum **worked exactly as designed and never
once failed**: 0 off-cast labels across ~1,705 emitted turns on 40 chunks, 0%
transcript-text labels, 0% truncated. The 14.70 → 0.27 collapse in the headline
is genuine. The hypothesis was right.

**But a passing headline was hiding a lane that produces almost nothing usable.**

| | |
| --- | --- |
| turns accepted | **338** |
| turns answered `Unknown` | 847 |
| turns **discarded as out-of-range** | **520** |
| usable share | **20%** |

`outOfRangeTurns` was wired after round 2 and was live here for the first time —
it is the round's most valuable finding. A fifth of all output is timestamps
outside the chunk the model was given, **silently dropped by both this harness and
the shipped `findTurns`** (`attributeOne.ts` `continue`s on the same condition
without counting). This is a SECOND failure, independent of the label space, and
it was invisible in rounds 1 and 2.

### Why the 0.27 must not be read as success

**4 of 8 videos are single-label at 100% talk time, and a 5th produced nothing.**
A single label covering everything scores a near-perfect headline while being
worthless — the exact trap `dominantSpeakerShare` exists to expose.

| video | chunks | labels | new/chunk | top share | verdict |
| --- | ---: | ---: | ---: | ---: | --- |
| chibi-reviews/VQykVuHd9xQ | 1 | 1 | n/a | 100% | degenerate |
| the-quartering/J0ySGwzP4Nw | 1 | 1 | n/a | 100% | degenerate |
| angryjoeshow/RPJqkewZP5I | 3 | 1 | 0.50 | 100% | degenerate, **and over the bar** |
| chrissie-mayr/cfLF2o2-0BA | 9 | 1 | 0.13 | 100% | degenerate — a multi-guest podcast as ONE speaker |
| destiny/5nmDzKB23OU | 4 | 0 | n/a | — | **nothing at all** (64/64 `Unknown`), reproduced from round 2 |
| the-quartering-rumble/v6xl0vu | 1 | 2 | n/a | 85% | plausible |
| rekietalaw/EsZhaCfc8HQ | 8 | 2 | 0.29 | 81% | plausible |
| HasanAbiVODs/GjPX_ueTdfc | 13 | 2 | 0.17 | 65% | **wrong** — see below |

So the mean of 0.27 is computed mostly over videos that emitted one label. At
most 2 of 8 produced defensible multi-speaker attribution.

### Pass A is better than pass B, but it is NOT clean either

0 cast names were rejected by the guards on any video, and most are real. But
checking every name against its transcript AND title:

- **Names come from the title as well as the transcript.** `Chrissie Mayr`
  (confidence **1.00**) appears 0× in the transcript and is in the title. That is
  legitimate grounding — the prompt supplies the title — but it refines round 2's
  claim of "checked against the transcript, none hallucinated": the correct
  statement is *grounded in transcript or title*. Same for `AngryJoe` (0× as one
  word; `Angry Joe` appears 2×).
- **It names TOPICS as speakers.** On the 8-hour `HasanAbiVODs/GjPX_ueTdfc` the
  cast is Cody / Troop AJ Hunter / Lane / Tony / Raymond — **the host, Hasan, is
  absent** — and pass B then attributed 65% of the video to `Raymond` and 35% to
  `Tony`, who are discussed (55× and 28× mentions), not speaking. `Twitter` was
  offered as a person on `the-quartering/J0ySGwzP4Nw`. `Jacob Frey` / `Tim Walls`
  on rekietalaw are the same error, saved only by pass B declining to use them.
- **It finds no names at all on some videos**: `Reviewer` (chibi-reviews),
  `Caller`/`Host` (destiny) — and destiny's generic cast is what caused its
  64/64 `Unknown`, reproduced identically across rounds 2 and 3.

Cast discovery costs **5.1 s/video, 1 call → 4.4 days** corpus-wide (better than
the 6.8 previously projected). That is cheap enough to be interesting, but the
Hasan result means "videos featuring X" would confidently list people who never
spoke. **Cast-only is a promising candidate, not a shippable one**, and it needs
its own evaluation with its own pre-stated bar — the round-1 decision table's
"pass A sane ⇒ ship cast-only" was written before anyone had seen pass A's output
on 8 videos.

### What this decides

**Do not adopt the closed-cast per-turn lane.** `attributeOne.ts` is unchanged and
`ATTRIBUTION_PROMPT_VERSION` is NOT bumped, so the 9 sidecars on disk stay valid.
Cost alone is disqualifying (63 days for a lane the digest sweep already
out-competes at 11.2 s/chunk), and the quality is thinner than the headline.

The diarized lane remains the one worth having: 1 call per video, acoustic
boundaries, and it already produced clean names with calibrated confidences.

---

## Diarization backfill, measured in flight (2026-08-08)

Running `common/bin/diarize-backfill.ts --scope transcribed` over the 87
transcribed-with-audio videos (257 audio-hours), `concurrency` 1, `threads` 4.

### Peak RSS on a genuinely long file — the spike's open item, now measured

`plans/diarization-spike-results.md` §8 listed this as untested and extrapolated
**~230 MB per audio-hour**. Measured on `HasanAbiVODs3/bCp-EvNxBgs`, a
**7h42m** file: **3.9 GB RSS**, i.e. **~505 MB per audio-hour — 2.2× the
extrapolation.** Memory is released fully between videos (11.4 GB free again
immediately after).

**This makes `diarization.concurrency: 1` load-bearing, not merely polite.** The
backfill list contains an 8h02m VOD, which at this rate needs ~4.1 GB resident.
Two of those in parallel would not fit alongside anything else on a 16 GB box
that already runs several GB of swap. Raising `concurrency` on this hardware
risks an OOM mid-run, and the failure would land on the longest, most valuable
videos.

### Throughput is BETTER than the clean single-file measurement

| | s/audio-hour |
| --- | ---: |
| spike, contended (loadavg ~30) | 1305 |
| clean single-file re-run, 12.8 min file | 585 |
| **backfill running average, 4 videos / 8.2 audio-hours** | **358** |
| the 7h42m file alone | 373 |

Short files are dramatically cheaper per audio-hour (18 s for a 9-minute file =
~120 s/audio-hour), so the 585 figure — taken from one 12.8-minute file — was
not representative of a mixed batch. Projected wall time for the 87 fell from
~42 h to **~25 h**. Every number here is a rate over its own denominator; none
is a per-video figure.

### A pre-existing bug found by running this: `isRealAudioFile` accepts non-audio

`common/lib/videoStatus.ts:63` allow-lists **anything** whose name starts with
`audio.` and then subtracts a denylist. It therefore returns true for files that
are not audio at all. Corpus-wide, exactly **3 files across 3 video dirs**:

| file | why the denylist misses it |
| --- | --- |
| `audio.en-orig.vtt` | a SUBTITLE track; no rule excludes `.vtt` |
| `audio.live_chat.json.part-Frag114` | the `.part` rule tests `endsWith`, and this ends in `-Frag114` |
| `audio.live_chat.json.part-Frag514` | same |

Bounded (913 real audio files against 3 fakes), but it is not only cosmetic:

- `resolveDiarizableMedia` (`controller/diarizeOne.ts`) hands the file to
  ffmpeg, so those 3 videos fail the backfill. Fails fast and is visible in the
  outcome tally; deliberately NOT special-cased in the backfill script, which
  shares the runner's resolver on purpose so the two cannot disagree.
- **`audioFilesToRemove` uses the same predicate**, so the cleanup sweep can
  delete `audio.en-orig.vtt` — a subtitle — believing it is audio. That is real,
  if small, data loss. (Recorded here twice as `audioFilesToDelete`, which is not
  a function that exists; corrected 2026-08-08 along with the fix itself.)
- `readVideoFiles().audioFiles` feeds the cleanup buckets, so "Est. reclaim"
  counts these too.

**Not fixed here.** Tightening the predicate to require a known media extension
changes cleanup behaviour and touches several exact-string e2e assertions; it
wants its own branch and a full e2e run, not a drive-by during a 25-hour job.

### Confirmed in flight: what the `isRealAudioFile` bug actually costs

The 3 predicted videos failed at **[15/87]–[17/87]**, in **0 s each** (fail-fast,
no wasted engine time). Reproduced read-only on
`chrissie-mayr/5UHN0qEoyVM`, output to a temp path — no sidecar written anywhere:

```
[out#0/f32le] Output file does not contain any stream
Error opening output files: Invalid argument
diarize-sherpa: ffmpeg failed (234)
diarize: engine exited 4
```

That directory contains **no real audio whatsoever** — only `audio.en-orig.vtt`,
a subtitle, beside the usual `transcript.*`. So the honest outcome for these
videos is **`no-audio`**, and the bug makes them report **`failed`** instead.

That is not cosmetic. `DiarizeOneOutcome` documents `not-configured` as
"reported distinctly from a failure so an operator can tell 'not set up' from
'tried and broke'" — the same distinction `no-audio` carries. A predicate that
invents audio collapses "there was nothing to do here" into "the engine broke",
which is precisely the signal an operator triages on.

Two consequences to expect, both small and both permanent until it is fixed:

1. The backfill's final tally will be **84 diarized + 3 failed**, not 87, and
   those 3 fail identically on every re-run.
2. With the guard armed they are transcribed-and-undiarized forever, so the
   cleanup sweep will report **3 videos "awaiting diarization" permanently**.
   Ironically the guard is now the thing preventing `audioFilesToRemove` — which
   shares the broken predicate — from deleting that subtitle as if it were audio.

**FIXED 2026-08-08.** Requiring a known media extension turned out not to be
enough on its own — this repo's own transcode scratch is
`audio.tmp-<pid>.<targetFormat>`, a perfectly valid audio extension, so an
extension allowlist would have re-admitted it and raced the running transcoder.
The shipped rule is an ANCHORED SINGLE-SEGMENT match (`^audio\.(<media exts>)$`,
`^source-media\.(<media exts>)$`, `^audio\.(<media exts>)\.part$`) over
`AUDIO_EXTS ∪ VIDEO_CONTAINER_EXTS`, which rejects all four junk names and the
scratch file with one rule. Lives in the new `lib/mediaFiles.ts` (pure string
rules, no `node:fs`, so the editor's client components can share the lists);
`lib/videoStatus.ts` re-exports it. Tests: `lib/mediaFiles.test.ts`.

### CORRECTION + escalation: the kernel OOM-killed a diarization run

**The "~505 MB per audio-hour" figure recorded above is wrong, and the error was
in the method: it was a single `ps` sample taken mid-run, not a peak.** Retract
it as a peak-memory number.

The measured peak, from `journalctl -k`, on `hasanabi/2834644359` (6h12m):

```
Out of memory: Killed process (python) total-vm:34643056kB, anon-rss:11138996kB
```

**11.1 GB resident, 34.6 GB virtual — killed by the kernel after 35 minutes of
engine time.** No sidecar was written; nothing in the corpus was damaged; the
backfill continued to the next video.

**Memory is NOT linear in duration, so duration is a proxy and not the cause.**
A **7h42m** file completed fine, and a **6h12m** file died. The mechanism is
agglomerative clustering holding a pairwise distance matrix over speech-segment
embeddings — **O(n²) in SEGMENT COUNT**. A dense, fast-turnover Twitch VOD yields
far more segments per hour than a monologue or a reaction video, so content
density is what decides it. This also explains the throughput spread already
recorded (120 s/audio-hour on short files vs 373 on a long one).

Consequences, measured against the remaining work:

| | |
| --- | --- |
| remaining after video 19 | 67 videos, 216 audio-hours |
| of those **≥ 4h** | **26 videos, 149 audio-hours** |
| of those ≥ 6h | 10 videos, 77 audio-hours |

So most of the remaining audio sits in the size class that OOM'd once. Each OOM
costs that video's full engine time (~35 min here) and puts an 11 GB transient on
a 16 GB box — the kernel chose python both by luck and by it being the largest
RSS, and that is not a guarantee.

**Mitigation shipped, not applied:** `--max-audio-hours` on
`bin/diarize-backfill.ts` defers longer videos and **says loudly what it
deferred** (a cap that silently shrinks the work reads as "the corpus is done").
`--max-audio-hours 4` leaves 45 videos / 74 audio-hours (~6 h at the observed
300 s/audio-hour) and defers 27 / 155.

It is **deliberately not applied to the running job**: scaling down approved
scope is the operator's call, and the failures are non-destructive. Deferred
videos lose nothing — the cleanup guard holds their audio, so they can be run
later on a bigger box or with a segment-bounded clusterer.

`diarization.concurrency: 1` is now doubly load-bearing: two 11 GB transients
would not merely be tight, they would be unschedulable.

## Windowed diarization (2026-08-08) — the OOM wall is REMOVED, with numbers

### The two memory sinks, and why windowing closes both

1. **`sherpa_onnx` clustering is O(n²) in SPEECH-SEGMENT count**, not in duration. Segment
   density varies ~40x across this corpus, which is why duration never predicted the kills:
   a sparse 7h42m file finished while a dense 6h12m one died.
2. **The whole-file decode buffered the entire stream** — `subprocess.run(stdout=PIPE)`
   accumulates one `bytes` object, ~1.84 GB for an 8h file, peaking near 2x that while the
   buffer grows.

Windowing divides per-window `n` by the window count, so the matrix falls by its SQUARE, and
one window is decoded at a time. The window decode also writes straight into a preallocated
`np.empty(n, float32)` via `readinto`, so even the per-window buffer never doubles.

### Measured, on the file that was being killed

`hasanabi/2834644359`, 6.21 h (22,368 s), 9 windows of 45 min with 30 s overlap:

| | before | after |
| --- | --- | --- |
| outcome | **OOM-killed** (kernel, `anon-rss 10,512,464 kB`) | **completed** |
| peak RSS | 10.5 GB | **~2.0 GB** (`VmHWM` 2,061,008 kB) |
| result | nothing | 3,433 turns, 96 speakers, 2,774 s (442 s/audio-hour) |

Peak RSS is sampled from `/proc/<pid>/status` — **GNU `time` is not installed on this box**.
Two kernel kills are in the journal at 18:39 and 19:21 on 2026-08-08, both at ~10.5 GB
anon-rss, which is what the O(n²) estimate brackets (30k segments = 6.7 GiB, 40k = 11.9 GiB).

### Reproducibility gate — short files are byte-identical

`ObviousRises-rumble/v6z1o2g` re-ran through the new script with windowing not triggered:
**51 turns, 13 speakers, every non-volatile field equal** to the sidecar on disk, and no
`windowing` key. The whole-file branch is the original code, unchanged, and `--window-minutes 0`
forces it. This is what keeps the 51 sidecars already written reproducible.

### Quality gate — compared on talk-time, not speaker count

Windowed vs whole-file on the same file (4-minute windows, i.e. a HARSHER seam test than the
shipped 45-minute default):

| | whole-file | windowed |
| --- | --- | --- |
| total speech | 713.3 s | 712.7 s (**−0.1%**) |
| wall-clock covered | 711.3 s, 0.03–765.97 | 711.4 s, 0.03–765.98 |
| speakers | 13 | 6 |
| top-1 / top-2 talk share | 73.1% / 84.3% | 88.2% / 94.0% |

Windowing's risk is fragmenting one person across seams. The opposite happened: no speech is
lost, coverage is identical, and identity is MORE concentrated — consistent with the known
over-splitting at threshold 0.9, since centroids averaged over a speaker's longest turns are
a cleaner signal than sherpa's per-segment clustering.

### THE BUG THE GATE CAUGHT, which reading the code did not

The first seam merge joined only **consecutive** turns in the sorted list. That is not
equivalent to merging a speaker's own intervals: two different LOCAL speakers can map to one
GLOBAL speaker, and their turns then interleave with other people's. On the 6h12m file that
left **35 same-speaker self-overlaps and 24 sub-0.5s splits** — talk time double-counted in
every downstream consumer. Fixed to a per-speaker interval union; re-verified at 0 and 0.
Cross-speaker overlap is deliberately preserved (genuine overlapping speech; the whole-file
path emits it too — 702 such pairs on this file).

### API facts, verified live against the installed sherpa-onnx 1.13.4

- `SpeakerEmbeddingExtractor(cfg)` — `.dim` is **192**; `.create_stream()` →
  `accept_waveform(sr, samples)` / `input_finished()`, then `.is_ready(stream)` and
  `.compute(stream)`.
- `FastClustering(FastClusteringConfig(num_clusters, threshold))` is **callable**: it takes an
  arbitrary `(n, 192)` float32 array and returns a list of labels. It exposes no named
  methods (`dir()` is empty) — call the instance.
- `ffmpeg -ss N -t D -i <file> -f f32le -ac 1 -ar 16000 -` is sample-exact on this corpus's
  files, so `-ss` BEFORE `-i` (input seek) is safe for window boundaries.

### Windowing is recorded but is NOT part of the freshness identity

`DiarizationRecord.windowing` is top-level, deliberately outside `engine`. The freshness
target is built from settings alone and cannot know a video's duration, so a window field in
the identity would mark every sidecar on disk stale the day windowing shipped. Same treatment
`version` already gets, for the same reason.

### The cap is now OFF by default

`settings.diarization.maxAudioHours` shipped at 4 h as the stopgap and defaults to **0** now
that windowing exists. Residual risk, stated rather than hidden: the engine decides whether to
window from **ffprobe**, and if ffprobe cannot measure the file it falls back to the
whole-file path (preserving determinism). A multi-hour file whose duration cannot be measured
would therefore take the old path; setting `maxAudioHours` again is the backstop.

## Corrupt-media scan (2026-08-08) — first corpus run, and it found four things

Tier 1 only (ffprobe container read), **953 media files across 68 channels in 83 s**:

| verdict | files | size |
| --- | ---: | ---: |
| unreadable | 4 | 4.04 GiB |
| stray (unrecognized name) | 39 | 1.17 GiB |
| unknown (duration mismatch) | 7 | 0.86 GiB |

- **`nuxanor-kick/fd7bd973-…/source-media.temp.mp4`, 4.04 GiB** — `moov atom not found`. The
  known case, and the only `source-media.*` in the corpus. Already transcribed; disk at 99%.
- **3 ZERO-BYTE `audio.mp3`** in `leaflit-rumble` (`v6v9mq3`, `v6v9o25`, `v6v9r2r`), none
  transcribed. This is the more interesting find: a 0-byte file satisfies the NAME-based
  `isRealAudioFile`, so `destinationExists` reads these videos as already downloaded and the
  pipeline never re-fetches them. `v6v9r2r` also holds a real `audio.aac`, which
  `AUDIO_READ_PREFERENCE` (mp3 first) would pass over in favour of the empty file.
- **39 `transcript.m4a` in `community-notes`, 1.17 GiB** — audio written under the SUBTITLE
  output template. Invisible to the app in both directions: not audio (wrong base name), and
  not a subtitle either, because `SUB_FILE_RE` requires `transcript.<x>.<y>` — two segments.
- **7 duration mismatches**, up to 5 h (`piratesoftware/yTj0ciOOZys` is 18,315 s short).
  Reported as `unknown`, never as `corrupt`: `ffmpegStreamProbe` records that a truncated
  container exits 0, so only the opt-in tier-2 decode can settle these.

**The scan deliberately looks at every MEDIA-EXTENSION file, not only recognized ones.** The
file it was written for is precisely one the fixed predicates exclude — scanning only
recognized outputs would have missed it.

---

## Phase D step 1 — the digest counter collapse (verified 2026-08-09)

**The digest kind's `state()` was dead code as shipped.** `channelSnapshot.ts` resolved its
per-video probes from `laneBackfillKinds()`, which filters on
`lane.queueKey === BACKFILL_QUEUE` and therefore excludes digest by construction. So Phase C
registered the operation and moved no number anywhere. It now iterates `allBackfillKinds()`,
and the lane filter moved to the READ side as `laneEntriesOf()`
(`common/lib/backfillKinds.ts`).

**Four generic sum sites assumed `snapshot.backfill` WAS the backfill lane**, and all four
would have absorbed ~75,000 digest videos:
`editor/app/channels/[slug]/lib/stageStatus.ts:384`,
`editor/app/actionable/lib/loadActionable.ts:150` and `:158`,
`editor/app/api/widget/sync/route.ts:116`.

**`addBackfillState` discards `present` by design** (`common/lib/backfillKinds.ts`), so the
counts cannot yield a coverage denominator. That is why `BackfillSnapshotEntry.eligible` is
stored rather than derived, and why `presentBackfillWork()` returns `null` — not 0 — for a
snapshot written before the field.

**`digestVideo.ts:158` regenerates only the sections that are not fresh**
(`stale = sections.filter((s) => force || !isSectionFresh(...))`). This is what makes
`partial` a cost distinction rather than a label: a video needing only tags is a fraction of
one needing everything.

**`candidateAction` in `common/controller/backfillBatch.ts` is still the ONLY `never` check in
the backfill system.** Adding `partial` to `BackfillState` produced a compile error there and
nowhere else — `addBackfillState` and (formerly) `countBackfillWork` are unguarded if-chains.

**`countBackfillWork` had already drifted before this change.** It re-spelled the reachable
rule as `if (state === "missing" || state === "stale")` and counted `blocked` nowhere, despite
its own header promising the same derivation as the batch. It now folds through
`addBackfillState` + `reachableBackfillWork` and returns `blocked` as a fourth field.

**`backfillSweep.ts` and `backfillBatch.ts` contained LITERAL NUL BYTES** (2 and 1
respectively), used correctly as join/key separators. This is why `grep` treated both as
binary, and why the scope comparison at `backfillSweep.ts:382` was repeatedly misread as
`join(" ")` — it was already joining on a NUL. Both used the `\u0000` escape by the end.
**All three files are deleted** (slice 1.3 / 1.2); the lesson survives them, and
`sweepRecency.ts` — which still had one — is gone too.

**Corpus census, 2026-08-09** (read-only walk of all 68 channel dirs, 20 s):

| measure | value |
| --- | --- |
| video dirs / `eligible` for digest | 78,963 / 78,885 (so exactly **78** untranscribable) |
| `blocked` (no transcript) | **1,631** |
| `deferred` (no current `cues.json`) | **1,933**, of which `piratesoftware` alone is **1,683** — see the correction below: these are overwhelmingly MISSING, not stale |
| new reachable | **75,199** |
| old `noDigest` (54 channels that have the bucket) | 75,613 |
| `present` (digested at the current identity) | 122 |
| snapshots with a `backfill` block | 44 of 66 — **SUPERSEDED 2026-08-26: 68 of 68**, see the step-1 section at the end of this file |
| channels predating the `noDigest` bucket | 11 (~1,516 videos) |

**CORRECTED 2026-08-10 — `deferred` was NEVER mostly "stale cues.json".** A per-video walk of
all 79,219 dirs split the bucket by reason for the first time:

| reason | videos |
| --- | --- |
| **no `transcript.cues.json` at all** | **1,942** (`piratesoftware` 1,683 · `jfg-tonight` 151 · `angryjoeshow` 44 · `destiny` 30 · `omnibased` 14 · `jeremy-hambly` 8 · `the-quartering` 6 · `elissa-clips` 4 · 2 more) |
| genuinely superseded (stale) | **47**, all `shondo-vods` |

So the superseded case the branch was written for is **2.4%** of what it caught, and the claim
that it "resolves itself" was false: `transcribeOne.ts:238` is the ONLY automatic caller of
`normalizeTranscript`, and a `handling: "youtube"` channel downloads subtitles with
`--skip-download` (`downloadOneManaged.ts:133-146`) so it never runs. It went unseen because
`buildIndex.ts:636-679` treats `cues.json` as a CACHE and silently re-parses the raw VTT — the
published site is correct, and only the digest lane, which has no fallback, can see it.

**RESOLVED the same day.** `normalizeChannelTranscripts` was added and run over the 11 affected
channels: **1,991 sidecars written, 0 failures**, ~1.9 min total (57 s of it `piratesoftware`).
Re-measured with the REAL `digest.state()` over the whole corpus afterwards:

| measure | before | after |
| --- | --- | --- |
| digest `reachable` | 75,406 (live post-regen) | **77,392** |
| `deferred` | 1,987 | **1** |
| `blocked` | 1,626 | **1,626** (unchanged — correctly) |
| `present` / `not-applicable` | — | 122 / 78 |
| `piratesoftware` reachable | ~114 | **1,797** (of 1,801; 4 blocked) |

The single remaining `deferred` is a live-corpus artifact (a transcript rewritten mid-run).
A related one in `nerdrotic-live` has no `metadata.info.json` at all and so reports `no-meta` —
normalize cannot fix that one, and reporting it honestly is why `isCuesJsonFresh` now returns a
`reason` (`missing` / `stale` / `no-raw` / `no-meta`) alongside `fresh`.

**NOT a separate bug: `omnimirror`'s 712.** Checked because it is `handling: "transcribe"`, so
`--skip-download` could not explain it. All 712 have `audio.mp3`, `metadata.info.json` and NO
transcript of any kind — downloaded, never transcribed. They classify `blocked` correctly and
normalizing would do nothing. Same for `RagingGoldenEagle` (659). The earlier per-channel list
had conflated untranscribed dirs with unnormalized ones.

**The plan predicted the count would RISE by ~1,530; it FALLS by 414.** `deferred` was
underestimated. `digest.state()` costs **0.34 ms/video** (125-video channel) to **0.38
ms/video** (773-video channel), i.e. 0.7x–1.2x the `readVideoFiles` the snapshot already pays.

**`scripts/diarize-sherpa.py` already emitted per-window progress and nothing read it**
(`window {i}/{n} ... in {elapsed}s`, plus a plan line `-> N window(s)`). A `backfill` task was
given `createDownloadProgressParser()` by `common/jobs/taskHooks.ts`, which matches none of
it. The zero-samples line prints a BARE index (`window 2 decoded zero samples`) with no `/N`,
so it correctly matches nothing.

## Verified 2026-08-24 — the arbiter, the band, the workers

Facts a cold agent would re-derive expensively, from the 08-19 → 08-24 commits that landed
with no STATE.md entry. Commit bodies (`git log -1 --format=%b`) carry the measurements.

**`band.ts` must carry no directive and no value import** (`editor/app/components/pipelines/buildBands.test.ts:333` pins both). `FlowStation`
is a server component and CALLS `bandSentence()`; a `"use client"` on the module makes every
channel page 500 at request time — and `pnpm build` passes, because the route is force-dynamic
and nothing prerenders it. `StateBand.tsx` exports only components for the same reason.

**The auto-queue claim key is `${operation}\0${id}`** (`common/jobs/autoQueuePolicy.ts:366`). The same video is
legitimately pending for digest AND diarization; an id-keyed set lets whichever leaf runs first
steal the other's work. Every pre-existing tree names no operation, so its keys are `"\0"+id`
and the dedup is byte-identical to before.

**RETIRED 2026-09-07 (slice 1.3): the arbiter and both sweeps are deleted.** What the two
entries that stood here said is preserved because the reasoning outlived the code. The arbiter
ran on `queueKey: ""` — a long-lived job that WAITS on jobs needing the real keys must not hold
one or it deadlocks against its own work; `controller/autoRunner.ts` runs on the same empty key
for the same reason. It refused to start beside an armed sweep, because two dispatchers on one
lane start the same channel twice; there is one dispatcher per lane now and that rule
(`laneBlockedReason`) is gone with the flag it read. `SweepKindCounts` (`lib/sweepPlan.ts`)
carried five populations that are never summed — `reachable`, `missingInput`, `blocked`,
`deferred`, plus `eligible` / `present` as `number | null`, because a partial denominator
smaller than its numerator is a worse lie than "unknowable". That type is gone; **the rule
survives on `OperationBand`** (`editor/app/components/pipelines/band.ts:27`), which the rail
draws. Reachable and needs-media still differ by ~91× on this corpus.

**Run `tsc` per package before calling a session green.** The lesson that used to be attached
to `sweepPreview.test.ts`: three fixtures there kept the old four fields after `dee7500`
widened the type, `tsc` failed on `main`, and `node --test` stayed 821/821 — the test runner
does not typecheck.

**Worker tags route work through one rule** (`common/lib/workers.ts:136`): untagged matches everything, tagged
matches on intersection, a requirement lists acceptable qualifications. The pool's
`eligible / pickFree / hasEligibleWorker` and the sweep console's "also runs on …" line both go
through it, so display and routing cannot disagree. An `llm` worker never matches a
requirement-less lease, so transcription can never land on a bare `ollama serve`.

**`/api/worker/unit` refuses anything that is not a backfill kind** (`common/controller/workerServer.ts:232`, `editor/app/api/worker/unit/route.ts:41`) —
download politeness and the transcription pool stay single-scheduler. A unit's `inputs` are
ordered with `transcript.cues.json` LAST so the executor's scratch materialization passes the
`isCuesJsonFresh` mtime gate. `applyResult` runs on the PRIMARY through the guarded writers;
only `diarization.json` is copied verbatim.

**A directory name is not a metadata id on ~14.5% of this corpus** (recency, `efea56f`):
`the-quartering-rumble/data/v1007ay` holds `vxe1ae`. Every scheduling path hands
`buildRecencyKeys` DIRECTORY names, and the transcript index is keyed by `summary.id`, so a
corpus-wide flat map lets channel A's dir name inherit channel B's date. The lookup is scoped
through `datesBySlug` when `owner` is supplied; every scheduling path supplies it. (Same trap
already recorded for `community-notes/v2fkbw7` → `v2cywen` under Phase 2.)

**`editor`'s `lint` script has no config** — `eslint` v9 finds no `eslint.config.*` in
`editor/` or the root; the root `lint` delegates to `export`. `tsc` + e2e are the editor's
verification, not lint.

## Verified 2026-08-26 — editor IA slice 2, the operation runner and the lane resolver

Facts a cold agent would otherwise re-derive from the slice-2 commits (`1da6f22` → `1058b98`).
Commit bodies carry the reasoning.

**`Operation.laneFor?` is OPTIONAL AND ITS PRESENCE IS NO LONGER SIGNIFICANT** — CHANGED
2026-09-07, phase 1 slice 1.2 (`common/lib/operations.ts`). It used to be:
`common/controller/backfillBatch.ts` keyed the GPU idle-only rule off `k.laneFor &&`, i.e. off
the field EXISTING, as the marker for "this kind's scarce resource depends on settings, so
nothing else is deciding it" — which made "give every kind a `laneFor` defaulting to `lane`" a
behaviour change wearing a refactor's clothes.

`common/controller/operationBatch.ts` (which replaced both batch files) asks the DECLARATION
instead: `laneYieldsToTranscription(laneForOperation(op.id) ?? op.lane)`, keyed on
`contendsFor`. So a kind with a FIXED GPU lane and no `laneFor` is now caught (it was not
before), and adding a `laneFor` for any other reason changes nothing. Behaviour on today's
registry is identical — no BACKFILL_QUEUE operation declares a static GPU lane
(`operations.ts` has diarization `cpu` with a `laneFor`, both attribution ops `network`).
`common/controller/operationBatch.test.ts` ("the GPU carve-out is keyed on contendsFor, not on
laneFor existing") pins the new rule.

**Digest declaring a `laneFor` still does not put it in that guard**, and never did because of
the guard: `operationsForLane("backfill")` admits BACKFILL_QUEUE only, so digest can never
reach the backfill run's operation array even when asked for by name. `operations.test.ts`
pins it.

**`laneForOperation` lives in `common/controller/operationLane.ts`**, alone, because it started
as the arbiter's: the arbiter planned units against it and `operationJobs.ts` reserves a queue
key with it, while the arbiter called `operationJobs`. In `arbiter.ts` that was an import
cycle. The arbiter retired in slice 1.3; the module stays where it is.

It asks `getBackfillKind`, **NOT `operationCatalog()`**, and that is load-bearing:
`getBackfillKind("download")` is `undefined`, so download and transcription get no lane. A
catalog lookup would hand them one, and a caller would reserve the backfill queue for work no
backfill operation can do.

It also **does not consult `enabled`** and never has. A switched-off kind still resolves a lane;
what keeps it out of dispatch is `operationsForLane`, which projects only the operations
`allOperations` returns — so it arrives with an empty id list. Teaching the resolver to return null would look like a tightening and would be a
second, redundant gate that label-only callers would read as "no lane at all".
`common/controller/laneForOperation.test.ts` pins the boundary.

**`common/controller/operationJobs.ts` is the ONE per-channel runner path** — a hand-clicked run
and a group-button one are the same function (a swept one and an arbiter-dispatched one were
too, until both dispatchers retired in slice 1.3). `runBackfillChannelJob`,
`runDigestChannelJob`, and `runOperationChannelJob(operation, …)` over both. Since slice 1.2
all three drive `controller/operationBatch.ts`, which is also what the auto-queue runner's
digest and backfill lanes dispatch through — one executor, two callers.

**They do NOT drain.** They return the `StreamActionResult` and a caller that wants sequencing
`await drainStream(result.stream)`s itself. A runner that drained would consume the stream the editor's `StreamActionLog`
renders as a live log, and every stage card's log would come up dead. This is the single most
likely thing to be "fixed" back.

**`onDone?: () => void` exists because `common/` cannot import `next/cache`.** The editor's
server actions pass `() => revalidatePath(...)`; the runner calls it at job end.

**`GROUP_STAGES`** (`editor/app/channels/[slug]/lib/stageStatus.ts`) is an exhaustive
`Record<OperationGroup, readonly StageId[]>` spread in `OPERATION_GROUP_ORDER` to build the
channel page's stage list. NOT 1:1 with groups — `media` owns `download` AND `transcode` — which
is why it is a Record of arrays. It covers only the MIDDLE: configure/playlist and
cleanup/diagnostics/danger are channel chores, not operations, and stay hand-listed. `tsc`
checks membership; `stageOrder.test.ts` pins order and cardinality, which it does not.

**`StageId` "backfill" is now "speakers"**, together with `FlowStationId`. `?stage=backfill`
still resolves, via `STAGE_ALIASES` in `page.tsx` — an unknown `?stage=` falls back to the
overview at 200, which is right for a retired stage and wrong for a renamed one. Four id spaces
still spell "backfill" and each was decided, not missed: `StationId` (group buttons) and the
`/actionable` section id wait for the vocabulary pass and slice 4; the widget's `SectionId` is
persisted in user URLs and never changes; `snapshot.backfill` and `BACKFILL_QUEUE` are keyed by
kind id / are a scheduler key and are correctly named.

**The stage card's POPULATION aria-labels still say "backfill"** (`backfill reachable`,
`backfill kind …`, `backfill blocked/deferred/needs re-acquiring`, `videos needing a backfill …`)
— 16 spec lines, deferred to the vocabulary pass. Only the wrapper became `speakers section`.

**`ExternalOperation.runner?: AutoQueueKind`** names the auto-queue runner that dispatches an
operation. `dispatch` cannot answer it: download and transcription are `external` WITH a runner,
a future `transcode` would be `external` with none. **Since slice 1.2 `/operations/<id>` chooses
its console off `pauseLaneFor(op.id)`, not off `runner`** — `runner` is `undefined` for every
registry operation, so reading it would leave the digest and backfill lanes without one — and
`pauseLaneFor` asks `runner` FIRST, so an external entry sharing a queue with no runner of its
own still gets `null`. Null renders a "no console here" panel; an id-shaped predecessor would
have rendered the backfill lane's console — with a live Start button — under a `transcode`
heading. (`sweepLaneIdFor` did this job for the sweep panel and is deleted with it.)

## Verified 2026-08-26 — the vocabulary pass (`BackfillKind` → `Operation`)

**Names in every section above this one are PRE-RENAME.** Three commits after `e0703b4`
renamed the registry and the id spaces slice 2 handed forward. Grep the mapping below when
an older section (or a commit body) names something that no longer exists.

**The rule that decided every rename:** "backfill" survives where it names the QUEUE/LANE
and its persisted contracts; it goes where it named the KIND concept. The backfill lane
(`BACKFILL_QUEUE`) is one queue several operations share — one pause, one sweep, one share —
and is the only thing `common/lib/operations.ts` still calls "backfill".

| Old | New |
| --- | --- |
| `common/lib/backfillKinds.ts` (+ `.test.ts`, `backfillUnit.test.ts`) | `common/lib/operations.ts` (+ `operations.test.ts`, `operationUnit.test.ts`) |
| `BackfillKind` | `Operation` |
| `BackfillLane` | `Lane` (generic `{queueKey, contendsFor}`) |
| `BackfillState` / `BackfillClassification` | `OperationState` / `OperationClassification` |
| `BackfillCostTier` | `OperationTier` (`"inline" \| "lane"` — a tier, not a cost) |
| `BackfillDispatch` / `BackfillProbe` | `OperationDispatch` / `OperationProbe` (the VALUE `"backfill"` survives — it names the machinery) |
| `BackfillRunOptions` / `BackfillRunOutcome` / `BackfillTargetContext` | `OperationRunOptions` / `OperationRunOutcome` / `OperationTargetContext` |
| `BACKFILL_KINDS` / `BACKFILL_KIND_BY_ID` | `OPERATIONS` / `OPERATION_BY_ID` |
| `getBackfillKind` / `allBackfillKinds` | `getOperation` / `allOperations` |
| `laneBackfillKinds` | `backfillLaneOperations` — LANE-scoped (filters `queueKey === BACKFILL_QUEUE`), so the lane word stays and moves first |
| `laneEntriesOf` / `laneKindEntriesOf` | `backfillLaneEntriesOf` / `backfillLaneOperationEntriesOf` — once `Lane` is generic, "entries of WHICH lane" has to be said |
| `resolveBackfillKinds` | `resolveBackfillLaneOperations` — resolves ids WITHIN the backfill lane |
| `BackfillCounts` / `emptyBackfillCounts` | `OperationCounts` / `emptyOperationCounts` |
| `addBackfillState` / `reachableBackfillWork` / `presentBackfillWork` | `addOperationState` / `reachableOperationWork` / `presentOperationWork` |
| `BackfillSnapshotEntry` | `OperationSnapshotEntry` (the VALUE type of `snapshot.backfill[id]`; the on-disk KEY does not move) |
| `DIGEST_KIND_ID` / `DIARIZATION_KIND_ID` | `DIGEST_OPERATION_ID` / `DIARIZATION_OPERATION_ID` |
| `StationId "backfill"` (`/channels` group line) | `"speakers"`; the station's label is `ChannelGroupSection.speakersLabel`, derived like the stage title ("Derived data" under default settings) |
| `/actionable` section id `"backfill"`, `countLabel "to backfill"` | `"speakers"`, `"reachable"` |
| `BackfillStage.tsx` / `BackfillKindView` / prop `kinds` | `SpeakersStage.tsx` / `OperationRowView` / `operations` |
| aria `backfill kind <id>` / `backfill reachable\|blocked\|deferred\|needs re-acquiring` | `speakers operation <id>` / `speakers reachable\|…` |
| aria `videos needing a backfill list\|empty`, `video needing a backfill <id>` | `videos needing speaker work list\|empty`, `video needing speaker work <id>` |
| `backfillChannelGroupAction` | `speakersChannelGroupAction` (still runs `backfillChannelAction`, the LANE runner) |
| `editor/app/jobs/components/PauseBackfillButton.tsx` | deleted — zero importers since `LaneDeck` absorbed it |

**Deliberately still "backfill", each a decision:** `BACKFILL_QUEUE`; job kinds
`backfill-channel` / `backfill-sweep`; `JobTaskKind "backfill"` (persisted on job records);
`settings.backfill.*`, `BackfillSettings`, `sanitizeBackfill`, `defaultBackfill`;
`snapshot.backfill` (on-disk key); `spec.params.kindIds` and `settings.backfill.sweepKinds`
(persisted — `jobReplayRegistry` reads `p.kindIds`); the lane runners `backfillSweep.ts`,
`backfillBatch.ts`, `backfillReacquire.ts`, `backfillAvailability.ts`, `diarize-backfill.ts`;
`backfillActions.ts` / `backfillChannelAction` / `runBackfillChannelJob` (run the LANE over
one channel); `start|stopBackfillSweepAction`, the
`/api/test/resume-backfill-sweep` route (`pause|resumeBackfillAction` were listed here too —
**deleted by slice 7**, which replaced all eight pause actions with one lane-keyed pair); `SweepLaneId "backfill"` and `data-lane="backfill"`;
the aria-labels `pause backfill` / `resume backfill` / `start|stop backfill sweep` (they act on
the lane); the widget's `SectionId "backfill"` (serialized as `?backfill=1` / layout code `bf`
— permanent); `SweepKindCounts` and every other `*Kind*` outside the registry's export table
("one registry entry", still true). `SettingsForm.tsx`'s "Run the backfill lane" fieldset
waits for slice 3, which moves it.

**"unit" has ONE meaning** (written beside `costBasis` in `operations.ts`): a UNIT is one item
of dispatchable work — `ArbiterUnit`, `startWorkerUnit`, `runUnitViaRemote`,
`/api/worker/unit`, job kinds `worker-unit` / `auto-download-unit` — and three of those are
persisted contracts, so the dispatch side keeps the word. What one video of an operation
costs is its COST BASIS (`costBasis`), and no surface calls that a unit: the `Figure({unit})`
prop in `OperationRail.tsx` / `SweepLane.tsx` was a population label and is `population`;
prose saying "unit" for cost says "cost basis". `DurationUnit` is a third, unrelated meaning.

**SUPERSEDED 2026-08-30 — removed, see the section at the end of this file.**

**`transcode` is registered** (`EXTERNAL_OPERATIONS`, after `download`): group `media`,
`lane: { queueKey: TRANSCRIPTION_QUEUE, contendsFor: "cpu" }`, `dependsOn: ["download"]`,
`dispatch: "external"`, no `runner`, and the first `appliesTo(config)` —
`handling === "transcribe" && !!audioFormat`, exposed as `operationApplies(id, config)` and
replacing the three verbatim copies of that gate (`channels/[slug]/page.tsx`,
`channels/[slug]/videos/page.tsx`, `stageStatus.ts`). `/operations/transcode` renders slice
2's no-console panel. **The transcode BAND is not registered and cannot be yet**:
`buildOperationBands` is snapshot-only and pure (`noCorpusWalkInRenderPaths`), `ChannelSnapshot`
carries no `handling`/`audioFormat`, so `eligible`/`present` for a channel that never
transcodes is indistinguishable from one that has finished. The honest route is the snapshot
writer recording a transcode population — a snapshot-shape change filed with unified-ops
step 1. `EXTERNAL_BAND_IDS` stays two. Side effect accepted: `settings/page.tsx` offers every
catalog id as a worker tag, so "transcode" is offerable beside "download".

**Grep gates used, over `common/ editor/` `*.ts *.tsx`:** must be 0 — `\bBackfillKind\b`,
`backfillKinds`, `getBackfillKind`, `BACKFILL_KINDS`, `\bBackfillLane\b`, `_KIND_ID\b`,
`BackfillStage`, `PauseBackfillButton`; must be unchanged — `BACKFILL_QUEUE` 42 (+1 comment in
the new header), `"backfill-channel"` 14, `"backfill-sweep"` 9, `settings.backfill` 40 (+1
comment), `kindIds` 58, `sweepKinds` 24, `"worker-unit"` 1, `"auto-download-unit"` 4, and
every `backfill` under `editor/app/widget/` (34).

## Verified 2026-08-26 — slice 3 seams (per-operation settings)

Census taken before writing `editor-ia-slice-3.md`, so its plan rests on line numbers
checked at `32950aa`. Everything here is read-only observation; nothing was changed.

**`SettingsForm.tsx` (1,163 lines) is eight `<fieldset>`s**, and the four slice 3 moves are
contiguous: Digest `:526-707`, Diarization `:708-888`, Speaker work lane `:889-981`, Speaker
attribution `:982-1087` — **562 lines**. The other four stay on `/settings`: Transcription
workers `:82-104`, Sync scheduler `:328-478`, Build pipeline `:479-525`, Social links
`:1088-1099`. The file is `"use client"`, one `useActionState(saveSettingsAction)`, one
"Save settings" button (`:1105`) and one `role="status"` (`:1109`). Its `Field` helper is
file-local (`:1128`), not exported. The Digest and Attribution fieldsets read the
`digestApps: DigestAppDescriptor[]` prop (`:551,650,683,1061`), built on the server in
`settings/page.tsx` because `digestApps.ts` reaches `process.env` and imports execa.

**`settings/actions.ts` (506 lines) already has the four blocks marked**: Digest `:264-343`,
Diarization `:344-393`, Backfill lane `:394-411`, Speaker attribution `:412-448`; the `next`
object is assembled at `:449` and the four blocks land on it at `:491-494`. Each block is
gated on a hidden `<input name="*FormPresent" value="1">` — `digestFormPresent :289`,
`diarizationFormPresent :351`, `backfillFormPresent :401`, `attributionFormPresent :417` —
whose ONLY reason to exist is that one form saves everything: an unchecked checkbox is absent
from a FormData, so a submit from a form without the block would read every switch as off.
The comments name what each marker guards: an armed digest sweep, the diarization capture
lane (whose loss lets Clean-audio delete held audio), `allowRedownload` + the backfill sweep
flag/scope, and `textOnlyEnabled` (~194,000 calls). **Once each block has its own form and
action, every marker is dead**, and the `...current` spread each block already does becomes
the whole isolation story. Sanitizers are already per-block in `common/lib/settings.ts`:
`sanitizeDigest :937`, `sanitizeBackfill :1111`, `sanitizeAttribution :1149`,
`sanitizeDiarization :1211` (types at `:447/:289/:243/:342`, defaults at
`:869/:1094/:1137/:1174`). `writeSettings` re-sanitizes every block regardless (`:1679`).

**The lane fieldset is not per-operation.** "Speaker work lane" (`enabled`, `weight`,
`concurrency`, `allowRedownload`) governs `BACKFILL_QUEUE`, which diarization,
`attribution-text` and `attribution-diarized` share; its own comment (`:890-894`) says it is
"THE ONE FIELDSET THAT STILL SAYS LANE, and it is the right one". So it cannot go on any one
`/operations/<id>` as that operation's settings. Where the lane IS drawn: `SweepLane.tsx` is
rendered from exactly one place, `OperationDetail.tsx:167` inside `SweepOperationView`
(`:104-169`) — i.e. on every member page of a sweep lane and NOT on the `/operations` board
(`OperationsBoard` draws the rail; `LaneHeader.tsx` is the RUNNER lanes' header for
download/transcription, nothing to do with the backfill lane). `SweepOperationView` already
carries `data-lane={laneId}` "deliberately the SAME value on every speaker operation's page,
since they are one lane", the shared pause and the shared sweep. A lane-settings form beside
`SweepLane` there is one definition rendered on three pages, matching how the pause already
appears. Digest's lane has one member, so its lane facts (`sweepEnabled`, order/reach) are
already in the Digest block.

**How e2e sets these blocks:** `backfill.spec.ts` (17 calls), `attribution.spec.ts` (4) and
`worker-unit.spec.ts:113` all go through `writeSettings()` in `e2e/helpers.ts:66`, which
writes `test-settings.json` directly — they never drive the `/settings` form for these
fields. The only specs that DO drive the form for the moving blocks are three in
`settings.spec.ts`: `:179` "digest settings round-trip through the form" (`/settings`,
`getByRole("group", { name: "Digest" })`, `Timestamp mode`, `prompt variant label`,
`spend cap`, `long-tail cutoff`, `enable the metered`, `Context window (num_ctx) for
ollama-direct`, then "Save settings" + status "Saved"); `:221` "an unrelated settings save
does not reset the digest prompt shape" (sets digest fields, reloads, saves `admin title`,
reads `test-settings.json`); `:265` "the sortformer engine settings round-trip" (targets
`select[name="diarizationEngine"]` / `diarizationBackend` BY NAME because `getByLabel`
substring-matches, plus `Sortformer engine binary`, `Sortformer model (GGUF)`). The
attribution and lane fieldsets have **no form-driving spec at all**.

**Copy that will point at the wrong page once the switches move.** Each says "in Settings"
about a switch slice 3 relocates: `operations/components/OperationDetail.tsx:150` ("switched
off in Settings, so nothing dispatches it"), `operations/components/SweepLane.tsx:218` ("turn
one on in Settings"), `channels/[slug]/components/stages/SpeakersStage.tsx:144` ("Turn an
operation on in Settings"), `channels/components/ChannelGroupLine.tsx:184` (lane "switched off
in Settings" title), `channels/groupActions.ts:108` (skip reason), `stages/DigestStage.tsx:210`
and `videos/[id]/components/DigestPanel.tsx:144` ("metered — disabled in Settings"). *(Both
were fixed by slice 3; the digest one now reads "metered — disabled on the Digest page" and,
since slice 6, lives in `videos/[id]/components/DigestBody.tsx`. The group skip reason is
now "the lane is switched off on its operation page", at `groupActions.ts:186` on `e172749b`.)* The
disk-floor sentences ("lower the floor in Settings", four sites) stay true — the floor is not
moving. `ChannelForm.tsx:812`, `scheduler/*`, `workers/*` link to `/settings` for blocks that
stay.

**`SettingsForm` has no per-fieldset test ids** — the digest spec scopes with
`getByRole("group", { name: "Digest" })`, i.e. the `<legend>` text is the accessible name.
Keeping the legends verbatim on the new pages keeps that selector valid after only the
`goto` changes.

### As shipped (`f14ceb5`, `43bb519`)

The census above is now history — here is what replaced it, so the line numbers do not send
the next reader to the wrong file.

- **`Operation.settingsBlock`** (`common/lib/operations.ts`), a closed union
  `OperationSettingsBlock = "digest" | "diarization" | "attribution"`, copied through to
  `OperationDescriptor` in `operationCatalog()`. Set on `digest`, `diarization` and BOTH
  attribution entries (one block, one form, two pages). `settings.backfill` is deliberately
  NOT named here — it is the lane's, not an operation's.
- **The four forms** are `editor/app/operations/components/settings/{Digest,Diarization,
  Lane,Attribution}SettingsForm.tsx`, each `"use client"`, each a `<form
  data-settings-block="…">` with its own `useActionState`. `DigestAppsField.tsx` moved into
  that directory with them. `Field` is `editor/app/components/forms/Field.tsx` (exported; the
  three other file-local copies are explicitly out of scope and the file says so).
- **The four actions** are `editor/app/operations/settingsActions.ts`
  (`saveDigestSettingsAction`, `saveDiarizationSettingsAction`,
  `saveBackfillLaneSettingsAction`, `saveAttributionSettingsAction`), each the old block
  verbatim minus its marker; `num()` is module-level there now. `revalidateOperations()` is
  duplicated rather than imported — a `"use server"` module may only export async functions.
- **THE `*FormPresent` MARKERS ARE GONE**, all four, and nothing emits or reads one. That was
  the point of the split: the isolation is now structural (a form cannot submit a block it
  does not render), not a hidden input. `saveSettingsAction` carries the four blocks as
  `getSettings().<block>`.
- **Which form a page draws** is `settingsFormFor(op.settingsBlock, …)` in
  `operations/[id]/page.tsx` — an exhaustive switch over the union, never over the id. The
  LANE form is `laneId === "backfill" ? <LaneSettingsForm …> : null`, passed to
  `OperationDetail` as a second slot (`operationSettings`, `laneSettings`) and rendered by
  `SweepOperationView` after `<SweepLane>`, INSIDE `section[data-lane]` so every existing
  scoped selector still reaches the lane's controls.
- **The `role="status"` boundary.** `SaveBar.tsx`'s "the ONLY role=status on this page" means
  RUNNER pages — `auto-subs-replace.spec.ts:415` asserts `getByRole("status").first()` on
  `/operations/transcription`. Sweep-fed pages now carry settings forms with their own status
  regions; they have no policy tree, so the two never meet. The comment now says this, and
  the settings specs scope by `form[data-settings-block]` rather than by role.
- **Specs**: `editor/e2e/operation-settings.spec.ts` (7 tests) holds the three that moved out
  of `settings.spec.ts` plus four new ones — attribution and the lane had no form-driving
  spec at all before. `settings.spec.ts` is 168 lines and still has exactly one `<form>` on
  the page, so its `page.locator("form")` selectors stay unambiguous.

---

## Verified 2026-08-26 — unified-ops step 1 (`buckets.noDigest` deleted)

Measured read-only over `transcripts/channels/*/snapshot.json` with `node -e`, no editor
booted, nothing written under `transcripts/`.

**The migration the fallback existed for was already over.**

| measure | value |
| --- | --- |
| snapshots on disk | **68** |
| carrying `backfill.digest` | **68 of 68** (and all 68 carry a numeric `eligible`) |
| `generatedAt` range | 2026-08-11T22:18Z → 2026-08-26T20:39Z |
| Σ `buckets.noDigest` | **59,159** |
| Σ `backfill.digest.ids` | **47,382** |
| Σ `backfill.digest.deferred` | **16,156** |
| Σ `backfill.digest.blocked` | **1,685** |
| Σ `backfill.digest.partial` | **0** |

So the `source: "bucket"` branch in `digestWorkOf()` was dead against production, and no
rendered number moved when it was deleted. **This supersedes "snapshots with a `backfill`
block | 44 of 66"** in the 2026-08-09 table above, and STATE.md's "STEP 4 IS NOT DONE AND
CANNOT BE DONE FROM HERE" (dated note added there): the live editor was restarted on the new
build some time after 08-10 and the snapshot scheduler regenerated the rest.

**The two counters disagreed by 11,777 videos and could not be reconciled.** On 65 of 68
channels `noDigest − digest.ids` is EXACTLY `deferred` — the registry gates on a current
`cues.json`, the bucket did not. The three exceptions are videos with a fresh digest but no
current `cues.json`, which the registry calls `deferred` and the bucket called done:

| channel | `noDigest − ids` | `deferred` |
| --- | --- | --- |
| `HasanAbiVODs3` | 260 | 348 |
| `chibi-reviews` | 34 | 2,699 |
| `destiny` | 2,243 | 3,869 |

The bucket also had no transcript gate (it silently omitted untranscribed videos — the
regression `stageStatus.ts` records as "how a channel of untranscribed videos read as fully
digested") and no `partial`.

**What each surface reads now** — all of them already did, through `digestWorkOf`, which is
now a pure read of `snapshot.backfill.digest`:

- dashboard / `NeedsWorkPanel` / `ChannelsTable` — `actionableNoDigestCount`
  (`editor/app/actionable/lib/loadActionable.ts`), `.reachable`.
- `/api/widget/sync` — `eligible − blocked` summed corpus-wide, `blocked` and `deferred`
  reported separately, all `number | null`.
- `/api/widget/actionable` — reports `noDigest` (the wire field name is unchanged) and still
  REFUSES to filter on it: during the backfill it is ~99.87% of the corpus.
- the channel station (`channelFlow.ts`), the Digest stage card (`stageStatus.ts`,
  `[slug]/page.tsx`), the `/channels` digest column (`channelGroupSections.ts`), the
  pipelines bands (`components/pipelines/buildBands.ts`).

**`DigestWork` no longer has `source`.** Its shape is `ids / reachable / blocked / deferred /
partial / present / eligible`; the no-entry return is `present: null, eligible: null` and
everything else 0/[] — "unknown, not zero coverage", which
`editor/app/api/widget/sync/route.ts` builds its null rule on. A snapshot with no entry is now
a channel whose FIRST snapshot has not been written, not an old generation of one.

**Four "digest is special" branches deleted**, each of which existed only to cover a snapshot
with no entry: `components/pipelines/buildBands.ts`, `controller/sweepPreview.ts`
(`reachableIdsFor` and `countsFor`), `controller/sweepRecency.ts`. Digest is now a plain
registry entry to every reader, exactly as diarization is: no entry → no work known, coverage
unknown. `digestWorkOf` has **no callers in `common/`** and stays in `channelSnapshot.ts` as
the editor's adapter.

**No snapshot schema version exists**, and none was added: per-field optionality is the
convention (`presentOperationWork` returning `null` for a snapshot predating `eligible` is the
precedent). `normalizeBuckets` picks only the keys it knows, so an old snapshot's stray
`noDigest` key is ignored until its next routine regen. No regeneration was run and no regen
tooling was written: an offline writer would race the live editor's `snapshotScheduler` on the
same files.

**An operator finding, not fixed here: corpus-wide `deferred` is 16,156.** It was measured at
**1** on 2026-08-10, right after the normalize pass ("Phase D step 1" above: 1,987 → 1). The
largest holders are `destiny` 3,869, `the-quartering` 3,762, `chibi-reviews` 2,699,
`nux-taku` 1,802, `leaflit` 1,612, `kirsche` 1,197. Either new `handling: "youtube"`
downloads have accumulated with no `cues.json` (nothing automatic runs `normalizeTranscript`
for a subtitle-downloading channel) or the cues gate regressed. It is exactly what the Digest
card's **Normalize transcripts** button exists for, and it was invisible to a reader of the
old bucket.

---

## Verified 2026-08-27 — why `deferred` was 16,156

The 08-26 finding ("either accumulation or a regression") was **neither**. It was a single
sweep, in code, on a defect that is now fixed (`fed4b01`, `ca42f7b`).

### The census

Run read-only with the real `isCuesJsonFresh` over all **78,128** transcribed video dirs:

| reason | count |
|---|---|
| `stale` (cues.json older than its inputs) | **16,081** |
| `missing` (no cues.json at all) | 75 |
| `no-meta` | 1 |

16,081 + 75 = 16,156, which is the corpus-wide digest `deferred`. Of the stale ones, **7,849**
also had a re-fetched VTT and **8,231** were metadata-only rewrites. They sit on eight
`handling: "youtube"` channels, written in contiguous serial blocks **2026-08-22 → 08-26**:

| channel | stale |
|---|---|
| destiny | 3,869 |
| the-quartering | 3,762 |
| chibi-reviews | 2,699 |
| nux-taku | 1,802 |
| leaflit | 1,612 |
| kirsche | 1,197 |
| quartering-live | 805 |
| HasanAbiVODs3 | 348 |

Per channel, redownloads ≈ deferred ≈ a slice of that channel's `missingInput` population —
the signature of one ordered walk, not of accumulation. Each dir's `download-outcome.json`
records a `metadata-prefetch` + `primary` attempt with `handling: "youtube"`.

### The mechanism, with the trail

`settings.json` had `backfill.reach: corpus`, `order: newest`, `allowRedownload: true` and
diarization enabled.

1. Every video on a subtitle-downloading channel is diarization **`missing-input`** — no
   audio, by design of that handling (`common/lib/operations.ts`, the `hasDiarizableInput`
   branch of the diarization `state()`).
2. `allowRedownload` turns `missing-input` into a **dispatch** (`backfillBatch.ts:194-196`).
3. `reacquireMediaFor` called `downloadOneManaged` with the channel's **unmodified** config
   (`backfillReacquire.ts:116-133` before the fix — there was no `handling` check anywhere in
   the file), so yt-dlp ran `--skip-download --write-subs --write-auto-subs`.
4. That rewrote `metadata.info.json` (and a VTT where YouTube served one), landed no audio,
   logged "nothing usable landed", and moved to the next video at ~12/min.
5. `isCuesJsonFresh` compares `transcript.cues.json`'s mtime against metadata and the raw
   transcript (`normalizeTranscript.ts:243`), so every touched video went stale — which reads
   `deferred` to the digest lane and `no-transcript` → `skipped` to attribution
   (`attributeOne.ts:139`, `operations.ts:983`).

~16,000 wasted fetches (with firefox cookies), zero diarizations.

### The content is fine

230 of 240 sampled re-fetched VTTs parse to **byte-identical** cues; the 10 that differ do so
by a few cues of YouTube ASR drift. The 8,231 metadata-only cases never touched the transcript
at all. So the 16,081 are an **mtime false positive**, and one Normalize pass clears them.

### Why re-normalizing is safe

`isSectionFresh` (`digest.ts:513-534`) is **provenance-keyed** — app / model / prompt /
contextHash — not cues-mtime. Re-normalizing invalidates no digest.

### The exposure, had it been re-armed unfixed

**66,540** `handling: "youtube"` videos are diarization `missingInput` corpus-wide. Next in
`newest` order: chrissie-mayr 3,514, nuxanor 3,211, rev-says-desu 2,770, plus ~7,500
unvisited on the-quartering.

### The two precedents for the override

The fix (`reacquireConfigFor`) is not novel; the same one-video `handling: "transcribe"`
override already existed twice:

- `autoRunner.ts:996-1010` — the `replaceAutoSubs` unit, "the channel's stored config
  untouched".
- `downloadOneManaged.ts:932-950` — its own no-subs fallback, same name, same shape.

And the precedent for re-normalizing right after the thing that changed the inputs is
`transcribeOne.ts:236-243`.

---

## Verified 2026-08-27 — the re-acquire / auto-transcribe hand-off

Read-only against `da339a4`. This section is the trail behind the hand-off shipped in
`e450c2c`; it is also the answer to STATE.md runbook step 4.

### There is no per-video lock anywhere

`common/jobs/registry.ts:78-80` — the registry serializes on `queueKey` alone. Two lanes
holding different queue keys can touch the same video dir at the same moment, and the
backfill (`BACKFILL_QUEUE`) and the transcription runner (`TRANSCRIPTION_QUEUE`) do exactly
that, by design.

### The collision, with the trail

1. `backfillBatch.ts:684-693` — the item's `finally` calls `reacquired.cleanup()`, which
   unlinks the audio the re-acquire just fetched.
2. `channelSnapshot.ts:997` — `downloadedAutoSubsOnly` is `asrVtt && files.audioFiles.length
   > 0`. A re-acquired `audio.mp3` next to YouTube auto-captions puts the video in it.
3. `autoRunner.ts:871` — a snapshot regen is requested on every unit completion, 1 s
   debounce. (The BACKFILL regenerates once, at job end, `operationJobs.ts:138`.)
4. So `autoQueue.transcription` can start on the file between (2) and (1).
5. `scripts/parakeet-stitch.mjs:350` — parakeet re-opens the audio once per 480 s window, so
   the unlink surfaces mid-run as a `sliceWav` failure. whisper.cpp opens once, so a short
   video may survive; parakeet on a long one will not.
6. `transcribeOneFromQueue.ts:164-166` — anything that is not a `TranscribeError` with
   `failureClass === "no-audio"` (`:156-163`) appends the id to `failed-transcriptions`.
7. `whisperBatch.ts:101-107` — the manual per-channel batch honours that list PERMANENTLY.
   The auto runner passes no `failedSet` and would retry.

### Two facts that shaped the fix rather than a lock

- **Nothing automatic deletes audio after a transcription.** `cleanAudioFromTranscribed` is
  a manual channel button (`whisperActions.ts:415`). So audio kept for the runner behaves
  like any other download: `transcribedWithAudio` after transcription, waiting for the
  operator's Clean-audio sweep. The steady-state cost is bounded by the existing UI and the
  disk floor.
- **`replaceAutoSubs: false` is not a refusal.** A leaf whose `match.bucket` is
  `downloadedAutoSubsOnly` draws it regardless (`autoQueuePolicy.ts:147-149, :180-184`). The
  correct question is "does any leaf covering this channel draw that bucket", where a
  bucket-less leaf draws `defaultBucketsForPolicy` — the only place the flag enters. That is
  `policyDrawsBucket`.

### The disk bar is the resume mark, not the floor

`autoRunner.ts:663-668` — the download runner resumes only at `resumeBytes` (floor +
margin). A hand-off is a download the backfill was about to give back, so keeping audio the
runner would have refused to fetch would be incoherent. `decideKeep` calls
`evaluateDiskGate({ ...disk, latched: true }).ok` on the PURE core; `diskGate()` in enforce
mode mutates a shared module latch (`diskSpace.ts:231`) and must never be called from a keep
decision.

### The remote branch wraps ENOENT as "transport"

`remoteTranscribe.ts:111, :126-133`. A vanished-audio check at the local rethrow alone would
still let the remote path blacklist the video, which is why `throwIfAudioVanished` also
wraps `transcribeViaRemote`.

### The `"failed"` cleanup was dead code

`backfillReacquire.ts:196-208` has always returned a real partial-file cleanup for the
`"failed"` outcome, and the batch's `finally` only ever called `cleanup()` for `"fetched"`.
It runs now (`fetched || failed`).

### The sweep has no inter-download sleep, and it is channel-major

`backfillSweep.ts:55, 335-368`. STATE.md's runbook step 3 previously said "sleep 30 s between
downloads → ≥ 23 days"; `sleepBetweenDownloadsSeconds` is the CHANNEL sync path's setting and
the backfill sweep does not consult it. The sweep walks channel by channel, each channel's
candidates in the configured order.

### Follow-up, deliberately not fixed: the digest lane is equally blind

`DigestProvenance` records no transcript source, and `contextHash` is
`hashDigestContext(note)` over the channel's `digest-context.md`
(`digestContext-server.ts:47-60`) — nothing about the transcript. So an ASR→whisper
replacement leaves every digest section looking fresh over rewritten text, exactly as
attribution did before `f661677`. Same field, same record-carries-it rule, ~10 lines. NOT
done here because it would re-queue a local LLM digest for every replaced transcript, which
is a cost decision for the operator, not a correctness one.


## Verified 2026-08-28 — editor IA slice 4 seams

Census taken before writing `editor-ia-slice-4.md`, against `184cb9f`. Read-only observation
at census time; the "As shipped" notes below were added with the docs commit.

**`/actionable` was one 696-line page** (`editor/app/actionable/page.tsx`) rendering ten
`SectionConfig`s from a literal array (`:92-321`) plus two hand-written sections
(`DuplicatesSection :421-475`, `MediaScanSection :356-419`), behind a hand-exhaustive
`nothingPending` gate (`:77-90`) whose own comment said a section missing from it is a
section that never renders.

**The dashboard's digest number was ALREADY the band's `reachable`.**
`actionableNoDigestCount` (`loadActionable.ts:142-144`) returned
`digestWorkOf(row.snapshot).reachable` — the same `reachableOperationWork` that
`buildBands.ts:63` folds. So the IA doc's "drop `noDigest` for band `reachable`" described a
change to a number that was already that number. Readers were `page.tsx:80,92`,
`NeedsWorkPanel.tsx:74-79`, `dashboard/ChannelsTable.tsx:69`, `dashboard/types.ts:21`,
`api/widget/actionable/route.ts:24,42`. **`MonitorWidget` never read it** (`ActionableStrip`
reads slug / undownloaded / untranscribed; `LaneDeck.tsx:81-82` likewise), which is what made
the wire field renameable.

**The review half of the summary had no consumer outside the page.**
`summary.duplicates / duplicateOverrides / mediaScan / mediaScanOverrides`
(`loadActionable.ts:52-64`, loaded `:194-201`) were read only by `actionable/page.tsx:341-348`
— so the dashboard render and every widget poll paid the 6.7 MB duplicates parse for nothing.

**`SweepPlan`'s `sweep <slug>` checkbox exists only while choosing a scope**
(`SweepPlan.tsx:171-174`), and its total is a cross-kind sum by design (`bandForScope`,
`:92-96`). A channel with no snapshot goes into a COUNT there, not into a row — which is why
the site-scope pool assertion could not move to a sweep plan.

**`/cleanup` lists a snapshot-less channel by label.** `ChannelCleanupCard` is
`<section aria-label="cleanup <slug>">` (`:49`) and the page reads no `searchParams` at all.

**As shipped** (`a623958` → `43c4e26`):

- `SectionConfig` gained `operation` (`"download" | "transcription" | "digest" | null`),
  `role` (`"work" | "attention"`) and `getRows`, so a page never hand-pairs a config with a
  summary list. `sectionsFor(op)` returns work then attention in declaration order, and `[]`
  for an unknown id — which is what makes the cast at the `/operations/[id]` call site safe.
- `ChannelWorkTable` renders **outside** `section[data-lane]` and outside the runner's
  `<section>`, and carries no `role="status"`. All three constraints are recorded in its
  header comment with the specs that depend on them.
- The census lost `backfill`, `staleOrMissing`, `actionableBackfillCount` and
  `actionableBackfillMissingInputCount`; `reportStateOf(brief)` is new (three states) and
  `isStaleOrMissing(row)` is now defined in terms of it.
- `refreshAllChannelSnapshotsAction` lives in `editor/app/channels/actions.ts`; the four
  review actions in `editor/app/review/actions.ts`; the two global incomplete-transcript
  actions stay in `editor/app/lib/actionable/actions.ts`.
- Revalidation of the operation pages is `revalidatePath("/operations/[id]", "page")` — the
  route-pattern form, the only one that reaches `/operations/digest` without naming it
  (`node_modules/next/dist/docs/.../revalidatePath.md`; the shape `operations/actions.ts:30-33`
  already documented).
- `editor/app/lib/actionable/` keeps its name deliberately: renaming the `actionable*`
  identifiers is a vocabulary pass, and `/api/widget/actionable` is a wire contract.

## Verified 2026-08-28 — editor IA slice 7 seams (one pause)

Census taken before writing `editor-ia-slice-7.md`, against `494cbee`. Read-only observation
at census time; the "As shipped" notes were added with the docs commit.

**Four gates, three polarities, eight actions in two files** — the IA bullet's "six actions"
was wrong. `transcriptionsPaused` (`settings.ts:152`, plus the LIVE
`WorkerPool.pauseAll/resumeAll/isPaused`, `workerPool.ts:283-316`, re-applied at boot by
`editor/instrumentation.ts:56-73`); `downloadsPaused` (`:157`); `digest.digestsPaused`
(`:474`); `backfill.enabled` (`:289-292`, **inverted**, shared by diarization /
attribution-text / attribution-diarized, and deliberately also written by the
`LaneSettingsForm` checkbox, `operations/settingsActions.ts:214`). The actions were
`jobs/actions.ts:150-178` (downloads), `:180-215` (digests), `:329-379` (backfill) and
`workers/actions.ts:9-23,60-83`.

**Three UI copies, one of them dead.** `PauseTranscriptionsButton.tsx` had two importers
(`jobs/active/page.tsx:37`, `WorkersView.tsx:125-129`); `PauseDownloadsButton.tsx` had
**zero**; `LaneDeck.tsx` carried four inline `LaneControl` descriptors
(`:126-148,216-238,283-309,437-459`); and `SweepLane.tsx:187-211` was a fifth, on the ui
`Button`, with a COMPOSED aria-label and the OPPOSITE emphasis (warning tint when NOT held).

**The inversion lived in three readers and the widget shipped it raw.** `LaneDeck.tsx:471`
(`gateHeld: !laneEnabled`), `operations/lanes.ts:334-336`, `buildActiveJobs.ts:337`;
`api/widget/sync/route.ts:72,96,289,296` sent `digest.paused` and `backfill.enabled`.

**Playwright's `getByRole(…, { name })` is a case-insensitive SUBSTRING match unless `exact`
is passed, and no pause/resume lookup in the suite passes it** (grep-verified). That is the
whole reason every label survived one canonical table: `auto-queue.spec.ts:1186`'s
`"Pause Digest"` (scoped to `section[data-lane="digest"]`) matches `"pause digests"`.
`"Pause Speakers"`, `"Pause Derived"`, `"Resume Digest"` and `"Hold the lane"` are asserted
nowhere.

**Transcription's `held` is the live pool on every UI surface, never the flag.**
`isGateHeld(settings, "transcription")` answers "will the pool be paused after a restart".
The e2e harness rewrites `test-settings.json` wholesale between tests while the pool keeps its
`pausedSnapshot`, so a surface reading the flag would disagree with the machine.

**The runner pages had no pause at all** (`LaneHeader.tsx:51-84`: Start/Drain/Stop only;
`AutoQueueKindStatus` carried no held field; `railStates.ts:36` hard-coded `gateHeld: false`).
Worse, `/operations/transcription` said **"no enabled worker to run it"** while paused, because
`pauseAll` disables every worker and `autoRunner.ts:598` reported `no-workers`.

**As shipped** (`c924f73` → `685cba3`):

- `common/lib/pauseGates.ts`: `PauseLane`, `pauseLaneFor(operationId)`, `isGateHeld` and
  `withGateHeld`. `pauseLaneFor` asks the descriptor's `runner` BEFORE its queue key —
  `transcode` shares `TRANSCRIPTION_QUEUE` and has no runner, so a queue-key map alone would
  hand it the transcription pause; its answer is `null`. It walks `operationCatalog()` (all
  seven ids), not `OPERATION_BY_ID` (the four registry entries). 6 unit tests
  (`pauseGates.test.ts`), one of which pins the seven-id table.
- `isGateHeld` switches on the lane and touches ONLY that lane's field, because
  `laneGuards.test.ts:22` casts a `{digest}`-only object to `SiteSettings`.
- Two actions, `pauseLaneAction(lane)` / `resumeLaneAction(lane)` in
  `editor/app/operations/actions.ts`. Transcription flips the pool FIRST, then persists; a
  failed write returns `{ok:false}` (`persistTranscriptionsPaused` used to swallow it).
  Revalidates `/jobs`, `/workers` and `/operations/[id]` — **not `/`**, which reads its pauses
  from polls and whose revalidation wipes the client router cache app-wide.
- `editor/app/components/lanes/pauseControl.tsx` (`pauseLaneControl` + `PauseLaneButton`) is a
  client module and imports `PauseLane` as a **type only**: a value import would drag
  `operations.ts` / `settings.ts` and `fs` into the client graph.
- `disabled` reaches the PAUSE side only, so a resume is always clickable. This fixes
  `SweepLane.tsx:191`, which disabled both sides on `!lane.available`.
- The wire says `held` on both sweep lanes. One reader the census MISSED:
  `MonitorWidget.tsx:727-728` (`BackfillStrip`'s non-dense branch, "lane off" / "sweeping")
  read `backfill.enabled` and was rewired in the same commit — the census's "nothing in
  MonitorWidget/WidgetControls" was wrong.
- `AutoQueueKindStatus.held` is the LIVE pool for transcription and `isGateHeld(…, "download")`
  for download; `railStates.ts` passes it through, so a runner lane can read *Holding*.
- New idle reason `"workers-paused"`, checked before the `no-workers` branch in
  `autoRunner.ts`'s `limit()`, mapped in `dispatch.ts` ("transcriptions are paused") and
  `buildActiveJobs.ts` ("transcriptions paused globally").

## Verified 2026-08-28 — editor IA slice 6 seams (the video page, one panel per operation)

Census taken before writing `editor-ia-slice-6.md`, against `ce2ebd9`. Read-only observation
at census time; the "As shipped" notes were added with the docs commit.

**`hasDigest` had ONE caller and it was not the video page.** `controller/channels.ts:94`,
inside `countDataFiles` (`:67`) under `listChannelStatsFromDisk` — the batch ground-truth
walk. Identity-blind on purpose (`digest-server.ts:84-90`: "is there a digest at all", never
"is it current"), and `channelProjection.test.ts:66-67` pins that a record with a non-empty
section counts. Defined at `digest-server.ts:91-98`, not `:89` as the IA bullet said.

**`hasAttribution` was already dead** — `attribution-server.ts:36-38`, zero callers across
`common editor export homepage umtool mcp`. **`hasDiarization` is NOT dead**:
`cleanAudioFromTranscribed.ts:125` (the audio-deletion guard), `diarizeOne.ts:185`,
`diarization.test.ts:57-92`. `files.hasDiarization` on `VideoFiles` is a separate listing flag.

**The page duplicated the digest operation's `state()`.** `page.tsx:155-184` called
`resolveDigestTarget` with `lane: "local"` and folded `isSectionFresh` + the `derivedFrom` rule
per section; `digest.state()` (`operations.ts:1104-1185`) folds the same rule at `:1153` and
`:1176-1178`, and its `resolveTarget` (`:1096-1103`) calls the same resolver with no lane,
which `resolveDigestChunking` (`digestTarget.ts:69-79`) resolves to `localAppId` — the same
identity. Dropping the copy changed no displayed value.

**`readVideoFiles` had never been called from `editor/`.** The page's own `loadVideoDir`
(`page.tsx:57-77`) is a `readdir` + per-file `stat` for size/mtime, which the Files card needs,
so it stays; `readVideoFiles` is a second `readdir` and is the registry `state()`'s probe.

**`ids` existed on the batch and not on the job.** `runBackfillBatch` took `ids?: string[]`
(`backfillBatch.ts:99`, intersected with disk at `:290-291`); `BackfillChannelJobOptions`
(`operationJobs.ts:60-75`) did not, and `countBackfillWork` (`:869-926`) walked every dir with
no filter. `jobReplayRegistry.ts:281-284` read `p.kindIds` only. `digestBucketAction`
(`digestActions.ts:83-135`) is the precedent for an id-scoped job on the other lane.

**Client-graph hazard, carried through.** `lib/operations.ts` imports `digest-server`,
`diarization-server`, `attribution-server` and `videoStatus` — all `node:fs`. Every client file
in this slice imports from it as `import type` only. `lib/digest.ts`, `lib/diarization.ts` and
`lib/attribution.ts` have no imports at all and are safe for types and pure values.

### As shipped

- `common/controller/videoOperations.ts`: `inspectVideoOperations` (one `readVideoFiles`, one
  `resolveTarget` + `state()` per entry, in `OPERATIONS` order, filtering nothing),
  `shownOnVideoPage` (`enabled || any output present`), `orderForVideoPage`
  (`OPERATION_GROUP_ORDER` then registry order — a stable sort, so digest comes first and the
  three speaker operations keep their registry sequence). `VideoOperationView.target` is the
  erased `unknown` and never crosses to a client.
- `digestSectionStates(record, sections, target)` in `lib/digest.ts` is the ONE fold;
  `operations.ts:1176` counts through it. The `derivedFrom` early return at `:1153` stays, so
  behaviour is identical.
- `hasDigest` → private `hasDigestWithItems` in `channels.ts`; `hasAttribution` deleted.
- `ids?: string[]` on `BackfillChannelJobOptions`, through to `countBackfillWork` (which now
  intersects the dir list with it before the walk) and `runBackfillBatch`; in `spec.params`;
  parsed in `jobReplayRegistry.ts` exactly as `kindIds` is; a fourth argument on
  `backfillChannelAction`. `backfillSweep.ts:168` (three args) is unaffected.
- `editor/app/channels/[slug]/videos/[id]/`: `components/operationState.ts` (the state→words
  table + `stateTone`, pure, no directive, `import type` from `lib/operations`),
  `components/OperationPanel.tsx` (the frame: `${id} panel`, `${id} freshness`, `${id} off`,
  and an exhaustive body switch whose `undefined` arm renders `${id} outputs`),
  `components/DigestBody.tsx` (the renamed `DigestPanel`, frame removed, everything else
  byte-for-byte), `components/SpeakerBodies.tsx`, `lib/videoOperationPanels.ts` (server-only;
  loads one body per `settingsBlock`, reads `attribution.json` ONCE for both attribution
  views, strips `target`), `operationActions.ts` (`"use server"`, functions only).
- The digest heading is `view.label` — **"Digest"**, not "AI digest". No spec pinned the old
  string; `sections.tsx:154` is the only remaining "AI digest" in `editor/`, and it is prose.
- `runOperationForVideoAction` is the SPEAKER lane only. Digest keeps `digestBucketAction`
  (its own queue, its own guards). No `queueKey`, no `background`.
- Left alone deliberately: `readVideoDigestAction` (`digestActions.ts:149`) still has **zero
  callers**; the two-pane `/channels/[slug]/videos?video=` route is still `VideoPanel`-only;
  `common/components/TranscriptModal.tsx` has its own unrelated local `DigestPanel` (the
  published player's), which is why a repo-wide `DigestPanel\b` grep is not zero.

## Verified 2026-08-29 — editor IA slice 8a+8b seams (sync is an operation; its settings and the workers' live on their pages)

Census taken read-only against `6f6c307` before writing `editor-ia-slice-8ab.md`; the "As
shipped" notes were added with the docs commit.

**Every consumer of `operationCatalog()`, and what a `sync` entry does to it.** The catalog
went from seven ids to eight, and this is the whole blast radius:

| consumer | before | after |
| --- | --- | --- |
| `operations.ts` `operationApplies/Label/Group/ShortLabel/CostBasis` | `find` by id | unchanged; `operationLabel("sync")` is "Sync" |
| `pauseGates.ts` `pauseLaneFor` | walks the catalog | `null` for sync — no runner, and its queue key is neither sweep's; `pauseGates.test.ts` pins it |
| `operations/[id]/page.tsx` `descriptorFor` | the 404 gate | `/operations/sync` resolves, and the page reads `op.trigger` for the console |
| `settings/page.tsx` worker tags | every id | moved to `workers/page.tsx`, filtered `scope === "video"` |
| `channels/page.tsx` `pipelineColumns` | Map lookup; `ids` = `EXTERNAL_BAND_IDS` + enabled kinds | unchanged — sync is in neither list, and its group is not in `OPERATION_GROUP_ORDER` |
| `channels/[slug]/lib/channelFlow.ts` | Map lookup over `buildChannelBands` ids | unchanged, same reason |
| `lib/pauseGates.ts` `pauseLaneFor` | `runner` first, then the queue key | `null` for sync (was `operations/lanes.ts` `sweepLaneIdFor`, deleted in slice 1.3) |
| `components/pipelines/buildBands.ts` | `EXTERNAL_BAND_IDS` + operation ids | unchanged — **no sync band, deliberately** |
| `controller/videoOperations.ts` | walks `OPERATIONS` | unchanged; sync is `scope: "channel"`, so a per-video reader has nothing to ask it |
| `allOperations` / `backfillLaneOperations` / `countOperationWork` / `operationsForLane` | `OPERATIONS` | untouched — the registry, not the catalog |

**`pauseGates.test.ts` pins the catalog's LENGTH**, which is what makes a new entry a failing
test rather than a silent omission: `assert.equal(ids.length, 8)` plus an expected lane for
every id. That is the pin that forced sync to state `null` on purpose.

**`ExternalOperation` was a duplicate field list, and is now a projection.** It repeated
`OperationDescriptor`'s eight fields plus `runner` and `appliesTo`; it is
`Omit<OperationDescriptor, "dispatch" | "settingsBlock"> & { dispatch: "external" }` now, so
`scope` and `trigger` are declared once and a future field cannot go missing from one of the
two. `SYNC_OPERATION` is typed `OperationDescriptor` directly (it HAS a `settingsBlock`) and
is not a member of `EXTERNAL_OPERATIONS` — that list is the media-derived pipelines the rail
draws bands for.

**The lane NOTE strings were TWO copies and a paraphrase, not three copies.**
`railStates.ts` and `buildActiveJobs.ts` held byte-identical four-row tables ("no operation
switched on", "sweep armed, lane paused", "lane paused", "no sweep armed");
`buildActiveJobs.ts` ALSO re-stated `deriveLaneState`'s precedence beside its table.
`SweepLane.tsx` is a sentence over the same derivation, and stays one. **No spec pinned any of
the four strings** (grep-verified before the change), so `laneState.test.ts` is the first
thing that does.

**Where the two Storage chores actually show.** `keptChecksQueued` / `savedVideoBackupQueued`
are fields of `SchedulerTickResult` and reach **no UI**: `SchedulerView`/`SyncConsole` read
`queued`/`skipped`/`reason`, and `SchedulerRun` records neither. They are visible only as (a)
the `skipped` reasons (`kept-check: …` and the pseudo-slug `(saved-video backup)` — now
`storage chore (…)` in both), (b) the *Keep-latest check interval* field, (c) the
`/saved-videos` sentence. Recording them in `SchedulerRun` is a state-shape change and was out
of scope; the Run-now message reads them off the POST body instead, which needed no tick
change at all.

**`editor/app/scheduler/` is the sync operation's RUNNER, and only `page.tsx` was deleted.**
Importers of the rest, all still live: `instrumentation.ts` (`heartbeat.ts`),
`api/scheduler/status/route.ts` and `api/scheduler/tick/route.ts` (`status.ts`, `runTick.ts`,
`auth.ts`), `operations/syncRow.ts` (`status.ts`), `ChannelForm.tsx` and the moved cadence
forms (`intervalPresets.ts`, `actions.ts`). A route directory with no `page.tsx` is not
routable, so `/scheduler` is answered by a `permanent: false` (307) redirect in
`next.config.ts`; `/api/scheduler/*` is deliberately NOT redirected.

**One writer per settings block, now true of two more blocks.** `saveSchedulerSettingsAction`
is the only writer of `settings.syncScheduler` and `saveWorkersAction` the only writer of
`settings.workers`; both read the current file and replace their own block, and
`settings/actions.ts` preserves both by name beside `digest` / `diarization` / `backfill` /
`attribution` / `autoQueue` / `savedVideoBackup`. `hourOrNull` moved from `settings/actions.ts`
to `scheduler/actions.ts` with the quiet-hours pair: those are the one place in the block where
BLANK IS A VALUE, so they cannot go through `intOrKeep`.

**One consumer the plan did not name, found by tsc.**
`channels/[slug]/videos/[id]/lib/videoOperationPanels.ts` switches exhaustively over
`OperationSettingsBlock | undefined` to pick a per-video panel body. Widening the union broke
it. `case "syncScheduler":` falls through to `case undefined:` with a comment: `views` comes
from the per-video registry walk, so a channel-scoped block can never arrive — and the arm
exists precisely because the exhaustive switch is what makes a NEW per-video block a compile
error rather than a blank panel.

**As shipped.** `editor/app/operations/components/sync/` holds `SyncConsole.tsx` (was
`scheduler/components/SchedulerView.tsx`), `SchedulerSettingsForm.tsx`,
`ChannelCadenceEditor.tsx`, `BulkCadenceBar.tsx` and `cadence.ts`;
`editor/app/workers/components/` holds `WorkersField.tsx` (was under `settings/components/`)
and the new `WorkersConfigForm.tsx`; `sweepLaneNote` is in
`editor/app/components/lanes/laneState.ts` with `laneState.test.ts` beside it.

---

## Verified 2026-08-30 — editor IA slice 8c seams (`/jobs` is one list)

Read-only census against `a609566` (clean), before the four commits `2226680` → `21feed3`.
Line numbers are that tree's.

**The three shapes, and how little they overlap.**

| source | type | fields nothing else had |
|---|---|---|
| `.jobs` directory ∪ registry | `JobListEntry` (`common/jobs/listJobs.ts:12-29`) | `logSize`, `logPath`, `inRegistry`, `replayable`, `status: JobStatus \| "archived"` |
| registry, running/queued only | `RunningJobsListItem` (`editor/app/jobs/components/RunningJobsList.tsx:38-69`) | `progress`, `tasks`, `draining`, `drainable`, `background`, `canMoveUp/Down`, `status: "queued" \| "running"` |
| scheduler ∪ registry | `QueueSlotView` (`editor/app/jobs/queue/buildQueueView.ts:19-31`) | `ageMs`, `stuck`, `stuckReason`, `pid`, `lastLogLine`, `status: string` incl. `"evicted"` |

`JobRowView` (`editor/app/jobs/jobRowView.ts`) is the union: every `RunningJobsListItem` field
NAME kept, `status` widened to `JobStatus | "archived" | "evicted"`, everything else optional.

**Who reads a live row, and on what.** `MonitorWidget.tsx` reads `status`, `kind`,
`background`, `channelSlug`, `progress`, `tasks` (`:1047-1086`) and the `progress`/`tasks`
element types (`:1121,1139,1176`); `PipelineBand.tsx:37-39` reads `jobs.jobs[].status`;
`LaneDeck.tsx:64` reads `jobs.disk`; `WidgetControls.tsx:75` passes the payload through.
**None narrows on `status`**, which is why widening it compiled with one import line changed.

**The type dependency was backwards.** `buildActiveJobs.ts:18` imported its row type from
`RunningJobsList.tsx:38` — a `"use client"` component. It worked because it was `import type`;
the shape three surfaces read now lives in a types-only module whose only imports are
`JobStatus`, `JobProgressMetric`, `JobTaskKind` from `common/jobs/registry`.

**Who called the heal, before and after.** Before: `buildQueueView.ts:231-234`, reached from
`/jobs/queue`'s render, its 2 s poll — and from **`/jobs/active`'s server render**, which
called `buildQueueView()` purely for a badge count (`active/page.tsx:15-20`). After:
`buildActiveJobsPayload`, i.e. `/jobs`, `DashboardCockpit.tsx:39-44`'s 1 s poll,
`MonitorWidget.tsx:71-76`'s poll and `/api/jobs/active`. `/api/pulse` does NOT join them
(`api/pulse/route.ts:36-53`: it observes, it "MUST NEVER CONSTRUCT").

**The `"running"` badge's consumers.** `nav.ts:45,103`; `layout.tsx:59` (the seed) and
`:106-117` (the `metric` switch); `SidebarBadges.tsx:22-33`; `api/pulse/route.ts:73,121`
(computes `runningJobs`, derives `busy` from it); `components/pulse.ts:20,30,69`. Only
`jobs-active-order.spec.ts:64` pinned `"1 running job"`. The nav key, the seed and the prop
went; **`PulsePayload.runningJobs` stays** — `busy` reads it and removing it is a wire change
no page needs.

**Today's queued order vs the scheduler's.** `buildActiveJobs.ts:182-185` sorted running
before queued and otherwise kept `registry.list()`'s order, which is `queuedAt` DESC
(`registry.ts:157-161`). The scheduler's order is the array order in `queues()`
(`scheduler.ts:167-178`): running prefix, then queued. Queued rows now sort by
(`queueKey` localeCompare, `position`) off ONE `queues()` snapshot — `buildQueueView.ts:112-115`
already made the argument for snapshotting once.

**`forceRelease`'s contract**, which is what makes reaping an already-healed id safe:
`registry.ts:260-276` — `scheduler.complete` is a no-op for an unknown id and the method
returns `true` regardless; it also **stamps `endedAt`** on a running/queued record
(`:266-269`), so a force-released job is a `recent` row for `RECENT_MS`.

**`builtAt`, and why.** `next.config.ts:46` sets `staleTimes.dynamic: 15`, so a `/jobs`
render served from the router cache can be OLDER than the client's last poll. Adopting a new
`initial` prop unconditionally would show a finished job as running again. The payload carries
the server's `Date.now()` and the client renders whichever of the prop and the poll is newer.

**Client-safety of the pure module.** `common/jobs/jobKinds.ts` has ZERO imports and is
already in the client graph via `jobKindLabels.ts`; `common/jobs/ulid.ts` has zero imports.
Those two are `jobRows.ts`'s only value imports, which is what lets a `"use client"` table
import the same adapters the server builder uses — the `laneState.ts` precedent.

**The `nth(1)` assertions, one by one.** Order after the fold: stuck, running (newest first),
queued (queue, position), finished ≤ 30 s (newest first), then history newest first.
`queues.spec.ts:36` (slow-a running → first live row); `queues.spec.ts:126-129` (slow-a
running nth 1, slow-b queued nth 2 — the assertion is symmetric and today's order was the
reverse); `digest.spec.ts:382-384` and `:466-467`; `bulk-actions.spec.ts:65,96,117`;
`channels-actions.spec.ts:41,59`; `jobs-channel.spec.ts:21,43-52`. Each holds because the job
under test is either running (head, first) or finished seconds ago (`recent`, first). The
pre-existing `refresh-report` hydration race (FACTS.md:1004-1010) is exactly as it was.

**As shipped.** `editor/app/jobs/jobRowView.ts` (types only), `editor/app/jobs/jobRows.ts`
(adapters, order, merge, `reconcileSlots`, `fromSlot`, `RECENT_MS`, `STUCK_AGE_MS`) with
`jobRows.test.ts` beside it; `buildActiveJobs.ts` gains `rowsForRecords`, `liveJobRows`,
`listJobRows`, `readLastLogLine`, `stuckJobIds` and the heal loop; `components/LaneStrip.tsx`
and `components/JobProgressBars.tsx` are byte-identical extractions; `components/JobsTable.tsx`
is the one list; `components/ReapStuckButton.tsx` is the queue strip's action. Deleted:
`jobs/active/page.tsx`, `jobs/components/ActiveJobsLive.tsx`, `jobs/queue/` (three files) and
`api/jobs/queue/route.ts`.

**One consumer the plan did not name, found by tsc.**
`editor/app/channels/[slug]/lib/stageStatus.ts:165` typed its `runningJobs` input `JobRecord[]`
while reading only `status` and `kind`. The channel page no longer holds `JobRecord`s, so the
input takes the SHAPE (`ReadonlyArray<{ status: string; kind: string }>`) instead. Its other
caller (`videos/page.tsx` → `videoRowsServer.ts`) still passes records and is untouched.

## Verified 2026-08-30 — editor IA slice 5 seams (a site has tabs; the family has one page)

Read-only at `2a8081e`, implemented at `140212a` → `df9b839`. Trust these over re-deriving.

**What the five pages actually were** (the IA bullet's premise, "all per-site facts already;
only their routes say otherwise", is wrong for two of them):

| page | scope | reads | writes | `?site=` |
|---|---|---|---|---|
| `/charts` | **per-site** templates; preview DATA = last-composed site | `readTemplates(paths, siteId)` → `sites/<id>/chart-templates.json`; `useStats`/`useSummaries` fetch `/stats/*` = `export/public/stats` = whichever site `compose-site` ran last | `saveDefaultDashboardAction`, no revalidate | yes, REQUIRED one site |
| `/aliases` | **global + per-site overlay** | `readGlobalAliases` → `transcripts/search-aliases.json`; `readSiteAliases` → `sites/<id>/search-aliases.json`; merged at compose, per-site id SHADOWS global (`aliasesStore.ts:68-73`) | `saveGlobalAliasesAction`, `saveSiteAliasesAction`, no revalidate | optional |
| `/deploy` | **per-site target + global chrome** | `listSites`; `export/CHANGELOG.md`; `export/out/index.html` mtime (`resolveOutDir` ignores siteId); `settings.buildPipeline.mode` *(gone 2026-09-28, O6c)* | `cutReleaseAction`, `setBuildModeAction`, `deployExportAction(siteId)` + four from `buildAction` | optional |
| `/build` | **corpus-wide, no site notion at all** | `activeQueueNames()`, `liveJobRows(BUILD_KINDS)` — no `searchParams`, no `listSites` | eleven actions in `buildAction.ts` | **never** |
| `/homepage` | **global — the hub's identity** | `getHomepageConfig` → `sites/_homepage/homepage.json` | `saveHomepageConfigAction` | **never**; page was sync |
> **Superseded by release 18 (2026-10-06):** the `/deploy` row's `export/out` is now a link to the bundle built last; a deploy ships `<exportBuildsDir>/<target>/out` — see "The publish stages" at the end of this file.

**The seven import edges, and where each went.** `build/` and `deploy/` were already one module
in two directories: `build/buildAction.ts:34` imported `deploy/buildDeployCore`, and four
`deploy/components/*` imported `build/buildAction`. Now: server modules in
`editor/app/sites/lib/` — `buildAction.ts`, `deployAction.ts`, `cutReleaseAction.ts`,
`buildModeAction.ts` *(deleted 2026-09-28, O6c)*, `homepageActions.ts`, `chartsActions.ts`, `aliasesActions.ts` (all
`"use server"`) plus `buildDeployCore.ts` (deliberately NOT, its header says why). Components
FLAT in `editor/app/sites/components/`, so every moved file has the same import shape:
`../lib/x`, `../../components/QueueControl`, `../../jobs/actions` — the last two byte-identical
to what they were from `deploy/components/`. `changelog/page.tsx:12` is the one outside
repoint (`CutReleaseForm`, `workspace="editor"`, driven by `cut-release.spec.ts`).
`SiteTabs.tsx` lives under `sites/[siteId]/components/` (the `ChannelTabs` precedent). Neither
`sites/lib` nor `sites/components` has a `page.tsx`, so neither is routable and neither can
shadow a site id — and **no static sibling of `[siteId]` was added**, because `/sites/publish`
would shadow a site called `publish` (`SITE_ID_RE = /^[a-z0-9][a-z0-9-]*$/`).

**`has`-rule anchoring and the query merge (Next 16.2.3).** `matchHas` compiles the value as
`new RegExp(`^${hasItem.value}$`)`
(`next/dist/shared/lib/router/utils/prepare-destination.js:101`) — ANCHORED, so
`?site=__all__` fails `[a-z0-9][a-z0-9-]*` and falls through to the bare rule. The named group
becomes a destination param (validator: `next/dist/lib/load-custom-routes.js:210-263`). The
initial query is MERGED into the destination (`prepare-destination.js:278-284`) and stringified
into `Location` (`next/dist/server/lib/router-utils/resolve-routes.js:509-517`), so
**`/charts?site=testsite` lands on `/sites/testsite/charts?site=testsite`** — the query is not
stripped. Any spec regex on a captured redirect must therefore end `(\?|$)`. Redirects are
checked BEFORE the filesystem, so a redirect for a route that still has a page hides the page:
each commit added only the redirects for the pages it deleted.

**The metadata template rule.** A layout's `title.template` applies to CHILD segments and NOT
to a `title` in the same segment's `page.js`
(`node_modules/next/dist/docs/.../generate-metadata.md:284-287`). So
`sites/[siteId]/layout.tsx` exports
`{ default: `${siteId} — Sites`, template: `%s — ${siteId} — Sites` }`: the index page exports
no title at all and gets `default` (today's string, unchanged), and each tab exports a bare
static `title` ("Charts", "Search aliases", "Publish") and gets templated.

**`revalidatePath` literal vs `"layout"`.** A literal path invalidates only that page
(`revalidatePath.md:38`, `:151` "will not invalidate pages beneath"); `type: "layout"`
invalidates the layout, nested layouts and every page beneath (`:39`, `:155-162`).
`saveSiteAction`'s `revalidatePath(`/sites/${siteId}`)` therefore did NOT cover the tabs by the
letter — it worked only through the "temporary" server-function behaviour that refreshes every
visited page. It is `revalidatePath("/sites/[siteId]", "layout")` now (the h1 above every tab
reads `siteTitle`, which that form edits). `buildStatsAction`'s `/charts` became
`revalidatePath("/sites/[siteId]/charts", "page")` (precedent: `channels/actions.ts:312`).
`revalidatePath("/sites")` now has **eight** callers (was five).
> **Superseded by release 18 (2026-10-06):** `buildStatsAction` is deleted; the stats datasets are built inside the `update-index` stage — see "The publish stages" at the end of this file.

**`seedsSiteParam` and the path rule beside it.** `SiteScopeSelect.tsx`'s
`seedsSiteParam = !pathname.startsWith("/sites")` is UNCHANGED and its reason still holds: the
mount effect's `replace()` clobbered an in-flight push to `/sites/<id>` (a link click on the
list), bouncing the user back to `/sites?site=<id>`. Beside it now: `siteIdFromPathname()` in
`app/lib/activeSite.ts` — a pure `SITE_PATH_RE = /^\/sites\/([a-z0-9][a-z0-9-]*)(?:\/([a-z-]+))?\/?$/`
that rejects `new` (a static route that beats `[siteId]`) and anything deeper than a tab. The
id pattern is `SITE_ID_RE` **re-spelled**, because `common/lib/site.ts` imports `node:fs` and
`activeSite.ts` must stay importable from the client picker. On a site path the picker's value
IS the path segment, the reconcile effect writes it to localStorage (so Dashboard and Channels
follow), `onChange` does `router.push("/sites/<other>/<segment>")` and "All sites" pushes
`/sites`.

**Superseded by release 15 slice SS (2026-09-29): the active site is a cookie.**
`seedsSiteParam`, the reconcile effect and every localStorage read on the render path are gone;
`siteIdFromPathname` and the path rule stand.
- **Store:** the cookie `archilyzer-active-site-<port>` (`activeSiteCookieName(host)` in
  `app/lib/activeSite.ts`; base name `ACTIVE_SITE_COOKIE`, a host with no port uses it bare):
  `path=/`, `SameSite=Lax`, one year, `httpOnly`. The port is in the name because a cookie is
  shared by every port on a host and localStorage was per origin.
- **One writer:** `setActiveSiteAction` (`app/lib/activeSiteActions.ts`, `"use server"`), which
  only shape-checks (`isStorableActiveSite`: a `SITE_ID_RE`-shaped id of ≤ 128 chars, or
  `__all__`). Setting the cookie makes Next re-render the current page and its layouts, which
  is how Dashboard and Channels re-scope; nothing calls `router.refresh()`.
- **One read:** `readActiveSite(param?, siteIds?)` (`app/lib/activeSiteServer.ts`,
  `server-only`). The root layout calls it with no param, and Dashboard (`app/page.tsx`) and
  Channels (`app/channels/page.tsx`) with `searchParams.site`. The precedence is
  `resolveActiveSiteFrom(candidates, siteIds)`: the first candidate naming a configured site or
  `__all__` wins, else `resolveActiveSite`'s default (the lone site, else all). The server passes
  `[?site=, cookie]`; the picker passes `[its held choice, the path's site, ?site=, stored]`.
- **The root layout now reads a cookie, so every page renders per request** (the build lists
  every page `ƒ`; route handlers were `ƒ` already, and `/icon.svg` stays static). The one page
  whose mode changed is `/_not-found`. The picker's Suspense stays for the build's
  missing-Suspense check.
- **`SiteScopeProvider`** (`app/components/SiteScopeProvider.tsx`, context + `useSiteScope()`)
  holds `stored`, following the layout's value when it changes and not while a picker write is
  in flight. `choose(value)` (the picker's changes) updates `stored` optimistically; the two
  effects, visiting `/sites/<id>/…` and the one-time localStorage migration, only WRITE
  (`record`), because a state change during hydration re-renders the picker before React
  replays a pre-hydration change, and the replayed event then reads the reset value.
- **Other tabs.** A client-side navigation does not re-render the root layout, so a tab's
  `stored` would stay what its layout last read while another tab changed the shared cookie.
  Every successful write (`choose` and `record`) is therefore posted on
  `new BroadcastChannel(ACTIVE_SITE_CHANNEL)` (`"archilyzer-active-site"`, per origin and so per
  port), and the other tabs call `router.refresh()`. A channel instance does not receive its own
  posts, so a tab does not refresh for its own write. Without `BroadcastChannel` a tab keeps its
  value until its next full load. Passive refresh (`AutoRefresh`) also re-reads the layout, but
  only when the pulse token moves.
- **A `?site=` link** governs its own request and is not stored. Choosing on such a page writes
  the cookie, THEN `router.replace`s the URL without `site` (`withoutSiteParam`). On
  `/sites/<id>/…` the picker writes the cookie, THEN pushes, so a page opened once the URL has
  moved reads the new value. In both, the choice is held for the URL it was made on, so the
  controlled select does not snap back while the navigation is in flight, and dropped on the first
  render at another URL (else Back to that URL showed the old choice over the path).
- **A new channel starts checked on the active site** (review L5): `ChannelFormClient` resolves
  `resolveActiveSiteFrom([?site=, useSiteScope().stored], siteIds)` on its first render, and
  `SiteMembershipsSection` takes it into its INITIAL state (there was an effect), so the box is
  checked in the server's HTML and a later refresh cannot re-check a box the user cleared. With
  one site configured and nothing stored, that site starts checked.

**`BUILD_KINDS` is wrong in both directions** and was moved verbatim, with a comment saying so:
six kinds (`build-index`, `build-stats`, `build-export`, `normalize-transcripts`,
`archive-transcripts`, `archive-combined-transcripts`) — MISSING the three live-chat kinds the
Pool's own buttons enqueue, and INCLUDING `build-export`, which is enqueued from a site's
Publish tab and never from here. Not fixed by slice 5.

**`_homepage` can never be a `[siteId]`.** `HomepageConfig` lives at
`sites/_homepage/homepage.json` — inside `sitesDir`, with a leading underscore that
`isValidSiteId` rejects. That is why the Hub is a section of `/sites` and not a tab.

**The hub's form is not what deploys the hub.** The `homepage/` package's own `deploy` script
hardcodes `--project-name archilyzer`, so the form's `cloudflareProject` field is NOT what
`pnpm deploy:homepage` uses, and no editor action, job or button builds or deploys the hub.
Pre-existing; slice 5 does not touch the script. Adjacent globals that are NOT the same field:
`HomepageConfig.siteUrl` (the Hub section) vs `SiteSettings.homepageUrl` ("Family hub URL" on
`/settings`) vs per-site `Site.hubUrl` (`SiteForm.tsx`).

**`idBaseUrl` is absolute**, so moving the charts client changed nothing about its data:
`useStats`/`useSummaries` fetch `${idBaseUrl(origin)}/stats/…`
(`common/components/statsCache.ts:28,44`), served through `next.config.ts`'s
`/stats|/summaries|/transcripts → /exported/…` rewrites. The preview therefore still draws
whichever site `compose-site` ran last, which the Charts tab's intro now says out loud.

**`getSite` throws on a malformed id** (`common/lib/site.ts:356`, sync), which is why the tab
pages do not call it directly: `sites/[siteId]/lib/siteCache.ts` wraps
`isValidSiteId(...) && listSiteIds(...).includes(...)` and returns `Site | null`, React
`cache()`d so the layout and the tab page share ONE read per request. The layout's `notFound()`
is the one 404 for `/sites/<missing>` and every tab under it; each tab page guards through the
same read (the channel page does likewise). There is no `loading.tsx` anywhere under `sites/`
— in this app one turns `notFound()` 404s into 200s.

**e2e labels newly co-resident on `/sites`, and why none collides.** A site's title now appears
THREE times on that page: the picker `<option>`, the list `<Link>`, and `BuildSitesPanel`'s
visible `<span>{s.siteTitle}</span>` beside its `aria-label="Select <title>"` checkbox.
`sites-crud.spec.ts` survives because it already scopes by
`getByRole("link", { name: /Alpha Site/ })`, and its `getByText("Doomed")).toHaveCount(0)` runs
AFTER the delete, when all three are gone. Its `getByRole("button", { name: /delete/i })` stays
unique: none of the ~15 buttons added to `/sites` contains "delete".
`getByRole("button", { name: "Build index" })` is a SUBSTRING match and still unique there
("Build all sites", "Build selected", "Build stats dataset" do not contain it), and
`getByLabel("Build index output")` is route-independent. **`getByRole` ignores what a closed
`<details>` hides**, so anything inside the Pool disclosure or "Individual steps" needs the
click first — which is why `e2e/helpers.ts` grew `buildIndex(page)` (goto `/sites`, click
"Pool jobs", press, assert "Done") and now imports `expect` as a value.
> **Superseded by release 18 (2026-10-06):** `BuildSitesPanel`, "Build all sites", "Build selected" and "Build stats dataset" are gone from `/sites`; "Build index" enqueues the `update-index` stage and `buildIndex(page)` waits for `[stage] update-index _index: Done` — see "The publish stages" at the end of this file.


## Verified 2026-08-30 — transcode: what it was, what stayed

Read-only `jq` over `transcripts/channels/*/{snapshot,config}.json` plus `ls` on the
`failed-transcodings` files. Nothing booted, nothing written.

| fact | figure |
|---|---|
| channels / snapshots | **68 / 68** — every snapshot carries a `buckets.untranscoded` key |
| `generatedAt` | 44 on 2026-08-27, 19 on 08-30, 5 on 08-31 (UTC) |
| `buckets.untranscoded` non-empty | **0 of 68** |
| `buckets.multipleAudioFormats` non-empty | **0 of 68** |
| `cleanupBytes.foreignAudio > 0` | **0 of 68** |
| `failed-transcodings` files on disk | **2** (`cornbreadman` mtime Jun 29, `the-quartering-rumble` mtime May 16), **both 0 bytes** |
| channels passing `handling === "transcribe" && !!audioFormat` | **4**: cornbreadman, hasanabi, omnimirror, the-quartering-rumble (all mp3) |
| `keepLatest > 0` (forces `extractionMode: "app"`, `persistencePlan.ts:92-94`) | **2**: nuxanor-kick 1, quarteringvlogs 5 |

**Transcode was three layers wearing one name, and only the middle one was deleted.**

1. **Download-time extraction.** The app runs ffmpeg itself (`transcodeAudio`,
   `common/controller/transcode.ts`) when `extractionMode === "app"` — **two callers**,
   `common/ytdlp/audioCheckedDownload.ts:44,768` and
   `common/ytdlp/downloadOneManaged.ts:30,224` (`finalizeAppExtraction`) — and `keepLatest > 0`
   forces that mode (`persistencePlan.ts:92-94`). **Live in production, KEPT.**
2. **The transcode OPERATION.** Built by `70ed00f` (2026-05-19, "transcode failure handling")
   and half of `bb380c6` (2026-06-18): a channel-page Transcode stage, a `failed-transcodings`
   ledger, four job kinds, `buckets.untranscoded`, a "transcoded" dot and failed filter on the
   video list, the catalog entry carrying the registry's only `appliesTo`, and
   `/operations/transcode`. **DELETED 2026-08-30.**
3. **Wrong-format audio cleanup** — the OTHER half of `bb380c6`: `multipleAudioFormats` /
   `foreignAudio`, both sweeps and their bulk actions. **KEPT**, re-gated on
   `!!config.audioFormat` (`wrongFormatApplies`, `CleanupStage.tsx`).

**It could not have mattered.** `common/controller/transcribeOne.ts:22-31` `resolveAudioFile`
falls back to ANY real audio file when `audio.<fmt>` is absent; strict matching is opt-in per
manual batch and defaults false (`whisperBatch.ts:73,99`). A video whose audio is in another
format transcribes from that file.

**`transcode-audio` was never a registered job kind.** Its only spellings were
`videos/[id]/videoActions.ts:84` (the KEPT per-file action) and the stage map in
`stageStatus.ts`. The map entry left with the stage; the job still appears in
`RunningJobsList` and now marks no stage as running, which is right — there is no stage.

**The bucket is `wrongFormatAudio`, and there is no regen.** The population is unchanged (the
predicate in `channelSnapshot.ts` is untouched): audio on disk, none of it in the channel's
`audioFormat` — the orphan half of what "Remove wrong-format audio" deletes. No snapshot
schema version exists and every bucket field is optional by design, so an old snapshot keeps a
stray `untranscoded` key and reads `wrongFormatAudio` as `[]` until its next regen. An offline
rewriter would race `snapshotScheduler`. Production has 0 ids in the bucket, so nothing
rendered moves. The five e2e fixtures still spelling `untranscoded: []` are untyped JSON and
are left alone: `normalizeBuckets` picks only keys it knows, exactly as it ignores production's
stray key.

**The "runner first" order in `pauseLaneFor` survives without its example.** It is a property
of the catalog's SHAPE, not of transcode: an external entry sharing a runner's queue with no
runner of its own must answer `null`, or a queue-key map alone would hand it that runner's
pause. Same rewording in `operations.ts`, `operations.test.ts`, `operations/[id]/page.tsx`,
`operations/lanes.ts` and `OperationDetail.tsx` (whose `NoConsoleView` stays as the
fallthrough).

**The catalog is SEVEN.** Pinned at `pauseGates.test.ts` (`ids.length === 7`), stated in
`pauseGates.ts` ("all seven ids"), and listed in `operations.test.ts` ("the catalog covers
every operation"). `jobKinds.test.ts` uses `clear-failed-transcriptions` as its label-less
replayable example now.

**The worker tag lives on `/workers`, not `/settings`** — correcting the last line of the
2026-08-26 section above. `workers/page.tsx:21-28` builds `knownTags` from
`operationCatalog().filter(o => o.scope === "video")`, so the "transcode" tag disappeared with
the catalog entry and needed no edit.

**`EXTERNAL_BAND_IDS` is `["download", "transcription"]` permanently** (`buildBands.ts:163`,
pinned by `buildBands.test.ts`). The band question is closed by deletion, not by a
snapshot-shape change.

**Merge hazard.** The `duplicates-page` worktree edits `common/jobs/jobKinds.ts` (a +30 hunk
around `:251-290`) while this change deleted four entries lower in the same file, adds
`/duplicates` to `nav.ts` where main's `nav.test.ts` pins eleven, and still carries files main
deleted (`build/page.tsx` with its own `BUILD_KINDS`, `actionable/page.tsx`). Their merge —
recorded so nobody is surprised.

---

## one-core Phase 0 (verified 2026-09-07, branch `one-core/phase-0`)

### The exports-map trap: a fallback array type-checks and does not build

`common/package.json` now has an `exports` map. `"./components/*":
["./components/*.tsx", "./components/*.ts"]` passes `tsc --noEmit` in all six packages and
**fails `next build`**: Turbopack resolves the first entry of a fallback array and stops, so
`components/statsCache`, `components/summariesCache` and `components/virtualizer` (all `.ts`)
died with module-not-found. The map lists the **25** `.ts` modules under `components/`
explicitly — an exact key beats a pattern — and keeps `"./components/*": "./components/*.tsx"`
for the 30 `.tsx` ones. **A new `.ts` file under `components/` needs a new line in that map.**
Corollary for any future exports work: an `exports` change is a RUNTIME resolution change, so
`tsc` is not the test. `pnpm --filter editor exec next build` is.

### `styles/tokens.css` is imported by relative path, not as a subpath

`editor/app/globals.css:2`, `export/app/globals.css:2`, `homepage/app/globals.css:2` all do
`@import "../../common/styles/tokens.css"`. Only `styles/fonts` is a package subpath
(`editor/app/layout.tsx:10` and the two siblings). The exports map maps `"./styles/*.css"`
anyway, but nothing uses it today.

### `common/`'s back-edges: 12 remain, and the test is the ledger

`common/architecture.test.ts:41-99` — the allow-list, one entry per edge with the phase that
removes it. Rules: `lib/` ✗ `controller/` `jobs/`; `jobs/` ✗ `controller/`; `components/` ✗
`controller/` `jobs/` `ytdlp/`. It fails on a NEW edge **and** on a stale entry, so the list
can only shrink. The heaviest cluster is `lib/operations.ts` → four controllers (plus three in
its test): the registry's `run()` closures call the engines, which inverts in phase 1 step 4.

`common/lib/autoQueueTypes.ts` is new and holds the persisted auto-queue shape
(`AutoQueueMode/MatchType/Order/Reach/Match/Leaf/Group/Node/Policy/Settings`, `isGroup`,
`AutoQueueKind`). `jobs/autoQueuePolicy.ts:2-20` and `jobs/autoQueueState.ts:23-25` re-export
every name, so `from "../jobs/autoQueuePolicy"` still resolves everywhere.

### `page-${n}.json` existed six times, not three

`common/lib/manifest.ts` had three identical copies (the survey's count) — **and** so did
`lib/stats.ts:23`, `lib/posts.ts:164` and `lib/digests.ts:38`. All six are now
`manifest.ts`'s single `pageFileName`; `statsPageFileName`, `postsPageFileName` and
`digestPageFileName` are aliases of it, and `transcriptPageFileName` / `subsPageFileName` are
**deleted** (12 call sites rewritten). A seventh copy at
`common/components/searchIndex.worker.ts:39` is deliberate and stays: it is a bundled web
worker whose only import is its sibling protocol module.

### `CONTRACT` owns the published version numbers

`common/lib/corpus.ts` — `CONTRACT` holds `corpusSpec 3`, `siteDescriptor 1`, `manifest 3`,
`transcriptsManifest 1`, `subsManifest 4`, `subsChannelManifest 1`, `summariesPageSize 1000`,
`pagePad 4`, and `layers ["transcripts","subs","posts","digests","summaries"]`. The seven
existing named exports re-export its fields. Import direction is `corpus.ts` →
`{manifest,siteDescriptor}.ts`; `corpus.ts` imports `siteDescriptor` **type-only**, so there
is no runtime cycle, and `project.ts` (its only value import) imports nothing.

### How to compose a fixture site offline, and what a clean diff looks like

There is no existing harness for this — export's e2e route-mocks and the 2origin setup
hand-writes its shards. What works:

```sh
# a corpus root + a one-channel site
cp -r editor/e2e/fixtures/test-transcripts/one-youtube-channel-with-data/channels $F/
mkdir -p $F/sites/testsite && cat > $F/sites/testsite/site.json   # siteId/groups/channels
cd common && env TRANSCRIPTS_DIR=$F SITES_DIR=$F/sites \
  EXPORT_PUBLIC_DIR=$O/public EXPORT_INDEX_DIR=$O/index \
  SETTINGS_FILE=$F/settings.json SITE_ID=testsite \
  pnpm exec tsx bin/build-index.ts && ... bin/compose-site.ts
```

Output: **16 files** under `public/`, **7** under `index/`. Two runs differ ONLY in
`generatedAt` — in `corpus.json`, `site.json`, the subs/posts/digests/summaries/transcripts
manifests, and (pretty-printed, so normalize `"generatedAt": "…"` with a space too) the
archive zip's `channel.json`. The zip's own bytes differ because entry mtimes do; its
CONTENTS diff clean. Anything else differing is a real change to the wire.

### `editor/content` is a symlink out of the repo and it panics Turbopack in dev

> **SUPERSEDED 2026-09-22 — the symlink is gone and the path is gitignored.** `ls -l
> editor/content` fails on `main` @ `766e0873`, and `.gitignore:110` is `/editor/content`
> (`1e0b10a9`), so `git add -A` can no longer stage it. `pnpm e2e` runs in the primary
> checkout. See "`editor/content` is GONE" at the foot of this file. Everything below is kept
> as the record of the failure mode, in case the symlink is ever re-created.

`editor/content -> /home/user/Projects/recipe-content` (untracked, made 2026-08-31).
Tailwind's automatic source detection follows it out of the project and Turbopack panics
compiling `editor/app/globals.css`: `FileSystemPath("editor").join("../../recipe-content")
leaves the filesystem root`. The dev server reports `Ready` and then FATALs on the first
request, so **`pnpm e2e` in the primary checkout dies before the first spec**. Verified
2026-09-07 on `one-core/phase-0` AND on `main` @ `5ffb0e1` — environmental, not a code
regression. `next build` is unaffected. A `git worktree` of the same commit has no such
symlink and runs the suite normally — **511 passed / 0 failed in 23.8 min** on `1691c4f`,
one worker. A worktree needs one extra step first: its `export/public` holds only the tracked
static assets, so the export webServer 500s and Playwright dies with "Timed out waiting
120000ms from config.webServer". Copy a composed fixture site into it (20 files, ~4.8 MB —
`.claude/worktrees/duplicates-page/export/public` is one) and it serves 200.

**Two ways it follows you into the worktree, both hit on 2026-09-07 (slice 1.3).**
`git add -A editor` from the primary checkout STAGES THE SYMLINK — it is untracked, not
ignored — so a commit made that way carries `editor/content` into every worktree of it and
the panic is back. Add by path, or `git rm --cached editor/content` and amend. And a
worktree under `.claude/worktrees/<name>/` is three levels deeper, so the panic reads
`join("../../../../../recipe-content")` rather than `join("../../recipe-content")` — same
fault, different arithmetic, and a grep for the old string will not find it.

### The bake-off harnesses do not take `--help`

`plans/tools/{digest-bakeoff,attribution-bakeoff,attribution-pilot}.ts` (moved here from
`common/bin/`) ignore unknown flags and **start a real run against the corpus** — the first
opens the LMDB index and writes `plans/bakeoff/round.partial.json`. Run them under
`cd common && pnpm exec tsx ../plans/tools/<name>.ts` only when you mean to. They needed
`common/bin/_lmdb.ts` (a re-export of `open`) because `plans/` is not a workspace package: a
bare `import "lmdb"` resolves from the importing file upward and the repo root's
`node_modules` holds only `tsx`.


## one-core Phase 1 slice 1.4 (2026-09-08) — a lane's pause is a key on the lane

**Supersedes the "four gates, three polarities" half of the 2026-08-28 slice-7 census
above.** That entry is still the right description of what pauses look like from the UI
(one control, one action pair, one polarity known in one file); what changed is WHERE the
answer is stored.

**One key: `autoQueue[lane].held`** (`common/lib/autoQueueTypes.ts`, `AutoQueuePolicy`).
Optional, and **absent is not `false`** — `sanitizePolicy` passes a boolean through and
leaves anything else `undefined`, deliberately, because every settings.json in existence
spells one of the four retired fields and no key, and defaulting it would read a paused
corpus as running.

| retired field | polarity | now |
|---|---|---|
| `transcriptionsPaused` (`settings.ts:156`) | held = true | `autoQueue.transcription.held` |
| `downloadsPaused` (`:161`) | held = true | `autoQueue.download.held` |
| `digest.digestsPaused` (`:452`) | held = true | `autoQueue.digest.held` |
| `backfill.enabled` | **inverted** — held = false | `autoQueue.backfill.held`, not inverted |

All four fields **remain in the type and in their sanitizers**; they are the migration's
INPUT and nothing else reads them. They are deleted in a later slice, once the live
`settings.json` carries all four `held` keys (i.e. after one write through the editor).

- **`isGateHeld(settings, lane)`** reads `settings.autoQueue?.[lane]?.held` and falls back
  to `legacyGateHeld` when it is `undefined`. Both still touch only the named lane's field —
  `laneGuards.test.ts` casts a `{digest}`-only object to `SiteSettings`.
- **`legacyGateHeld` lives in `common/lib/laneMigration.ts`, not in `pauseGates.ts`**, and
  the reason is an import cycle worth remembering: `getSettings` must run the copy on every
  read, and `pauseGates.ts` imports `lib/operations.ts` (for `pauseLaneFor`), which imports
  the controller layer. Putting it in pauseGates would pull the whole operation registry
  into every reader of settings.json — `bin/` scripts, the MCP server, the export build.
- **`withGateHeld` writes the new key only** and spreads the policy. What a rebuilt literal
  would now drop is the lane's TREE, its order and its snooze.
- **`getSettings` copies legacy → `held`** via `migrateHeldToLanes(merged)`, placed AFTER
  `sanitizeDigest`/`sanitizeBackfill` (two of the four fields live in those blocks) and
  therefore not beside `migrateSweepsToLanes`, which runs on the PARSED file. It never
  unholds a lane, returns the input object unchanged when every lane already carries a key,
  and treats `held: false` as an answer rather than an absence.
- **The transcription asymmetry is unchanged.** The stored value is intent;
  `getWorkerPool().isPaused()` is live state; `editor/instrumentation.ts` re-applies the
  pool from `isGateHeld(getSettings(), "transcription")` at boot; no UI surface reads the
  stored value. That is why the e2e fallback proof uses the DIGEST lane — a fixture flag on
  transcription is not observable through any page by design.
- **Only the two operation lanes hold through `limit()`.** `laneLimit` returns
  `{limit: 0, hold: {reason: "paused"}}` for digest and backfill; the download lane's gate
  is asked in `next()` (idle reason `downloads-paused`) and transcription's is the worker
  pool's slot count. One gate, three shapes.
- **Writers.** `withGateHeld` is reached by `pauseLaneAction`/`resumeLaneAction`
  (`operations/actions.ts`) and by `saveBackfillLaneSettingsAction` — the "Run the backfill
  lane" checkbox, still a deliberate second writer of one key, whose `defaultChecked` is now
  `!held` from `isGateHeld`. `saveAutoQueueAction` spells every policy field explicitly and
  therefore carries `held` beside `snoozeUntil` (asserted in `auto-queue.spec.ts`).
  `armLaneAction`, `disarmLaneAction` and `snoozeAutoQueueAction` spread the policy and are
  safe by construction. `settings/actions.ts` and `saveDigestSettingsAction` PRESERVE their
  retired field rather than rebuilding it, because that is what an unmigrated file reads.
- **`AutoQueueReach`, `AUTO_QUEUE_REACHES`, `sanitizeAutoQueueReach` and
  `OrderReach.tsx` are deleted.** The component is `LaneOrder.tsx`; every caller had passed
  `reach={null}` since slice 1.3.

**Numbers: the before/after diff of `plans/tools/phase1-numbers.ts` over the live corpus is
EMPTY** (2,629 lines each), which is a direct test of the fallback: the live file carries
`transcriptionsPaused: true`, `downloadsPaused: false`, `digest.digestsPaused: false`,
`backfill.enabled: true` and no `held` anywhere, and the script's four `held <lane>` lines
still read `true/false/false/false` through `isGateHeld`.

## One-core Phase 1 (verified 2026-09-08) — four lanes, one runner

The whole-phase anchors. The slice-1.4 entry above stays as the detail on where a lane's
pause lives; this is everything else a session needs before touching dispatch. Branch
`one-core/phase-1`, `7f294df` → `81a663f` plus a docs commit, 36 commits, unmerged, off Phase 0's `af2a360`. The
record with every divergence is `plans/one-core-phase-1.md`.

**The model in one sentence:** the LANE is the dispatch noun (a queue key, a policy tree, a
runner, a pause, a console), the OPERATION is the work noun (a registry entry with a state
per video), and a leaf in a lane's tree names channels and, where a lane carries more than
one operation, an operation.

### The four lanes, and which half of the model each draws from

`LANES` / `AutoQueueKind` (`common/lib/autoQueueTypes.ts`) is
`["transcription", "download", "digest", "backfill"]`, and `PauseLane` is an alias of it.
Two of them draw BUCKETS and two draw OPERATIONS, which is the split every function in
`jobs/autoQueuePolicy.ts` keys on:

| lane | draws | its work list |
|---|---|---|
| `download` | buckets | `snapshot.backfill.download.ids` = `partialDownloads` ∪ `undownloadedIds` |
| `transcription` | buckets | `snapshot.backfill.transcription.ids` = `downloadedNoTranscript` ∪ `failedListed` |
| `digest` | operations | `snapshot.backfill.digest.ids` |
| `backfill` | operations | `snapshot.backfill.{diarization,attribution-text,attribution-diarized}.ids` |

- **`bucketsForKind` / `optInBucketsForKind` / `selectableBucketsForKind` return `[]` for the
  operation lanes**, and `operationsForLane` returns `[]` for the bucket lanes — download and
  transcription are `EXTERNAL_OPERATIONS` with no `state()` or `run()`, so there is no
  `Operation` to hand back even though they now have a snapshot entry. The lane asks
  `bucketLaneOperationId(lane)` (`lib/operations.ts`) for its work list's KEY instead; it is
  `pauseLaneFor` read backwards, off the same `ExternalOperation.runner` declaration.
- **`defaultBucketsForPolicy` describes the POPULATION; `defaultDrawsForPolicy` is what the
  runner projects.** The first is what `policyDrawsBucket` asks ("would the runner draw this
  bucket for this channel"). The second returns `[<operation id>, ...optIn if
  replaceAutoSubs]` on a bucket lane — one list, named for the operation, with the opt-in
  auto-captions buckets still strictly at the tail.
- **The lane's work list is projected into `ChannelWork.buckets`, not `.operations`**, and
  that placement is load-bearing. `buildPendingByLeaf` claims a video as
  `${operation}\0${id}`, so an operation draw and a bucket draw are DIFFERENT claim spaces: a
  video an explicit retry-bucket leaf claimed would be claimed a second time by a catch-all
  drawing the operation. On a bucket lane the operation and the union are the same work, so
  it shares the bucket space — and `laneOperationIds` still answers `[]` there, which is why
  `dropCompleted`, `leafOperationIds` and `markCompleted` were untouched by 1.5.
- **`bucketLaneWorkIds(lane, snapshot)`** (`jobs/autoQueuePolicy.ts`) is ONE fold with two
  callers: `generateChannelSnapshot` writes it, and `autoRunner.buildChannelWork` falls back
  to it for a snapshot with no entry. That is the whole migration — **no live snapshot is
  regenerated by 1.5**, so all 68 take the fallback until their next regen, and the two sides
  cannot disagree because they are the same function.
- **`bucketIdsFrom(source, name)`** knows the one asymmetry: `undownloadedIds` is a TOP-LEVEL
  snapshot field and every other bucket is under `snapshot.buckets`.

### Where `held` lives

One key, `autoQueue[lane].held`, absent-is-not-false, with the four retired fields read
through `legacyGateHeld` in `common/lib/laneMigration.ts`. Full detail in the slice-1.4
entry above, including why that function is not in `pauseGates.ts` (an import cycle:
`settings → pauseGates → operations → controller → settings`). **The same cycle is why
`bucketLaneOperationId` is in `lib/operations.ts` while the fold that uses it is in
`jobs/autoQueuePolicy.ts` and takes the name as a parameter** — `lib/settings.ts` imports
`autoQueuePolicy` for its sanitizers, so `autoQueuePolicy` importing `operations` would open
the same door.

### The migration files

- **`common/lib/laneMigration.ts`** — pure, two functions, no I/O.
  `migrateSweepsToLanes(parsed)` runs on the PARSED settings file (absent-from-the-file is
  its trigger, and a merged object can no longer tell absent from default);
  `migrateHeldToLanes(merged)` runs on the MERGED object AFTER `sanitizeDigest` /
  `sanitizeBackfill`, because two of the four fields live in those blocks. Tested in
  `common/jobs/laneMigration.test.ts` — in `jobs/` because `architecture.test.ts` forbids
  `lib/` importing `jobs/` and the migration must be asserted THROUGH `sanitizeAutoQueue`.
- **`laneRootFromScope`** is the ONE leaf builder: `armLaneAction` and the sweep migration
  both call it, so "arm on channels X" and "migrate `sweepChannels: X`" are the same
  function. Its optional `available` collapses a scope naming every operation to `[]`.
- **The migrated leaf ids are `digest-all` / `backfill-all`**, which only that builder
  produces — visible in the numbers diff, which is how the migration was checked on the live
  file rather than asserted.

### `controller/operationBatch.ts` — one executor

Replaces `digestBatch.ts` (647) and `backfillBatch.ts` (937). `openOperationRun` resolves the
engine, the duplicate-cluster plan and the fan-out envelope ONCE PER RUN; `runOperationUnit`
takes that prepared run, not a bag of per-video arguments. `laneLimit(settings, live)` takes
the lane on a tagged `live` union. `runOperationBatch({lane, …})` is one function with one
result type; `runDigestChannelJob` / `runBackfillChannelJob` keep their job kinds and queue
keys and call into it.

Four things in it that only a long-lived runner can break, all already paid for: the metered
spend cap and the disk-floor latch survive the run context's 60 s refresh; the refresh waits
for the lane to be idle and carries the WHOLE `live` object across (`opened.live =
laneRun.run.live`) or a unit settling after the swap leaks a lease; a failed engine open is
covered by the TTL too; and the digest unit calls `digestVideo` rather than `op.run()`
because `OperationRunOutcome` cannot carry a cost and routing it through `run()` would
silently disable the spend cap.

**The `laneFor` trap is closed.** The GPU idle-only rule asks
`laneYieldsToTranscription(laneForOperation(op.id) ?? op.lane)` on `contendsFor`, not on the
field EXISTING. `laneForOperation` (`controller/operationLane.ts`) resolves the registry
first and then `EXTERNAL_OPERATIONS`' declared lanes; **`sync` still resolves `null`** — it
is a per-channel cadence, the same answer `pauseLaneFor` gives it.

### The snapshot memo, and what it is not on

`readChannelSnapshotShared` (`controller/channels.ts`) memoizes the PARSE keyed on
`(mtime, size)`. It exists because `buildChannelWork` runs on the runner's scheduling tick
AND on a three-second status poll folding four lanes — ~6.5 MB of JSON re-parsed eight times
a tick. Measured: the poll is 86–102 ms before the two lanes went live, 386–413 ms after with
no memo, **256 ms with it**. It is deliberately NOT on `readChannelSnapshot`, which the
snapshot GENERATOR calls. `resetChannelSnapshotMemo` is wired into
`/api/test/invalidate-cache`.

### The `cheapest` composition

`digestBatch.ts` sorted by duration and then again, stably, by upload date — so the live
meaning was **date primary, duration as the tiebreak within a day**, the opposite of the
order the two `sort()` calls read in. That is one `cheapestComparator` now, with the date
half fixed at newest-first (`digest.recencyOrder` retired rather than migrated: it was only
the date HALF of a composition). Unknown durations sort LAST. `cheapest` on any other lane is
accepted by the sanitizer and falls back to LISTED — `recencyOrdering` returns a null
comparator, which everywhere in the runner means "do not sort".

### `.auto-queue/state.json` is written WHOLE

`writeAutoQueueState` serializes every lane, so the four runners share ONE in-memory object
on the auto-runner singleton (`sharedAutoQueueState`). Two runners each holding their own
copy meant every persist clobbered the other lanes' pick log and fairness memory — invisible
with one slow lane, immediate with two fast ones. Anything else that read-modify-writes that
file (`jobs/downloadBackoff.ts` does) can still lose picks; a new writer must take the shared
object. Its tmp path carries a per-write counter, not just the pid.

### The band that is folded once

`buildOperationBands` (`editor/app/components/pipelines/buildBands.ts`) folds
`addExternalBands` for download and transcription and `addRegistryEntry` for everything
else — and the registry fold now SKIPS the two external ids. `/channels` passes
`[...EXTERNAL_BAND_IDS, ...allOperations]` in, so once slice 1.5 wrote
`snapshot.backfill.download`, folding it on top of `addExternalBands` doubled every one of
that band's five numbers (a three-video channel read "6 done of 6"). The `/operations` rail
(`operations/lanes.ts`) and the channel page (`channelFlow.ts`) pass registry ids only and
were never affected.

**The bands and the snapshot entries are two different measures and must stay so.** The
band's transcription `reachable` is `downloadedNoTranscript` ALONE — the retry bucket is not
in it, and on the live corpus that is 881 against the lane's 882; its `blocked` is what the
entry calls `missingInput`; its `eligible`/`present` are the playlist and
`totals.downloaded`/`totals.transcribed`. `EXTERNAL_BAND_IDS` is now
`EXTERNAL_OPERATIONS.map(o => o.id)` rather than a hand-written pair.

### A run log lives in the panel's React state, so the panel must not be unmounted (`fae99f1`)

**THE RULE: a component carrying a `StreamActionLog` must not be UNMOUNTED when the record its
own run produced lands.** `StreamActionLog` keeps the streamed log in `useState` and calls
`router.refresh()` itself the moment a run ends (`common/components/StreamActionLog.tsx:156-163`).
That refresh re-renders the SERVER component that draws the panel — with the sidecar the run
just wrote now on disk. Unmount it in that render and the log is not stale, it is GONE: with
`log` empty and `running` false the component renders no `<pre role="log">` at all. Two ways
that happens, and the rule has to cover both.

**Moved unkeyed across a differing sibling shape.** `SpeakerBodies.tsx` returned
`[empty state, RunOne]` before a record and `[dl, (ul,) p, RunOne]` after. Static JSX fragment
children compile to ONE array, so `reconcileChildrenArray` runs: the index fast-loop breaks at
0 (`p` vs `dl`), and the map pass then looks up index 1 and finds `ul`/`p` where `RunOne` used
to be — **a positional TYPE MISMATCH is what destroyed it, not the move itself**. React
preserves state across a keyed move: a `key` alone would have matched the old `RunOne` fiber at
its new index with state intact, and a fixed position alone would never have reached the map
pass. Either was sufficient; the fix ships both — the record body is a sibling of the button
and `<RunOne key="run-one" …>` is last in both branches
(`editor/app/channels/[slug]/videos/[id]/components/SpeakerBodies.tsx:86-99,166-179`).
`DigestBody.tsx:71-131` was already written that way (one return, one ternary, the log at a
fixed index); only the speaker panels were under a spec that could see it, which is why only
they flaked — `attribution.spec.ts:346`, 1-2 runs in 10, for a batch that had finished in 65 ms
with every line written.

**Dropped by a parent branch swap** — same effect, different mechanism. `VideoPanel.tsx` had
four instances, and **every known instance on the video page is closed as of `12d1778`**
(`c19098b` + follow-ups): `SourceVideoSection` early-returned the persisted view once
`savedVideo` was truthy, `IncompleteTranscriptBanner` and `ShortAudioBanner` were dropped by
the parent when the run cleared the condition that drew them, and `PerFileTranscribeRow`
swapped its panel for "Transcribe disabled — transcript already present." when its own run
wrote transcript.json (`hasTranscript` is server-derived at `VideoPanel.tsx:360`; since
slice 3b, `VideoPanel.tsx:122` on `e172749b`).

**THE SHAPE TO COPY** is the same in all four and is what a fifth should be written as: the
parent renders the component unconditionally and passes the CONDITION down; the component holds
a `ranHere` flag set inside the `trigger` it hands `StreamActionLog`, returns null only while
`!condition && !ranHere`, puts the message and the run panel in two FIXED slots (the panel last
and keyed), and passes the now-cleared condition to `StreamActionLog`'s existing `disabled`
prop — so the panel that stays for its log is not a second Run button
(`VideoPanel.tsx:1085-1120` persist, `1550-1588` incomplete, `1638-1670` short-audio,
`729-756` the transcribe row, at `12d1778`; since slice 3b each is its own file under
`videos/[id]/components/cards/`: `SourceVideoSection.tsx:38,64`,
`IncompleteTranscriptBanner.tsx:38-39`, `ShortAudioBanner.tsx:40-41`,
`PerFileTranscribeRow.tsx:39,62` on `e172749b`). A banner's
`role="alert"` and warning aria-label are spread conditionally on that same condition, so the
box that outlives the warning stops answering `getByLabel("incomplete transcript")` —
`truncated-check.spec.ts:69` asserts exactly that. `PerFileTranscodeRow` (`:810` at `12d1778`)
(`cards/PerFileTranscodeRow.tsx:39` since 3b) is NOT an instance: its `return null` depends on the file's extension against a static format
list, which a transcode cannot change, and the rows are keyed by file name.

**On the channel page, the bucket cards** (release 11 slice O3, `86449b88`): `RetryBucketControl`
and the Download stage's three bucket cards (`NoTranscriptList`, `PartialDownloadsList`,
`NeedsCookiesList`) returned null on an empty bucket, and a retry EMPTIES its own bucket. What hands
the card its emptied bucket is not only the end-of-run refresh: `recordTaskDone` →
`requestSnapshotOnFinish` (`common/jobs/streamCommand.ts`) regenerates the snapshot after EACH video
a batch finishes, the pulse moves, and `AutoRefresh` refreshes the page MID-RUN. Now the shape
above: `ranHere` set in the trigger (and `onRun` to tell the card), null only while
`ids.length === 0 && !ranHere`, `disabled={ids.length === 0}` (`RetryBucketControl.tsx:60-84`,
`DownloadStage.tsx:357,404,454`). `cookies-mode.spec.ts:241` waits for the refreshed EMPTY card
(`needs cookies empty`), which makes the old race certain rather than likely. The Transcribe
stage's Fetch audio control is covered too (its section stays while `autoSubsCount > 0`). **NOT
Diagnostics:** its two grids drop an emptied bucket's card before the control renders
(`DiagnosticsStage.tsx:156` `populated`, `:694` `listed`), so a Diagnostics retry that empties its
bucket still loses its log — open. **Closed in release 13 slice W1:** both grids keep a card whose
Retry ran on the page — a `ran` set (`useRanBuckets` in `DiagnosticsStage.tsx`), filled by
`RetryBucketControl`'s `onRun`, keyed by the card's aria label (channel health) or status
(availability); `AvailabilitySummary`'s hook sits above its `total === 0` return, which yields to
a ran card. `diagnostics-retry-log.spec.ts` waits for the refreshed EMPTY list in each grid. An
availability bucket is never emptied by its own retry (a download records availability history
only, `updateTopLevel: false`); a probe landing mid-run empties it.

The persist case needed a fixture: `editor/e2e/fixtures/bin/fake-ytdlp.mjs:680-725` (at
`12d1778`) grows an app-extraction branch — the LAST branch checked, matched on the media
output template naming `source-media` (only `plan.extractionMode === "app"` emits that), which
writes `data/<id>/source-media.mp4` plus `metadata.info.json` when absent so
`finalizeAppExtraction` has a container to extract and persist. Without it that invocation fell
through to "unknown invocation", exit 2, and no pointer ever landed.

The full trace, and why five of the plan's hypotheses — H1's mechanism included — were all
killed by it, is in `plans/deflake-e2e.md`'s "4, as shipped".

### The `editor/content` symlink still blocks e2e in the primary checkout

> **SUPERSEDED 2026-09-22 — it does not.** The symlink is absent and `/editor/content` is in
> `.gitignore` (`1e0b10a9`). See "`editor/content` is GONE" at the foot of this file.

Unchanged from the Phase 0 entry, plus one thing Phase 1 learned twice: **`git add -A` stages
it** (it is untracked, not ignored), which carries the Turbopack panic into every worktree of
that commit. Add by path. A worktree also needs a composed fixture site copied into its
`export/public` or the export webServer 500s and Playwright times out at 120 s.

### A channel's media may be on another drive (verified 2026-09-11, branch `storage/relocate-media`)

`channels/<slug>/data` may be an **absolute symlink** to `<root>/<slug>/data` with
`config.dataDir` recording the target (`common/lib/channelConfig.ts`, written only by the
relocate job), and the `<slug>/data` suffix is fixed rather than configurable
(`relocatedDataDir`, `common/lib/channelMedia.ts:102`) so an empty mountpoint can never be
mistaken for the media and `deleteChannel`/`renameChannel` can recognise a target by shape.
**No reader changed**: the on-disk contract `channelDir/data/<id>/…` is what yt-dlp's
cwd-relative writes, the LMDB index (mtimes, which `rsync -a` preserves) and the export build
already use, and the only `lstat`/`readlink`/`realpath`/`symlink` calls anywhere in `common/`,
`editor/` or `export/` are in `channelMedia.ts`, `relocateChannelMedia.ts` and
`renameChannel.ts` — every other hit is a comment or a test. What that buys
in call-site churn it owes in one failure mode — a dangling link reads as ENOENT and every
enumerator swallows ENOENT as "this channel has no videos", which to a runner means
*everything is undownloaded* — so `inspectChannelMedia` (`channelMedia.ts:191`, two stats and
at most one small JSON read: `in-place` / `ok` / `unreachable` / `in-transition` /
`inconsistent`) and `assertChannelMediaReachable` (`:319`, only the first two pass) are the one
place that can tell the two apart, and **four guards plus one bypass** call them:
`runManagedFunction` refuses before any job record exists (`common/jobs/streamCommand.ts:277`
and `:292`) for a kind that declares `needsMedia` — **opt-in, absent means false**
(`common/jobs/jobKinds.ts:60`, `kindNeedsMedia` at `:464`), so an unlisted kind behaves exactly
as it did before the guard and `relocate-channel-media` writes `false` out because it is the
thing that fixes an unreachable channel; the four lane runners skip the channel and keep
running every other one (`common/controller/autoRunner.ts:370-386`, three syscalls per channel
per tick, the parsed config passed in so it is not a 69th config read); snapshot generation
throws rather than write a snapshot saying every video is undownloaded
(`common/controller/channelSnapshot.ts:607-619` — the scheduler keeps the last good
`snapshot.json` on a failed refresh); `runOperationBatch` asks before deciding the candidate
list for both operation lanes (`common/controller/operationBatch.ts:1580-1585`), as does
`normalizeAllTranscripts` (`common/controller/normalizeAll.ts:63`, which skips and counts a
failure rather than reporting a clean 0/0/0/0); and the ONE path with no job record,
`saveShardConfigAction` (`editor/app/channels/[slug]/shardActions.ts:88`), asks at the top for
all three of its branches. The low-disk gate is now **per volume**: `diskGate(paths, settings,
{ mode, dir })` defaults `dir` to `paths.transcriptsDir` and six media callers pass the
channel's own `data` path, the hysteresis latch is a `Map<dir, boolean>`
(`common/lib/diskSpace.ts:215`, `diskGate` at `:243`, `isDiskGateLatched(dir?)` at `:286` —
no-arg answers for ANY volume), and `getFreeBytes` (`:29`) **walks up to the nearest existing
ancestor on ENOENT only**, because `channels/<slug>/data` does not exist until a channel's
first download and the old fail-open Infinity waved that download through; every other errno
still fails open. `autoRunner`'s lane-level gate deliberately keeps the corpus volume — it runs
before the pick, so there is no channel yet. **A relocation root is contained by rule, not by
hint**: `relocationRootProblem` (`common/controller/relocateChannelMedia.ts:169`, asked by the
preview, the action and the job — `:387`, `:491`) refuses blank, relative, inside the corpus,
and a root whose `<slug>` level resolves back into the channel dir, comparing REAL paths and
resolving the target separately from the root; without it `root = <transcriptsDir>/channels`
makes the source its own target, `rsync -a src/ src/` succeeds, the verify compares the tree
with itself, and the reclaim deletes the only copy. **Every relocation in the process runs on ONE queue**, `relocationQueueKey()` =
`"relocate"` (`common/lib/queueKeys.ts`), set by the single enqueue both the Storage panel and
the `/channels` bulk move share (`editor/app/channels/lib/relocationJob.ts`) — because
`registry.ts` caps a queue key at concurrency 1 and caps nothing across keys, so a per-channel
key would start every selected channel's rsync at once onto one destination volume and each
job's start-time space check would be credited room the others had already claimed.
Serializing a move against the channel's OWN jobs is done by refusal, not by the queue: both
actions reject a channel with running or queued jobs before they enqueue.
`channels/<slug>/.relocating.json`
(`channelMedia.ts:40`) is the in-flight marker: present means "in transition" to every guard,
its `phase` is what lets an interrupted move resume, `deleteChannel` and `renameChannel` refuse
while it exists, and `clearRelocationMarker` (`:160`) removes it and nothing else.
### Release 17 slice T1 — the media tier's model, and which guard holds what (2026-10-01)

Supersedes, where they differ, the facts in the section above and in "The index build's hold",
"`cues.mjs` carries a reachability twin" and the drive-health notes below; those passages are kept
as they were measured.
- **The model.** A big file — `isTierable(name)`: `audio.<ext>` and `transcript.live_chat.json`, never
  `source-media.*` or a partial (`common/lib/mediaTier.ts`, pure; `classifyEntry` is media / text /
  scratch by NAME) — may be a RELATIVE link `data/<id>/<name> -> ../../media/<id>/<name>`;
  `channels/<slug>/media` is a real dir (tiered in place), ONE absolute link to `<root>/<slug>/media`
  recorded as `config.mediaDir` (relocated), or absent (classic). `data/` is always a real dir on the
  corpus disk. The hook (`tierMediaFile` & co., `lib/mediaTier-server.ts`) is called after every
  media finalisation (transcode, both download-outcome writes, a batch `runYtdlp` mode, a live-chat
  normalize that wrote — not the export build's archive pass) and never throws; the bytes are placed by
  a hard link (same disk) or an atomic copy before one rename swaps the name, so a crash never leaves the
  name missing; the link carries the file's mtime (`lutimes`), and the
  live-chat freshness check and the index's sub-track key (`subsMs`) `lstat` a tierable name, so the
  index's scan never reaches the media drive; when a tiered live chat's cues are stale the index reads
  the raw only while the channel's media is `ok`/`in-place` — one `stat` probe through `onDrive(mediaDir)`
  (the watchdog's budget is sized for a stat), then a direct read — and otherwise keeps the cues the last
  build held, or, with none, stores `subsMs: null` so the next build retries (`buildIndex.test.ts` (k): a
  stalled drive, nothing asked of it; (l): the retry).
  An EXDEV tier gives the copy the file's times, so `stat` and `lstat` agree. Every deleter of
  a video-dir entry goes through `removeMediaFile` / `removeVideoDirMedia`.
- **`inspectChannelMedia`** now describes the `media` link + `mediaDir`, returns `mediaLink` and
  `text: { dir, readable }`, and has a seventh status, **`legacy`**: a `data` link or a recorded
  `dataDir` (the retired whole-directory layout), answered without a call to the far drive, text
  unreadable. Memo key: slug + `mediaDir` + `dataDir`.
- **Two guards.** `assertChannelMediaReachable` (only `ok`/`in-place` pass) for a kind with
  `needsMedia` ("opens or writes the BIG file"); `assertChannelTextReadable` (passes unless `legacy`,
  `data/` not a dir, or a marker with `scope: "tier-migration"`) for a kind with the new `needsText`
  (14 kinds flipped, pinned in `jobs/jobKinds.test.ts`). `runManagedFunction` asks the one the kind
  declares, at enqueue and at start.
- **Who is held by what.** The index and stats builds, the snapshot, `normalizeAllTranscripts`,
  `saveShardConfigAction`, clip eviction and the digest batch read the TEXT tier and hold only on an
  unreadable text tier; the digest lane holds on `isTextHeld` (= `legacy`) or unreadable text
  (`isChannelHeldForLane`, `controller/autoRunner.ts`); transcription, download and backfill lanes,
  the backfill batch and `normalizeAllLiveChat` keep the media hold. A media move's marker
  (`scope` absent or `"media"`) holds media writers only; `channelWriters(slug, { mediaOnly })`
  answers that set.
- **The snapshot's bytes** are three siblings: `totalMediaBytes` (tierable names, through one
  `onDrive(mediaDir)` per video for the links; ABSENT, with `totalAudioBytes`, when the media tier
  could not be read), `totalTextBytes` (new), `totalClipsBytes` (no longer inside media).
- **`onDrive` by file kind.** `channelMediaStall` keys on `mediaDir` (else the retired `dataDir`);
  `channelTextStall` on the retired `dataDir` only. `readChannelStat` and the recency tail reads pass
  a drive only for a legacy channel. `rootOfUnknownPath` strips `<root>/<slug>/media` and `/data`.


### Release 17 slice T2 — the mover over `media/`, and the surfaces (2026-10-02)

Supersedes, where they differ, the mover and storage-location facts above (the whole-`data/` move,
`relocatedDataDir`, `config.dataDir` as the location key).
- **The mover's unit is `channels/<slug>/media`** (`controller/relocateChannelMedia.ts`). Out: the
  job's first step asks the writers, then a classic channel is tiered in place
  (`tierChannelMedia(paths, slug, { createMediaDir: true })`, only in the `copy` phase — a resumed run
  tiers nothing, its marker stands), then `media/` is measured, copied to `<root>/<slug>/media`
  (`relocatedMediaDir`), mirrored and verified, renamed to `media.relocated-<ts>`, replaced by ONE
  absolute link, and `config.mediaDir` written. Back: `<root>/<slug>/media` → `media.incoming` → the
  link swapped for the real dir, `mediaDir` unset; the per-file links are never rewritten. The marker
  carries `scope: "media"` (and `readDirMarker` now keeps a `scope` it reads). Refused before anything:
  a `legacy` channel (a `data` link or `config.dataDir`, the sentence names `archilyzer storage
  migrate-tier <slug>`) and a marker with `scope: "tier-migration"`. `rootOfRelocatedMediaDir`
  replaces `rootOfRelocatedDataDir`; `relocatedDataDir` (`lib/channelMedia.ts`) is kept only as the
  retired shape for the migration and the tests. The containment check resolves the deepest EXISTING
  ancestor of `<root>/<slug>/media` (it usually does not exist yet), so a `<slug>` level linked back
  into the channel dir is still refused before the preview tiers anything.
- **The preview tiers too** — an in-place channel with a `data/`, no marker — and reports
  `tieredFirst`; a second preview tiers nothing. The result carries `tiered`, and the job's done line
  says "(N file(s) tiered first)".
- **A move is held by the channel's MEDIA writers only.** `channelMediaWriters(slug, opts)`
  (`relocateChannelMedia.ts`) = `channelWriters` minus every job whose kind is not `needsMedia` —
  except `relocate-channel-media` itself (its kind is not `needsMedia`, and must not be, but it is the
  thing writing into `media/`) — minus the digest lane's units. The job's first step (ignoring its own
  kind), the third ask under the marker, the preview, and the editor's
  `channelMediaBusyReason(slug, what, { mediaOnly: true })` for Move, Move back, Resume, Reconcile,
  Clear marker, the bulk move and the panel's blocked line ask it. Rename and delete still ask every
  writer.
- **Location membership keys on `config.mediaDir`, or a legacy channel's retired `dataDir`**:
  `channelsOnLocation` (with `textBytes`, `unknownTextBytes` and a `legacy` count inside
  `unreachable`), `channelVolumeOf(config, locations)` (now takes the config), the storage watch (one
  auto-pause per channel, as before), `deleteChannel` (removes both targets). The re-point rewrites the
  `media` link and `mediaDir`, and a legacy channel on the same location the RETIRED way — its `data`
  link and `dataDir` to `relocatedDataDir(newRoot, slug)`, in the same ledger and rollback
  (`RepointPreflight.legacy`), so `dataDir` is always `<root>/<slug>/data` for the tier migration. The
  rename moves a convention-shaped `<root>/<slug>/media` and re-points the `media` link; it REFUSES a
  legacy channel (`migrate-tier`), for the same invariant. `tierMigrationRefusal` (exported from the
  mover) is the one sentence the job, the preview, Resume/Reconcile and Clear marker refuse a
  `scope: "tier-migration"` marker with.
- **`/storage` bytes.** A location row's figure is its channels' `totalMediaBytes` (the media tier),
  with no clips (`clipsBytes` 0 there); the internal row is in-place media + every channel's
  `totalTextBytes` + `totalClipsBytes` (`internal.corpus`, folded in `editor/app/storage/buildStorage.ts`;
  a report with no text figure counts unmeasured, once per channel; a legacy channel is left out of the
  sums and named "legacy (n to migrate)") with the breakdown in `tiersText`
  (`aria-label="location tier bytes"`). `channelsText` adds "(n to migrate)".
- **The two video pages read the text on the corpus disk.** They gate on `channelTextStall` (a legacy
  channel only), not `channelMediaStall`, and list a directory through ONE loader,
  `loadVideoDirFiles(videoDir, mediaDir)` (`editor/app/channels/[slug]/lib/videoDirFiles.ts`): links
  are listed (a dirent `isFile()` hid them), a link's time is its `lstat` (the hook copies the file's
  times onto it), and the media links' sizes are asked of the media drive in ONE `onDrive(mediaDir)`
  call; unreachable → `VideoFile.size: null`, rendered "— (media drive not reachable)".
- **The file route picks the drive by where the file is**: a link (`lstat`) with an `isTierable` name
  → `mediaDir`; anything else, `source-media.*` included, the corpus disk (a legacy channel's retired
  `dataDir` for both). It answers **503 with `retry-after: 15`** when the stat of such a link fails AND
  the channel has `mediaDir` — a tiered file whose drive is away; a dangling link on an in-place
  `media/` is a missing file, 404. `deleteVideoFileAction` refuses the first (unlinking alone would
  orphan the bytes) and removes the second.
- **The live-chat archive (export build) reads no raw replay while the channel's media is not
  `ok`/`in-place`**: it stages the cues on disk as they are (`isLiveChatCuesFresh` `lstat`s the link)
  and logs how many are older than their replay and how many videos with a raw replay and no cues it
  left out; it never drops the channel.
- **`noCorpusWalkInRenderPaths.test.ts` greps render-path files for the walkers' NAMES**, comments
  included: naming `measureTree` in a comment of a file a page imports fails it.

### A channel's media is tiered — the model, the hook, the guards, the migration (release 17, verified 2026-10-02)

The whole of release 17's storage model in one place; the T1 and T2 sections above carry the detail
and the measurements.
- **The model.** `channels/<slug>/data/` is ALWAYS a real directory on the corpus disk and holds the
  text: transcripts, cues, `metadata.info.json`, every sidecar, `clips/` (never tiered), scratch, and
  `source-media.*` (the saved-video store renames it, so it is never a link). A tierable file
  (`isTierable`: `audio.<ext>`, `transcript.live_chat.json`) may be a RELATIVE link
  `data/<id>/<name> -> ../../media/<id>/<name>` carrying the file's times. `channels/<slug>/media` is a
  real dir (tiered in place), ONE absolute link to `<root>/<slug>/media` with `config.mediaDir`
  (relocated), or absent (classic). Classification is BY NAME (`lib/mediaTier.ts`, pure).
- **The hook** (`lib/mediaTier-server.ts`): `tierMediaFile`/`tierVideoDir`/`tierChannelMedia` after every
  media finalisation, never throwing; `removeMediaFile`/`removeVideoDirMedia` for every delete. It writes
  nothing while a marker stands.
- **The guards** (`lib/channelMedia.ts`): `assertChannelMediaReachable` for a kind with `needsMedia`,
  `assertChannelTextReadable` for one with `needsText`; statuses `in-place | ok | unreachable |
  in-transition | inconsistent | stalled | legacy`. A `media`-scoped marker holds media writers only; a
  `tier-migration` marker holds the text too.
- **The mover** (`controller/relocateChannelMedia.ts`) moves `media/` only, tiering a classic channel
  first; it refuses a `legacy` channel and a `tier-migration` marker with `tierMigrationRefusal`.
- **`legacy`** = `config.dataDir` recorded or `data/` a link: the pre-release-17 whole-directory move.
  T2's re-point and rename keep `dataDir` = `<root>/<slug>/data` (rename refuses a legacy channel), so the
  migration may derive everything from that shape.
- **The migration** (`common/bin/migrate-media-tier.ts`, `archilyzer storage migrate-tier
  <slug>…|--all`, release 17 slice T3). Editor STOPPED: a real run refuses while
  `<ARCHILYZER_EDITOR_URL>/api/pulse` answers (a timeout counts as running) or a `running`/`queued` meta in
  `.jobs/` belongs to a live pid that is not its own (a pid-less `running` meta written after the
  machine booted counts too; files older than the boot are not read); a dry run only notes it and writes
  nothing. Per channel: the plan reads the corpus disk (config, `data` link, marker) — a marker whose
  `scope` is not `tier-migration` is refused, `dataDir` must be `<root>/<slug>/data` and agree with the
  link, `mediaDir` must be absent; preflight: the old tree is a directory, `assertRelocationRootPresent`,
  `<root>/<slug>/media` and `channels/<slug>/media` absent, one walk classifying every video dir's entries
  (a tierable REGULAR file stays; a postprocessor's dead `*.temp.*` — `isLeftOnPlatter` — stays too,
  unlinked; everything else is listed), the space rule `copy bytes − bytes already
  in data.incoming + margin ≤ free(channelsDir) − minFreeDiskGB` (margin 0 when the gate is off, the
  mover's rule); copy: marker `{target: <root>/<slug>/media, direction: "out", phase: "copy", scope:
  "tier-migration"}`, the NUL list at `channels/<slug>/.tier-migration.files`, `rsync -a -r --from0
  --files-from=… --partial --info=progress2` into `channels/<slug>/data.incoming/` (`-r` explicitly:
  `--files-from` turns off `-a`'s recursion and `clips/` is a directory), verify = the same list's
  `--dry-run --itemize-changes` empty (a `.d..t` directory-time line is not content) AND per-kind
  (`text | clips | scratch | source`) files and bytes equal, then a link per tierable file
  (EEXIST = already, if it is the same link) with `lutimes` to the file's times; marker → `swap`;
  swap: platter rename `data → media`, the `media` link, unlink the old `data` link, rename
  `data.incoming → data`, `patchChannelConfig(slug, { mediaDir }, { unset: ["dataDir"] })` — each step
  `linkOrDirState`s first, so a rerun after a kill at any point finishes; the swap leaves
  `channels/<slug>/.tier-migration.reclaim` (the reclaim note); `--reclaim` (marker phase `reclaim`, only
  on a channel carrying the note — a named slug without it is refused, `--all --reclaim` takes only those):
  in `<root>/<slug>/media/<id>/` a tierable regular file stays, a dead `*.temp.*` goes, and any other entry
  goes only when one `lstat` finds its twin at `channels/<slug>/data/<id>/<name>` (a dir for a dir, else the
  same size) — the rest is kept and listed; an emptied dir goes; the note is removed. Done: marker cleared,
  the channel must then inspect `ok`. A channel on the new layout is a no-op. `--all` = every legacy channel plus any carrying a
  `tier-migration` marker (those first), smallest copy first, the three big-text channels
  (`LARGE_TEXT_CHANNELS`: omnibased, rekietalaw, the-quartering-rumble) deferred with the free space and
  each one's copy bytes (from the ordering walk) printed unless `--include-large`; a real run stops at the first channel it cannot
  finish, a dry run reports every channel and projects the space the earlier ones would take. No index
  rebuild: `buildIndex` over a migrated fixture reports 0 added, 0 changed, 0 removed
  (`bin/migrate-media-tier.test.ts`). `purge-superseded-auto-subs` is `needsText`, so it is refused on a
  legacy channel and runs AFTER the migration. `.syncthing.<name>.tmp` is scratch (`lib/mediaTier.ts`).

## Channel priority (verified 2026-09-11) — one tier per channel, four compiled trees

Branch `channel-priority/s5`, off S0's `28bfee3`, merging `s1`–`s4` and closing the twelve
review findings. Unmerged; every line:number below is at `d487519`. The plan and its "as
shipped" record are [`channel-priority.md`](channel-priority.md).

**The model is `settings.channelPriority` (`common/lib/channelPriority.ts`): one focus
selector plus a sparse map of channels that differ from the default — a `tier`
(`normal|low|paused`), an optional `rank`, and a per-operation `overrides` map over the five
`PRIORITY_OPERATIONS` (`sync` plus the four lanes). It COMPILES, it is not consulted.**
`compileLaneRoot` (`:486`) turns it into a lane's `AutoQueueGroup` — `prio-focus` >
`prio-normal` > `prio-low` > `prio-all`, all strict — and the ordinary engine dispatches over
it, so `buildPendingByLeaf`, `selectNextWork`, `laneLimit`, `pauseGates` and every `held` key
are untouched. A focus holds the rest because strict descent already does that, re-asked on
every grant.

- **`isDefaultChannelPriority` (`channelPriority.ts:350`) is the whole bypass.** No focus and
  no channel entry means the compiler never runs and the stored trees stand byte for byte. It
  lives in the MODEL, not in the runner, because five callers in two packages ask it and a
  controller cannot import the runner without an import cycle (`backfillReacquire` does).
- **`laneDispatchRoot` (`controller/autoRunner.ts:441`) is the one answer to "which tree does
  this lane dispatch from".** The runner loop and `computeLeafPending` call it, and so does the
  editor's status payload (`editor/app/operations/channelPriorityView.ts`) — a console that
  compiled its own would be a second compiler that merely agrees. It takes a
  `PriorityDispatchContext` (`{model, focusSlugs}`), which is the widened shape that let the
  editor pass its own resolution in.
- **`priorityContextFor(paths, settings)` (`:400`) caches the resolved focus on a 60 s TTL
  keyed by `(document, sitesDir)`.** The TTL is not a memo: a `{kind:"site"}` focus tracks the
  site's `channels[]`, so a channel added to the focused site joins the focus with no settings
  write. Only a site focus reads the sites directory. The settings object is a PARAMETER —
  both call sites already hold it.
- **Paused is a filter on the channel LIST, not a tree shape.** `listChannelMeta(paths, kind,
  model)` (`:315`) drops `isChannelPaused(model, slug, kind)` — the EFFECTIVE tier for the lane
  being listed — and it is the single source of that list for both the runner loop and the
  status panel. A tree cannot express exclusion: a catch-all matches everything.
- **`siteChannelIndex(paths)` (`lib/site.ts:324`) is the one spelling of "siteId -> slugs".**
  It was inlined four times (runner, sync tick, writer, status payload).

**ONE WRITER, and since this slice that means `root` too.** `saveChannelPriorityAction`
(`editor/app/channels/actions.ts:761`) is the only function that writes
`settings.channelPriority`, and it recompiles the four roots in the same `writeSettings` call,
spreading each policy so `held`, `snoozeUntil`, `enabled`, `order` and `maxWorkers` survive.
Three actions that used to write a root no longer may while a model exists:
`saveAutoQueueAction` and `armLaneAction`-with-a-scope refuse server-side with a message
naming `/channels` (S4's read-only `PolicyTreeEditor` is the courtesy; this is the rule), and
`prioritizeChannelDownloadAction` is a priority EDIT (`{kind:"promote"}`) that takes the first
rank and shifts the rest. `createChannel`/`deleteChannel` recompile through the same writer.
The writer takes one option, `enableLanes`, because "Add to the top of the download queue"
has always meant prioritise AND switch on, and two writes would race on one settings file.

**THE SEEDING RULE, and it is what keeps a hand-made order alive.** The bypass is
all-or-nothing, so the first click that makes a document non-default also stops the stored
trees being dispatched from — and a hand-made lane order lives ONLY in those trees. So when
the stored document is default AND `hasCompiledLaneRoots(settings.autoQueue)` is false
(`channelPriority.ts:682` — `prio-*` ids are produced by the compiler and nothing else), the
writer seeds from `channelPriorityFromLegacy` (`:748`) and applies the edit on top. Never on a
`recompile`: creating a channel is not a statement about priority. A DEFAULT document compiles
nothing, matching the runner's own bypass — clearing the last priority must not overwrite the
stored trees with an all-normal compile.

**`channelPriorityFromLegacy` renumbers DENSELY and is idempotent.** Merging the two lane
orders by "the lower index wins" produces collisions (four pairs live), and a collision falls
through to `orderWithin`'s slug fallback — neither lane's order. Tie rule: merged index, then
the TRANSCRIPTION lane's own order, then slug. And it returns the stored document untouched
once any root carries a `prio-*` id, because compiled channel leaves ARE bare channel leaves
and a second run would otherwise re-derive the order from the tree that order produced.

**A HOLD IS NEVER A STOP, and `backfillReacquire.decideKeep` (`:392`) is where that nearly
became data loss.** It asked `policyDrawsBucket` on the stored transcription root; on the
compiled root a channel paused for transcription has NO LEAF, so the honest reading answers
"no-leaf" for exactly the channels just put on hold and unlinks their re-acquired audio. The
pause is now asked FIRST and KEEPS (reason `"paused"`), below only "nothing landed" and "not
this bucket's shape"; the leaf question is then asked of the compiled root, built for that one
slug — which tier group holds a channel changes the order, never whether a leaf draws a bucket.

**`excludeFromSync` is DELETED** — field, sanitizer clause, action, toggle, and both legacy
skips in `syncScheduler.ts` (`:132`, `:259`), `syncAllChannelsAction` and `stationWorkFor`.
`isChannelPaused(model, slug, "sync")` is the one question all five ask. `parseChannelConfig`
DROPS the key rather than carrying it, so an un-migrated config parses to a channel that says
nothing about sync and therefore syncs — which is what it did before the flag existed. That is
why `common/bin/migrate-channel-priority.ts` reads the raw `config.json` for the flag, and why
the editor's legacy seed passes `{}`: the seed is after the lane ORDER, not the flag.
`excludeFromBuild` and `excludeFromCleanup` are untouched — different axes.

**The live corpus, measured through the migration's `--dry-run` against a read-only copy of
`settings.json`:** 68 channels, 28 entries, 14 ranked (dense 0–13, `quartering-live` first),
15 carrying `overrides: {sync:"paused"}`, no focus, every base tier `normal`. All four
compiled roots are `prio-normal(68) > prio-all`. No lane's membership moves; only the `sync`
operation loses anyone.

## The storage + priority integration (verified 2026-09-12) — where the two branches collide

`integrate/2026-09-storage-priority` off `e74f005`: `storage/relocate-media` first (branched
at `4059dad` = `e74f005^`, so it conflicts only in `plans/STATE.md`), then
`channel-priority/s5`, which conflicts in six files. Five of the six are "keep both, relocate
first". **The two that are not a union are below, and the next branch to touch `/channels` or
the runner's channel list lands in the same two slots.**

### `listChannelMeta` returns `{ meta, slugs }`, filters paused, and carries the config

`common/controller/autoRunner.ts`. The merged signature is
`listChannelMeta(paths, kind, priority): Promise<{ meta: ChannelMeta[]; slugs: string[] }>`,
and all three of its properties are load-bearing, one from each branch:

- **`{ meta, slugs }`, not an array** (priority). `slugs` is the PRE-FILTER list, because it
  is an EXISTENCE filter for the focus resolver: filtering it would drop a focused channel the
  lane happens to have paused and make the runner's "M channels held" line disagree with the
  banner, which resolves against every channel.
- **The paused filter is per lane** (priority), `isChannelPaused(priority, slug, kind)` — the
  EFFECTIVE tier for the lane being listed, so `{tier:"normal", overrides:{sync:"paused"}}`
  is still drawn by the download lane. Paused is a filter on the channel LIST, never a shape
  in the tree.
- **`config: ChannelConfig` stays on each meta entry** (relocate). `ChannelMeta` carries the
  parsed config purely so the media guard can call
  `inspectChannelMedia(paths, m.slug, m.config)` without re-reading 68 `config.json` files on
  every tick of four lanes and on every three-second status poll — `listChannelConfigs` has
  already parsed them. A resolution that dropped the field would compile as soon as the guard
  re-read the config, and would cost 68 reads per tick to do it.

### `ChannelsTable` ends in TWO sibling bulk bars, storage first

`editor/app/channels/components/ChannelsTable.tsx`. Both branches appended a bulk bar after
`</table>`, in the same slot, each with its own props — `ChannelStorageBulkBar` takes
`defaultRoot`, `ChannelBulkBar` does not. A naive union of the conflict hunk produces ONE
element carrying both bars' props (tsc: duplicate props) and, fixed the obvious way, silently
drops a bar. The shape is:

```tsx
<ChannelStorageBulkBar slugs={selectedSlugs} onClear={…} defaultRoot={defaultMediaRoot} />
<ChannelBulkBar slugs={selectedSlugs} onClear={…} />
```

Both branches had ALSO, independently, added the same select-checkbox column and the same
`selected`/`selectedSlugs`/`toggleOne` state — identical text, so git merged it to one copy,
and `colSpan` is `10 + columns.length` from both sides rather than 11. The header is
checkbox · Slug · Name · Handling · Build · Tier · Playlist · Last sync · Report · pipelines ·
Actions; priority replaced the Sync column with Tier, so the fixed count moved by exactly the
one column the selection added. `editor/app/channels/page.tsx` feeds both halves: a row
carries `media:` AND `priority:`, and the table takes `defaultMediaRoot` AND
`sites`/`focusLabel`.

## one-core Phase 2 (verified 2026-09-12, branch `integrate/2026-09-storage-priority`)

Five slices merged onto the integration tip in order — `7f86aef` S1, `b7a351c` S2b,
`858aabc` S2c, `9026007` S3, `bd3d4ec` S2a. The seams below are what Phase 3 lands on;
every path was re-read at `bd3d4ec`.

### `common/lib/archive/` — eight modules, and what each owns

| file | owns |
|---|---|
| `contract.ts` | `CONTRACT`, `pageFileName`, `ARCHIVE_TREES`, `PER_CHANNEL_TREES`, `ROOT_FILES`, the URL builders (`corpusUrl`, `manifestUrl`, `treeManifestUrl`, `pageUrl`, `rootFileUrl`), `shipsPwa`, and the hub entry types (`HubMemberInput`, `HubCorpusSite`, `HubSite`) |
| `io-stats.ts` | `recordRead` / `ioStatsSnapshot` / `ioStatsEnabled`, guarded `typeof process !== "undefined" && process.env?.MCP_IO_STATS === "1"` |
| `reader.ts` | the `ArchiveReader` interface, `RemoteSource`, `PageCache`, `ArchiveHttpError`, `buildDuplicateIndex`. **Zero `node:*` imports** |
| `reader-fs.ts` | `LocalSource` — the only `node:fs` / `node:path` file; `reader.ts` never value-imports it |
| `reader-hub.ts` | `HubSource` — federation across member origins |
| `readers.ts` | the browser's reader REGISTRY: one `RemoteSource` per origin (`readerFor`), `channelRef`, `resetReaders` |
| `headers.ts` | the `_headers` renderer plus `SITE_CORS_PATHS` / `HUB_CORS_PATHS` / `contractCorsPaths()` |
| `offlineUrls.ts` | `channelArchiveUrls` (one channel's per-channel trees) and `siteArchiveUrls` (the flat trees + root files of one origin) |

### `contract.ts` OWNS `CONTRACT` and `pageFileName`; `corpus.ts` / `manifest.ts` re-export

Not a style choice — the other arrangement is a hard ESM failure. `corpus.ts` imports the
URL builders, `contract.ts` needs `CONTRACT.pagePad` for `pageFileName`, and `manifest.ts`
reads `CONTRACT.manifest` **at module scope**. Leaving `CONTRACT` in `corpus.ts` closes the
loop `corpus → archive/contract → manifest → corpus` and the first module imported throws
`ReferenceError: Cannot access 'CONTRACT' before initialization`. So `contract.ts` is the
BOTTOM of the stack (it imports only `lib/duplicates.ts`), and every existing import site
(`from "./corpus"`, `from "./manifest"`, the three `*PageFileName` aliases) is byte-identical.

`stats/` gets URL builders without joining `CONTRACT.layers`: `corpus.json`'s `shardScheme`
does not document it, so the builders take a wider `ArchiveTree = ContractLayer | "stats"`
and the published layer list stays frozen.

### `ArchiveReader` is mcp's 18-member `ShardSource`, verbatim, and has no `record()`

`label`, `listChannels`, `transcriptsManifest`, `transcriptPage`, `loadAliases`,
`loadGroups`, `publicOrigin`, `subsManifest`, `subsPage`, `postsManifest`, `postsPage`,
`availabilityMap`, `videoIndex?`, `pageConcurrency?`, `duplicateIndex?`, `statsIndex?`,
`digestsManifest?`, `digestPage?`. **`record(layer, slug, id)` must not be added**: the walk
is manifest → shard → record and callers already hold the shard, so a per-record fetch is a
bench regression by construction.

`mcp/src/source.ts` is 47 lines of re-export (it was 1,386), so this server's seven
`./source` importers and `mcp/bench` are untouched.

### The raw throwing reads are on `RemoteSource` only

Twelve one-to-three-line URL + fetch + parse reads that **throw** —
`readCorpus`, `readAliasConfig`, `readDuplicates`, `readSummariesManifest`,
`readSummariesPage`, `readStatsManifest`, `readStatsPage`, `readSubsSiteManifest`,
`readPostsSiteManifest`, `readChannelSubsManifest`, `readChannelPostsManifest`,
`readChannelDigestsManifest` — with every tolerance policy sitting on top. The reason is
react-query: it retries a REJECTED query and will never retry a resolved `null`, so folding
the browser's policy and the MCP's `null`-for-anything-not-200 into one method is how a
transient blip becomes a panel that stays empty for the session. `ArchiveHttpError` came with
them for the one caller that must tell a 404 from a dropped connection (the alias dictionary,
`staleTime: Infinity`); its `message` is byte-identical to the `Error` it replaced.

The tolerant methods are rebased on the raw read they duplicated, so the MCP's behaviour is
unchanged by construction and no read count moves. The `io-stats` blind spots are preserved
deliberately: the raw reads take an OPTIONAL `kind`, and the ones passing none are exactly the
reads that recorded nothing before.

### The browser's page-cache budget is 8 MB per cache, set in `readers.ts`

`RemoteSource` defaults to `DEFAULT_PAGE_CACHE_MB = 48` (`reader.ts`, env
`TRANSCRIPT_MCP_PAGE_CACHE_MB`) and holds TWO page caches, so an origin costs 96 MB — right
for one long-lived MCP process, wrong for a tab and emphatically wrong for a hub page holding
a reader per member. `readers.ts` passes `BROWSER_PAGE_CACHE_BYTES = 8 MB` explicitly, so an
origin is 16 MB and five federated members are 80 MB rather than 480 MB. It can be this small
at no cost in reads because the viewer memoises every RECORD it has seen
(`transcriptCache.resolved` + IndexedDB), and `MIN_CACHED_PAGES = 2` still floors it where one
page exceeds the whole budget. **`mcp/src/source.ts` constructs `RemoteSource` directly and
keeps the 48 MB default**, which is why no bench counter moves.

Two memos stay in `components/` on purpose: the subs/posts CHANNEL-manifest memos (they keep
the throwing policy above), and the posts and digest PAGE memos (the reader caches subs and
transcript pages but not those two, and `fetchThread` walks every page of a channel).

### `common/lib/search/` — six modules, and lib holds no caller's policy default

`policy.ts` (`MCP_POLICY` and `VIEWER_POLICY`), `evalTree.ts` (the per-record boolean
evaluator), `window.ts` (both excerpt shapes — the MCP's merged ±45 s paragraph and the
viewer's per-cue row — one `truncate`, one `clock`), `rank.ts` (the two comparators that
exist: newest-first by `uploadDate`, oldest-first by `createdAt` tie-broken by id),
`collapse.ts` (pure, synchronous, generic over `CollapsibleHit`), `leafPipeline.ts` (the
browser's streaming leaf scanner, three worker-pool drivers + the leaf adapter).

**The rule: `lib/search/` holds no caller's budget as a default.** All three widths
(`truncate`'s `max`, `windowedTranscript`'s `maxLines`, `RecordCtx.snippetChars`) are
REQUIRED, and no non-test module under `lib/search/` imports `MCP_POLICY` at all except
`policy.ts`, which defines it (`maxPages` 400, `hardVideoCap` 2000, `windowLineCap` 200,
`snippetChars` 240; `VIEWER_POLICY` spells the uncapped one).

A default would have failed the bad way: an adopter that forgot its policy would
silently clip every excerpt at 240 with the whole suite green.

`lib/searchEval.ts` and `lib/search/evalTree.ts` are SIBLINGS, not a copy and its original:
one answers *which slugs survive* (streaming, over per-leaf network pipelines) and one answers
*does this record match*. Each names the other in a comment and states the rule — the meaning
of AND / OR / negate changes in both together. No test can compare a streaming slug-set walk
against a per-record boolean, so the prose is the only guard.

`components/searchPipeline.ts` is 68 lines: it answers one question — WHICH FETCH — and
supplies `searchRuntime`. `mcp/src/search.ts` is 1,205 lines of orchestration (it was 1,563);
`buildScanPlan` stayed there and calls the single `passesFilters` from `lib/search/evalTree`,
so the pruner and the scanner cannot disagree about what matches.

### `FORBIDDEN.lib` now includes `components`, and the allow-list is still 11

`common/architecture.test.ts`: `lib: ["controller", "jobs", "components"]`. Four back-edges
had to go first — `searchEval → components/searchPipeline`, `searchEval →
components/searchLayerCache`, `aiHandoff → components/searchPipeline` (a type),
`searchQuery → components/urlState` (a type). All four inverted: the pipeline moved down, the
fetch and the memo are injected as `SearchRuntime.runLeaf` / `SearchRuntime.cache`, and
`CachedResult` / `SearchMode` moved to the modules that interpret them (the old homes
re-export). **The forbidden list grew while the ALLOWED ledger did not** — still the same 11
entries, byte-identical to the base.

### The two service workers' path lists are pinned to the contract by `contract.test.ts`

`export/service-worker/site-sw.js` and `export/service-worker/sw-hub.js` each hand-write
three regexes — a service worker can import nothing — and `common/lib/archive/contract.test.ts`
reads both files and asserts the alternations equal the contract: `SHARD_RE` ∪ `FLAT_RE` =
`ARCHIVE_TREES`, `SHARD_RE` = `PER_CHANNEL_TREES`, `ROOT_RE` = `ROOT_FILES`. Verified by
mutation (dropping `digests` from sw-hub's `SHARD_RE` turns it red). The same test pins
`common/components/searchIndex.worker.ts`'s deliberate `pageFileName` copy — a worker cannot
import the reader, so that one walk stays, guarded.

`SHARD_RE` matches three path segments, so `/duplicates.json` and `/summaries/*` never matched
it: both workers gained `FLAT_RE` and `ROOT_RE`, answered NETWORK-FIRST (those documents carry
no per-channel `generatedAt` to evict against). Three drifts were closed with them: `summaries`
was dead in site-sw's `SHARD_RE` and in both eviction prefix lists; `/posts/` and `/digests/`
were absent from both eviction lists, so a rebuilt channel served stale posts and digests
forever; and sw-hub had no `digests` at all.

**An offline copy is TWO lists.** `offlineUrls.ts` splits them because the cost model does:
appending the flat trees and root files to EACH channel pinned ~41.5 MB of byte-identical data
per channel on jeralyzer (summaries ~14 MB, stats ~21.6 MB, `/duplicates.json` 5.9 MB), and
NONE of it was removable — both evict paths sweep `/<tree>/<slug>/` prefixes and not one of
those URLs lives under a channel prefix. Site data now rides with the FIRST channel pinned on
an origin, and an `EVICT_SITE` message in both workers removes it when the last pinned channel
of that origin goes.

`offlineCache.ts` keeps its own `cache: "no-store"` fetch rather than taking the shared reader:
the reader is a plain `fetch` and would be answered from the very service-worker cache that
function exists to refill.

### `_headers` is generated by `headers.ts`; the site gets two CORS lines the hub does not

One renderer, two ordered path lists. `SITE_CORS_PATHS` gained `/duplicates.json` and
`/digests/*` — the wire change of Phase 2, and the only one. `HUB_CORS_PATHS` is UNCHANGED:
a hub holds no shard data (it reads every member cross-origin at runtime), so declaring
headers for paths it never serves would be noise. `contractCorsPaths()` plus
`headers.test.ts` assert every `CONTRACT.layers` tree and every `ROOT_FILES` document has a
line, so adding a layer and forgetting its CORS entry fails a test rather than a deploy.

The lists are ORDERED data, not derived: `_headers` is matched top-down by Cloudflare and the
file is diffed against a committed fixture, so deriving the order from `ROOT_FILES` +
`CONTRACT.layers` would have reordered every line.

**`curl -I` cannot show this gap locally and never could.** `serve` (what the export, hub and
2-origin suites all run behind) gives `**/*.json` a blanket `Access-Control-Allow-Origin: *`
via `export/serve.json`, and `wrangler pages dev` — the only local server that reads `_headers`
at all — adds the header to every response of its own accord. What wrangler does report is its
own parse: **12 valid header rules before, 14 after**. The real before/after is a deploy.

### `shipsPwa` is server-called only

> **AMENDED 2026-09-22 (`d0df901b`): the guard is there now** —
> `typeof process !== "undefined" && process.env.INSTANCE_MODE === "hub"`,
> `common/lib/archive/contract.ts:203-207`. Read the amendment at the foot of this file before
> concluding anything from it: **the guard stops a client import from crashing; it does NOT
> make hub detection work client-side.** The paragraph below is otherwise still the reasoning,
> and its correction about inlining is still the thing people get wrong.

`common/lib/archive/contract.ts:183`. It reads `process.env.INSTANCE_MODE` BARE, with no
`typeof process` guard, unlike `io-stats.ts` and the page-cache knob. That is safe only
because of who calls it: `common/bin/compose-site.ts` (a build script) and
`export/app/lib/mode.ts`, whose only caller is `export/app/layout.tsx` — a server component —
and whose `currentSite()` reads the sites dir anyway. `contract.ts` is not reachable from any
browser-but-not-Next context (the service workers import nothing; the search worker keeps its
own copy). **A future CLIENT caller owes the guard.** Do not reason from the earlier claim
that Next inlines `INSTANCE_MODE` into the client bundle — it does not (`INSTANCE_MODE` is
neither `NEXT_PUBLIC_` nor in a `next.config.ts` `env:` block), and that claim has been
corrected twice.

### `cues.mjs` carries a reachability twin of `assertChannelMediaReachable`

**Release 17 slice T1:** it is now the twin of `assertChannelTextReadable` — it refuses a `legacy`
channel (a `data` link or a recorded `dataDir`, mounted or not) and a marker only when its `scope` is
`tier-migration`; relocated MEDIA is read past. The paragraphs below describe the old twin.

`umtool/report-to-video/cues.mjs`'s `checkChannelReachable` replicates
`inspectChannelMedia` / `assertChannelMediaReachable` (`common/lib/channelMedia.ts:320-327`,
which carries the cross-reference comment) in plain `.mjs`, because umtool's bins run under
bare node with no `tsx`. It reads `dataDir` from `config.json`, checks the `.relocating.json`
marker, `lstat`s `data/`, compares `readlink` against the configured target, and `stat`s the
deep `<root>/<slug>/data` path — then **throws** a `CueLookupError`, which carries no `code`,
so `load`'s `ENOENT`/`ENOTDIR` fallback rethrows it instead of reaching for the archive. Zero
fetches, asserted.

Where the line is drawn, deliberately: **a channel whose `data/` is simply absent with no
configured target does NOT throw.** That is `in-place` to the editor's twin, and it is the
archive-only workflow this repo advertises (a clone with no corpus at all). What throws is the
case that motivated the slice — a relocated channel whose drive is gone.

Not closed, and wanting the same guard when umtool's local-corpus access is next touched:
`umtool/report-to-video/check-availability.mjs:53` (`cueMeta`) and
`umtool/lib/projects/report.mjs:121` (`cuePathFor`) still join
`channels/<slug>/data/<id>/transcript.cues.json` by hand and read an unmounted channel as an
absent file. Neither answers a cue WINDOW, so neither can cut a clip in the wrong place.

### `e2e:2origin` is known-red on the base and Phase 2 did not touch it

> **CLOSED 2026-09-22 (`f40c4257`, `7a38b60b`, `2e13c0ab`).** The suite is GREEN, 3/3 — the
> first time since hub `/ask` existed. `export/app/ask/AskHub.tsx` needed the WHOLE provider
> stack, not an opt-out of prerendering. Details at the foot of this file. **Stop treating
> `e2e:2origin` as known-red; a red run is now a regression.** The paragraph below is the
> record of the failure.

`playwright.2origin.config.ts:16` → `e2e-2origin/globalSetup.ts:142` shells
`pnpm run build:hub`, and the hub build dies prerendering `/ask`:
`Error: useSearchSession must be used within a SearchSessionProvider`, from
`common/components/SearchSessionContext.tsx` + `export/app/ask/AskChat.tsx`. **Verified on
`c7f7b90` itself** (the pre-Phase-2 integration tip) and again at `bd3d4ec`: same page, same
message, same two chunks. It predates Phase 2 and is the same failure already recorded with
the export responsive redesign. What the hub build DOES prove each time it is run: it compiles
and type-checks, so the bundle resolves `lib/archive/*` and `lib/search/*` in hub mode too and
never pulls `reader-fs.ts` into a client chunk.

## One-core Phase 3 slice 1 (verified 2026-09-15, `main` @ `838da4a`)

- **`common/views/` is the view-model layer.** It sits above `lib/`, `controller/`, `jobs/`
  and below `components/`; `common/architecture.test.ts` forbids `lib`/`jobs`/`controller` →
  `views` and `views` → `components`/`ytdlp`/`bin`/`social`, and adds two tests: no bare
  `react`/`next`/`server-only`/`client-only`/`node:`/`yt-dlp-transcript-common` specifier in a
  non-test view (the self-name is listed because a package-name self-import hides from the
  relative scan), and a TEXTUAL, context-blind ban on `getRegistry(`, `getScheduler(`,
  `getWorkerPool(`, `getPaths(`, `getSettings(`, `getAutoRunnerStatus(`, `readChannelStat(`,
  `readJobMeta(`, `listChannelBriefs(`, `listChannelConfigs(`, `readSchedulerState(`,
  `readAutoQueueState(`, `computeLeafPending(`, `readWorkerDefaults(`, `diskGate(`, `Date.now(`.
  A comment that mentions one with its parenthesis fails it; reword. **The allow-list is 10** (9 since slice 4a, 2026-09-23).
- **Views import common RELATIVELY.** `common/package.json` exports `"./views/*": "./views/*.ts"`
  (a string) and both test-glob brace lists include `views`; `noCorpusWalkInRenderPaths.test.ts`
  walks `common/views` too. A `.tsx` under `views/` would need its own exports line.
- **The port is `views/inputs.ts`** (`LiveInputs`, `ObserveInputs`, `RegistryReader`,
  `PoolReader`; types only) and **the one constructor is `editor/app/lib/liveInputs.ts`**
  (`liveInputs()` calls the five getters; `observeInputs()` reads `globalThis.__ytt*__`, two
  `statSync` mtimes and injects `sha1/base64url`). The three globals are declared by
  `common/jobs/{registry,scheduler,workerPool}.ts`; the pulse route no longer restates them.
- **The injected reader fields are `channelStat` / `jobMeta`**, not `readChannelStat` /
  `readJobMeta` — the textual ban forbids the latter spelling inside a view.
- **Shells at the old paths keep the old names and values:** `jobs/active/buildActiveJobs.ts`
  (120 lines, holds the 8 KB `readLastLogLine` tail), `workers/buildWorkers.ts` (20),
  `operations/status.ts` (72; reads `.auto-queue/state.json` ONCE per poll, was 4×),
  `operations/channelPriorityView.ts` (86; `readPriorityView` stays), `scheduler/status.ts`
  (32; `resolveHeartbeatSeconds` imports `runTick`, never from views),
  `widget/lib/syncInputs.ts` (25). `operations/lanes.ts` is DELETED. `api/widget/sync/route.ts`
  and `api/pulse/route.ts` export exactly `GET` and `dynamic` (both DELETED 2026-09-23 by slice 2;
  the handlers are in `api/view/views.ts`). Every editor import of a shell
  is a value import; every payload TYPE is imported from `yt-dlp-transcript-common/views/*`.
- **`/api/pulse` rev bytes are unchanged**; `views/pulse.test.ts` asserts the hashed string
  through an identity digest, so a reorder names what moved.
- **`liveJobRows` never heals; `buildActiveJobsPayload` always heals** (`scheduler.complete`
  lives in the view) — both asserted in `views/activeJobs.test.ts` against `createScheduler()`.
- **`pnpm wt rm` takes the worktree DIRECTORY name** (`one-core-phase-3-s1b`), not the branch,
  and needs `--force` once `export/public` is seeded with the fixture site.
- **The full editor suite took 38.8 min on `838da4a`** (533/533, nothing flaked) against the
  23-min idle-machine baseline; two other Opus implementers were building in sibling
  worktrees at the time. Wall time is not a signal here; the pass count is.

## Per-channel download filter + metadata scan (verified 2026-09-20, branch `feat/download-title-filter`)

- **The metadata scan NEVER creates `data/<id>/`, and that is not a style
  preference.** Two readers treat a video directory as a fact about the corpus:
  `common/controller/buildIndex.ts:309-315` admits ANY `data/<id>/` that holds a
  `metadata.info.json`, transcript or not — so a metadata-only pass that made
  directories would put ~1,800 text-less videos into the LMDB index and into the
  published site — and `deriveChannelSets` (`common/controller/channelSets.ts:58-67`,
  fed at `channelSnapshot.ts:1167-1174`) keys "ever fetched" off those same dir
  names, so a scanned id would stop being reported in `missingNeverFetched`, the
  one record of a video that vanished before we ever got it. The store is
  therefore channel-level: `channels/<slug>/metadata-scan.json`
  (`common/controller/metadataScanStore.ts`), modelled on `rosterStore.ts`
  (versioned, normalize-on-read, additive, write skipped when unchanged). The e2e
  asserts the absence of the directories directly rather than inferring it.
- **"Settled" is DERIVED, never stored.** `settledByTitleFilterIds(paths, slug,
  config)` = the scan's entries that the channel's CURRENT `downloadFilter`
  rejects. There is no signature, no generation counter and nothing per video:
  editing a regex re-decides the whole channel on the next snapshot, with no
  rescan and nothing to migrate — asserted in e2e by a byte-identical
  `fake-ytdlp.invocations` across the flip. `DownloadOutcomeRecord.filter` is
  `{name, reason}` and deliberately carries no verdict.
- **`includeLivestreams` is a SECOND positive selector, not a modifier.** The
  rule, in `classifyAgainstFilter` and nowhere else: `exclude` always wins; with
  no positive selector (exclude-only) everything else passes; otherwise a video
  must satisfy `include` over title+description OR be a livestream when
  `includeLivestreams` is on. The corner that surprises: `{ includeLivestreams:
  true }` with no `include` means "livestreams only" — plain uploads are
  rejected. Live statuses that count are `was_live`, `post_live`, `is_live`;
  `is_live` is included because the FILTER accepting a live stream and skip-live
  declining to download it until it ends are two different questions, answered
  by two registry entries. The store persists `liveStatus` for exactly this, and
  the matcher reads both `liveStatus` (store) and `live_status` (raw yt-dlp) so
  the scan's prediction and the download's decision cannot diverge. The
  Playlist-stage count is SPLIT (by title/description vs livestreams) because
  otherwise switching the flag on is indistinguishable from widening the regex.
- **A run of "Video unavailable" is a soft block, not availability.** Measured
  2026-09-20 on a raw yt-dlp pass over one channel's playlist: after ~100 good
  records YouTube answered `Video unavailable` for 545 CONSECUTIVE videos, all of
  which fetched fine when probed individually minutes later. `runMetadataScan`
  therefore HOLDS those errors instead of recording them, releasing them only
  when the streak breaks (a readable record, or a different error); at
  `SOFT_BLOCK_STREAK` = 10 it stops the run, records the shared per-platform
  cooldown and DISCARDS the streak, so the next run re-reads those ids. Recording
  them would mark public videos deleted AND suppress re-reading each for a day.
  Members-only ("Join this channel…") breaks the streak and is recorded as
  `members_only` — it is genuinely not fetchable and must not be discarded with
  a block's ids.
- **It fails closed in both directions.** No filter, or an unparseable one
  (which is inert at download time too), settles nothing. An id the scan only has
  an ERROR for is never settled — we do not know what it is called, so we must
  not decide it; it stays ordinary download work.
- **Settlement applies only to a video with NO artifact on disk.** A video
  downloaded before the filter was written is DOWNLOADED, which is a fact rather
  than a preference. Short-circuiting it in the snapshot's per-video loop would
  drop it from `transcribedWithAudio` and the cleanup estimates while it still
  counted in `totals.transcribed` — a channel reporting more transcripts than
  videos. Both the loop and the `skippedByTitleFilter` bucket apply the same
  no-artifact rule so they cannot disagree.
- **`buckets.skippedByTitleFilter` vs `buckets.skippedByFilter`.** The first is
  settled (the operator's "not this one"); the second is the RETRYABLE skip that
  skip-live has always produced, and a configured filter meeting
  `metadata === null` deliberately lands there — a flaky extractor must not be
  able to settle anything. The settled ids are also excluded from
  `undownloadedIds` (artifact-derived, which is why an archive line could never
  have settled anything: archive lines also mean "downloaded" to
  `verifyTranscripts.ts:47` and the `missingFromArchive` bucket).
- **Sync counts a settled id as an ARCHIVED HIT** (`selectDownloadableUrls`,
  `common/ytdlp/runYtdlp.ts`). `archivedHits > 0` is the paged walk's stop signal;
  a settled video has no archive line and usually no directory at all, so without
  this a filtered channel's daily sync walks every page of non-matches forever
  and never sees a hit on the pages the filter emptied. The set is resolved ONCE
  per run (one small JSON read), not per video.
- **The registry order is `[titleFilter, skipLive]`** and it is load-bearing: a
  non-matching video that is also live must be declined on the operator's terms,
  not classified as a live-stream retry. A video that passes the include still
  falls through to skip-live.
- **The scan is a catalogued operation**, `metadata-scan`: second channel-scoped
  entry in `operationCatalog()`, `trigger: "backlog"` (sync stays the ONE
  `"cadence"` entry — that is how `/operations/sync` is chosen), platform download
  queue. Its backlog is `snapshot.metadataScan.unscanned`, which must keep
  meaning exactly what `metadataScanTargets()` will fetch.
  **TWO CORRECTIONS, 2026-09-21.** Its job kind declares **`needsMedia: TRUE`**,
  not false — `jobKinds.ts` says why at length: the scan's target set is
  "listed, minus what is already on disk", so it OPENS `data/`, and against an
  unmounted drive it would re-request the whole channel. (It writes no media;
  that is a different question.) And `pauseLaneFor` answers **`"download"`**
  now, because the download runner dispatches it — see the follow-ups section
  below. What the old exemption was FOR is intact and now belongs to the Run
  button, which checks the platform cooldown and no gate at all.
- **A scan error suppresses a re-scan of that id for 24 h**
  (`METADATA_SCAN_ERROR_COOLDOWN_MS`). Without it a members-only video keeps the
  backlog above zero forever and the operation page never stops offering work.
- **YouTube's bot check is `rate_limit`-class.** "Sign in to confirm you're not
  a bot" (right single quote in yt-dlp's output — match either) now classifies in
  `classifyDownloadFailure`. It is not a 429 and not per-video: once it fires,
  every remaining entry in the batch fails the same way, so the scan kills the
  child, records the shared per-platform cooldown and keeps what it flushed
  (every 25 records). Note it is NOT in `parseUnavailableFromStderr` — that
  function's `/confirm your age/` branch does not match it, which is what lets it
  fall through to the failure classifier.
- **FOLLOW-UP, not done here: nothing auto-dispatches the scan.** The descriptor
  has no `runner`, so the operator presses Run. The obvious next step is for the
  download lane to run it for a channel whose filter has unscanned listed videos
  — which is exactly the backlog the snapshot already carries.
  **DONE 2026-09-21 — see the section below, which also amends the pause note
  above.**

---

## Filtered-channel follow-ups (verified 2026-09-21, branch `feat/filtered-channel-followups`)

Three things the filter slice left: a rejection's leftover directory, nothing
auto-dispatching the scan, and no answer but "skip" for a livestream the filter
rejects.

- **A TITLE-FILTER REJECTION NOW DELETES ITS OWN PREFETCH DIRECTORY**
  (`ytdlp/downloadOneManaged.ts`, `discardPrefetchDir`). The prefetch writes
  `data/<id>/metadata.info.json` BEFORE the filters look at it, so by the time
  the operator's "not this one" is known the directory exists — and a directory
  holding a metadata.info.json is admitted to the LMDB index and the published
  site by `buildIndex.ts:309-315`, transcript or not, while `deriveChannelSets`
  reads its NAME as "ever fetched". The scan creates none of them for exactly
  those two reasons; the downloader now creates none either. It fires when a
  rejection reaches the DOWNLOADER at all — a video the filter needed a live
  prefetch for, i.e. one the scan has not read. The two batch paths never invoke
  yt-dlp for a settled video (`selectDownloadableUrls` counts it an archived
  hit), but `importVideoAction` reaches `downloadOneManaged` by URL and bypasses
  both, so "a settled video is never invoked" is true of a sync and a
  download-missing and NOT of a hand-pasted link.
- **The count does not move, and the reason is that it never came from there.**
  `buckets.skippedByTitleFilter` is built at `channelSnapshot.ts:1378-1383` from
  `settledIds` ← `settledIdsFrom(metadataScanStore, config)` at `:927`. Nothing
  in it reads `download-outcome.json`. The only on-disk reader of
  `"skipped-filtered"` is the RETRYABLE `skippedByFilter` bucket at `:1101-1105`,
  which is why every OTHER filter (skip-live) still writes its outcome sidecar:
  that skip says "we will try again", and a video with neither directory nor
  outcome would silently leave the bucket. `channelSnapshot.test.ts` runs a whole
  filtered channel with NO `data/` dirs at all and still gets the bucket.
- **`videoHasAnyArtifact` was a private copy of `isVideoDownloaded`, byte for
  byte**, in a module that already imported the original (it is what increments
  `downloaded` in the same walk). It is an alias now: two names for one
  predicate is how the settled short-circuit and `totals.videos` end up
  disagreeing about what an artifact is, and the five call sites read better
  asking "does this dir hold anything we fetched?".
- **IT IS AN ALLOW-LIST, AND THE DENY-LIST IT REPLACED WAS A BUG.** This is a
  recursive delete, so the question it must answer is "is EVERYTHING in here
  mine?". The first version named `isVideoDownloaded`, `clips/` and
  `saved-video.json` — and would therefore have deleted a chat-only corpus
  member (`transcript.live_chat.json` + `live_chat.cues.json`), a
  `transcript.es.vtt`, a resumable `audio.mp3.part`, a `diarization.json` or a
  `digest.json`. Reachable, not hypothetical: the chat-only branch calls this
  whenever its chat pass came back with no file, so a chat re-fetch that failed
  or was aborted would have deleted the chat that was already there. The rule is
  now `PREFETCH_OWN_FILES` = `{metadata.info.json, download.log,
  download-outcome.json}`, files only — **a directory is never ours** — and
  anything else keeps the dir. `ytdlp/downloadOneManaged.test.ts` runs one case
  per protected shape. The returned `DownloadOutcomeRecord` is unchanged either
  way, so `runYtdlp.ts:949` and the runner's `unitStatus` check need no edit.
- **`deriveChannelSets` takes the settled set**, and both call sites pass it
  (`channelSnapshot.ts`, and `syncFullSweep` in `runYtdlp.ts`). Both sets it
  derives are defined by the ABSENCE of a directory, and a settled video has none
  now — so without this a filtered-out video that later leaves the listing reads
  as `missingNeverFetched`, the loudest alarm this system raises, pointed at a
  video the operator asked us not to fetch. `undownloaded` is subtracted for the
  same reason: settled work is not work.
- **THE DOWNLOAD LANE AUTO-DISPATCHES THE SCAN.** `METADATA_SCAN_OPERATION` now
  declares `runner: "download"`, and the runner's `next()` runs a pre-pick before
  any video: `pickMetadataScanChannel` (pure, exported, unit-tested) takes the
  first channel in `metaCache` order that has a COMPILING filter, a non-zero
  `snapshot.metadataScan.unscanned`, no scan already done by this runner, and a
  platform that is neither busy nor cooling. It goes first because it decides
  what the downloads ARE.
- **The scan unit is channel-scoped and holds a platform slot.** `Picked` gains
  `scan`; the synthetic key is `metadata-scan <slug>` (a space, which no video id
  contains) with leaf id `metadata-scan` and an EMPTY `path`, so no node's
  `maxWorkers` moves for it. It takes `platformInFlight` exactly as a download
  unit does, so a scan and a download never hit one source at once.
  `AutoRunnerInFlight` gains `note?`, and `InFlightList` renders the note (and
  links the CHANNEL) instead of a dead video link.
- **A FOCUS HOLDS THE SCAN TOO.** The compiled priority tree holds every
  download pick by strict descent, and the pre-pick does not go through that
  tree — so without this, "only jeralyzer is moving" would be false the moment
  another channel had titles to read, on the same network the focus is trying to
  have to itself. `pickMetadataScanChannel` takes the `focusSummary` the lane
  already computes for its log line: while `holding` (i.e. `focusPending > 0`)
  only a focused channel is offered a scan; once the focus is exhausted the lane
  is free and so is the scan.
- **ONE SCAN PER CHANNEL PER RUNNER, deliberately.** A scan that left the backlog
  above zero was stopped by something — a soft block, a cooldown, a batch that
  ended early. `scannedThisRun` means this runner does not re-offer it three
  seconds later; the operator's Run and the next restart both still work.
- **`pauseLaneFor("metadata-scan")` is `"download"` now, not null, and the old
  note's reasoning moved to the Run button.** `pauseLaneFor` asks `runner` first,
  so naming the runner gives the operation the download lane's console AND makes
  the download pause hold the AUTO-dispatch. What the exemption was FOR is
  intact: `runMetadataScanAction` checks the platform cooldown and no gate at
  all, so the operator can still scan while downloads are paused — which is
  precisely when they want to decide what the lane should fetch on resume.
- **`downloadFilter.rejectedLivestreams: "skip" | "chat-only"`, absent = "skip"**
  (`lib/channelConfig.ts`), and the sanitizer stores it only alongside a real
  filter and only when it is not the default. A channel without the field
  behaves byte-for-byte as it did.
- **"chat-only" IS A REJECTION with an instruction attached, not a fourth way to
  pass.** `DownloadFilterVerdict` gains it; `classifyAgainstFilter` returns it
  from ONE place (`rejection()`), so an `exclude`-matched livestream and an
  unmatched one cannot get different answers. **`titleFilterRejects` still
  answers TRUE for it** — that is what keeps `settledIdsFrom`, `undownloadedIds`
  and the sync walk correct with no other change. `titleFilterWantsChat` is the
  next question, asked only by the downloader and the snapshot.
  `chatOnlyIdsFrom` (metadataScanStore) is the derived STRICT SUBSET of the
  settled set.
- **The download path runs ONE extra yt-dlp pass** (`fetchLiveChatOnly`):
  `--skip-download --write-subs --no-write-auto-subs --sub-langs live_chat`, with
  the refusals AFTER `channelConfigArgs` and `-o` after those — yt-dlp takes the
  LAST occurrence, so a channel's own `--write-thumbnail` cannot turn this into a
  partial download. `--no-write-info-json`, NOT the absence of
  `--write-info-json`: the prefetch's `metadata.info.json` must SURVIVE, or
  `buildIndex.ts:309-315` never sees the video and the chat is published nowhere.
  Then `normalizeLiveChat` writes `live_chat.cues.json` on the spot. No archive
  line — an archive id means "downloaded" to the sync walk and to
  `verifyTranscripts`.
- **A CLEAN PASS THAT FOUND NOTHING IS AN ANSWER, not a retry.** A stream with
  chat replay off makes yt-dlp exit 0 and write nothing. The directory goes like
  any other rejection's, and — because nothing on disk can then remember it —
  the scan entry carries **`noLiveChat: true`**, which `chatOnlyIdsFrom` drops.
  Without it the id sits in `chatOnlyPending` forever: `markCompleted` retires it
  for the SESSION only, so every runner restart re-prefetched it to run a pass
  that will never return anything. A pass that FAILED (non-zero exit, cooldown,
  abort) deliberately does not set it — that one stays retryable — which is why
  the chat pass now runs BEFORE the store is written rather than after.
- **The chat-only verdict is decided off the FILE, not the mode**, in the
  snapshot's settled branch: a dir holding `transcript.live_chat.json` is a
  `chatOnly` member however `rejectedLivestreams` currently reads. Asking
  `chatOnlyIds` there made the same directory a settled STUB the moment the mode
  flipped back — and `settledOnDisk` is subtracted from `totals.videos`, so the
  site kept serving a video the report had stopped counting.
- **`DownloadOutcomeStatus` gains `"chat-only"`** and `DownloadAttemptKind` gains
  `"live-chat-only"`. The batch counts it as a SKIP (`okCount` means videos
  downloaded); the runner counts it as a SUCCESS (the unit did the work it was
  picked for, and the platform's cooldown clears).
- **Two buckets, and neither is `skippedByTitleFilter`.** `chatOnly` = the
  verdict plus `transcript.live_chat.json` on disk — a corpus MEMBER, counted in
  `totals.videos`, never in `settledOnDisk` (which is subtracted from it), and
  short-circuited out of every bucket that means something is missing.
  `chatOnlyPending` = the verdict without the file, appended LAST to
  `DOWNLOAD_BUCKETS` so a chat backlog can never delay a real download. Both are
  `[]` for every channel without the field, so the fold, the lane work list and
  the pick order are byte-identical for them.
- **It cannot ride in `undownloadedIds`**, and that is the reason `chatOnlyPending`
  is a bucket rather than a derived count: that list means "fetch the media", and
  fetching the media is the one thing this video must not have done to it.
- **THE RISK THE TESTS EXIST FOR: a chat-only dir makes "metadata, no
  transcript" a legitimate shape** — exactly what `buildIndex.ts:309-315` and
  `deriveChannelSets` (`channelSets.ts:58-67`) read as "ever fetched". Get the
  bucket rules wrong and filtered livestreams silently leave
  `missingNeverFetched` and enter the published site as blank pages.
  `channelSnapshot.test.ts` runs all three states (chat landed / chat pending /
  mode turned off) against a real `generateChannelSnapshot`, and
  `editor/e2e/chat-only.spec.ts` builds the index and asserts the published
  record carries ONLY a `live_chat` track and zero cues.
- **`common/controller/metadataScanJob.ts` is the one definition of the scan as a
  JOB** — kind, per-platform queue key, replay spec and the shared
  `onPlatformBackoff` wiring. The editor action keeps only what a CLICK is owed
  (the cooldown answered as a sentence, and three `revalidatePath` calls, passed
  as `afterRun`); the runner passes `background: true` and neither. `needsMedia`
  comes from the kind (TRUE for this one), so `runManagedFunction` refuses it
  against an unmounted drive for both callers with nothing said in the module.

## Clip windows: media sourced for another tool (2026-09-20)

umtool asks the editor for a clip window instead of running yt-dlp
(`POST /api/media/fetch-window`). Verified while building it:

- **A window fetch MUST NOT write `metadata.info.json`, and that is the whole
  design constraint.** `common/controller/buildIndex.ts:309-315` stats that file
  per video dir and `continue`s when it throws — so the file's presence IS a
  video's presence in the LMDB index. Thirty seconds of audio would otherwise
  put an undownloaded video into the corpus. This is why
  `common/ytdlp/fetchWindowManaged.ts` assembles its own argv and goes through
  neither `outputArgsForUrl` (`ytdlp/runYtdlp.ts`) nor `downloadOneManaged`'s
  prefetch. `editor/e2e/fetch-window.spec.ts` pins it, and the fake yt-dlp's
  `--download-sections` branch deliberately writes only the window.
- **`channels/<slug>/data/<id>/clips/` is invisible to every video-dir
  enumerator**, and it is invisible because the predicates are ANCHORED, not
  because anything was added to exclude it. Re-verified, each one:
  - `readVideoFiles` (`common/lib/videoStatus.ts:143-158`) filters a plain
    `readdir` with the anchored regexes in `common/lib/mediaFiles.ts`
    (`^audio\.(ext)$`, `^source-media\.(ext)$`, `^transcript\.[^.]+\.vtt$`) —
    a directory named `clips` matches none.
  - `controller/scanCorruptMedia.ts:112` filters the same listing by
    EXTENSION (`MEDIA_EXT_SET.has(fileExt(e))`); `clips` has none.
  - `controller/pruneSavedVideos.ts:51` and `controller/savedVideoInventory.ts:57`
    `readdir` **dataDir** (the video dirs, one level above `clips/`) and are
    pointer-driven from there.
  - `controller/channelSnapshot.ts` decides undownloaded with
    `videoHasAnyArtifact(readVideoFiles(dir))`, so a video dir holding only
    `clips/` stays undownloaded. The e2e asserts the count does not move.
  None needed a guard. A NEW reader of `data/<id>/` must still ask whether a
  subdirectory is a file.
- **`reconcileVideoDirs.mergeDir` is the one thing that MOVES a video dir's
  contents**, and it is written for files: a colliding entry is stashed as
  `<name>.dup-<srcName>`. It now special-cases `clips` and merges the two
  subdirectories, because stashing the directory would hide every window in it
  from `listClipWindows` (which reads `clips/` and nothing else). A file present
  in both is the same bytes — a window's name IS its span. **Remove the emptied
  source with `rmdir`, never `rm` without `recursive`**: the latter throws
  EISDIR on a directory, the catch swallows it, and the `rmdir(srcDir)` that
  follows then fails ENOTEMPTY — so a merge that worked is reported as a
  "source dir not empty" conflict and the video dir is left split in two.
  `controller/reconcileVideoDirs.test.ts` pins all four cases.
- **A channel's `ytdlpExtraArgs` can defeat the no-info-json rule, so the
  window fetch refuses the sidecars explicitly.** That field is free text an
  operator typed into a form, validated only as strings, and appended to every
  invocation — a channel carrying `--write-info-json` would make a window fetch
  write one. `fetchWindowManaged` appends `--no-write-info-json
  --no-write-description --no-write-thumbnail --no-write-subs
  --no-write-auto-subs --no-download-archive` AFTER `channelExtraArgs(...)`, and
  `-o` after those, because yt-dlp takes the LAST occurrence of an option.
  Ordering is the guard; `editor/e2e/fetch-window.spec.ts` asserts it.
- **`umtool/lib/paths.mjs` READ_ROOTS now includes `CHANNELS_DIR`, and
  WRITE_ROOTS deliberately does not.** `/api/report/raw` resolves the file it
  serves through `resolveInRoots`, so without the read root a corpus window
  400s as "outside the roots". The corpus is production data; nothing in umtool
  should be able to render over it. That two-list split is exactly what makes
  this safe to widen.
- **`WORKER_TOKEN` is shared with `/api/worker/*` by design.**
  `common/lib/workerToken.ts` validates against the env var, never settings, and
  a missing token DISABLES the endpoint (503, not 401). The fetch endpoint
  spends a source's patience, so it must be no easier to reach than the executor
  protocol. It is NOT put in a umtool job step's `env`: `lib/jobs.ts:262`
  (`jobView`) echoes a step's env back to the browser.
- **The clip format selector is umtool's, not `downloadFormatPreset`'s.**
  `resolveDownloadFormatSelector` answers "what should we archive"; the window
  needs "what can ffmpeg cut and re-encode cheaply". Unpinned, yt-dlp picks
  VP9+Opus at these heights and `--force-keyframes-at-cuts` then re-encodes
  through libvpx-vp9 (27 s to cut a 5 s clip, measured) and writes `.webm`. The
  two copies must stay byte-identical or a window one side fetched is invisible
  to the other.
- **`/api/report/fetch`'s "already cached" check must CLAMP its wanted start at
  0**, because the fetch does. `build-video.mjs`'s `fetchClip` and
  `fetch-via-editor.mjs` both take `Math.max(0, start - padBefore)` — a
  recording has no seconds before its first — so asking whether a window holds
  a NEGATIVE start asks for something no file can hold. Unclamped, the check
  could never fire for a clip within `pad` seconds of the beginning, which is
  exactly where a sweep starts; the route queued a job whose only finding was
  that the bytes were already there. Pinned by the reuse case in
  `umtool/e2e/report-fetch-via-editor.spec.ts`.
- **`WIN_EPS = 0.02` and 2 dp naming are a cross-repo contract.**
  `common/lib/clipWindow.ts` and `umtool/report-to-video/build-video.mjs` both
  declare them. A request that rounds differently addresses a different file and
  the cache misses forever.
- **`clips/` HAS NO GARBAGE COLLECTION, and its bytes are counted by nothing.**
  Nothing prunes a window once it is fetched (the retention sweep is
  pointer-driven, so `pruneSavedVideos` never sees one), and
  `channelSnapshot.ts` (the `mediaBytes` loop, ~:773) does `if (!st.isFile())
  continue` — its comment says "a video dir is flat", **which this feature makes
  untrue**. So a `clips/` subdirectory adds to the platter without adding to
  `snapshot.totalMediaBytes`, which is the number the storage page reads and the
  number a relocation estimate is drawn from — while `rsync -a` of the data dir
  moves the windows regardless. Deliberate for now (a window is seconds, not a
  recording) but it is a real under-count, and a channel walked many times by
  many reports accumulates them silently. A later sweep owes three things: the
  recursion or an explicit clips total, a count on the storage page, and an
  eviction rule.
- **`SavedVideoPointer.origin` is separate from `keepReason` on purpose.**
  `keepReason` stays `override`/`pin` so `pruneSavedVideos` never evicts a
  container somebody asked for; `origin` is who asked. `parseSavedVideoPointer`
  is tolerant, so a legacy pointer parses unchanged (`clipWindow.test.ts`).

---

## Storage locations S5–S6 (verified 2026-09-20, branch `storage/locations-s5-s6`)

Six things, in the order they were built. Trust these over re-deriving them.

### Bytes: `snapshot.totalMediaBytes`

- **EVERY byte under `data/<id>/`**, not the audio. `totalAudioBytes` is a
  different question (what a CLEANUP could reclaim); this is what a volume holds
  and what a move carries, and on a real channel the two differ by the whole
  transcript/cues/metadata mass.
- Gathered in the EXISTING per-video walk in `channelSnapshot.ts` (~746): the
  `audioSizes` loop became one loop over `files.entries`, statting each, feeding
  both numbers. No second walk; the added cost is a stat per non-audio entry,
  warm inode cache, on a pass that already reads several sidecars per video.
  Sub-directories count as nothing rather than recursing — a video dir is flat.
- **OPTIONAL, and the distinction is load-bearing.** A snapshot written before
  the field lacks it, and every reader must render that as "size unknown until
  Refresh report", NEVER as 0: a zero ranks a 400 GB channel bottom of the very
  list the operator opened to find it. `LocationRollup` therefore carries
  `bytes` AND `unknownBytes`, and `storageBytesText(bytes, unknown)` in
  `views/storage.ts` is the one wording.

### The corpus volume as a row: `INTERNAL_LOCATION_ID = "internal"`

- **SYNTHETIC, never stored in `settings.storage.locations`.** There is nothing
  to configure (the root is wherever the corpus is), nothing to re-point, and —
  the load-bearing reason — a stored entry would make `locationOfDataDir` match
  every unrelocated channel, breaking the rule the whole design rests on: a
  channel is on location L iff its `dataDir` is under `L.root`, and an in-place
  channel HAS no `dataDir`.
- Assembled in `views/storage.ts` (`internalRow`) from `StorageRowsInputs.internal
  = { root, freeBytes? }`, which the shell fills. It sorts FIRST, is
  `available` by construction, and every one of its five actions is present with
  `offered: false` and the same sentence — a greyed button with no reason is
  what that page exists not to be.
- `channelsOnLocation({ includeInternal: true })` rolls the no-`dataDir` channels
  under that id. A `dataDir` under a root NOBODY named is counted in NEITHER; the
  nudge is to name that root on /storage.
- `StorageRowsPayload` exposes `bytesOnLocation` (by row id, internal included)
  and `bytesInPlace`.

### The Storage panel has ONE verb

- `MoveOut`/`MoveBack` folded into `MoveMedia` (`StorageStage.tsx`). The corpus
  volume is a destination (`__internal`) and picking it calls
  `moveChannelMediaBackAction` — unchanged, by that name, so the `/api/ops/*`
  routes on `feat/ops-api` keep working.
- While the media IS on a location, `__internal` is the ONLY option offered: the
  controller refuses a location-to-location move by name ("already relocated to
  X. Move it back in place first."), and a select of options that all refuse is
  worse than one that works plus a sentence. No preview gate on the way back.
- One log, one accessible name: `getByLabel("Move media output")` for both
  directions. The button LABEL still reads "Move back in place" when the
  destination is internal.

### `/channels` is the storage working surface

- Two columns: **Location** (`aria-label="media location for <slug>"`, the
  volume label with the existing reachability badge beside it) and **Size**
  (`aria-label="media size for <slug>"`, sort key `size`, first click biggest
  first, "—" and never "0 B" when unmeasured). Sort keys `location` and `size`
  joined `SortKey`; `colSpan` went 10 → 12 + columns.
- **Free space is NOT a column.** It is a fact about a disk; 71 copies of one
  number is what the focus bar already taught us not to do. It lives in
  `ChannelVolumeBar` (`aria-label="storage volumes"`), one chip per volume
  (`aria-label="volume <id>"`), and the chip IS the filter.
- **`?location=<id|internal>`**, a URL param beside `?site=`, validated on the
  server against what is on screen (a stale /storage link must show the page,
  not an empty table). A volume filter FLATTENS the grouped render: a group is a
  partition of a site, and half a group is not a group.
- **`?sort=size`** seeds the sort ONCE. Sorting is otherwise client state,
  deliberately — a `router.replace` races the global AutoRefresh's
  `router.refresh()` and gets dropped.
- **"Free up N GB"** lives in the volume bar, not the deck: the deck only exists
  once something is ticked, and this is the control that does the ticking. The
  deck shows the resulting note (`aria-label="free up selection note"`). The
  rule is pure in `common/views/freeUpSelection.ts`: only in-place channels
  (moving one already on the platter frees nothing on the disk being emptied),
  unmeasured ones excluded AND COUNTED, largest first, last pick overshoots.
- **Per-volume free space is `volumeFreeBytes` (controller), two syscalls per
  root and never a probe.** The `stat` is what stops `getFreeBytes` reporting an
  unmounted root's PARENT volume — which on this machine is the disk being
  emptied. Tables do not shell out.

### Relocate progress

- `rsync --info=progress2` was ALREADY on the copy; every frame went to the job
  log as a carriage-return redraw. `parseRsyncProgress` (jobs/progressParsers.ts)
  reads one frame — `30,000,000  85%  1.03GB/s  0:00:03 (xfr#1, to-chk=1/3)` —
  into `{bytes, percent, rate, etaSeconds}`. Grouping separators are stripped
  with `\D`, not assumed to be commas.
- **The fraction divides by the MEASURED tree, not by rsync's percentage.** Under
  incremental recursion (the default) rsync's percentage is of what it has
  enumerated so far and walks BACKWARDS. The controller already measured the
  whole tree for its space check.
- `relocateChannelMedia`/`relocateSavedVideos` take `onProgress`, keep frames out
  of the log, and write one decile line: `Copying… 12.3 GB of 45.6 GB · 27 % ·
  110.50MB/s · ETA 5:32`. Same wording in the job's task detail.
- The job publishes it as a **`JobTask` of kind `"relocate"`** (new member of
  `JobTaskKind`; the two `Record<JobTaskKind, …>` tables in
  `JobProgressBars.tsx` and `MonitorWidget.tsx` are the compile errors that
  catch a third). NOT a `JobProgress` metric — that counts artifacts
  re-countable from disk, and a copy in flight is neither. The task is added on
  the FIRST FRAME, not at start: the preflight and a resumed run's verify pass
  transfer nothing.

### `relocateDir.ts` and the movable saved-video store

- `common/controller/relocateDir.ts` is `relocateChannelMedia.ts`'s core lifted
  out UNCHANGED: `measureTree`, `linkOrDirState`, the marker read/write/clear,
  `rsyncTree` (takes `rsyncBin`, not `Paths`), `COPY_ARGS`, `verifyCopy` (dry run
  + re-measure, one `.d..t` retry) and `makeProgressSink`. What stayed behind is
  everything channel-specific. The channel mover's 24 tests pass against it.
- `relocateSavedVideos({ paths, locationId, io? })`: `""` moves back.
  `<store>` becomes a symlink to `<root>/saved-videos`;
  `savedVideoRoot()` (lib/savedVideo.ts) is untouched and every reader follows
  the link. Marker: `transcripts/.relocating-saved-videos.json`, the SAME
  `{target, direction, startedAt, phase}` shape a channel's uses.
- **`settings.storage.savedVideosLocationId`** is a RECORD of where bytes are,
  not a preference — so unlike `defaultLocationId` it is NOT fallen back to
  another location when the named one is deleted; it sanitizes to `""`.
- `ChannelConfig.savedVideosDir` (the per-channel override) is neither read nor
  rewritten: it is an absolute path the operator set.
- Job kind `relocate-saved-videos`, in `NO_REGEN_KINDS`, on
  `relocationQueueKey()` with the channel move and the re-point. A store move or
  a re-point freezes every /storage row (`runningRepoint` checks both kinds); a
  CHANNEL move deliberately does not.
- `/storage` grows `SavedVideosStoreCard` — size, location, Move / Resume /
  Clear marker. The store is WALKED (`measureTree`) because it holds one
  container per pinned or kept-latest video, not one per video; if it ever grows
  to corpus scale, `listSavedVideos` (pointers carry their own `bytes`) is the
  cheaper answer waiting.

### The drive watch (S5)

- `common/controller/storageWatch.ts`. Every existing guard runs at the START of
  a piece of work; none is a DETECTOR, so a channel on a vanished drive sits
  being refused with nothing saying why. `runStorageWatchPass` probes every
  location (`refresh: true` — the 10 s memo is for page renders), auto-pauses the
  channels it cannot reach and restores them when it can.
  `startStorageWatch()` arms it at `STORAGE_WATCH_INTERVAL_MS` (5 min).
- **`ChannelPriorityEntry.autoPaused = {reason: "storage", since, previousTier}`.**
  `autoPauseForMedia` no-ops on an already-auto-paused channel (a flapping drive
  must not overwrite `previousTier` with `paused`) and on one the OPERATOR
  paused. `restoreAfterMedia` no-ops without a record. `clearAutoPause` is called
  by the one priority writer on every manual tier change — the operator's word
  always wins.
- **The sanitizer now KEEPS a rank on an auto-paused channel.** It still drops
  one from a channel paused everywhere, which is right for a pause the operator
  meant and catastrophic for a temporary one: an unplugged cable would otherwise
  destroy the queue order and restore the channel unranked.
- **THE PASS PAYS THE LEGACY SEED.** `laneDispatchRoot` is all-or-nothing on
  `isDefaultChannelPriority`, so auto-pausing one channel on a corpus with an
  empty document would switch it off its hand-made lane trees. Same condition and
  same remedy as `saveChannelPriorityAction` (S2/S3 review, finding 3), and the
  lanes are recompiled in the SAME `writeSettings`.
- Writes at most once per pass, and only on a transition — a quiet pass bumps no
  pulse revision. `in-transition` (a relocation marker) is never a reason to
  pause: the relocate job is what an auto-pause would be refusing.
- Armed in `instrumentation.ts` BELOW the idle gate, unlike the boot probe above
  it: the probe is read-only, the WRITE is work, and `ARCHILYZER_IDLE_BOOT`
  refuses work.
- The flag: `autoPauseReasonOf` is the one sentence, rendered as a "storage" chip
  by `ChannelTierSelect` (`aria-label="auto-paused reason for <slug>"`).

### Review fixes, 2026-09-20 — the five that were not optional

- **An auto-pause/restore cycle used to destroy per-operation overrides.**
  `sanitizeOverrides` normalises away any override equal to the BASE tier, and
  while the machine's pause stands the base on the entry is the FORCED
  `paused` — so every `{op:"paused"}` fence stopped being an exception and was
  deleted. The record is now computed BEFORE the overrides and they are
  normalised against `previousTier`. Test: a pause→restore round trip preserving
  tier, rank AND overrides.
- **`common/lib/savedVideoStore.ts` is the store's guard, and it is in lib/ on
  purpose.** `savedVideo-server.ts` is what persists a container, it is lib, and
  lib may not import controller — so the marker's name, its reader and
  `assertSavedVideosStoreWritable` live there and the controller that WRITES the
  marker imports them. `persistSourceVideo`/`unpersistSavedVideo` take an
  optional `paths` and consult it; `downloadOneManaged` passes it. A caller that
  omits it opts out, which is right for a per-channel store elsewhere.
  `editor/app/storage/lib/storeBusy.ts` is the courtesy half — a sentence before
  the operator commits — and its kind list is deliberately NOT exhaustive,
  because the marker is the guard.
- **The swap links defensively and records only once the link reads back.**
  `moveFileCrossDevice` does an unconditional `mkdir -p`, so a persist between
  the rename and the symlink recreates `saved-videos` as a real dir; an EMPTY
  one is removed and linked, a non-empty one refuses, and
  `savedVideosLocationId` is never written without a link.
- **Two consecutive down passes before the watch pauses; one up pass to
  restore.** Availability is a bare `stat` with a blanket catch, so EIO or a
  spun-down disk reads as "not mounted". The pending count is MODULE state, not
  settings (`resetStorageWatchSuspicion()` is the test seam). The watch also
  calls `maybeAutoRepoint` now, so a drive that comes up elsewhere while the
  editor is running no longer waits for a reboot.
- **Move-back deletes the target only when the run can vouch for the local
  copy** — it did the swap, the marker says a previous run got past it
  (`phase: "reclaim"`), or `measureTree(store) >= measureTree(target)`.
  Otherwise it finishes, clears the marker and says what it did not delete: "a
  real directory" is also what `rsync --copy-links` produces.
- Smaller, same commit: a resumed copy's bar is offset by `measureTree(dest)`
  taken before the copy (rsync counts only what IT sent, so a resume topped out
  at 40 %); `rsyncTree` buffers the trailing segment across chunks and flushes it
  at exit, so a torn frame never parses as `bytes=0`; the parked name is
  `saved-videos.relocated-<ts>` swept by prefix; a store that never existed is
  created empty rather than failing rsync 23 behind a stuck marker; both sides of
  the containment check are realpath-resolved; and deleting a location the store
  is on is refused in the action AND withheld on the row.

---

## The ops API (`/api/ops/*`) — added 2026-09-20

**It is adapters, and nothing else.** Each route under
`editor/app/api/ops/<action>/route.ts` is ~5 lines: validate a JSON body, call
ONE existing server action, map its result. No route contains a rule the UI does
not already enforce — the point of the layer is that an agent over HTTP and an
operator clicking the same button get the same refusal, with the same sentence,
from the same code. A check written in a route would be a second opinion nobody
maintains. `editor/app/api/ops/_lib.ts` holds auth, body parsing and the three
result mappers (`jobResponse` / `actionResponse` / `queueResponse`).

**`WORKER_TOKEN` is shared with `/api/worker/*` by design.** It already means
"this instance accepts instructions from something that is not the browser in
front of it", and the failure modes are identical, so the gate is: unset → 503
(the surface is off until you opt in), wrong → 401. `authorizeWorkerRequest`
(`common/lib/workerToken.ts`) is the single implementation; nothing new was
written. A second secret would be a second thing to distribute, rotate and leave
unset.

**A job-starting route returns `{ ok: true, jobId }` and NEVER streams.**
`runManagedFunction` hands back a `ReadableStream` the browser consumes; an HTTP
caller wants to hang up and poll. Every job adapter calls `result.stream.cancel()`
— which stops pushing into the controller and leaves the on-disk log running
(`streamCommand.ts`'s `cancel()` note) — and the caller follows
`/api/jobs/<id>/log`. Returning the id is also the honest answer: the queue may
hold the job behind other work for hours, so "started" is not "running".

**Unknown body keys are a 400, never a silent ignore.** The allow-list passed to
`ops()` IS the route's documented body shape. A caller that misspells
`downloadFilterExclude` would otherwise get `{ ok: true }` and a channel that
still downloads everything.

**`ops/channel-config`'s patch keys are the FORM's field names, not
`ChannelConfig`'s** — `downloadFilterInclude` / `downloadFilterExclude` rather
than a `downloadFilter` object, `ytdlpExtraArgs` as a string or an array of
lines. That is what routes them through `parseChannelForm`'s validators. The
patch is laid over the channel's CURRENT form representation
(`editor/app/channels/components/channelConfigToForm.ts`) rather than posted
alone, because `updateChannelAction` deletes every `CHANNEL_FORM_FIELDS` key from
the stored config before layering the parse result on — a FormData carrying only
a patch would clear everything the patch did not name.

**`GET /api/ops/channel/<slug>`'s live counts are opt-in (`?counts=1`).**
`readChannelStat` walks every video directory — eleven thousand readdirs on the
largest channel here — so a poll loop asking for a channel's state would be the
thing hammering the platter. The report's totals answer the same question from a
file. The field is `counts` and is null without the flag.

**No action needed a refactor to be callable from a route.** `revalidatePath` is
supported in Route Handlers (Next 16 —
`docs/01-app/03-api-reference/04-functions/revalidatePath.md:10`), no adapted
action calls `cookies()`, and the only actions that `redirect()`
(`createChannelAction`, `gotoVideoAction`) are deliberately not exposed.

**The 503-when-unset branch is not covered by e2e.** The editor test server runs
with `WORKER_TOKEN=test-worker-token` in `editor/package.json`'s `dev:test`, one
server for the whole suite, so no spec can observe the disabled state.
`editor/e2e/ops-api.spec.ts` covers 401 (missing and wrong); the 503 is
`authorizeWorkerRequest`'s own first branch, shared with `/api/worker/*`.

---

## Storage debts (verified 2026-09-21, branch `storage/debts-1`)

The sweep FACTS asked for above ("a later sweep owes three things: the recursion
or an explicit clips total, a count on the storage page, and an eviction rule").

### `clips/` is counted now, and `totalMediaBytes` GREW

- **`snapshot.totalMediaBytes` includes clip windows.** The `mediaBytes` loop in
  `channelSnapshot.ts` recurses ONE level into `data/<id>/clips/` and nothing
  else; the old `if (!st.isFile()) continue` sat under a comment saying "a video
  dir is flat", which the clip-window feature made untrue. The definition did
  not change — it was always "every byte under `data/<id>/`" — the number did.
  Four readers see a slightly larger, correct figure: the /storage rows, the
  /channels Size column, the free-up selection and the relocation preflight.
  Nothing partitions on it.
- **`totalClipsBytes` is the "of which", not a sibling.** Optional on the same
  terms (absent means "unknown until Refresh report", never 0; a fresh snapshot
  always writes it, 0 included). Split out because clips are the one part of a
  channel's bytes that is a CACHE nothing prunes.
- `LocationRollup.clipsBytes` and `StorageRow.clipsBytes` carry it to /storage;
  the video page folds `listClipWindows`'s own per-window `bytes`, which costs
  no I/O. There is no `unknownClipsBytes`: it would be the same set of channels
  `unknownBytes` already counts.

### Eviction is BY AGE, and that is load-bearing

- `common/controller/evictClipWindows.ts` is the only thing that removes a
  window. **Whether a window is still WANTED cannot be known from the editor**:
  a umtool report's manifest cites spans, and those manifests live in a umtool
  project — possibly on another machine, possibly not written yet. There is no
  reference count and no honest way to invent one. Every surface says so (the
  /storage card's caveat block, the job log's second line, the route header).
  An evicted window is re-fetchable: the cost is a fetch, not data.
- **The age is the MTIME, not the provenance sidecar's `fetchedAt`.** A window
  whose sidecar was never written (a fetch interrupted after the media landed)
  would otherwise be un-evictable forever — exactly backwards. `rsync -a`
  preserves mtimes, so a relocated channel's windows keep their real ages.
- `needsMedia: true` on the job kind covers a one-channel run;
  `inspectChannelMedia` inside the controller covers the corpus-wide one, where
  there is no slug for `runManagedFunction` to check. Without it the pass
  reports a clean eviction of zero bytes about a platter full of windows.
  `in-transition` is refused outright: the mover's verify pass compares trees.
- **Per-channel eviction has no UI.** `evictClipWindows` takes a `slug` and the
  job sets `channelSlug` (which is what makes the snapshot regen land), but the
  only caller that passes one is `POST /api/ops/evict-clips`. The /storage card
  is corpus-wide, which is the shape the bytes have — a channel page button is
  the obvious next surface and nothing blocks it.
- The empty `clips/` is left behind on purpose — `rmdir` would race a fetch that
  just created it, and an empty directory is invisible to every video-dir
  enumerator anyway.

### `volumeFreeBytes` tests the mount boundary AT THE MOUNTPOINT

- **Comparing `stat(root).dev` with its parent's is wrong**, and it broke the
  only location on this machine. A root is `join(mountpoint, relPath)`;
  `platter` is `/run/media/user/<uuid>/archilyzer-media`, a SUBDIRECTORY of the
  mountpoint, so root and parent are on the same filesystem by construction and
  /channels reported "free space unknown" for a correctly mounted drive. A bind
  mount reads the same way. The question is asked of `volume.mountpoint`
  against its own parent — two syscalls, because TABLES NEVER PROBE rules out
  `probeLocation`. Only for a location that has learned a `volume.uuid`.
- A unit test cannot mount anything and a tmpdir has no boundary in it at all —
  which is exactly the shape that made the broken version look right. The test
  FINDS a real one (/run, /dev, /sys, /proc) and points a root at a plain
  subdirectory of it.

### `assertRelocationRootPresent`

- **Every absolute `mkdir` in both movers is `{recursive: true}`**, so a move
  aimed at an unmounted root built it on the root filesystem and filled it. Two
  checks: `stat(root)` is a directory, and — when the root belongs to a location
  carrying a learned `volume.uuid` — the probe answers `available` with a KNOWN
  identity whose uuid matches. An empty mountpoint directory passes the first
  and fails the second, because findmnt -T reports the root filesystem's uuid.
- **It FAILS OPEN on unknown identity** (a container has no block devices) and a
  root nobody named as a location is STAT-ONLY. Called from
  `relocationRootProblem` — so preview and action agree — and again immediately
  before each copy phase's mkdir, because a job can sit in the queue for hours.
  On the move-BACK paths the guard is on the LOCATION ROOT, not on `incoming`.
- **The probe memo moved to `lib/storageVolumes.ts`** (re-exported from
  `controller/storageLocations.ts`): the guard probes and is called per channel
  by the bulk move and the re-point preflight, but the controller imports
  `relocationRootProblem`, so reaching the memo through it would be a cycle.

### `relocateChannelMedia` takes an `io` settings seam

- The space check demands `bytes + resumeMarginGB` free, default 2 GB, and the
  unit-test fixtures live under `os.tmpdir()` — a tmpfs sized from RAM. Eight
  tests failed on this machine with "2.9 KB to move plus a 2 GB resume margin".
  The tests now inject `minFreeDiskGB: 0`, which is production's own rule
  (`minFreeDiskGB > 0 ? resumeMarginGB : 0`), not a faked margin.
  `relocateSavedVideos` already had the seam, which is why none of its tests
  were in the failing set.

### `/api/jobs/<id>/log` is deliberately ungated

- **It leaks job log text by id**, plus status and queue position: yt-dlp output,
  slugs, video ids, corpus paths. Not credentials (a step's env is never logged)
  and not media.
- **Gating it would switch every run panel off on a default install.**
  `authorizeWorkerRequest` answers 503 when `WORKER_TOKEN` is UNSET, and the
  browser polls this endpoint same-origin with no token. The boundary is
  `docker/guard-exposure.sh` plus Caddy binding 127.0.0.1, not this route.
  `scripts/archilyzer-ops.mjs`'s `followJob` sent an authorization header to it;
  that header is gone, because implying a gate that does not exist is worse than
  sending nothing.

### A fan-out now returns its job ids

- `QueueOutcome.jobIds` is parallel to `queued`, and `queueResponse` emits it
  plus a bare `jobId` when exactly one job started. Without it `pnpm ops
  relocate --wait` found no id, concluded nothing had been started and returned
  0 — reporting success about a copy that had not begun. Both fields are
  additive; `queued` keeps its meaning and spelling.

### A full source reaches the build through the pointer, not through `clips/`

- `full: true` puts the whole recording in the SAVED-VIDEO STORE, which is on
  another path and possibly another drive — so the only way back to it is
  `data/<id>/saved-video.json`. `clipWindowDirs` (`umtool/lib/projects/report.mjs`)
  is now ASYNC and emits `{video, dir: pointer.dir, duration}` beside the clips
  dir; `rawCacheOf`'s `SOURCE_MEDIA_RE` branch then counts the container as the
  window `[0, duration]`.
- **The duration comes from the cue doc, and ONLY for a video that has a
  pointer.** `rawCacheOf` needs a finite duration; the cue file is the archive's
  own record of it, and it is the expensive input that module memoises against
  mtime. Reading it for the handful of videos somebody fetched a full source for
  keeps the index load exactly as cheap as it was. No duration ⇒ no entry, never
  a guess.
- The bench's "fetch whole source via editor" SKIPS the cached-window check in
  `/api/report/fetch`: that check asks "does a file hold this span", and a full
  source is not a span. There is no local (`UMTOOL_LOCAL_FETCH`) twin — a
  machine with no editor has nowhere to put a full source anything else finds.

### `/review` lists what the machine decided

- `common/views/review.ts` (`autoPausedRows`) over `settings.channelPriority`.
  A channel a PERSON paused is not a row. Resume is `setChannelTierAction` — the
  ONE priority writer — posting the `previousTier`, which is the whole content
  of the record; a manual tier change is also what clears `autoPaused`.

### The four nits that were numbers that could lie

- **`volumeFreeBytes` believed an unmounted mountpoint**: the directory existing
  is not the drive being there, so `getFreeBytes` reported the PARENT volume's
  free space — the disk being emptied. `st.dev` vs the parent's is what a mount
  is; asked only when the location has a `volume.uuid`.
- **"Free up N GB" proposed channels mid-relocation**, which the bulk move
  refuses by name — a guaranteed skip whose bytes inflated the promise.
  `FreeUpSelection.moving` counts them separately from `unmeasured`.
- **`bytesOnLocation` travelled without its caveat**; `unknownBytesOnLocation` /
  `unknownBytesInPlace` now pair with it.
- **"internal" was an available location id** in both the form regex and the
  sanitizer. `INTERNAL_LOCATION_ID` moved to `lib/storageLocations.ts` so
  `lib/settings.ts` can refuse it (lib may not import controller).
- Also: `measureTree` in `buildStorage.ts` ran per render on a `force-dynamic`
  page an AutoRefresh re-renders. `editor/app/storage/lib/measureStore.ts` caches
  60 s, 32 entries; `measureTree` is BANNED in
  `noCorpusWalkInRenderPaths.test.ts` with an allow map naming that one file, and
  the ban's match is word-bounded so `measureTreeCached` is distinguishable.

### The umtool suite skips instead of going red without the song data

- **`make-fixture.mjs` used to throw on its first readdir of `SONG_DATA`**,
  taking the ENTIRE suite down before the test server started — including the
  two dozen specs that have nothing to do with the song project. It tolerates
  a missing or partial source now.
- **`fixtures/song-capabilities.mjs` is the one rule, read by two callers.**
  `make-fixture.mjs` writes `fixture-capabilities.json` as the record (and
  warns on stderr); `e2e/capabilities.ts` answers the same question for the
  specs, **from the SOURCE directories rather than from that file** — Playwright
  loads spec modules to build its test list and the fixture is built by a
  `webServer` command, so on a fresh checkout the file is not there yet and a
  helper that failed closed on its absence would skip the song suite on a
  machine that HAS the data.
- Three capabilities, because they are three halves of the same absent archive:
  `song` (cand2 + wav48), `media` (the face deck reads source videos), `asr`
  (the phrase console runs against the real corpus).
- Skipped, each confirmed failing on main under the same missing data: browse
  (3), deck (2), faces (6), find (whole file), triage (whole file), usage
  (whole file), undo (3 of 4 — the empty-journal refusal still runs), projects
  (1).
- **`mix.spec.ts` IS ORDER-DEPENDENT, in both directions, on main.** In a full
  suite run `:166`/`:201` fail and `:110` passes; in a four-spec run it is the
  other way round. The fixture is built once per suite invocation and earlier
  specs leave clip windows in `channels/testchan/data/<id>/clips/`, which
  `projectCache` folds in — so which file `containing()` picks depends on what
  ran first. Not a capability, not skipped, and it predates this work.

## The 2026-09-22 release — curated-tags follow-ups + debts sweep (`main` @ `766e0873`)

Three branches off `4ac8ceda`, merged in order: `1a011d96` alone, then `tags/rules-and-ops`
(`9837f066`), `export/tags-followups` (`cb254919`), `editor/debts` (`766e0873`).

### A tag can exist on some sites only (`sites`, 2026-10-06)

- `CuratedTagDef.sites?: string[]` (`common/lib/curatedTags.ts`): the site ids a tag EXISTS on;
  absent or empty = every site. Corpus layer only — `coerceTagDef` drops it from a site's
  tags.json, so a site cannot widen or narrow it. Not presentation (that is `hidden`).
- **Derivation:** `curatedTagsRuntime(config, members)` resolves `scope` = tag id -> the channel
  slugs of its sites' members (`tagChannelScope`; `loadCuratedTagsRuntime` reads `listSites`).
  `deriveCuratedTags` ends with `scopeTagsToChannel`: neither a rule hit nor a PIN carries a
  scoped tag to a video on a channel outside its sites. `needsCaptionCues` / `needsChatCues`
  skip a scoped tag's rules there too (no cue read is paid for them).
- **Per site:** `buildIndex` filters each site's summaries through `tagsForSite`, so a channel
  that is a member of an allowed site AND of another publishes the tag on the allowed one only
  — summaries and `tag-counts.json` (compose then writes no `/tags.json` entry). The SHARED
  per-channel transcript pages of such a dual-member channel still carry it (one byte-stream
  for every site); the viewer renders an id its site does not publish as the raw id.
- **The hash:** `hashCuratedRules(defs, scope)` folds the resolved scope in ONLY when some tag
  is scoped, so shipping the field re-derives nothing; scoping a tag, or changing the membership
  of a scoped tag's sites, changes `curatedRulesHash` and the next `build-index` re-derives the
  corpus once (the `rulesChanged` branch below).
- Written like every def: the /tags page's **Sites** box (`aria-label="tag sites"`), or
  `pnpm ops tags --json '{"op":"define","tag":{…, "sites":["anilyzer"]}}'` (the whole def).

### A rule can exclude channels, and the exclusion wins — and it re-derives the corpus once

- `CuratedTagRule.channelsExclude?: string[]` (`common/lib/curatedTags.ts:54`), compiled to a
  `Set | null` on `CompiledTagRule` (`:459`, filled at `:503-506`). `ruleApplies` (`:531`)
  tests the allow-list FIRST (`:535`) and the exclude SECOND (`:539-541`), so **a channel
  named in both is excluded**. That ordering is the contract, not an accident of the code.
- **The trap is the hash, not the rule.** `channelsExclude` is part of the shape
  `hashCuratedRules` digests (`common/controller/curatedTagsIndex.ts:75`, the field at `:86`),
  so merely SHIPPING this commit changes `curatedRulesHash` for every existing rule set. The
  first `build-index` after the deploy therefore takes the `rulesChanged` branch of
  `reapplyCuratedTags` (`curatedTagsIndex.ts:333`, branch at `:421-434`), which walks
  **`sums.getRange({snapshot: false})` — every record in the corpus** — rather than the
  targeted `byChannel` scan an assignment-only change takes. Measured ~80 s on the live
  corpus, once. The build log says which branch ran: `curated tags: rules <hash8> (changed)`
  (`:484`, combined line at `:487-490`; the full-rebuild variant is at `:359`). A reviewer who
  sees an 80 s re-derive on a deploy that "only added a field" is looking at this, and it is
  correct.

### A site layer carries no rules — dropped on READ and on WRITE

- `coerceTagDef(raw, layer)` (`common/lib/curatedTags.ts:214`) forces `rules: []` when
  `layer === "site"` (`:235-238`), and `readSiteTags` / `writeSiteTags`
  (`common/lib/curatedTagsStore.ts:94-113`) both call `sanitizeTagsConfig` with
  `{layer: "site"}`. So a rule hand-written into `sites/<id>/tags.json` is **removed from the
  file the next time the editor writes it**, not merely ignored at merge. `mergeTagDefs`
  (`:371`) has no rule branch left to reach; the header comment stating the rule is
  `curatedTagsStore.ts:9-17`.
- Why, restated because it is the kind of rule people "fix": a record is shared by every site
  that carries its channel, so a site-layer rule could only tag records the OTHER sites also
  publish. The site layer is presentation — `label/groupLabel/color/order/hidden`.

### `--wait` polls a log route, and a dropped poll is not a failure

- `followJob(jobId, quiet, opts = {})` — `scripts/archilyzer-ops.mjs:296`, with
  `opts.fetch` / `opts.sleep` / `opts.now` injectable (`:297-300`), which is what makes it
  testable (`scripts/archilyzer-ops.test.mjs:8,156`).
- **`/api/jobs/[id]/log` is a POLLED JSON route, not a stream.** It returns
  `{content, nextOffset, status, queueKey, queuePosition}`
  (`editor/app/api/jobs/[id]/log/route.ts:55-61`) and `pollLog` re-fetches with `&from=<n>`
  (`archilyzer-ops.mjs:311-322`). There is no SSE here — do not reason about `--wait` as if a
  connection were being held open.
- A poll that throws returns `null` rather than propagating (`:311-322`, the reason spelled
  out at `:270-278`: *a poll failure is not a job failure*). After three consecutive failures
  it asks `/api/jobs/active` (`stillListed()`, `:324-332`) and keeps waiting if the job is
  still there. Probe failures are bounded by `MAX_PROBE_FAILURES = 10` (`:64`, enforced
  `:383-386`), and `--wait-timeout` bounds the whole wait (`:123,135,138,142-143`, enforced
  `:390-396`).
- **A recovered poll that answers `queued` or `running` is not an outcome** (`94750a1b`) —
  the earlier shape treated any successful re-poll as terminal.

### `reqSiteIds` — both build routes take `siteId` or `siteIds`, and a bad id is 400 before any job

- `export function reqSiteIds(body: OpsBody): string[]` —
  `editor/app/api/ops/_lib.ts:179-199`. It throws `OpsInputError` for both keys at once
  (`:183`), for neither (`:189-191`), and for any id failing `isValidSiteId` (`:195-197`).
- Both `build-site/route.ts` and `build-deploy/route.ts` call it, and the whole array is
  validated before the fan-out loop's body runs — so **an invalid site id can never start a
  partial fan-out**. `OpsInputError` is caught in `ops()` (`_lib.ts:77-79`) and mapped by
  `opsFail`, whose default status is 400 (`:35-41`).
- `build-deploy` returns `{ok: true, jobs, skipped}` plus `jobId` only when `jobs.length === 1`
  — a caller that reads `jobId` unconditionally breaks on a multi-site body.
  > **Superseded by release 18 (2026-10-06):** with `all`, `build-deploy` and `build-site` also answer a top-level `jobId`, the run's last job — see "The publish stages" at the end of this file.

### `wt rm` finds the directory `wt add` made

- `worktreeDirFor(main, name)` — `scripts/worktree.mjs:81-84`. Absolute names pass through;
  everything else is flattened with `name.replace(/[^A-Za-z0-9._-]/g, "-")` under
  `dirname(main)`, so `tags/site` → `…/tags-site`. `cmdRm` (`:289-306`) calls it at `:300`.
  One function for both verbs is the point: the flattening cannot drift between them.
  Covered by `scripts/worktree.test.mjs:17,19,25,27,36-37,43`.

### The four-lane status poll reads the corpus ONCE

- `computeLeafPending(kind, paths = getPaths(), shared?: {configs?, state?})` —
  `common/controller/autoRunner.ts:919-927`. Without `shared` it reads the channel configs and
  `.auto-queue/state.json` itself, which is four corpus reads per `/operations` tick.
  `buildAutoQueueStatusPayload` (`editor/app/operations/status.ts`) now reads both ONCE via
  `Promise.all` and passes the pair to all four lanes.
- **This CORRECTS `plans/one-core-phase-3.md:466-468`**, which says the two are "still called
  four times per poll … (not claimed fixed; the reads are in-memory)". The parenthetical was
  wrong even then: `computeLeafPending`'s reads were on disk. `getAutoRunnerStatus` is still
  per-lane and IS in-memory.

### `shipsPwa` now carries the `typeof process` guard (amends "server-called only")

- `common/lib/archive/contract.ts:203-207`:
  `site.pwa === true || (typeof process !== "undefined" && process.env.INSTANCE_MODE === "hub")`.
- **The guard stops a crash; it does not make hub detection work client-side** — the comment
  at `:183-198` says so outright. `INSTANCE_MODE` is neither `NEXT_PUBLIC_`-prefixed nor in a
  `next.config.ts` `env:` block, so Next never inlines it and a client bundle reads
  `undefined`. What changed is only the failure mode of a future client import: it evaluates
  to `false` (no PWA) instead of throwing `ReferenceError: process is not defined`. Hub
  detection stays server-only. The earlier entry's "**A future CLIENT caller owes the guard**"
  is now paid; its correction about inlining still stands and is still the thing people get
  wrong.

### Tag chip groups fold, and the summary says how many are selected

- `FiltersPanel` (`common/components/FiltersPanel.tsx:135`) renders one `<details>` per tag
  group (`:889`, `data-testid="tag-chip-group"`), open-state from
  `collapsedTagGroups: Set<string>` (`:786`) via `toggleTagGroup` (`:789`) and
  `open={isOpen}` where `isOpen = !collapsedTagGroups.has(key)` (`:877`). The `<summary>`
  shows `{selectedCount} selected` (`:923`, in `data-testid="tag-group-selected"` at `:920`)
  only when `selectedCount > 0`. The state is LOCAL to the panel — folding a group is not a
  filter and never touches the URL.

### `SCOPE_LABELS` is the one scope-label table

- `export const SCOPE_LABELS: Record<LayerScope, string>` —
  `common/components/QueryLeafView.tsx:50-56`:
  `transcripts: "Transcripts"`, `chat: "Live chat"`, `posts: "Posts"`,
  `metadata: "Title / channel"`, `description: "Description"`, **`tags: "Keywords"`** (the
  yt-dlp-keyword scope — the naming hazard, kept out of the curated-tag vocabulary).
- Used by its own `<select>` at `:215` and imported by `SearchResults`
  (`common/components/SearchResults.tsx:36`) for the leaf-section heading at `:706`.
- **Checked 2026-09-22: nothing else in `common/components` or `export/` holds a second copy**
  of this map. The remaining string matches are the definition, comments about it, and e2e
  specs asserting rendered text. The two surfaces are label-consistent by construction, not by
  coincidence — so a relabel is a one-line change.

### `e2e:2origin` is GREEN — the ~:4100 entry is CLOSED

- The hub `/ask` prerender crash (`useSearchSession must be used within a
  SearchSessionProvider`) is fixed by **giving the page the whole provider stack**, not by
  opting out of prerendering. `export/app/ask/AskHub.tsx:41-52` mounts, in order,
  `PlayerProvider` → `MultiSiteDataProvider` → `SearchSessionProvider` → `AskChat`, with
  `TranscriptModal` and `PostModal` as siblings inside `PlayerProvider`. The comment at
  `:31-38` records that none of them is optional and that "the fix is the stack, never an
  opt-out of prerendering"; there is no `force-dynamic`, no `dynamic =`, no `ssr: false` on
  that route or the workspace layout.
- `export/e2e-hub/ask.spec.ts` covers it (`test.describe("hub /ask")` at `:26`).
  `pnpm --filter export run e2e:2origin` passes **3/3** — the first green run since hub
  `/ask` existed. The known-red note above it is history; do not skip the suite on its word.

### A curated-tag filter takes posts OUT of an MCP search

- Posts carry no `curatedTags` — the field is on `TranscriptSummary`, and a post is not a
  video — so a search that both asks for posts and filters by tag would scan every post page
  to return nothing. It doesn't: `postsSkippedForTagFilter` (`mcp/src/search.ts:562-563`) and
  `const wantPosts = postsAsked && !postsSkippedForTagFilter` (`:564`) gate the posts pass at
  `:710`; the query-tree path does the same through `wantsPosts` (`:1156-1159`).
- It is REPORTED, never silent: `postsScanned` gains
  `skippedForTagFilter: boolean` beside `requested` / `channels` / `pages`
  (`mcp/src/search.ts:241-246`, assembled `:792-797`), and `describePostsPass`
  (`mcp/src/server.ts:1367`, called `:1247` and `:1459`) emits, verbatim
  (`:1371-1374`):

  > `posts: skipped — a tag filter was given and posts carry no curated tags (the export UI does the same)`

  The parenthetical is load-bearing: the export UI drops the posts section under a tag filter
  for the same reason, so the two surfaces agree and neither is a bug report.

### The channel page can evict that channel's clip windows

- `ClipWindowsCard` — `editor/app/storage/components/ClipWindowsCard.tsx:62-79`,
  `{clipsBytes, slug?, blockedReason?}`. With no `slug` it is the corpus-wide card on
  `/storage`; the channel Storage panel mounts it WITH one
  (`editor/app/channels/[slug]/components/stages/StorageStage.tsx:187,200,236-239`), and the
  panel's own `blockedReason` — `channelMediaBusyReason`, computed at
  `editor/app/channels/[slug]/page.tsx:595-596,625` — disables it (`:87`, `:194`, `:205`).
  One card, two scopes; there is no second eviction UI.
- **The by-age caveat is shown, not buried** (`:122-127`): *"Eviction is by age only. Nothing
  here can know whether a report still cites a window — those manifests live in umtool
  projects this editor cannot see. An evicted window is re-fetchable, so the cost of getting
  this wrong is one fetch, not data. Preview first."* Every surface that prunes `clips/` says
  this, because there is no reference count and there cannot be one.
- `evictClipWindowsAction` (`editor/app/storage/actions.ts:421-452`) validates the slug
  (`:439-445`, `isValidChannelSlug` then `channelExists`) before it walks anything;
  `editor/app/api/ops/evict-clips/route.ts` is a thin adapter onto the same action.

### Rename and delete refuse while a channel's media is busy

- `channelMediaBusyReason(slug, what?): string | null` —
  `editor/app/channels/lib/mediaBusy.ts:33-53`. Delete calls it at
  `editor/app/channels/actions.ts:609` (`"deleting it"`), rename at `:679`
  (`"renaming it"`); the same function feeds the Storage panel's `blockedReason`, so the
  button and the action can never disagree.
- The `.relocating.json` refusal thrown by `deleteChannel` itself reaches the form as
  `{error}` rather than a 500 (`actions.ts:618-621`) — the operator could not read it before.

### Sync all skips a channel whose media drive is not mounted

- `syncAllChannelsAction` passes a `skip` to `queueForSlugs` that calls `inspectChannelMedia`
  (`editor/app/channels/actions.ts:571`) and returns, verbatim (`:572-574`):
  ``` `media ${media.status}: ${media.detail ?? "not reachable"}` ``` for any status that is
  neither `ok` nor `in-place`. **An unmounted drive is not an empty channel** — without this,
  a sync-all would have walked the absent `data/` and read the whole channel as undownloaded.
- **Do not cite `common/controller/autoRunner.ts:582-583` for this string.** The scheduler's
  own skip log is `media ${status} — ${detail}` (em dash, no colon). Two call sites, two
  formats; only the colon form is the sync-all action's.
- Driven end to end by the real button:
  `editor/e2e/channel-storage.spec.ts:794` *"Sync all skips a channel whose media drive is not
  mounted"*, asserting `media unreachable: … drive not mounted` (`:816-819`).

### Worker auth is 503 when no token is configured, not 401

- `authorizeWorkerRequest` (`common/lib/workerToken.ts:23-43`) returns
  `{ok: false, status: 503, error: "worker endpoint disabled (set WORKER_TOKEN to enable)"}`
  when `WORKER_TOKEN` is unset (`:25-31`) — **before** it looks at what the request carried,
  so no credential can talk its way past an unconfigured endpoint. 503 and not 401 because
  the endpoint is disabled, not the caller rejected.
- `common/lib/workerToken.test.ts:39-59` pins it (*"no token configured: every request is 503,
  whatever it carries"*), and `editor/app/api/test/worker-token/route.ts` exposes it to e2e.

### EVERY `/api/test/*` route 404s unless `EDITOR_TEST_ROUTES=1`

- `testRouteDenied()` — `editor/app/api/test/_guard.ts:23-26` — returns a 404
  `{error: "Not Found"}` unless `process.env.EDITOR_TEST_ROUTES === "1"`, and returns `null`
  (proceed) otherwise. All five routes under `editor/app/api/test/` call it:
  `stuck-job`, `invalidate-cache`, `resume-lane`, `worker-token`, `uncaught-count`.
  **Checked 2026-09-22: none is missing it.** A new route under that directory owes the first
  line of its handler to this guard.
- `EDITOR_TEST_ROUTES=1` is set by `dev:test` and `start:test` only
  (`editor/package.json:8-9`), so a production `start` serves 404 for all of them. It is a
  404 and not a 403 on purpose: the route does not admit it exists.
- **AMENDED 2026-09-28 (release 11 O6-B): the variable is `E2E_TEST_ROUTES`** (`_guard.ts:25`), and
  it is set by `editor/playwright.config.ts`' `E2E_SERVER_ENV` (`:38`), NOT by `dev:test` /
  `start:test` any more. A hand-started `dev:test` therefore serves 404 on every `/api/test/*`; a
  server reused under `E2E_PORT_CHECK=0` must be started with `E2E_SERVER_ENV`'s values
  (WORKTREES.md). A production `start` still serves 404.

### S0-pause — the four legacy pause fields are DELETED, and `held` defaults per lane

- Gone from `SiteSettings`, from every sanitizer, and from `writeSettings`' merge literal
  (`common/lib/settings.ts:1713-1718` at the time; since 2026-09-23 the writer parses through
  `siteSettingsSchema`, `settings.ts:242`): `transcriptionsPaused`, `downloadsPaused`,
  `digest.digestsPaused`, and the inverted `backfill.enabled`. A `settings.json` that still
  spells one is read past on load and **loses it on the next write**. `legacyGateHeld` and
  `migrateHeldToLanes` no longer exist anywhere in the tree.
- **`common/lib/laneMigration.ts` still exists** and is not a leftover: it hosts
  `migrateSweepsToLanes` (slice 1.3's sweep-scope migration), which is live. Its header
  (`:6-12`) says the pause migration is the part that went.
- **The default is the retired fields' reading, preserved.** `defaultHeldFor(lane)`
  (`common/jobs/autoQueuePolicy.ts:684-686` then; `common/lib/autoQueueSchema.ts:204-206` since
  2026-09-23) is `lane === "backfill"`, applied by
  `sanitizeAutoQueue` at `:749` (now `autoQueueSchema.ts:269`) (`held: typeof r.held === "boolean" ? r.held : defaultHeldFor(lane)`)
  and by `defaultAutoQueuePolicy` at `:695` (now `:217`). The three paused-flags defaulted false; the
  inverted `backfill.enabled` defaulted false and therefore shipped the backfill lane HELD,
  which is why backfill's default is the odd one. Defaulting became REQUIRED rather than
  merely tidy: from slice 1.4 until S0-pause an absent `held` had a legacy field to fall back
  to, and now it has none.
- **The backfill lane is off twice over on a fresh install** — unarmed (`enabled: false`) and
  held. That is gate B kept as two deliberate acts, not one. Asserted through the sanitizer,
  where a reader would actually hit it:
  `common/jobs/autoQueuePolicy.test.ts:396` (was `:390`) *"sanitizeAutoQueue: a lane naming no gate gets
  the default its retired field gave it"*.
- **A grep for `downloadsPaused` still hits, and it is not a survivor.**
  `common/views/workers.ts:48,109` has a view-model field of that name, computed
  `isGateHeld(i.settings, "download")`. Same word, different layer.
- `plans/tools/phase1-numbers.ts` no longer prints the retired fields; the print loop
  (`:142-144`) reads `isGateHeld(settings, lane)`, and `:131-137` says why.

### `editor/content` is GONE — the e2e blocker in the primary checkout is closed

**This supersedes both earlier entries** ("`editor/content` is a symlink out of the repo and
it panics Turbopack in dev", and "The `editor/content` symlink still blocks e2e in the primary
checkout"). Verified 2026-09-22 on `main` @ `766e0873`:

- `ls -l editor/content` → **No such file or directory.** The symlink to
  `/home/user/Projects/recipe-content` is not in this checkout any more.
- `.gitignore:110` is `/editor/content` (`1e0b10a9`, rationale in the comment at `:106-109`),
  so even if it is re-created, **`git add -A` can no longer stage it** — which was the half of
  the hazard that carried the Turbopack panic into every worktree of a commit made that way.
  The "add by path" discipline is no longer load-bearing for this file.
- What remains true and is worth keeping: a fresh `git worktree` still needs a composed
  fixture site copied into its `export/public`, or the export webServer 500s and Playwright
  dies at the 120 s `config.webServer` timeout. That was always a separate problem.

## Cloudflare Pages preview deployments (added 2026-09-23, branch `deploy/preview`)

**Every deploy this app ran before today was production, and not because it said
so.** `runDeployIntoLog` ran `pnpm dlx wrangler pages deploy <outDir> --project-name
<project>` with **no `--branch`**, and wrangler infers the branch from the git
checkout it runs in. Cloudflare Pages treats a deploy to the project's production
branch as production and any other branch as a **preview**. So the pre-existing
hazard is real and is unchanged: a "production" deploy run from a feature-branch
checkout silently lands as a preview. Only the preview path passes `--branch`.
> **Superseded by release 18 (2026-10-06):** every deploy names its branch (`--branch main` for production) and runs the pinned wrangler, never `pnpm dlx` — see "The publish stages" at the end of this file.

**The rules live in `common/lib/pagesDeploy.ts`, which is node-free on purpose.**
Four pure functions — `previewBranchProblem`, `pagesDeployArgs`, `previewAliasUrl`,
`deploymentUrlIn` — because the same rule is needed by the server action, by the ops
route (which must 400 before any job starts) and by the browser control that greys
its button out as you type. Tests: `common/lib/pagesDeploy.test.ts` (14).

- **A valid branch is `/^[a-z0-9](?:[a-z0-9-]{0,26}[a-z0-9])?$/`, max 28 chars**
  (`MAX_PREVIEW_BRANCH`). That is exactly what Cloudflare's alias sanitizer keeps
  verbatim, which is what makes `previewAliasUrl` — shown in the UI *before* the job
  ends — the alias that actually resolves. Uppercase is **refused, never
  lowercased**: silently rewriting `Main` into `main` would deploy to production.
- **`main`, `master`, `production` are refused** with "…is the production branch; a
  preview needs another name."
- **`pagesDeployArgs` with no `previewBranch` is byte-identical to the old argv.**
  Pinned by a test; the production path was not to change.

**The branch alias is `https://<branch>.<project>.pages.dev` and is knowable before
the deploy.** The immutable per-deployment URL (`https://<hash>.<project>.pages.dev`)
is only knowable after — wrangler prints it on its "Take a peek over at …" line, which
`deploymentUrlIn` scrapes off the stream as it goes past (not by re-reading the log
file). On exit 0 the job log gets ONE line: `[preview] <alias> (this deployment:
<hash url>)`, or `[deployed] <hash url>` for production.

**A preview shares the production R2 archive bucket.** R2 has no per-branch
namespace and the keys are `<siteId>/archives/<file>.zip` either way. Cheap in
practice (the upload skips any object R2 already holds at the same size), but a
*changed* archive replaces the one production's manifest links to.
`PREVIEW_SHARES_ARCHIVES_NOTICE` (`common/publish/build.ts`, moved from the editor in one-core Phase 4 slice 1) is
logged once at the top of every preview deploy, by both actions.

**Three surfaces, one rule.** `deployExportAction(siteId, { previewBranch })` and
`buildAndDeployAction(siteId, skipArchives, { previewBranch })` each call
`previewBranchProblem` and return `{ ok: false, error }` — build-and-deploy checks
*before* the build, so a typo does not cost one. **Job kinds are unchanged**
(`deploy-export`, `build-deploy`): a preview is not a different operation.
> **Superseded by release 18 (2026-10-06):** `deployExportAction` and `buildAndDeployAction` are gone and those two kinds are no longer created; a deploy is a `publish-deploy-site` stage — see "The publish stages" at the end of this file.

**`/api/ops/deploy-site` is new — deploy-only, of the already-built `export/out`.**
`POST { siteId | siteIds, preview? }`, answering build-deploy's shape plus
`previewUrl` per job (and at top level when exactly one job). It exists because
previewing is only useful if the SAME bundle can then go to production unrebuilt,
and `build-deploy` always builds. `build-deploy` gained `preview` too, but **refuses
it alongside `all`**: the all-sites runner has nowhere to thread a branch, and
building every site to ship it to production is the worst reading of the request.
> **Superseded by release 18 (2026-10-06):** `/api/ops/deploy-site` is an alias over the deploy stage, which ships the site's own stamped bundle `<exportBuildsDir>/<id>/out`, never `export/out` — see "The publish stages" at the end of this file.

**The fan-out loop is `fanOutSiteJobs` in `editor/app/api/ops/_lib.ts`**, shared by
both deploy routes — extracted, not copied, because the careful parts (one site's
throw not costing the others their job ids; zero jobs being a 400 rather than a
cheerful `{ ok: true, jobs: [] }` that `--wait` exits 0 on) are exactly what a copy
gets wrong. `optPreviewBranch` is the body reader; it is the same
`previewBranchProblem`, asked earlier.

**CLI: `pnpm ops deploy-site --json '{"siteId":"x","preview":"<branch>"}' [--wait]`.**
`previewUrlsIn` (exported for tests) reads the alias off `jobs[]`, falling back to the
top-level key, de-duplicated — the single-job response repeats it in both places.
Printed on **stderr**, last (after `--wait`'s logs), so `pnpm ops … | jq` still sees
nothing but the response.

**No e2e spec starts a deploy job, deliberately.** Every external binary the suite
touches has a fake in `editor/e2e/fixtures/bin`; **wrangler has none**, because until
previews no spec had a reason to reach a deploy. So `ops-api.spec.ts` asserts the half
decided before a job exists and proves it by watching the `.jobs/*.meta.json` sidecars
not appear; a valid preview is shown to reach the action by the refusal it gets there
("no Cloudflare Pages project"), which is distinguishable from both "unknown key" and
a branch complaint. `site-publish-preview.spec.ts` covers the control itself.
> **Superseded by release 18 (2026-10-06):** wrangler has a fake now (`editor/e2e/fixtures/bin/fake-wrangler.mjs`, via `WRANGLER_BIN`), and `publish.spec.ts` deploys through it — see "The publish stages" at the end of this file.

**Who can open a preview is a Cloudflare project setting, not ours** — *preview
deployment access*, **public by default**. Documented in `DEPLOY_CLOUDFLARE.md` →
"Preview deployments". *(2026-09-28, release 11 O6: that file is gone; the section is
`PUBLISH.md` → "Preview deployments", `:89`.)*

### Deploy-only refuses somebody else's bundle (2026-09-23)

**`export/out` is ONE directory whichever site built into it** — `resolveOutDir`
ignores its `_siteId` argument on purpose, because the basic (host) build composes
one site at a time into the shared `export/` tree. So a deploy-ONLY action ships
whatever was built last, to whichever project was asked for: building jeralyzer and
then deploying anilyzer put jeralyzer's bundle on anilyzer's Pages project, in
production, with a green log.
> **Superseded by release 18 (2026-10-06):** each target has its own bundle, `<exportBuildsDir>/<target>/out`, and a deploy ships only that; `export/out` is a link to the bundle built last — see "The publish stages" at the end of this file.

**The bundle names itself.** `compose-site.ts` writes the federation contract
`site.json` (carrying `siteId`) into the public dir, and `next build` copies
`public/` into `out/`. `common/lib/builtExport.ts` reads it: `builtSiteIdIn(outDir)`
→ id or null (missing dir, missing/unparseable file, and absent `siteId` are ONE
answer, because they mean one thing to a caller), and `builtSiteProblem(outDir,
siteId)` → the sentence or null. Tests: `common/lib/builtExport.test.ts`.

**Called in `deployExportAction` BEFORE `runManagedFunction`**, after the
`cloudflareProject` check (so a site that cannot be deployed at all still says
that). It refuses rather than rebuilding: "deploy the export" is the operator
saying *ship what is there*. `buildAndDeployAction` needs no check — it builds.
The ops route surfaces it as the 400/`skipped` reason it already returns for any
action error.
> **Superseded by release 18 (2026-10-06):** `deployExportAction` is gone; the deploy stage runs `builtBundleProblem` over the target's own bundle — see "The publish stages" at the end of this file.


## One-core Phase 3 slices 2 + 4a (verified 2026-09-23, `main` @ `ae2fa5a9`)

Every `file:line` below was grepped at `ae2fa5a9`. Records: `one-core-phase-3.md`, "Release
2026-09-23" and the two "as shipped" sections.

### One polling route — `/api/view/[name]` (slice 2, merged `8d6e84f6`)

- **The route.** `editor/app/api/view/[name]/route.ts` (41 lines): `dynamic = "force-dynamic"`
  (`:8`), `isViewName` checks the name against `VIEW_NAMES` (`:26-28`) **before any input is
  constructed** — an unknown name is a 404 with no corpus read (`:37-39`) — then
  `VIEWS[name](request)` (`:40`). No auth and no `EDITOR_TEST_ROUTES` guard, by design: the
  eight routes it replaced had none, and the header (`:15-21`) says no `/api/test/*` name may
  ever join the tuple.
- **The table is total.** `editor/app/api/view/views.ts:36`,
  `VIEWS: Record<ViewName, (req) => Promise<Response>>` — a name in the tuple with no handler
  is a tsc error. Each handler is a lazy closure that assembles its OWN inputs exactly as its
  old route did; there is no shared constructor, and adding one is the regression the header
  (`:19-35`) names.
- **`VIEW_CONTRACT`** in `common/views/names.ts:46-55` declares each view `observe` or
  `construct`; `VIEW_NAMES` is the tuple at `:20-29`, `ViewName` at `:31`. `pulse` is the only
  `observe` view.
- **Pulse observes, checked as text.** `editor/app/api/view/pulseView.ts:30` calls
  `computePulse(observeInputs())`. `editor/app/api/view/views.test.ts:33-38` is the
  context-blind ban list (`liveInputs(`, `getRegistry(`, `getSettings(`, `getWorkerPool(`);
  `:40-55` requires `observeInputs(` in `pulseView.ts` and bans the four; `:57-67` applies the
  same ban to the dispatcher `[name]/route.ts`. A comment naming one with its parenthesis
  fails it. `:79-84` is the compile-time `CleanableChannelRow` → `CleanableChannel`
  assignability check.
- **API paths are rewritten, never redirected.** `editor/next.config.ts:139-148`: eight
  `rewrites()` entries, `/api/pulse`, `/api/jobs/active`, `/api/workers`,
  `/api/auto-queue/status`, `/api/scheduler/status`, `/api/widget/{sync,actionable,cleanable}`
  → `/api/view/<name>`. A rewrite is server-internal: method, status, body and query string
  (`?rev=`) pass through, so a pinned widget or a script on an old path keeps working. The
  comment at `:117-138` explains why; the e2e suite still asserts at the OLD paths on
  purpose. `redirects()` (`:100-114`) is for PAGES only. `/api/widget/presets` is not a view
  and keeps its own route file.
- **Eight route files are deleted**: `api/pulse`, `api/jobs/active`, `api/workers`,
  `api/auto-queue/status`, `api/scheduler/status`, `api/widget/{sync,actionable,cleanable}`.
  The two route-resident builders became pure views: `common/views/cleanable.ts`,
  `common/views/widgetActionable.ts`; the per-channel row mapping is one exported
  `widgetActionableRows` (`editor/app/lib/actionable/loadActionable.ts:80`), called by the
  view handler and by `plans/tools/phase3-view-numbers.ts`.
- **One client poller.** `editor/app/lib/usePolledPayload.ts` (moved from `widget/lib/`):
  serial polling (the next tick is scheduled only after the previous one settles, `:103`),
  every tick an `AbortController` aborted on cleanup combined with
  `AbortSignal.timeout(pollTimeoutMs(pollMs))` via `AbortSignal.any` (`:94-96`);
  `pollTimeoutMs = max(10 s, 3 × pollMs)` (`:43`); `{ immediate?: boolean }` (`:37`,
  `false` for the SSR-seeded operations board and sync console). Used by `DashboardCockpit`,
  `JobsTable`, `MonitorWidget`, `useOperationsStatus`, `SyncConsole`. **Not** by
  `components/pulse.ts` (its own `?rev=` loop, `:35,:88`) or `WorkersView.tsx` (its own
  `setTimeout` loop, `:56-61`) — both poll `/api/view/*` directly.
- **Numbers tool:** `plans/tools/phase3-view-numbers.ts` — offline, read-only, `now` frozen;
  dumps `widgetActionable`, `cleanable`, `widgetSync` as sorted-key JSON.

### One settings schema — zod (slice 4a, merged `ae2fa5a9`)

- **zod is a `common` dependency** (`common/package.json:69`, `^4.3.6`). It must never reach a
  client bundle: the three zod seams live in `common/lib/settingsFieldSchemas.ts`
  (`settingsField` `:49`, `workersSchema` `:53`, `channelPrioritySchema` `:57`,
  `autoQueueSchema` `:61`), NOT beside their sanitizers, because `workers.ts`,
  `channelPriority.ts` and `autoQueueSchema.ts` are value-imported by `"use client"` forms.
- **The schema.** `common/lib/settingsSchema.ts`: `siteSettingsSchema = z.object({…})` at
  `:1436` (31 top-level fields, each `.describe()`d), `SiteSettings = z.infer<…>` at `:1543`,
  `defaults()` = `siteSettingsSchema.parse({})` at `:1548-1549`, `defaultSiteSettings()` at
  `:1555`. Every field is `z.unknown().catch(undefined).transform(coerce)` over the old
  clamp/sanitizer — no `.default()`, no `.passthrough()`. The types, constants, clamps and
  block sanitizers that were in `lib/settings.ts` live here now.
- **`common/lib/settings.ts` is I/O only — 250 lines, was 1,783.** `export * from
  "./settingsSchema"` (`:52`), so no importer changed. `getSettings` `:124-126` =
  `finishRawMigrations(siteSettingsSchema.parse(premigrateRaw(raw)), raw)` (`premigrateRaw`
  `:90`, `finishRawMigrations` `:107`); `writeSettings` `:235`, parsing at `:242-244`
  (`deriveWorkerShadow` `:187`, `validatedSocialLinks`) then tmp + rename. **Every anchor of
  the form `settings.ts:<n>` recorded before 2026-09-23 predates this layout — line numbers
  under 250 included.**
- **The auto-queue sanitizer moved** from `jobs/autoQueuePolicy.ts` to
  `common/lib/autoQueueSchema.ts` (the picker stays and re-exports every moved name):
  `defaultHeldFor` `:204-206`, `defaultAutoQueuePolicy` `:208` (`held` at `:217`), the `held`
  fallback in the policy sanitizer `:269`, `sanitizeAutoQueue` `:277`. The allow-list entry
  `lib/settings.ts -> jobs/autoQueuePolicy` is burned: **`common/architecture.test.ts`
  `ALLOWED` (`:64`) has 9 entries**, was 10.
- **Nested keys are documented by type.** `common/lib/fieldDocs.ts:14`,
  `FieldDocs<T>` requires one string per key of `T` (optional keys and every union member's
  keys included), so an undocumented new nested field is a tsc error. 24 `*_FIELD_DOCS`
  records across `settingsSchema.ts` (9), `channelPriority.ts` (4), `autoQueueTypes.ts` (3),
  `storageLocations.ts` (3), `workers.ts` (3), `transcriptionApps.ts` (1), `digest.ts` (1).
- **One editor writer.** `editor/app/settings/saveSettings.ts`: `saveSettings(patch:
  Partial<SiteSettings>)` (`:56-58`) over the pure `mergeSettingsPatch` (`:42-54`) — a
  plain-object patch value merges ONE level over the current block; arrays, scalars and
  objects nested inside a block replace. It is **the only file under `editor/app` that
  imports `writeSettings`**, and it is not a `"use server"` module. 19 `saveSettings(` calls
  in 11 action files. Not `saveSettingsBlock(block, patch)`: `channels/actions.ts` writes
  `channelPriority` and the four `autoQueue` roots in one write (header `:26-30`). The e2e
  helper `writeSettings` (`editor/e2e/helpers.ts:114`) is a different function with the same
  one-level rule.
- **Generated docs.** `common/bin/settings-example.ts` writes `settings.json.example` and
  `SETTINGS.md` (`:27-28`) from `renderSettingsExample` / `renderSettingsMarkdown`
  (`common/lib/settingsDocs.ts:61,232`); `--check` (`:33,:38`) writes nothing and exits 1 on
  drift. Regenerate: `pnpm --filter yt-dlp-transcript-common exec tsx
  bin/settings-example.ts`. `common/lib/settingsDocs.test.ts` pins both files to the
  generator (`:15-20`), that the example parses back to the defaults (`:30`), and that every
  block has a complete nested key table (`:40,:51`). **Never hand-edit `SETTINGS.md` or
  `settings.json.example`**; `SETTINGS.md:3` says so. The example deliberately omits
  `workers` (an absent key synthesizes one worker; `workers: []` would mean none until the
  next save).
- **`archiveStorage` is a required key now** (zod 4 cannot express an optional key that is
  always emitted); it always was emitted at runtime.
- **Numbers tool:** `plans/tools/phase3-settings-numbers.ts` — prints `getSettings()` and what
  `writeSettings(getSettings())` would put on disk (to a scratch copy under `os.tmpdir()`,
  never the measured file), for the live file, the example, the e2e fixture and both
  entrypoint seeds.

### Anchors above this section that are now stale (not rewritten in place)

Historical entries keep their text as a record of what was true then. These anchors point at
files deleted by slice 2 or at the pre-slice-4a `settings.ts` layout; use the entries above
instead:

- `api/pulse/route.ts:*` (the heal-consumer and running-badge notes) → `api/view/pulseView.ts`
  and `common/views/pulse.ts`.
- `api/widget/sync/route.ts:*`, `api/widget/actionable/route.ts:*`,
  `api/scheduler/status/route.ts` → `common/views/{widgetSync,widgetActionable}.ts`,
  `editor/app/scheduler/status.ts`, served through `api/view/views.ts`.
- `common/lib/settings.ts:<n>` in any entry dated before 2026-09-23, whatever `n` (the per-block
  sanitizers, the retired-pause-field table, the writer's merge literal) → `common/lib/settingsSchema.ts` /
  `common/lib/settings.ts:235-250`.
- `common/jobs/autoQueuePolicy.ts:684-749` (`defaultHeldFor`, `sanitizeAutoQueue`) →
  `common/lib/autoQueueSchema.ts:204-277`.

## One-core Phase 3 slices 3a + 4b (verified 2026-09-24, `main` @ `ef88ac4d`)

Records: `one-core-phase-3.md`, "Release 2026-09-24 — rollout, slice 3a, slice 4b" and the two
"as shipped" sections.

### One drawing per noun — slice 3a (merged `3241fed2`)

Every `file:line` below was grepped at `3241fed2`; none of the cited code files changed
between `3241fed2` and `ef88ac4d`, so they hold at `ef88ac4d`. Record: `one-core-phase-3.md`, "Slice 3a,
as shipped" (deviations 1–13 and the eight review fixes).

**The channel row**

- **One builder, no config on the wire.** `common/views/channelRow.ts`: `ChannelRowView`
  `:76-116`, `buildChannelRowView` `:176-218`. The header `:30-34` is the rule — the view
  carries the six config fields a cell draws, never `config` (cookie paths, yt-dlp args,
  download filter). `reportStateOf` moved here from `loadActionable.ts` (`:139-150`,
  three states `missing`/`stale`/`current`); `channelVolumeOf` (the page's old `volumeOf`)
  `:162-174`; `neutralChannelPriority()` `:51-60` is what a table with no Tier column hands
  the builder. The optional `mediaLocationLabel` (`:129-133`, used `:206-211`) exists so the
  dashboard still names the badge's location from the media TARGET
  (`editor/app/page.tsx:106-108`); every other caller gets the volume's label.
- **One set of per-channel counts.** `common/views/actionableCounts.ts` (`undownloadedCountOf`
  `:40` … `cleanExtraFormatsBytesOf` `:106`); `loadActionable.ts:46-68` are one-line
  `actionable*` wrappers over them, so no caller moved. The dashboard's Videos / Digest-to-do
  cells and the widget's "Needs work" strip read the same functions; the dashboard's "Needs
  work" SSR seed is `buildWidgetActionablePayload(widgetActionableRows(rows))`
  (`editor/app/page.tsx:115`) — the same two calls the `widgetActionable` view makes.
- **Columns are a REGISTRY BY ID.** Ids, sort keys, `PipelineColumn` and the three presets are
  in the directive-free `editor/app/channels/components/channelColumnPresets.ts`
  (`ChannelColumnId` `:8`, `ChannelSortKey` `:30`, `PipelineColumn` `:46`, `RACK_COLUMNS`
  `:63`, `DASHBOARD_COLUMNS` `:79`, `WORK_COLUMNS` `:89`); the cells are
  `CHANNEL_COLUMNS` in the `"use client"` `channelColumns.tsx:114` (keyed by every id but
  `select` and `pipelines`, which the table draws itself), which re-exports the presets for
  client importers (`:19-28`). **WHY the split: a server component that imports a VALUE from
  a `"use client"` module gets a client reference, not the value** —
  `WORK_COLUMNS.filter is not a function` on every operation page. **tsc cannot catch it**;
  only a render does. A server importer must take ids/presets from `channelColumnPresets.ts`
  (as `ChannelWorkTable.tsx:13-15` does). Why ids and not column objects:
  `channelColumns.tsx:30-39` — a function cannot cross the server/client boundary as a prop;
  what a server caller puts in a cell travels as data or a rendered element in `rowExtras`.
- **`ChannelsRack` vs `ChannelsTable`.** `ChannelsRack.tsx` (250 lines, header `:23-28`) is
  the /channels chrome: focus line, volume bar, instrument bar (grouping, band legend), the
  one scroll region and its `--thead-h` measurement (`:132-138`), selection state and the
  free-up selection, and the `ChannelSelectionDeck` **outside** the overflow box (`:229`). It
  draws `ChannelsTable` with `RACK_COLUMNS`, `sticky` and `theadRef` (`:210-226`).
  `ChannelsTable.tsx` (`:183`) is rows, cells, sort, group-header rows and selection
  checkboxes for all three callers: the rack, `DashboardCockpit.tsx:134-142`
  (`DASHBOARD_COLUMNS`, no sort, no selection) and `ChannelWorkTable.tsx:106-118`
  (`WORK_COLUMNS`, `extra` dropped when a section has none, `:85-87`). Group-header
  `colSpan` is counted from the drawn columns, `pipelines` counting one per pipeline
  (`ChannelsTable.tsx:246-254`) — no literal.
- **Dimming is rack-only and per cell.** `ChannelsTable.tsx:527-530`: `opacity-60` only when
  `sticky` AND (build-excluded OR tier `paused`). The comment `:513-526` gives both rules:
  never on the `<tr>` (opacity makes a stacking context that traps the Tier cell's popover;
  that cell's registry entry is `dim: false`), and never outside the rack (a build-excluded
  channel in an "undownloaded" work list is not out of any pipeline).
- **`ChannelWorkTable` is a server shell.** `ChannelWorkTable.tsx:18-23`: `SectionConfig`'s
  `primaryAction` is a function, so the section, heading and empty paragraph stay on the
  server and each row's count / extra / actions cross as `rowExtras` (`:70-84`). Its rows are
  `buildChannelRowView` with neutral inputs (`workRowOf`, `:128-139`). The aria contract the
  four specs locate by is in the header (`:25-33`); never `role="status"` in it (`:35-37`).
- **Group sections reach the client as slugs only.** `ChannelGroupSectionView`
  (`common/views/channelGroupSections.ts:66-72`) is a section with `channels: {slug}[]`;
  `/channels` projects to it before render (`editor/app/channels/page.tsx:314-325`), so no
  `ChannelConfig` rides along with a section. `ChannelsRack`, `ChannelsTable`,
  `ChannelGroupLine` and `ChannelGroupHeaderRow` all take the view type.
- **`PrioritizeButton`** is `editor/app/components/actions/PrioritizeButton.tsx`, used by
  `DashboardCockpit.tsx:19,120` (it was a private function in the deleted dashboard table).
  The dashboard's Sync is `ChannelSyncButton` (same `sync <slug>` name).
- `MediaBadgeInput` survives as an alias, `= ChannelRowMedia`
  (`editor/app/components/MediaLocationBadge.tsx:35`); its old `Pick<…>` is gone.

**The job in flight**

- **One row, three variants.** `editor/app/jobs/components/JobRow.tsx`: `JobRow` `:308`,
  `variant: "table" | "card" | "compact"` (`:44`); `show?: Partial<JobRowShow>` merges over
  per-variant `DEFAULTS` (`:46-80`, merge at `:329`). `JobRowShow` (`:32-42`): `tasks`,
  `jobBar`, `headingProgress`, `eta`, `actions`, `links`, `log`, `elapsed`, **`statusPill`**
  (off where every row is running by construction). The `table` variant ignores `show`
  (`:330`). `JobRowHeading` (`:194`) is private.
- **One action rule.** `JobRowActions` `:143-176`: Retry a failed replayable job, Reorder a
  queued one, Drain a drainable running one, Cancel running/queued, Force-release running OR
  stuck — `forceRelease="stuck"` (`:145-150`) narrows it to stuck only.
- **Who draws it.** `JobsTable.tsx:336-340` (`table`); `RunningJobsList.tsx:27-34` (`card`,
  `show={{ log: true }}`); the widget's `ActiveJobsStrip`
  (`widget/components/MonitorWidget.tsx:985`, row at `:1014-1025`, `compact`,
  `actions: false`, `links: false`); `operations/components/InFlightList.tsx:70-84`
  (`compact`, `links`, `elapsed`, `statusPill: false`, `tasks: false`). **`LaneStrip` is not
  a `JobRow`** (`LaneStrip.tsx:17-20`): it keeps its lane line (section, `<h2>`, dot, word,
  note) and uses only `JobRowActions` with `forceRelease="stuck"` (`:84`).
- **The bars** are `JobProgressBars.tsx` alone: `TASK_KIND_VERB` `:23`, `TASK_KIND_GLYPH`
  `:40`, `METRIC_PREFIX` `:164`, `compactProgressText` `:182`. Compact keeps the widget's
  glyphs ("↓ 5/10"), full keeps the suite's names ("Transcribing id") — header `:17-20`.
- **`fromInFlight`** (`common/views/jobRows.ts:349-365`, comment `:337-348`) maps an
  `AutoRunnerInFlight` unit to a `JobRowView`. **Id rule** (`:354`): the unit's `jobId` when it
  has one, else synthetic `${runnerJobId ?? kind}:${videoId}`. **`inRegistry`** is
  `Boolean(unit.jobId)` (`:361`); `status` is always `"running"`; a unit with a `note` (the
  metadata-scan unit) drops `videoId` and says the note. `source: "runner"` (`:363`; union at
  `common/views/jobRowView.ts:96-100`): `JobRow`'s `linksToJob` (`JobRow.tsx:125-130`) links
  `Job <id>` for a runner row only when `inRegistry`. `InFlightList.tsx:15-20` maps each lane
  to its unit's JOB kind (`auto-download-unit` / `auto-transcribe` / `auto-digest` /
  `auto-backfill`), a `Record<AutoQueueKind, string>` mirroring `autoRunner.ts` because a
  client cannot import that module.
- **`inFlight.jobId` is set in exactly two places**: the two `onChildJob` callbacks in the
  runner loop, `common/controller/autoRunner.ts:1896` (metadata scan) and `:1911` (download
  `launchUnit`). Field declared `:187-189`. The private `childJobIds` map (`:1245`) stays
  private. A transcription, digest or backfill unit is a task on the runner's own job and
  never gets one.
- **`formatElapsed` lives in the editor**, `editor/app/lib/formatElapsed.ts:4` ("42s",
  "3m07s", "2h05m"), re-exported by `operations/components/dispatch.ts:188-189` so
  `LaneHeader` did not move. Not `common/lib/format.ts`: slice 4b owned `common/lib` during the
  release, and it is not `formatDuration` (a media duration that renders 0 as "").

**Tools and history**

- **The numbers tool does not cover `autoQueueStatus`.** `plans/tools/phase3-view-numbers.ts`
  dumps `widgetActionable`, `cleanable`, `widgetSync` only; slice 3a's one wire change (the
  optional per-unit `jobId` in `autoQueueStatus`) is outside its diff by construction.
- **Bisect hazard: `f63260d8` up to, not including, `c944475f`** (`f63260d8`, `0d20c42a`,
  `797078c2`, `4a784486`): every operation page throws at render
  (`WORK_COLUMNS.filter is not a function`). History is not rewritten;
  `git bisect skip f63260d8^..c944475f^`.

### The rest of the schemas — slice 4b (merged `ef88ac4d`)

Every `file:line` below was grepped at `7dfd7508`, whose code is byte-identical to
`ef88ac4d` (the merge adds only the `b3cebcf8` record lines). The record is `one-core-phase-3.md`, "Slice
4b, as shipped" (deviations 1–10, behaviour changes, review fixes `973e59ee`).

**One JSON reader, one atomic writer — `common/lib/jsonFile-server.ts`**

- `readJsonFile` `:72` / `readJsonFileSync` `:84` return `{ok:true, value}` or
  `{ok:false, reason: "absent"|"unreadable"|"unparseable"}`, and never throw. `absent` covers
  ENOENT and ENOTDIR.
- `writeJsonAtomic(file, value, {indent, newline, mkdir})` `:158`. The value is serialised at
  the call. Writes to one `path.resolve`d path are CHAINED (`:165-176`): the last write issued
  is the one that lands, and a rejected write does not block the next.
  `writeJsonAtomicSync` `:183` is for the three synchronous stores (`chartsStore`,
  `aliasesStore`, `curatedTagsStore`); it has no chain and uses the same temp name.
- `withJsonFileLock(file, fn)` `:205` serialises a whole READ-MODIFY-WRITE cycle. Only
  `patchChannelConfig` takes it.
- **Temp name:** `${file}.tmp-${pid}-${seq}-${hex8}` (`tmpPathFor` `:132-135`, 4 random
  bytes).
- **State is on `globalThis.__yttJsonFile__`** (`:112-129`: `tmpSeq`, `chains`, `locks`).
  **WHY:** Next can load the module once per bundle layer. The runners are armed from
  `instrumentation.ts` and the form saves are server actions, so two module copies would
  each start `tmpSeq` at 0 and each hold their own locks. That is the house pattern
  (`jobs/registry.ts`, `controller/autoRunner.ts`). `jsonFile-server.test.ts:67` imports a
  second module instance and checks that the two share one chain.
- **Bytes are per caller, not a house style.** `jsonText` is at `:105`, and `indent`/`newline`
  are options (header `:35-39`):
  - Attribution and diarization: compact, with a trailing newline.
  - Export pages (buildIndex, buildStats, compose-homepage): compact, no newline.
  - Chart, alias and tag stores: indented, no newline.
  - Everything else: indented, with a newline.
  The six local `function writeJsonAtomic` left in `buildIndex.ts:404`, `buildStats.ts:376`,
  `bin/compose-homepage.ts:40`, `aliasesStore.ts:23`, `chartsStore.ts:50` and
  `curatedTagsStore.ts:61` are one-line wrappers that pin those bytes over the shared writer.
  They are not copies.
- **Per process, not per machine.** A CLI such as `migrate-channel-priority.ts` running beside
  the live editor is not covered (header `:26-29`). The rename is still atomic, so there is
  never a torn file, but the last rename wins.

**Sidecars — `common/lib/sidecar-server.ts`**

- `sidecar(filename, schema, {indent, newline})` `:67` returns
  `{filename, path, load, write, remove}`.
  - `load` never throws. Absent, unparseable, a coercion that rejects and a coercion that
    throws all read as null (`:85-96`).
  - `write` goes through `writeJsonAtomic` and `remove` is `rm -f`.
  - `sidecarField(coerce)` `:47` is `z.unknown().transform(coerce)`, which is 4a's
    `settingsField` without the `.catch`.
  - A sidecar load does NOT strip unknown keys (`sidecar-server.test.ts:156`).
- **The naming guard runs at declaration** (`:72-76`): a filename that `SUB_FILE_RE` matches
  throws at module load, so a misnamed sidecar fails boot and every test that imports it.
  `SUB_FILE_RE` is exported from `common/lib/videoStatus.ts:88` for this purpose.
  `SIDECAR_FILENAMES` `:65` is enumerated by `sidecar-server.test.ts:43` (nine names, with all
  eight modules imported).
- **No mtime freshness** (header `:26-27`), because no reader consumes it.
- **The eight declarations.** Each shape check is an exported `coerceX` in the same file, and
  the old `loadX`/`writeX`/`xPath` names are kept by destructuring the declaration:

  | File | Declaration | Coercion |
  |---|---|---|
  | `attribution-server.ts` | `:27` | `:9` |
  | `availability-server.ts` | `:26` | `:14` |
  | `diarization-server.ts` | `:20` | `:7` |
  | `digest-server.ts` | `:95` (machine), `:96` (overrides) | `:40`, `:69` |
  | `doNotClean-server.ts` | `:16` | `:10` |
  | `downloadOutcome-server.ts` | `:27` | `:9` |
  | `excludeTruncatedCheck-server.ts` | `:18` | `:8` |
  | `transcribeOutcome-server.ts` | `:20` | `:7` |

  The two markers (doNotClean, excludeTruncatedCheck) read ANY parseable JSON, including
  `null` and `3`, as present (`{setAt:""}`; deviation 8). `availability-server` reads the
  outcome side through `loadDownloadOutcome`.
- **Out of `sidecar()` by name:** `savedVideo-`, `clipWindow-`, `posts-`, `transcripts-` and
  `digestContext-server`. Only the JSON write halves of the first three moved to
  `writeJsonAtomic`.

**`site.json` — `common/lib/siteSchema.ts` + `site.ts`**

- **The schema:**
  - `siteFieldsSchema` `:216` has one `settingsField` per key over the existing parsers.
  - `siteSchema` `:253-273` adds ONE object step: it resolves `defaultGroupId`, drops a
    membership `groupId` that names no group, and **re-emits every key in `SITE_KEYS` order**
    (`:270`). **WHY:** zod 4 omits an input-absent key whose transform returns `undefined`,
    and `parseSite` has always emitted every key, present and `undefined` (comment
    `:247-252`).
  - `SITE_KEYS` `:276` is taken from `SITE_FIELD_DOCS` `:92`.
- **`parseSite(siteId, raw)`** `:280-285` never throws. A non-object or an array reads as `{}`.
  The `z.object` is built once at load, and `parseSite` sets `siteId` after the parse.
- **`siteToDisk`** `:290-326` is pure. It ALWAYS writes `siteId`, the three titles,
  `homeTagline`, `groups`, `defaultGroupId` and `channels`; everything else is written only
  when it is not the default.
- **What moved in from `site.ts`:** the `Site` types, `SITE_ID_RE` `:128`, `isValidSiteId`
  `:130`, `parseSiteChannels` `:137`, `parseSiteUrl` `:162` and `parseRelatedSites` `:173`,
  plus the docs records `SITE_CHANNEL_MEMBERSHIP_FIELD_DOCS` `:50` and
  `RELATED_SITE_GROUP_FIELD_DOCS` `:63`. `CHANNEL_GROUP_FIELD_DOCS` is
  `channelGroups.ts:22`.
- **`site.ts` is I/O plus resolvers.** It does `export * from "./siteSchema"` (`:33`), so no
  importer moved.
  - `getSite` `:174` throws only on a malformed id (`:175-176`) and reads through
    `readJsonFileSync` (`:180-181`).
  - `writeSite` `:214`: the throwing validations, then `writeJsonAtomic(…, siteToDisk(…),
    {mkdir:true})` (`:244-248`).
  - `siteChannelIndex` `:118`.

**Channel `config.json` — `channelConfig.ts` (pure) + `channelConfigSchema.ts` (zod)**

- **One coercion set, zod-free.** `CHANNEL_CONFIG_COERCIONS` is at `channelConfig.ts:350-396`
  (`-?` mapped type, so every key must have an entry).
  - `parseChannelConfig` `:406-414` composes it without zod.
  - `channelConfigSchema.ts:45-75` wraps the same functions as `settingsField(coerce)`, and
    `channelConfigSchema` `:84-89` is the transform the server uses.
  - **WHY two compositions:** six `"use client"` modules value-import `channelConfig.ts`, so a
    zod import there would ship zod to the browser (deviation 2).
  - `channelConfigSchema.test.ts:137` pins that the two agree, key order included, over
    generated inputs. `:38` pins docs = coercions = schema keys, with the sync-state keys
    inside.
- **The OMIT rule.** An invalid OPTIONAL key is omitted, never defaulted, so `"k" in config`
  means the file set it. zod emits a key whose transform returned `undefined` when that key
  was present in the input, so `stripUndefined` (`channelConfigSchema.ts:78-82`) runs after
  the object parse. The strip is one level deep: `coerceAudioCheck` (`:313`) and
  `coerceDownloadFilter` (`:288`) build objects with no undefined members.
- **Key records.** `CHANNEL_CONFIG_FIELD_DOCS` `:147` (the type's comments moved in),
  `AUDIO_CHECK_FIELD_DOCS` `:57`, `DOWNLOAD_FILTER_FIELD_DOCS` `:81`, and
  `CHANNEL_CONFIG_KEYS` `:200` (the emission order and the unknown-key oracle).
  `CHANNEL_SYNC_STATE_KEYS` `:208-212` holds `lastSyncedAt`, `lastFullDownloadAt` and
  `lastFullSweepAt`: stamped by sync, sweep and download, never by the form.
  `isChannelShape` `:268` is the "is it a channel at all" gate.
- **`*_FIELD_DOCS` count:** 31 records, up from 4a's 24. The seven new ones are three in
  `siteSchema.ts`, three in `channelConfig.ts` and one in `channelGroups.ts`. The four
  channel/group records ship to the browser because their modules are client-imported. That
  is a few KB and no zod, and review accepted it.

**The reader, the strict writer, the patcher — `common/controller/channels.ts`**

- **`readChannelConfigFile(file)`** `:165-170`. It never throws, and answers null for absent,
  unreadable, not JSON, or not a channel. `readChannelConfig(paths, slug)` `:172` wraps it,
  and `buildIndex.ts:296` and `buildStats.ts:285` call it directly. The header `:152-157` names
  the raw readers that bypass it: `channelMedia.ts:179` (the `dataDir` guard) and the legacy
  migrations (`migrateToSites.ts:101` for `group`, `bin/migrate-channel-priority.ts` for
  `excludeFromSync`, which also WRITES raw at `:206`).
- **`writeChannelConfig` is STRICT** (`:474-488`). It parses on the way out, which drops
  unknown and invalid keys, THROWS on a value with no valid `handling`, and returns what it
  wrote. **Rule: callers pass a parsed config.** The non-test callers are `createChannel`
  `:528`, the patcher `:516`, and the two whole-config fallbacks,
  `relocateChannelMedia.ts:774` and `renameChannel.ts:175`. **The e2e fixtures seed raw on
  purpose:** `editor/e2e/helpers.ts:429` has its own `writeChannelConfig(slug, raw)`, and
  `scheduler.spec.ts:15-16` writes its configs directly. Neither goes through this function.
- **`patchChannelConfig(paths, slug, patch, {unset})`** (`:503-518`) is the only way to change
  some keys. Under `withJsonFileLock` it re-reads the file NOW, deletes `unset`, assigns
  `patch` and writes strictly. On a null re-read it writes nothing and returns null.
  - **Callers:**
    - `runYtdlp.ts:1814,1820,1828` (the three stamps)
    - `fetchPosts.ts:190` (`lastSyncedAt` only)
    - `relocateChannelMedia.ts:771,990`
    - `storageLocations.ts:635,732`
    - `renameChannel.ts:169`
    - `socialActions.ts:59`
    - the form save `editor/app/channels/actions.ts:317-319` (`unset: CHANNEL_FORM_FIELDS`,
      `parseChannelForm.ts:37`)
    - the two exclude toggles `:469-470,486-487`
    - the scheduler's bulk cadence save `editor/app/scheduler/actions.ts:95`
  - **What a null patch does:** `storageLocations.ts:732-737` THROWS on it so the ledger rolls
    the link back. `relocateChannelMedia.ts:764-775` writes the job's own copy instead
    (deviation 10: the swap has already happened and there is no ledger to roll back).
  - `updateConfigField` is deleted.

**Generated docs**

- `common/bin/file-schemas-docs.ts` writes root `SITE.md` (198 lines) and `CHANNEL.md` (64)
  from `renderSiteMarkdown` / `renderChannelMarkdown` (`common/lib/fileSchemaDocs.ts:55,139`).
  `--check` writes nothing and exits 1 on drift, and `fileSchemaDocs.test.ts:20` makes the
  same claim.
- Regenerate with `pnpm --filter yt-dlp-transcript-common exec tsx bin/file-schemas-docs.ts`.
  **Never hand-edit either file.** `SITE.md:3` and `CHANNEL.md:3` say so.
- `SETUP.md:259-260,270` and `AGENTS.md:196-197,225-226` link to them.

**Rules**

- **zod only in `*Schema(s).ts` and `*-server.ts`.** The complete list of zod importers is
  `settingsFieldSchemas.ts`, `settingsSchema.ts`, `siteSchema.ts`, `channelConfigSchema.ts`
  and `sidecar-server.ts`, plus their tests. Nothing under `editor/app`, `export/app` or
  `common/components` imports the new server modules. `grep -rl 'ZodError\|_zod'` over both
  `.next/static` prints nothing.
- **Config writes come out in SCHEMA key order.** Before, a form save or toggle wrote the
  caller's spread order. Nothing changes semantically, but `transcripts/` is its own git repo,
  so the **first form save or toggle per channel may show a one-time key-reorder diff**
  there. That is expected, not corruption.
- **`build:index` is NOT read-only.** `pnpm --filter export build:index` writes its LMDB to
  `paths.lmdbPath = $TRANSCRIPTS_DIR/index.mdb` (14 GB live), and that path cannot be
  overridden by env. **Never point it at the primary's `transcripts/` while the editor runs.**
  To time it, use a scratch corpus of SYMLINKS to the live `channels/`, `sites/`,
  `saved-videos/` and the corpus-wide JSON, with no `index.mdb` and `EXPORT_PUBLIC_DIR` in
  scratch. Every read is then real, every write is scratch, and every run is a cold full
  build. The harness was `$CLAUDE_JOB_DIR/tmp/s4b-buildindex.sh`. The branch measured +0.5 %
  against a quiet `main` run (1699.98 s vs 1691.98 s, 77,624 transcripts).

**Owed: JSON writers still on the per-pid temp name `${file}.tmp-${process.pid}`**

Verified at `ef88ac4d` with `git grep 'tmp-${process.pid}' -- common`. The slice record calls
these "14"; the list is **16 write sites in 13 files**:

- `controller/failedTranscriptions.ts:33,54`
- `controller/maybeMissingStore.ts:54`
- `controller/rosterStore.ts:235`
- `controller/duplicateShorts.ts:640,734`
- `controller/scanCorruptMedia.ts:393,454`
- `controller/shard.ts:56`
- `controller/backupSavedVideos.ts:118`
- `controller/relocateDir.ts:139`
- `jobs/syncSchedulerState.ts:122`
- `jobs/workerDefaults.ts:61`
- `lib/widgetPresets.ts:83`
- `lib/homepage.ts:129`
- `bin/migrate-channel-priority.ts:206`

**`maybeMissingStore` and `rosterStore` are per-channel files written from several lanes**,
which is the same race class 4b fixed for `config.json`.

Not in the 14:

- The export build's streamed page writers `buildIndex.ts:971` and `buildStats.ts:358`. These
  are JSON writers still on the per-pid name, not in the list above only because there is one
  writer per build. They are owed with the rest (16 + 2).
- `metadataScanStore.ts:188-206` and `autoQueueState.ts:141-156`. They carry a module-level
  `writeSeq` (`${file}.tmp-${pid}-${seq}`), which is unique per module copy, not per process —
  the hazard review finding 1 fixed in `jsonFile-server` by pinning its counter on
  `globalThis`. Owed: the same fix, or `writeJsonAtomic`. **Done by slice W (`9bfd15cd`,
  merged `ddad13f4`):** both counters deleted, both writers on `writeJsonAtomic`
  (`metadataScanStore.ts:200`, `autoQueueState.ts:155`); see the release-4 section below.
- The non-JSON writers.

**The numbers tool** is `plans/tools/phase3-files-numbers.ts` (317 lines). It is one process,
never writes the corpus, and uses only names present on both sides.

- **Freezing:** `FREEZE_TO=/abs/dir` copies exactly what a run reads into a scratch tree, and
  both runs then take `LIVE_TRANSCRIPTS_DIR=` that tree.
- **Output:**
  - each site parse, plus the file `writeSite(getSite())` writes
  - each config parse, plus the md5 of `writeChannelConfig(readChannelConfig())`
  - per sidecar, the md5 of the canonical load and of `write(load())` (load only for the two
    markers)
  - an unknown-key report
- **Result:** at 4b, `main` vs the branch is an empty diff over 3,832 lines (6 sites, 71
  configs, 1,763 sidecar files).
- **Not covered:**
  - the key-order change, because parse → write never reorders
  - the patch paths
  - the `savedVideo`/`posts`/`clipWindow` writes
  - the 14 writers above

### Anchors above this section that are now stale (not rewritten in place)

Line numbers are `plans/FACTS.md` lines as of `ef88ac4d`. As in the 2026-09-23 list, the
historical entries keep their text; use the subsections above.

Slice 3a (merged `3241fed2`) deleted or moved:

- `:56` — `MonitorWidget.tsx:628`'s `METRIC_PREFIX` → `editor/app/jobs/components/JobProgressBars.tsx:164`;
  the widget has no bars or glyph tables of its own.
- `:2763` — `dashboard/ChannelsTable.tsx:69`, `dashboard/types.ts:21`: both files deleted; the
  dashboard's channel cells are `channelColumns.tsx`'s `videos` / `digestReachable` entries
  over `ChannelRowView.work` (`common/views/channelRow.ts:92-97`).
- `:2539` — "dashboard / `NeedsWorkPanel` / `ChannelsTable`" reading `actionableNoDigestCount`:
  the dashboard table reads `digestReachableCountOf` (`common/views/actionableCounts.ts:89`)
  through the builder.
- `:2791-2792` — `reportStateOf(brief)` is in `common/views/channelRow.ts:139`, not
  `loadActionable.ts`; `isStaleOrMissing(row)` is deleted (with `ChannelWorkTable`'s `Row`).
- `:3046-3047` — `MonitorWidget.tsx:1047-1086,1121,1139,1176` (the widget's private `JobRow`,
  `JobProgressBar`, `TaskBar`, `jobProgressText`) are deleted; the widget draws `JobRow`
  `compact` from `ActiveJobsStrip` (`MonitorWidget.tsx:985`).
- `:3104-3105` — "`components/LaneStrip.tsx` … byte-identical extraction": `LaneStrip`'s
  runner buttons are `JobRowActions` now (`LaneStrip.tsx:84`).
- `:4356-4357` — "`InFlightList` renders the note (and links the CHANNEL)": it still does, but
  through `fromInFlight` + `JobRow compact` (`InFlightList.tsx:63-84`), not its own markup.
- `:3888`, `:3903` — "`ChannelsTable` ends in TWO sibling bulk bars" and "`colSpan` is
  `10 + columns.length`": the bars became `ChannelSelectionDeck` (in `ChannelsRack.tsx`,
  outside the scroll box), and `colSpan` is counted from the drawn columns
  (`ChannelsTable.tsx:246-254`). The merge-conflict lesson stands; the shape does not.
- `:5422` (slice 2, above) — `widgetActionableRows` is `loadActionable.ts:80`, not `:162` (the
  count helpers above it became one-line wrappers). **Corrected in place.**

Slice 4b (merged `ef88ac4d`) deleted or moved:

- **Named things.** FACTS names none of `updateConfigField`, the private `writeJsonAtomic`
  copies or `MediaBadgeInput` (which slice 3a kept as an alias, so it is not deleted anyway).
  The `SUB_FILE_RE` entry (`:134-140`) was already corrected by 4b and is right:
  `videoStatus.ts:88`, exported.
- `:166` — the "Reusable helpers" row "tmp+rename write idiom | `normalizeTranscript.ts:139-141`
  | `${path}.tmp-${process.pid}`" now points readers at the per-pid name 4b retired for JSON.
  For JSON, the idiom is `writeJsonAtomic` (`common/lib/jsonFile-server.ts:158`), or
  `sidecar()` (`common/lib/sidecar-server.ts:67`) for a per-video sidecar. The
  normalizeTranscript line is a non-JSON cue writer that is still per-pid.
- `:3182` — "`SITE_ID_RE` **re-spelled**, because `common/lib/site.ts` imports `node:fs`":
  `SITE_ID_RE` is in `common/lib/siteSchema.ts:128`, which imports zod. It is still
  server-only, so the re-spelling in `activeSite.ts` still stands, now for that reason.
- `:3211` — `getSite` "(`common/lib/site.ts:356`, sync)" → `site.ts:174`, throw at `:175-176`.
- `:3804` — `siteChannelIndex` "(`lib/site.ts:324`)" → `site.ts:118`.
- `:2884-2887` — `digest-server.ts:91-98` (the `version` fallback in `loadDigestOverrides`) is
  now inside `coerceDigestOverrides` (`digest-server.ts:69`), and the loader is the
  declaration at `:96-107`. `attribution-server.ts:36-38` (the `hasAttribution` note) does not
  apply: the file is `coerceAttribution` `:9` plus the declaration `:27-37`, and it has no
  `hasAttribution`.
- `:4378` — "the sanitizer stores it only alongside a real filter": the sanitizer is
  `coerceDownloadFilter` (`common/lib/channelConfig.ts:288`).
- `:5449-5455` (slice 4a's own entry) — `settings.ts` is **245** lines, not 250. Every anchor
  moved up by 3:
  - `getSettings` `:121-123`
  - `premigrateRaw` `:87`
  - `finishRawMigrations` `:104`
  - `deriveWorkerShadow` `:184`
  - `writeSettings` `:232`, with the parse at `:239-242`

  The writer ends in `writeJsonAtomic(file, merged)` (`:244`), not an inline tmp + rename, and
  `getSettings` reads through `readJsonFileSync`.
- `:5236` — `settings.ts:242` → `:239`.
- `:5506` — "`common/lib/settings.ts:235-250`" → `:232-245`.
- **Line shifts only (text still true).** These moved because 4b edited the files:
  - `buildIndex.ts`
    - `:233` → `:234`
    - `:165` → `:166`
    - `:146-154` → `:147-155`
    - `:694` → `:680`
    - `:830-832` → `:816-818`
    - `:636-679` → `:622-665`
    - `:1088-1118` → `:1074-1104`
    - `:1065-1240` → `:1051-1226`
    - `:1765` → `:1751`
    - `:309-315` → `:303-309` (FACTS `:4182,4299,4396,4431,4453`)
  - `channelSnapshot.ts`
    - `:57-143` → `:58-144`
    - `:607-619` → `:608-620`
    - `:997` → `:998`
    - `:1167-1174` → `:1168-1175`
    - `:1378-1383` → `:1379-1384`
  - `curatedTagsStore.ts`
    - `:94-113` → `:92-111`
    - `applyTagAssignments` is at `:208` (FACTS `:178` says `:198`; it was already off before
      4b)
  - `aliasesStore.ts:68-73` → `:66-71`
  - `videoStatus.ts:143-158` → `:145-160`
  - `relocateChannelMedia.ts`: `relocationRootProblem` → `:169` (FACTS `:3752`; the line now
    lands on the function, where before 4b it was off by 4)
  - `editor/app/channels/actions.ts`
    - `:761` → `:754` (FACTS `:3808`; `saveChannelPriorityAction`)
    - `:609` → `:602`
    - `:618-621` → `:611-614`
    - `:571` → `:564`

## One-core Phase 3 release 4 — slices P, W, 3b (verified 2026-09-24, `main` @ `e172749b`)

Records: `one-core-phase-3.md`, "Release 2026-09-24 (evening)", and the three "as shipped"
sections above it (P, W, 3b). Every `file:line` below was grepped at `e172749b`. Phase 3 is
complete with this release.

### The /channels rack's layer ladder — slice P (merged `77a32de2`)

- **One ladder, one module.** `editor/app/channels/components/rackLayout.ts` is plain data,
  deliberately not `"use client"`. It holds:
  - `RACK_LAYERS` `:37-43`: `popover` z-40 > `thead` z-30 > `groupHeader` `md:z-20` >
    `identity` z-10. `deck` z-20 sits beside the ladder, not in its order.
  - `RACK_IDENTITY` `:53-56`: `checkboxWidth` `w-9`, `slugLeft` `left-8`.
  - `RACK_BRIDGE` `:59`.

  The header comment `:9-35` explains why the checkbox and Slug cells share **one** z. Two
  sibling cells at one z-index paint in DOM order. The Slug cell comes later, so it covers
  the 4 px the two cells overlap, and that overlap closes the seam `20ee34db` found. That
  commit had closed the seam by lifting Slug to z-20, which TIED it with the group header:
  scrolled down and right, every later row's slug band painted over the group header and
  took its clicks.
- **The width invariant** is `slugLeft` (32 px) < `checkboxWidth` (36 px), stated at `:45-52`.
  Equal values reopen the sub-pixel seam. `rackLayout.test.ts:13` parses both numbers. `:19`
  checks that the ladder's order is strict.
- **Class sites read the tokens.** Every entry is a complete literal, because Tailwind v4
  scans source for them, so never build one as `z-${n}`. The readers:
  - `ChannelsTable.tsx:277,389,553`;
  - `channelColumns.tsx:123,127`;
  - `ChannelGroupHeaderRow.tsx:53`;
  - `ChannelTierSelect.tsx:232`, with `max-md:scroll-mb-48` so the panel stops above the deck;
  - `ChannelSelectionDeck.tsx:130`.

  `grep -rn 'z-[0-9]' editor/app/channels/components --include='*.tsx'` is empty.
- **The region is `isolate`** (`ChannelsRack.tsx:221`, comment `:212-217`), so the ladder is
  ordered inside the region and not against the page. It carries
  `data-testid="channels-rack"`. `ChannelSelectionDeck` stays **outside** it (`:245`).
- A group header's name and stations pin left: `ChannelGroupHeaderRow.tsx:63`,
  `sticky left-2 max-w-[calc(var(--rack-w,100%)-1rem)]`. The section rule is the th's inset
  shadow (`:52`), not the `<tr>`'s border, because a collapsed border stays in the grid when
  the th pins.

### The transcribe station counts both buckets and queues by id — slice P

- **The one fold** is `transcribeStationIds(snapshot)` (`common/views/channelGroupSections.ts:114-123`).
  It returns `{missing, autoSubs}`:
  - `missing` is `downloadedNoTranscript` minus `excludedDownloadIdSet`;
  - `autoSubs` is `downloadedAutoSubsOnly` minus the same set.

  The two lists are disjoint. `stationWorkFor`'s transcribe branch (`:187-199`) returns
  `missing.length + autoSubs.length` and never consults `handling`. `"social account"`
  (`:172-174`) is now the only ineligible case.
- **The group action queues exactly those ids.** `transcribeChannel` is at
  `editor/app/channels/groupActions.ts:93-127`:
  - With a snapshot it runs `transcribeBucketAction(slug, ids.missing, …,
    "downloadedNoTranscript")` (kind `whisper-bucket-downloaded-no-transcript`) and
    `transcribeAutoSubsBucketAction(slug, ids.autoSubs)` (kind `whisper-bucket-auto-subs`).
  - The scan, `transcribeMissingAction` (a `whisper-all` with no ids), runs **only** when there
    is no snapshot (`:97`).
  - Why by id: `downloadedNoTranscript` does not filter excluded ids, so a scan would also
    transcribe a video downloaded before it went private.
  - `jobIds` carries the first ok half's id (`:116`), and the other ok stream is cancelled.
    A refused half is `console.warn`ed (`:122`), because `StreamActionResult`'s ok arm has no
    message field.
- **The dedupe spans all three kinds.** `KIND_FOR.transcribe` (`groupActions.ts:61-65`) is
  `whisper-all`, `whisper-bucket-downloaded-no-transcript` and `whisper-bucket-auto-subs`.
  `activeSlugsForKinds(KIND_FOR[station])` is at `:209`. All three run on
  `TRANSCRIPTION_QUEUE`.
- **The band/station divergence is on purpose.** The rack's transcription band counts
  `downloadedNoTranscript` **alone**: `common/views/pipeline/buildBands.ts:168-172`
  (`transcription.reachable += downloadedNoTranscript`, rule stated at `:104`). The stage
  title lists auto-captions as informational only (`common/views/pipeline/stageStatus.ts:342-352`).
  On a YouTube channel with many auto-caption-only videos, the station's figure is higher than
  the band's. The station counts what its button queues; the band counts the default lane's
  reachable work. `channelSnapshot.ts:581-587` warns that the two must not be merged; its last
  line names the retired path `editor/app/components/pipelines/buildBands.ts`.

### One write idiom — slice W (merged `ddad13f4`)

`common/lib/jsonFile-server.ts` (268 lines):

- The header `:1-5` says what is left on its own temp name: see
  `one-core-phase-3.md`, "Slice W, as shipped".
- Header `:33-35`: **the chain serialises WRITES, not read-modify-write cycles.** A
  read-modify-write takes `withJsonFileLock` (`:251`), and only `patchChannelConfig` does.
- `tmpPathFor` `:134-137` builds `${file}.tmp-${pid}-${seq}-${hex8}`. The state is on
  `globalThis.__yttJsonFile__` (`:114-131`).
- `chained(key, op)` `:152-163` is the one per-absolute-path chain. `replaceNow` `:166-180` is
  mkdir?, temp, fill, `rename`. On any failure it runs `rm(tmp, {force: true})` and rethrows
  the original error.
- **`writeFileAtomic(file, data: string | Buffer, {mkdir, mode})` `:186-198`.** `mode` goes to
  `writeFile(tmp, data, {mode})`, so the bytes are never more widely readable, even before
  the rename (options doc `:139-147`).
- **`copyFileAtomic(src, dest, {mkdir})` `:203-212`** copies into a temp beside `dest` and
  renames. It is on the same chain, keyed on `dest`.
- `writeJsonAtomic` `:217-223` is `jsonText` (`:107`) → `writeFileAtomic`.
  `writeJsonAtomicSync` is at `:229`.
- **Tests**, in `jsonFile-server.test.ts`:
  - `:72` two module copies share one chain;
  - `:132` exact string and Buffer bytes;
  - `:147` mode 0o600 on the file and on the temp. It intercepts `rename` via `node:fs/promises`
    + `syncBuiltinESMExports`; `:169` asserts that exactly one temp was seen;
  - `:173` `writeFileAtomic` and `writeJsonAtomic` share one chain on one path;
  - `:190` copy;
  - `:202` the remark literal.

  Also `controller/compactJsonWriters.test.ts` (the four compact writers' bytes) and
  `jobs/autoQueueState.test.ts` (12 overlapping writes, the last one issued lands, no temp
  left).
- **Call sites** (a sample):
  - `rosterStore.ts:236` (mkdir);
  - `metadataScanStore.ts:200`;
  - `autoQueueState.ts:155` (mkdir; the old counter's comment is replaced at `:139`);
  - `xSessionBroker.ts:218` (0o600);
  - `savedVideo-server.ts:78` (`copyFileAtomic`);
  - `normalizeTranscript.ts:141` (`{indent: 0, newline: false}`);
  - `videos/[id]/videoActions.ts:499` (VTT promote) and `:609` (the remark,
    `{transcription: []}` at `{indent: 0}`).
- **The two write counters are deleted.** `git grep -n 'writeSeq\|nextWriteSeq' -- common
  editor` is empty.
- **What `git grep -n 'tmp-${process.pid}' -- common editor` still finds:**
  - `buildIndex.ts:971` and `buildStats.ts:358`, the export page writers, out of scope;
  - `transcode.ts:31` (ffmpeg's output, renamed at `:55`);
  - `transcribeOne.ts:142` (the transcription app's `outputBase`);
  - the shared writer's own comment `:9`, code `:136`, and test `:68`.

  `transcribeOne.ts:173` (`if (bytes) await writeFile(transcriptPath, bytes)`) has no temp
  at all, so this grep cannot see it.
- **Temp-name readers** match either shape: `videos/[id]/page.tsx:63` and `videos/page.tsx:50`
  use `includes(".tmp-")`, and `cards/videoFiles.ts:43` uses `startsWith("audio.tmp-")`.

### The video page's chore cards — slice 3b (merged `e172749b`)

- **`editor/app/channels/[slug]/videos/[id]/components/cards/`** holds 17 files: the 15 card
  modules, `Heading.tsx` (shared by the two per-file rows) and `videoFiles.ts` (`VideoFile`,
  `WHISPER_FILENAME`, `CANONICAL_VTT`, the extension predicates, `mediaUrl`).
  - Children stay with their only caller: `PersistedSourceVideo` is in
    `SourceVideoSection.tsx:96` and `DeleteFileButton` in `FilesList.tsx:67`.
  - `VideoNavStrip.tsx` (60 lines) and `PipelineStatusStrip.tsx` (51) sit beside `VideoPanel`,
    not in `cards/`.
- **`VideoPanel.tsx` is the assembly**: 455 lines (1,839 at `4130aca1`). `VideoPanel()` starts
  at `:96`. `:49` re-exports `FetchedWindow` and `VideoFile`, so
  `videos/[id]/page.tsx:33` and `channels/[slug]/videos/page.tsx:26` did not change.
  `hasTranscript` is derived at `:122`.
- **`lib/videoChoreCards.ts`** (149 lines) holds `VideoChoreCard` `:46` and
  `VIDEO_CHORE_CARDS` `:58`: fifteen rows `{id, component, shown, why}` in render order.
  Nothing imports it at runtime. `videoChoreCards.test.ts` (`:23`, `:28`, `:36`) reads
  `VideoPanel.tsx` as text and pins three things: fifteen distinct components, the rendered
  order equal to the list, and the `./cards/` imports equal to the list. The registry
  operations (digest, diarization, attribution) still render through `videoOperationPanels.ts`
  + `OperationPanel`, after `<VideoPanel>` in `videos/[id]/page.tsx`.
- **The stage half needed no change.** `computeStageStatuses`
  (`common/views/pipeline/stageStatus.ts:192`) and `computeChannelFlow` (`channelFlow.ts:220`)
  are each called once, at `channels/[slug]/page.tsx:256` and `:308`. `stageOrder` is at
  `:278-286`, around `GROUP_STAGES` (`stageStatus.ts:95`).
- **The ranHere banners, now one file each.** This is the shape the 2026-09-08 entry above
  describes:
  - `SourceVideoSection.tsx:38,64`;
  - `IncompleteTranscriptBanner.tsx:38-39`;
  - `ShortAudioBanner.tsx:40-41`;
  - `PerFileTranscribeRow.tsx:39,62`.

  `PerFileTranscodeRow.tsx:39` is the static `return null`, which is not an instance.

### Anchors this release made stale

Line numbers are `plans/FACTS.md` lines at `e172749b`, before this record's in-place edits.

**Corrected in place** (the grep the release-4 docs brief named:
`VideoPanel.tsx:`, `groupActions.ts:`, `channelGroupSections.ts:`, `metadataScanStore.ts:`,
`autoQueueState.ts:`):
- `:2442`: `channels/groupActions.ts:108`. This is historical: slice 3 fixed the copy. The
  skip reason now reads "the lane is switched off on its operation page", at `:186`. A
  pointer was added.
- `:3346`: `jobs/autoQueueState.ts:23-25`. **Holds**; W's edits are below it.
- `:3675`, `:3683`: the `VideoPanel.tsx` anchors "at `12d1778`". Historical. Their current
  homes (the ranHere list above) were added in place.
- `:5573`: `channelGroupSections.ts:66-72` (`ChannelGroupSectionView`). **Holds**. P's edits
  are below it, and the type is still at `:70`.
- `:5858`: "`metadataScanStore.ts:188-206` and `autoQueueState.ts:141-156` … Owed". Both
  counters were deleted by W (`9bfd15cd`), and the entry now says so.

**Moved by P** (the 3a entry's text still holds; only the numbers changed):
- `ChannelsRack.tsx` is 263 lines, not 250. The header `:23-28` holds. `--thead-h` is
  `:136-142`, not `:132-138`. The deck is `:245`, not `:229`. `ChannelsTable` is drawn at
  `:223-239`, not `:210-226`.
- `ChannelsTable.tsx`:
  - the function is `:184`, not `:183`;
  - the `colSpan` count is `:247-255`, not `:246-254`;
  - the dim is `:533-536`, not `:527-530`, with its comment at `:519-532`, not `:513-526`.
- `channelColumns.tsx`:
  - `CHANNEL_COLUMNS` is `:115`, not `:114`;
  - the re-exports are `:20-29`, not `:19-28`;
  - the registry-by-id comment is `:31-40`, not `:30-39`.

**Moved by W** (the 4b entry for `jsonFile-server.ts`; the text holds unless noted):
- `readJsonFile` is `:74`, not `:72`. `readJsonFileSync` is `:86`, not `:84`.
- `writeJsonAtomic` is `:217`, not `:158`. The chain is `chained` `:152-163`, not `:165-176`.
- `writeJsonAtomicSync` is `:229`, not `:183`. `withJsonFileLock` is `:251`, not `:205`.
- `tmpPathFor` is `:134-137`, not `:132-135`. The state is `:114-131`, not `:112-129`.
- `jsonText` is `:107`, not `:105`. The bytes header is `:37-41`, not `:35-39`. The
  per-process header is `:28-31`, not `:26-29`.
- The second-module-copy test is `jsonFile-server.test.ts:72`, not `:67`.
- The 4b entry "**Owed: JSON writers still on the per-pid temp name**" (16 sites in 13
  files) is **done**: W folded all of them. The two `failedTranscriptions` sites went onto
  `writeFileAtomic` as text.
- The "Reusable helpers" row at `:166` ("tmp+rename write idiom | `normalizeTranscript.ts:139-141`")
  is historical. `normalizeTranscript.ts:141` is now `writeJsonAtomic(cuesPath, out,
  {indent: 0, newline: false})`. The idiom for any file is `writeFileAtomic` /
  `writeJsonAtomic`.

## Release 5 — slices R, X (verified 2026-09-24/25, `main` @ `93dcb532`)

- **One yt-dlp arg builder with a platform table.** `common/ytdlp/channelArgs.ts`:
  `PLATFORM_ARGS` :30 (`rumble: --impersonate chrome --sleep-requests 1`), `platformArgs` :34,
  `channelPlatform` :39 (`config.platform ?? detectPlatform(config.url)`), `channelExtraArgs` :45
  = cookies → platform args → `ytdlpExtraArgs` (a channel override is last and wins). `configArgs`
  (runYtdlp), the metadata scan and `checkAvailability` all delegate to it; `probeChannelMeta`
  and the no-config availability path call `platformArgs(detectPlatform(url))`. The table is code;
  there is no setting.
- **A 429 mid-sweep is "incomplete".** `EnumerationIncompleteError` `runYtdlp.ts:329`
  (`platform, pagesReached, count`), `lastListingPage` :353 (last `Downloading page N` — the real
  wording is `[RumbleChannel] TheQuartering: Downloading page 155`). `syncFullSweep` catches it
  before `acceptEnumeration`: best-effort `opts.onPlatformBackoff("rate_limit")` :1644 (=
  `recordDownloadBackoff`, the download runner's helper and schedule), the `Full sweep incomplete`
  line :1653, then `return syncPaged(opts)` :1658. No playlist write, no `lastFullSweepAt`. Any
  other non-zero exit throws as before; exit 101 untouched. `fullSweepDue` :1408 is exported, async,
  and false while `platformCooldownRemainingMs(detectPlatform(url) ?? "unknown") > 0` — the Sync
  gate's key. Syncs are REFUSED during the cooldown (`pipelineActions.ts` Sync gate), and the sweep
  is due again the moment it ends — no last-attempt stamp exists (follow-up if live sweeps keep
  coming back incomplete).
- **A bare `HTTP Error 403` is `network`** (`common/lib/availability.ts:255`), so a Cloudflare
  block backs the platform off; there is no `blocked` class because `DownloadFailureClass` is
  persisted in every `download-outcome.json`.
- **Fake yt-dlp** records every flat-playlist argv as `flat-playlist:full|paged argv=…` in the
  per-channel `fake-ytdlp.invocations` (`fake-ytdlp.mjs:543`); the `sweep429` URL sentinel :549
  prints 3 pages × 5 urls then the real 429 line and exits 1 on a FULL enumeration only.
- **`transcriptDownloads`** (absent = on) lives in three files and one context: `site.json`
  (`siteSchema.ts:88` type, :122 docs, :245 zod, :328 write-if-false), `homepage.json` for the hub
  (`homepage.ts:39,83,133` — the hub has NO site.json; `hubSite()` `export/app/lib/site.ts:40` passes
  it through), and `PlayerProvider` `features` (`PlayerProvider.tsx:118`, default all on);
  `TranscriptModal.tsx:79` `showDownloads` hides exactly Copy download command, the Download
  dropdown and Copy MD. FOUR mounts, all in `export/` (`(workspace)/layout.tsx` → `SiteWorkspace`,
  `duplicates/page.tsx`, `HubHome`, `AskHub` via their server pages); the editor mounts neither.
  `SITE.md` is generated; `homepage.json` has no generated doc and no zod schema.
- **The export e2e off-test flips the committed fixture** `export/e2e/fixtures/sites/testsite/site.json`
  for one test; `export/playwright.config.ts:38` strips a leftover key at config load (before any
  spec), so a killed run leaves at most a whitespace diff. `workers: 1`, so no other test can see
  the flip.
- **Rollout facts.** `ops channel-config` with `patch: {"<field>": null}` CLEARS a Configure-form
  field (the route lays the patch over `channelConfigToFormData(existing)` and
  `updateChannelAction` unsets every form field first) — that is how `fullSweepIntervalMinutes: 0`
  was removed from `the-quartering-rumble`. A site's `archives` / `transcriptDownloads` are written
  only by the Settings form (`saveSiteAction` → `writeSite`); there is no `ops site-config`.
- **A Settings-form save materialises missing `order` fields** on a site's groups and channels
  (entries added through the CLI carry none). Group order is consumed by `sortGroups`
  (`channelGroups.ts:118`, missing = last); channel `order` is parsed (`siteSchema.ts:154`) and
  read by nothing. So a "no-op" site save can move bytes; `jq -S` plus the `order` fills is the
  expected diff, not a bug.

## Release 17 — slice RL: a subtitle 429 is not a platform failure; the pace adapts (verified 2026-10-01)

- **YouTube's 429s are its subtitle (timedtext) fetch, per video.** Measured 2026-10-01 on the
  live corpus: all 78 HTTP 429 lines in 24 h of job logs were `Unable to download video subtitles
  for 'en': HTTP Error 429`; none on the watch page, player API, m3u8 or a listing; the backoff
  read `fails: 80`. The 2026-09-25 postmortem (`plans/youtube-lane-pacing.md`) found the same.
- **`subs_rate_limit`** is a `DownloadFailureClass` (`lib/availability.ts`): `classifyDownloadFailure`
  returns it when a subtitle-429 line is present and every `ERROR:` line is a subtitle line (no
  soft block, no bot check) — `isSubtitleRateLimitOnly` / `hasSubtitleRateLimit`. It is set on a
  **SUCCESS** record (`status: ok…`, `failureClass: "subs_rate_limit"`), the one class that is.
- **yt-dlp's `--ignore-errors` turns ANY subtitle failure into a WARNING and carries on** — a 429, a
  403/404/5xx, a failed `live_chat` replay, an OSError writing the file (review H1, verified offline for
  a 403) — so the downloader parses the WARNING's class: only a rate limit takes the media path
  (`hasNonRateLimitSubtitleFailure` keeps any other a failed attempt, not archived, classified from the
  tail)
  (`YoutubeDL._write_subtitles`: `ignoreerrors is True` → `report_warning`; `'only_download'`, i.e.
  `--no-abort-on-error`, still raises). Without it, a `--load-info-json` run that fails re-extracts
  from the URL once (`download_with_info_file` "The info failed to download … trying with URL") —
  the "one internal re-extraction" the evidence saw. The youtube-handling primary
  (`downloadOneManaged.ts` `youtubeHandlingArgs`) carries `--ignore-errors` and
  `--sleep-subtitles max(5, pace)` after `-t sleep`; a subtitle 429 there exits 0, no transcript
  lands, and attempt 3 (the no-subs media pass, `--no-write-subs --no-write-auto-subs` appended)
  fetches the audio. Any other primary that died on its subtitles alone is re-run once as
  `primary-without-subs` (`DownloadAttemptKind`).
- **The pacing memory** is three maps beside `platformBackoff`/`videoDeferrals` on every lane of
  `.auto-queue/state.json` (download only in practice; `{}` coerced for an older file):
  `platformPace {sleepRequestsSeconds, baseSeconds, cleanUnits}` (absent = at the static value),
  `platformHolds {since, probeAt}`, `subtitleDeferrals {count, lastAt, until, channelSlug}`. The
  pure seam is `jobs/platformBackoff.ts` (`escalatePlatform`, `settlePlatformClean`,
  `prunePlatformPacing`, `deferSubtitles`, `downloadGapMs`, `heldPlatformSentence`) and
  `jobs/unitOutcome.ts`; every writer outside the runner goes through `jobs/downloadBackoff.ts`'s
  one write-through (`recordDownloadBackoff(pf, paths, failureClass)`, `recordSubtitleDeferral`,
  `clearSubtitleDeferral`, `heldPlatformRefusal`).
- **The pace reaches every spawn synchronously**: `channelExtraArgs` reads
  `livePlatformPaceSeconds(pf)` (`jobs/autoQueueState.ts`) — the shared object when a runner holds
  it, else the pace the last read/write of the file saw (`holder.lastPace`; the status poll reads
  the file), else the static value. `withSleepRequests` only RAISES `--sleep-requests`; the
  channel's own `ytdlpExtraArgs` still come last and win. The pace key is
  `detectPlatform(url) ?? "unknown"`, the cooldown's key.
- **The hold**: `FAILS_TO_REACH_CAP` = 6 (60 s doubling reaches the 30-min cap at the sixth);
  `failsAtCap(fails) = max(0, fails − 5)`. At `pacing.holdAfterFailsAtCap` the backoff's `until`
  becomes `now + holdProbeMinutes` (no jitter) and `platformHolds[pf].probeAt` mirrors it
  (`rateLimited` false for a hold reached through network failures alone); a held platform's backoff
  entry is never pruned. It is cleared by a clean lane unit (a `subs_rate_limit` unit included), by a
  clean manual run once the probe is due (`runYtdlp`'s `onPlatformClean` → `recordPlatformClean`, and a
  clean metadata scan), or by **Clear hold** (`clearPlatformHold`, a `clear-platform-hold` job on queue
  `pacing:<pf>`). Manual actions are refused only while held AND before the probe time.
- **The one time-based rule:** a raised pace eases one step per `PACE_TIME_DECAY_MS` (1 h) since its
  `steppedAt` with no rate limit (`effectivePaceSeconds` for readers, `decayPaceByTime` on writes). A manual Sync / download / metadata scan / fetch-window on a held platform is refused with
  `heldPlatformSentence` (`<pf> is held: … the next probe is in N min. <What> will run once a probe
  comes back clean.`).
- **The download lane now waits between units**: `platformNextStartAt` (in memory) =
  settle + `downloadGapMs(settings.sleepBetweenDownloadsSeconds, pace, base)` — the setting plus
  the pace ABOVE its base (the base is already paid inside each spawn). `runManagedDownloads`
  sleeps the same sum. Idle reasons `held` and `paced` join `cooldown`/`deferred`.
- **download-missing-subs** skips videos inside a subtitle deferral (logged in the prefilter line),
  records a subtitle 429 and goes on to the next video whatever `abortOnError` says, and clears a
  deferral when the subtitles come down. `runChildAndStream` returns its stderr tail (and attaches
  it to the thrown error as `stderrTail`).

## Release 7 — slices Y, C, K (verified 2026-09-25, `main` @ `bb3dbb4c`)

- **A rate-limited video is deferred, per video, for 6 h.** `common/jobs/platformBackoff.ts`:
  `VideoDeferral {until, channelSlug}`, `VIDEO_RATE_LIMIT_DEFER_MS` (6 h), `deferVideo`,
  `isVideoDeferred`, `pruneDeferred`, `coerceVideoDeferrals`. The map is `videoDeferrals` on every
  lane of `transcripts/.auto-queue/state.json`, **beside `platformBackoff`, persisted** (a restart
  honours it; an older build drops the key on its next write). The one seam is
  `common/jobs/unitOutcome.ts` `applyUnitOutcome` — `rate_limit` backs the platform off AND defers
  the id; `network` backs off only; success clears the backoff. Its line, grep-able in
  `transcripts/.jobs/*.log`: `Auto-download: <pf> rate_limit — backing off <s>s (attempt <n>).
  <id> deferred 6h; next video after cooldown.` (the `network` line, and the pre-release-7
  `rate_limit` line, end `<id> will retry after cooldown.`). The download pick drops deferred ids; when that leaves nothing the idle reason
  is **`deferred`** (`AutoRunnerIdleReason`, `dispatch.ts` `idleReasonText`, `activeJobs.ts`
  `autoIdleNote` — both exhaustive). **Manual Sync and download-missing ignore deferrals**; a manual
  429 records a platform cooldown only. `/api/view/autoQueueStatus` carries `<lane>.deferred:
  [{videoId, channelSlug, untilMs}]`; `/operations/download` draws `role="region"` "Rate-limit
  cooldown" with lists "Platforms in cooldown" / "Deferred videos". The runner never merges
  deferrals from disk mid-run (only it writes them). The pick filter is by video id, so a channel
  rename leaves a stale but harmless `channelSlug` until expiry.
- **An identical metadata-scan error refreshes its `at`** once it is
  `METADATA_SCAN_ERROR_COOLDOWN_MS` old (`common/controller/metadataScanStore.ts`
  `upsertMetadataScan`), so members-only ids are no longer re-scanned at every runner start.
- **YouTube is ONE serialized queue.** Every job kind with `queueKeyStrategy: "platform"` (sync,
  metadata-scan, download-missing, retry-bucket, fetch-window, auto-download-unit, …) lands on
  `platform:youtube` (`common/lib/queueKeys.ts:69-73` `downloadQueueKey`), and the registry submits
  every job with `concurrency: 1` (`common/jobs/registry.ts:189-211`). Two YouTube downloads never
  overlap (0 overlaps in 36 h of job metas, 2026-09-25). The exceptions are dormant:
  `check-kept-deleted` runs on `channel:<slug>`, and the backfill re-acquire runs on the
  `backfill` queue (off while `backfill.allowRedownload` is false). YouTube has **no**
  `--sleep-requests` in `common/ytdlp/platformArgs.mjs` (Rumble has `1`); every retained YouTube
  429 is a per-video subtitle fetch.
- **`archilyzer` is the one command line**: `common/bin/archilyzer.ts`, a table over
  `common/bin/_cli.ts` (`resolveCommand` longest-path, `argumentProblem` refuses an unknown flag
  before `run`) and `_parseFlags.ts` `parseArgv` (skips pnpm 11's forwarded `--`). Run as
  `pnpm --filter yt-dlp-transcript-common exec tsx bin/archilyzer.ts <cmd>` (or `tsx
  ../common/bin/archilyzer.ts` from `export/` / `homepage/`). Commands: `index`; `compose
  site [<id>] | hub | homepage`; `build site [<id>] [--nodata] [--skip-archives] | all
  [--skip-archives] | hub | homepage`; `deploy site [<id>] [--preview <b>] | hub [--preview <b>] |
  homepage`; `sync tick`; `settings example [--check]`. Exit 0 ok, 1 failed/refused, 2 usage.
  Not yet: `doctor`, `run`, `mcp` (Phase 4 slice 3). The ten bins export `main(opts)` and
  auto-run through `runIfEntryPoint`, so `tsx bin/x.ts` still works.
  > **Superseded by release 18 (2026-10-06):** `build site|all` and `deploy site|hub|homepage` are printed aliases of `archilyzer publish …`, and a stage exits 0, 1, 2, 3 or 130 — see "The publish stages" at the end of this file.
- **`export/package.json` `build` IS the CLI** (`tsx ../common/bin/archilyzer.ts build site`,
  `SITE_ID` from env); `build:hub` → `… build hub`, `deploy` → `… deploy site` (refuses without a
  project). **`prebuild` and `build:nodata` are gone** — the data phase is an explicit step of
  `buildSiteSteps` (`common/publish/build.ts`: `build:data` unless skipData, `compose:site`, `next
  build`). `docker/build-site.sh` / `publish-site.sh` call the CLI. `common/publish/build.ts` has
  the named entry points `buildSite`, `deploySite`, `buildAll`, `composeHub`, `buildHub`,
  `deployHub`, `composeHomepage`, `buildHomepage`, `deployHomepage`; the editor's jobs call them.
  > **Superseded by release 18 (2026-10-06):** `buildSite`, `deploySite`, `buildAll`, `deployHub` and `deployHomepage` are deleted from `build.ts` (`514e9674`); the editor's jobs are publish stages — see "The publish stages" at the end of this file.
- **The hub builds and deploys.** `buildHub` = compose-hub + `INSTANCE_MODE=hub next build` into
  **the shared `export/out`** (it removes `public/site.json` first; compose-site removes
  `public/hub-sites.json`). `deployHub` reads `homepage.json` `cloudflareProject` — live value
  **`archilyzer-hub`**, `siteUrl` `https://archilyzer-hub.pages.dev` — and `hubProjectProblem`
  refuses the literal `archilyzer` (`HOMEPAGE_PAGES_PROJECT`, the homepage's project). Deploys
  re-check the bundle inside the job: `builtHubProblem` (`common/lib/builtExport.ts`; a `site.json`
  means a site bundle even with a stale `hub-sites.json`) / `builtSiteProblem`. Entry points:
  `/sites` Hub section (`HubBuildButtons.tsx`: **Build hub**, **Deploy after build**, **Deploy
  hub**), `pnpm ops build-hub` / `deploy-hub`, the CLI. **A Pages project must exist before its
  first deploy:** wrangler offers to create one only on a TTY, and a job or the CLI spawns it with
  piped stdin, so it fails fast. A production `deploy hub` takes its branch from the git checkout;
  `deploy homepage` passes `--branch main` to `archilyzer`.
  > **Superseded by release 18 (2026-10-06):** the hub's build is installed as `<exportBuildsDir>/_hub/out`, and every production deploy, the hub's included, passes `--branch main` — see "The publish stages" at the end of this file.
- **Posts-only channels publish their manifest.** `common/bin/compose-site.ts`
  `reconcileChannelTree` copies a manifest-only tree under `MANIFEST_ONLY_SIGNATURE` instead of
  removing it; `corpus.json` still advertises `manifests.transcripts` unconditionally, spec 4.
- **`pnpm ops keep-videos`** `{slug, match, fields?, note?, dryRun?}`
  (`common/controller/keepVideosMatching.ts`, `editor/app/api/ops/keep-videos/route.ts`) sets the
  do-not-clean marker on every video whose title + description matches — the download filter's
  own matcher (`compileDownloadFilter` / `classifyAgainstFilter`, ReDoS guard first). It never
  creates `data/<id>/`: matches with no dir come back in `notDownloaded`, ids with no text in
  `unscanned`. One-shot, idempotent; re-run after new downloads. Media guard first.
- **e2e isolation: `export/out` belongs to the checkout, not the fixture.** `resolveOutDir` =
  `paths.exportDir/out`, so whatever the last `e2e:2origin` / hub build left there is what an
  editor spec's deploy route sees. `ops-api.spec.ts`'s deploy-hub "not the hub" sub-case therefore
  runs only when `../export/out/hub-sites.json` is absent or a `site.json` is present, else it
  records `subcase-not-exercisable` (`211d4666`) — before that guard it started a real deploy job.
  Any spec that can reach a deploy must check the build dir before calling with a valid project.
  > **Superseded by release 18 (2026-10-06):** a deploy reads the target's stamped bundle, never `export/out`; the guard is gone and the sub-case runs in any checkout — see "The publish stages" at the end of this file.
- **tsc in the primary checkout reports errors in `editor/.next/dev/types/validator.ts`** — a
  stale generated file left by an old `next dev`, naming routes that moved. 0 source errors;
  worktrees without that file are clean. Clear it with `rm -rf editor/.next/dev` when no dev
  server runs.

## Release 8 — slices V, S (verified 2026-09-25, `main` @ `0e72ef73`)

- **A channel's video titles come from `common/controller/videoTitles.ts`.**
  `readChannelVideoTitles(paths, slug, ids)` returns `Map<id, {title, source}>`. It tries three
  sources in order, and the first hit wins:
  1. **`index`**: the LMDB `sums` sub-DB, reached by a key-only walk of the channel's `byChannel`
     range. It is opened `readOnly` with `compression: true`, and an index title equal to the id is
     skipped as `summarize()`'s fallback.
  2. **`scan`**: `channels/<slug>/metadata-scan.json`, through `loadMetadataScan`.
  3. **`metadata`**: `data/<id>/metadata.info.json`. It reads a 16 KB head plus a regex, and does
     the full parse only when the head has no title.

  **Source 3 is memoized per channel** in `globalThis.__yttVideoTitleMemo__`, a
  `Map<dataDir, {dataDirMtimeMs, titles}>`, **keyed by the `data/` dir's mtime**: one `stat` per
  render, and a changed mtime (a dir added or removed) drops the channel's entry.
  `MEMO_MAX_CHANNELS = 64`, evicted least recently used. **Untitled ids are not memoized**, so a
  dir still downloading picks up its title later. A `metadata.info.json` rewritten inside an
  existing dir does not refresh the memo, which is accepted. `resetVideoTitleMemo()` is called by
  `editor/app/api/test/invalidate-cache/route.ts`. Nothing here creates `data/<id>/`.

  Why the memo: every Rumble dir name misses the index, whose key is the embed id while the dir is
  the URL slug. `the-quartering-rumble` (8,049 dirs) cost 5,024 ms cold / 224 ms warm on every
  render before the memo, and 5,331 ms first then ~6 ms after.
- **The list and search contract** (`editor/app/channels/[slug]/videos/page.tsx`,
  `components/VideoListPane.tsx`, `lib/videoRows.ts`). `VideoRow.title?` is filled once per
  render over data-dir ids ∪ `undownloadedIds`. A titled row shows the title, with the id on a
  muted mono line under it. An untitled row shows the id alone. **The row labels are unchanged:
  `open <id>`, the checkbox `select <id>`, and the search box's label `search videos`.** Its
  placeholder is "Search title or id…". `matchesVideoQuery(row, q)` (`lib/videoRows.ts`: id OR
  title, case-insensitive) is the ONE predicate, shared by the client filter and the server's
  `?q=` prev/next ordering. Rows stay sorted by id.
- **The video page falls back to the scan.** `editor/app/channels/[slug]/videos/[id]/page.tsx`
  reads `readVideoMetadataForDisplay(paths, slug, id)`, which returns `{title?, description?,
  webpageUrl?, uploader?, uploadDate?, duration?, source: "metadata"|"scan"|"none"}` with
  `metadata.info.json` first. When `source` is `scan`, the header shows the scan's title, date and
  duration, plus an italic note, "from the listing scan — not downloaded"
  (`aria-label="metadata source"`). A collapsed `<details>` **Description** appears when either
  source has one. `generateMetadata` falls back title → id.
- **ONE `AutoQueueState` object per process, for real.** The holder is
  `common/jobs/autoQueueState.ts` on `globalThis.__yttAutoQueueState__`.
  `sharedAutoQueueState(paths)` caches the **in-flight read, per state file**, so the four lanes
  booting concurrently all await one `readAutoQueueState` and share the object. A failed read is
  not cached. `common/controller/autoRunner.ts` re-exports it, and `jobs/` still imports nothing
  from `controller/`. `liveAutoQueueState(paths)` returns the live object, or the in-flight one,
  without starting a read. Before this, each lane held a private copy, and `writeAutoQueueState`
  (which writes all four lanes) let any lane's persist revert another's. That is the live
  2026-09-25 13:33:37 revert of a 6 h deferral and `fails: 13`, which recurred at ~14:18.
- **`recordDownloadBackoff` (`common/jobs/downloadBackoff.ts`) writes through the live object.**
  This is the 429 cooldown recorded by a manual Sync, a metadata scan or the video page. When a
  runner is live, it merges the disk entry in (the later `until` wins, and the entry is copied
  whole: a known race can lower `fails`), escalates on the live object and writes through it.
  With no runner live, it is a disk round trip. `platformCooldownRemainingMs` and the status
  builder's `computeLeafPending` prefer the live object.
- **The e2e reset clears two more globals.** `api/test/invalidate-cache` now sets
  `__yttAutoQueueState__ = undefined` beside `__yttAutoRunner__`, and calls
  `resetVideoTitleMemo()` (`__yttVideoTitleMemo__`). A new process memo or holder must be added
  there, or it leaks across specs.
- **A QUEUED job that calls `revalidatePath` ends `failed` after doing its work** (the invariant).
  The editor's job bodies and completion hooks call `revalidatePath`:
  `editor/app/channels/[slug]/pipelineActions.ts:220-224` in `runPipelineAction` (sync,
  download-missing, download-missing-subs, retry-bucket), the metadata scan's `afterRun`
  (`:364-367`), and the `onDone` callbacks passed to `runOperationChannelJob` (the hook exists
  because common cannot import `next/cache`, `common/controller/operationJobs.ts:23`). A job that
  starts inside the submitting request (an empty platform queue) has a request store. A job that
  was queued is started later by the queue's drain loop, which has none, and Next throws `[error]
  Invariant: static generation store missing in revalidatePath /channels/<slug>`. The work is
  done and the files are written, but the status is `failed`, `pnpm ops … --wait` exits 1, and
  nothing is revalidated. First seen live: sync `01M3CY7BN3DNN12T93X9GZM48X` (teamrcn),
  2026-09-25 15:21. Fix owed: a store-tolerant revalidate.
- **A cancelled metadata scan keeps what it scanned.** `channels/<slug>/metadata-scan.json` is
  written incrementally, and a later scan resumes the remainder (paramount-tactical: cancelled at
  377/1,382, and the store holds 377).
- **The download filter settles scanned non-matches with no request.** `runYtdlp`
  (`common/ytdlp/runYtdlp.ts`, `settledByTitleFilterIds`) reads the scan store once per batch and
  drops every id the channel's `downloadFilter` already rejects, before the per-video metadata
  prefetch. Its log line is `Settled by this channel's download filter: <n> skipped (already
  decided).` Live: 376 of 377 scanned on paramount-tactical with `include: "Quartering"`. Unscanned
  ids still pay a prefetch each. So **scan first, then download-missing**, on a filtered channel.
- **The `/jobs` stall label is age-without-tasks, not age-without-progress.**
  `common/views/jobRows.ts` marks a live record `possibly-stalled` when it has no `tasks` and has
  run past `STUCK_AGE_MS` (10 min). A metadata scan registers no tasks, so a healthy scan at ~10
  videos/min (`--sleep-requests 1` plus per-video requests) reads `STUCK · POSSIBLY-STALLED` after
  10 minutes. It is soft: surfaced, never auto-healed.
- **Restart leftovers.** Jobs queued when the editor stops keep `status: "queued"` in their meta
  forever (no re-queue, no mark). A just-drained job also reads `queued` (`startedAt: null`) for a
  while after its log starts. Both are cosmetic.

## Release 9 facts (2026-09-25)

- **A job body never calls `revalidatePath` directly.** A job the platform queue drains runs with no
  request store and Next throws `Invariant: static generation store missing`, which marked the job
  `failed` after its work was done. Job bodies and `onDone`/`afterRun` hooks call
  `safeRevalidate(paths, tags?)` (`editor/app/lib/safeRevalidate.ts`): it swallows exactly that
  invariant, rethrows anything else. Request-context server actions keep the plain call.
  **Release 10 (L2):** every skip is counted by one `SkipReporter` per process
  (`globalThis.__yttSafeRevalidateSkips__`): the first after a quiet spell is logged at once and
  opens a 10 min window (`SKIP_REPORT_WINDOW_MS`), the rest are reported as one
  `[safeRevalidate] N more skip(s) …; T since this process started.` line when it ends. It was one
  warning per module instance.
- **`--sleep-requests 1` is a YouTube platform arg** (`common/ytdlp/platformArgs.mjs`), like
  Rumble's; a channel's `ytdlpExtraArgs` comes after and wins.
- **`runManagedDownloads` skips the inter-download sleep only for `skipped-filtered`** (no media
  request was made). Every failure class still sleeps — YouTube's soft block "try again later"
  classifies as `deleted`/per_video, so skipping there would hammer a soft block.
  **Release 10 (L2): no longer.** `isSoftBlock` (`common/lib/availability.ts`, "isn't available,
  try again later", either apostrophe) is checked first: `parseUnavailableFromStderr` → `error`,
  `classifyDownloadFailure` → `rate_limit` even over a per-video class. The batch records the
  platform cooldown and aborts; the metadata scan stops as a `soft-block` block. Every failure
  still sleeps. **L2 review fixes:** a metadata prefetch that classifies `rate_limit` ends
  `downloadOneManaged` there (no attempt 1; `writeOutcome` writes the sidecar for both exits), and
  `runAvailabilityCheck` stops at its first `rate_limit` probe (`blocked`, `probedIds`, one
  `recordDownloadBackoff`). **`verifyBeforeClean` leaves every tier C suspect the check did not probe
  `unverified`** (not in `probedIds`: the check was blocked before it, or it had no `webpage_url`) —
  never judged on its old `availability.json`, which is what would clear an irreversible delete. No live sidecar held the string (2026-09-26 read-only grep of 136,401
  `availability.json`/`download-outcome.json` and every `metadata-scan.json`), but an availability
  check stores no text for `deleted`, so an earlier misread there cannot be found after the fact.
- **A job record carries `progressAt`** (live-only, stamped by the one progress writer and by task
  completion). `/jobs` marks `possibly-stalled` only when tasks are idle AND progress has not moved
  for 10 min (`common/views/jobRows.ts`).
- **Boot settles queued metas** (`common/jobs/bootQueuedJobs.ts`, from `instrumentation.ts`, after
  the storage boot pass, best-effort): `sync` is never re-queued (the heartbeat re-derives it);
  metas queued > 24 h before the boot are cancelled as stale; of the rest only the newest per kind +
  channel + bucket + params is re-queued via the retry path; the others are cancelled as superseded;
  `ARCHILYZER_IDLE_BOOT` cancels everything. A `cancelReason` field on the meta says why. First live
  boot: re-queued 1, cancelled 390. **Release 10 (L2):** the wait on the storage pass is bounded
  (`settleAfterStoragePass`, `STORAGE_PASS_WAIT_MS` 60 s; a `stat`/statfs on a hung mount has no
  timeout of its own) and logged when it fires; the storage pass is not cancelled. `cancelReason`
  is drawn on `/jobs` (`JobListEntry` → `JobRowView.cancelReason`, only on a `cancelled` meta;
  `data-testid="cancel-reason"` on the row and the job page's "Cancelled because" cell).
  **Release 13 (W1): an operator's cancel of a QUEUED job now writes its `cancelled` sidecar**
  (before, it kept `queued`, and this pass could re-queue it). `registry.cancel()` marks the record
  terminal (`markTerminal`) before `scheduler.cancel()` fires `onCancel`, and streamCommand's
  `onCancel` persists a terminal record. **Graceful shutdown still leaves `queued`:**
  `shutdownCancel.ts` calls `registry.beginShutdown()` first, so a queued job reaches `onCancel`
  still queued and nothing is written — this pass keeps its input. A job's meta writes are chained
  (`metaWriter` in `streamCommand.ts`), so the enqueue's write never lands after the terminal one.
- **The hub embeds `public/hub-summary.json`** at `compose:hub` (`common/controller/poolSummary.ts`
  shared with `compose-homepage`; `common/lib/hubSummary.ts` projects `official` + per-site figures
  from the same `buildHomepageSummary`). Optional end to end: missing/404/malformed → cards without
  figures. `compose-site` removes it; `builtHubProblem` does not require it; it is gitignored. A
  member's `corpus.json` carries only channel/video counts, so the figures cannot be summed live.
- **The hub defaults to the `archilyzer` theme, dark** (`export/app/layout.tsx` branches on
  `instanceMode() === "hub"`); site builds stay base/system. In that theme `--chart-3` is its own
  green (light `#5a9e3a`, dark `#86c86a`), no longer `--state-gone`'s hex.
- **Port blocks follow the sorted worktree list** (`pnpm wt list`): adding or removing a worktree
  shifts every later block. Tell a running implementer.
- **Worktree e2e can write INTO the primary through `export/public` symlinks** (2026-09-25, slice
  C1b): `export/playwright.config.ts` copies `service-worker/site-sw.js` to `public/sw.js` when the
  config loads, and in a worktree that path is a link to the primary's generated hub `sw.js`. A
  site-mode export e2e in a worktree therefore overwrites the primary's hub service worker (10,027 →
  10,043 B). ~~Replace `export/public/sw.js` with a copy before any export e2e in a worktree; the
  proper fix (unlink before copy in the config) is a release-10 low.~~ `build-hub` regenerates the
  file, so a deploy is never wrong, only a worktree run in between.
  **SUPERSEDED 2026-09-26 (release 10 L1, on `main` since `5c0a6ef9`): do NOT copy `sw.js` any
  more.** `export/playwright.config.ts:51-55` `fs.rmSync`s `public/sw.js` before its
  `copyFileSync` (`rmSync` reads the path with lstat, so it removes the link, never its target).
  Proved on the integrated tree: the export suite ran with the worktree's `sw.js` a LINK (to a
  sentinel in the job's scratch) and left the target byte-identical (`release-10.md`, "Integration
  (S4 + L1 + L2), as merged"). The per-path seed of the `export/public` links stays.
- **The homepage build refuses symlinks that point outside the project**, so a worktree's
  `homepage/public` data (~60 MB, `homepage-summary.json` + stats pages) must be COPIED from the
  primary, not linked.

## Brand + themes — slices S0–S3 (verified 2026-09-25, `main` @ `b9772e53` + S3 `brand/found-line` @ `2c76f6b2`)

Next is 16.2.3 (`export/node_modules/next/package.json`). The plan and every slice record are in
[`brand-and-themes.md`](brand-and-themes.md) "As shipped"; the release is
[`release-10.md`](release-10.md).

- **A force-static GET route handler is copied to its EXACT path under `output: "export"`.**
  `next/dist/export/index.js:712` marks an app route handler, and `:728-736` copies its prerendered
  `<route>.body` byte for byte to `out/<route>` — no `.html`, no hash. So
  `export/app/icons/[file]/route.ts:9-14` (`dynamic = "force-static"`, `dynamicParams = false`,
  `generateStaticParams` over `ICON_FILES`) writes `out/icons/icon-192.png` etc., and
  `homepage/app/icons/[file]/route.ts:9-14` is its twin. `app/icon.tsx` cannot do this: its URLs
  are always hashed. Checked on every S3 build: seven files, PNG magic `89504e47…`, IHDR
  180/192/32/512/512. Such a route must never read the request.
- **`next/og` runs under tsx**, so a unit test can render a real PNG and read its IHDR
  (`common/lib/brandIcons.test.ts:129-148`, which also reads pixel (0,0) out of the inflated IDAT to
  tell the variants apart). A probe script that uses top-level await must be `.mts`: tsx refuses it
  in a `.ts` it compiles to CJS.
- **`/favicon.ico` can be a route handler** (`export/app/favicon.ico/route.ts:7`,
  `homepage/app/favicon.ico/route.ts:6`, force-static). Next files `/favicon.ico` as a metadata
  route (`next/dist/lib/metadata/is-metadata-route.js:114`, `FAVICON_REGEX`), so it is **missing
  from the build's route table but IS emitted** (`out/favicon.ico`, starting `00 00 01 00 03 00`:
  three PNG entries, 16/32/48). Next adds no `<link>` for it; `<head>` is exactly `ICON_METADATA`
  (`common/lib/brandIconFiles.ts:35-43`).
- **Importing Next's root types into `common/` breaks common's tsc.** `import type { Metadata }
  from "next"` pulls `next/index.d.ts:1` (`/// <reference types="./types/global" />`), whose
  `ProcessEnv` augmentation makes `NODE_ENV` required (`next/types/global.d.ts:23`) on every
  `process.env` object in common's program: 10 errors in untouched tests (S1, tsc run 1). So
  `ICON_METADATA` is untyped (`brandIconFiles.ts:32-34`) and the layouts type it. `next/og` does not
  carry the reference.
- **The service workers: `SHELL` is `"shell-v2"`, `VERSION` stays `"v1"`, `/icons/` is
  network-first.** `export/service-worker/site-sw.js:37-40` (`sw-hub.js:28-31`); activate keeps only
  `{SHELL, PAGES, META}` (`:64` / `:54`). **Never bump `VERSION` for a shell change:** `PAGES` and
  `META` are `pages-${VERSION}` / `meta-${VERSION}`, so a bump deletes every reader's offline channel
  downloads. `/_next/static/` is cache-first (content-hashed); `/icons/` is `networkFirst(req,
  SHELL)` (`:107-108` / `:97-98`) because the icons keep their URL across an accent change.
  `networkFirst` stores only an `ok` response and falls back to the cache when the fetch throws
  (`site-sw.js:134-144`); `common/lib/archive/serviceWorkerRouting.test.ts` runs both workers in
  `node:vm` and pins fresh-online, a non-ok response not replacing the cached icon, and the offline
  fallback. **The rename's one cost:** activate also drops shell-v1's cached HTML and chunks, so right
  after the update an installed app opens offline only after one more online visit.
- **The reader's theme is two localStorage keys** (`common/components/themeConfig.ts:27-36`):
  `ytdlp-tb:base` (`system|light|sepia|dark`) and `ytdlp-tb:accent` (an accent id, stored ONLY
  while it differs from the site's: `setAccent(siteAccent)` removes it, `ThemeProvider.tsx:178-190`;
  `"custom"` is never stored). The retired `ytdlp-tb:theme` / `ytdlp-tb:mode` are read once and
  deleted. **The migration** (`migrateLegacy`, `:167-181`, and the same table inside the pre-paint
  script, `:207-213`) runs only when no base is stored: mode `light` → `light`, or `sepia` when the
  old theme was `archive`; `dark` → `dark`; `system` → `system`; absent → nothing stored. The family
  is dropped. The pre-paint script (`buildThemeScript`, `:196-226`) sets `data-base` + `.dark`, then
  `data-accent` only from a valid stored id, then every `meta[name=theme-color]`, and **LAST
  `data-theme-ready="1"`** — the e2e no-flash marker. After a `reload({waitUntil: "commit"})` the new
  document can have no root yet, so a spec waits on `document.documentElement?.dataset.themeReady`
  (S2 `e3e3fb26`). `ThemeProvider`'s `useLayoutEffect` (`:137-140`) adopts the stored choice and
  re-asserts the attributes before paint, because hydration can reset them.
- **`data-base` / `data-accent` and the cascade** (`common/styles/tokens.css`). `.dark` is on
  `<html>` iff the resolved base is dark; `@custom-variant dark (&:where(.dark, .dark *))` (`:39`)
  keeps Tailwind's `dark:` on the class, so sepia styles as light. The light block is
  `:root, html[data-base="light"]` (`:155-156`) and doubles as the no-script fallback; sepia
  (`:247`) and dark (`:325`) are `html[data-base=…]`, (0,1,1), and win over `:root`'s (0,1,0). The
  eight `html[data-accent=…]` rules (`:403-437`) come AFTER all three bases at the same
  specificity, so the accent wins `--brand` on every base; `--brand` reads the base's `--swatch-<id>`,
  so an accent is always its contrast-corrected value for the ground it is on. `--brand-mark` is the
  accent's on-dark value on every base (the header mark sits on an ink tile), with a Signal default
  on `:root` (`:116-122`) for the editor, which renders no `data-accent`. `--primary` is neutral ink
  on every base; `--ring: var(--brand)`. `themeTokens.test.ts` parses the sheet and pins all of it,
  including the swatches against `lib/brand.ts` `ACCENTS`.
- **The hub and the homepage render dark on the server; a site cannot.**
  `export/app/layout.tsx:109-120` adds a literal `… dark` class and `data-base="dark"` only when
  `defaultBase === "dark"` (the hub); `homepage/app/layout.tsx:67-70` always does. A site's default
  is `system`, which only the browser can resolve, so a site's server HTML carries `data-accent`
  (and a custom hex's inline `--accent-custom-*`) but no `data-base`, and a no-JS reader gets the
  light block. `suppressHydrationWarning` is on both `<html>`s; React does not patch attributes on
  hydration.
- **Chromium on Linux splits IBM Plex Sans words at 1.5x and up.** The Google-served font has no
  TrueType instructions (no `fpgm`/`prep`, no glyph programs) but its `gasp` table asks for
  grid-fitting at every size (`{9: 10, 65535: 15}`), so FreeType hints it and each advance is
  rounded to a whole CSS pixel: at 14px the `g` of "Signal" is 9 px against a 7.41 px design width,
  at every DPR (S3 probe, `$T/s3-probe2.log`; S2's "ships TrueType hinting" was inexact). At
  1x and 1.25x the hinted glyph fills the advance and reads clean; **from 1.5x (1.5, 1.75, 2, 3) it
  reads "Sig nal"**. `text-rendering: geometricPrecision` turns hinting off (advance 7.41). It is
  scoped `@media (min-resolution: 1.5dppx)` (`tokens.css:141-149`; built as `(min-resolution:1.5x)`)
  on `html, button, input, select, textarea` — the UA sheet resets form controls to `auto`.
- **Google Fonts can answer a static-weight request with `l/font?kit=…&skey=…` URLs, and Turbopack
  cannot load them.** IBM Plex Sans is a variable master on Google (`wght` 100–700; next's
  `font-data.json` lists `variable`). A request for static weights is cut from it — usually a cached
  `https://fonts.gstatic.com/s/ibmplexsans/v23/<instance>.woff2`, but at times through the dynamic
  instancer, `https://fonts.gstatic.com/l/font?kit=…&skey=…&v=v23`. Turbopack's `next/font/google`
  puts the font URL in a `?{"url":…}` import query and requires exactly one query entry, so the `&`
  breaks it: `next/font/google queries have exactly one entry` → `Module not found:
  '@vercel/turbopack-next/internal/font/google/font'`, and `next dev` never answers (the homepage e2e
  webServer timed out at 120 s, S3, 23:30) or `next build` fails (S1, the homepage build). Twice on
  2026-09-25, both on IBM Plex Sans; 26 later static-weight requests all got `/s/` URLs. **Request
  a variable family with no `weight`** (`common/styles/fonts.ts:42-46`, the reason in the comment
  above it): the variable file is always a pre-built `/s/` URL. Its `wght=400` instance has the
  static file's advances and outlines exactly (fontTools, 54 glyphs). IBM Plex Mono is static-only
  on Google, and Archivo was already requested variable.
- **Worktree e2e and builds write through the `export/public` links into the primary.** Besides
  `sw.js` (the release 9 fact above), `e2e:2origin` with `TWO_ORIGIN_REBUILD=1` runs `pnpm run
  build:hub` (`export/e2e-2origin/globalSetup.ts:142`), whose `compose:hub` `writeFile`s
  `hub-sites.json`, `corpus.json`, `llms.txt`, `robots.txt`, `_headers` and `sw.js` into
  `paths.exportPublicDir` (`common/bin/compose-hub.ts:79-137`). `writeFile` follows a symlink, so a
  worktree with no corpus would overwrite the primary's live hub pool with an empty one. ~~Swap those
  links for plain copies before the run and relink after~~ (every brand slice did; the primary's files
  kept their size and mtime). `rm` of the no-index `hub-summary.json` (`:59-62`) removes the link,
  not the target.
  **SUPERSEDED 2026-09-26 (release 10 L1, on `main` since `5c0a6ef9`): do NOT swap the compose
  outputs for copies any more.** `common/bin/_publicFile.ts` — `writePublicFile` / `copyPublicFile`
  `rm` the path first (`:19-30`), `ownDir` replaces a linked directory with an empty real one
  (`:32-39`) — and every public write of `compose-hub.ts` (`:70`, `:106-136`; `sw.js` was already
  `rm`-first at `:142`) and `compose-site.ts` (`:78-189`, `:611`, `:743-766`, `:789`, `:820`, `:912`)
  goes through them. So a worktree compose replaces each link with its own file and the primary's
  target is untouched. Proved on the integrated tree: `e2e:2origin` with `TWO_ORIGIN_REBUILD=1` and
  the links left in place (`release-10.md`, "Integration (S4 + L1 + L2), as merged"; L1's own runs
  before it). A worktree run leaves plain files where it wrote; the next per-path seed relinks them.
  *(2026-09-28, release 11 O6-B: the variable is `E2E_TWO_ORIGIN_REBUILD=1` now. Re-proved at the
  release 11 integration: `e2e:2origin` 3 passed in a worktree with the links in place, the primary's
  `export/public` byte-identical — `release-11.md`, "Integration, as merged". Never run it from the
  primary checkout, where the entries are real files.)*
- **`pnpm wt` port blocks are `git worktree list` order**, which is the admin dirs under
  `.git/worktrees/` sorted by name (`scripts/worktree.mjs:101-109`). Adding `brand-found-line` put it
  at #1 ahead of `diet-series`, which moved to #2 (reconfirms the release 9 fact above); removing
  `brand-mark` and `brand-themes` will move `diet-series` again.
- **The published accent is always a hex, and an absent accent publishes no key** — a decision, not
  an accident (2026-09-25, S3). `accentHex` (`common/lib/accent.ts:107`) maps an id to its on-dark
  value;
  `siteDescriptor.ts`, `compose-hub.ts` and `homepageSummary.ts` omit `accent` when the site sets
  none, although a reader's page then shows Signal. Third-party hubs keep their own fallback for such
  a site, as before; the official sites get explicit accents at rollout.

### Anchors this release made stale

- `:6441-6443` (Release 9 facts): "The hub defaults to the `archilyzer` theme, dark". The theme
  families are gone; the hub opens on the dark base in Signal (`export/app/layout.tsx:36-44`,
  `defaultBase: "dark", accent: DEFAULT_ACCENT`), server-rendered, and `--chart-3` is fixed per base
  (a violet), no longer the archilyzer block's green. Historical, left in place.

## Release 10 — brand S4, lows L1 + L2 (verified 2026-09-26, `main` @ `5c0a6ef9`)

Merged S4 `dcb04f61` → L2 `41ddc382` → L1 `5c0a6ef9`, then gated together on `brand/found-line`
(`release-10.md`, "Integration (S4 + L1 + L2), as merged"). Records: `brand-and-themes.md` "Slice
S4, as shipped"; `release-10.md` "Slice L2 / L1, as shipped". Every anchor below was re-read on
`5c0a6ef9`.

### S4 — Archilyzer Media

- **`renderSvgPng(svg, {width, height})` renders ANY SVG to a PNG** (`common/lib/brandIcons.ts:31-42`:
  satori lays out one `<img>` of the SVG as a data URI, resvg rasterises it). `renderIconPng`
  (`:44-50`) is now a call to it, and its bytes did not change (the nine icon PNGs checked, S4).
  It runs under tsx, so a CLI renders brand PNGs with no `rsvg-convert` (`common/bin/brand-media.ts`).
- **The Archilyzer Media lockup's letters are outlines, not text** (`mediaLockupSvg`,
  `common/lib/brandMedia.ts:232`), so drawing it needs no font anywhere (rsvg, satori, ImageMagick).
  The outlines are the generated `common/lib/brandMediaGlyphs.ts` (do-not-edit header;
  `common/bin/gen-media-glyphs.py`, a fontTools instancer at wdth 118, reading the Archivo umtool
  vendors). `MEDIA_GLYPH_SOURCE` (`:28-33`) records the font's sha256 and **the fontTools that made
  it, `4.65.0`**. The parity test (`brandMedia.test.ts:147-165`) diffs the file against a fresh
  `--stdout` run, and SKIPS, saying why, without python3 + fontTools or under another fontTools
  version (another version may round the instancer differently; that is not a stale file). It ran,
  not skipped, on this machine.
- **The spec's 5.334 em wordmark width is unkerned.** Archivo's GPOS kerns `rc` −14 and `ze` −20
  units, which gives 5.300 em. `mediaLockupGeometry` (`brandMedia.ts:125`) keeps the spec's width
  and spreads the difference as one adjustment per gap (the canvas's `textLength` +
  `lengthAdjust="spacing"`); MEDIA at `MEDIA_RATIO` 1.035 (`:72`) then gets 0.3002 em tracking.
- **`FONTCONFIG_FILE` is set only on the brand preset's own `magick` / `rsvg-convert` children**,
  never process-wide: `childOpts(render, opts)` (`umtool/report-to-video/brand.mjs:161-164`) returns
  `opts` itself when the manifest has no `render.brand`, else the same with
  `FONTCONFIG_FILE = fonts/fonts.conf` (`:44`). Every such call site passes through it
  (`brand-cards.mjs:51,63,174,211,293`; `render-cards.mjs:241,248,308,318`). ffmpeg's `drawtext`
  takes the vendored face as a `fontfile=` path (`MONO_FONT_FILE`, `:45`), which is why the one
  static Plex Mono is vendored. The fonts (`umtool/report-to-video/fonts/`, OFL, unmodified: Plex
  carries a Reserved Font Name) are NOT installed system-wide.
- **`render.brand` is opt-in, and no brand means the same object back.** `resolveBrandRender`
  (`brand.mjs:97`), `brandManifest` (`:122`), `childOpts` and `brandFaces` each return their input
  itself when there is no `render.brand`. `brandManifest` is called at the END of `selectVariant`
  (`build-video.mjs:155`), the one door the build, `verify-build.mjs:30`, `compose-chrome.mjs:539`
  and umtool's export go through, and by `render-cards.mjs:1532`. **Under a brand it appends an end
  card** (`{type:"card", id:"end", style:"end", hideRail:true, chapter:"End"}`, 20 s by default,
  `END_CARD_DEFAULT_SECONDS`, `:48`), unless the timeline has its own `style:"end"` card or
  `render.endCard` is `false` / `null` (`endCardConfig`, `:83`; `null` is off so resolving twice keeps
  it off). A timeline entry already named `end` is an error. umtool's project page lists the raw
  timeline, so the appended card is built and chaptered but not listed there.
- **Byte identity of a report-to-video render: ImageMagick's PNG date chunks are the only noise.**
  ImageMagick 7 stamps the wall clock into three `tEXt` chunks (`date:create`, `date:modify`,
  `date:timestamp`) of every PNG it writes and ignores `SOURCE_DATE_EPOCH`, so the UNCHANGED code
  run twice differs in exactly those chunks (S4's control: 334 files, 201 raw-identical, 133
  date-chunk-only, 0 different). Compare PNGs with those chunks and any `tIME` dropped and every
  other byte (IHDR, IDAT) kept; x264 mp4s here are raw-identical run to run. The method is S4's
  `$T/s4-idiff.mjs` (job scratch, not in the repo); rewrite it from this paragraph if needed.
- **umtool's new-project form offers the brand from data**: `BRAND_CHOICES` in
  `umtool/report-to-video/brand-ids.mjs` (no imports: the registry is read by client components),
  declared on the report-video kind (`umtool/lib/projects/kinds.mjs:83`), rendered by
  `components/NewProjectMenu.tsx:155-170`; `umtool new --brand archilyzer-media`. The server page
  passes the registry to the client form, so the served `/` HTML carries the choice's label — a
  curl check tells whether a running umtool has the build.

### L1 — hub lows

- **A member's subs manifest: 404 = empty, one retry, never fails the archive**
  (`common/components/SearchDataContext.tsx:343-378`, the rule at `:415-425`). A 404
  (`ArchiveHttpError` status 404) resolves at once to an empty manifest, one request. Any other error
  (network, 5xx, or a 404 served WITHOUT CORS — `serve` on a self-hosted archive does that, and the
  browser reports it as a network error) is retried once (`retry: 1`) and then counts as SETTLED:
  the archive is `ready`, its videos are searched, only its live chat is missing, and nothing says
  so (a new low). Official members send CORS on their 404s (checked live on
  `https://jeralyzer.pages.dev/subs/<missing>.json`).
  **AMENDED 2026-09-28 (release 11 O1; `release-11.md`, "Slice O1, as shipped"): the rule keys on
  `errorUpdateCount`, and the low is closed.** "Has errored" is `subs.data === undefined &&
  subs.errorUpdateCount > 0` (`SearchDataContext.tsx:461`), not `isError`. TanStack (query-core
  5.100.5, `fetchState`) puts an errored query with no data back to `pending` / `error: null` on
  refetch but keeps the count, and the count moves only on the final `error` dispatch (after
  `retry: 1`). Settled is `data !== undefined || (errored && (progressive || !isFetching))`
  (`:462-464`): the progressive front page stays ready through a refetch, while `/ask` waits for one.
  The count survives in the shared query client into `/ask`'s own mount (`retryOnMount`), a scope
  toggle off→on, or a whole-archive Retry. A ready archive whose subs errored carries
  `liveChatMissing: {retrying, error?}` (`:477`). Its scope chip shows `LIVE_CHAT_MISSING`
  (`export/app/ask/hubScopeCopy.ts:76`; shipped as written, ruled 2026-09-28) in `data-testid="hub-scope-live-chat"`, with a Retry
  (`Retry live chat from <title>`, `HubScope.tsx:106-115`). The Retry calls
  `federation.retryLiveChat(origin)`, which refetches `["subs-manifest", origin]` exactly (`:799-802`).
  `resetQueries` would zero the count; nothing in `common/` or `export/` calls it, and `gcTime` is
  Infinity.
- **An empty scope is never ready unless the provider is `progressive`**
  (`SearchDataContext.tsx:456-466`: `allSettled = (progressive || scoped.length > 0) && …`).
  `MultiSiteDataProvider` has two users: the hub's front page (`HubHome.tsx:40`, `progressive`:
  settles on an empty scope, results read "No videos match", the chips say why) and `/ask`
  (`AskHub.tsx:44`, not progressive: with every chip off the composer stays disabled and shows
  `NO_ARCHIVES_IN_SCOPE`, `export/app/ask/hubScopeCopy.ts:64` (anchor as of `e1ef1923`), `data-testid="ask-blocked"`,
  `role="status"`; the [bracketed] words render as a link to `/`). The same rule closes the instant
  before the hub's list arrives. A hub with zero archives therefore reads "Loading transcripts…"
  forever on `/ask` (a new low). Both surfaces take their list from `useFederatedSites()`
  (`export/app/components/hub/useHubSites.ts:49`), so an archive off on the front page is not fetched
  on `/ask`.
  **AMENDED 2026-09-28 (release 11 O1): the zero-archive low is closed, and `/ask` waits for the
  hub's list.**
  - `siteRegistry.ts` has `builtinsLoaded` (`:76`; `getBuiltinsLoaded` `:106`; `useRegistry()` returns
    it). `loadBuiltins` (`:195`, exported) sets it once `/hub-sites.json` has answered in any way — a
    list, `[]`, a 404, a 500, a network error or bad JSON — in the same `emit` that adds the
    built-ins. It is still never retried.
  - `useHubSites().listed = builtinsLoaded && summary settled` (`useHubSites.ts:36`) is passed
    through `useFederatedSites` to `MultiSiteDataProvider`'s `listed` prop (default `true`,
    `SearchDataContext.tsx:310`), where `allSettled = listed && …` (`:527`). `federation.listed`
    carries it. Only `AskHub` passes it (`AskHub.tsx:48`); the progressive front page is unchanged.
  - Once `listed`, `AskChat` (`:40`) blocks the composer with `NO_ARCHIVES_ON_HUB` (an empty list) or
    `NO_ARCHIVES_IN_SCOPE` (every chip off). Before `listed`, it reads "Loading transcripts…".
  - `AskScope` (`AskHub.tsx:49`) renders `ASK_SCOPE_LINE(inScope, total)` in
    `data-testid="ask-scope"` once `listed` with at least one archive in scope. `null` hides it.
  - `NO_ARCHIVES_ON_HUB`, `LIVE_CHAT_MISSING` and `ASK_SCOPE_LINE` (`hubScopeCopy.ts:70/76/82` as of `e1ef1923`) are
    DRAFTs awaiting the operator's ruling. `LinkedCopy` renders a line's one [bracketed] link to `/`.
  - **RULED 2026-09-28 (O1c): the four lines ship as written, and the [bracket] link is gone.** Each
    line is `` copy`…${link("…")}…` `` (a `Copy` `{before, link?, after, text}`). `copyWithLink`,
    `copyText` and the regex are deleted. See "The hub (O1, O2b)" below.
- **The official instances' order is the homepage's key and tiebreak.** The homepage sorts its
  public sites by `transcribed.total` descending, then `siteTitle.localeCompare`
  (`common/lib/homepageSummary.ts:437-441`); `hub-summary.json` keeps that order, and
  `officialInstances(members, summary)` (`common/lib/hubSummary.ts:190-214`) sorts the hub's members
  by their index in `summary.sites` (tiebreak: the `hub-sites.json` order), then appends any member
  the summary does not name. Colour: the site's accent, else the summary's, else
  `seriesColor(index in the summary)` — the homepage card's colour; an unnamed member takes
  `seriesColor(listed + k)`, so it never shares a named one's. Since release 10's accent slice
  it goes through `siteColor` (`common/lib/siteColor.ts`): a NAMED accent is
  `var(--swatch-<id>)` (per base) from the summary's `accentId`, used only when `hub-sites.json`'s
  hex (on-dark only) is absent or equal to the summary's; the homepage's `ArchiveCards` use the
  same helper. A CUSTOM hex is fitted per base (release 11, slice O2): `perBaseColor(resolveAccent(hex))`,
  one `rgb(calc(…))` over tokens.css's one-hot `--base-light|sepia|dark`. That value is CSS ONLY —
  never parse or compare it as a hex; `perBaseColor` throws on anything but a `#rrggbb` per base, and a
  fourth base must add its own flag to tokens.css (`themeTokens.test` holds one 1 per base over
  `BASE_GROUND_IDS`). A visitor-ADDED hub archive's published hex goes through the same fit
  (`fittedHex`, in `useHubSites`; release 11 O2b), and a non-hex accent is dropped. *(2026-09-28
  integration: `fittedHex` is `perBaseColor`'s ONLY production caller, `siteColor.ts:124`; a new
  caller goes through `fittedHex`, never `perBaseColor` directly.)* With no accent the
  fallback is the site's CHART colour, `siteChartColors(sites)`: the `--chart-N` of its accent's hue
  family (blue 1, green 2, violet 3, brass 4, sakura 5, vermilion 6 — `--chart-6` is a rust since
  release 11), else `seriesColor(i)` when free (the first SIX are `var(--chart-1..6)`), else the
  lowest free slot — never two sites in one colour, and any six wear the six validated slots. The growth
  chart, its legend and `/stats` (`SiteGrid`, `homepageChartData`, the By-site leaderboard) wear
  it (release 14 slice CF: the growth chart draws two or more sites each under 5 % of its total as
  ONE Other band on top, in its own `--chart-other` (tokens.css, Light `#3e545c`, Dark `#62625c`;
  not in `REQUIRED_TOKENS`); `homepage/app/lib/growthGaps.ts` `growthLayers` /
  `layerColors`, which run `siteChartColors` over EVERY site, so a kept site keeps its slot); the
  accents themselves fail the dataviz validator as a chart palette (no five with Brass and Blue
  pass). `useHubSites` lists the official
  instances only once `/hub-summary.json` has SETTLED (found, missing or unreadable;
  `useHubSummary.ts:45`, `networkMode: "always"`), so they never reorder a moment later. The order
  is applied in the browser: `hub-sites.json` on disk is unchanged.

### L2 — runner lows

- **YouTube's soft block is `isSoftBlock`, `/isn['’]?t available,? try again later/i`**
  (`common/lib/availability.ts:179-181`), checked FIRST by `parseUnavailableFromStderr` (→ `error`,
  `:189`) and `classifyDownloadFailure` (→ `rate_limit`, `:271`, even over a per-video class the
  caller already holds). Its consumers are the existing `rate_limit` paths: the manual download batch
  (cooldown + abort), the auto runner (`common/jobs/unitOutcome.ts:63-69`: platform backoff, the
  video deferred), `fetchWindowManaged.ts:246-250`, the metadata scan (`metadataScan.ts:492-500`,
  block kind `"soft-block"`, which changes only the log wording; the one cookie retry is kept), a
  metadata prefetch (`downloadOneManaged.ts:722-745`: a `rate_limit` prefetch ends the video with
  no attempt 1), and the availability check (`checkAvailability.ts:~300`: the first `rate_limit`
  probe sets `blocked`, the rest are skipped, one `recordDownloadBackoff`, `:337`). "Try again
  later" is what marks it: a bare "Video unavailable", "…removed by the uploader", a terminated
  account, a ToS removal, Rumble's `HTTP Error 410: Gone` and "This content isn't available." with
  no retry advice stay `deleted` / per_video.
- **`verifyBeforeClean`: a tier C suspect the check did not probe is `unverified`**
  (`common/controller/verifyBeforeClean.ts:186-211`; `probedIds` from `checkAvailability.ts:92`).
  Two ways to be unprobed: the check was blocked before it, or it has no `webpage_url`. It is never
  judged on its old `availability.json`, which could say `public` and clear an irreversible audio
  delete. It is skipped with no marker and retried next sweep.
- **The boot pass waits at most `STORAGE_PASS_WAIT_MS` = 60 s for the storage pass**
  (`common/jobs/bootQueuedJobs.ts:128`; `waitForStoragePass` `:130-169` races a DERIVED promise, so
  the storage pass is never cancelled and a throw counts as finished; `settleAfterStoragePass`
  `:173`, called from `editor/instrumentation.ts:138`). Timeout line: `[boot] storage pass still
  running after 60 s; settling queued jobs without it (…)`, then `[boot] storage pass finished N s
  after …` when it ends.
- **A hung mount still holds the re-queues behind it.** After the timeout, a job re-queued for a
  channel on an UNMOUNTED drive is refused at once (the media guard's `stat` gets ENOENT). On a HUNG
  mount the guard's own `stat` (`common/lib/channelMedia.ts`) hangs on the same syscall, and since
  re-queues run one at a time, every re-queue after it stays `queued` until the mount answers.
  Cancels all run first. Left, not fixed (`bootQueuedJobs.ts:113-125`).

## `fetch_clip` — the one MCP tool that causes a write, and the editor does it (verified 2026-09-26)

- `mcp/src/fetchClip.ts` is HTTP only (`env`, `fetch`, `sleep`, `now` injected); the MCP process
  writes nothing. It POSTs `/api/media/fetch-window` with `Authorization: Bearer $WORKER_TOKEN`,
  `requestedBy: "mcp"`, `reason` (≤ 400, required), `manifest` = the optional `report`; then polls
  `GET /api/media/fetch-window/<jobId>` every 1 s until `wait_seconds` (default 90, max 300) and
  returns `queued` + the job id (not an error) to resume with `job`. Every request has a 15 s
  `AbortSignal.timeout`; a poll network error keeps the job id in its text. When the client sends a
  `progressToken`, one `notifications/progress` per poll keeps a reset-on-progress client alive
  (the client SDK's default request timeout is 60 s, `DEFAULT_REQUEST_TIMEOUT_MSEC`).
- **Rumble:** the cited id is the EMBED id (the record's `id`); the editor's dir is the URL slug.
  `server.ts` maps through `findVideo(source, video, channel)` → `extractVideoId(record.webpageUrl)`
  and sends that as `videoId` (+ `webpageUrl` in window mode). Not found in `source` → passed as-is
  with a `note:` prefix. Live: `vxe1ae` → `data/v1007ay/clips/…`, and 80 of 8,051 sampled
  `the-quartering-rumble` dirs follow the slug rule.
- **`full: true`** sends `{channelSlug, videoId, full: true, …}` with no from/to/pad/webpageUrl;
  the editor's `fetchFullSourceAction` uses the saved-video store (`transcripts/saved-videos/<slug>/
  <id>/source-media.<ext>`, pointer `data/<id>/saved-video.json` with `keepReason: "override"` and
  `origin`), job kind `redownload-archive`, and takes NO URL (404 when the video has neither
  metadata nor a playlist entry). It WAS a silent no-op on a youtube-handling video that already had
  a transcript (the keep-source override reached only transcribe handling or the no-captions
  fallback) — **fixed by release 10 slice N**: `archiveSourceVideo` and `persistKept` pass
  `forceMedia: true`, so the no-subs fallback (attempt 3, `downloadOneManaged.ts` `forced` /
  `keepTranscript`) runs whenever the subtitle pass succeeded; with a transcript on disk it adds
  `--no-write-subs --no-write-auto-subs` after the channel's args and finalizes persist-only
  (`finalizeAppExtraction` `extractAudio: false`: no `audio.<fmt>`, no whisper, no short-audio
  probe, `fellBackToTranscribe` unset). The primary subtitle pass still runs as on any re-download,
  and yt-dlp re-writes an existing subtitle file by default (`YoutubeDL.existing_file`,
  `default_overwrite=True`, with `overwrites` popped when unset — verified in the installed
  `yt-dlp-patched` 2026.08.19), so a `transcript.<lang>.vtt` gets a new mtime; a whisper
  `transcript.json` is untouched. It rewrites `metadata.info.json` (every managed download's
  prefetch does); since slice N each rewrite that changes the bytes appends to
  `metadata.history.json` (`common/lib/metadataHistory.ts`). The window path never writes metadata.
  **A forced pass that FAILS over a transcript** (release 11 slice O3) keeps the download's status
  (the subtitle pass's `ok`) and records only the failed n: 3 attempt; `archiveSourceVideo` reads
  it through `sourceFetchFailure` and throws, so the job ends `failed` with yt-dlp's line in the
  poll's `error` tail — it used to end `done` with no file ("finished but named no file").
  Neither path dedupes a running job: a repeated request while one runs queues a second fetch, which
  is why every text says "resume with job".
- The editor must already HAVE the channel (404 `Channel "<slug>" not found` otherwise); a
  public-only setup gets the "no editor configured" error naming both env vars, and the README's
  `yt-dlp --download-sections` is the no-editor fallback only.

### O3 — runner lows (release 11, 2026-09-28)

- **An `error` probe never confirms a maybe-missing video** (`resolveMaybeMissingState`,
  `common/lib/availability-server.ts:156-170`, `:164`). `stateFromAvailability` folds `error` (a
  403, a network failure, the bot check, a blocked run's one rate-limited probe) into `available`
  because it is no evidence the video is gone; it is no evidence it is there either, so a probe
  after the scan that came back `error` now leaves it `maybe_missing`. `needs_auth` (an age gate)
  after the scan still confirms. The ONE caller is `buildIndex.ts:1180` (the published `state` on a
  site's summaries pages, and the `videoState` sub-DB behind the status chart); the clean gate reads
  `resolveEffectiveAvailability`, which the fix does not touch. `maybeMissingBuild.test.ts` pins it
  through the real `buildIndex`. The shared transcript pages carry no `state`; the summaries (and
  subs) pages do.
- **The five real videos it moved (read-only count, 2026-09-28)** were all Rumble probes that got
  `HTTP Error 410: Gone` on 2026-09-25 and were stored as `error`, just before `6d5cdbc3` taught
  `parseUnavailableFromStderr` that 410 is `deleted`: `rekietalaw-rumble/v7e07us` and
  `the-quartering-rumble/v4vriou v4x5o1l v4yqask v501kfc`. A "Full-check unexpected" on those two
  channels would settle them `deleted`.
- **`sourceFetchFailure(record)`** (`common/ytdlp/downloadOneManaged.ts`) is how a caller that
  asked for the SOURCE tells whether it got it. When the last attempt is the `no-subs-fallback`
  media pass, ITS exit code alone answers (a fallback that persisted the container and whose inline
  whisper then failed ends `failed`, and the source is there — review low 1); otherwise the status
  (`failed`, `failed-corrupt-source`). Read by `archiveSourceVideo` (throws) and `persistKept`
  (counts it `failed`, not `persisted`). A failed
  `keepTranscript` pass (`:1503`) leaves the status alone and logs `forceMedia: the source download
  failed (yt-dlp exit N); the transcript on disk is untouched and the download stays <status>.`,
  naming any `source-media.*.part` it leaves (left on purpose: a retry resumes it).
- **`cutReleases` always sets `untouched`** (`common/controller/cutRelease.ts`, `nothingWritten`
  `:311`): true = no changelog was written (every refusal); false once any was, including a result
  with **`written: true`** — a cut whose file was written and whose commit then failed (`:253`).
  The type keeps it optional only for hand-built outcomes (`common/bin/_cli.test.ts`).
  `describeCutFailure(outcome, target)` (`:415`) is the ops route's 400 `error`: the failure,
  `<workspace>: `-prefixed for `all`, then `Before it, editor was already cut (## [x] - date,
  committed <sha8>).` The route revalidates whenever `untouched !== true`.

## Release 11 — slices O1–O6 (verified 2026-09-28, `main` @ `eb28a341`)

Merged overnight, gated together on `eb28a341` (`release-11.md`, "Integration, as merged"), NOT rolled
out. O3's facts are the section just above ("O3 — runner lows"). Anchors are at `eb28a341`.

### The CLI's last subcommands, and one short form (O6)

- **`pnpm archilyzer <command>`** is a root script (`package.json`: `pnpm --filter
  yt-dlp-transcript-common exec tsx bin/archilyzer.ts`). pnpm prints its `$ …` line on stderr, so
  `-- pnpm -C "$PWD" archilyzer mcp` is a clean MCP registration (stdout carries only the protocol).
  - *Amended 2026-09-28 (release 13, slice W2 fix round, W2 review S1): true on pnpm 11 only.*
    `pnpm archilyzer` is a `pnpm run`, and **pnpm 9 and 10 print their script banner (a blank line,
    `> yt-dlp-transcript-browser-monorepo@0.1.0 archilyzer <dir>`, `> <command>`, a blank line) to
    STDOUT** before the server starts — ahead of the JSON-RPC answer. pnpm 11 prints `$ <command>`
    to stderr. `pnpm exec` prints no banner on any of them. **Register it as
    `-- pnpm --silent -C "$PWD" archilyzer mcp`** (the long spelling: `claude mcp add` has its own
    `-s`); measured with an initialize request against an empty `--local` dir, stdout is exactly one
    line, the answer, on 9.15.4, 10.18.0 and 11.26.0 (`--silent` also drops pnpm 11's stderr `$`
    line; the server's own banner stays on stderr). 9.15.4 is what the Dockerfiles install, and
    `package.json` pins no `packageManager`. Separately, pnpm 11 may install before a `run` or an
    `exec` in a checkout whose install is missing or stale, and prints that to stdout whatever the
    flags (both forms). Every doc example carries `--silent` since this amendment.
- **`archilyzer doctor [--json]`** (`common/bin/doctor.ts`, row `archilyzer.ts:280`) is STRICTLY
  read-only: it stats the LMDB index and never opens it, never mkdirs, never writes settings, and
  calls a port "in use" when a TCP connect succeeds (it never binds). The one process-state change
  is a `chdir` around umtool's tool table, put back at once. A **FAIL (exit 1)** is only something
  the machine is configured to do and cannot (`:14-19`): settings that do not parse or are not a JSON
  object, an enabled worker's engine or model missing BESIDE a corpus (`:216`), a required binary
  missing (`:239`), node below next's `>=20.9.0` (`:87`), no `node_modules/.pnpm` (`:96`). A clone
  with no corpus gets warnings, never a fail. It reads the port block through `scripts/worktree.mjs
  ports` over `lib/ports.mjs` (`:30`, `:262`), and umtool's table by a runtime import of
  `umtool/lib/tools.mjs` (common does not depend on umtool).
- **`archilyzer run <operation> <channel> [ids…] [--lane local|remote]`** (`common/bin/run-operation.ts`,
  row `archilyzer.ts:197`) calls `runOperationChannelJob`, the body the editor's buttons and lane
  runners call — a real `backfill-channel` / `digest-channel-*` job with a record and log under
  `transcripts/.jobs/`. It runs the four registry operations (diarization, attribution-diarized,
  attribution-text, digest) and REFUSES the `external` ones with a sentence read off the descriptor
  (sync, metadata-scan, download: the paced per-platform queue lives in the editor; transcription:
  the worker pool). Also refused: an operation switched off, a paused lane (the batch would wait for
  a resume only the editor can give), `--lane` off digest, ids none of which is on disk. Exit
  (`:31-34`): 0 done, 1 failed or refused, 2 usage (unknown operation or channel, a stray flag), 130
  cancelled. **It does not see the editor's lanes** (`:26-29`): beside the editor's lane on the same
  channel it does the same videos twice (atomic writes: wasted work, not damage), and the backfill
  lane's yield-to-transcription reads THIS process's (zero) transcription activity.
- **The digest channel job carries `ids`** (as the backfill job did): `runOperationChannelJob`
  passes them to both runners and the editor's digest replay forwards them, so a replayed scoped run
  cannot widen to the channel. **An editor built before `5da3e9e1` (the live :3001 until its restart)
  replays an ids-scoped `archilyzer run digest` job over the WHOLE channel** — restart before
  retrying one. No spec replays a digest job; the forwarding is type-checked only.
- **`archilyzer mcp [args…]`** (`common/bin/mcp.ts:22`) is a CHILD process, not an import: mcp's own
  tsx, cwd `mcp/`, env passed through, nothing printed on stdout.
- **Every `common/bin/*.ts` is a subcommand**, and `_cli.test.ts` fails when a bin has no row. Rows
  that parse their own argv are `passthrough: true` (matched on their leading words; everything after
  is handed on verbatim, `_cli.ts:159-170`); those that must run as a child go through `script(…)`
  (`archilyzer.ts:305-313`) → `_spawnBin.ts` `runBinScript` (with a heap cap where the old script had
  one, e.g. `duplicates`' 8 GB). `archilyzer transcribe` / `transform.ts` were deleted (O6 review Q2).
- **The package scripts the publish pipeline runs by NAME are kept and call the CLI**: export's
  `build:index|stats|templates|archives`, `compose:site|hub`, homepage's `build:index` / `compose`.
  Export's `detect:duplicates` is gone (`archilyzer duplicates`). Root `build:index` and `sync:tick`
  are kept: `sync:tick` is the documented cron line. **`homepage`'s `build` still has a `prebuild` that
  runs `build:index` over the corpus** — the integration gate builds it with `pnpm --filter homepage
  exec next build`, never `run build`.
- **`common/lib/toolProbe.mjs`** is umtool's `probeOne` lifted out (plain ESM, `probeTool` `:48`);
  `umtool/lib/tools.mjs` keeps its table and calls it, and doctor shares it.

### Ports and environment variables are declared once (O6)

- **`common/lib/ports.mjs`** is the port table: `PORTS` (`:34`, name → `{base, what}`), `PORT_BASES`
  (`:54`), `OFFSET_STEP = 100` (`:59`), `portsForOffset(offset)` (`:67`), `portFor(name, env)` (`:86`;
  the env wins, else the base; an unknown name throws). `scripts/worktree.mjs:13`, `sync-tick.ts:19`,
  doctor, every playwright config and the e2e helpers read it (since checkpoint B, `baseUrl.ts`, the
  two export specs, the ollama stub, the umtool editor stub and the 2origin spec too). It gained the
  three e2e ports worktree.mjs never offset: `HUB_PORT` 3041, `ORIGIN_B_PORT` 4610, `HUB_A_PORT` 4611.
  **Two places cannot import it** — a package.json script's `${NAME:-N}` and queue-lock's `--ports
  NAME:N` lists — and `ports.test.ts:93` reads them as text and fails on a drift.
- **`common/lib/envVars.ts`** lists every variable the apps' code reads, by audience (`:33`: `paths`
  = exactly what `getPaths()` reads, `runtime`, `port` = generated from ports.mjs, `internal` = set
  by the pipeline, `docker` = the `ARCHILYZER_*` set, `test`). **`ENVIRONMENT.md` is generated** from it
  (`archilyzer docs env [--check]`, `common/bin/env-docs.ts`). `envVars.test.ts` holds it both ways:
  every `process.env.X` / `env.X` read under common/, editor/, export/, homepage/, mcp/src and scripts/
  is declared (`:84`; the scan knows `env(Int|Float|Bool)Override` and `parseIntArg`); every entry is
  still named outside the list (`:111`); every `ARCHILYZER_*` in docker/, the Dockerfiles and the
  compose files is declared (`:105`). umtool's own knobs stay in `umtool/docs` until Phase 5.
- **Every test-only variable is `E2E_`-prefixed and declared in its playwright config**
  (`envVars.test.ts:156`, `:168`; excepted: `PLAYWRIGHT_BASE_URL`, `QUEUE_LOCK_HELD`, `:154`). The
  renames (old → new): `EDITOR_TEST_ROUTES` → `E2E_TEST_ROUTES`; `AUDIO_CHECK_*_OVERRIDE` →
  `E2E_AUDIO_CHECK_*`; `AUDIO_CHECK_DEBUG_PAUSE_MS` → `E2E_AUDIO_CHECK_DEBUG_PAUSE_MS`;
  `FAKE_YTDLP_*` / `FAKE_GALLERY_DL_AUTH_FAIL` → `E2E_FAKE_*`; `FIXTURE_MAX_LIFETIME_MS`,
  `OLLAMA_STUB_MODEL`, `RACK_SHOTS`, `TWO_ORIGIN_REBUILD`, `HOMEPAGE_SUMMARY_FILE` → `E2E_…`; the
  sharded runner's `SHARDS` / `IMAGE` / `SKIP_BUILD` → `E2E_SHARDS` / `E2E_IMAGE` / `E2E_SKIP_BUILD`;
  umtool's `EDITOR_STUB_LOG`, `UMTOOL_CUT_DELAY_MS`, `UMTOOL_EXTRA_KINDS` → `E2E_…` (declared in
  `umtool/playwright.config.ts`, not envVars.ts). **Unchanged:** the queue lock and port check
  (`E2E_QUEUE`, `E2E_PORT_CHECK`, `E2E_QUEUE_TIMEOUT`, `E2E_PORT_GRACE_MS`, `E2E_QUEUE_LOCK_FILE`),
  `PLAYWRIGHT_BASE_URL`, `CI`, `E2E_MODE`, the port names, the docker `ARCHILYZER_*` set, and the two
  node-unit knobs `KEEP_TAG_PREVIEW_FIXTURE` / `CUES_TEST_DIR`. Old names survive only in `plans/`
  and released changelog text.
- **The editor's test-server env is `E2E_SERVER_ENV` in `editor/playwright.config.ts:37-44`**
  (`E2E_TEST_ROUTES=1` and the five audio-check knobs), passed as the webServer's `env`. `dev:test` /
  `start:test` no longer carry them, so **a hand-started `dev:test` has no `/api/test/*`** — a server
  reused under `E2E_PORT_CHECK=0` must be started with those values (WORKTREES.md).
- **`e2e:2origin` is run as `E2E_TWO_ORIGIN_REBUILD=1 node scripts/worktree.mjs run -- pnpm --filter
  export run e2e:2origin`**, from a WORKTREE only (never the primary: there `build:hub` would write
  the live hub files). With the variable set playwright loads the config twice, so the hub is built
  twice per run (N1, pre-existing).

### Docs (O6)

- **`PUBLISH.md` absorbed `DEPLOY_CLOUDFLARE.md` and `DEPLOY_DOCKER.md`** (both removed): what gets
  published, the editor / `pnpm ops` / CLI table (`:40-60`), Pages, previews (`## Preview deployments`
  `:89` — the "who can open a preview" note FACTS cites below now lives there), R2, the cost-abuse
  defenses, containers (`:352`), the MCP registration. README's and SETUP's env tables are pointers to
  `ENVIRONMENT.md` and `doctor`. Two released editor changelog links were retargeted to PUBLISH.md
  anchors, words unchanged (`ef84f535`).
- **The build mode is a label.** No build reads `settings.buildPipeline.mode`: Build all / Build &
  deploy all use containers whenever `docker version` answers, else the serial host build. Settings
  ("Basic (a label for now)" / "Docker (a label for now)"), the schema text, SETTINGS.md, `/sites` and
  the homepage's Docker page say so. Whether they should honour it is an open operator question.
  - *Amended 2026-09-28 (morning, follow-up O6c): ruled — dropped.* The operator: "If docker build
    mode isn't ready yet, just drop it for now rather than keep the stub." `buildPipeline.mode`,
    `BuildMode` / `isBuildMode`, the `/sites` toggle (`BuildModeToggle.tsx`,
    `buildModeAction.ts`) and the Settings select are gone. `buildPipeline` is
    `{maxParallelBuilds, dockerImage, dockerfile}`, and `sanitizeBuildPipeline` builds only those,
    so a `settings.json` that still says `"mode": "basic"` loads and loses the key on the next save
    (`settingsSchema.test.ts`, `settingsWrite.test.ts`). The container path is unchanged: Build all
    uses containers whenever `docker version` answers.

### The homepage builds and deploys from `/sites` (O4)

- Three job kinds, all through `runManagedFunction` in `editor/app/sites/lib/homepageDeployActions.ts`:
  `build-homepage` on the `build` queue (`:47-48`), `deploy-homepage` (`:69-70`) and
  `build-deploy-homepage` (`:90-91`) on `deploy`; the bodies are `buildHomepage` / `deployHomepage`,
  unchanged, and a build-deploy deploys only on exit 0. No `jobKinds.ts` entries (the hub's have none).
  > **Superseded by release 18 (2026-10-06):** `homepageDeployActions.ts` is gone; the homepage is built and deployed by the `publish-build-homepage` / `publish-deploy-homepage` stages, and the three old kinds stay in `jobKinds.ts` for archived metas only — see "The publish stages" at the end of this file.
- **Refusals before any job:** a bad preview name (`previewBranchProblem`), and for a deploy-only
  `builtHomepageProblem(homepageOutDir(paths))` (`common/lib/builtExport.ts:93`; `builtHomepageAt`
  `:106` is index.html's mtime; `homepageOutDir` `common/publish/build.ts:948`, exported so the editor
  never re-derives it, and `deployHomepage` ships exactly that directory).
- **Ops:** `/api/ops/build-homepage` `{deploy?, preview?}` (a preview without deploy is 400),
  `/api/ops/deploy-homepage` `{preview?}` answering `previewUrl`; `pnpm ops build-homepage` /
  `deploy-homepage` (`scripts/archilyzer-ops.mjs:40-41`, `:113-114`). The preview is `--json
  '{"preview":"<b>"}'`, not a flag. Both routes exist only on an editor built from this code.
- **`JobLane` under Strict Mode** (`editor/app/sites/components/JobLane.tsx:46-64`): liveness is its
  own `aliveRef`, kept by its own effect. The old launch effect gated updates on a flag its cleanup
  set, so `next dev`'s mount → cleanup → mount left a lane on "Starting…" forever while the job ran.
  Production mounts once and was unaffected.
- **No e2e builds or deploys the homepage.** The Build homepage click runs with the `build` AND
  `deploy` queues held by `/api/test/stuck-job` (never released) and is cancelled from its lane; the
  refusal tests hold both queues (`holdBuildAndDeployQueues`, `ops-api.spec`).

### The hub (O1, O2b)

- `builtinsLoaded` / `listed` / the three DRAFT lines: see "L1 — hub lows" above, AMENDED 2026-09-28.
  The DRAFT constants are `export/app/ask/hubScopeCopy.ts` `NO_ARCHIVES_IN_SCOPE` `:7` (release 10's,
  still unruled), `NO_ARCHIVES_ON_HUB` `:16`, `LIVE_CHAT_MISSING` `:24`, `ASK_SCOPE_LINE` `:33`.
  **Ruled 2026-09-28 (O1c; `release-11.md`, "Operator rulings and follow-up O1c"): the four ship as
  written, with no DRAFT markers.** The copy convention is now a tagged template in
  `export/app/ask/hubScopeCopy.ts`:
  - `` copy`words ${link("linked phrase")} words` `` returns a `Copy` `{before, link?, after, text}`.
  - Plain interpolations are text; only a `link()` value (a `CopyLink`) is the link to `/`.
  - Two links in one line throw where it is built: at module load for the constants, and
    `ASK_SCOPE_LINE` (`Copy | null`) is evaluated once at load.
  - `LinkedCopy` renders `before` + one `<Link href="/">` + `after`, and the hub specs read
    `.text` / `.link`.
  - A line with no link may be a plain string (`LIVE_CHAT_MISSING`).
  - Nothing parses brackets any more.
  - `export/app/**/*.test.ts` — 11 files, 98 tests at `e1ef1923` (3 under `ask/`, 8 under `lib/`) —
    are in no suite script: `export/package.json` has no `test` script. Run them with
    `export/node_modules/.bin/tsx --test`. All 98 passed at O1c's review (2026-09-28).
    - *Amended 2026-09-28 (release 13, slice W2):* `export/package.json` now has
      `"test": "tsx --test \"app/**/*.test.ts\""` — `pnpm --filter export test`, 11 files,
      98 tests, all passing — and it is named in the implementer gate list.
- **`normalizeSocialSvg` themes a SINGLE-colour icon only** (`common/lib/settingsSchema.ts:1373`).
  The solid colours of the root and every child outside a `<mask>` or `<clipPath>` are counted
  together (spellings folded by `paintKey` `:1304`: `#FFF`, `#ffffff`, `white`, `rgb(255,255,255)`
  are one); `none` / `transparent` / `inherit` / `url()` never count. At most one colour → every fill
  becomes `currentColor`; two or more → kept as pasted. Masks, clip paths (block and self-closing,
  self-closing matched first, `:1351`) and animation tags (`fill="freeze"` is timing, `:1352`) are
  passed over. Idempotent. **It runs on EVERY `writeSettings`** (`validatedSocialLinks`), not only
  the Settings form, so the first settings write after the :3001 restart rewrites the stored x.com
  icon; every site, the hub AND the homepage then need a rebuild. Left: a `<pattern>`'s children are
  themed; class fills in a `<style>` block and an unquoted `fill=white` are neither counted nor
  themed; strokes are never themed.
- **Hub added archives are fitted per base** (O2b): `useHubSites` maps every external archive's
  accent through `fittedHex` (`export/app/components/hub/useHubSites.ts:51`); a value that is not a
  `#rrggbb` is dropped and the card falls back to `var(--brand)`.

### Colour (O2, O2b)

- **`fittedHex` is `perBaseColor`'s ONLY production caller** (`common/lib/siteColor.ts:124`), and
  `fittedHex` is called by `siteColor` (`:130`) and `useHubSites.ts:51`. A new caller goes through
  `fittedHex`, which drops a non-hex, rather than calling `perBaseColor` — which THROWS a
  `RangeError` on anything but a `#rrggbb` per base (`:107`). The value is CSS only
  (`rgb(calc(… * var(--base-light, 1) + …))`): never parse or compare it as a hex.
- **The one-hot base flags** `--base-light|sepia|dark` are declared once per base block in
  `common/styles/tokens.css` (light `:217-219`, sepia `:319-321`, dark `:402-404`); a fourth base must add
  its own (`themeTokens.test` holds exactly one 1 per base).
- **`--chart-6` is a rust, Vermilion's family**: `#823c10` light and sepia (`tokens.css:255`, `:340`),
  `#a54a08` dark (`:424`); `--color-chart-6` in `@theme` (`:101`). `CHART_SLOTS = 6`
  (`common/lib/homepageChart.ts:22`), `seriesColor(5)` is `var(--chart-6)`, `ACCENT_CHART_SLOT.vermilion
  = 5` (`siteColor.ts:48-54`), `REQUIRED_TOKENS` is 50 (`common/components/themeConfig.ts:104`). Past
  six, `seriesColor`'s golden angle still gives hue 105 (7th) and 243 (8th, near chart-1's blue).
  **`ChartView.tsx` (export and editor charts) still cycles `(i % 5) + 1`** and never wears
  `--chart-6`. The rust sits near `--state-gone` (normal ΔE 7.2–13.1); gone is only ever labelled
  text on the homepage. **Ruled 2026-09-28: the rust is accepted near `--state-gone`, and Vermilion
  keeps slot 6** (`ACCENT_CHART_SLOT.vermilion = 5`).
- **The mark's forced-colours edge** is two classes on `BRAND_MARK_RING_CLASS`
  (`common/components/BrandMark.tsx:36-38`): `forced-colors:outline
  forced-colors:outline-[color:CanvasText]`, a 1px outline at offset 0 on every base under
  `@media (forced-colors:active)`, matching nothing outside it. Chromium keeps an svg's box-shadow in
  forced colours (its UA sheet gives `svg` `forced-color-adjust: preserve-parent-color`), so the dark
  ring stays there and the outline is painted over it. Playwright applies a forced palette with
  `page.emulateMedia({ forcedColors: "active" })`; this version's `test.use` has no `forcedColors`.

### The homepage e2e reads a synthetic summary (O2, O2b)

- `homepage/e2e/fixture-summary.ts` runs the REAL `buildHomepageSummary` over made-up recordings
  (`:67-130`; `FIXTURE_NOW` 2026-09-15 `:35`; six public sites `:43`: Brass, the pale custom hex
  `#f4c2d7` `:38`, three with no accent, Vermilion). `homepage/playwright.config.ts` writes it to
  `e2e/.e2e-summary.json` (gitignored) before the server starts and passes
  `E2E_HOMEPAGE_SUMMARY_FILE` (`:47`). **`homepage/app/lib/summary.ts:47` honours that variable only
  when `NODE_ENV !== "production"`**, so a production build never reads a test file.
- Nothing is read from `homepage/public` or the primary: a fresh clone runs every homepage spec with
  0 skipped (31 at the integration gate). `e2e/fixture-accents.ts` is gone.
- **`no-data.spec.ts` renames the fixture aside** (`.e2e-summary.json.aside`, same gitignore pattern)
  and restores it in `finally`; it runs serially (`:15`). A killed run can leave the `.aside`; the
  next config start rewrites the fixture anyway.
  - *Amended 2026-09-28 (release 13, slice W2):* `mode: "serial"` orders one file's tests, not the
    files, so under `--workers=N` the other specs read the summary while it is aside. The test now
    skips itself when `test.info().config.workers > 1`, naming the run's worker count in the skip
    reason; the config's own `workers: 1` still runs it.
- **`playwright.2origin.config.ts` stages only in the runner** (release 13, slice W2): Playwright
  evaluates a config again in every worker process, after setting `TEST_WORKER_INDEX` there
  (`playwright/lib/worker/workerMain.js:60`, 1.59.1), and each evaluation re-ran
  `stageTwoOrigins()` — which `rmSync`s and rewrites `.2origin/originB` under the running `serve`.
  The call is now `if (!process.env.TEST_WORKER_INDEX) stageTwoOrigins();`. (UI mode's
  out-of-process loader would still evaluate it without that variable; the CLI loads test files
  in-process.)

### report-to-video measures the brand's face per character (O5)

- **Under `render.brand: "archilyzer-media"` the rail, ledger, scroll and chart SVG text are IBM Plex
  Sans, fitted by the face's own advances**, not an average. `svg-faces.mjs`: `FIRA_SANS`
  (`{family, em: 0.5}`, `:55`), `IBM_PLEX_SANS` (a measured face, `:71`), `textWidth(text, size, face,
  {weight, ls})` (`:84`), `FALLBACK_EM = 1.3` for a character Plex does not map (`:52`; anchors as
  of release 13 W2, which lengthened the header comment by eleven lines). **1.3 em
  covers emoji, CJK and the common scripts, but not every fallback glyph** (O5 review L2, measured
  through the branded conf: `⟹` 1.42 em, `﷽` 1.93, `Ⅷ` 1.31) — a label made mostly of long arrows
  would overrun by ~9 %; no real label has one. The table is `face-metrics.mjs`, GENERATED by `fonts/gen-face-metrics.py` (fontTools
  4.65.0) from the vendored `IBMPlexSans[wdth,wght].ttf` at wght 400/700, wdth 100 (891 characters,
  the font's sha256 in its header) — regenerate it, never edit it.
- `render-cards.mjs` `fit(text, size, maxPx, face = FIRA_SANS, run)` (`:428`) and `wrapPx(…, face)`
  (`:1010`): an average face (Fira) runs the old code path verbatim; a measured face keeps the
  longest prefix whose width — ellipsis, weight and letter-spacing included — fits. **Kerning is
  ignored, and the plain sum is NOT conservative in general** (O5 review L1; *amended 2026-09-28,
  release 13 slice W2:* `svg-faces.mjs:32-47`, the `FALLBACK_EM` doc comment and the README's "Why a
  table, not an average" now say so, and say 1.3 em is not a bound for every glyph — comments and
  prose only, no code changed, so no render was needed): IBM Plex Sans has POSITIVE kerning pairs (412 at wght 400, 348 at 700,
  up to +55 units: `r”`, `y’`, `f”`, `TT`, `AA`; bold `(j` +70), so `T`×60 at 13 px renders 464 px
  of ink against a table sum of 446.2. Over the 144 real strings and their capitals the worst net
  kerning is +0.50 px, so it is sub-pixel today. The fix, if it ever matters, is positive-only kern
  pairs emitted by `gen-face-metrics.py` and added in `textWidth` (branded path only). `svgFaceOf(render)`
  (`:376`) = `brandSvgFace(render)` (`brand.mjs:174`, null without a brand) `?? FIRA_SANS`.
- **Why a table:** an average cannot promise no overrun. Fira's own 0.50 overruns the scroll's bold,
  letter-spaced column head in 40 of 87 real strings; uppercase overruns in both faces at every
  average 0.50–0.55. **The unbranded Fira path can still overrun** given long enough text; the
  byte-identity rule forbids changing it (a fix would be a Fira table pinned to one Fira build).
- **`rasterize()` hands rsvg-convert `childOpts(render, …)`** (`render-cards.mjs:408`): without it a
  branded SVG found no Plex (not a system font) and silently fell back to another sans.
- **IBM Plex Mono Bold is vendored** (`fonts/IBMPlexMono-Bold.ttf`, unmodified, google/fonts
  `0b58fb37`, sha256 `ac27abd6…`); `resolveBrandRender` sets `render.fontBold` to it
  (`brand.mjs:50`, `:117`), so compose-chrome's HyperFrames band sets its bold in the brand's mono.
- **An unbranded render is byte-identical** (334 files: 201 raw-identical, 133 identical but for
  ImageMagick's `tEXt date:*` chunks).

### Runner lows (O3) — see "O3 — runner lows" above

- The maybe-missing change is a SEMANTICS change for a published badge: an `error` probe after the
  scan keeps a video `maybe_missing` (`availability-server.ts:156`, one caller `buildIndex.ts:1180`).
  Five real videos move to "Missing?" at the next index build (jeralyzer 4, rekietalyzer 1).
- `sourceFetchFailure` (`common/ytdlp/downloadOneManaged.ts:534`) is how a caller that asked for the
  source tells whether it got it; `archiveSourceVideo` throws on it and `persistKept` counts it failed.

### What the integration gate found (2026-09-28, `eb28a341`)

- **`transcript-source.spec.ts:76` is intermittent in the full editor suite** (first seen here: 652
  passed / 1 failed of 665, 39.5 min; alone `--repeat-each=3` 9/9). The Diagnostics stage read a
  snapshot with no `nonStandardVtt` id, so "Channel health" said "All clear." and the
  `Non-standard transcript VTT name (1)` heading never came. The likeliest mechanism is
  `generateReport` returning early whenever `snapshot.json` already exists (`editor/e2e/helpers.ts:193`):
  a snapshot written between the test's `resetData` and its VTT swap (a debounced flush left by
  the previous test, `:42`, which switches the primary transcript) is stale and never regenerated.
  The fixture ships no `snapshot.json`. The fix would be to `rm` the snapshot after the swap, or to
  always click Refresh report. Nothing in release 11 touches that path.
- **The umtool pair `mix.spec.ts:166` / `:201` still fails in every full umtool run** (175 / 2 / 45
  here, as at O5 and O6-B; alone ×3: 36/36) — the order-dependent clip window above.
- **A worktree's homepage e2e is self-sufficient**: 31 passed, 0 skipped, with `homepage/public`
  holding only its tracked `_headers`.
- **`export/public` in a worktree, per run** (the links seeded from the primary; the primary
  byte-identical after every run): the export suite replaces the `sw.js` link with its own file;
  `e2e:2origin` (`compose hub`, twice) replaces `sw.js`, `hub-sites.json`, `corpus.json`, `llms.txt`,
  `robots.txt` and `_headers`. `e2e:hub` writes none. Re-seed before the next export run.

## Release 12 — the source mirror (verified 2026-09-28, `main` @ `ffdeb2cd`)

Slices Q (`4855f70b`) and R (`ffdeb2cd`): [`release-12.md`](release-12.md), the plan
[`source-mirror.md`](source-mirror.md), the operator-facing doc `PUBLISH.md` "The source mirror
(homepage)". Anchors are at `ffdeb2cd`.

### The step (`common/publish/source.ts`)

- **`publishSource`** (`:611`) → `publish` (`:647`) runs these steps in order:
  1. The git COMMON dir's `refs/heads/main`: a worktree build mirrors the primary's main. No
     repository at all (`commonDir` `:543`) says `NO_REPOSITORY` (`:510`).
  2. The operator files (`loadSourceRules` `:216`).
  3. The tools: `resolveFilterRepo` `:321` and `gitleaksIdentity` `:483`.
  4. The skip.
  5. A `--no-local --bare --single-branch --no-tags` clone into
     `mkdtemp(ARCHILYZER_SOURCE_SCRATCH/archilyzer-source-)`. The scratch root is refused inside the
     checkout or the public dir (`scratchRootProblem` `:582`).
  6. filter-repo, then `repack -a -d --max-pack-size=20m`, `prune-packed`, `pack-refs`,
     `update-server-info`.
  7. The object audit.
  8. The tree and the tarball.
  9. The allowlisted stage.
  10. The file audit.
  11. The limits: 15,000 files, 24 MiB a file.
  12. The link-safe install: the manifest removed first and written LAST.

  `buildHomepage` (`build.ts:991`) runs it between compose and `next build`, with `noRepository:
  "empty"`. So `archilyzer build homepage`, `/sites` Build homepage and `pnpm ops build-homepage`
  all do.
- **A refusal withdraws the source.**
  - Once the rules are loaded, any non-zero outcome runs `removePublishedSource` (`:520`). `--check`
    writes nothing, this included.
  - `buildHomepage` then removes `out/source` and the two download files (`withdrawBuiltSource`,
    `build.ts:1026`). `out/source/index.html`, the `/source` PAGE, goes with them.
- **The deploy key.** `homepage/.source-publish.json` sits beside `public/`, NEVER inside it (a
  published rules hash would confirm a guess at the denylist). It holds `sourceCommit`,
  `mirrorHead`, `rulesHash`, `filterRepo`, `gitleaks` and `contentDigest`:
  - `rulesHash` is `rulesHashOf(scrub lines, literals, SOURCE_STEP_VERSION)` (`:243`).
    **`SOURCE_STEP_VERSION` (`:86`, now 3) must be bumped whenever the scrub or the audit
    changes**, so an unchanged main is re-published and an old `out/` refuses to deploy.
  - `gitleaks` is the version line plus the sha256 of the binary. This machine's gitleaks prints
    `version is set by build process` for every release.
  - `contentDigest` is `sourceDigest` (`:447`): the sorted path, size and streamed sha256 of every
    published file — `source/archilyzer.git/**`, `source/tree/**`, `source/manifest.json`, the
    tarball, `snapshot.json`. It takes about 0.5 s over 2,459 files.
- **`publishedSourceProblem`** (`:985`), asked by `deployHomepage` (`build.ts:1079`) before every
  deploy, preview included:
  - no `/source` page in `out/` refuses: a refused build, or one from before release 12;
  - the page with no artefacts beside it is a `--no-source` build, and deploys;
  - otherwise it binds: a valid manifest, a complete state, `rulesHash` = today's, `mirrorHead` =
    `out`'s, main = the state's and the manifest's, the tarball's sha256, the gitleaks identity, and
    the content digest.

  A hand-written state file is the only way past it, and the file is the operator's own record.
- **The report never prints a literal or an object's bytes.**
  - A literal is `denylist line N (len L)`, `scrub line N lhs (len L)` or `built-in home rule (len
    L)`.
  - A hit is its kind, object id, the blob's path in history, the byte offset and a commit/tag
    field (`objectField`, `sourceAudit.ts:229`).
  - Every refusal message, and every path it prints, goes through `maskLiterals`
    (`sourceAudit.ts:144`).
  - A literal spanning path components (`a/b`) is invisible to the object walk, which reads tree
    entry names one at a time. The staged-path sweep catches it.
- **The operator files** are `${ARCHILYZER_CONFIG_DIR:-~/.config/archilyzer}/source-{scrub,denylist}.txt`,
  read through `getPaths()` (`sourceScrubFile`, `sourceDenylistFile`). The two readers are
  `operatorLines` (`sourceAudit.ts:72`) and `parseScrubRules` (`source.ts:161`):
  - they drop a BOM and CRLF;
  - the home dir loses a trailing `/`;
  - an empty left side refuses;
  - every literal left side is denied too — its exact bytes; a new spelling is caught only by the
    denylist.

### git-filter-repo (2.47.0, pipx `~/.local/bin`)

- **`--replace-text` has no comments.** `get_replace_text` treats a `#` line as a literal to replace
  with `***REMOVED***`. The step writes `replace.txt` without comments or blank lines.
  `--replace-message` reads the same syntax. Lines split at the LAST `==>`, then
  `regex:`/`glob:`/`literal:`.
- **`git filter-repo --version` prints a hash (`a40bce548d2c`), not `2.47.0`.**
  `commit-map`/`ref-map` under `<repo>/filter-repo/` hold the PRIVATE ids, and are deleted before
  staging. The default `--replace-refs` is `update-no-add`; the step passes `delete-no-add`.
- **A blob with a NUL in its first 8 KiB is never scrubbed** (`_tweak_blob`): a binary is audited,
  never scrubbed. Compressed content (a zip member, PNG text chunks, a PDF stream) is opaque to the
  byte search. At release 12 every such blob in history was decompressed by the reviewer: 0 hits.
- **Deterministic:** the same main, rules and filter-repo gave the same `mirrorHead` on every run
  (`20c367613f75` for main `e56101fdee5d`). Pack BYTES differ run to run, which is why the digest is
  taken per publish.

### git's dumb HTTP, and Cloudflare Pages

- **The published file set** is `HEAD`, `packed-refs`, a LOOSE `refs/heads/main`, `info/refs`,
  `objects/info/packs` and `objects/pack/pack-*.{pack,idx}`, from an allowlist: never `config`
  (the clone's origin path), `hooks/`, `description`, `logs/`, `filter-repo/`, `*.rev` (git 2.55
  writes them by default) or `*.bitmap`.
- **The loose ref is load-bearing.** git treats a directory as a repository only if it has a
  `refs/` directory, so a `file://` clone or `source audit` of the published dir fails without it.
  An empty `refs/` would not survive a deploy.
- **The `?service=git-upload-pack` probe falls back to dumb** when the server returns plain
  `info/refs`. Verified against `python3 -m http.server`. The live Pages proof is the rollout's
  preview.
- **`_headers`** (wrangler 4.88 `attachHeaders`, re-read in 4.142 by the review):
  - EVERY matching rule applies, in file order. A header a LATER rule sets again is **APPENDED**
    (`text/plain; charset=utf-8, text/html; charset=utf-8`), so an override must detach it first
    with `! Content-Type`.
  - A splat is `(?<splat>.*)` matched against the ENCODED pathname. A rule with two `*` compiles to
    duplicate group names and is dropped silently; wrangler's parser also refuses it.
  - The limits are 100 rules and 2,000 characters a line. Only the ROOT `_headers` is read.
  - `homepage/app/lib/headers.test.ts` holds a replica and pins the source-tree rules.
- **Pages answers a missing path with the NEAREST `404.html`**, walking up, with the REQUEST path's
  headers. So a tracked `404.html` in the raw tree would run as HTML on the origin, and the tree
  step refuses one (`sourceTree.ts:142`), as it refuses a tracked `index.html` or a symlink.
- **A Pages PREVIEW is a public publication, and every deployment stays reachable at
  `<hash>.<project>.pages.dev` until that deployment is DELETED.** A newer deploy does not remove
  an older one. A preview branch name is guessable (`source`, named in the mirrored plans).
- **`next dev` serves `public/` but not a directory's `index.html` at `/<dir>/`,** and ignores
  `_headers`. A static export always writes the `/source` page into `out/source/index.html`, so
  `out/source` exists in every build, `--no-source` included.

### Tailwind, tsc, eslint and docker must not read the mirror

- `/homepage/public/source` and `homepage/.source-publish.json` are gitignored, because Tailwind v4
  scans every file `.gitignore` does not exclude, and a binary pack yields "class names" that break
  the stylesheet.
- `homepage/tsconfig.json` excludes **`public` AND `out`**. `next build` copies `public/` into
  `out/`, and the SECOND build with a mirror failed its type check on
  `out/source/tree/common/jobs/registry.ts`: a duplicate `declare global var __yttJobRegistry__`.
- `homepage/eslint.config.mjs` ignores `public/source/**`, and `.dockerignore` excludes both paths.

### Measured (2026-09-28, the real repo)

- **`main` `e56101fdee5d` publishes:**
  - 1,703 commits and 21,447 objects;
  - 2,459 staged files, 69–71 MB;
  - 2 packs (about 21 and 16 MB);
  - 2,035 tree files in 412 directories;
  - a tarball of about 7.2 MB.
- **`homepage/out`:** 2,640 files, about 78 MB. The largest file is 19.99 MiB, against the step's
  24 MiB limit and Pages' 25 MiB.
- **Time:** the step adds about 19 s to `build homepage` (filter-repo about 5 s, gitleaks about 7 s).
  An unchanged main, rules, tools and files skip it. The deploy check takes 0.6–0.8 s.
- **The live :3001 editor runs its BUILT bundle.** Until it is rebuilt on a tree with release 12,
  its `/sites` Homepage jobs have no source step, no withdrawal and no deploy check.

### A path joined from `process.cwd()` is a directory of assets to Turbopack (slice Q, after rollout)

**The hazard.** In a module a Next app imports, Turbopack traces a path joined from
`process.cwd()` as a directory of assets. The same goes for a module's own `import.meta.url` or
`__dirname`.
- **How:** Turbopack evaluates these statically as paths in the project. A `path.join` /
  `path.resolve` / fs call on the result becomes an asset reference: to a file, or, when the joined
  path is a directory, to every file under it (`DirAssetReference`).
- **A worktree build will not show it.** A worktree has no `transcripts/`, so the reference is
  empty. **Test with the corpus visible.** Nor does it have umtool's e2e fixture (`.e2e-song`,
  `.next-e2e`), which is what slice UT's pattern reached (below).
- **What happened:** slice Q wrote `path.join(REPO_ROOT, "transcripts", "channels")` with
  `REPO_ROOT = findRepoRoot(process.cwd())` in `umtool/lib/paths.mjs`. The walk's fallback,
  `path.resolve(start, "..")`, evaluates to the project root.
  - In `<primary>`, `pnpm --filter umtool exec next build` walked the corpus (hundreds of GB, with
    channel `data/` symlinked to another drive). It grew until the kernel OOM-killed it: twice, at
    about 3.7 GB RSS. The live umtool was down until the fix.
  - Under a memory cap it dies at once instead: `<DirAssetReference as
    ModuleReference>::resolve_reference failed … Symlink [project]/transcripts/channels/<slug>/archive
    is invalid, it points out of the filesystem root`.
  - A worktree built it in 30 s at 0.8 GB, which is how the gate passed.
- **The opt-out is per expression, and it is not documented for path or fs calls** (corrected by
  release 15, slice UT). `path.join(/* turbopackIgnore: true */ process.cwd(), bar)` is Turbopack's
  own advice, in the text of its "Encountered unexpected file in NFT list" issue (the "whole project
  was traced" warning; the 16.2.3 native binary carries it), and Next's own server uses it, on
  the join and on the fs call around it: `next/dist/server/next-server.js:620` (16.2.3) reads
  `existsSync(/* turbopackIgnore: true */ (0, _path.join)(/* turbopackIgnore: true */ this.dir,
  'static'))`. The Next docs (`08-turbopack.md` and
  `02-guides/lazy-loading.md`, "Magic Comments") list the comment only for `import()`, `require()`,
  `require.resolve()` and `new Worker()`. It goes before the FIRST argument of each call, and it
  changes nothing at run time. Measured in slice UT, it works on a `path.join` and on an fs call.
  Per call, not per value:
  - a nested call needs its own marker (`path.dirname(/* turbopackIgnore: true */
    fileURLToPath(import.meta.url))`);
  - **an fs call on an opted-out `path.join` is NOT covered**, nested or through a variable: it
    traces the join's value. Slice UT, on umtool's clip-audio route. With 4 probe files in its dot
    directories: the join opted out and the fs calls on its value kept, 4 traced; those calls
    stubbed, 0. With the primary's fixture: one `existsSync(path.join(/* opt-out */ CACHE_DIR, …))`,
    1,704; the same with the `existsSync` opted out as well, 0; the join held in a variable and
    only `existsSync(/* opt-out */ cached)` reading it, 0. On a cwd-derived value the join is a
    known path, so the outer call traces the one file it names; the guard lets that through (its
    comment says so; the release 15 review ruled its four sites safe). Next's own
    `next-server.js:620` (above) opts out both calls.
- **A value the tracer cannot know is a dynamic part, not ignored** (corrected by release 15, slice
  UT). `process.env.*`, `os.homedir()`, a parameter and an imported binding all make patterns over
  the app's own directory (`umtool/`):
  - 66 of umtool's 68 routes trace its whole tree outside dot-directories (361 files,
    `next.config.ts` among them). Opting out every path op in `song/paths.mjs`, `lib/paths.mjs`
    and `lib/paths.ts` (`path.resolve(process.env.X ?? path.join(os.homedir(), …))` and the like)
    left 31 of the 68 routes clean; every path op in all 53 modules that have one (319 calls),
    49 (`_global-error` and `_not-found` were clean before). The rest come through fs calls
    (`lib/report/snapshots.mjs` is the first the warning names).
  - The clip-audio route's `path.join(CACHE_DIR, `${stamp}.${asMp3 ? "mp3" : "wav"}`)` (CACHE_DIR
    imported, built on the env or home directory) also took in the dot-directories: 1,704 of its
    2,167 entries were the e2e fixture (`.e2e-song`), the e2e server's build directory
    (`.next-e2e`) and `.env.local`. Hoisting the ternary into a `const` changed nothing. Without
    the ternary (`${stamp}.wav`), as a ternary of two joins, or with the name handed to a function
    from another module (the fix, `cacheFile` in `umtool/lib/paths.mjs`), it did not. The video
    route's `.mp4` join did not reach the `.mp4` inside `.e2e-song`.
  - **A pattern walk does not enter a symlinked directory**, in the root or out of it: a link at
    `umtool/.e2e-song/data/planted` to `<primary>/transcripts/channels` gave 0 entries before and
    after the fix, while the old route's walk listed the real files beside it (`data/mkvocals`);
    one to the worktree's `common/` (675 files) gave 0 on the old route. That is what the
    synthetic-HOME build showed, not that the env and home directory are unfollowed. A KNOWN
    directory (slice Q's `<root>/transcripts/channels`) is different: it is walked through its
    symlinks.
- **The guard is `scripts/next-build-trace.test.mjs`** (in `test:scripts`; it was
  `umtool-build-trace.test.mjs` until release 14 widened it). It scans umtool's app, components,
  lib, `report-to-video/*.mjs` and `song/paths.mjs`, and, since release 14 (F8), `homepage/app`,
  `export/app`, `editor/app`, `editor/lib`, `editor/instrumentation.ts` and every `common/` module
  but `bin/`, per module. A path or fs call carrying a value derived in that file from
  `process.cwd()`, `import.meta.url|dirname|filename`, `__dirname`, or a call to a function
  declared in the file whose body carries one, must open with the opt-out.
  - It is static and per module, as Turbopack's value analysis is: an imported binding is opaque to
    it (to Turbopack it is an unknown, which is a dynamic part: see above).
  - With the slice Q `paths.mjs` it fails on the defect's line.
  - **Since release 15 (slice UT):**
    - The scan set also follows every relative import out of those folders, which adds
      `common/bin/_publicFile.ts`, `homepage/content/docs.ts` and seven `umtool/song` modules
      (umtool 211 → 218 modules, the rest 895 → 897); a test pins them.
    - The checked calls include `open`, `writeFile`, `appendFile`, `createWriteStream` (and their
      Sync forms) and the `fs.promises.` / `fsPromises.` prefixes. No new finding.
    - **It reads umtool's last build back.** Every `.nft.json` under `umtool/.next` but the
      build's own `cache/` and `dev/` fails on an entry outside the repo, under `transcripts/`, or
      through any name starting with a dot other than the build's own directory and
      `node_modules/.pnpm`.
    - **It skips, saying so,** when there is no build (`umtool/.next/server` or `BUILD_ID`
      missing), and when `BUILD_ID` is older than `umtool/next.config.ts` or any umtool module it
      scans (review M1). A merge or checkout gives the changed files new mtimes, and umtool runs
      under `next dev`, which does not refresh `.next`, so a stale build skips until umtool is
      rebuilt instead of failing on a call already fixed.
    - **What it can see** (review L2). Without the excludes, the old clip-audio route failed it with
      1,704 entries (the primary's pre-fix build: 1,705, `test-results/.last-run.json` too). With
      the excludes umtool's config now carries, such a pattern shows only through a name they
      miss: `test-results/.last-run.json` after an e2e run, `.next-shots`, the corpus, a path
      outside the repo. A checkout with no e2e run behind it is blind to it; the fix at the call
      is what keeps the route clean.
- **The build gate** is run with the corpus visible and under a memory cap (the command is in
  `plans/tools/implementer-rules.md`). Linking `<primary>/transcripts` into a worktree is for a
  BUILD only. Remove the link afterwards: never run an app, an index or a fixture builder through it.
- **The other apps were safe by accident; since release 14 (F8) they are by rule:**
  - `common/lib/paths.ts` builds every path on the repo root through one opted-out `under()`, and
    `findMonorepoRoot()`'s walk and its `process.cwd()` fallback are opted out. Since release 15
    `under(first, ...rest)` puts the marker before a named first argument, not a spread (the
    release 14 review's L3); `getPaths()` is unchanged.
  - `homepage/app/lib/source.ts`' directory join on `public` (the source mirror) and the homepage's
    and export's other cwd joins carry the opt-out.
  - The guard covers them. A homepage build with the published source measured the same with and
    without it (`release-14.md`, "The final review's Lows").

## The stats cache key (verified 2026-09-28, branch `fix/stats-cache-key`)

The record is [`stats-cache-key.md`](stats-cache-key.md). Anchors are at the branch tip. Two notes
on anchors elsewhere in this file:
- The branch added lines to `buildIndex.ts`: anchors above this section that point past `:66`
  moved by +1, and past `:559` by +6. They are not rewritten in place.
- The three `buildStats.ts` anchors in the slice-W sections were refreshed here.

- **The stats cache is keyed on the metadata AND the index's own record for the video.**
  - `statsByPath` (`common/controller/buildStats.ts`) holds `{metaMs, idx, stat}` per
    `[channelSlug, videoDir]` (`:92`). A stat is recomputed when `metaMs` or `idx` moved (`:482`).
  - `idx` is `indexSignature` (`:114`) of buildIndex's whole `mtimes` record: `metaMs`,
    `transcriptMs`, `subsMs`, `availabilityMs`, `digestMs` (every input that makes buildIndex
    re-process the video, `buildIndex.ts:585`) and `indexKey`. It is `NOT_INDEXED` (`"-"`,
    `:107`) when the index has no record.
  - The cues are read under the record's own `indexKey` (`:543`). The key buildIndex used when
    `transcript.cues.json` is fresh comes from that file's `uploadDate`, which a later metadata
    rewrite can differ from; the computed key is only the fallback for a video the index lacks.
  - Cost on the unchanged path: one LMDB get per video, and no file I/O.
  - **Until schema 6 the key was `metaMs` alone.** A transcript that arrived after a video was
    first seen never reached its stat: Whisper days later, a Normalize run, or a stats run made
    before `build:index` had the video. The pool composers make exactly that last kind of run:
    `poolSummary.ts:76` runs `buildStats` with no index build. A later
    `build:index && build:stats` then reported "added 0, changed 0" over those videos.
  - **Why the whole record, not just the transcript mtime:** buildIndex does not re-index when only
    `transcript.cues.json` changes, but a re-index for another reason (subs, availability, digest)
    reads the fresher cues.json and changes the cue count. Keying on the whole record redoes the
    stat then. The cost is a recompute on those rarer changes.
  - **Race, benign:** buildStats reads the record before the cues, and buildIndex writes the cues
    (`buildIndex.ts:720`) before `mtimes` (`:841`). A concurrent index build can only pair an
    older record with newer cues, which the next run recomputes.
- **Two kinds of video have no index record, and they are counted apart.**
  - buildIndex writes `meta.scannedAt` (`INDEX_SCANNED_AT_KEY`, `common/lib/stats.ts:19`) at
    `buildIndex.ts:2006`, when a build completes. The value is the time its scan began (`:564`).
  - **`notIndexedYet`:** metadata newer than `scannedAt`, or no build has completed yet. The video
    was downloaded since, and it heals on the first stats run after the next index build.
  - **`notIndexable`:** older than `scannedAt`, and the index has no record. The build did not
    index it:
    - no `upload_date` (`buildIndex.ts:701`);
    - a processing failure;
    - or its channel was held during that build (its media unreachable). Since release 15 (slice
      IG) an incremental build keeps a held channel's records, so this is a video that reached the
      drive after the last index build that could read it. Once the drive is back, a stats-only run
      (Build stats dataset, or a pool composer) before the next index build counts it here, and
      that index build heals it. Under `ARCHILYZER_INDEX_ALLOW_HELD`, a full rebuild drops all of
      the held channel's records the same way (see "The index build's hold").
      > **Superseded by release 18 (2026-10-06):** the "Build stats dataset" button is gone; the stats build runs inside the `update-index` stage, after the index build — see "The publish stages" at the end of this file.

    It stays until fixed, and is logged as such rather than as pending (`:500`).
- **A transcript always has a date, and a caption video takes its captions' arrival.**
  `resolveAcquisitionDates` (`:227`) tries, in order:
  1. transcribe-outcome's `transcribedAt`;
  2. the mtime of the picked index transcript, which is `transcript.json`, else the caption VTT (`:241`);
  3. `transcript.cues.json`;
  4. `downloadedDate` (`:245`).

  Whisper videos resolve as before. The one difference is an outcome sidecar whose date will not
  parse: it now falls through instead of giving null.
- **The downgrade guard.** A build never clears a cache that a NEWER schema wrote (`:424`). It
  throws, naming both versions and `ARCHILYZER_STATS_ALLOW_DOWNGRADE` (`:129`). That variable is
  declared in `envVars.ts` for a deliberate rollback.
  - The guard helps FUTURE bumps only. Schema-5 code has no guard, and would clear a schema-6 cache.
  - `STATS_SCHEMA_VERSION` is 6 (`stats.ts:11`). It versions the cache. The pages' version,
    `STATS_MANIFEST_VERSION`, stays 1.
  - `digestPlan.ts:395,447` and `duplicateShorts.ts:228` only warn on a mismatch, and read
    `value.stat` alone.
- **An unmounted media drive is not an empty channel, for stats either.**
  - `scanSource` asks `inspectChannelMedia` per channel (`:294`). A channel that is not `ok` or
    `in-place` is "held": not rescanned, its cached stats kept and published (`:509`), and logged.
  - A schema clear with any channel held REFUSES (`:443`), because the clear would drop that
    channel's stats for good.
    - The message names each held channel, with its storage location's label and no path.
    - It lists the ways out, mounting first: mount its media; repair or re-point its location on
      /storage; finish or clear its move; or, for a channel gone for good, delete it or set
      `excludeFromBuild`. An excluded channel is skipped before the check.
  - This is the build's own guard. The job registry's `needsMedia` check
    (`streamCommand.ts refuseForUnreachableMedia`) is per channel and needs a `channelSlug`, so it
    never covered this pool-wide build, from the editor or from the CLI.
  - **buildIndex had no such guard until release 15.** An index build with a drive unmounted
    dropped those channels' index records, and the site pages built from it lost them. It holds
    them now: see "The index build's hold" below.
- **One stats build at a time: an operator rule, not a lock.**
  - Two concurrent runs are harmless unless one clears the cache (a schema change) after the other
    has scanned. The other then collects a partly refilled `statsByPath` and publishes truncated
    pages.
  - There is no cross-process lock primitive in `common/`: `scripts/queue-lock.mjs` is the e2e
    queue's flock wrapper.
  - The editor's build jobs share the queue `"build"` by default. The per-button queue fields can
    split them.
  - **The CLI is outside every queue.**
- **The homepage fold counts a transcript that has no date** (`common/lib/homepageSummary.ts:407-408`).
  It counts toward totals, channels, hours, the card's `transcribed.total` (`withUndated`) and
  upload-month placement. Only the transcribed series, "this month" and the recent rail need the
  date.
- **MCP `get_video_metadata`** prints its "## Stats" block from the stats pages
  (`mcp/src/server.ts:2273`). **Still owed:** a video with no transcript has coverage 0 and gets the
  "covers only 0% — truncated" note (`coverageNote`, `:2309`).
- **A caption test fixture must carry YouTube's inline timing tags.** `parseVtt` (`vtt.ts:30`) keeps
  only cue lines containing `<hh:mm:ss.mmm>` (`TIMING_TAG_RE`, `:3`). A plain `WEBVTT` cue parses to
  zero cues. `maybeMissingBuild.test.ts`'s VTT is such a file, which is harmless there.
  - The same rule makes a video whose English track is a *manual* caption (no inline tags) index
    as 0 cues. That is rare: 0 in 3,000 sampled of the-quartering, 6 of chibi-reviews.
  > **Superseded by `200a3105` (2026-10-06; verified 2026-10-10, release 20 D3):** `parseVtt` reads a document
  > with no timing tag as plain cue blocks (every line of a cue is its text), so a manual caption and the
  > livestream `en` shape parse; see "The caption-track rule" at the end of this file.
- **Measured before the fix,** on the whole-pool stats of 2026-09-28T20:40Z:
  - 49,798 transcripts shown, of about 77,000 on disk;
  - 24,710 records with `hasTranscript` but no `transcribedDate`;
  - 2,484 with a stale `hasTranscript: false`;
  - Jasolyzer 0 of 1,889.
- **The schema bump's cost:** one full re-extraction. That is 79,500 videos and 39.3 GB of
  metadata, measured at 149 MB/s on NVMe. About a quarter of the video dirs are on a USB drive, at
  4–5 random reads per recompute. Expect **about 10–30 minutes, longer with a cold cache**.
  - The pass commits per batch of 200.
  - It is interruptible, and it resumes: the schema is written at the clear, so the next run
    finishes the rest.
  - Run in the editor, it stalls the editor's event loop for the length of the pass. Prefer the CLI
    with the editor idle.

## The index build's hold (verified 2026-09-29, branch `r15/index-hold`)

The record is [`release-15.md`](release-15.md), "Slice IG, as shipped". Anchors are at the branch
tip. The branch added lines to `buildIndex.ts` from `:10` on, so every `buildIndex.ts` anchor above
this section is stale, by +16 near the top and +203 at the end; they are not rewritten in place.

- **An unmounted drive is not an empty channel, for the index either.**
  - `scanSource` (`common/controller/buildIndex.ts:309`) calls `inspectChannelMedia({ channelsDir },
    slug, cfg)` for every channel that is not excluded and not social (`:348`), before it reads
    `data/`. A status other than `ok` or `in-place` (`isMediaHeld`,
    `common/lib/channelMediaHold.ts:26`) puts the channel in `held` with a reason and no path, and
    it is not scanned.
  - It calls it again after the walk (`:465`), so a drive that goes away mid-walk holds the
    channel instead of dropping the videos after that point (without it, `buildIndex.test.ts`
    case (i) removes 3 of 4).
  - A failed `readdir(data/)` holds too (`its data directory could not be read (<code>)`), except
    ENOENT on an `in-place` channel, which is a channel with no downloads and is logged as such
    (`:362`). A per-video metadata `stat` failing with anything but ENOENT or ENOTDIR holds the
    channel too, logged as `a video in its data directory could not be read (<code>)` (`:387`).
- **What a held channel keeps, on an incremental build:**
  - its `mtimes` records: the removal pass skips its keys and counts them (`:715`), so `sums`,
    `cues`, `subs`, `digests` and `byChannel` keep them too;
  - its shared transcript, subs and digest trees: not rewritten, not pruned, not removed
    (`:1204`, `:1393`, `:1772`, and the top-level cleanups `:1513`, `:1879`);
  - its subs and digest stats, carried from `channelStatsDb` / `channelDigestStatsDb`, so the
    per-site subs and digest manifests still list it;
  - its availability states: the maybe-missing overlay skips it (`:1324`), and the last build's
    `videoState` entries for it are carried over (`:1356`). Its `availability.json` files are on
    the missing drive, and a missing one reads as `maybe_missing`.
  - The per-site summaries come from LMDB, so the site built next still lists its videos.
- **A curated-tag change while a channel is held:** the re-apply pass re-derives its records in
  LMDB (no disk read), but its pages are not written, so `curatedPagesPending` is NOT cleared while
  a channel is held and the pass had pages pending (`:1551`). The first build with the drive back
  rewrites them.
- **A full rebuild with a channel held refuses** (`:649`). A full rebuild is a schema change or a
  first build (no `meta.schema`); it clears every sub-DB, and a held channel cannot be re-read.
  - The scan now runs BEFORE the clear (`:639`), so the refusal leaves the index untouched.
    `scanStartedAt` is still taken at the scan's start.
  - The message names each channel with its location's label, the ways out (`HELD_WAYS_OUT`,
    shared with the stats build's refusal), and `ARCHILYZER_INDEX_ALLOW_HELD` (`:512`, declared in
    `envVars.ts`) with where it is set: the command's own environment for a CLI run; the editor's
    own environment, and so a restart, for the editor's Build index job or a site build started
    from the editor (their children inherit `process.env`). The CLI exits 1 on it, so a site
    build's data phase fails with it.
  - With the variable set, the build proceeds: the held channel's records go with the clear, its
    shared trees are left on disk, and it is out of the index (the site lists it with 0 videos)
    until its media is back and an index build runs.
- **Who sees it:** `BuildIndexResult.heldChannels` (`:502`); the log's per-channel line, the
  `Diff:` line's ` Held: N channel(s), K video(s) kept.` suffix (`:780`), and the `Done in` line's
  ` Held, their media not readable: <slugs>.` suffix. The CLI (`archilyzer index`, the export's
  and homepage's `build:index`, so every site build's data phase) prints the log; the editor's
  **Build index** job (`buildIndexAction`) streams it into the job log, which `pnpm ops build-index
  --wait` follows. Nothing reads the result's field outside the tests.
  > **Superseded by release 18 (2026-10-06):** `buildIndexAction` is deleted and a site build runs no data phase; Build index is the `update-index` stage child, and its stamp records `index.heldChannels` — see "The publish stages" at the end of this file.
- **The words are shared with the stats build** (`lib/channelMediaHold.ts`): `HELD_REASON` is a
  `Record<ChannelMediaStatus, string>`, so a new status added to `inspectChannelMedia` fails tsc
  until it has a reason; `isMediaHeld` treats any status but `ok` and `in-place` as held.
- **Not covered:** a drive that drops during the PROCESSING phase (after the scan), for a changed
  video whose metadata was read before the drop. A transcript read that fails after it is caught
  as "no cues" (`cueList = undefined`, `:838`); a sub-track read that fails is skipped, and with
  none left the video's subs are removed (`subs.remove`, `:895`); a digest load that fails leaves
  no digest, which is removed (`digests.remove`, `:962`/`:965`). `mtimes` is then written with the
  video's current mtimes, so the loss lasts until any of its tracked mtimes (metadata, transcript,
  subs, availability, digest) moves.

## The storage health gate (verified 2026-09-29, branch `r15/drive-stall`)

The record is [`release-15.md`](release-15.md), "Slice DS, as shipped", with the parent's rulings
(Q1–Q5) and the review's fixes (M1–M3, L1–L10); the timings became settings in "Slice DT, as
shipped". Anchors are at slice DT's tip (`r15/drive-timings`).

- **A drive can be mounted and not answering.** Every in-process fs call on it waits on one of
  libuv's threads (4 by default, 16 in the editor's `start`) until it answers (~30 s for the observed
  USB reset loop); only a child process isolates a call. A child `stat` of a location's ROOT does not
  detect it reliably: the root's inode is in the kernel's cache whenever the drive was used lately.
- **The timings are settings: `settings.storage.health`** (slice DT). `budgetMs` (default 3000,
  500–60000), `passIntervalMs` (15000, 5000–300000), `probeTimeoutMs` (3000, 500–30000),
  `clearAfterCleanPasses` (2, 1–10), `inFlightPerLocation` (4, 1–8: at most half the editor's 16
  file-access threads, review M1); the defaults, ranges, sanitizer
  and words are `common/lib/storageHealthTimings.ts` (pure; the /storage form imports it). A read
  clamps into the range and keeps only a value that differs from its default (an untuned file has no
  `health` key); the /storage form refuses out of range with a sentence. Every number is read through
  ONE accessor, `healthTimings()` (`storageHealth.ts:182`), from the timings as last applied on
  `globalThis` — no file read per call. `applyHealthTimings(stored)` (`:193`) sets them: the health
  pass on every pass (from the settings it reads), /storage's save at once
  (`saveHealthTimingsAction`), and the `index` and `build stats` bins once at start. Any other process
  with no pass (a CLI, `archilyzer doctor` until slice SG adds its line) runs on the defaults. A changed interval is told to
  `onPassIntervalChange` (`:214`) subscribers, which re-arms the armed pass's timer; a raised cap
  admits waiting calls, a lowered one is reached as calls return. `resetStorageHealth` keeps the
  timings (configuration, not health); `setDriveCallBudget` is a test seam below the 500 ms floor and
  wins over them.
- **The state is `common/lib/storageHealth.ts`**, one map on `globalThis.__yttStorageHealth__` (the
  pass writes it from instrumentation's module copy; pages read it from theirs), with each entry's
  `detector` and the counters' `device`. `recordLocationHealth` (`:251`): one `stalled` answer stalls
  at once, and every transition to stalled refuses `onDrive`'s waiting calls; `clearAfterCleanPasses`
  (2 by default) clean answers in a row clear it; `absent` is clean; a new root starts over.
  `registerLocationHealth` (`:336`) creates entries with no answer. `stalledLocationForPath`
  (`:388`) matches like `locationOfDataDir`; `stalledLocation` (`:404`) is by id AND root.
- **Detector 1, every `passIntervalMs` (15 s): the block device's counters** (`detectLocationHealth`,
  `lib/storageVolumes.ts:607`). The root's device from the last pass (findmnt `-J -T <root> -o
  SOURCE,UUID`, raced against `probeTimeoutMs` (3 s), only when there is none or its `/sys` entry stops reading;
  another volume's UUID names none; `[…]` stripped, `/dev/mapper` resolved, basename); then
  `/sys/class/block/<dev>/stat` (`parseBlockStat`, `storageHealth.ts:831`): completed = fields 1 + 5
  + 12 + 16 (reads, writes, discards, flushes), in flight = field 9. Stalled ⇔ in flight at both
  samples AND nothing completed between; samples at least `minCounterIntervalMs()` apart
  (`storageVolumes.ts:472`: min(10 s, interval − 5 s), floored at half the interval — 10 s at the
  default 15 s); the first gives no verdict. in_flight counts only requests dispatched to the driver: one requeued
  during a host reset is not counted, so a sample in that window can read clean (the watchdog covers
  it). No device → the child `stat -L -c %F` probe (`probeLocationHealth`, `:388`, raced against
  `probeTimeoutMs`). The samples are
  on `globalThis.__yttHealthDetector__` (the pass and /storage's Refresh share them).
- **Detector 2, on every gated call: `onDrive(where, call)`** (`storageHealth.ts:722`). Refused with
  no call on a stalled location; otherwise raced against `budgetMs` (3 s by default, read as the call
  starts; test seam `setDriveCallBudget`); the budget covers the whole unit passed in. A timeout marks the location
  stalled (since now) and throws `DriveNotAnsweringError`, leaving the call to settle — unless the
  location's device counters (read synchronously from `/sys` through the reader `storageVolumes.ts`
  registers with `setCounterReader`, `:515`) moved since the call began: then the call is refused
  as slow and nothing is marked. At most `inFlightPerLocation` (4 by default) calls per slot key in
  flight (`acquireSlot`, `storageHealth.ts:573`): the rest queue in JS. A waiting call's deadline follows progress: every call that
  returns on the key (in time or late) restarts it (`releaseSlot`, `:673`, re-arms every waiter), and a
  waiting call is refused unmarked only when nothing on the key has returned for the budget plus a
  quarter of it (at most 250 ms) — never for the queue's depth alone. Waiting calls are refused at
  once by any transition to stalled; and when every slot is held by a call already past its budget
  (`overdue`, each kept with the counters reading from when it began), a new call is refused at once,
  and the location is marked stalled again only if the disk has completed nothing since the oldest of
  them began (otherwise "drive slow", unmarked). A slot is freed when its call really returns. The
  slot key: a configured location's id; a probe of another root under its id, that root (marks
  nothing); a path on no configured location, the root it is under (`rootOfUnknownPath`, `:529`;
  marks nothing). Do not nest it for one key. The timer is not unref'd.
- **The cadence** is `runStorageHealthPass` (`controller/storageWatch.ts:442`): apply the timings it
  read, prune, register, then every location concurrently; every `passIntervalMs` (15 s) from
  `startStorageHealthWatch` (`:566`, re-armed when the interval changes), plus one at arm time,
  armed by `editor/instrumentation.ts` ABOVE the idle gate (it writes nothing). The five-minute pass
  (`startStorageWatch`, `:535`) stays below it. A CLI process has no pass (its inspects are still
  raced). `refreshLocationHealth` (`:499`) is /storage's Refresh.
- **The gate order in `inspectChannelMedia`** (`lib/channelMedia.ts:317`): config → memo (a
  remembered `in-transition` is returned as is, anything else is gated first) → the relocation
  marker (`:367`, corpus disk) → the gate (`:386`) → the link (corpus disk) → the target's `stat`
  through `onDrive` (`:447`). A stall is never memoised. Other gated calls: `probeLocation`
  (`storageVolumes.ts:239`, its stat and statfs through `onDrive`) and its memo; `volumeFreeBytes`
  (`controller/storageLocations.ts:289`, `:326`, `:335`); `readChannelStat` (`controller/channels.ts:205`,
  the walk through `onDrive`, `null` on a stall); the snapshot walk (`controller/channelSnapshot.ts:753`,
  its listing, keep-latest keys and per-video unit); the recency tail reads; the move-root check; the
  saved-video store; `listSavedVideos` with `notAnswering`; the videos list, the video page, the
  Cleanup stage, the Storage stage's statfs and the media file route. `channelMediaStall(config)`
  (`channelMedia.ts:232`) is the no-I/O question for a holder of a config.
- **`stalled` is a sixth `ChannelMediaStatus` and a sixth `StorageLocationStatus`** ("Not
  answering"). `HELD_REASON`, `MediaLocationBadge`'s two tables and `STORAGE_STATUS_LABEL` are the
  `Record`s that make tsc name every table a seventh would need. `isMediaHeld` holds it, so both
  pool-wide builds hold a stalled channel; the storage watch counts it as down (two passes pause),
  on a location or not, and the pause record carries `cause: "not-answering"` (`ChannelAutoPause`,
  `lib/channelPriority.ts`; absent = not there).
- **`inspectChannelMedia` is memoised for 5 s** (`CHANNEL_MEDIA_MEMO_MS`, `:266`), keyed by channels
  dir, slug and configured `dataDir`, on `globalThis.__yttChannelMediaMemo__`. `{ fresh: true }`
  skips it and does not store; the deciders that pass it are listed in the record (the guard and its
  six callers, both movers, both builds, the watch, eviction, the re-point preflight, doctor). The
  runners' tick shares the status poll's `buildChannelWork` and so reads the memo.
  `forgetChannelMedia` (`:292`) is called by the channel mover's marker writes and clear,
  `clearRelocationMarker`, a re-point, /storage's Refresh and the e2e `invalidate-cache` route.
- **`UV_THREADPOOL_SIZE`** defaults to 16 in `editor/package.json`'s `start` and in
  `docker/entrypoint.sh`. `ports.test.ts` reads every `${NAME:-N}` in a script as a port and names it
  as the one exception (`NUMERIC_NOT_PORTS`, `common/lib/ports.test.ts:29`).
- **Not covered:** a call already in flight when the drive stalls (at most `inFlightPerLocation` per
  drive for the calls through `onDrive` — every page and poll path and the snapshot walk; a job's own reads that do
  not go through it, `measureTree`, the index build's processing phase, the snapshot's sequential
  reconcile pass, are not capped); a hand-typed root is capped but never marked; a drive already
  stalled at boot before the second counter sample, unless a page reaches it; per-click server
  actions; the file route's stream; the corpus disk itself.

## The source's history (stagit) (verified 2026-09-30, branch `r15/stagit`)

Release 15 slice SG ([`release-15.md`](release-15.md)); the operator-facing doc is `PUBLISH.md`, "The
source mirror (homepage)". Anchors are at the branch.

- **stagit** (codemadness.org, C over libgit2; built from `519cae2f`, "bump version to 1.3",
  2026-09-14, against the system libgit2 1.9.7) renders the scrubbed mirror into `/source/git/`.
  It is operator-installed like git-filter-repo: never vendored. `resolveStagit`
  (`publish/sourceHistory.ts:122`): `paths.stagitBin` (`STAGIT_BIN`, else `"stagit"`, `lib/paths.ts:314`)
  — a name with a slash is that file or nothing; a bare name is PATH, then `~/.local/bin/<name>`.
  It has no version flag: `stagitIdentity` (`:136`) is the first 12 hex of its binary's sha256,
  never the path (the manifest is published, and a home-dir path is a denied literal).
- **What stagit does** (read in `stagit.c`): it writes into its CWD; the repository's NAME is its
  directory's basename minus `.git` — so the step's scratch clone is `<scratch>/archilyzer.git`
  (`source.ts:834`), no longer `bare`; `description` (read with `fgets`, the newline KEPT — write it
  without one) and `url` (newline stripped) come from the repository directory; the header links
  `<relpath>file/README.md.html` and `LICENSE` when HEAD has them, and the logo `<a href="../<relpath>">`
  lands on `/source/` from every depth; `file/` pages are written for HEAD's whole tree on EVERY run;
  every text from the repository is xmlencoded (`"` → `&quot;`), so no page text can fake an
  `href="…"`; `-l N` keeps the NEWEST N log lines (the revwalk is newest first) and ends "M more
  commits remaining, fetch the repository", but still writes a page for EVERY commit (it only skips
  the diffstat of a page that exists); `-c` with `-l` is a usage error; a diff's paths are percent-encoded (`/` and `,-.` kept); a commit over 1,000 files or
  100,000 added or deleted lines prints "Diff is too large, output suppressed"; `-c <file>` walks from
  HEAD to the commit the cache file names — in COMMIT-DATE order, so a `--no-ff` merge of commits
  older than that commit leaves them out (the step's count check then renders every page again,
  about 8 s: common with parallel slices, and correct) — KEEPS every `commit/<sha>.html` already in
  the CWD, and appends the cached log lines — so the cache is the whole output directory, and a cache
  whose commit is not an ancestor duplicates the log. Its temp cache file (`cache.XXXXXXXXXXXX`) is made in the CWD.
- **The cap** (`SOURCE_HISTORY_MAX_COMMITS`, 10,000; ruled 2026-09-30): up to it, `-c`; past it,
  `-l 10000`. Either way the pages published are exactly the commits the log links
  (`loggedCommits`: every `href="commit/<sha>.html"` in log.html), each of which must exist, and the
  first must be the head. The manifest's `history.total` is every commit, `commits` those with a
  page; `/source/` says "the latest N of M" when they differ. Past the cap each publish computes N
  diffstats (no `-c`): 8.75 s at 1,834 commits with every page present, against 0.58 s with `-c`.
  The oldest published page's parent link is then a 404.
- **The step** (`source.ts`, step 12b) runs after the object audit and the mirror's staging,
  before the manifest and the file audit: `stageHistoryPages` (`:1114`) → `renderHistory`
  (`sourceHistory.ts:573`). **An allowlist is staged** (`TOP_FILES`, `COMMIT_PAGE`, `:94`): `log.html`,
  `files.html`, `refs.html`, `atom.xml`, `tags.xml`, `commit/<40 hex>.html`, plus `style.css`. Never
  `file/`, never a leftover. Pages are rewritten byte for byte (latin1 in and out; every injection is
  ASCII: the back link says `&middot;`).
- **The post-pass** `rewriteHistoryPage` (`:327`), pages only: `<script>` + the homepage's pre-paint
  script (`homepageThemeScript`, `:88` = `buildThemeScript({ defaultBase: HOMEPAGE_DEFAULT_BASE })`)
  before `</head>`; `HISTORY_BACK_LINK` (`:85`) after `<body>`; `href="(../)*file/<p>.html"` →
  `href="$1../tree/<p>"`; `logo.png`/`favicon.png` → `/icons/icon-32.png` (a route the homepage renders
  at build). With the published set (`PublishedSet`: the staged raw tree's files, decoded; the log's
  commits), a link to a file main no longer has (a diff of a deleted or renamed file: 3,342 anchors at
  1,882 commits) or to a commit with no page loses its ` href="…"` and keeps its text and its `id`
  (a diff header is the diffstat's `#h<n>` target); `a:not([href])` is styled as text. At `4dfe21e5`
  every one of the 32,609 remaining tree links and every commit link resolves. The theme config moved to `lib/themeConfig.ts` for this (publish may not import
  components/; `components/themeConfig.ts` re-exports it); `HOMEPAGE_DEFAULT_BASE` (`:62`) is what the
  homepage layout passes. The attribute the script sets is `data-base`, not `data-theme`.
- **`style.css`** is `historyStylesheet` (`:215`) over `common/styles/tokens.css`: the light block
  (`:root, html[data-base="light"]`), the dark block for `html[data-base="dark"]` AND for
  `:root:not([data-base])` under `prefers-color-scheme: dark` (no JS); `HISTORY_TOKENS` and whatever
  they reach through `var()`. Diff `+` lines are `--success`, `−` lines `--destructive`; there is no
  chart-safe red in the tokens (the chart palette is blue, green, violet, amber, magenta, rust).
- **Never a failed build over the history.** No stagit: one line with the install (`source.ts:973`).
  A render that fails (`HistoryProblem`), a stagit timeout (600 s), unreadable tokens, more files
  than the step's 15,000 in all, or a page over 24 MiB: a `[source] WARNING: …` and no history. A
  cancel still cancels; any other error is a crash as before.
- **The manifest's `history`** (`lib/sourceManifest.ts:88`, parsed at `:140`, all-or-nothing):
  `href`, `commits` (`git rev-list --count`), `head`, `files`, `bytes`, `sha256` (`historyDigest`,
  `source.ts:508`: `sourceDigest`'s walk over `source/git/**` alone), `tool`. `sourceDigest` (`:492`)
  now walks `source/git` too. The state (`.source-publish.json`) gains `stagit` and `history:
  {files, digest} | null`; the skip needs both to match, and a stagit present with no history never
  skips. `SOURCE_STEP_VERSION` is 4 (`:109`).
- **The deploy check** (`publishedSourceProblem`, `:1254`) names the history on its own (`:1336`):
  `out/source/git`'s digest must be the state's (null when none) and the manifest's.
- **The render cache** is `${XDG_CACHE_HOME:-~/.cache}/archilyzer/source-history/`
  (`getPaths().sourceHistoryCacheDir`; an empty `XDG_CACHE_HOME` is unset; ruled 2026-09-30):
  `key.json`, `stagit.cache`, `out/`, and `lock` while held. `historyCacheFor` (`source.ts`) gives
  none for `--check` and none, with a line, inside the checkout or the public dir. `holdHistoryCache`
  (`sourceHistory.ts:508`): the lock names the holder's pid; a live holder with a lock under an hour
  old (`HISTORY_LOCK_STALE_MS`, `:498`) → render without the cache; a holder not running, or a lock
  over an hour old → emptied and taken, with one line. An I/O error on the dir, the lock or the key
  (`isIoError`, `:653`: an errno code — EACCES, EROFS, ENOSPC) → one line and a render without the
  cache; a key that cannot be written is no key. Every line `renderHistory` logs goes through
  `maskLiterals` (`source.ts`' `onLog` for it).
  Its pages are kept when the key (`historyCacheKey`: rules hash, filter-repo, stagit, description,
  clone URL, base URL) matches and `out/log.html` exists; its `-c` file only when the commit it names
  is an ancestor of the head (`git merge-base --is-ancestor`), else that file alone goes. A page of a
  commit no longer in history is never published (only the log's commits are). The key is removed
  before a render and written after it. A cached render whose log names a page that is not there
  is rendered again from nothing, once. `--force` renders
  afresh; `--check` renders in its own scratch; a refusal removes the cache (`source.ts:716`).
- **Measured (2026-09-30, `main` `6b8aa450` → mirror `8c924ca31701`):** 1,872 commits; 1,878 files,
  141,299,532 bytes; the largest `commit/7ddfc955….html`, 5,017,646 bytes; stagit 8 s of a 32 s
  publish (every page); the whole publish 4,396 files, `homepage/out` 4,576. On the published mirror
  at 1,834 commits: 8.0 s every page, 2.0 s from the cache with nothing new. The cache is 138 MB.
  At `main` `4dfe21e5`: 1,882 commits, 1,888 files, 4,409 staged in all. One file per commit: the cap
  keeps the history at 10,006 files at most; the 15,000-file drop is the last resort.
- **`_headers`**: `/source/git/*` is `X-Robots-Tag: noindex` (ruled at review, M1), like the raw
  tree; no other rule matches it, so the pages keep their own types (`headers.test.ts` pins both).
- **Doctor** (`bin/doctor.ts`): the stagit line ends `; cache: <path>, <size>`. Since the merge of
  slice DT it reads the settings before the corpus and applies `settings.storage.health`
  (`applyHealthTimings`) before it inspects any drive, and prints the timings in force on a
  `drive health` line.
- **The homepage** believes `history` only beside `source/git/log.html` (`homepage/app/lib/source.ts:43`;
  without it the manifest comes back without the block). Its e2e reads a fixture publish from
  `E2E_SOURCE_PUBLIC_DIR` while it holds a manifest (`sourcePublicDir`, `:69`; never in a production
  build).

## Search in (verified 2026-09-30, branch `r16/search-in`, after its review)

- **The row governs "transcripts"-scope leaves only.** The Filters panel's "Search in" row
  (`common/components/FiltersPanel.tsx:421`, `data-testid="search-in-row"`) says what a leaf of
  scope `"transcripts"` reads — the default leaf, `newLeaf({scope: "transcripts"})` in
  `emptyRoot()` (`common/lib/searchQuery.ts:86`), and every plain query. A leaf asked for by
  name ("Live chat", "Posts", "Title / channel", "Description", "Keywords") is not the row's
  business — including "Posts" with Posts unticked: `nop` no longer gates the global scope
  (`SearchSessionContext.tsx:898` checks only the tag filter). The browse listing (an empty
  query) is the Type row's.
- **The mechanism is a rewrite of the committed tree just before it runs**, never of the tree
  itself: `applySearchIn(root, {transcripts, posts, chat})` (`searchQuery.ts:544`) turns an active
  transcripts leaf into itself (transcripts only), itself with another scope and the same id (one
  other kind), or an OR group `<id>~in` over copies `<id>~transcripts` / `~posts` / `~chat` (two or
  three kinds; a negated leaf is a negated one-child AND `<id>~not` around the OR). The session
  (`SearchSessionContext.tsx:589`) runs the rewrite and folds the progress back with
  `foldSearchIn` (`common/lib/search/searchIn.ts:18`; called at `SearchSessionContext.tsx:960`):
  copies' hits are re-filed under the visitor's leaf id, their states folded into one (the count
  is the OR group's union once every copy has started). `committedRoot`, its canonical hash and
  `qt=` stay the visitor's tree. `lib/search/` has a seventh module for this, `searchIn.ts`.
  Each copy has its own hit cap, so a plain leaf reading two or three kinds can show up to 2–3×
  "Max hits" before "Load more", as an explicit OR of leaves always could.
- **Posts, as read by a plain query, is new in release 16.** On `main` before it a transcripts
  leaf never read posts: posts joined the global scope only when a posts leaf was in the tree
  (`needsPostsManifests`), and a non-posts leaf subtracts the posts slugs
  (`searchEval.ts:337`). The row reads them through a posts copy of the leaf.
- **Under a curated-tag filter no posts copy is made** (`searchInUnderTags`, `searchQuery.ts:507`):
  a post carries no tags. Unless posts are all the row reads — then the copy stays and reads an
  empty scope, so the leaf does not fall back to its transcripts.
- **An empty scope settles.** Each streaming driver in `lib/search/leafPipeline.ts` finalizes when
  no worker is running after its first `ensureWorkers` and after a raised cap (`settleIfIdle`,
  `:199`, `:342`, `:528`); before, zero slugs never reported done and the query read "searching"
  for ever. `searchEval.runLeaf` also answers an empty effective scope at once, with no cache
  lookup (`searchEval.ts:353`).
- **What counts as ticked is what the site can honour** (`SearchSessionContext.tsx:552`, `:562`):
  Posts only where `postsManifest.channels` is non-empty, Live chat only where
  `subsManifest.liveChatTotalCount > 0` — the same conditions the panel offers the boxes on. **It
  waits for the manifests:** `SearchDataValue.manifestsSettled` (`SearchDataContext.tsx:67`; the
  single site's settles at each manifest's first answer or first failure, `:165`; the hub's is
  `summariesReady`, since an archive is ready only once both its manifests have settled). Until
  then Search is not refused and the query does not run (`SearchSessionContext.tsx:944`).
  Nothing ticked (`draftSearchInEmpty`, `:583`) disables Search, `Apply filters`, Save and Save
  as…, and `commitSearch` and the two profile saves refuse it. The row's line (`FiltersPanel.tsx:462`,
  `aria-live="polite"`, not `role="status"`: from xl the panel is always mounted, and the video
  modal's own status is found by role) is always mounted, empty unless refused; the Search button is described
  by an always-mounted copy in the bar (`SearchBar.tsx:182`, `id="search-in-refusal"`), since the
  panel below xl is a sheet that is not mounted while closed. The words are
  `SEARCH_IN_REFUSAL` (`SearchSessionContext.tsx:190`).
- **The keys:** `notr` (Transcripts unticked) and `lc` (Live chat ticked) beside `nop` in
  `FilterSnapshot` (`common/components/exportFilterStorage.ts:38-40`), in the working snapshot and
  the profiles of `ytdlp-tb:export-filters`, each written only off its default. **Share links do
  not carry them** (nor `nop`): no share-v1 key, no `ShareSelection` field. The row is read from
  the stored snapshot on hydration whatever the URL carries, so a `qt=` or share link reads with
  the visitor's own row.
- **The display:** every track hit wears its `TrackBadge`, live chat included
  (`SearchResults.tsx:933`); a transcripts leaf's section is named for what it holds
  (`sectionScope`, `:949`): "Posts" on a post's card, "Live chat" when every hit is a chat hit.
- **Not governed by the row:** the charts' own search series (`components/charts/useSearchSeries.ts`)
  and `/ask`'s retrieval (`export/app/lib/askRetrieval.ts`) build and run their own trees; the MCP
  has no row.
- **The export e2e fixture's posts have words of their own** (`kappa`, `sigma`, `omega` —
  `export/e2e/fixtures/data.ts`, `postsPage`), so a plain "alpha" or "gamma" in a spec reads no post.

## Use with AI is the homepage's AI and MCP doc (verified 2026-09-30, branch `r16/research-setup`)

- **The research-only setup lives on the homepage doc; `README.md` §1/§4 and `mcp/README.md` carry
  copies to change with it.** `homepage/content/docs/ai-and-mcp.md` "Ten-minute setup": clone (or
  the tarball) → `cd archilyzer && pnpm install` → `claude mcp add archilyzer --env
  TRANSCRIPT_SITE_URL=…` → `claude`, `/ask`. **README §4's quickstart carries that whole sequence,
  in the same order** (its command adds the two optional editor lines). **README §1 and
  mcp/README's "Add to Claude Code" and `mcp.json` examples share only the registration**, `claude
  mcp add archilyzer … -- pnpm --silent -C <checkout> archilyzer mcp`:
  README §1 with `"$PWD"` from the repo's root, mcp/README with the placeholder
  `/ABS/PATH/TO/archilyzer`. Nothing shares text between `homepage/content` and the READMEs
  (`homepage/content/README.md`'s drift table names them).
  - *Amended 2026-09-30 (release 13 slice W2, brought to main):* every copy — the doc's block and
    its `mcp.json` note, README §1/§4, mcp/README's "Add to Claude Code" and `mcp.json` (`"args":
    ["--silent", "-C", <checkout>, "archilyzer", "mcp"]`), AGENTS.md's no-corpus block — runs the
    server as `pnpm --silent -C <checkout> archilyzer mcp` (was `pnpm -C <checkout> --filter
    yt-dlp-transcript-mcp exec tsx src/index.ts`; why `--silent`: "The CLI's last subcommands" above).
    `homepage/e2e/docs.spec.ts` pins the doc's line and that `exec tsx src/index.ts` is not on the
    page.
- **A site has no `/use-with-ai` page** (export and hub). `AI_DOC_URL` (`common/lib/project.ts`,
  `${PROJECT_URL}/docs/ai-and-mcp/`) is the target of the header's nav entry (a plain `<a>`: the
  header's and `MobileMenu`'s links take `external: true`), the footer's link and Ask AI's link,
  label "Use with AI", same tab. `corpus.json`'s `useWithAi` keeps its key and names the doc (site
  and hub); `llms.txt`'s "## Ask AI" is two lines, `[Ask AI](<base>/ask/)` and `[Use with AI](<doc>)`;
  the sitemap's routes are `/`, `/changelog` (+ `/downloads`, `/duplicates` when built).
- **A route outside the workspace, in the same page life, is reached in a spec through
  `window.next.router.push(…)`.** Next 16.2.3 sets `window.next.router` "for debugging"
  (`next/dist/client/components/app-router-instance.js:388`), in development and production. It is
  undocumented (not in `node_modules/next/dist/docs/`): check it first on a Next upgrade; if it is
  gone, the specs fail with a TypeError rather than pass. Since
  the header's Use with AI left the site, no site link makes a client navigation to a page outside
  the workspace (the footer's are plain `<a>`, a new page life; Downloads and Duplicates show only
  when built), so `first-search` and `restore-no-refire` push `/changelog/` that way.
- **A multi-line JSX text that holds an HTML entity loses its leading space** under Next 16.2.3's
  SWC: `<b>X</b> is the⏎project&apos;s` compiles to `"is the project's"` (without the entity, or on
  one line, `" is the …"`). Put `{" "}` after the element. Measured 2026-09-30 by compiling every
  `.tsx` with and without its entities (`next/dist/build/swc` `transform`): 22 texts in 19 files differ,
  1 in `homepage/app/downloads/page.tsx` and 21 in `editor/app/**`; none in `export/app` or
  `common/components`.

## A form that fails keeps what was typed (verified 2026-10-01, branch `r16/forms-keep-input`)

- **React resets a `<form>` whose `action` is a function when the action's transition commits —
  success or failure alike.** In the react-dom the editor runs (Next 16.2.3's bundled
  `19.3.0-canary-3f0b9e61-20260317`, `next/dist/compiled/react-dom/cjs/react-dom-client.development.js`):
  `startHostTransition` calls `requestFormReset$1(formFiber)` beside `action(formData)` (`:9222`);
  the commit marks the form (`needsFormReset`, `:15963`) and, after every mutation of the root,
  calls `recursivelyResetForms` (`:16017-16018`), which calls the native `form.reset()` (`:16223`).
  (The standalone `react-dom@19.2.4` under `editor/node_modules` has the same code at `:8955`,
  `:14848`, `:14900-14901`.) The reset comes AFTER the commit's prop updates, so a new
  `defaultValue`/`defaultChecked` written in that commit is what the reset restores.
- **Which elements survive the reset, and why** (measured in Chromium against react-dom 19.2.4,
  `fk-exp` in the slice's scratch, whose code for these paths is the canary's; then probed in the
  editor itself on `main`'s code):
  - an uncontrolled text input, textarea or checkbox goes back to its default — and takes a NEW
    default written in the same commit (`updateInput` / `updateTextarea`);
  - a controlled TEXT input survives: `updateInput` keeps its `defaultValue` in step with `value`;
  - a **focused number input** is the exception: `setDefaultValue` skips it (`:1857`), so a submit by
    Enter in one restores its OLD default;
  - an uncontrolled `<select>` restores the option it MOUNTED with: a `defaultValue` change after
    mount is applied only when `multiple` toggles (`:22447`);
  - a **controlled checkbox, radio or select does not survive**: `defaultChecked` is set only at
    mount (`initInput`, `:1849`; `updateInput` writes `checked` alone, `:1797-1798`), and a controlled
    select's options NEVER get `defaultSelected` (`updateOptions(…, false)` at mount, `:22121`, and on
    update, `:22444`), so the reset selects the server-rendered `selected` option, or the FIRST
    option for a select mounted on the client (a membership's group select that appears on a tick).
    After any submit the DOM shows that while state holds the choice, **until the next re-render that reaches the
    element** re-asserts the prop (React 19 calls `updateInput` with every prop on any update) — in
    the editor 0.3 to 7 s, the auto-refresh being the usual one; never, with it off. A NAMED one
    submitted in that window posts the stale choice.
- **The `values` contract** (`editor/app/lib/formState.ts`, pure — imported by the `"use server"`
  actions and the client forms both). An action that can refuse captures `const values =
  formValues(formData)` at its top — each name's FIRST value, files skipped — and returns it with
  every refusal: `{ ok: false, error, values }` (`FormState<T>`), or `{ error, values }` for the
  channels flavour (`FormErrorState`; success is `undefined`). A success carries no `values`.
  `seedValue(state, name, initial)` is the submitted value when the last submit failed and carried
  the name, else `initial` (a name not posted — disabled, or not rendered then — keeps `initial`).
  `seedChecked(state, name, initial)`: **when `values` is present, a checkbox is ticked iff its name
  is in it** — an unticked box sends nothing, so absence means unchecked. One reading of both
  flavours: a state is a failure unless it says `ok: true`.
- **The seeding primitives** (`editor/app/components/forms/`): `Field` (the one labelled input; it
  takes `state`), `SeededInput` (re-mounts a number input when its default changes — the focused
  case), `SeededSelect` (always re-mounts on a new default — the select case); both key on the
  default itself, so an unchanged default re-mounts nothing. `ControlledCheck` / `ControlledSelect`
  (`Controlled.tsx`) put a controlled element's latest committed value back a microtask after its
  form's native `reset` event (React calls `form.reset()` inside the commit, so the microtask runs
  after it), and touch the DOM at no other time. **Never write a controlled element's DOM value at
  mount:** a choice made before hydration is replayed by React as a change event once it hydrates
  the element, and a mount-time write overwrites the DOM first, so the replay reads the old value
  (a layout-effect version of these lost `cadence-ui`'s and `channel-site-membership`'s
  straight-after-`goto` selections). A `key` on the whole FORM is not a fix: it would discard the
  typed values with the stale ones.
- **A name posted more than once cannot be seeded from `values`** (each name's first value).
  The one in the editor is DigestSettingsForm's `digestSections` (one box per section): its boxes
  are controlled (`ControlledCheck`) and re-read from the stored list after a success or a new
  stored list.
- **A form action that only fails on a settings write is refused for real in e2e by putting a
  directory at the settings path**: `editor/test-settings.json` is set aside, `mkdir` takes its
  name, the atomic write's `rename` fails `EISDIR`, and `getSettings()` reads defaults meanwhile
  (a read never throws). `forms-keep-input.spec.ts` `withSettingsUnwritable` restores the file in a
  `finally`. A background writer in that window fails the same way, so the spec keeps it to one
  submit.

## A move holds the channel's writers and mirrors its copy (verified 2026-10-01, branch `r16/move-holds-writers`)

The record is [`release-16.md`](release-16.md), "Slice RM, as shipped". Anchors are at the branch tip.
This section amends "A channel's media may be on another drive" (above): **a move is now serialized
against the channel's own writers by refusal at the job's start as well as at enqueue**, and the copy
phase deletes from the destination.

- **Which writer got past the guard on 2026-09-30 (`realcandaceo`, from the job metas, read only).**
  Not a lane: the lanes skip a channel with a marker twice over (guard 2 in `buildChannelWork`, and the
  pick→run backstop that reads the marker before a unit launches), and both held. It was a manual
  **Transcribe all** (`whisper-all`, job `01M3TGYDXA7WCBGN014A90J3JW`, queue `transcription`, spec
  `params: {}` — the scan over the channel's 434 items). The move (`01M3TGHZSMQHHYXH44ATXXFKSQ`) was
  queued 21:16:42 and passed the action's busy check (nothing running); the Transcribe all was queued
  and started at 21:23:30 — no marker existed, so its `needsMedia` guard passed, correctly; the move
  started at 21:36:28 after waiting behind other moves on the one relocation queue, and asked nothing
  about the channel's jobs. `v50t5yt`'s transcription (749.78 s) began ≈21:25:37, its parakeet scratch
  dir (`.audio.mp3.parakeet/`, meta + four windows) was copied, and its outputs landed at
  21:38:06–07, after rsync had passed the directory; the verify at 22:02:37 refused (4 differ). The
  batch then **kept writing while the marker stood** — `v511otv` at 22:40:29, `v519k6c` at 23:13:25,
  `v51fpcd`'s scratch from 23:21 — until it was cancelled at 23:29:44: a job's guard ran only at
  enqueue, and its per-video loop never re-asks. The resume (`01M3VX740RAK1H24RZ2CRKYZ79`, 10:17) copied
  the new files and refused on the counts, 1755 against 1750 — the five scratch files on the
  destination, which a copy that never deletes could not settle.
- **The three closes.** (1) The move refuses over a writer at its preview, its job's FIRST STEP and a
  third time right after the copy phase's marker is written (`relocateChannelMedia.ts:167`
  `assertNoWriters`, `:493`, `:551`, `:672` `assertNoWritersUnderMarker` — the third removes a marker
  this run created). (2) A `needsMedia` job's guard is asked again when the queue STARTS it
  (`jobs/streamCommand.ts:429`, `refuseForUnreachableMedia` `:327`), so a job queued before a marker
  and started after it fails before `fn` runs. (3) The per-video writers that were not in
  `JOB_KINDS` at all — `whisper-video`, `transcribe-one`, `download-one-pipeline`, `transcode-audio`,
  `check-availability`, `quick-availability-check`, `check-maybe-missing` (`jobs/jobKinds.ts:577`
  on) — declare `needsMedia`; absent meant false, so none was ever refused. Labels stay absent
  (`/jobs` unchanged). Not in the table and still not refused: `worker-transcribe`/`worker-unit` (this
  box as a worker: a scratch dir or another machine's mount), `refresh-report` (asserts reachability
  itself), and the corpus-wide `normalize-live-chat`/`archive-*` (no slug).
- **Who is a writer: `controller/channelWriters.ts`.** `channelWriters(slug, opts)` (`:89`): registry
  jobs whose `channelSlug` is the slug, running (queued too with `includeQueued`), minus
  `ignoreKinds`, then every lane's in-flight units for the slug (`getAutoRunnerStatus(lane).inFlight`).
  A lane download unit is also an `auto-download-unit` job; it is named once, as the lane's.
  `describeChannelWriter` (`:164`) names the first task's video ("a transcription of v50t5yt is running
  (Transcribe all, job …)"); `channelWritersRefusal` (`:190`) is the move's sentence. The move's job
  passes `ignoreKinds: ["relocate-channel-media"]` (it is itself running on the slug; the relocation
  queue runs one at a time); the preview passes nothing. **The editor's `channelMediaBusyReason`
  (`editor/app/channels/lib/mediaBusy.ts`) reads the same list with `includeQueued`**, keeps its
  counts sentence (the e2e regex `running\/queued job\(s\) for this channel` still matches) and
  appends `Now: <the first writer>.`. Corpus-wide jobs carry no slug and are not writers here:
  `normalizeAll` and `evictClipWindows` re-ask the hold per channel, and the mirror covers a write that
  lands mid-copy.
- **The hold's words: `lib/channelMediaHold.ts`.** `HELD_REASON["in-transition"]` (`:40`) leads with
  "its media is moving (a move is in progress or was interrupted)" — it also reaches both builds' held
  lines. `mediaHoldText(status)` (`:52`) is "held: <reason>" or null — the rack's chip
  (`ChannelTierSelect`, `aria-label="media hold for <slug>"`, visible "media held", the sentence on
  `title` and in sr-only text), the Storage panel's line (`aria-label="media hold"`), the refused
  job's sentence, the runners' skip log. It reaches the row as `ChannelRowView.mediaHold`
  (`views/channelRow.ts:114`) and the panel as a server-computed prop; `lib/storageLocations.ts`
  (imported by the hold module) is never pulled into a client file by this. The runners skip on
  `isMediaHeld` (`autoRunner.ts:641`); their skip log is now `[auto] skipping <slug>, held: <reason>:
  media <status> — <detail>` (the old `media <status> — <detail>` is its tail).
- **The mirror: `controller/relocateDir.ts`.** `MIRROR_ARGS = ["-a", "--delete", "--info=del"]` —
  every removal is a `deleting <path>` line in the job log; the verify's dry run is `VERIFY_ARGS`
  (`--delete` included, so an extra on the destination is a difference, `*deleting`). **`--delete`
  never reaches the live media**: `assertMirrorDirection` (`:468`, asked by `copyMirrorVerify` before its
  FIRST rsync, and by `mirrorTree`) takes `live` from the caller — `channels/<slug>/data` for a
  channel (both directions; resolved through its link, so on the way back it is the relocated
  target) and `paths.savedVideosDir` for the store — and refuses when the destination's realpath is
  the live media's, contains it or is inside it; and when the source and destination contain one
  another. `live` is never derived from `src`/`dest`, so a swapped call is refused with nothing
  spawned (review M1: the first cut compared `dest` with an `underConstruction` every caller set to
  `dest`, which could not fail). `copyMirrorVerify` (`:565`) is the copy phase for both
  movers and both directions: the progress copy (`COPY_ARGS`), the mirror pass, `verifyCopy` in mirror
  mode (`verifyMirrored`, `:709`): an empty itemized dry run plus equal counts; a difference gets one
  more mirror pass (`retried`), a second refuses with `CopyVerificationError` (`:430`) carrying the
  differences by kind (`classifyDrift`, `:391`: `*deleting` → extra on the destination, all-`+`
  attributes → missing on the destination, anything else → changed). **A swap-phase re-verify
  mirrors only from the live media** (`data/` still a real directory, `relocateChannelMedia.ts:872`);
  against a parked `data.relocated-*` it is the strict legacy verify — the target is never mirrored
  from a copy that is no longer live. Resume takes the copy phase again, so stale files on a
  destination are removed.
- **Reconcile and resume** = `relocateChannelMedia({ reconcile: true })`, refused without a marker
  (`relocateChannelMedia.ts:556`): the copy phase skips the progress copy, logs `diffTrees` by kind
  ("Reconciling: the destination copy differs from the source — …"), and the mirror pass carries the
  progress sink. `RelocateChannelMediaResult.reconciled` is true only when the copy phase ran as a
  reconcile; a reconcile of a marker past the copy phase is a plain resume and says "resumed". Editor: `reconcileRelocationAction` (`storageActions.ts:136`, Resume's guards), the
  Storage panel's button beside Resume move (log `"Reconcile and resume output"`), the job's done line
  "(reconciled and resumed an interrupted move)".
- **The saved-video store shares the pipeline** (`relocateSavedVideos.ts` copy phases →
  `copyMirrorVerify`; the swap re-verify mirrors while the store is still a real directory) and takes
  `busy` (`:246`, asked first, `:259`); the editor's job passes the store check with `runningOnly`
  (`editor/app/storage/lib/storeBusy.ts`). It has no reconcile button.
- **A cancel is a request, not an exit.** `registry.cancel` on a RUNNING job sets `cancelled` at once
  (no `endedAt`) and the function winds down; `markTerminal` then skips it, so `registry.finalize`
  stamps `endedAt` itself for a cancelled record that has none, and `forceRelease` does for one never
  finalized. `channelWriters` counts `cancelled` with no `endedAt` as a writer, status "stopping"
  ("— wait for it to stop"). Before this, a job cancelled while running never got an `endedAt` at all
  (the 2026-09-30 Transcribe all's meta has none).
- **The race the third ask leaves is closed by ordering** (the review's trace): `registry.enqueue`
  marks a job running before `start()`, whose guard then reads the marker; a lane unit is in
  `inFlight` before the pick→run backstop reads the marker. Either the third ask sees the writer or
  the writer sees the marker.
- **Not covered:** a corpus-wide
  writer mid-channel when a move starts; a resumed or reconciled move-out is charged the whole tree
  against the destination's free space, not the remainder (move-back charges the remainder).

## Connecting an X account (verified 2026-10-01, branch `r16/x-login`)

- **Why Google refused the Connect window: the automation signals.** Measured on this box under
  Xvfb (headed, no window on the operator's display; the slice's `xl-exp/`), Playwright 1.59.1
  driving system Chromium 153 and the bundled build:
  - Playwright's defaults: `navigator.webdriver === true` and the bar "Chrome is being controlled
    by automated test software" (that is `--enable-automation`).
  - `ignoreDefaultArgs: ["--enable-automation"]` alone: the bar goes, **`navigator.webdriver` stays
    true** — Playwright's `--remote-debugging-pipe` sets it. `--disable-blink-features=
    AutomationControlled` is what turns it off (false, headed and headless).
  - A system Chrome then draws "You are using an unsupported command-line flag" for
    `--disable-blink-features=AutomationControlled`, and for Playwright's default `--no-sandbox`.
    `chromiumSandbox: true` removes the second (the sandbox starts on this box for both builds).
    `--test-type` removes the first: it is Chromium's internal test-harness switch, which makes the
    browser skip its startup bars (`AddInfoBarsIfNecessary` returns before the bad-flags prompt), and
    it sets no automation signal (measured in review: `navigator.webdriver`, `window.chrome`, the
    user agent and the plugin count are the same with and without it; `runtime_features.cc` turns
    `AutomationControlled` on only for `--enable-automation`, `--headless` and the debugging pipe or
    port). ChromeDriver passes `--test-type=webdriver`; the bare switch is used here. It is NOT the
    documented route: that is the `CommandLineFlagSecurityWarningsEnabled` policy, machine-wide,
    root to set, and it would silence the operator's everyday browser too. The bundled Chrome for
    Testing draws neither bar (it honours Playwright's `--disable-infobars`).
  - Not hidden by any of this: the debugging pipe itself, and the headless user agent
    (`HeadlessChrome/…`). Google's sign-in may still refuse; X's password login is the reliable path.
- **The launch options are one pure builder**, `buildXBrowserLaunchOptions`
  (`common/social/xBrowser.ts`): `ignoreDefaultArgs: ["--enable-automation"]` ONLY, `args`
  `--disable-blink-features=AutomationControlled` and `--test-type`, the sandbox on for the headed
  window (it retries without when the host cannot start one). **Never `ignoreDefaultArgs: true`:**
  it also drops `--password-store=basic`, and a system Chromium would then encrypt the profile's
  cookies with the desktop keyring's key, which the bundled headless build that refreshes the jar
  cannot read.
- **Which browser opens.** `ARCHILYZER_X_BROWSER` (a path, or a name on PATH; one that is not an
  executable refuses the connect), else the first of `chromium`, `google-chrome`,
  `google-chrome-stable`, `chrome` on PATH, else Playwright's bundled Chromium. Connect logs which
  (`[x-session] Opening Chromium 153.0.8010.47 Arch Linux at /usr/bin/chromium (found on PATH)…`).
- **The bundled build is chromium-1217, Chrome for Testing 147.0.7727.15** (and its headless shell,
  the same revision): `playwright-core@1.59.1`'s `browsers.json`. `~/.cache/ms-playwright` also holds
  chromium-1234 (151) and two older revisions; this Playwright does not use them.
- **The profile/executable pairing.** A connect writes `archilyzer-browser.json` into the profile
  dir (`{ executablePath | null, version, recordedAt }`). The headless refresh and the Playwright
  fallback fetcher open the profile with the bundled build and fall back to the recorded executable
  when the bundled launch throws. **The refresh never replaces a jar holding an `auth_token` with one
  that has none:** a bundled read that comes back without the login is read again with the recorded
  executable, and when no read finds it the jar is kept and the refresh refuses, saying so — a
  profile written by a newer system browser could open in the bundled build without an error and
  without its cookies. Measured: a profile written by system Chromium 153 (a cookie added, headed and
  headless) opens in the bundled headless shell 147 with the cookie's value readable; `Last Version`
  stays `153.0.8010.47`; 153 re-opens it after. So the fallback is a guard, not the common path.
- **The X login source, `social.x.cookieSource`** (`common/social/xCookieSource.ts`, pure).
  `"browser"` | `"profile"`; absent = **resolved at read time, never stored**: `"browser"` when
  `cookiesFromBrowser` is set and no profile is connected (connected = the broker's exported jar
  carries an `auth_token`, `readXSessionStatus().looksAuthenticated`), else `"profile"`. A stored
  choice always wins. The fetch resolves it per channel against the channel's own
  `cookiesFromBrowser` over the global one (`fetchPosts` → `resolveXCookieSourceFor`).
  **The source, not `cookieMode`, governs the X fetchers**: the browser source passes the spec
  whatever the mode; the profile source keeps the old order (the jar, else the `"always"`-mode
  spec, else a guest run).
- **Where X posts may appear, `social.x.visibility`** (release 17 slice XP; `"public"` default |
  `"private"`, kept by `sanitizeSocial` beside `cookieSource`). **saveSettings' merge is one level
  deep, so a patch `{ social: { x } }` replaces the whole X block**: both X actions
  (`xSessionActions.ts`) write over the block as it is (`socialXPatch`). The rule is
  `common/lib/postsVisibility.ts` (`postsVisibleTo`, `publishedMemberSlugs`): while private, an X
  channel (social, platform `twitter`) is built only into sites with `site.json` `audience:
  "private"`; a public site leaves the channel out WHOLE (posts are all it holds) — its posts
  manifest entry, posts tree, transcripts tree, channel list, `site.json` and `corpus.json` entry,
  and `channel-sites.json`. Applied in `buildIndex`'s per-site loop (the site fingerprint names the
  `withheld` members) and in `compose-site` (which prunes a previously shipped tree); the shared
  posts tree and the LMDB posts sub-DB stay corpus-wide. A private site publishes no `hubUrl`
  (`resolveHubUrl`), its `corpus.json` says `site.audience: "private"`, and every deploy path
  refuses it or its bundle before any upload (`lib/builtExport.ts` `deployAudienceProblem`; the
  bulk deploys skip it). Build & deploy all still BUILDS it.
- **The hub carries no site's data** (release 17 XP review): `public/` is shared, so a hub built after
  a site's compose used to ship that site's data trees. `compose-hub` now removes every per-site entry
  first (`SITE_ONLY_PUBLIC_ENTRIES`) and writes the global `search-aliases.json`; `builtHubProblem`
  refuses a hub bundle carrying a data tree. **compose-site's own stages (summaries, stats,
  duplicates) are trusted from its cache only when `public/site.json` names the site**; the
  per-channel trees keep their signatures across sites.
- **gallery-dl 1.32.9** takes `--cookies-from-browser BROWSER[/DOMAIN][+KEYRING][:PROFILE][::CONTAINER]`
  (yt-dlp's syntax plus `/DOMAIN`) and reads every browser it supports, Chromium's encrypted store
  included, on each run. The spec is passed verbatim (`galleryDlCookieChoice`).
- **Reading Firefox's store ourselves** (`common/social/xBrowserLogin.ts`): for the Playwright
  fallback and the Settings "Check". The store is found much as gallery-dl finds it — a profile path
  or name from the spec, else the most recently modified `cookies.sqlite` under
  `~/.config/mozilla/firefox`, `~/.mozilla/firefox`, Snap, Flatpak, macOS (two levels deep). Not
  exactly: gallery-dl also honours `$XDG_CONFIG_HOME` and a second Flatpak root
  (`~/.var/app/org.mozilla.firefox/config/mozilla/firefox`), and for a profile NAME takes the first
  root holding `<name>/cookies.sqlite` where this takes the newest.
  `cookies.sqlite` **and its `-wal`** are copied back to back to a private `mkdtemp` dir, and the db
  alone copied again from there; both are read and removed; only X's rows are selected; the profile
  is never opened in place. **Two views:** with the WAL (what Firefox holds now — the Playwright
  fallback uses it) and the main file alone (what gallery-dl sees: it opens `cookies.sqlite`
  `mode=ro&immutable=1`, which ignores the WAL, and its fallback copies the db file only). A fresh
  login sits in the WAL until Firefox checkpoints (closing Firefox does it); the Check says so when
  the `auth_token` is in the WAL only.
  **Containers are read as gallery-dl reads them** (`cookies.py` `_firefox_cookies_database`): no
  `::CONTAINER`, or `::none`, = only cookies outside every container (gallery-dl's default; yt-dlp
  reads them all); `::all` = no filter; `::NAME` = the `userContextId` whose `name` is NAME, else whose
  `l10nId` is `user-context-NAME` (or ends `-NAME`), else whose `l10nID` is `userContextNAME.label` —
  case-sensitive. The Check says when an x.com login sits only in a container the spec does not read.
  **A login counts on x.com only** (`.x.com`, `x.com`, subdomains): gallery-dl's twitter extractor
  looks its `auth_token` up on `.x.com`; a twitter.com `auth_token` is reported as the old domain's
  and not counted (`ct0` is not needed — gallery-dl makes one).
  `expiry` is seconds (read as ms when too large for seconds); `lastAccessed` is PRTime (µs). The
  Chromium family is NOT read here (its values are encrypted with a keyring key): the readers say so
  and gallery-dl reads it.
- **gallery-dl 1.32.9's `twitter:search`** (`extractor/twitter.py`, `TwitterSearchExtractor`)
  matches `…/search?…q=<query>` (q may follow other params; `&f=live` after it is fine) and decodes q
  as `unquote(q.replace("+", " "))` — so the query is percent-encoded whole and an encoded `+`
  survives. It reads the query's single `from:<user>` to fill each record's `user` (with the
  account's `date`, its creation time). Product defaults to "Latest"; `search-pagination` defaults
  to `max_id`: after each page it REWRITES the query's `max_id:` (adding one if absent) to just below
  the oldest tweet read and sets the API cursor to None — so **a search run logs no
  `Cursor:` line and cannot be resumed with `extractor.twitter.cursor`**. It stops after
  `search-stop` (default 3) empty pages. Quoted tweets are skipped unless `quoted` is set.
- **The older-posts backfill** (`fetchPosts({ older })` → `SocialFetcher.fetchOlder`; for X
  `fetchOlderViaSearch` in `xGalleryDlFetcher.ts`, window arithmetic in `social/olderBackfill.ts`).
  Windows of 3 months in UTC days, `from:<h> since:<d> until:<d> include:nativeretweets`, the first
  ending the day after the oldest archived post; one gallery-dl run per window, a random 45–120 s apart (every X request itself waits a random 4–10 s: `sleep-request=4.0-10.0`, `ratelimit=wait`), one
  3-hour budget across them. Its resume point is its own: the oldest post id read in the window,
  sent back as `max_id:<id>` (inclusive; gallery-dl's rewrite replaces it). State is
  `posts-state.json` `older` (`OlderBackfillState`), apart from the timeline `cursor`; a normal fetch
  copies `older` through untouched and an older run copies every other field through. Ends at the
  later of the `floor` and the account's creation day, or after 4 empty windows in a row; then
  `older.complete` and a re-run fetches nothing. No login = refused before spawning
  (`needsCookies`). It does not stamp `lastSyncedAt`.
- **`node:sqlite`** (Node 22.23 here; unflagged since 22.13, an ExperimentalWarning once per process)
  is loaded at run time through an assembled specifier with `webpackIgnore`
  (`common/social/nodeSqlite.ts`), like `playwrightRuntime.ts`: the editor's Turbopack build has
  nothing to resolve, and the repo's `@types/node` (20) has no types for it, so they are structural.
- **The e2e never reads a real browser.** `x-session.spec.ts` writes a Firefox store under
  `test-transcripts/` (`common/social/__fixtures__/firefoxCookieStore.ts`, imported by relative path)
  and points `cookiesFromBrowser` at it as `firefox:<abs path>` — a profile PATH in the spec, so no
  home directory is searched.

## umtool's deliverables switch (verified 2026-10-01, branch `r17/umtool-deliverables`)

- **`clips/` and `share-*/` of a report project may be links** into `UMTOOL_MEDIA_DIR` — per project,
  when `video.manifest.json` says `"storage": { "deliverables": "media" }` (absent = local). `out/` is
  the other directory that may be a link, and it follows `UMTOOL_MEDIA_DIR` on its own (slice U1).
  Readers open `clips/<id>.mp4` by path through the link; a dirent `isDirectory()` filter over a
  project hides a moved one (`listBatches` follows links for that reason).
- **One writer for the value:** `updateStorage` in `umtool/lib/report/manifest.mjs`, called only by
  `moveDeliverables` (`umtool/lib/report/storage.mjs`) after every directory has moved. A no-op is not
  rewritten.
- **A missing deliverable directory is made by `deliverableDir(project, name)`** — never a bare
  `mkdir` (`cut.mjs`, `buildShareBatch`). Under `"media"` it is a link to a new mirror directory; the
  media root is never created; a dangling link, a cut move's leftover (`<name>.moved-*`,
  `<name>.incoming`), a bad value, or `"media"` in a process without `UMTOOL_MEDIA_DIR` refuse.
- **`umtool storage deliverables <project> --to media|local`** is the move (the bench's "Move
  deliverables" runs it as a job). It, and `move-out`/`move-back`, refuse a project while
  `lib/report/busy.mjs` sees a pipeline process in it: a script argument under the project directory
  (the build steps), a `--project` value equal to the project's id or name or resolving to its
  directory (how the app runs `cut-from-cache.mjs` and `share-batch.mjs` — matched whole, never by
  prefix), or `apply-manifest.py`/`build.py` by cwd. A hand-run command that is none of these, and
  another machine, are not seen. `umtool check` reports `storage-unreachable` (blocking: an `out`,
  `clips` or `share-*` link whose target is gone) and `storage-mismatch` (open).
- The e2e app server has no media root (`UMTOOL_MEDIA_DIR=` in `playwright.config.ts`); specs give
  their CLI one (`<fixture>-media`), so `deliverables.spec.ts` shows an app cutting through a link it
  did not make and refusing a new batch under `"media"`.

## A persisted container's format is not in `metadata.info.json` (2026-10-04)

- **The info json on disk describes the PREFETCH's format, not the download's.** The metadata
  prefetch writes it with `--skip-download` (yt-dlp's default selector), and every later pass reads
  it back with `--load-info-json` and does not rewrite it. Its top-level `format_id`/`height`/`vcodec`
  can name a 1080p format for a file downloaded at 720p.
- **`requested_downloads` is never in it.** yt-dlp sets that key in `process_video_result` after
  `process_info` has written the file (`YoutubeDL.py`, `info_dict['requested_downloads'] = …` just
  before `run_all_pps('after_video', …)`), so only an `after_video` print can see it.
- So a persist pass prints `DLOM_FORMAT %(requested_downloads.0.height)s …vcodec…format_id` (the
  `FORMAT_MARKER` in `common/ytdlp/runOneYtdlp.ts`), and the saved-video pointer's `format` is read
  from that line (`savedVideoFormatFromLine`). A field yt-dlp lacks prints as `NA`.
- **Source-video quality resolves through `resolveSourceVideoQuality`** (`common/ytdlp/downloadFormat.ts`):
  per-persist override > `ChannelConfig.sourceVideoQuality` > settings `sourceVideoQuality` >
  `"original"`. `downloadOneManaged`'s `persistFormatPreset` takes the result; unset is the historical
  `bestvideo*+bestaudio/best`. The download lane's keep-latest persists pass nothing, so they stay
  `"original"`.

## The publish stages (verified 2026-10-06, branch `r18/surfaces` @ `5a77682e`)

The record is [`release-18.md`](release-18.md) ("Slice S1/S2/S3/S5, as shipped"). Every anchor below
was read at that tip. Release 18 replaced the one-shot build and deploy jobs with seven queueable
stages driven by stamps on disk; the facts above that describe `export/out` as the shared deploy
source, a site build's data phase, Build all, `pnpm dlx wrangler` or the in-process Build index /
Build stats jobs carry a "Superseded by release 18" line pointing here.

### The seven stages and their targets

- **`common/publish/stages.ts` is the only module that knows every stage.** `StageKind`
  (`:33-40`): `update-index`, `build-site`, `deploy-site`, `build-hub`, `deploy-hub`,
  `build-homepage`, `deploy-homepage`. `STAGES` (`:406-420`) gives each a label, `jobKind:
  publish-<kind>` and `queueKey: "publish"` (`stage()`, `:390-404`), a pure `needs()`, `argv`
  (`stageArgv`, `:305-316`) and a `run` that lazily imports `stageBodies.ts`.
- **Targets** (`stamps.ts:22-25`): `_index` (update-index), a site id (build-site, deploy-site),
  `_all` (build-site only), `_hub`, `_homepage`. `fixedTarget` (`stages.ts:334-339`) pins the hub's
  and the homepage's kinds to their one target, and `parseStageArgs` (`:345-384`) refuses any
  other target for them ("stage deploy-homepage: the target is _homepage") and a `_`-target for a
  site kind except `build-site _all`. `--run-id` is required; `--preview` with `--to local` is
  refused.
- **`StageRequest`** (`:56-73`): `{kind, target, runId, preview?, to?: pages|local, runner?:
  local|docker, force?, skipArchives?, indexAfter?, builtAfter?, allowMissingMedia?}`. `indexAfter`
  / `builtAfter` are ms times: the on-disk preconditions of a run.

### The stamps — `common/publish/stamps.ts`

- **Three files** (`:128-142`): `<exportIndexDir>/stamp.json` (`IndexStamp`, written by
  update-index), `<exportBuildsDir>/<target>/built.json` (`BuiltStamp`, the build stages) and
  `<exportBuildsDir>/<target>/deployed.json` (`DeployedFile`, the deploy stages). `target` is a
  site id, `_hub` or `_homepage`. By default `exportIndexDir` is `export/.export-index` and
  `exportBuildsDir` is `export/.export-builds` — siblings of `export/public` (`paths.ts:212-214`,
  `:253-255`); `EXPORT_INDEX_DIR` / `EXPORT_BUILDS_DIR` override them (the compose file sets
  `/data/builds/.export-index` and `/data/builds/.export-builds`, `docker-compose.yml:71-72`).
- **`IndexStamp`** (`:27-54`): `stampId`, LMDB `generation`, `scannedAt` (`INDEX_SCANNED_AT_KEY`:
  when the completed scan began), `builtAt`, `templatesAt`, `commit`, `index {shortCircuited,
  added, changed, removed, heldChannels}`, `stats {shortCircuited, notIndexedYet, notIndexable}`,
  `sites[id] {siteFp, statsFp, inputSig}`, `hubSig`, and `settingsSig?` (`indexSettingsSig` over
  the settings the index read; a stamp without one reads as changed, once).
- **`BuiltStamp`** (`:59-83`): `stampId`, `target`, `kind: site|hub|homepage`, `indexStampId`,
  `inputSig`, `builtAt`, `checkedAt?` (a later no-op build found the bundle still current),
  `commit`, `branch`, `runner: local|docker`, `audience`, `corpusGeneratedAt`, `files`, `bytes`,
  `archivesStaged`, `sourceCommit?` (homepage). **`DeployedFile`** (`:118-124`) holds one
  `production`, one `local` and `previews[branch]`; `recordDeploy` (`:263-275`) replaces one slot
  and keeps the others.
- **Malformed = null = stale.** Writes are atomic (`writeJsonAtomic`); every read goes through
  `readAs` (`:216-219`) and a shape check (`asIndexStamp` `:163`, `asBuiltStamp` `:182`,
  `asDeployedFile` `:205`): a missing, unparseable or wrongly-shaped file is `null`, and `null` is
  "no stamp" to every `needs()` (header `:8-11`). A build removes its old `built.json` before the
  swap and writes the new one last (`build.ts:935`, `:966`; `stageBodies.ts` `stampBuilt`).
- **`commit` / `branch`** come from `checkoutInfo` (`stageBodies.ts:100-109`):
  `ARCHILYZER_COMMIT` / `ARCHILYZER_BRANCH` WIN over git, each on its own (the image bakes them;
  the e2e server sets the branch); else git's HEAD, and a detached HEAD records `branch: null`.
- **The update-index stage keeps its stamp id when nothing changed** (`stageBodies.ts:277-290`):
  both builds short-circuited, the same `generation`, every site's `inputSig` and the `hubSig`
  unchanged. The outcome is `noop`, and the builds made from that index stay current. `builtAt` is
  still rewritten (`:297`), so a run's `indexAfter` is met by a no-op index update.

### The publish lock — `common/publish/stageLock.ts`

- **`<exportBuildsDir>/.publish.lock`** (`:58-60`), JSON `{pid, host, kind, target, since,
  pidStart}`, taken with `open(…, "wx")` (`:218`) by every stage: the child the editor spawns and
  the CLI (`stageRun.ts:96`). One publish stage at a time per builds dir, whoever started it.
- **The host is `ARCHILYZER_HOST_ID` when set, else `os.hostname()`** (`lockHostId`, `:92-94`).
  The compose file sets `ARCHILYZER_HOST_ID: archilyzer-editor` on the editor service only
  (`docker-compose.yml:127`).
- **Stale only on the same host with the holder gone** (`holderIsGone`, `:135-147`): the pid is
  dead (`processIsAlive`), or answers with another `/proc/<pid>/stat` start time, or names a
  process that started more than 2 s (`START_SLACK_MS`) after the lock's `since`. Without `/proc`
  only pid-alive is asked. **Another host's lock is never judged stale**; the wait line names both
  hosts and the file to remove (`:252-259`). A torn (unparseable) lock is taken over after 60 s
  (`LOCK_TORN_GRACE_MS`, `:49`, `:238-245`). A live holder is waited for: a 5 s poll
  (`LOCK_POLL_MS`), one log line, and the stage's signal cancels the wait (exit 130,
  `stageRun.ts:102-104`). Release removes the file only if it is still this holder's (`:271-276`).

### Bundles — `<exportBuildsDir>/<target>/out`

- **Every deploy ships `<exportBuildsDir>/<target>/out`** (`bundleDir`, `build.ts:745-747`), the
  homepage excepted: its bundle stays `homepage/out` (`homepageOutDir`, `:630-632`) and only its
  stamps live in `<exportBuildsDir>/_homepage/`. The hub's bundle is `_hub/out`.
- **The local runner still builds into the checkout's `export/out`** (Next's `distDir` may not
  leave the project), then installs it (`installBundle`, `:804-823`): moved to `out.next`, then
  `out → out.prev`, `out.next → out`, `out.prev` removed; a leftover `out.next` is deleted first; a
  rename that fails EXDEV is a copy + remove. `recoverInterruptedInstall` (`:790-798`) renames an
  `out.prev` with no `out` back before any build or install.
- **`export/out` is a relative SYMLINK to the bundle built last** (`pointExportOutAt`,
  `:836-844`); `unlinkExportOut` (`:829-833`) removes the link before each build, so a failed build
  cannot leave an older bundle readable there. `.gitignore:62` is `/export/out` (no trailing slash:
  the link is not a directory to `**/out/`). Seen 2026-10-06 in a worktree after an e2e run:
  `export/out -> ../editor/test-transcripts/.export-builds/pubsite/out` — the test server's builds
  link the CHECKOUT's `export/out` (`exportDir` is always `<repo>/export`, `paths.ts:206`).
- **A site's oversize archives** are staged at `<exportBuildsDir>/<id>/.r2-staging/<id>/archives`
  (`dockerSiteStagingDir`, `:43-45`) for both runners (`stageSiteArchives`, `:852-869`).
- **`buildSiteBundle`** (`:909-949`) runs `buildSiteSteps` with `skipData: true` (compose:site,
  then `next build`; the data phase is update-index's), `builtBundleProblem` over `export/out`, then
  install, staging, link. **`buildHubBundle`** (`:951-971`) runs `buildHub` (removes
  `public/site.json`, compose:hub, `INSTANCE_MODE=hub` `next build`), `builtHubProblem`, install,
  link.

### What makes each stage stale — `needs()`

- **update-index** (`needsIndex`, `stages.ts:163-177`): no stamp; forced; an ingest job ended
  `done` after `stamp.scannedAt` ("new data since the last index"); a config file newer than
  `scannedAt`; or `settingsSig` differs from the stamp's ("the settings the index reads changed").
  The ingest signal is every job meta whose kind is in `INGEST_KINDS` (`jobs/jobKinds.ts:943`,
  `isIngestKind` `:980`) ended `done`, plus each `channels/<slug>/snapshot.json` mtime (the lane
  units that make no job record; `publishState.ts:194-209`, `:312-315`). The index's config files:
  `tags.json`, `search-aliases.json`, `duplicates*.json`, every `sites/*/site.json`,
  `homepage.json`, the charts config (`publishState.ts:317-331`). **The settings are judged by
  signature, never the file's mtime:** `indexSettingsSig` (`inputSig.ts:171-184`) over
  `socialLinks`, `homepageUrl`, `buildArchives`, `archiveStorage`, `social.x.visibility`,
  `maxTranscriptPageBytes` and the storage locations' `[id, root]`.
- **build-site** (`needsBuildSite`, `:211-227`): BLOCKED "update the index first" with no stamp
  (forced too), "waiting for the index update this run started" while `stamp.builtAt <
  indexAfter` (`indexGate`, `:180-187`), and when the stamp has no entry for the site. Then stale
  (`builtStale`, `:199-209`), in order: forced; never built; `changedChannels` ("N channels changed
  (a, b, …)"); a config file newer than `builtCheckedAt(built)` = max(`builtAt`, `checkedAt`)
  (`:195-197`); `built.inputSig !== stamp.sites[id].inputSig` ("data changed"); a bundle problem.
  `_all` is stale when any site is. A different `built.commit` is NOT stale (the status's
  `codeNewer` chip, `publishPlan.ts:444`).
- **build-hub** (`:229-235`): as a site, against `stamp.hubSig`. `hubInputSig` (`inputSig.ts:202-214`)
  signs the stamp id, `homepage.json`'s bytes and each listed site's id + `siteUrl` + title — so
  EVERY new index stamp id stales the hub.
- **build-homepage** (`:237-249`): `built.indexStampId !== stamp.stampId`; `built.sourceCommit` ≠
  `main`'s head when a repository answers; a bundle problem. Its `built.inputSig` is the stamp id
  (`stageBodies.ts:522`).
- **deploy-*** (`needsDeploy`, `:261-299`): BLOCKED by a private target (`deployProblem`), no Pages
  project (`pagesProblem`, not for `--to local`), no build ("no build of X — archilyzer publish
  build X"), `builtAfter` not met (unless the bundle matches the current index and that index ran
  at or after `builtAfter` — a run's no-op build), a bundle problem, and **a production deploy of a
  build whose `branch` is not `main` — `null` included** (`:287-293`). Then stale when forced or
  when `deployed[kind/branch].builtStampId !== built.stampId`.
- **`inputSig`** (`siteInputSig`, `inputSig.ts:100-146`): the site's whole `.export-index/sites/<id>/`
  tree (`chart-templates.json` by its bytes), each PUBLISHED member's shared transcripts / subs /
  posts / digests tree (`manifest.json` ignored), `site.json`'s bytes, the `sites/<id>/` dir, the
  global aliases, curated tags and duplicates files (size + mtime), `archiveStorage` + X visibility
  + `buildArchives`, the resolved social links, hub url and footer siblings. A superset: a needless
  rebuild, never a wrong skip.

### Who asks `needs()`, with what

- **The status asks with every signal; a stage child asks with signatures only.** `needsInputOf`
  (`publishPlan.ts:296-321`) fills `changedChannels` (a site's members with an ingest after
  `builtCheckedAt`; the hub's: the listed sites' members; the homepage's: every channel with a
  signal), the config mtimes and `settingsSig`. The child's `readNeedsInput`
  (`stageBodies.ts:132-173`) leaves `changedChannels` empty, `configChangedAt` null and
  `settingsSig` absent: the child rebuilds only when forced, never built, its signature moved or
  its bundle is wrong. A build the plan chose for changed channels that the index update then
  finds unchanged is a no-op that writes `checkedAt` (`markChecked`, `:416-418`), which clears the
  chip.
- **update-index's body never asks `needs()`** (`runStageBody`, `stageBodies.ts:549`): run, it
  always runs `buildIndex` → `buildStats` → the chart templates in one child, then the stamp.
- **Every other body asks first** (`:566-592`): blocked → `StageFailure` exit 3; fresh and not
  forced → `noop` (a build's no-op writes `checkedAt`).

### Exit codes

- `STAGE_EXIT` (`stageRun.ts:25-31`): **0** ran or no-op, **1** failed, **2** usage, **3**
  precondition not met, **130** cancelled. A `DeployStageError` carries its own code and its
  sentence is not printed twice (`:125-133`).
- **`pnpm --filter … exec` collapses 2, 3 and 130 to 1.** Measured 2026-10-06 on pnpm 11.26.0 in a
  scratch workspace: `pnpm --filter <pkg> exec sh -c 'exit 3'` exits 1 with
  `ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL … Command failed with exit code 3` (130 the same); a plain
  `pnpm exec` in a single package passed 2, 3 and 130 through. The root `archilyzer` script is
  `pnpm --filter yt-dlp-transcript-common exec tsx bin/archilyzer.ts` (`package.json:8`), so
  `pnpm archilyzer publish …` reports 1 for any non-zero code. The editor spawns `tsx` directly
  (`stageCommand`, `stageRun.ts:50-68`) and sees the real code.

### The queue, the runs, the lane

- **One stage = one `runManagedCommand` job on queue `publish`** (`enqueueStage`,
  `publishStages.ts:113-139`), the child `<common>/node_modules/.bin/tsx bin/archilyzer.ts stage
  <kind> <target> …`, cwd `common/`, update-index with `--max-old-space-size=8192`
  (`stageRun.ts:50-68`). Cancel kills the child; the child traps SIGTERM and tree-kills its
  children (`stageMain`, `:156-178`). The spec is `{kind: publish-<stage>, slug: target, params:
  the request}` (`stageSpec`, `:82-86`) — Retry replays it. A duplicate (same kind, target and
  destination queued or running) is refused `{ok: false, info: true, jobId}` (`:118-126`).
- **Order is on disk, not in memory.** `enqueuePublishRun` (`:162-196`) enqueues a whole plan
  under one run id; builds carry `indexAfter`, deploys `builtAfter`, and a child whose
  precondition is unmet exits 3. /jobs shows `run <last six of the run id> · <target>`
  (`jobs/jobDetail.ts:24-29`). At boot a queued publish stage is cancelled — "server restarted; the
  publish lane re-derives stages from on-disk state" — never re-queued (`bootQueuedJobs.ts:63-64`,
  `:292-293`).
- **`publish` is a PIPELINE lane, not in `LANES`** (`PIPELINE_LANES`, `lib/autoQueueTypes.ts:219`;
  `LANES` `:203`). `PauseLane = AutoQueueKind | PipelineLane` (`lib/pauseGates.ts:53`);
  `isGateHeld` / `withGateHeld` read and write `settings.publish.held` for it (`:104`, `:125-127`).
- **`settings.publish`** (`defaultPublish`, `lib/settingsSchema.ts:1624`; `sanitizePublish`
  `:1651`): `{enabled: false, held: false, checkEveryMinutes: 10 [1–1440], refreshEveryMinutes: 360
  [0–43200], quietHours: null, runner: "local", previewBranch: "preview", hub: "off", homepage:
  "off"}`. A site's policy is `site.json` `publish.auto` (`sitePublishPolicy`,
  `lib/siteSchema.ts:239`: absent = off); `preview` / `production` clamp to `build` for a private
  site or one with no `cloudflareProject` (`clampSitePublishPolicy`, `:228-236`).
- **The runner** (`publish/publishRunner.ts`): kind `auto-publish`, queueKey `""`
  (`startPublishRunner`, `:286-314`; `jobKinds.ts` `auto-publish` drainable). It wakes every
  `checkEveryMinutes`; a pass is due (`publishPassDecision`, `publishPlan.ts:555`) with no stamp,
  when the index is stale and the stamp is `refreshEveryMinutes` old, or when a policy target is
  left stale and the last pass is that old; never while off, held, in quiet hours or with any
  publish stage queued or running (`laneBlockedReason`, `:534`). **A pass re-reads the status
  and re-plans before EACH stage** (`runPublishPass`, `publishRunner.ts:110-219`), dispatches one
  stage (`background: true`) and awaits its end; a failed index update ends the pass; a failed build
  drops its deploy. **A hold, quiet hours or the lane switched off stop the dispatching, never a
  stage** (`gateShut`, `:89-94`). A drain lets the stage in flight finish; **Stop ends the runner
  and does not cancel the stage in flight** — it is its own job (`:178-191`, `stopPublishRunner`
  `:322-327`). Started from `editor/instrumentation.ts:226-237`, below the idle-boot return
  (`:191`).
- **The plan** (`planPublishRun`, `publishPlan.ts:758`): update-index when the index is stale;
  per site (by id) its build when `needs()` says stale and its policy is not off (else skipped
  "stale, and its policy is off", unless `builds: "stale"`), and its deploy where `publish.auto`
  says; `settings.publish.runner: "docker"` plans one `build-site _all --runner docker`; then the
  hub, then the homepage, by `settings.publish.hub|homepage`. Never forced.

### The surfaces

(Anchored by symbol; verified at the S4 merge, `dddbc183`.)

- **Every editor surface, and the ops routes through `api/ops/_publish.ts`, enqueue through
  `editor/app/sites/lib/publishCore.ts`**: `wantedPlan` puts the index update first when the index
  is not fresh and a build is asked, builds `--force`, and gives a deploy `builtAfter` when its
  build is in the run; `refusal` answers with the deploy stage's own `resolveDeployRequest`
  sentence before any job. `publishActions.ts`: `publishNowAction` = `planPublishRun(status,
  {deploys: "policy"})`, `buildAllStaleAction` = `{builds: "stale", deploys: "none"}`,
  `updateIndexAction` (the Pool's Build index) = the update-index step always (`indexPlan`; the
  child runs, and ends `noop` when nothing changed), `deployTargetAction` deploys with `force:
  true`. Nothing builds in the editor's process. `publishRunStream.ts` `followRun` joins a run's
  jobs into one console.
- **`editor/app/api/ops/publish/route.ts`**: `POST {verb: index | build | deploy | hub | homepage
  | now | stale, …}` (`VERBS`); `GET` returns `readPublishStatus`. The old
  routes (`build-site`, `build-deploy`, `deploy-site`, `build-hub`, `deploy-hub`, `build-homepage`,
  `deploy-homepage`, `build-index`) are aliases over the same stages; `build-site` accepts and
  ignores `skipData`.
- **One status:** `readPublishStatus` (`publish/publishState.ts:400-406`) is what the /sites panel,
  the ops route, `archilyzer publish status` and the lane read.
- **A console's Cancel is the run's**: every publish console (the /sites rows, Publish now, Build all stale,
  the Pool's Build index, a site's Publish tab) cancels through `cancelPublishRunAction`
  (`sites/lib/publishActions.ts`), which cancels every queued or running `publish` job whose
  `spec.params.runId` is the console job's, newest first. `followRun` also cancels a run's later jobs when one
  ends `cancelled`, but never a part another run queued (`RunPart.existing` — a duplicate stage answered by
  `enqueuePublishRun` with the existing job's id), and the console's job is the first this run enqueued.
- **Refused before any job** (`publishCore.ts` `refusal`): an unknown site (`no site "<id>"`), a preview with
  no or a bad branch name (`previewBranchProblem` — never let fall to production), and every
  `resolveDeployRequest` sentence, except "no build of X" when the run builds first. The ops route also refuses
  a local deploy with a preview, and `{build, runner: "docker"}` puts the index update first when the index is
  not fresh (`indexAfter` on the `_all` build). One target's throw is that target's refusal (`_publish.ts`).
- **CLI:** `publish hub|homepage --deploy-only [--force]` ships the bundle as built (`--force` re-ships);
  `--deploy` with `--deploy-only` is a usage error (exit 2); `deploy hub|homepage` are its printed aliases.
  `build hub` and `build homepage` stay RAW builds that stamp nothing (export's `build:hub`, which e2e:2origin
  runs) — a deploy stage never ships them.

### The deploy stage

- **`runDeployStage`** (`publish/deployStage.ts`, order in its header `:16-40`) asks the request
  (exit 2), the target's refusals (exit 3), `built.json` (exit 3 "no build of X in <dir>"), the slot
  already holding this `stampId` (a no-op unless forced), production-only-from-`main` (exit 3), the
  bundle guards (exit 3), then `--to local` (into `ARCHILYZER_SITE_OUT` / `ARCHILYZER_HOMEPAGE_OUT`,
  unset = exit 3) or the credential preflight (exit 1), R2, the pinned wrangler, the live check, and
  LAST `recordDeploy`. Nothing is written to `deployed.json` on a refusal.
- **wrangler is pinned**: `common/package.json:94` `"wrangler": "4.147.0"`; `wranglerBin`
  (`lib/pagesDeploy.ts:101-106`) = `WRANGLER_BIN`, else `<repo>/common/node_modules/.bin/wrangler`;
  `pagesDeployArgs` always passes `--branch` (`main` for production, `PRODUCTION_BRANCH`, `:68`). Nothing
  spawns `pnpm dlx` any more: `git grep "pnpm dlx"` over `common/`, `editor/`, `export/`,
  `homepage/`, `scripts/` and `docker/` finds one comment (`pagesDeploy.ts:21`) and the changelog.
- **The live check** (`publish/liveCheck.ts`): `<url>/corpus.json` plain and `?cb=<builtStampId>`
  (`&try=N` on a retry, `:67-70`), 3 tries 10 s apart (`:57-58`); verdicts `ok`, `stale-edge`,
  `mismatch`, `unreachable`, `skipped` (`E2E_LIVE_CHECK=skip`, `:163`) — a warning, never a failure.
  The hub's deploy also probes its tombstones (`deployStage.ts:537`).

### The hub's bundle check — `builtHubProblem`

- `common/lib/builtExport.ts:422-454` refuses a hub bundle that holds a `site.json` (any site's), or
  no `hub-sites.json`, or any of `HUB_FORBIDDEN_TREES` (`:510-519`: `summaries`, `transcripts`,
  `subs`, `posts`, `digests`, `stats`, `archives`, `media`) — except a `posts/` that
  `isTombstonePostsTree` (`:460-501`) finds holds tombstones only (an empty posts manifest; per
  channel a `pageCount: 0` manifest with no `slugToPage` and only `[]` `page-N.json` files).
- **`reports/` and `m/` are not refused as trees** — the export app renders `reports/index.html`
  and the `_none` placeholder pages into every build. `hubReportDataIn` (`:541-571`) looks for report
  DATA by name instead: `reports/index.json`, `m/index.json` (`REPORTS_INDEX_PATH` /
  `MOMENTS_INDEX_PATH`, `lib/report/views.ts:71-72`), under `reports/` any `page.json`,
  `citations.json`, `citations.csv`, `report.html`, `report.pdf`, `report.md`, `evidence-pack.zip`
  or `history.json` below the top level, any `reports/**/history/repo/`, and any
  `m/**/moment.json`.
- Its sentences still say "export/out"; the deploy stage rewrites that prefix to the bundle's
  directory (`deployStage.ts:436`).

### Tombstones — `common/publish/tombstones.ts`

- **The hub tombstones only X channels that are a member of at least one non-private site**
  (`withdrawnXChannels`, `:157-183`): only while `social.x.visibility` is private, only channels
  with a shared posts tree, and the site list is `listSites(paths)` — every configured site
  (`bin/compose-hub.ts:142`), filtered by `isPrivateSite` alone (`audience === "private"`,
  `lib/siteSchema.ts:94-96`). So **a member of an unlisted site or a cited (report-only) site is
  still tombstoned**; a channel only private sites carry, or no site, is never named on the hub.
- A tombstone (`writePostsTombstones`, `:89-116`) is the channel's posts manifest at `pageCount: 0`,
  `maxPageBytes: 0`, `slugToPage: {}`, plus `[]` for every page below the SHARED tree's
  `pageCount`; the hub adds an empty `posts/manifest.json` (`compose-hub.ts:137-155`). `_headers`
  serves them `Cache-Control: no-store` (`renderHeadersFile` `noStore`, `lib/archive/headers.ts:103`;
  the hub `/posts/*`, a site `/posts/manifest.json` + `/posts/<slug>/*`, `tombstones.ts:137-145`).

### The `publish/` layering

- `common/architecture.test.ts` `FORBIDDEN` (`:31-52`): `lib` may not import `publish` (`:38`),
  `jobs` and `controller` may not import `publish` (`:39-40`), and `publish` may not import `views`
  or `components` (`:51`). `views` may import `publish`: `views/publishStatus.ts` re-exports
  `publish/publishPlan.ts`. That is why the status builder, the enqueuer and the runner live in
  `publish/`, not `controller/`, and why the runner is started from `instrumentation.ts`, not from
  `controller/autoRunner.ts`.
- **Only static imports are checked** (`IMPORT_RE`, `:106-107`): a dynamic `import()` is not seen.
  `stages.ts` and `stageBodies.ts` load `build.ts` and the bodies lazily for weight, not to dodge it.

### The e2e seams — `editor/playwright.config.ts`

- `E2E_SERVER_ENV` (`:68-80`) gives the editor's test server: `E2E_LIVE_CHECK=skip`;
  `WRANGLER_BIN` → `e2e/fixtures/bin/fake-wrangler.mjs`; **`ARCHILYZER_BRANCH=main`** (a worktree's
  branch is never `main`, and production refuses any other); **`CLOUDFLARE_API_TOKEN` a dummy**
  (`e2e-fake-token-never-sent`: the preflight asks for one, the fake never sends it, and the suite
  must not lean on the host's `wrangler login`); `EXPORT_NEXT_BIN` →
  `e2e/fixtures/bin/fake-next.mjs`.
- **`fake-next.mjs`**: `build` copies `EXPORT_PUBLIC_DIR` to `./out` (cwd `export/`) and writes an
  `index.html` — compose runs for real, nothing is rendered. `nextBuildStep` (`build.ts:112-117`)
  runs `<EXPORT_NEXT_BIN> build` when set, else `pnpm exec next build`.
- **`fake-wrangler.mjs`**: `pages deploy <outDir> --project-name <p> --branch <b>` appends
  `{argv, cwd, project, branch, outDir, files}` to **`.fake-wrangler.json` beside the bundle**
  (`<exportBuildsDir>/<target>/.fake-wrangler.json`, `:106`) and prints wrangler 4's success lines;
  **auth-fail mode** comes from the MODE sidecar `.fake-wrangler-mode.json` `{"authFail": true}`
  (looked for in `EXPORT_BUILDS_DIR`, then `<dirname(EXPORT_PUBLIC_DIR)>/.export-builds`, then two
  levels above the bundle, `:58-74`) or `E2E_FAKE_WRANGLER_AUTH_FAIL=1`: it prints
  `Authentication error [code: 10000]` and exits 1 with no argv sidecar. `--version` answers
  `4.147.0`. `publish.spec.ts` reads and writes both under `test-transcripts/.export-builds`
  (`:32`, `:65`, `:174`).

## Main's October work, outside release 18 (verified 2026-10-09, `4cffda3f`)

The record is [`landed-2026-10.md`](landed-2026-10.md). Every anchor below was read at `4cffda3f`.

### `pnpm ops transcribe` — one local file through the editor's workers

- **The body is `path`, `start`, `end`, `workerId`, `out`, `words`** (`TRANSCRIBE_FILE_BODY_KEYS`,
  `common/controller/transcribeFile.ts:71-78`); any other key is a 400. `path` is absolute and may be anywhere,
  the corpus included (`:15-17`); `out` is refused inside any corpus root (`:307`); `"words"` must be a boolean
  (`:171`).
- **Job kind `transcribe-file`** (`:64`), `queueKey: ""` (`:547`): parallel at the queue; the worker pool
  serialises it (`common/jobs/jobKinds.ts:884-896`, not drainable, not replayable). Only `kind: "local"` workers;
  default = the one auto-transcribe would get.
- **The audio is always a 16 kHz mono WAV cut by ffmpeg** into scratch (`:21-25`, `:374`), so parakeet's wrapper
  never writes beside the source.
- **The result** (`TranscribeFileResult`, `:107`) carries `cues` (seconds, shifted back onto the SOURCE file's
  clock), `text`, `worker`, `durationMs`, and with `"words": true` a `words` array of
  `TranscribedWord = {w, start, end, conf?}` (`:97`). Only parakeet emits word timings (`--words`,
  `common/lib/transcriptionApps.ts:252-256`); any other engine gives `words: []`.
- **`durationMs` includes the wait for a worker**: `started` is taken at `:444`, before the ffmpeg cut and the
  "Waiting for a free local worker…" lease (`:472`); it is read at `:511`. (Release 19 B4 changes this.)
- **The job's last log line is `@@transcribe-result <json>`** (`TRANSCRIBE_RESULT_MARKER`, `:68`, the same
  string at `scripts/archilyzer-ops.mjs:205`); `pnpm ops transcribe --wait` prints that JSON alone on stdout
  (`resultMarker`, `:331`).

### Refresh one video's metadata

- **Job kind `refresh-metadata`** (`REFRESH_METADATA_JOB_KIND`, `common/controller/refreshVideoMetadataJob.ts:47`;
  `common/jobs/jobKinds.ts:648-656`: platform-queued, replayable, `needsText`). It runs on the channel's
  download queue (`resolveQueueKey(downloadQueueKey(channelConfig), …)`, `refreshVideoMetadataJob.ts:95`); a
  rate limit records the platform's backoff, a clean pass settles it (`:115-116`).
- **One yt-dlp spawn**: `--skip-download --write-info-json`, no subtitles, `--sleep-requests 1`, the channel's
  extra args before the negations (`buildRefreshArgs`, `common/controller/refreshVideoMetadata.ts:181`).
- **The rewrite goes through `withMetadataHistory`** (`:424`) as writer `"refresh"` (`:418`;
  `common/lib/metadataHistory.ts:80`), so what moved lands in `metadata.history.json`.
- **Refused:** a video with no `data/<id>/` (`notFetchedRefusal`, `:92` — the directory is never created); a
  record a non-yt-dlp writer owns — archive.org, Wayback, feed backfill (`NON_YTDLP_WRITERS`, `:154`); a held
  or cooling platform. The same server action backs the video page's button and `POST /api/ops/refresh-metadata`
  `{slug, id, queueKey?}`.

### fetch-windows — a paced batch of clip windows

- **One job per queue key, and the WINDOW'S URL picks it**, not the channel's (`planFetchWindows`,
  `editor/app/channels/[slug]/videos/fetchWindowsAction.ts:165-169`, `queueKeyForUrl`). Job kind
  `fetch-windows`: platform-queued, drainable, replayable, `needsText` (`common/jobs/jobKinds.ts:318-326`).
- **Pacing:** at least `CLIP_WINDOW_MIN_GAP_SECONDS` = 30 between two network fetches
  (`common/controller/fetchWindows.ts:82`), Rumble 120 (`CLIP_WINDOW_PLATFORM_MIN_GAP_SECONDS`, `:90-91`). The
  gap ACROSS runs is keyed `clip-window:<platform>` (`:387`) in `common/jobs/platformGap.ts`, which is
  process-wide and IN MEMORY (`globalThis.__yttPlatformGap__`, `platformGap.ts:13-20`): an editor restart
  forgets it.
- **Cache:** a window is `data/<id>/clips/<from>-<to>.mp4`; `findContainingClipWindow`
  (`common/lib/clipWindow-server.ts:79`) answers with the tightest held window that covers the ask, checked
  before any pacing (`fetchWindows.ts:345`) and costing no pause.
- **Dedupe is within ONE request only** (`dedupeFetchWindowsItems`, `fetchWindows.ts:213-218`): nothing looks
  for an existing job, so two requests for one window make two jobs (release 19 A5).
- **Rumble gets `-extension_picky 0` on the first try** (`common/ytdlp/fetchWindowManaged.ts:261`): every
  attempt reloads the Rumble page, and Cloudflare refuses a share of loads. Elsewhere it is a retry on
  `HLS_EXTENSION_REFUSED`, and a picky run that finds no HLS retries without it (`:65-67`, `:288-296`).
- **The /jobs row** says who asked, for what, how many: the first log line
  ``Fetch windows: N window(s) for <requestedBy>[ · <manifest>]`` (`fetchWindows.ts:269`); progress metric
  `clips`.

### Channel create, rename and delete over ops

- `create-channel`, `rename-channel`, `delete-channel` and `channel-config`'s `sites` are the New channel form
  and the channel page's Danger zone over HTTP; there is no separate sites route.
- **A social URL makes a social channel**: `parseChannelForm` infers `sourceKind: "social"` from the platform
  (X, Bluesky, XenForo; `isSocialPlatform`, `common/lib/platform.ts:42`) and refuses one with no derivable
  handle (`editor/app/channels/components/parseChannelForm.ts:85-107`).
- **Confirmation:** delete needs `confirm` = the slug, rename the current slug
  (`editor/app/channels/actions.ts:635`, `:695`). Both are refused while `channelMediaBusyReason` names a job or a
  lane unit on the channel (`:644`, `:723`; `editor/app/channels/lib/mediaBusy.ts:48`), and delete while
  `.relocating.json` exists (`common/controller/channels.ts:581-592`).
- A social channel's page now carries the same Danger zone (`data-social-danger`,
  `editor/app/channels/[slug]/page.tsx:214`).

### umtool's operator notes

- **Where:** an article's notes are `SITES_DIR/<site>/reports/<report>/notes.json`, beside `report.json`; a
  report-video project's are `<project>/notes.json` beside its manifest (`umtool/lib/annotations/targets.mjs:1-12`).
  The article file is the ONE corpus file umtool writes, only through `isCorpusNotesFile`
  (`umtool/lib/paths.mjs:252`: exactly `<site>/reports/<report>/notes.json`, realpath-checked).
  `SITES_DIR` = `$SITES_DIR`, else `$TRANSCRIPTS_DIR/sites`, else `<repo>/transcripts/sites` (`paths.mjs:217-223`).
- **Shape:** `{format: "umtool-notes", version: 1, subject, source?, notes}` (`umtool/lib/annotations/shape.mjs:13-14`);
  statuses `open|resolved|wontfix`, authors `operator|agent` (`:16-17`); anchors
  `text|cite|section|whole|moment|entry|take|edit` (`:18`) — a `text` anchor is a quote with prefix/suffix,
  re-located on read, never an offset (`umtool/lib/annotations/anchor.mjs`).
- **One writer, `writeOp`** (`umtool/lib/annotations/store.mjs:139`): a `<file>.lock` taken exclusively (stale
  after `LOCK_STALE_MS` 30 s, `:28`), an mtime+size token (`notesToken`, `:50`) — a stale token is `StaleNotes`
  (409, `:32`), an unparseable file is never overwritten (`NotesUnreadable`, `:41`) — then tmp + rename (`:152`);
  the last note deleted removes the file.
- **Who:** `/api/notes` stamps every write `operator` (`umtool/app/api/notes/route.ts:46`); `umtool notes` stamps
  `agent` (`umtool/lib/annotations/cli.mjs:67`, `:80`). The agent digest (`digest`,
  `umtool/lib/annotations/digest.mjs:160`) is what both `umtool notes <target>` and
  `GET /api/notes/context` print.
- **Never published:** compose and the report history read named files only; the guard is the test
  `common/publish/composeReports.test.ts:794` (a sentinel in `notes.json` appears in no built file and no
  history revision).

### umtool kinds declare capabilities; nothing branches on a kind id

- `PROJECT_KINDS` (`umtool/lib/projects/kinds.mjs`): `report-video` declares `notes: true` and
  `linksArticles: true` (`:109`, `:112`); `song` and `sweep-report` neither. Callers ask
  `kindTakesNotes` / `kindLinksArticles` (`:192`, `:195`) — `umtool/lib/annotations/targets.mjs:80`, `:164`;
  `umtool/lib/articles/links.mjs:47` — and an e2e spec fails on a kind id written as a literal outside
  `lib/projects/` and `components/projects/`.
- **/sites** lists every site's articles (`umtool/lib/articles/sites.ts`): published ids unioned with draft
  report dirs, each with its open notes, its source and its linked video. An article row's `kind` is the REPORT's
  kind (`factcheck|sweep`), not a project kind.

## The caption-track rule (verified 2026-10-10, release 20 D3, against `585be292`)

The `en` → 0 cues bug (filed 2026-10-01: the index preferred `en` over `en-orig`, and some livestream VODs' `en`
parsed to 0 cues, indexing the video textless) is CLOSED by `200a3105` (transcripts/en-track-fallback).
- **One rule, by name then by content** (`common/lib/videoStatus.ts`, `CAPTION_TRACK_RULE_VERSION` 1): English
  tracks ranked operator pin (`transcript-pin.json` → `transcript.en.vtt` first) > `en-orig` > `en` > regional
  (`en-US`, …) > `en-en-*`, ties by name (`englishVttsByPreference`); the cues are the first track in that order
  that parses to at least one cue (`readEnglishVttCues`); all empty → the most preferred, with no cues.
  `resolvePrimaryVtt` is the name half only (the editor's "primary" label and change detection).
- **Every cue reader goes through it:** the index (`buildIndex.ts` → `readEnglishVttCues`), normalize
  (`normalizeTranscript.ts`), report compose (`composeReports.ts`), the editor's track reader
  (`captionTracks-server.ts`); umtool's `report-to-video/cues.mjs` carries a copy that `captionTrack.test.ts` holds
  equal. `buildIndex.ts`'s other `parseVtt` call is the non-English/live-chat subtitle tracks.
- **`parseVtt` reads two shapes** (`common/lib/vtt.ts`), decided per document by the presence of an inline
  `<hh:mm:ss.mmm>` tag: rolling (keep the tagged line) or cue blocks (every line, all tags stripped, entities
  decoded). The fixture of the second is `common/lib/__fixtures__/vtt-cue-blocks.vtt`.
- **An index built under an older rule is re-read once** for the records the rule can reach (two or more English
  VTTs, or stored cues empty), logged per channel (`Caption track v1: <slug>: N re-read, M now read different text,
  K had no text and now do.`), then `meta.captionTrackRule` is recorded.
- **Tests:** `lib/captionTrack.test.ts` (order, pin, the fall-through, umtool's copy), `lib/vtt.test.ts` (both
  shapes), `controller/buildIndexCaptionTrack.test.ts` (through the real `buildIndex`: `en-orig` beside a served
  cue-block `en`, a lone cue-block `en`, the one-shot re-read, and — release 20 D3 — an empty `en-orig` before an
  `en` with text and an empty `en` before an `en-US` with text).
- **Not closed by it (found 2026-10-10, not fixed):** the stats cache (see "The stats cache key") keys a video's
  stat on its `mtimes` record, and the caption-track pass rewrites a record's cues with an UNCHANGED `mtimes`
  record (`buildIndex.ts`, the `mtimes.put` after processing writes the same `metaMs`/`transcriptMs`/…). So a
  record the pass took from no text to text keeps `hasTranscript: false` and its old `cueCount` in the stats until
  something else moves its record.