Codebase Rewrite

Progress

Operating rules

1. Program to the Interface. Domain services import ports, never concrete adapters.
2. Wire once. Concrete construction belongs in server.py or a dedicated application factory.
3. TDD is mandatory. No production Interface or Object is written before its failing test. Work proceeds Red → Green → Refactor.
4. Characterize before moving. Characterization tests pin public output, errors, caching, locking, and failure behavior before legacy code moves.
5. Types are executable contracts. Python boundaries use strict Pydantic models; new browser code uses strict TypeScript.
6. Keep pure code simple. Pure transforms remain functions; do not create an Interface without a boundary.
7. Side effects require ports. Network, process, filesystem, database, clock, logging, metrics, and notifications are injected.
8. One slice per change. Interface, Object, adapter, tests, wiring, and compatibility shim travel together.
9. No live dependencies in unit tests. Use small fakes that implement the same port contract.
10. Preserve HTTP contracts. Status, headers, JSON shapes, timeouts, and route names stay stable unless separately approved.
11. Delete completed detail. Once a row meets its exit test, remove it from this ledger. Git is the completion history.

Strict typed contracts and test-first development

Python contract policy

ABCs describe behavior; Pydantic models describe data. Commands, results, API requests/responses, repository records, configuration, events, and adapter payloads use named models derived from one strict base:

from pydantic import BaseModel, ConfigDict

class StrictModel(BaseModel):
    model_config = ConfigDict(strict=True, extra="forbid", frozen=True)

• No unvalidated dict[str, Any] may cross a port. Validate once at the outer adapter, then pass typed models inward.
• No implicit coercion at a boundary: "1" is not accepted where an integer is required.
• Unknown fields fail closed through extra="forbid"; immutable DTOs prevent hidden mutation.
• Discriminated unions model variant results such as up/down/starting or receipt/statement/unknown.
• Every public function and method in a rewritten module has complete parameter and return annotations.
• Any, unparameterized containers, and blanket type ignores require a written decision-log exception.

Static checking runs with pyright --project dashboard/pyrightconfig.json, where typeCheckingMode = "strict". Runtime Pydantic validation complements static checking; neither replaces the other.

TypeScript contract policy

• All new frontend code is TypeScript (.ts), with strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, and useUnknownInCatchVariables.
• Existing JavaScript may remain only as legacy. A touched module is migrated or placed under // @ts-check with complete JSDoc types until migration is practical.
• No blind type assertions (as Foo) for HTTP JSON. A type guard or runtime schema validates unknown input first.
• Discriminated unions replace stringly typed status objects and scattered property checks.
• bunx tsc --noEmit -p dashboard/tsconfig.json must pass before tests and deployment.
• The TypeScript build emits browser JavaScript deterministically; generated output is never hand-edited.

TDD order for every ledger row

1. RED: write the consumer behavior test and run it. Record the expected failure; import/contract absence counts as red for a new extraction.
2. Add Characterization tests around the legacy seam so the behavior being preserved is explicit.
3. Add Shared contract tests that every concrete adapter and fake must pass.
4. Add Negative validation tests proving malformed types, missing fields, extra fields, and invalid variants are rejected.
5. GREEN: add only enough typed Interface/Object code to make the focused tests pass.
6. REFACTOR: remove duplication and improve names while the tests and type checkers stay green.
7. Run the focused suite, complete Python suite, complete browser suite, static type checks, and coverage gate.

Required test layers

Target architecture

dashboard/
  server.py                 # construct adapters, start threads/server, compatibility exports
  http/                     # route registry, controllers, HTTP/WebSocket adapters
  agents/                   # Letta gateway, directory, messaging, agent health
  server_management/        # health probes, logs, SSH, restart orchestration
  model_usage/              # usage sources, history, provider health/failover
  intake/                   # scanners, classification, staging, dispatch, Trainer
  finance/                  # expense/receipt/report repositories and services
  voice/                    # existing transcription/cleanup pipeline
  tests/                    # mirrors the production domains above

The directory names are targets, not a mandate to move everything at once. A slice may begin as one flat module when that keeps the change reviewable.

Definition of done for the rewrite

• server.py is startup and dependency wiring, ideally below 500 lines.
• DashboardHandler adapts HTTP to registered controllers and contains no business rules.
• Every concrete external dependency can be replaced by a test fake through constructor injection.
• All Python boundary data is strict Pydantic; all new frontend modules are strict TypeScript.
• Pyright and TypeScript complete with zero errors and no unexplained suppressions.
• test_server.py contains only composition/compatibility tests; domain tests live beside their domains.
• The complete Python and JavaScript dashboard suites pass without contacting live infrastructure.

Active Interface/Object ledger

