commit 0fcc40ffb626736f8eb20d1498caee53d1a8ce4f
parent 56ff9bcaabc2c2865d7e91d23c4c83b5c84d5eaf
Author: triesap <tyson@radroots.org>
Date: Mon, 10 Aug 2026 18:23:08 +0000
architecture: record transport and tooling decisions
- document the pinned direct rust-nostr profile adapter and ownership boundary
- define tested criteria for adopting a reusable transport again
- retain Detekt alpha.5 as a dated build-tooling-only exception
- link the accepted public decisions from the repository overview
Diffstat:
3 files changed, 112 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -47,6 +47,10 @@ The durable product contract is under:
spec/harvestcircle_mvp_v1/
```
+Accepted architecture and tooling decisions are under `docs/decisions/`,
+including the [direct rust-nostr transport decision](docs/decisions/ADR-0011-direct-rust-nostr-transport.md)
+and the [Detekt compatibility exception](docs/decisions/ADR-0012-detekt-tooling-exception.md).
+
## Security
Do not submit secret keys, nsec values, signer secrets, or decrypted private
diff --git a/docs/decisions/ADR-0011-direct-rust-nostr-transport.md b/docs/decisions/ADR-0011-direct-rust-nostr-transport.md
@@ -0,0 +1,60 @@
+# ADR-0011: Use direct rust-nostr profile transport
+
+- Status: Accepted
+- Date: 2026-08-10
+
+## Context
+
+HarvestCircle previously reached Nostr through both the shared Radroots
+transport crates and the rust-nostr SDK. Commit
+`1f8e5728f4815961d7dac0545c2b03464991b592` removed the redundant shared
+transport dependency chain and its duplicate registry-sourced rust-nostr
+graph. No specific vulnerability identifier is claimed by this decision.
+
+The profile adapter now depends directly on `nostr`, `nostr-sdk`, and the
+test-only `nostr-relay-builder`, all pinned to rust-nostr revision
+`5bba5163eb77107f82c4a8262cf29d7f33a73219`.
+
+## Decision
+
+HarvestCircle owns its current profile-fetch transport policy locally in
+`radroots_harvestcircle_nostr`. The adapter uses the pinned rust-nostr SDK
+directly and preserves these application-visible behaviors:
+
+- only relay endpoints with read capability are queried;
+- each readable endpoint receives a bounded kind-0 profile filter;
+- the overall operation has a deadline;
+- returned events are checked for signature, author, kind, and valid profile
+ metadata;
+- the newest valid event is selected deterministically; and
+- partial and complete outcomes remain distinct, including per-relay failure
+ evidence.
+
+Local mock-relay tests exercise these semantics without making external relay
+availability part of the test contract.
+
+This is a profile-transport decision only. Domain relay classification and
+capability policy remain owned by `radroots_harvestcircle_domain`, and
+application orchestration remains owned by
+`radroots_harvestcircle_application`.
+
+## Consequences
+
+The direct dependency reduces duplicate transport and dependency surfaces,
+but HarvestCircle must maintain the adapter, its retry/deadline behavior, and
+its tests. Future collective-market transport is not required to use this
+profile adapter; it must be selected against the collective protocol and
+privacy requirements when those contracts are implemented.
+
+## Re-adoption criteria
+
+A reusable transport abstraction may replace this adapter only when it:
+
+1. uses one revision-pinned and policy-compliant rust-nostr graph;
+2. preserves the typed endpoint capability and destination boundary;
+3. preserves bounded querying, validation, deterministic selection, and
+ partial-success evidence;
+4. does not introduce private or product-external dependencies into this
+ public capsule; and
+5. passes the capsule's source, dependency, Rust, binding, and integration
+ verification lanes.
diff --git a/docs/decisions/ADR-0012-detekt-tooling-exception.md b/docs/decisions/ADR-0012-detekt-tooling-exception.md
@@ -0,0 +1,48 @@
+# ADR-0012: Retain the Detekt alpha compatibility exception
+
+- Status: Accepted with expiry
+- Date: 2026-08-10
+- Owner: HarvestCircle maintainers
+- Review date: 2026-11-10
+
+## Context
+
+The build pins Kotlin `2.4.10`, Gradle `9.5.0`, and Detekt
+`2.0.0-alpha.5`. Detekt's official compatibility table reports alpha.5 with
+Gradle `9.5.1` and Kotlin `2.4.0`, while stable Detekt `1.23.8` is reported
+with Gradle `8.12.1` and Kotlin `2.0.21`.
+
+Sources:
+
+- <https://detekt.dev/docs/introduction/compatibility/>
+- <https://detekt.dev/changelog-2.0.0/>
+
+Moving to the stable Detekt line would therefore require unrelated Kotlin and
+Gradle downgrades rather than a tooling-only replacement.
+
+## Decision
+
+Retain Detekt `2.0.0-alpha.5` as a narrowly scoped build-tooling exception.
+It is used for static analysis only and is not linked into the HarvestCircle
+runtime or packaged application.
+
+The reviewed risks are alpha API and rule behavior changes, possible plugin
+incompatibility, and non-final defaults. They are contained by exact version
+pinning, checked-in configuration, deterministic Gradle verification, and the
+repository's lint and full-check lanes.
+
+## Expiry and upgrade trigger
+
+Re-evaluate this exception no later than 2026-11-10, or earlier when a stable
+Detekt release officially supports Kotlin 2.4.x and Gradle 9.x. Replace the
+alpha when that stable release:
+
+1. runs with the pinned Kotlin and Gradle toolchain without unrelated
+ downgrades;
+2. preserves or intentionally migrates the checked-in rule configuration;
+3. passes `make lint`, `make check`, and both governed and standalone
+ verification lanes; and
+4. produces no new runtime or packaging dependency.
+
+If no compatible stable release exists at review time, maintainers must
+record a new dated review rather than silently extending this exception.
