From 0e2d530ed63af1bfe4c1d39700af9c2c9437cf11 Mon Sep 17 00:00:00 2001 From: Dobromir Popov Date: Wed, 29 Jul 2026 15:37:40 +0200 Subject: [PATCH] more stratch pads --- .scratch/architecture-deepening/PRD.md | 26 ++++++++++++++ .../01-deepen-route-session-execution.md | 36 +++++++++++++++++++ .../02-deepen-node-startup-orchestration.md | 33 +++++++++++++++++ .../03-deepen-tracker-request-intake.md | 35 ++++++++++++++++++ .scratch/architecture-deepening/prd.json | 10 ++++++ graphify-out/cache/last_query_stamp | 2 +- 6 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 .scratch/architecture-deepening/PRD.md create mode 100644 .scratch/architecture-deepening/issues/01-deepen-route-session-execution.md create mode 100644 .scratch/architecture-deepening/issues/02-deepen-node-startup-orchestration.md create mode 100644 .scratch/architecture-deepening/issues/03-deepen-tracker-request-intake.md create mode 100644 .scratch/architecture-deepening/prd.json diff --git a/.scratch/architecture-deepening/PRD.md b/.scratch/architecture-deepening/PRD.md new file mode 100644 index 0000000..eac3561 --- /dev/null +++ b/.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. diff --git a/.scratch/architecture-deepening/issues/01-deepen-route-session-execution.md b/.scratch/architecture-deepening/issues/01-deepen-route-session-execution.md new file mode 100644 index 0000000..eafff25 --- /dev/null +++ b/.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. diff --git a/.scratch/architecture-deepening/issues/02-deepen-node-startup-orchestration.md b/.scratch/architecture-deepening/issues/02-deepen-node-startup-orchestration.md new file mode 100644 index 0000000..47a3123 --- /dev/null +++ b/.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. diff --git a/.scratch/architecture-deepening/issues/03-deepen-tracker-request-intake.md b/.scratch/architecture-deepening/issues/03-deepen-tracker-request-intake.md new file mode 100644 index 0000000..dec66ba --- /dev/null +++ b/.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. diff --git a/.scratch/architecture-deepening/prd.json b/.scratch/architecture-deepening/prd.json new file mode 100644 index 0000000..6e24acb --- /dev/null +++ b/.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"]} + ] +} diff --git a/graphify-out/cache/last_query_stamp b/graphify-out/cache/last_query_stamp index e8fc0e7..b3390ef 100644 --- a/graphify-out/cache/last_query_stamp +++ b/graphify-out/cache/last_query_stamp @@ -1 +1 @@ -1785331673.1795876 \ No newline at end of file +1785331773.2279537 \ No newline at end of file