Architecture

Repository direction

• src/lumen_research/domain owns types and invariants without importing outward.
• db owns explicit queries and transactions against PostgreSQL.
• providers translate external behavior into domain contracts.
• workflows coordinate durable execution through Temporal.
• api composes authenticated commands, reads, streams, and trusted gateways.
• apps/web consumes generated OpenAPI types and never imports backend implementation.
• apps/docs consumes shared tokens and generated reference truth but has no backend runtime dependency.

Deployable shape

Railway hosts app and worker from one Python image. Vercel serves only the static web artifact. GitHub Pages serves only apps/docs/build/client. Sandbox runtime code executes inside compute and is not a third hosted control-plane service.

Runtime ownership

The selected attempt runtime is the low-level in-memory Agent from the exact @earendil-works/pi-agent-core@0.83.0 package, inside a thin one-process-per-attempt JSONL runner. The workspace lockfile pins package integrity, and the digest-pinned runtime image carries Node 24.18.0. There is one production attempt runtime and no selector, compatibility layer, or fallback.

Lumen supplies a custom inference streamFn and the exact trusted tool definitions resolved for the attempt. It owns approvals, policy, budgets, durable product delegation, canonical knowledge, normalized events, context/checkpoints, and durability. Pi's stock AgentHarness, CLI/RPC, durable session persistence, automatic resource discovery, extensions, skills, MCP behavior, provider credentials, and control-plane behavior are not adopted.

Ordinary work stays inside the disposable sandbox. Planning receives local read, list, and search. Research and verification also receive local write, edit, bash, persistent scratch python, and bounded subagents.delegate. Those local tools can affect only the attempt workspace and processes. Trusted Lumen tools own web research, connectors, enabled remote MCP, canonical research records, task controls, messages, and workspace publication.

Before inference, the worker materializes the exact project snapshot, selected context, datasets, upstream handoff artifacts, and installed skill bytes under .lumen, verifies their digests, and chmods them 0400. Direct write and edit reject those reserved paths. This is not a hard read-only mount: same-UID bash can alter the disposable copy, while canonical provenance retains the frozen digest and restart restores exact bytes. The worker also freezes one runtime manifest containing the execution profile, build/image/environment/Pi/model and reasoning identities, local tool IDs and limits, trusted definition digests and remote provenance, context digest, and subagent caps. Tasks do not author filesystem/shell tool lists or environment capability requests.

Human notebook kernels remain separately leased document runtimes. An attempt's persistent Jupyter-compatible python tool is scratch computation in that attempt sandbox; its files, variables, and outputs become canonical only through explicit workspace/output/evidence publication.

The runtime's tool_execution_start signal first normalizes to tool.requested, because it occurs before the pre-call hook resolves. A local tool then emits tool.started immediately before sandbox execution; a trusted tool does so only after the Lumen gateway accepts the call and any approval. The acceptance suite covers deterministic inference, normalized text/reasoning/usage/tool events, approval outcomes, cancellation, steering, tool ordering, context digest verification, direct write/edit rejection, exact restart rematerialization, semantic compaction, explicit output promotion, process death, manifest equality, monotonic sequencing, egress and secret canaries, resource budgets, license, SBOM, and adapter fixtures.

The committed A–F candidate passes only the deterministic outcome scorer. There is no production acceptance exporter yet, so no genuine A–F runtime or live-model pass is claimed.

The separate managed infrastructure canary is deliberately summary-only: tasks.list, approved tasks.revise_plan, human plan-revision approval, research-local bash, persistent python, and research.record(kind=summary) produce one immutable attempt-deliverable artifact and a terminal ResearchResult. Bash stages the Python input, proving both tools share one sandbox workspace. It does not claim a canonical notebook, execution, claim, evidence review, write-up, or A–F model-quality result.

CodeMirror autocompletion belongs to the human block editor and does not expose agent tools. Cloudflare Code Mode is not part of this runtime; it is a typed-API composition pattern that could complement local bash if a future large trusted tool catalog justified it, not another name for shell execution.

Change rule

The first public release candidate freezes the Alembic chain through revision 0034 and begins the compatibility epoch. There is no earlier public database reader for that first candidate. From the next schema change onward, CI migrates the previous release fixture to head and keeps old readers and workers compatible until open work drains. Before this durability promise, replace obsolete internal contracts atomically. After it, preserve data through expand, compatible deploy, resumable backfill, switch, and later contract—without preserving obsolete product behavior.