refactor: architecture upkeep (#444) #491

2026-07-26T02:18:36-04:00

didericis-codex commented

2026-07-26 02:18:36 -04:00

Part of #444.

Focused architecture upkeep that completes the remaining work in the issue without changing the project’s security posture or adding runtime dependencies.

Issue coverage

Reconciliation

preserves the existing typed macOS enumeration failure path, which skips reconciliation rather than treating an unavailable snapshot as zero live bottles;
strictly validates /reconcile snapshots as lists of non-empty strings;
rejects boolean, string, negative, NaN, and infinite grace_seconds values before cleanup can run.

Architecture guardrails

removes Docker-only utility and plan imports from the generic start command;
moves slugify to a backend-neutral utility while retaining a Docker compatibility wrapper;
adds AST-enforced CLI/backend import boundaries;
adds lightweight global and focused module-size ceilings.

Egress decomposition

turns egress/addon_core.py into a small compatibility facade;
separates schema parsing, route matching, DLP scanning, shared types, and request-context resolution;
migrates runtime callers to focused modules while preserving existing public exports and fail-closed behavior.

Backend preparation

extracts shared launch preparation into a typed BottlePreparationPlanner;
adds a PreparationBackend protocol and typed PreparedBottle result;
leaves concrete backends responsible only for their hooks and final plan resolution.

Diagnostics and security

replaces silent optional backend-probe failures with typed, safe diagnostics;
surfaces optional TUI/detail failures with contextual debug/status reporting;
makes reconciliation and reprovision skips observable;
redacts exception messages from orchestrator 500 responses and logs, recording only safe context and exception type;
keeps egress and reconciliation paths fail-closed and adds regression tests ensuring sensitive exception text is not exposed.

Validation

2,396 unit tests pass under coverage;
296 focused tests pass after rebasing onto current main;
integration discovery passes (22 backend-dependent tests skipped because Firecracker/KVM are unavailable on this host);
changed-line coverage: 97.1% (534/550);
Pyright on tracked source: 0 errors, 0 warnings;
Pylint: 9.84/10;
compileall and git diff --check pass;
push-side gitleaks scan reports no leaks.

Part of #444. Focused architecture upkeep that completes the remaining work in the issue without changing the project’s security posture or adding runtime dependencies. ## Issue coverage ### Reconciliation - preserves the existing typed macOS enumeration failure path, which skips reconciliation rather than treating an unavailable snapshot as zero live bottles; - strictly validates `/reconcile` snapshots as lists of non-empty strings; - rejects boolean, string, negative, NaN, and infinite `grace_seconds` values before cleanup can run. ### Architecture guardrails - removes Docker-only utility and plan imports from the generic start command; - moves `slugify` to a backend-neutral utility while retaining a Docker compatibility wrapper; - adds AST-enforced CLI/backend import boundaries; - adds lightweight global and focused module-size ceilings. ### Egress decomposition - turns `egress/addon_core.py` into a small compatibility facade; - separates schema parsing, route matching, DLP scanning, shared types, and request-context resolution; - migrates runtime callers to focused modules while preserving existing public exports and fail-closed behavior. ### Backend preparation - extracts shared launch preparation into a typed `BottlePreparationPlanner`; - adds a `PreparationBackend` protocol and typed `PreparedBottle` result; - leaves concrete backends responsible only for their hooks and final plan resolution. ### Diagnostics and security - replaces silent optional backend-probe failures with typed, safe diagnostics; - surfaces optional TUI/detail failures with contextual debug/status reporting; - makes reconciliation and reprovision skips observable; - redacts exception messages from orchestrator 500 responses and logs, recording only safe context and exception type; - keeps egress and reconciliation paths fail-closed and adds regression tests ensuring sensitive exception text is not exposed. ## Validation - 2,396 unit tests pass under coverage; - 296 focused tests pass after rebasing onto current `main`; - integration discovery passes (22 backend-dependent tests skipped because Firecracker/KVM are unavailable on this host); - changed-line coverage: 97.1% (534/550); - Pyright on tracked source: 0 errors, 0 warnings; - Pylint: 9.84/10; - `compileall` and `git diff --check` pass; - push-side gitleaks scan reports no leaks.

didericis force-pushed refactor/architecture-upkeep-444 from 70e38ce74a to 55ee91f356

2026-07-26 02:19:52 -04:00

Compare

didericis force-pushed refactor/architecture-upkeep-444 from 99040ea0b1 to 571ea4dbf0

2026-07-26 02:42:48 -04:00

Compare

didericis added 6 commits 2026-07-26 02:55:57 -04:00

refactor: validate reconciliation inputs and neutralize CLI helpers 2039ef635f

refactor(egress): separate matching, DLP, and context concerns 90defdc9cd

refactor(egress): make addon core a compatibility facade 1d85acfd99

refactor(backend): extract shared bottle preparation planner e29b79d517

fix(diagnostics): make optional failures observable and safe 22dde95561