# lethe-server

**Status:** Execute (verify pending)
**Module:** `sourcecraft.dev/bigbes/lethe`
**Branch:** master
**Worktree:** none
**Parent RFC:** Personal AI Assistant Log Aggregator (2026-04-25)
**Sibling tasks (deferred):** `lethe-collector-claude-code.md` (#2), `lethe-search-and-opencode.md` (#3)

## Design

### Purpose

Stand up the `lethe` server binary: SQLite-backed ingestion endpoint, session list/detail JSON API, forward-auth header trust against an Authelia-protected reverse proxy, ready to deploy on phoebe behind Caddy/Traefik+Authelia. Search, stats, any HTML/UI, and any collector code are explicitly deferred to siblings or a later UI task.

A successful end state for this task: I can `curl -X POST` a fixture NDJSON file at `/api/v1/ingest`, then `curl` the sessions list and a single session detail through the reverse proxy (with either an Authelia session forwarding `Remote-User` or an Authelia-issued OIDC bearer) and get the expected JSON back.

### Scope

**In:**
- Single Go binary `lethe` (`cmd/lethe/main.go`) — JSON API server only.
- Full SQLite schema, including the FTS5 tables and triggers from the start (so #3 only adds query code, no migrations).
- Embedded migrations via `embed.FS` + `golang-migrate/v4`, applied on startup.
- `POST /api/v1/ingest` — NDJSON, turn-only protocol (server upserts session rows from turn data).
- `GET /api/v1/sessions` — paginated list with filters (`tool`, `host`, `since`, `until`).
- `GET /api/v1/sessions/{tool}/{host}/{session_id}` — full session with turns inline.
- Two auth paths, both gated by the same `auth.allowed_users` allowlist:
  - **Forward-auth**: trust `Remote-User` from an upstream reverse proxy (Caddy/Traefik) gated by Authelia.
  - **OIDC bearer**: validate `Authorization: Bearer <jwt>` against Authelia's OIDC issuer (JWKS lookup, signature, `iss`/`aud`/`exp`); take user from `preferred_username` (fallback `sub`).
- Each mode independently enable-able; if both enabled, bearer is checked first then header.
- **Per-user data isolation**: every session and turn is owned by the user that ingested it. List and detail endpoints filter by current user. Members of the configurable `auth.admins` list can see all owners' data and override via `?owner=<user>` (or `?owner=*`) on read endpoints.
- `/healthz`, `/readyz`, `/metrics` (Prometheus).
- Graceful shutdown, structured logging via `scribe`, structured errors via `culpa` rendered as RFC 7807 `application/problem+json`.
- `Justfile`, `.air.toml`, `Dockerfile`, `docker-compose.yml`, `config.example.yaml`, `.golangci.yml` per `go-selfhosted-backend` skill conventions.
- Wire types live in `internal/shared/wire/` so #2's collector imports them directly.
- Daily `.backup` is **documented** in the README (cron + `sqlite3 .backup`); no code in this task.

**Out:**
- Any HTML / web UI — timeline view, session view, templates, CSS, static assets, markdown rendering (`goldmark`/`bluemonday`). Deferred to a later UI task; the JSON API is the only consumer surface in this task.
- Collector binary, parsers, ingestion loop, outbox, backfill — all #2.
- `/api/v1/search` + search UI + `tool_outputs_fts` query path — #3 (table + triggers exist; queries don't).
- `/api/v1/stats` + rollups view — #3.
- `/debug/pprof` — defer until something forces the issue.
- Sub-agent / `parentUuid` session chaining (Claude Code resume semantics) — parser concern, lands with #2.
- Backup automation in code.

### Chosen approach

**Storage: option B (locked).** SQLite (`modernc.org/sqlite`, no CGO) with WAL, single DB file. Schema includes `turns_fts` (FTS5 over prose `content`) and `tool_outputs_fts` (FTS5 over `tool_calls` text). Both indexes populated by INSERT/UPDATE/DELETE triggers from the start — #3 only wires queries.

**Wire protocol: option B (locked).** Collector emits turn-only NDJSON. Server upserts the session row on first-seen turn from `session_meta` carried on the turn; subsequent turns extend the session's `ended_at`. No separate session events on the wire. Reduces collector state and makes outbox replay trivially idempotent.

**Repo layout: option A (locked).** Monorepo. `cmd/lethe/` (this task) and `cmd/lethe-collector/` (placeholder dir for #2) under one `go.mod`. Shared types in `internal/shared/wire/`.

**Auth model.** Server binds `127.0.0.1` only. A reverse proxy on phoebe (Caddy or Traefik) terminates TLS and forwards to localhost. Two independent auth paths inside lethe, each enable-able via config:

1. **Forward-auth (header trust).** Reverse proxy runs Authelia forward-auth on the lethe vhost, and on success injects `Remote-User` (and `Remote-Email`, `Remote-Groups`) headers. Middleware reads `Remote-User` (header name configurable for non-Authelia setups), checks allowlist, 403 on miss. Used by browsers and any other tool that already has an Authelia session cookie.

2. **OIDC bearer.** Lethe is registered as an OIDC client of Authelia (`client_id`/`client_secret` configured at the Authelia side, `client_id` only at lethe — the server validates tokens, never issues them). Middleware accepts `Authorization: Bearer <jwt>`, validates against Authelia's published JWKS (discovered via `/.well-known/openid-configuration`), enforces `iss`, `aud`, `exp`, then resolves user from `preferred_username` falling back to `sub`. Used by the collector and any scripted client. No code-flow / callback / cookie machinery in lethe — the bearer must already be obtained out-of-band (Authelia issues it via its OIDC flow to whatever client got it).

Both paths drop the user identity into the request context so handlers see the same shape regardless of how the user was authenticated. Both paths are gated by the same `auth.allowed_users` allowlist as a defense-in-depth check. If both are enabled and a request carries both an `Authorization` header and a `Remote-User` header, the bearer is validated first; the proxy header is ignored unless bearer validation fails open (configurable). Health and metrics endpoints are mounted *outside* the auth middleware so phoebe can scrape them locally without going through the proxy. The implicit assumption — that nothing else on phoebe binds 127.0.0.1 and forges the header — is the whole trust model for path 1; documented in the README.

**Layered design** (from `go-selfhosted-backend`):
- `internal/config` — Viper, strict mode, validator tags, fails on unknown keys. Top-level `Config` struct exposes substructs (`Server`, `Database`, `Auth`, …) via `config-section:""` tags so steward can inject them by type into individual services.
- `internal/platform/database` — sqlx connection, migration runner over `embed.FS`, transaction helper. Implements steward `Init` (open + migrate) and `Destroy` (close).
- `internal/platform/observability` — scribe logger service (`Init` sets `slog.SetDefault`), Prometheus registry singleton.
- `internal/platform/health` — `Checker` interface, `Set` aggregator service with steward multi-inject (`[]Checker \`inject:""\``), DB check service registered as a `Checker`. Adding a new check = registering a new asset; no edits to the set.
- `internal/server` — chi router, middleware stack (request-id, logging, metrics, recovery, auth), `Start` (listen) and `Stop` (graceful shutdown). Marked `steward.Root()` so it's always started.
- `internal/domain/ingest` — handler + service for `POST /api/v1/ingest`, both as steward services. Service owns the upsert-session-then-upsert-turn logic in a single transaction per batch.
- `internal/domain/session` — handler + repository for the list/detail JSON API, both as steward services.
- `internal/shared/wire` — `TurnEvent`, `SessionMeta` types. Imported by both server and (eventually) collector.
- `internal/pkg/httputil` + `internal/pkg/apierror` — JSON helpers, RFC 7807 problem rendering with culpa code → status mapping. Pure libraries, not steward components.

**Wiring & lifecycle.** All wiring goes through `steward.Manager`. `cmd/lethe/main.go` is a thin shell: parse `-config`, load `Config`, register configuration + service assets, conditionally register `OIDCVerifier` only when `cfg.Auth.OIDC.Enabled`, call `Inject → Init → Start`, wait on signal, call `Stop → Destroy`. Dependency direction is enforced by struct tags (`config:""`, `inject:""`, `inject:"" optional:"true"`); the manager solves the topological order. No global state outside `slog.Default` (set by the logger service in `Init`).

**Wire type (locked contract for #2):**
```go
package wire

type TurnEvent struct {
    Tool        string          `json:"tool"`
    Host        string          `json:"host"`
    SessionID   string          `json:"session_id"`
    TurnID      string          `json:"turn_id"`
    Seq         int64           `json:"seq"`
    Role        string          `json:"role"`        // user | assistant | tool | system
    Timestamp   int64           `json:"timestamp"`   // unix epoch seconds
    Content     string          `json:"content"`
    Model       *string         `json:"model,omitempty"`
    TokensIn    *int64          `json:"tokens_in,omitempty"`
    TokensOut   *int64          `json:"tokens_out,omitempty"`
    CostUSD     *float64        `json:"cost_usd,omitempty"`
    ToolCalls   json.RawMessage `json:"tool_calls,omitempty"`
    SessionMeta SessionMeta     `json:"session_meta"`
    Metadata    json.RawMessage `json:"metadata,omitempty"`
}

type SessionMeta struct {
    WorkingDir *string         `json:"working_dir,omitempty"`
    SourceFile string          `json:"source_file"`
    StartedAt  *int64          `json:"started_at,omitempty"` // optional; server falls back to MIN(turn.timestamp)
    Metadata   json.RawMessage `json:"metadata,omitempty"`
}
```

`tool_calls` is `json.RawMessage`: the server doesn't interpret it, just persists it and feeds its serialized text to `tool_outputs_fts`. Carrying `session_meta` on every turn is redundant (~100 bytes/turn) and intentional: collector replay never has to ask "did I already send the session header?"

**Ingest semantics.**
- Request body is NDJSON; one `TurnEvent` per line. Hard cap on body size (configurable, default 16 MiB). Per-turn `content` soft-capped at 4 MiB (configurable); a single oversize turn is a `LineError`, not a 413.
- **Required wire fields**: `tool`, `host`, `session_id`, `turn_id`, `seq`, `role`, `timestamp`, `content`. `role ∈ {user, assistant, tool, system}`. `source_file` (in `SessionMeta`) capped at 1024 bytes. Validation runs per-line before DB; failure → `LineError`.
- `owner` is **server-derived** from the authenticated user (request context), never read from the wire. The wire format in `internal/shared/wire/` deliberately has no `owner` field — collectors cannot impersonate other owners.
- All timestamps stored as SQLite `INTEGER` (unix epoch seconds). No TEXT timestamps anywhere in the schema.
- Server processes lines **in order** within a single SQLite transaction.
- For each turn:
  1. `INSERT INTO sessions ... ON CONFLICT (owner, tool, host, session_id) DO UPDATE SET ended_at = MAX(ended_at, excluded.ended_at)`. `started_at`, `working_dir`, `source_file`, `metadata` are **first-write-wins** (preserved on conflict); only `ended_at` extends.
  2. `INSERT INTO turns ... ON CONFLICT (owner, tool, host, session_id, turn_id) DO UPDATE SET <all non-key columns>`. Last-write-wins on the turn row. Triggers keep both FTS tables in sync.
- On any per-line error (malformed JSON, missing required field, FK violation), the transaction is rolled back **for the failing line and beyond**, and the response is `200 {"accepted": N, "errors": [{"line": N, "error": "..."}]}` where `accepted` is the count of lines successfully committed in a previous chunk. Practically, the server processes and commits in chunks (e.g. every 500 lines) so a single bad line near the end of a batch doesn't lose 499 good ones. Collector advances its offset by exactly `accepted`.
- Hard server errors (DB down, OOM): 5xx with empty `accepted`, collector retries the whole batch from the same offset.

**Schema (initial migration).** As specified in the RFC §4.2, with these adjustments:
- Add `owner TEXT NOT NULL` to `sessions` and `turns`. Composite PKs become `sessions(owner, tool, host, session_id)` and `turns(owner, tool, host, session_id, turn_id)` with FK `(owner, tool, host, session_id)` → sessions. Owner-leading PK gives a free index for "list my sessions" and makes per-user isolation a schema property.
- Add `owner UNINDEXED` column to both FTS tables so #3's search can `WHERE turns_fts MATCH ? AND owner = ?` cheaply; triggers carry it from the source row.
- Add `turns_fts_update` trigger so an UPSERT on `turns` keeps the FTS row current (the RFC has insert/delete only).
- Add the parallel `tool_outputs_fts` table with insert/update/delete triggers, indexing the `tool_calls` column when non-NULL.
- Add `schema_migrations` (managed by golang-migrate) — replaces the RFC's hand-rolled `schema_version`.
- Index `sessions(owner, started_at DESC)` for the timeline/list query.

**CLI.** This binary has one mode (run server). `flag` package, no cobra. Single arg: `-config <path>`. (Cobra will land with the collector binary in #2.)

**Tradeoffs that settled it.**
- *SQLite vs Postgres:* Phoebe doesn't need another service, FTS5's `snippet`/`highlight` and tokenizer are better than tsvector for this workload, single-user means no write contention. Migrating to PG later is mechanical if I'm wrong; the cost of being wrong is an afternoon.
- *Turn-only wire vs explicit session events:* Outbox replay correctness wins over "cleaner" two-event schema. The redundant `session_meta` per turn costs nothing at this scale.
- *Inline tool-call payloads vs blob/dedupe:* RFC's expected scale doesn't justify the extra code. Revisit in #3 if FTS index size or query latency actually bites.
- *Defer all UI:* Skipped HTML views in this task to land the JSON API + ingest pipeline first. The collector (#2) only needs the API; the UI lands once there's real data to look at.

**Unknowns that remain.**
- True size distribution of tool-call payloads in real Claude Code transcripts — won't know until #2 runs against `~/.claude/projects/`. If the FTS index for `tool_outputs_fts` grows pathologically, #3 has the option to add a size cap or move that table to a separate attached DB.
- JWKS rotation cadence at Authelia and the right cache TTL on the lethe side (`go-oidc` defaults usually fine; revisit if validation latency or 401-storms appear). Not blocking #1.

### Backwards-compatibility check

Greenfield. Empty repo, no consumers, nothing to break. The only forward-compat concern is the wire format, which is locked into `internal/shared/wire/` and versioned implicitly via the `/api/v1/` path prefix. Future breaking changes get `/api/v2/`.

TDD: yes (reason: ingest idempotency, the upsert-session-from-turn semantics, the chunked-commit-with-partial-accept response shape, the auth middleware allowlist, and migration application on startup are all deterministic, regression-prone surfaces.)

### Invariants

- Server never opens, reads, or writes any file outside its own data directory and config path. `source_file` from incoming turns is stored as opaque string only.
- The host identifier on a turn is whatever the collector says it is. Server does not derive or validate it against the authenticated user (whether resolved via forward-auth header or OIDC bearer).
- All schema changes go through `embed.FS` migrations applied on startup. No ad-hoc DDL, no startup-time conditional `CREATE TABLE`.
- Composite primary keys: `sessions` keyed on `(owner, tool, host, session_id)`; `turns` keyed on `(owner, tool, host, session_id, turn_id)`. No surrogate IDs anywhere.
- `POST /api/v1/ingest` is idempotent at the turn level **per owner**: re-POST of identical `(tool, host, session_id, turn_id)` by the same authenticated user produces the same final state regardless of how many times it's sent. Two different users posting the same `(tool, host, session_id, turn_id)` produce two distinct rows.
- `owner` is set from the authenticated user on every ingest write. The wire format has no `owner` field; the server never reads owner from the request body.
- Read endpoints (`GET /api/v1/sessions`, `GET /api/v1/sessions/{tool}/{host}/{session_id}`) return only rows where `owner = <current user>`, except when the current user is in `auth.admins` and supplies `?owner=<user>` (specific owner) or `?owner=*` (all owners). Non-admin requests with `?owner=` are 403.
- Every route under `/api/v1/*` validates the configured user header (default `Remote-User`) against `auth.allowed_users`. Only `/healthz`, `/readyz`, `/metrics` are unauthenticated.
- The HTTP listener binds `127.0.0.1` only. Binding any other interface is a config error and fails fast at startup.
- SQLite is opened in WAL mode with `_busy_timeout` configured. Foreign keys are enforced (`PRAGMA foreign_keys = ON`).
- A turn insert/update fires both FTS triggers as appropriate; the `turns_fts` and `tool_outputs_fts` tables are never written to directly outside triggers.
- Errors leaving any HTTP handler are rendered as RFC 7807 `application/problem+json` with the culpa code mapped to status; internal (5xx) errors are logged with full stacktrace via `scribe.Err` before being sanitized for the response.

### Principles

- Greenfield — no backwards-compat shims, no deprecation paths, no `_unused` parameters. If something turns out wrong, rewrite the file.
- Schema additions over schema changes. Tool-specific fields go into the `metadata` JSON column on the relevant row; new SQL columns require justification.
- Fail fast on config and migration errors. The auth allowlist has no default — empty list means the server refuses to start.
- Stdlib + `chi` + `sqlx` + `golang-migrate` + `modernc.org/sqlite` + `go-oidc/v3` (JWT/JWKS validation only — no auth-code flow) + `go.bigb.es/auxilia` (`steward` for DI/lifecycle, `culpa` for errors, `scribe` for logs, `async` only if a background task surfaces). No ORM, no template engine, no UI dependencies in this task.
- Lifecycle and dependency wiring go through `steward.Manager`. Adding a new component is registering an asset; `main.go` does not grow.
- Each layer is a steward service that declares its deps via struct tags (`config:""`, `inject:""`, optional + multi-injection where it earns its keep). Constructors are the zero value; setup happens in `Init`.
- Unit tests construct services with hand-built deps (no manager). Integration / e2e tests use `steward.Manager` to assemble a real graph against a `:memory:` DB.
- Errors propagate as `culpa` errors with codes; HTTP layer translates once at the boundary.
- Every authenticated route and every ingest semantic has a regression test.
- `internal/shared/wire/` is treated as a published API even though it isn't published — changes ripple into the collector and need to be obvious in diff.

## Plan

Approach: build bottom-up — wire types → config → DB+schema → platform → HTTP foundation → auth → ingest → read API → main. Each phase is one commit; tests land with the phase that introduces the behavior. Greenfield, so no compat shims.

### Phase 1 — Bootstrap & wire contract

- **1.1** `go.mod` (create) — `module sourcecraft.dev/bigbes/lethe`, Go 1.22+. Direct deps stub: `chi/v5`, `sqlx`, `modernc.org/sqlite`, `golang-migrate/v4`, `viper`, `validator/v10`, `prometheus/client_golang`, `coreos/go-oidc/v3`, `go.bigb.es/auxilia/{steward,culpa,scribe}`.
- **1.2** `Justfile`, `.air.toml`, `Dockerfile`, `docker-compose.yml`, `.golangci.yml`, `.gitignore`, `config.example.yaml` (create) — per `go-selfhosted-backend` skill conventions; SQLite volume mount, no CGO.
- **1.3** `README.md` (create) — purpose, quickstart, **trust model section** documenting both auth paths: (a) the `127.0.0.1` + reverse-proxy + Authelia forward-auth + `Remote-User` chain (with a sample Caddy `forward_auth` snippet), and (b) the OIDC bearer flow against Authelia (sample Authelia `identity_providers.oidc.clients` entry + sample lethe `auth.oidc` config). **Backup section** with the `sqlite3 .backup` cron snippet.
- **1.4** `cmd/lethe/main.go` (create, ~30 lines) — `flag.String("config", ...)`, prints version and exits. Real wiring in Phase 9.
- **1.5** `internal/shared/wire/wire.go` (create, ~40 lines) — `TurnEvent`, `SessionMeta` exactly as specified in Design. No methods; pure data. Locked contract for #2.
- **Invariant:** `internal/shared/wire/` published-API-discipline (Principles).
- Commit: `feat: bootstrap lethe server skeleton + wire contract`

### Phase 2 — Config

- **2.1** `internal/config/config.go` (create, ~190 lines) — `Config` struct with `Server`, `Database`, `Auth`, `Logging`, `Ingest` substructs. Each substruct has `mapstructure`, `validate`, **and `config-section:""`** tags so steward can `inject` them by type into individual services.
  - `Database` substruct: `Path string` (sqlite file path), `BusyTimeout time.Duration` (default 5s).
  - `Auth` substruct: `AllowedUsers []string`, `Admins []string` (subset of allowed users; may be empty), `ForwardAuth ForwardAuthConfig{ Enabled bool; UserHeader string (default "Remote-User") }`, `OIDC OIDCConfig{ Enabled bool; Issuer string (URL); Audience string; UsernameClaim string (default "preferred_username") }`.
  - `Ingest` substruct: `MaxBodyBytes int64` (default 16 MiB), `MaxTurnContentBytes int64` (default 4 MiB), `ChunkSize int` (default 500).
  - `Server` substruct: `Bind string`, `ShutdownGrace time.Duration` (default 10s).
  - `func Load(path string) (*Config, error)` — viper strict mode, validator, env-var overrides via `viper.SetEnvPrefix("LETHE")` + `viper.AutomaticEnv()` + `viper.SetEnvKeyReplacer(NewReplacer(".", "_"))`, returns `culpa` error on failure.
  - `func MustLoad(path string) *Config` — wraps `Load`, panics on error. Used by `main.go`.
  - Validation: `Server.Bind` must equal `127.0.0.1` or `127.0.0.1:<port>` (regex); `Database.Path` `required`; at least one of `Auth.ForwardAuth.Enabled` or `Auth.OIDC.Enabled` must be true (custom validator: `auth_at_least_one`); `Auth.AllowedUsers` `min=1`; every entry in `Auth.Admins` must also appear in `Auth.AllowedUsers` (custom validator: `admins_subset_of_allowed`); if OIDC enabled, `Auth.OIDC.Issuer` `url` and `Auth.OIDC.Audience` `required`; `Ingest.MaxBodyBytes` `gt=0`, `Ingest.MaxTurnContentBytes` `gt=0,ltefield=MaxBodyBytes`, `Ingest.ChunkSize` `gt=0`.
- **2.2** `internal/config/config_test.go` (create, TDD) — tests for: empty allowlist rejected; non-loopback bind rejected; both auth modes disabled rejected; OIDC enabled without issuer rejected; OIDC enabled with non-URL issuer rejected; admin not in allowed_users rejected; empty admins list accepted; missing `Database.Path` rejected; `MaxTurnContentBytes > MaxBodyBytes` rejected; unknown YAML key rejected (strict mode); env override works (`LETHE_AUTH_ALLOWED_USERS` overrides YAML); valid forward-auth-only config loads; valid OIDC-only config loads; valid both-enabled config loads; defaults applied (`UserHeader="Remote-User"`, `UsernameClaim="preferred_username"`, `MaxBodyBytes=16MiB`, `MaxTurnContentBytes=4MiB`, `ChunkSize=500`, `BusyTimeout=5s`, `ShutdownGrace=10s`).
- **Invariants:** auth allowlist has no default (Principles); listener binds 127.0.0.1 only.
- Commit: `feat(config): viper-loaded config with fail-fast validation`

### Phase 3 — Database & schema

- **3.1** `internal/platform/database/database.go` (create, ~110 lines) — `Database` is a steward service.
  - `type Database struct { Cfg config.DatabaseConfig \`config:""\`; DB *sqlx.DB }` — `DB` populated in `Init`.
  - `func (d *Database) Init(ctx context.Context) error` — opens via `modernc.org/sqlite` with `_journal_mode=WAL`, `_busy_timeout=5000`, `_foreign_keys=on`, `_synchronous=NORMAL`, `cache=shared`; then runs `Migrate(d.DB)`.
  - `func (d *Database) Destroy(ctx context.Context) error` — closes the DB.
  - `func Migrate(db *sqlx.DB) error` — runs `embed.FS` migrations via `golang-migrate/v4` `iofs` source + `sqlite` driver. Pure function so tests can call it directly.
  - `func InTx(ctx, db, fn func(*sqlx.Tx) error) error` — transaction helper, rollback on error. Pure function.
  - Other services depend on this via `inject:""` and read `.DB`.
- **3.2** `internal/platform/database/migrations/0001_init.up.sql` + `.down.sql` (create) — sessions, turns, turns_fts (FTS5 over `content` + `owner UNINDEXED`), tool_outputs_fts (FTS5 over `tool_calls` + `owner UNINDEXED`), insert/update/delete triggers for both FTS tables (triggers carry `owner` from source row). Composite PKs: `sessions(owner, tool, host, session_id)`; `turns(owner, tool, host, session_id, turn_id)` with FK `(owner, tool, host, session_id)` → sessions. All timestamps (`started_at`, `ended_at`, `turns.timestamp`) are `INTEGER NOT NULL` (unix epoch seconds). `tool_calls`, `metadata` are `TEXT` storing JSON. Index on `sessions(owner, started_at DESC)` for timeline.
- **3.3** `internal/platform/database/migrations.go` (create, ~10 lines) — `//go:embed migrations/*.sql` `var FS embed.FS`.
- **3.4** `internal/platform/database/database_test.go` (create, TDD) — tests with `:memory:` DB: migrate is idempotent on second run; turn insert populates `turns_fts` with correct `owner`; turn update updates `turns_fts`; turn delete removes from `turns_fts`; same for `tool_outputs_fts` when `tool_calls` non-NULL; FK rejects orphan turn; two owners with same `(tool, host, session_id)` coexist as distinct sessions; FTS query with `owner = ?` filter returns only that owner's rows.
- **Invariants:** WAL + busy_timeout + FKs on; FTS tables only via triggers; embed.FS migrations only.
- Commit: `feat(db): SQLite schema with FTS5 + migration runner`

### Phase 4 — Observability & health

- **4.1** `internal/platform/observability/logger.go` (create, ~110 lines) — `Logger` steward service.
  - `type Logger struct { Cfg config.LoggingConfig \`config:""\`; L *slog.Logger }`
  - `func (l *Logger) Init(ctx) error` — builds `scribe.NewTintHandler` (or JSON handler per cfg), applies `WithLevel`, `WithMaskKeys("password","token","authorization","secret","cookie")`, wraps with a small `contextHandler` that pulls `request_id` and `user` from `r.Context()` and adds them to every record. Sets `slog.SetDefault(l.L)`.
  - `func WithRequestID(ctx, id string) context.Context`, `func RequestIDFrom(ctx) string` — context helpers used by the request-id middleware in Phase 5.
- **4.2** `internal/platform/observability/metrics.go` (create, ~80 lines) — `Metrics` steward service.
  - `type Metrics struct { Registry *prometheus.Registry; HTTPRequests *prometheus.CounterVec; HTTPDuration *prometheus.HistogramVec; IngestLinesAccepted, IngestLinesErrored, IngestChunksCommitted prometheus.Counter }`
  - `func (m *Metrics) Init(ctx) error` — `prometheus.NewRegistry()`; register `collectors.NewProcessCollector` + `collectors.NewGoCollector`; register HTTP histograms with labels `{method, route, status}` (route from `chi.RouteContext(r.Context()).RoutePattern()` — never raw path, to keep cardinality bounded); register ingest counters.
  - HTTP middleware in Phase 5 reads from `Metrics`; ingest service in Phase 7 increments the ingest counters.
- **4.3** `internal/platform/health/health.go` (create, ~90 lines)
  - `type Checker interface { Name() string; Check(ctx context.Context) error }`
  - `type DBCheck struct { DB *database.Database \`inject:""\` }` — implements `Checker`; registered as a steward service tagged for multi-injection. `Check` runs `SELECT 1`.
  - `type Set struct { Checks []Checker \`inject:""\` }` — steward multi-injects every registered `Checker`.
  - `func (s *Set) Run(ctx) (results map[string]error, allOK bool)` — applies a per-check 2s timeout via `context.WithTimeout`. Empty `Checks` slice → returns `allOK = true` (intentional: no checks means nothing has declared a readiness signal yet, not an error).
  - Adding new checks later = registering a new asset that implements `Checker`. No edits to `Set`.
- **4.4** `internal/platform/health/health_test.go` (create, TDD) — `Set` returns aggregate failure when any check errors; passes when all OK; empty `Checks` returns `allOK=true`; per-check timeout enforced. Uses fake `Checker` implementations (no steward needed for unit test).
- **4.5** `internal/platform/steward_unwind_test.go` (create, TDD, throwaway after Phase 4) — confirms steward calls `Destroy` on already-init'd siblings when a later component's `Init` errors; if it doesn't, `Database.Destroy` won't run on partial-init failures and we need to add an explicit guard in `main`. Verifies the assumption underpinning the lifecycle design.
- Commit: `feat(platform): scribe logger, prometheus registry, health checker set`

### Phase 5 — HTTP foundation

- **5.1** `internal/pkg/apierror/apierror.go` (create, ~80 lines)
  - `type Problem struct { Type, Title, Status, Detail, Code, Instance, Errors }` — RFC 7807 shape.
  - `func Render(w, r, err error)` — extracts `culpa.Code` from `err`, maps to HTTP status (NotFound→404, Invalid→400, Unauthorized→401, Forbidden→403, Conflict→409, Internal→500), writes `application/problem+json`. 5xx logs full stacktrace via `scribe.Err` before sanitizing.
- **5.2** `internal/pkg/httputil/httputil.go` (create, ~50 lines) — `ReadJSON`, `WriteJSON`, `ReadNDJSONLines(r io.Reader, maxBytes int64) iter.Seq2[[]byte, error]`.
- **5.3** `internal/server/server.go` (create, ~150 lines) — `Server` is the steward root service.
  - `type Server struct { Cfg config.ServerConfig \`config:""\`; Log *observability.Logger \`inject:""\`; Metrics *observability.Metrics \`inject:""\`; Health *health.Set \`inject:""\`; Auth *auth.Authenticator \`inject:""\`; Ingest *ingest.Handler \`inject:""\`; Sessions *session.Handler \`inject:""\`; httpSrv *http.Server }`
  - `func (s *Server) Init(ctx) error` — builds chi router, mounts middleware stack:
    - **request-id**: generate ULID, set on context via `observability.WithRequestID`, echo as `X-Request-ID` response header.
    - **logging**: structured access log per request, picks up request-id automatically via the `contextHandler` from Phase 4.1. Body never logged.
    - **metrics**: increments `Metrics.HTTPRequests` and observes `Metrics.HTTPDuration` using `chi.RouteContext(r.Context()).RoutePattern()` as the `route` label.
    - **recovery**: panics → 500 problem.
  - Unauthenticated routes: `GET /healthz` (process up), `GET /readyz` (calls `s.Health.Run` with 5s timeout, 503 on any failure), `GET /metrics` (`promhttp.HandlerFor(s.Metrics.Registry, promhttp.HandlerOpts{})`).
  - Authed `/api/v1/*` group with `s.Auth.Middleware` then `s.Ingest.Mount(r)` and `s.Sessions.Mount(r)` (paths inside `Mount` are relative to the `/api/v1` group).
  - Validates `Cfg.Bind` resolves to a loopback IP — error otherwise.
  - `func (s *Server) Start(ctx) error` — spawns `http.Server.ListenAndServe` in a goroutine; returns nil immediately. Errors propagate via stop channel.
  - `func (s *Server) Stop(ctx) error` — `httpSrv.Shutdown(ctx)` with `Cfg.ShutdownGrace` (default 10s) drain budget. In-flight ingest chunks finish their commit; partially-processed batches return their `Accepted` count truthfully.
  - `steward.Root()` so it's always started even if no other component injects it.
- **5.4** `internal/pkg/apierror/apierror_test.go` (create, TDD) — each culpa code maps to expected status; problem JSON has all required fields; internal-error response detail is sanitized (no stack trace in body).
- **5.5** `internal/server/server_test.go` (create, TDD) — non-loopback bind returns error from `Server.Init`; recovery middleware turns panic into 500 problem; request-id propagates to log lines. Tests construct `Server` directly with hand-built deps (skip steward; unit test of router behavior).
- **Invariants:** errors rendered as RFC 7807; 5xx logged with stack; bind 127.0.0.1 enforced.
- Commit: `feat(http): chi server with middleware stack + RFC 7807 problem renderer`

### Phase 6 — Auth middleware (forward-auth + OIDC bearer)

- **6.1** `internal/server/auth/oidc.go` (create, ~140 lines) — `OIDCVerifier` is a steward service, registered conditionally in `main` only when `cfg.Auth.OIDC.Enabled`.
  - `type OIDCVerifier struct { Cfg config.OIDCConfig \`config:""\`; verifier *oidc.IDTokenVerifier; usernameClaim string }`
  - `func (v *OIDCVerifier) Init(ctx) error` — builds `oidc.NewProvider(ctx, Cfg.Issuer)` (which fetches `/.well-known/openid-configuration` + JWKS) and `provider.Verifier(&oidc.Config{ClientID: Cfg.Audience})`. Accepts `go-oidc` default clock skew (no explicit option). Hard-fails at startup if Authelia unreachable; that's the chosen tradeoff (see Risks).
  - `func (v *OIDCVerifier) Verify(ctx, raw string) (user string, err error)` — validates JWT, extracts username via `usernameClaim`, falls back to `sub`. Returns `culpa.Unauthorized`-coded error on any validation failure.
- **6.2** `internal/server/auth/middleware.go` (create, ~150 lines) — `Authenticator` is a steward service.
  - `type Authenticator struct { Cfg config.AuthConfig \`config:""\`; Log *observability.Logger \`inject:""\`; Verifier *OIDCVerifier \`inject:"" optional:"true"\`; allowed, admins map[string]struct{} }`
  - `func (a *Authenticator) Init(ctx) error` — builds `allowed` and `admins` lowercase sets from `Cfg.AllowedUsers` / `Cfg.Admins`; if `Cfg.OIDC.Enabled && Verifier == nil` → hard error (config invariant breach).
  - `func (a *Authenticator) Middleware(next http.Handler) http.Handler` — resolution order: (1) if OIDC enabled and `Authorization: Bearer <token>` present, call `Verifier.Verify`; (2) if forward-auth enabled and `<UserHeader>` non-empty, take it; (3) else 401 problem. After resolving user: lowercase, check `allowed`, 403 problem on miss, otherwise put `Identity{User, IsAdmin}` into request context via `WithIdentity` and call `next`.
  - `type Identity struct { User string; IsAdmin bool }`
  - `func WithIdentity(ctx, Identity) context.Context`, `func IdentityFrom(ctx) (Identity, bool)`, `func MustIdentity(ctx) Identity` — context helpers used by handlers.
  - Caller (`Server.Init`) mounts middleware on `/api/v1/*` only; `/healthz`, `/readyz`, `/metrics` unmounted (Phase 5/9).
- **6.3** `internal/server/auth/middleware_test.go` (create, TDD) — table-driven against an in-memory router:
  - **Forward-auth path** (OIDC disabled): missing header → 401; header set, user not in allowlist → 403; header set, allowed → 200; case-insensitive allowlist match → 200; configurable header name (`X-Forwarded-User`) honored → 200.
  - **OIDC path** (forward-auth disabled): missing `Authorization` → 401; malformed bearer → 401; valid JWT signed by test JWKS, allowed user → 200; valid JWT, user not in allowlist → 403; expired JWT → 401; wrong-audience JWT → 401; `preferred_username` claim used; falls back to `sub` when `preferred_username` absent.
  - **Both enabled**: bearer present and valid → user resolved from JWT (header ignored); bearer invalid + header present → 401 (do not silently fall back to header — fail closed); both absent → 401.
  - **Admin flag**: user in `Auth.Admins` → `IdentityFrom(ctx).IsAdmin == true`; user not in admins → `false`; admin not in `AllowedUsers` rejected at config load (covered in Phase 2 tests).
  - Test helper sets up a local `httptest.Server` serving JWKS + OIDC discovery + signs JWTs with a generated RSA key; pointed at by the verifier under test.
  - Problem JSON shape verified for 401 and 403.
- **Invariant:** every `/api/v1/*` route validates auth; only `/healthz`, `/readyz`, `/metrics` exempt (enforced by mount point in Phase 9). Same `auth.allowed_users` allowlist applied regardless of which auth path resolved the user.
- Commit: `feat(auth): forward-auth + OIDC bearer middleware with shared allowlist`

### Phase 7 — Ingest domain

- **7.1** `internal/domain/ingest/repository.go` (create, ~140 lines) — `Repository` is a steward service.
  - `type Repository struct { Database *database.Database \`inject:""\` }`
  - `func (r *Repository) UpsertChunk(ctx, tx *sqlx.Tx, owner string, turns []wire.TurnEvent) error` — single tx: per turn, `INSERT … ON CONFLICT (owner,tool,host,session_id) DO UPDATE SET ended_at = MAX(ended_at, excluded.ended_at)` for sessions (first-write-wins on metadata); `INSERT … ON CONFLICT (owner,tool,host,session_id,turn_id) DO UPDATE SET <all non-key cols>` for turns. `owner` is bound from the parameter on every row — never sourced from the wire payload. `started_at` falls back to `MIN(turn.timestamp)` when `SessionMeta.StartedAt` is nil.
- **7.2** `internal/domain/ingest/service.go` (create, ~160 lines) — `Service` is a steward service.
  - `type Service struct { Cfg config.IngestConfig \`config:""\`; Repo *Repository \`inject:""\`; Log *observability.Logger \`inject:""\`; Metrics *observability.Metrics \`inject:""\` }`
  - `type Result struct { Accepted int; Errors []LineError }`
  - `func validateTurn(t wire.TurnEvent, maxContentBytes int64) error` — required fields (`tool`, `host`, `session_id`, `turn_id`, `seq`, `role`, `timestamp`, `content` non-empty); `role ∈ {user, assistant, tool, system}`; `len(content) ≤ maxContentBytes`; `len(SessionMeta.SourceFile) ≤ 1024`. Returns `culpa.Invalid`-coded error on failure.
  - `func (s *Service) Ingest(ctx, owner string, body io.Reader, maxBytes int64) (Result, error)` — reads NDJSON via `httputil.ReadNDJSONLines`; per line: JSON-unmarshal then `validateTurn`; buffers up to `Cfg.ChunkSize` lines; on full chunk, opens tx and calls `Repo.UpsertChunk(ctx, tx, owner, chunk)`; on commit success, increments `Metrics.IngestChunksCommitted` and `IngestLinesAccepted` by chunk len, adds chunk len to `Accepted`; on parse/validation/DB error mid-chunk, rolls back chunk, increments `IngestLinesErrored`, logs at WARN with line number, owner, `tool/host/session_id`, returns with `Accepted` reflecting prior chunks plus a `LineError` for the failing line; subsequent lines are not processed.
- **7.3** `internal/domain/ingest/handler.go` (create, ~70 lines) — `Handler` is a steward service.
  - `type Handler struct { Cfg config.IngestConfig \`config:""\`; Service *Service \`inject:""\` }`
  - `func (h *Handler) Post(w, r)` — extract `auth.MustIdentity(r.Context()).User` as owner, `Content-Type` check, body limit reader at `Cfg.MaxBodyBytes`, calls `Service.Ingest(ctx, owner, ...)`, returns `200 {"accepted": N, "errors": [...]}`. Hard server errors (DB down) → 5xx problem with empty `accepted`.
  - `func (h *Handler) Mount(r chi.Router)` — `r.Post("/ingest", h.Post)`. Called by `Server.Init`.
- **7.4** `internal/domain/ingest/service_test.go` + `repository_test.go` (create, TDD) — tests against `:memory:` DB:
  - **Wire validation**: each required field missing → `LineError`; bad `role` value → `LineError`; `content` over `MaxTurnContentBytes` → `LineError` (not 413, body still under cap); `source_file` over 1024 → `LineError`. All other lines in the same chunk that came before the bad line still commit.
  - Idempotency: posting same NDJSON twice as the same owner produces identical row counts and identical row contents.
  - First-write-wins on session: posting turn-1 with WorkingDir=A then turn-2 with WorkingDir=B leaves session.WorkingDir=A.
  - Last-write-wins on turn: re-posting same turn_id with new content updates the row.
  - `ended_at` extends: `MAX(existing, incoming)`.
  - `started_at` fallback to MIN turn timestamp when SessionMeta.StartedAt is nil.
  - Chunked partial accept: 3-chunk batch with bad line in chunk 3 returns `Accepted = 2*chunkSize`, error references correct line number.
  - FK violation produces a LineError, not a 5xx.
  - DB-down → 5xx, no Accepted.
  - Body over `MaxBodyBytes` → 413 problem.
  - FTS rows present after ingest with correct `owner` (`turns_fts` contains turn content; `tool_outputs_fts` contains tool_calls JSON when present).
  - **Per-user isolation**: same NDJSON ingested by user A then by user B produces two distinct sessions and two distinct sets of turns; rows have correct `owner`. Modifying user B's session's `ended_at` does not affect user A's row.
  - **Wire `owner` is ignored**: a TurnEvent JSON line that includes a stray `"owner": "evil"` field (not in the wire struct) does not change the stored owner; ingest still attributes to the authenticated user. (Negative test against the trust model.)
- **Invariants:** ingest is idempotent at turn level per owner; owner is server-derived; chunked-commit-with-partial-accept semantics; first-write-wins session, last-write-wins turn.
- Commit: `feat(ingest): NDJSON ingest with chunked transactions and partial-accept`

### Phase 8 — Sessions read API

- **8.1** `internal/domain/session/repository.go` (create, ~150 lines) — `Repository` is a steward service.
  - `type Repository struct { Database *database.Database \`inject:""\` }`
  - `type OwnerScope struct { User string; AllOwners bool; SpecificOwner *string }` — resolved by handler from identity + `?owner=` param.
  - `type ListFilter struct { Owner OwnerScope; Tool, Host *string; Since, Until *int64; Limit, Offset int }`
  - `func (r *Repository) List(ctx, f ListFilter) ([]Session, error)` — dynamic WHERE built from non-nil filters; owner clause: if `AllOwners` no clause, if `SpecificOwner` `WHERE owner = ?`, else `WHERE owner = User`; `ORDER BY started_at DESC`; `LIMIT/OFFSET`.
  - `func (r *Repository) Get(ctx, scope OwnerScope, tool, host, sessionID string) (*SessionWithTurns, error)` — owner clause same as above; joined select; returns `culpa.NotFound` when session missing **or owner mismatch** (do not leak existence by returning 403 vs 404 — a non-admin asking for someone else's session must see the same 404 as if the session didn't exist).
- **8.2** `internal/domain/session/handler.go` (create, ~120 lines) — `Handler` is a steward service.
  - `type Handler struct { Repo *Repository \`inject:""\` }`
  - Pagination defaults: `limit=50` default, `limit` capped at 200, negative `limit`/`offset` clamped to default/0. `since > until` → 400 problem.
  - `func (h *Handler) resolveScope(r) (OwnerScope, error)` — read `auth.MustIdentity(r.Context())`, parse `?owner=`; if param empty → scope is current user; if param non-empty and identity is admin → scope is `SpecificOwner` (or `AllOwners` for `?owner=*`); if param non-empty and identity is **not** admin → 403 problem.
  - `func (h *Handler) List(w, r)` — `resolveScope`, parse other query params (`tool`, `host`, `since`, `until`, `limit`, `offset`), calls `Repo.List`, writes JSON.
  - `func (h *Handler) Get(w, r)` — `resolveScope`, chi URL params, calls `Repo.Get`, writes JSON; 404 problem when not found (auto via apierror).
  - `func (h *Handler) Mount(r chi.Router)` — `r.Get("/sessions", h.List)`; `r.Get("/sessions/{tool}/{host}/{session_id}", h.Get)`. Called by `Server.Init`.
- **8.3** `internal/domain/session/repository_test.go` + `handler_test.go` (create, TDD) — tests against `:memory:` DB:
  - Filters compose correctly (tool only, host only, time range, all combined); pagination caps `limit` (e.g. max 200) and clamps negatives; ordering by `started_at` desc; turns inline in correct order by `seq`.
  - **Per-user isolation (List)**: with rows owned by A and B, a request authenticated as A returns only A's rows. B's rows do not appear regardless of filter combination.
  - **Per-user isolation (Get)**: A asking for B's session by URL → 404 problem (not 403 — must not leak existence). A asking for own session → 200.
  - **Admin override**: admin with `?owner=B` lists/gets B's rows. Admin with `?owner=*` lists across all owners. Admin without `?owner=` defaults to admin's own rows (no implicit cross-tenant view).
  - **Non-admin `?owner=` rejected**: non-admin user A passing `?owner=A` (their own user!) or `?owner=B` → 403 problem. (Param is admin-only; non-admins must not pass it at all.)
- **Invariants:** errors rendered as RFC 7807; composite PKs throughout; per-user isolation enforced; existence never leaked across owners.
- Commit: `feat(session): list and detail JSON API with filters`

### Phase 9 — Main wiring + ops surface

- **9.1** `cmd/lethe/main.go` (modify, ~70 lines) — thin shell. No business logic; everything is a steward asset.
  ```go
  cfg := config.MustLoad(*configPath)
  mgr := steward.NewManager()
  mgr.AddComponent(ctx,
      steward.MustConfigurationAsset(cfg),
      steward.MustServiceAsset(&observability.Logger{}),
      steward.MustServiceAsset(&observability.Metrics{}),
      steward.MustServiceAsset(&database.Database{}),
      steward.MustServiceAsset(&health.DBCheck{}),     // registers as Checker
      steward.MustServiceAsset(&health.Set{}),
      steward.MustServiceAsset(&auth.Authenticator{}),
      steward.MustServiceAsset(&ingest.Repository{}),
      steward.MustServiceAsset(&ingest.Service{}),
      steward.MustServiceAsset(&ingest.Handler{}),
      steward.MustServiceAsset(&session.Repository{}),
      steward.MustServiceAsset(&session.Handler{}),
      steward.MustServiceAsset(&server.Server{}, steward.Root()),
  )
  if cfg.Auth.OIDC.Enabled {
      mgr.AddComponent(ctx, steward.MustServiceAsset(&auth.OIDCVerifier{}))
  }
  must(mgr.Inject(ctx)); must(mgr.Init(ctx)); must(mgr.Start(ctx))
  // wait on SIGINT/SIGTERM
  must(mgr.Stop(stopCtx)); must(mgr.Destroy(ctx))
  ```
  - All routes mounted by `Server.Init` (Phase 5.3): `/healthz`, `/readyz`, `/metrics` outside the auth group; `/api/v1/*` inside `Authenticator.Middleware`. Main does **not** touch chi.
  - Signal handling: `signal.NotifyContext(ctx, SIGINT, SIGTERM)` → on cancel, `mgr.Stop(ctx with 15s deadline)` → `mgr.Destroy(ctx)` → exit.
- **9.2** `cmd/lethe/main_test.go` (create, TDD, light) — end-to-end smoke via `steward.Manager` assembled in-test with a `:memory:` DB and a random-port `Server`: POST a fixture NDJSON as user A, GET sessions list as A (sees own row), GET session detail as A. Then POST a fresh batch as user B with the same `(tool, host, session_id)` and confirm both rows coexist; A still only sees A's. Confirms wiring + isolation reaches all the way through the steward graph.
- **9.3** `README.md` (modify) — fill in real config example with all keys (including both `auth.forward_auth` and `auth.oidc` blocks), add curl commands for ingest + list + detail (one variant with `Remote-User` for testing forward-auth, one variant with `Authorization: Bearer …` for OIDC), finalize the dual-auth trust-model section and backup section.
- **Invariant:** only `/healthz`, `/readyz`, `/metrics` are unauthenticated; mounting layout enforces this.
- Commit: `feat(cmd): wire server with /healthz /readyz /metrics + authed /api/v1`

### Order & dependencies

Linear: each phase depends on all prior phases. Phase 4 (observability/health) and Phase 5 (HTTP foundation) could parallelize but commit-coupling makes it not worth it. No phase can land before its dependencies (config → db → platform → http → auth → handlers → main).

### Open questions / risks / rollback

- **Risk:** `golang-migrate/v4` + `modernc.org/sqlite` driver compatibility — multiple-statement migrations (FTS triggers) may need `;` handling. **Mitigation:** Phase 3 test asserts migration applies; if it fails, swap to per-statement execution or `goose`.
- **Risk:** FTS5 trigger SQL on UPSERT — SQLite doesn't fire UPDATE triggers from `INSERT … ON CONFLICT … DO UPDATE` in older versions. **Mitigation:** Phase 3 test specifically covers UPSERT path; if triggers don't fire, replace UPSERT with explicit `SELECT then INSERT/UPDATE`.
- **Risk:** OIDC discovery on startup blocks if Authelia is down. **Mitigation chosen:** fail fast — `NewOIDCVerifier` errors propagate from `main`, lethe refuses to start. Acceptable because Authelia is on the same host; if Authelia is down lethe is unusable anyway. Forward-auth-only deployments are unaffected.
- **Open:** Authelia OIDC client registration is a manual step on the Authelia side — not in this repo. Documented in Phase 9.3 README only.
- **Rollback:** greenfield, single `git revert` per phase commit.

### Backwards-compat check

Greenfield — no compat surface. Wire format is the only forward-compat concern; pinned in `internal/shared/wire/` and `/api/v1/` URL prefix per Design. No further checks needed.

### Acknowledged out-of-scope (won't surface in this task, listed so they aren't re-discovered later)

- Rate limiting on `/api/v1/ingest` — body cap + per-turn content cap are the only safeguards in v1.
- OpenAPI spec / generated client — collector (#2) hand-writes against `internal/shared/wire/`.
- CORS — JSON API behind reverse proxy on the same origin; not needed.
- Cursor-based pagination / total-count on `/api/v1/sessions` — offset+limit is enough for the expected volume.
- Per-route per-user rate limits (would need `Authenticator` to expose a per-identity bucket).
- Pluggable auth backends beyond Authelia (the OIDC verifier is generic enough that pointing at a different IdP works, but only Authelia is documented).

## Conclusion

### Deviations from plan

- **Phase 1**: `go.mod` directive is `go 1.25.0`, not `go 1.22+`. `go get` of golang-migrate/v4.19, viper 1.21, and prometheus 1.23 forced the bump (each requires ≥1.24). Plan said "Go 1.22+" so this satisfies the floor; flagging because the explicit number changed and the Dockerfile builder image was bumped to `golang:1.25-alpine` to match (consistency fix folded into the same Phase 1 commit).
- **Phase 1**: added `internal/deps/deps.go` with blank imports of every direct dep so `go mod tidy` keeps them in `go.mod` until real packages start importing them. Transitional file; expected to shrink each phase and disappear by end of Phase 9. Without it, `go mod tidy` strips the dep stub the plan called for.
- **Phase 1**: `.golangci.yml` uses the v2 schema (golangci-lint 2.11.4 rejects v1). Same lint set as the plan listed (errcheck, govet, staticcheck, revive, gosec, unused, gofmt, goimports).

### Notes carried forward

- Phase 3 should add `migrate-up`, `migrate-down`, `migrate-create` to the Justfile alongside the migration runner so the targets aren't dead. (Done in Phase 3.)
- Each phase from 2 onward must remove the dep it adopts from `internal/deps/deps.go`; Phase 9 deletes the file.
- README's Caddy/Authelia snippets use `auth.example.com` placeholders; replace with phoebe-specific values when the production deploy lands (out of scope for this task).
- **Phase 4 finding (steward unwind gap)**: `steward.Manager.Init` returns on the first failing `CallInit` and does **not** iterate back over previously-initialized assets to call `Destroy`. The canary test `TestStewardUnwindsOnInitFailure` (in `internal/platform/health/steward_unwind_test.go`) is intentionally red on master to document this. **Phase 9 main must compensate**: track each component as it init's and, on `Init` error, walk the list in reverse calling `Destroy` directly on each (don't try `mgr.Stop`/`mgr.Destroy` — those panic unless the manager has reached Started). Once Phase 9 lands the explicit unwind, either delete the canary test or convert it to assert the new compensating behavior.
- **Phase 5 consistency fix (folded into commit `3c45b48` via amend)**: chi's default 404/405 handlers wrote text/plain, violating the invariant "errors leaving any HTTP handler are rendered as RFC 7807". Added explicit `chi.Router.NotFound`/`MethodNotAllowed` handlers that call `apierror.Render` with `NOT_FOUND` / `METHOD_NOT_ALLOWED` codes. Added `METHOD_NOT_ALLOWED → 405` entry to the apierror code-status map. Added two regression tests.
- **Phase 7**: added `UNSUPPORTED_MEDIA_TYPE → 415` entry to `apierror.codeStatus` (ingest handler enforces `application/x-ndjson` Content-Type). Repository simulates DB-down by closing the underlying `*sql.DB` (cleaner than service-faking, mirrors real driver-disconnect failure). Service-level FK test omitted because the schema makes it unreachable through the Service path (parent session is upserted in the same chunk); equivalent Repository-level test pins the wrap-and-classify code path.
- **Phase 8**: introduced `JSONText` (sql.Scanner wrapper) for nullable TEXT-JSON columns — `json.RawMessage` cannot Scan NULL directly. External JSON shape unchanged. If Phase #3 (search) wants the same scan-safety, factor up to `internal/pkg/sqljson`.
- **Phase 9**: refactored `Server.Start` to `net.Listen` first then `http.Serve(listener)` plus added `Server.Addr()` so `:0` binds report the kernel-assigned port — enables the e2e smoke to bind to a random port without races. `cmd/lethe/main.go` uses a `run() int` shell so tests can drive it. Steward unwind canary `internal/platform/health/steward_unwind_test.go` deleted; `main.go`'s reverse-order `unwindOnError` compensator is now the production guarantee. Bootstrap stderr slog handler installed before any asset registration so the unwind path always has a logger.

### Final state

- All 9 phases committed (`4ca03be` → `53221c9`).
- `go test ./... -race -count=1` fully green; no allowed-red exception.
- `go vet`, `gofmt -l`, `go mod tidy`, `golangci-lint run ./...` all clean.
- Manual smoke: lethe binary built and ran against `config.example.yaml`; `/healthz`, `/readyz`, `/metrics`, unauthed `/api/v1/sessions` (401), authed `/api/v1/sessions` with `Remote-User: bigbes` (200) all behaved as designed; SIGTERM triggered clean shutdown via the steward graph.
- **Phase 3 → Phase 7 contract pin**: `INSERT … ON CONFLICT … DO UPDATE` fires the UPDATE trigger on SQLite (verified by `TestUpsertFiresUpdateTriggerAndKeepsFTSCoherent`). Regular FTS5 (not contentless / external content) was chosen so `WHERE owner = ?` works on the FTS table without a join — accepted the storage cost (`content` duplicated in real table + FTS shadow). Composite key order is `(owner, tool, host, session_id[, turn_id])` everywhere; ingest INSERT/UPDATE/ON CONFLICT clauses must match. `started_at`/`ended_at`/`source_file` are `NOT NULL` — ingest derives `started_at` from `MIN(turn.timestamp)` when `SessionMeta.StartedAt` is absent.