more stratch pads

.scratch/architecture-deepening/PRD.md

@@ -0,0 +1,26 @@
+# Architecture Deepening
+
+## Goal
+
+Increase depth, locality, and testability in the existing Meshnet runtime without changing its domain behavior or reopening accepted architecture decisions.
+
+## Scope
+
+This feature backlog is derived from the Graphify code graph and the architecture review. It targets three high-coupling modules:
+
+1. Distributed Route Session execution in the node HTTP path.
+2. Node startup orchestration.
+3. Tracker request intake and HTTP dispatch.
+
+## Constraints
+
+- Preserve ADR-0009: the Tracker is the control plane and public proxy; workers own tokenizer and model execution.
+- Preserve the active Distributed GGUF Runtime plan: DGR-040 owns native-worker supervision; DGR-041 owns native capability registration. Do not duplicate or redesign those stories.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing, billing, admission, telemetry, and relay semantics.
+- Each task starts with focused characterization tests, then moves behavior behind one deep module interface.
+
+## Order
+
+1. Route Session execution, because it has the clearest seam and lets distributed execution be tested without HTTP.
+2. Node startup orchestration, using the existing capability-validator adapters.
+3. Tracker intake, only after the first two establish the preferred deep-module style.

.scratch/architecture-deepening/issues/01-deepen-route-session-execution.md

@@ -0,0 +1,36 @@
+# AD-001: Deepen Route Session execution behind one node seam
+
+- **Status:** needs-triage
+- **Priority:** p0
+- **Dependencies:** none
+- **Blocks:** AD-002
+- **Evidence:** Graphify identifies `torch_server.py` as the Activation Transport & Binary Frames hub; `_TorchHandler._do_chat_completions` has cyclomatic complexity 53 and owns request parsing, complete-model generation, distributed prefill/decode, Hot KV State recovery, transport clients, SSE, telemetry, and cleanup.
+
+## Objective
+
+Move distributed Route Session execution behind one deep module interface so the HTTP module only translates a client request into a Route Session result/stream.
+
+## Constraints
+
+- Preserve ADR-0009: the head worker owns tokenization and shard execution.
+- Preserve the existing OpenAI-compatible HTTP/SSE behavior.
+- Keep Hot KV State local to each shard and retain cache-miss re-prefill behavior.
+- Do not introduce native GGUF worker work; DGR-040 and DGR-041 own that scope.
+
+## Acceptance criteria
+
+- [ ] Characterization tests cover prefill, decode, cache-miss re-prefill, cancellation, and cleanup through the new module interface without an HTTP server.
+- [ ] The HTTP module retains only request translation, response translation, and request accounting.
+- [ ] Route Session lifecycle owns downstream direct/relay client cleanup in one place.
+- [ ] Existing two-node, KV-cache, relay, and OpenAI compatibility tests retain behavior.
+- [ ] `pytest` targeted tests and `python -m compileall packages tests` pass.
+
+## Likely files
+
+- Modify: `packages/node/meshnet_node/torch_server.py`
+- Create: module adjacent to `torch_server.py` for Route Session execution
+- Modify/add: `tests/test_two_node_pipeline.py`, `tests/test_kv_cache_distributed.py`, focused new tests
+
+## Non-goals
+
+No change to public route selection, model architecture behavior, native worker protocol, or WAN KV migration.

.scratch/architecture-deepening/issues/02-deepen-node-startup-orchestration.md

@@ -0,0 +1,33 @@
+# AD-002: Deepen Node startup orchestration
+
+- **Status:** needs-triage
+- **Priority:** p1
+- **Dependencies:** AD-001
+- **Evidence:** `run_startup()` in `packages/node/meshnet_node/startup.py` has cyclomatic complexity 101, a broad caller-facing parameter surface, and coordinates hardware, wallet, assignment, artifacts, server construction, capability proof, and Tracker registration.
+
+## Objective
+
+Create a deep Node startup module with explicit immutable startup intent and one execution seam, so callers and tests do not need to understand the full startup sequence.
+
+## Constraints
+
+- Retain the existing explicit capability-validator adapter used by tests.
+- Preserve current CLI behavior, registration data, startup ordering, and Transformers behavior.
+- Keep native-worker supervision out of scope: DGR-040 owns it. The result may expose a phase where DGR-040 can later attach, but must not implement that worker supervision.
+
+## Acceptance criteria
+
+- [ ] Characterization tests pin successful startup, capability refusal before registration, assignment behavior, and failure classification.
+- [ ] The public startup interface accepts a cohesive intent/plan rather than leaking orchestration details across callers.
+- [ ] Hardware/assignment, artifact/server, and proof/registration behavior are internally ordered and individually testable through internal seams.
+- [ ] Existing `tests/test_node_startup.py`, `tests/test_node_admission.py`, and mining CLI tests retain behavior.
+- [ ] `pytest` targeted tests and `python -m compileall packages tests` pass.
+
+## Likely files
+
+- Modify: `packages/node/meshnet_node/startup.py`, `packages/node/meshnet_node/testing.py`, `packages/node/meshnet_node/cli.py`
+- Modify/add: `tests/test_node_startup.py`, `tests/test_node_admission.py`, `tests/test_mining_cli.py`
+
+## Non-goals
+
+No new backend type, no Tracker placement algorithm change, and no native-worker process supervision.

