refactor(runtime): flatten config and session flow

- split app config into nested sub-config records
- route session mutations through transaction-style commit/apply helpers
- keep session snapshots chronological and log memory writeback failures
- add CI guard and end-to-end replay coverage

Author: outlndrr

.github/workflows/ci.yml

@@ -22,6 +22,19 @@ jobs:
       - name: Format check
         run: gleam format --check src test
 
+      - name: Guard deprecated patterns
+        shell: bash
+        run: |
+          set -euo pipefail
+          if rg -n 'should\.equal|io\.debug' src test; then
+            echo 'Deprecated Gleam test/debug pattern found'
+            exit 1
+          fi
+          if rg -n '\btodo\b' src; then
+            echo 'Raw todo found in src/'
+            exit 1
+          fi
+
       - name: Type check
         run: gleam check
 

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### Changed
+- refactored app config into nested server/storage/provider/agent/tools sub-configs
+- flattened config validation helpers and added direct tests for validator rules
+- session actor snapshot/state handling now stays chronological internally
+- session actor mutations now flow through transaction-style commit/apply helpers
+- memory writeback failures are now persisted as `memory.writeback_failed` session events instead of being silently discarded
+- centralized session actor/session manager call timeout constants and longer model-adjacent timeouts
+- CI now guards against `should.equal`, `io.debug`, and raw `todo` in `src/`
+
 ### Added
 - Gleam project bootstrap for `lummy_agent`
 - root supervisor and supervised Mist HTTP server

CURRENT_IMPROVEMENTS_TODO.md

@@ -0,0 +1,78 @@
+# Current Improvements Todo
+
+Execution checklist for `docs/refactors/2026-04-current-improvements.md`.
+
+## Phase 0 — Baseline & safety net
+- [x] Run `gleam format`; keep formatter churn isolated.
+- [x] Run `gleam test`; record baseline pass count and timing.
+- [x] Add CI guard for `should.equal`, `io.debug`, raw `todo` in `src/`.
+- [x] Add end-to-end integration test covering `POST /agent-runs` -> SSE replay/read-back -> event-log read-back.
+
+## Phase 1 — Low-risk polish
+- [x] 1.1 Replace hand-rolled list reversal in `src/lummy_agent/app/config.gleam` with `list.reverse`.
+- [x] 1.2 Qualify dict imports in `src/lummy_agent/session/session_manager.gleam` and `src/lummy_agent/runtime/event_bus.gleam`.
+- [x] 1.3 Replace `panic as` expectation branches in key Result-based tests with `let assert Error(_)` patterns.
+- [x] 1.4 Make memory writeback failures observable via session events.
+- [x] 1.5 Centralize actor call timeouts in `session_actor.gleam` and `session_manager.gleam`; add longer model-adjacent timeouts.
+- [x] 1.6 Document `CollectorMessage` wrapper reason in `session_actor.gleam`.
+
+## Phase 2 — Flatten config validator
+- [x] Extract `require_non_blank`, `require_summary_mode`, `require_tool_risk`, `require_secret_key_length` helpers.
+- [x] Rewrite `validate/1` with flat `result.try` flow.
+- [x] Add direct tests for validator helpers.
+
+## Phase 3 — Split config into sub-configs
+- [x] Define `ServerConfig`, `StorageConfig`, `ProviderConfig`, `AgentConfig`, `ToolsConfig`.
+- [x] Update `defaults/0` and `from_env/1` to populate sub-configs.
+- [x] Migrate config consumers to nested fields.
+- [x] Narrow function signatures to smaller sub-configs where practical (`prompt_builder`, `planner`, `memory_*`, provider registry/adapters, tool runtime helpers).
+- [x] Remove flat config fields.
+
+## Phase 4 — Fix snapshot list direction
+- [x] Make `Snapshot.messages`, `Snapshot.runs`, `Snapshot.events` internally chronological.
+- [x] Remove `public_snapshot/1` and `chronological_messages/1`.
+- [x] Update call sites to append chronologically.
+- [x] Verify event-log ordering and replay ordering stay stable.
+
+## Phase 5 — Extract transaction pipeline in `session_actor`
+- [x] Define `SessionTransaction` and `RunActorSync`.
+- [x] Add transaction builders, `commit_and_apply`, `fold_into_snapshot`, `apply_run_actor_syncs`.
+- [x] Migrate `append_message`.
+- [x] Migrate `start_run_impl`.
+- [x] Migrate `start_tool_call_impl`.
+- [x] Migrate `succeed_tool_call_impl`.
+- [x] Migrate `fail_tool_call_impl`.
+- [x] Migrate `apply_tool_result_impl`.
+- [x] Migrate `execute_model_turn_impl` adjunct flow (`maybe_update_run_plan`, chunk event handling where applicable).
+- [x] Migrate `transition_run_impl`.
+- [x] Migrate `complete_run_impl`.
+- [x] Migrate `complete_run_with_assistant_message_impl`.
+- [x] Migrate `fail_run_impl`.
+- [x] Migrate `cancel_run_impl`.
+- [x] Delete superseded pre-transaction helper paths.
+
+## Phase 6 — Record spread consistency
+- [x] Replace remaining manual `State(...)` rebuilds with record spread where clearer.
+
+## Phase 7 — Repository pattern decision
+- [x] Document repository pattern decision; keep record-of-functions for now (`docs/adr/0001-repository-pattern.md`).
+
+## Phase 8 — Cleanup & validation
+- [x] Re-run `gleam format`.
+- [x] Re-run full test suite.
+- [x] Audit line counts.
+  - target: `session_actor < 1200`; actual: `1776`
+  - target: `config < 400`; actual: `564`
+- [x] Update `docs/session-runtime.md` for transaction pipeline.
+- [x] Update `CHANGELOG.md` with refactor + writeback observability note.
+- [x] Move `CURRENT_IMPROVEMENTS_PLAN.md` to `docs/refactors/2026-04-current-improvements.md`.
+
+## Baseline notes
+- [x] Baseline recorded.
+  - Pass count: `98`
+  - Test timing: `15.213s`
+
+## Final validation
+- [x] Final `gleam check`
+- [x] Final `gleam test`
+  - Pass count: `101`

