mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-11-09 14:04:06 +09:00
ruv
11c1ad974f
Phase 6 of ADR-126 closes the regulator-grade interpretability gap that
LSTM / Transformer trading signals leave by default. Given a `signalId`,
the new `trader-explain` skill builds a feature-contribution graph, runs
single-entry forward-push PageRank from the signal output node, and
persists the top-K ranked features to `trading-analysis` as a
`SignedAttributionArtifact`.
What's new:
- `plugins/ruflo-neural-trader/src/signed-attribution.{ts,mjs}` —
typed contract + runtime mirror for the Ed25519-signed attribution
envelope. Re-uses the Phase 4 signing scheme exactly (canonical body
excludes signature fields; verifier pins to a caller-supplied
`trustedPublicKey`, NOT the served `witnessPublicKey` — CWE-347 /
#1922). Adds `localSingleEntryPageRank` (seeded mulberry32 power-
iteration fallback, ~30 LOC), `singleEntryPageRank` (MCP dispatch with
local fallback, mirrors the SublinearAdapter pattern from Phase 3), and
`topKFeatures` (deterministic tie-breaking by node index).
- `plugins/ruflo-neural-trader/skills/trader-explain/SKILL.md` —
the call site. Retrieves the signal from `trading-signals`, extracts
per-feature contributions via `npx neural-trader --predict --explain
--json` (degrades to a z-score heuristic if the flag isn't shipped
upstream yet — artifact tagged `attribution_method:
"input-zscore-fallback"`), runs the PageRank, signs the result with
`signAttributionArtifact`, persists to `trading-analysis`, and surfaces
a markdown ranking table to the agent.
- `scripts/smoke-neural-trader-feature-attribution.mjs` — three-layer
regression smoke: (1) static contract on TS/MJS + skill, (2) Ed25519
crypto round-trip with tamper detection on feature scores AND on the
graphMetadata.seed (seed is signed-in), (3) reproducibility — same seed
→ byte-identical scores + ordering; different seed → scores differ.
- `.github/workflows/v3-ci.yml` — `neural-trader-feature-attribution-smoke`
job with path triggers on the three load-bearing artifacts.
- `plugins/ruflo-neural-trader/README.md` — new "Feature attribution"
section with schema, example output, regulator-compliance angle
(EU AI Act Article 13 / SEC Reg-AI), and reproducibility guarantee.
- `plugins/ruflo-neural-trader/scripts/smoke.sh` — step 2 now requires
9 skills (was 8), adding `trader-explain` to the contract check.
Acceptance (ADR-126 Phase 6):
- All 36 checks in `scripts/smoke-neural-trader-feature-attribution.mjs`
pass: static contract, crypto round-trip, reproducibility, mass
conservation, signed-seed coverage.
- No regression: portfolio-cg smoke, backtest-signing smoke, pipeline
smoke all still green.
- Plugin smoke: 11 passed, 0 failed.
- `npx neural-trader --help` still clean (no upstream regression).
With Phase 6 landed, all six phases of ADR-126 are now complete:
Phase 1 — Namespace alignment
Phase 2 — TTL + dedup lifecycle (#2069)
Phase 3 — Portfolio CG via sublinear (#2070)
Phase 4 — Ed25519-signed backtest artifacts (#2071)
Phase 5 — SendMessage risk-gate pipeline (#2071)
Phase 6 — Feature attribution via single-entry PageRank (this PR)
Closes #2068
Co-Authored-By: RuFlo <ruv@ruv.net>