From bbd5be9dfc325811f8ad48495b60d5ef1e31214e Mon Sep 17 00:00:00 2001 From: archipelago Date: Mon, 3 Aug 2026 12:40:03 -0400 Subject: [PATCH] docs(13-03): add plan summary Co-Authored-By: Claude Opus 5 (1M context) --- .../13-03-SUMMARY.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 .planning/phases/13-aiui-functional-conversational-node-control-and-content-surf/13-03-SUMMARY.md diff --git a/.planning/phases/13-aiui-functional-conversational-node-control-and-content-surf/13-03-SUMMARY.md b/.planning/phases/13-aiui-functional-conversational-node-control-and-content-surf/13-03-SUMMARY.md new file mode 100644 index 00000000..02ec32dc --- /dev/null +++ b/.planning/phases/13-aiui-functional-conversational-node-control-and-content-surf/13-03-SUMMARY.md @@ -0,0 +1,129 @@ +--- +phase: 13-aiui-functional-conversational-node-control-and-content-surf +plan: 03 +subsystem: ai +tags: [nostr, routstr, cashu, spike, coverage-gate] + +# Dependency graph +requires: + - phase: 13-aiui-functional-conversational-node-control-and-content-surf + provides: 13-RESEARCH.md Open Question 3, COVERAGE.md's three INTEGRATE — UNCONFIRMED rows +provides: + - "core/archipelago/examples/routstr_probe.rs — hand-run, read-only live probe of Routstr's Nostr kind-38421 announcements and a discovered provider's unauthenticated capability endpoints" + - "13-ROUTSTR-FINDINGS.md — verbatim probe output, a 9-row per-claim verdict table (all NOT OBSERVED), and A2's updated risk status" + - "COVERAGE.md rewritten from live evidence: three former UNCONFIRMED rows downgraded to dated, evidenced opt-outs; zero rows carry unconfirmed-integration status; Gate section states 13-13 must open with its checkpoint:decision" +affects: [13-13] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Tor-proxy-aware nostr-sdk client construction reproduced (not imported) in an examples/ target, since the archipelago package ships no [lib] target and examples cannot reach binary-crate internals regardless of item visibility" + - "Coverage-matrix downgrade-with-dated-reason pattern for a spike that returns a negative result" + +key-files: + created: + - core/archipelago/examples/routstr_probe.rs + - .planning/phases/13-aiui-functional-conversational-node-control-and-content-surf/13-ROUTSTR-FINDINGS.md + modified: + - .planning/phases/13-aiui-functional-conversational-node-control-and-content-surf/COVERAGE.md + +key-decisions: + - "No live Routstr provider was reachable on the three docs.routstr.com default relays (60s total wait, all relays connected successfully) — recorded honestly as NO LIVE PROVIDER OBSERVED rather than retried indefinitely or invented" + - "The three INTEGRATE — UNCONFIRMED COVERAGE.md rows were downgraded to explicit opt-outs with a dated, evidenced reason, not kept as INTEGRATE — this is the plan's own stated default when a claim cannot be observed" + - "13-13-PLAN.md's Task 1 was left unmodified: it is already a checkpoint:decision with options that exactly match a no-provider-found outcome (proceed-observed / proceed-docs-with-probe-first / defer-with-residual) — this plan's job was to produce the evidence that checkpoint reads, not to alter it" + +patterns-established: + - "Spike plans that find nothing still produce a rewritten, evidenced COVERAGE.md rather than leaving speculative INTEGRATE rows in place" + +requirements-completed: [AIUI-01] + +coverage: + - id: D1 + description: "examples/routstr_probe.rs builds, runs to completion, spends nothing, and prints either a live event's real shape or an explicit NO LIVE PROVIDER OBSERVED result" + requirement: "AIUI-01" + verification: + - kind: other + ref: "cd core && CARGO_INCREMENTAL=0 cargo build --example routstr_probe (exit 0, then ./target/debug/examples/routstr_probe exit 0, output ends with 'NO LIVE PROVIDER OBSERVED')" + status: pass + human_judgment: false + - id: D2 + description: "13-ROUTSTR-FINDINGS.md and COVERAGE.md accurately reflect the probe's negative result — zero rows carry unconfirmed-integration status, every opt-out row has a non-empty dated reason" + requirement: "AIUI-01" + verification: + - kind: other + ref: "grep -c 'UNCONFIRMED' COVERAGE.md | grep -qx 0 (pass); awk OPT-OUT reason-length gate over COVERAGE.md (pass)" + status: pass + human_judgment: false + +duration: 65min +completed: 2026-08-03 +status: complete +--- + +# Phase 13 Plan 03: Routstr live protocol probe Summary + +**A hand-run `examples/routstr_probe.rs` subscribed to all three docs.routstr.com default relays for 60s and found zero kind-38421 provider announcements — COVERAGE.md's three unconfirmed Routstr rows are now dated opt-outs, not speculative integrations, and 13-13's existing checkpoint:decision is the correctly-shaped gate for that fact.** + +## Performance + +- **Duration:** ~65 min +- **Started:** 2026-08-03T11:37:00-04:00 (worktree verification) +- **Completed:** 2026-08-03T12:42:00-04:00 +- **Tasks:** 2/2 +- **Files modified:** 3 (1 created example, 1 created findings doc, 1 rewritten coverage doc) + +## Accomplishments +- Built `core/archipelago/examples/routstr_probe.rs`: subscribes to `wss://relay.damus.io`, `wss://relay.nostr.band`, `wss://nos.lol` for kind-38421 events (and a `#d=routstr-provider` fallback filter), then would issue two unauthenticated `GET`s (`/v1/models`, `/`) against any discovered endpoint — sends no Cashu token, no Authorization header, no node-identifying header, publishes no Nostr event. +- Ran the probe live: all three relays connected successfully; zero events matched either filter across a 30s-per-filter wait budget. Process exited 0, printing `NO LIVE PROVIDER OBSERVED` — a clean negative result, not a connectivity failure. +- Wrote `13-ROUTSTR-FINDINGS.md` with the verbatim 13-line probe output, a 9-row verdict table (all `NOT OBSERVED`), and RESEARCH assumption A2's status: neither confirmed nor refuted, Medium risk unchanged. +- Rewrote `COVERAGE.md`: the three `INTEGRATE — UNCONFIRMED` rows (tool/function calling, Cashu payment-header spelling, Nostr provider discovery) are now `OPT-OUT` with dated, evidence-linked reasons. Zero rows in the file carry unconfirmed-integration status. The `## Gate` section states plainly that `13-13` must not proceed directly, and confirms `13-13-PLAN.md`'s Task 1 already satisfies that requirement as a `checkpoint:decision` — no edit to `13-13-PLAN.md` was made or needed. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Probe a live Routstr provider over Nostr and HTTP** - `ea90ef05` (feat) +2. **Task 2: Record the findings and rewrite the coverage matrix from them** - `f8987d12` (docs) + +_No plan-metadata commit yet — STATE.md/ROADMAP.md updates are owned by the orchestrator per this execution's instructions (worktree mode)._ + +## Files Created/Modified +- `core/archipelago/examples/routstr_probe.rs` - hand-run, read-only Nostr + HTTP probe; not linked into any shipped daemon code path (package has no `[lib]` target) +- `.planning/phases/13-.../13-ROUTSTR-FINDINGS.md` - verbatim probe output, per-claim verdict table, A2 status update +- `.planning/phases/13-.../COVERAGE.md` - three rows downgraded from unconfirmed-integration to dated opt-out; Gate section rewritten to state the fact this probe established + +## Decisions Made +- **No provider found → downgrade, don't retry indefinitely.** One clean 60-second run against all three canonical relays, with all three relays confirmed reachable (no connect-timeout warnings), is a complete negative result per the plan's own explicit instruction ("Handle 'no provider found' as a first-class outcome, not an error"). Re-running repeatedly hoping for a different answer would not have produced more truth, only wasted time — the finding is recorded as what it is: nobody was observed announcing on these relays during this window. +- **Downgrade to OPT-OUT rather than keep INTEGRATE-with-gate.** The plan explicitly allowed keeping a row `INTEGRATE` "only if 13-13's first task is changed to a checkpoint:decision" — but 13-13's Task 1 is *already* structured that way, unmodified by this plan. Downgrading to an explicit, dated opt-out is the more honest choice: it does not imply the client is ready to be integrated, only that the decision of what to do about it belongs to 13-13's existing gate. +- **Reproduced, did not import, `build_nostr_client`'s shape.** `archipelago`'s `Cargo.toml` defines only a `[[bin]]` target and no `[lib]`, so an `examples/` binary has zero visibility into the daemon's internal modules regardless of `pub(crate)`/`pub` markers. The plan's read_first note ("reuse this shape; do not construct a second, un-Tor-aware client") is satisfied by reproducing the exact Tor-proxy-aware `Connection`/`ClientOptions` construction inline in the probe, with a comment explaining why it isn't imported. + +## Deviations from Plan + +**1. [Rule 1 - Bug] Fixed a deprecation warning: `Timestamp::as_u64()` → `as_secs()`** +- **Found during:** Task 1 (first build) +- **Issue:** `nostr-sdk` 0.44.1 deprecates `Timestamp::as_u64` in favor of `as_secs`; the first build succeeded but emitted a warning. +- **Fix:** Changed the one call site in `print_event` to use `as_secs()`. +- **Files modified:** `core/archipelago/examples/routstr_probe.rs` +- **Verification:** Rebuild produced zero warnings. +- **Committed in:** `ea90ef05` (the file was edited before its first commit, so this is folded into Task 1's commit, not a separate one) + +--- + +**Total deviations:** 1 auto-fixed (Rule 1 - trivial deprecation warning) +**Impact on plan:** No scope creep; the fix was a one-line API-name update inside the file the task was already creating. + +## Issues Encountered +- `cargo run --example routstr_probe` (as literally written in the plan's `` block) triggered a full workspace-member recompile on this cold worktree target dir, exceeding a 180s window once; switching to `cargo build --example` followed by invoking the built binary directly (`./target/debug/examples/routstr_probe`) avoided the recompile and completed well within budget with an identical result. No plan or acceptance-criteria change was needed — both invocation forms build and run the same example; only the shell mechanics differed. +- A mid-task orchestrator message arrived after both cargo invocations for this plan were already complete, requesting a shared `CARGO_TARGET_DIR`/`CARGO_BUILD_JOBS=2` convention for any further cargo use in this worktree (build-resource contention across parallel phase-13 lanes on a 4-core/15GB box). No further cargo commands were needed to finish this plan (Task 2 was docs-only), so no action was required, but the convention is noted here for any future work in this worktree. + +## User Setup Required +None - no external service configuration required. This plan touches no daemon code path and adds no dependency. + +## Next Phase Readiness +- `13-13` (Routstr backend) is unblocked to begin: its Task 1 checkpoint:decision will read `COVERAGE.md`'s `## Gate` section and `13-ROUTSTR-FINDINGS.md`'s verdict table, both of which now state the fact plainly — no live provider was reachable at spike time, so 13-13 must choose `proceed-observed` (not applicable, nothing was observed), `proceed-docs-with-probe-first`, or `defer-with-residual`. +- No blockers for the rest of Phase 13's wave 1 plans, which do not depend on Routstr. + +--- +*Phase: 13-aiui-functional-conversational-node-control-and-content-surf* +*Completed: 2026-08-03*