Adopt architecture principles: track the protocol, not the product #46

New issue

Open

opened 2026-10-15 18:38:07 +01:00 by vnprc-agent · 0 comments

vnprc-agent commented

2026-10-15 18:38:07 +01:00

Collaborator

Create docs/ARCHITECTURE_PRINCIPLES.md — the fork's standing policy on upstream tracking, dependency direction, and code shape — so structural decisions are made by rule instead of omission.

Primary goals:

Name the upstream strategy — track the protocol, not the product: protocols/v2 (binary_sv2, codec_sv2, noise/framing, channels, roles-logic) tracks named SRI tags and takes cherry-picked correctness/security fixes; the roles diverge freely and are never rebased wholesale.
One dependency rule — dependencies point down only: roles → shared utils → protocol crates. Protocol crates never import role or business logic.
One path per concern — every mechanism has exactly one wired implementation; unwired alternatives are deleted, not kept warm. Abstractions are built when the second real instance exists, not before.
Make it load-bearing — link the principles from AGENTS.md so every session starts from them; an unlinked principles doc is a dead letter.

Current state and specifics

There is no principles doc. docs/AGENTS.md describes the components but asserts no rules. docs/PLUGIN_ARCHITECTURE_PROPOSAL.md is a 400-line aspiration whose runtime-plugin machinery (discovery, hot-reload, versioning) is premature for a solo pre-alpha fork; its one artifact — the share-hooks trait and QuoteDispatchHook — was never wired into the pool (the vec is only ever Vec::new()), carries a latent prev_hash-instead-of-share-hash bug, and is the exact half-migration the principles should forbid. The upstream relationship is currently decided by omission: no sri remote, frozen snapshot, ~30 commits of custom work on top, last protocol-layer touch two commits after import. Background: the security review (notes/hashpool/security-review-2026-10-15.md) and the strategy discussion that produced "track the protocol, not the product".

Draft principles for the doc:

Dependencies point down. roles → shared → protocols. The protocol crates stay dumb: messages, validation, math.
Track the protocol, not the product. Add sri as a remote pinned to the base tag. Re-sync is triggered by upstream releases touching protocols/, not by calendar; take security/correctness/interop fixes in the protocol crates, cherry-pick only; role-level code never merges wholesale.
Hashpool lives in hashpool crates. Mint, ehash, quote path, and roles-utils are where fork code belongs; the smaller the diff surface in roles/pool et al., the cheaper every future decision (rebase, rewrite, or freeze) stays.
One path per concern. A mechanism has one wired implementation. Unused paths and speculative scaffolding are deleted on sight; the plugin seam gets built when a second real hook exists, with the trait redesigned by what that hook needs.
No speculative layers. No loaders, discovery, or runtime enablement until a concrete second plugin demands them; a config flag and an if are the whole feature toggle until then.
Load-bearing invariants are architecture. The doc lists the invariants the security review identified (mint recomputes quote amounts per vnprc/hashpool#44, listener liveness per vnprc/hashpool#45, single quote-dispatch path) with pointers, so refactors check against them.

Scope

In scope: the principles doc; AGENTS.md link plus a one-paragraph pointer replacing any duplicated guidance; a short superseded-banner on PLUGIN_ARCHITECTURE_PROPOSAL.md pointing at the principles. First concrete application, as its own PR immediately after: delete roles/pool/src/lib/mining_pool/quote_dispatch_hook.rs, the unused share_hooks field on Pool, and the roles-utils/share-hooks crate (nothing else imports it); revisit roles/pool/src/lib/mining_pool/quote_dispatch_hook.rs history via git when a real second hook appears. Out of scope: any plugin implementation, upstream re-sync execution, and the fixes tracked in vnprc/hashpool#44 and vnprc/hashpool#45.

Create `docs/ARCHITECTURE_PRINCIPLES.md` — the fork's standing policy on upstream tracking, dependency direction, and code shape — so structural decisions are made by rule instead of omission. Primary goals: - **Name the upstream strategy** — track the protocol, not the product: `protocols/v2` (binary_sv2, codec_sv2, noise/framing, channels, roles-logic) tracks named SRI tags and takes cherry-picked correctness/security fixes; the roles diverge freely and are never rebased wholesale. - **One dependency rule** — dependencies point down only: roles → shared utils → protocol crates. Protocol crates never import role or business logic. - **One path per concern** — every mechanism has exactly one wired implementation; unwired alternatives are deleted, not kept warm. Abstractions are built when the second real instance exists, not before. - **Make it load-bearing** — link the principles from `AGENTS.md` so every session starts from them; an unlinked principles doc is a dead letter. ### Current state and specifics There is no principles doc. `docs/AGENTS.md` describes the components but asserts no rules. `docs/PLUGIN_ARCHITECTURE_PROPOSAL.md` is a 400-line aspiration whose runtime-plugin machinery (discovery, hot-reload, versioning) is premature for a solo pre-alpha fork; its one artifact — the `share-hooks` trait and `QuoteDispatchHook` — was never wired into the pool (the vec is only ever `Vec::new()`), carries a latent prev_hash-instead-of-share-hash bug, and is the exact half-migration the principles should forbid. The upstream relationship is currently decided by omission: no `sri` remote, frozen snapshot, ~30 commits of custom work on top, last protocol-layer touch two commits after import. Background: the security review (`notes/hashpool/security-review-2026-10-15.md`) and the strategy discussion that produced "track the protocol, not the product". Draft principles for the doc: 1. **Dependencies point down.** roles → shared → protocols. The protocol crates stay dumb: messages, validation, math. 2. **Track the protocol, not the product.** Add `sri` as a remote pinned to the base tag. Re-sync is triggered by upstream releases touching `protocols/`, not by calendar; take security/correctness/interop fixes in the protocol crates, cherry-pick only; role-level code never merges wholesale. 3. **Hashpool lives in hashpool crates.** Mint, ehash, quote path, and roles-utils are where fork code belongs; the smaller the diff surface in `roles/pool` et al., the cheaper every future decision (rebase, rewrite, or freeze) stays. 4. **One path per concern.** A mechanism has one wired implementation. Unused paths and speculative scaffolding are deleted on sight; the plugin seam gets built when a second real hook exists, with the trait redesigned by what that hook needs. 5. **No speculative layers.** No loaders, discovery, or runtime enablement until a concrete second plugin demands them; a config flag and an `if` are the whole feature toggle until then. 6. **Load-bearing invariants are architecture.** The doc lists the invariants the security review identified (mint recomputes quote amounts per vnprc/hashpool#44, listener liveness per vnprc/hashpool#45, single quote-dispatch path) with pointers, so refactors check against them. ### Scope In scope: the principles doc; `AGENTS.md` link plus a one-paragraph pointer replacing any duplicated guidance; a short superseded-banner on `PLUGIN_ARCHITECTURE_PROPOSAL.md` pointing at the principles. First concrete application, as its own PR immediately after: delete `roles/pool/src/lib/mining_pool/quote_dispatch_hook.rs`, the unused `share_hooks` field on `Pool`, and the `roles-utils/share-hooks` crate (nothing else imports it); revisit `roles/pool/src/lib/mining_pool/quote_dispatch_hook.rs` history via git when a real second hook appears. Out of scope: any plugin implementation, upstream re-sync execution, and the fixes tracked in vnprc/hashpool#44 and vnprc/hashpool#45.

vnprc-agent referenced this issue

2026-10-15 18:58:49 +01:00

Remove unwired quote-dispatch hook scaffolding #47

vnprc-agent referenced this issue from a commit

2026-10-19 00:02:00 +01:00

memory: drop departed skills from the private index, add hashpool in-flight pointer