C9 · Platform ops & delivery

C9 is eli's operational backbone: the scheduled maintenance jobs (daily AI digest, 30-day trash purge) driven by Vercel Cron, the in-process event bus + SSE channel that pushes vault change events to every open browser tab, the test-only dev endpoints that let Playwright manipulate server state, deterministic seeding, benchmark, and ops CLIs (embedding backfill, KMS key rotation), the native-module (better-sqlite3) ABI self-heal that runs on every install, the esbuild packaging of the standalone eli-mcp stdio binary, and the full test pyramid (colocated unit, PGlite harness, adapter contract, MCP harness, pgTAP RLS, Playwright e2e) plus the two GitHub Actions CI gates (perf, RLS). The chokidar watcher and events bus are shared with C1 — C1 owns the indexing side; this page covers the delivery side: the SSE endpoint, its subscribers, heartbeats, and kill switches.

• Modes: cron routes serve both (local single-vault / saas workspace fan-out); SSE + watcher + dev endpoints + CLIs are local-only; the pgTAP gate validates the saas Postgres layer.
• Key dirs: app/api/cron/, app/api/events/, app/api/dev/, lib/watch/, scripts/, tests/, .github/workflows/, vercel.json, instrumentation.ts.
• Depends on: C1 storage adapters + SQLite index, C4 runDigest, C7 service-role Supabase client.
• Feeds: C2 vault UI (live refresh of every /v page), C5 (packaged MCP binary), every cluster (test + CI coverage).

Capabilities

System view — simplified

This cluster is everything that keeps eli running, fresh, and honest: scheduled jobs that the app itself never has to remember to run, a push channel that makes multiple tabs (and external editors) converge on the same view, and the tooling/test/CI layer that keeps the platform installable and correct. Standalone, it is fully usable against just a checkout: pnpm install self-heals the native SQLite binding, seed-vault + bench-search benchmark search on a synthetic 10k-note vault, the entire test pyramid runs without any external service (PGlite gives it an in-process Postgres), and both cron endpoints can be curl'd with a bearer secret against a local next dev server. The only piece that needs external infrastructure is the automatic schedulingof crons (Vercel) and the pgTAP gate's Postgres container (CI-provisioned).

System view — detailed