Each work row is one reviewable extraction. The checkbox is deliberately visual rather than browser-persistent: completion is shared by deleting the row in source control, not by storing private state in one browser.

Established examples — do not move backward

These are outside the active count because they already demonstrate the intended shape.

One-slice workflow

1. Choose exactly one active row; record its current callers and mutable globals.
2. Write the failing consumer test first, run it, and save the RED command plus failure.
3. Add characterization, shared-contract, and negative-validation tests before production code.
4. Define the smallest fully typed ABC and strict Pydantic models in the owning domain. The abstract module imports no concrete adapter.
5. Implement only enough typed behavior for GREEN, including a minimal fake that passes the same contract tests.
6. Inject the port into the service/controller; construct the concrete only at the composition root.
7. Leave a temporary forwarding function in server.py when compatibility requires it.
8. Move relevant tests from test_server.py into the matching domain test file.
9. Refactor with tests green, then run Pyright, TypeScript, focused tests, full suites, coverage, and the relevant manual smoke check.
10. Record current line counts, delete this work row, and commit the shrinking plan with the implementation.

Required evidence in each handoff or PR

Slice:
Observed RED:
RED command and failure:
Interface:
Pydantic model(s):
TypeScript type(s):
Concrete Object(s):
Callers migrated:
Compatibility shim:
Focused tests:
Contract/negative tests:
Pyright result:
TypeScript result:
Branch coverage:
Full Python result:
Full JavaScript result:
server.py lines before/after:
test_server.py lines before/after:
Ledger row removed:

Decision log

2026-08-03 SSH compatibility slice: The Windows 10 Host SSH probe now routes through an injected ISshGateway port and OpenSshGateway Adapter, with ConfiguredIdentityStrategy owning deployment-specific key selection and ICommandRunner isolating subprocess execution. This replaces the previous target-specific command branch and makes the credential policy testable without a network. The focused gateway/server suite is green (368 tests), and all live dashboard instances now return CONNECTED — DESKTOP-SHDBATI. The working file measured 11,061 lines / 518,879 bytes after this slice versus 11,046 / 518,026 at HEAD: +15 lines, +853 bytes, +0.136%; the observed +15 includes +11 lines from the already-present SSH fallback patch and unrelated working-tree edits, so the slice-attributable delta is +4 lines (the compatibility shim/import). Current count is 575 above the 10,486 historical baseline (+5.48%). Last three commits are +90, +53, 0 lines; HEAD→worktree is +15 lines / +853 bytes. The non-negative delta is explained by introducing the port/adapter and its tests before deleting the compatibility shim; the next deletion target is ssh_test forwarding and the remaining raw SSH configuration in server.py.

2026-07-29

Use an incremental ports-and-adapters rewrite; do not replace the stdlib HTTP server or change routes as part of extraction.

2026-07-29

Interfaces are required at meaningful boundaries and all cross-cutting side effects. Pure transforms remain functions.

2026-07-29

Completed work rows are deleted instead of archived here, so this page becomes smaller as the rewrite advances.

2026-07-29

Begin with the green test baseline, then model usage as the pilot production slice.

2026-07-29

Adopt strict Pydantic v2 models for every Python boundary and strict TypeScript for all new frontend work; static and runtime validation are both required.

2026-07-29

Adopt strict TDD: witness RED before production code, reach GREEN minimally, then refactor; new domain/application modules require 100% branch coverage.

2026-07-30

Completed the model-read sub-slice of ILettaGateway: RED was pytest -q tests/test_letta_gateway.py failing because the agents boundary did not exist; GREEN was 14 focused gateway/model-option tests. Added strict frozen Pydantic contracts, FakeLettaGateway, UrllibLettaGateway, composition-root wiring, and a temporary agent_model_payload forwarding shim. The ledger row remains because messages, thoughts, tool calls, and write paths are not migrated.

2026-07-31

Completed the raw-message-read sub-slice of ILettaGateway: RED was pytest -q tests/test_letta_gateway.py failing to import the not-yet-created LettaAgentMessage; GREEN was 34 focused gateway tests plus 360 test_server.py tests. Added a strict immutable normalized message contract, shared fake/urllib behavior, fail-closed envelope and field validation, URL ownership in UrllibLettaGateway, and a temporary letta_messages forwarding shim. Installed/configured Pyright and branch coverage for the rewritten agents/ boundary; strict checking reports zero errors and the focused suite covers 229 statements and 90 branches at 100%. GoF dependency tests now prohibit application-service imports of concrete adapters and require the composition-root gateway plus compatibility shim to expose ILettaGateway explicitly; UrllibLettaGateway is constructed only in server.py. The public activity-view shapes and 25-second timeout remain unchanged. The ledger row remains for roster, thought/tool-call application services, and write paths.