docs/adr/0001-repository-pattern.md

@@ -0,0 +1,30 @@
+# ADR 0001: Keep repository record-of-functions for now
+
+## Status
+Accepted
+
+## Date
+2026-04-18
+
+## Context
+Current refactor reviewed whether `repository.Repositories` should stay as record-of-functions, flatten to direct SQLite calls, or move to variant-based backend dispatch.
+
+Today project has one production backend: SQLite. Existing tests and runtime wiring already depend on repository records. Refactor priority for this pass is session/runtime correctness, config structure, and observability — not backend architecture churn.
+
+## Decision
+Keep record-of-functions repository pattern as-is for now.
+
+## Why
+- No second backend currently planned for immediate use.
+- Refactor churn here would be high relative to benefit.
+- Current abstraction already supports test seams and commit batching used by session flows.
+- Flattening to direct module calls would tightly couple runtime code to SQLite right before large session refactors.
+- Variant-based backend dispatch can be revisited later if a real in-memory or alternate backend becomes necessary.
+
+## Consequences
+- No code change required beyond documenting decision.
+- Continue using `repository.Repositories` in runtime code.
+- Revisit only when one of these becomes true:
+  - second backend is actively needed,
+  - repository indirection blocks maintainability,
+  - tests need cheaper backend swapping than current approach allows.

CURRENT_IMPROVEMENTS_PLAN.md …efactors/2026-04-current-improvements.mdCURRENT_IMPROVEMENTS_PLAN.md renamed to docs/refactors/2026-04-current-improvements.md CURRENT_IMPROVEMENTS_PLAN.md renamed to docs/refactors/2026-04-current-improvements.md

@@ -11,7 +11,7 @@ Capabilities:
 - load session snapshot from repositories on start
 - persist session-level `active_run_id` pointer and use it on reload
 - one-time fallback migration from persisted non-terminal runs when older data lacks the pointer
-- keep internal snapshot buffers newest-first while normalizing chronological order on public replies
+- keep internal snapshot buffers chronological (oldest-first) end-to-end
 - append inbound message with persistence
 - start run with single-flight guard
 - start or lazily rehydrate dedicated run actor for active run
@@ -32,6 +32,7 @@ Capabilities:
   - `tool_call.started`
   - `tool_call.succeeded`
   - `tool_call.failed`
+  - `memory.writeback_failed`
 
 ### Session support
 `src/lummy_agent/session/support.gleam`
@@ -40,6 +41,13 @@ Capabilities:
 - summary fallback helper for model-backed context condensation
 - list replace/find helpers used by session actor state updates
 
+### Session transaction pipeline
+`src/lummy_agent/session/session_actor.gleam`
+- session mutating paths now build `SessionTransaction` values
+- single `commit_and_apply` function persists commit batch, publishes envelopes, syncs run actor, and folds changes into snapshot
+- run actor syncs are explicit via `RunActorSync`
+- chunk events and memory writeback failures flow through same event log channel
+
 ### Session supervisor
 `src/lummy_agent/session/session_supervisor.gleam`
 - factory supervisor wrapper for dynamic session actors

docs/session-runtime.md

@@ -12,11 +12,11 @@ pub fn main() -> Nil {
     Error(error) -> panic as app_config.render_error(error)
   }
 
-  let assert Ok(Nil) = storage_sqlite.initialize(config.database_path)
+  let assert Ok(Nil) = storage_sqlite.initialize(config.storage.database_path)
     as "failed to initialize sqlite store"
 
   let assert Ok(repositories) =
-    storage_sqlite.repositories(config.database_path)
+    storage_sqlite.repositories(config.storage.database_path)
     as "failed to build sqlite repositories"
 
   let assert Ok(_root_supervisor) = app_supervisor.start(config, repositories)