Behavior contracts locked by tests. The colocated suites are not just unit coverage — several pin exact behavioral contracts: app/api/_e2e.test.ts locks status-code/payload contracts for /v1/openapi.json, /v1/models, /api/import (existing path → updated, new → created), /api/search/hybrid (kind whitelist fts/semantic/hybrid, else 400), and both cron routes (401 on absent/mismatched bearer, digest 200 skipped:['no-active-vault'], prune default 30 days) with storage mocked; app/api/ai/_routes.test.ts locks all five /api/ai/* endpoints' 400 / 503-no-AI-key / 429 contracts, including the shared 60-per-minute 'local' rate bucket from lib/mcp/ratelimit that MCP and the AI routes both consume, and graceful degradation (extract-tasks returns 200 created:[] on non-JSON model output); lib/mcp/tools/p3-tools-04.test.ts pins add_comment version-pinning, daily_note real-calendar-date validation, and apply_template pass-through; server-action suites (app/_actions/{pin,inbox-toast,digest,projects,templates}.test.ts) lock semantic invariants (unpin deletes _pinned rather than setting false, dual-signal leftInbox, frontmatter sibling-field preservation). No suite makes live model calls — an AI-sandbox e2e is noted as future work (app/api/ai/_routes.test.ts:7-12).

Data flow — simplified

The load-bearing runtime flow: any change to a .md file on disk (external editor, agent, git checkout) is picked up by the chokidar watcher, incrementally re-indexed into SQLite, and broadcast over the in-process bus to every connected SSE client. Each browser tab collapses bursts with a 500 ms debounce and calls router.refresh(), so React Server Components re-render against the freshly updated index. In-app saves take a shortcut: lib/storage/local/writes.ts emits directly onto the bus and calls markEcho() so the watcher ignores the resulting filesystem echo.

Data flow — detailed

(a) Vault change → bus → SSE → debounced refresh across tabs (local mode)

(b) Cron digest run across modes

The trash-prune cron (app/api/cron/trash-prune/route.ts) follows the identical shape: same badAuth bearer check, same local/saas fan-out, but per adapter it lists up to 5,000 onlyTrashed notes, skips any with updatedAt newer than the cutoff (?days or 30), and hard-purges the rest one by one, swallowing individual failures.

Works separately / works together

Standalone

With every other cluster switched off, C9 still delivers: a self-healing install (ensure-native.mjs makes pnpm install survive Node ABI bumps with zero user action), deterministic fixture generation (seed-vault.mjs produces byte-identical 10k-note vaults), a search benchmark with a hard exit-code budget, a config bootstrapper for headless CI boots (seed-config.mjs), and a complete test pyramid that runs with no external services — PGlite provides in-process Postgres, the MCP harness uses in-memory transports, and Playwright brings its own fixture vault under .eli-test/. The cron endpoints work against any running instance via curl -H "Authorization: Bearer $CRON_SECRET"; only automaticscheduling needs Vercel. The SSE channel standalone is a generic "this vault changed" push feed any client could consume via EventSource('/api/events').

Composed

• C4 AI platform — the digest cron delegates to runDigest() in lib/ai/digest-runner.ts, the exact code path behind the UI's manual "Generate digest now" action (app/api/cron/digest/route.ts:33-35 docstring); digest logic itself lives in C4, C9 only schedules and auths it. The two callers are distinguishable by route tag: manual runs pass app/_actions/digest.generateNow and in SaaS are session-scoped to the single eli_ws-cookie workspace via the user's RLS client — cross-workspace service-role fan-out is reserved for the cron.
• C1 core data & storage — both cron routes consume the storage abstraction (LocalAdapter.forVault / SupabaseAdapter.fromClient); the events bus is fedby C1's chokidar watcher (which also drives lib/index/incremental.updatePath) and by lib/storage/local/writes.ts emit calls; the dev endpoints reach into C1 internals (lib/db/client.sqlite.closeAll, LocalAdapter._resetCache, lib/index/scanner.scanVault, lib/config._resetCacheForTests).
• C2 authoring UX — VaultEventsBridge is mounted in app/(local)/v/layout.tsx:54, so every RSC page under /vis indirectly refreshed by change events; C2's note list, backlinks, and lenses stay live because of this cluster.
• C7 SaaS collaboration — cron fan-out uses lib/auth/supabase.createSupabaseServiceRoleClient (RLS-bypassing, tracked as SERVICE-ROLEcomments); the pgTAP gate is the CI enforcement of C7's RLS policies.
• C5 agent surface — build-mcp-bin.mjs packages C5's lib/mcp/stdio.ts into the published eli-mcp bin; tests/mcplocks C5's 16-tool surface over both transports.
• C3 semantic search — tests/unit/scripts/embed-backfill-args.test.mjscovers the embed-backfill CLI's arg parsing; perf.ymlgates C1/C3's search latency.
• e2e ↔ dev endpoints — Playwright global setup POSTs /api/dev/reset, spec 02 mints per-test notes via /api/dev/seed-note, spec 06 busts the config cache via /api/dev/rescan after directly editing .eli-test/home/config.json.

Load-bearing details

• Cron auth is strict equality against `Bearer ${env.CRON_SECRET}`; an unset CRON_SECRET makes badAuth() return true → permanent 401, never wide-open (app/api/cron/digest/route.ts:46-51, app/api/cron/trash-prune/route.ts:32-36). The x-vercel-cron header is explicitly documented as untrusted (digest route comment, lines 15-18). CRON_SECRET is zod-optional (env.ts:98).
• Both cron routes alias GET→POST because Vercel Cron sends GET (digest/route.ts:57-61, trash-prune/route.ts:113-115); both export dynamic = 'force-dynamic'.
• The digest window is exactly 00:00:00Z→24:00:00Z of the target day, so multiple runs the same day are idempotent — they upsert the same digest path (app/api/cron/digest/route.ts:20-24 docstring, 53-55, 68-76).
• Trash prune has no trashedAt column — it proxies via updatedAt("the soft-delete write was the last update on a trashed row, by construction") and caps at 5,000 trashed notes per workspace per run (app/api/cron/trash-prune/route.ts:19-25,43-44).
• The SSE route deliberately does not replay the 256-entry backlog on connect — replay caused router.refresh() flurries that masked navigations and made e2e flaky (app/api/events/route.ts:31-37); recentEvents() (lib/watch/events-bus.ts:43-45) is therefore dead to the SSE path.
• Bus and watcher registry survive Next dev HMR via globalThis singletons: __ELI_EVENT_BUS__ (lib/watch/events-bus.ts:13-22) and __ELI_WATCHERS__ (lib/watch/chokidar.ts:27-34). The flip side: fan-out is single-process only and cannot span serverless instances — the SaaS answer is Supabase Realtime postgres-changes on notes (components/realtime/note-watcher.tsx), which shows a refresh-invite toast (never auto-replaces the buffer) and filters self-edits via a window-pinned set of version ids.
• GET /api/events performs no auth check of its own — any client that can reach the local server can subscribe to the change feed (app/api/events/route.ts:20).
• Echo suppression: adapter writes call markEcho(vault, relPath)with a 750 ms TTL so chokidar doesn't double-index files the adapter itself just wrote (lib/watch/chokidar.ts:36-58).
• All three /api/dev/* endpoints share a double guard: 403 when NODE_ENV === 'production' or when ELI_HOME doesn't contain the substring .eli-test— they can't fire on a real install even in dev mode (rescan/route.ts:17-23, reset/route.ts:19-24, seed-note/route.ts:21-26).
• /api/dev/reset exists specifically because playwright.config.ts reuseExistingServer keeps better-sqlite3 fds open on a deleted DB inode after global-setup reseeds; closeAll() + cache resets force reopening the new file (app/api/dev/reset/route.ts:7-17).
• seed-vault.mjs is byte-deterministic via mulberry32 (seed 42), which perf.yml exploits to cache the 10k-note fixture keyed on hashFiles('scripts/seed-vault.mjs') (.github/workflows/perf.yml:73-84).
• bench-search.mjs exits code 3 when p95 > ELI_PERF_P95_BUDGET_MS(default 200; CI sets 450 for shared runners) — that exit code is the perf gate's entire failure mechanism (scripts/bench-search.mjs:89-92).
• ensure-native.mjs probes better-sqlite3 by instantiating a :memory: DB and running SELECT 1, because many native packages only dlopen on first use, not on require (scripts/ensure-native.mjs:42-52); ABI-mismatch signatures matched by regex /NODE_MODULE_VERSION|ERR_DLOPEN_FAILED|invalid ELF header|not a valid Win32 application|Could not locate the bindings file/i (line 86); it never fails the install.
• build-mcp-bin.mjs reuses tests/_helpers/server-only-stub.ts as the esbuild alias for both server-only and client-only in the shipped MCP binary — a test helper is load-bearing in the production bin build (scripts/build-mcp-bin.mjs:83-86).
• e2e runs with ELI_LEGACY_EDITOR=1 (forces the legacy <textarea data-testid="note-editor">; BlockNote's contenteditable breaks End-key semantics) and ELI_DISABLE_LIVE_EVENTS=1 (SSE refresh races router.push) — so e2e covers neither BlockNote editing nor the live SSE bridge (playwright.config.ts:38-54).
• e2e is single-worker, serial, chromium-only, on port 3838 against next dev --turbopack — not a production build (playwright.config.ts:17-34).
• instrumentation.ts only starts the watcher when NEXT_RUNTIME === 'nodejs' and ELI_MODE is unset or 'local'; SaaS deployments never run chokidar (instrumentation.ts:16-17).
• tests/adapter/local.spec.ts skips the favorites capability because LocalAdapter favorites persist in ~/.eli/config.json keyed by registered vault id, and the contract factory creates an unregistered tmp vault (tests/adapter/local.spec.ts:50-54).
• The MCP tool surface is locked by test to exactly 16 tools (tests/mcp/tools.spec.ts:44-67); the HTTP path calls createMcpHandler with a fake Request — no real server; auth/rate-limit failure modes live separately in lib/mcp/auth.test.ts.
• vercel.json contains onlythe two cron entries — the sole Vercel-specific deployment config in the repo. SaaS topology is "Next.js on Vercel + Supabase"; local topology is self-hosted next dev/start -p 3737 (package.json:15,22) where crons must be invoked manually.
• package.json pins engines.node >= 22.11.0, and pnpm.onlyBuiltDependenciesallowlists build scripts for exactly better-sqlite3, esbuild, and sharp — pnpm blocks every other dependency's postinstall, so ensure-native.mjs only ever has one native module to heal.

Gaps and partially wired

• No CI for the bulk of the pyramid. Only two workflows exist (perf.yml, pgtap.yml); nothing in .github/workflows/ runs lint, typecheck, the ~75-file vitest suite, or the e2e suite — those gates are local-only conventions.
• Stale SSE docstring. app/api/events/route.ts:17-18still claims "On open, recent backlog is replayed" while the code comment at lines 31-37 (and the code) deliberately does the opposite. The doc lies; the code is right.
• recentEvents() is dead code on the delivery path (lib/watch/events-bus.ts:43-45) — kept on the bus but intentionally unused by the SSE route.
• hooks/use-vault-events.ts is a public hook with zero mounts — VaultEventsBridge inlines its own EventSource to own the 500 ms debounce; the hook itself is undebounced (per-event router.refresh() plus an optional onEvent callback) and exists for future consumers only.
• Missing Supabase adapter-contract run. tests/_helpers/pglite.ts:17-19 references tests/adapter/supabase.spec.ts, but no such file exists — the shared conformance suite runs only against Local/Memory/JsonFile, so the SaaS adapter is untested at the contract level.
• CRON_SECRET is optional in the env schema (env.ts:98): a deployment that forgets to set it gets both cron endpoints permanently returning 401 — safe, but silently no-op (digests and trash purge just stop happening).
• No cron invoker in local mode. vercel.json schedules only apply on Vercel; a self-hosted local install must curl the cron endpoints itself (or never get digests/pruning).
• e2e blind spots by design: BlockNote editing (ELI_LEGACY_EDITOR=1) and the live SSE bridge (ELI_DISABLE_LIVE_EVENTS=1) are excluded from Playwright coverage; the suite also runs against next dev --turbopack, not a production build.
• Trash prune approximations: no trashedAtcolumn (updatedAt proxy can extend a note's trash life if it is touched post-trash), and the 5,000-per-workspace cap means a larger backlog only drains across multiple daily runs.
• seed-config.mjs is unwired from package.json scripts — invocable only as node scripts/seed-config.mjs.
• tests/unit is nearly empty — a single CLI-arg-parsing suite (tests/unit/scripts/embed-backfill-args.test.mjs); everything else is colocated.