.scratch/architecture-deepening/issues/03-deepen-tracker-request-intake.md

@@ -0,0 +1,35 @@
+# AD-003: Deepen Tracker request intake without changing control-plane semantics
+
+- **Status:** needs-triage
+- **Priority:** p1
+- **Dependencies:** AD-001, AD-002
+- **Evidence:** Graphify marks `_TrackerHandler` as the highest-degree node (93 edges). `do_POST` dispatches auth, accounts, billing, registry, raft, gossip, placement, calibration, model, and inference paths; `do_GET` mixes operational projections and public request paths. Major handlers include proxy chat (CC 127), registration (CC 82), models (CC 43), and network assignment (CC 42).
+
+## Objective
+
+Deepen Tracker request intake around existing domain seams so HTTP dispatch stays thin and request-specific policy no longer leaks across unrelated control-plane workflows.
+
+## Constraints
+
+- Preserve ADR-0009: Tracker remains a control plane and public inference proxy, never a model host.
+- Preserve coverage-first assignment, billing, admission, relay, telemetry, Raft, and existing endpoint contracts.
+- Do not create a speculative adapter: each new seam must have at least two real callers/adapters or remain internal.
+
+## Acceptance criteria
+
+- [ ] Characterization tests pin all affected public endpoint response and error behavior before moving code.
+- [ ] HTTP dispatch delegates to cohesive intake modules for inference, node/registry lifecycle, and operator projections.
+- [ ] Route selection, billing attribution, admission, and coverage logic remain backend-agnostic and do not move into the HTTP module.
+- [ ] `_TrackerHandler` no longer owns unrelated endpoint policy directly.
+- [ ] Existing routing, capability-admission, billing, account, and consensus tests retain behavior.
+- [ ] `pytest` targeted tests and `python -m compileall packages tests` pass.
+
+## Likely files
+
+- Modify: `packages/tracker/meshnet_tracker/server.py`
+- Potentially modify: `packages/tracker/meshnet_tracker/billing.py`, `accounts.py`, `capability.py`, `recipe.py`
+- Modify/add: focused tests alongside `tests/test_tracker_routing.py`, `tests/test_tracker_capability_admission.py`, `tests/test_billing_ledger.py`, and `tests/test_tracker_consensus.py`
+
+## Non-goals
+
+No redesign of the Tracker architecture, no public endpoint removal, and no change to backend-neutral provider semantics.

.scratch/architecture-deepening/prd.json

@@ -0,0 +1,10 @@
+{
+  "name": "Architecture Deepening",
+  "description": "Deepen high-coupling Meshnet modules behind narrow interfaces while preserving current domain behavior and locked ADR decisions.",
+  "sourceOfTruth": "This prd.json and its issue files are planning artifacts; no task is approved for implementation until triaged.",
+  "stories": [
+    {"id":"AD-001","title":"Deepen Route Session execution behind one node seam","status":"needs-triage","priority":"p0","dependsOn":[],"blocks":["AD-002"],"files":["packages/node/meshnet_node/torch_server.py","tests/test_two_node_pipeline.py","tests/test_kv_cache_distributed.py"]},
+    {"id":"AD-002","title":"Deepen Node startup orchestration","status":"needs-triage","priority":"p1","dependsOn":["AD-001"],"blocks":[],"files":["packages/node/meshnet_node/startup.py","packages/node/meshnet_node/testing.py","tests/test_node_startup.py","tests/test_node_admission.py"]},
+    {"id":"AD-003","title":"Deepen Tracker request intake without changing control-plane semantics","status":"needs-triage","priority":"p1","dependsOn":["AD-001","AD-002"],"blocks":[],"files":["packages/tracker/meshnet_tracker/server.py","tests/test_tracker_routing.py"]}
+  ]
+}