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. Slice 6 must freeze the package graph, integrity, Node version, and runtime image digest before the runner becomes active.

Lumen supplies a custom inference streamFn and only Lumen-generated remote tools. It owns approvals, policy, budgets, delegation, knowledge, normalized events, context/checkpoints, and durability. The runtime's harness, CLI/RPC, session persistence, resource discovery, built-in filesystem or shell tools, extensions, skills, MCP behavior, provider credentials, and control-plane behavior are not adopted.

The runtime's tool_execution_start signal normalizes to tool.requested, because it occurs before the pre-call approval hook resolves. Only the Lumen tool gateway can establish that execution began. Activation still requires the committed deterministic, failure, cancellation, isolation, resource, license, SBOM, and adapter-fixture gates.

Change rule

Before the 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.