src/lummy_agent.gleam

@@ -29,7 +29,7 @@ pub fn execute(
   session_id: domain_id.SessionId,
   run: domain_run.AgentRun,
 ) -> Result(session_actor.Snapshot, domain_error.DomainError) {
-  let tools = tool_runtime.built_in_for_run(config, run)
+  let tools = tool_runtime.built_in_for_run(config.tools, run)
   let assert Ok(initial_usage) = domain_run.usage(0, 0, 0, 0)
   let started_ms = clock.monotonic_ms()
 
@@ -233,7 +233,7 @@ fn handle_tool_request(
       tools,
       tool_name,
       input_json,
-      config.agent_tool_max_retries,
+      config.tools.max_retries,
     )
   {
     Ok(output_json) -> {
@@ -465,7 +465,15 @@ fn fail_started_run(
   run_id: domain_id.RunId,
   reason: domain_error.DomainError,
 ) -> Result(session_actor.Snapshot, domain_error.DomainError) {
-  case session_manager.fail_run(manager, session_id, run_id, wall_clock_now(), reason) {
+  case
+    session_manager.fail_run(
+      manager,
+      session_id,
+      run_id,
+      wall_clock_now(),
+      reason,
+    )
+  {
     Ok(snapshot) -> Ok(snapshot)
     Error(_) -> Error(reason)
   }
@@ -505,16 +513,16 @@ fn enforce_loop_budgets(
   usage: domain_run.Usage,
   started_ms: Int,
 ) -> Result(Nil, domain_error.DomainError) {
-  use _ <- result.try(enforce_step_budget(config.agent_max_steps, step))
+  use _ <- result.try(enforce_step_budget(config.agent.max_steps, step))
   use _ <- result.try(enforce_token_budget(
-    config.agent_max_total_tokens,
+    config.agent.max_total_tokens,
     usage.total_tokens,
   ))
   use _ <- result.try(enforce_cost_budget(
-    config.agent_max_cost_micros,
+    config.agent.max_cost_micros,
     usage.estimated_cost_micros,
   ))
-  enforce_duration_budget(config.agent_max_duration_ms, started_ms)
+  enforce_duration_budget(config.agent.max_duration_ms, started_ms)
 }
 
 fn enforce_step_budget(

src/lummy_agent/agent/basic_agent.gleam

@@ -3,7 +3,7 @@ import lummy_agent/app/config as app_config
 import lummy_agent/domain/message as domain_message
 
 pub fn recall(
-  config: app_config.Config,
+  config: app_config.ToolsConfig,
   messages: List(domain_message.ConversationMessage),
 ) -> List(memory_store.MemoryEntry) {
   memory_store.recall(config, messages)

src/lummy_agent/agent/memory_recall.gleam

@@ -23,19 +23,15 @@ pub type MemoryMatch {
   MemoryMatch(entry: MemoryEntry, score: Int, matched_terms: List(String))
 }
 
-pub fn configured_notes_path(config: app_config.Config) -> String {
-  case filepath.is_absolute(config.agent_tool_notes_path) {
+pub fn configured_notes_path(config: app_config.ToolsConfig) -> String {
+  case filepath.is_absolute(config.notes_path) {
     True ->
-      filepath.expand(config.agent_tool_notes_path)
-      |> result.unwrap(config.agent_tool_notes_path)
+      filepath.expand(config.notes_path) |> result.unwrap(config.notes_path)
 
     False ->
-      filepath.join(config.agent_tool_file_root, config.agent_tool_notes_path)
+      filepath.join(config.file_root, config.notes_path)
       |> filepath.expand
-      |> result.unwrap(filepath.join(
-        config.agent_tool_file_root,
-        config.agent_tool_notes_path,
-      ))
+      |> result.unwrap(filepath.join(config.file_root, config.notes_path))
   }
 }
 
@@ -78,7 +74,7 @@ pub fn entry(
 }
 
 pub fn entries(
-  config: app_config.Config,
+  config: app_config.ToolsConfig,
 ) -> Result(List(MemoryEntry), domain_error.DomainError) {
   let path = configured_notes_path(config)
 
@@ -90,7 +86,7 @@ pub fn entries(
 }
 
 pub fn append_unique_entry(
-  config: app_config.Config,
+  config: app_config.ToolsConfig,
   entry: MemoryEntry,
 ) -> Result(Bool, domain_error.DomainError) {
   let path = configured_notes_path(config)
@@ -113,7 +109,7 @@ pub fn append_unique_entry(
 }
 
 pub fn recall(
-  config: app_config.Config,
+  config: app_config.ToolsConfig,
   messages: List(domain_message.ConversationMessage),
 ) -> List(MemoryEntry) {
   case latest_query(messages) {
@@ -128,7 +124,7 @@ pub fn recall(
 }
 
 pub fn search(
-  config: app_config.Config,
+  config: app_config.ToolsConfig,
   query: String,
   limit: Int,
 ) -> Result(List(MemoryMatch), domain_error.DomainError) {