docs(integrators): add m011 / m013 / m015 guides — complete the 9-mechanism set#98
Open
brawlaphant wants to merge 3 commits intoregen-network:mainfrom
Open
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive set of integrator-facing how-to guides for nine protocol mechanisms, ranging from credit class approval to contribution-weighted rewards. Each guide follows a standardized five-section template designed to help downstream consumers understand and implement the mechanisms. Review feedback highlights several mathematical inconsistencies where example output scores do not align with the provided input factors and weights across the m008, m009, m011, m014, and m015 guides. Additionally, a contradiction was identified in the m008 guide regarding the default reputation value.
| Four weighted factors drive the composite: | ||
|
|
||
| - `bond_adequacy` × 0.30 — bond amount relative to the minimum for this attestation type | ||
| - `attester_reputation` × 0.30 — attester's M010 reputation (default 500 when no history) |
Contributor
There was a problem hiding this comment.
There is a contradiction regarding the default reputation value. Line 14 states the default is 500, but line 83 (and the example on line 34) states it is 300. Based on the detailed explanation in section 4a, it appears 300 is the intended value for this mechanism.
Suggested change
| - `attester_reputation` × 0.30 — attester's M010 reputation (default 500 when no history) | |
| attester_reputation × 0.30 — attester's M010 reputation (default 300 when no history) |
|
|
||
| ```js | ||
| { | ||
| score: 811, // 0..1000 composite, clamped |
Contributor
There was a problem hiding this comment.
The score in this example does not match the weighted sum of the inputs provided on lines 35-38. Using the weights from Section 1 (0.30, 0.30, 0.25, 0.15) and the inputs (750, 680, 1000, 600), the calculated score is 769 (225 + 204 + 250 + 90), not 811.
|
|
||
| ```js | ||
| { | ||
| score: 801, // 0..1000 composite, clamped |
Contributor
There was a problem hiding this comment.
The score in this example does not match the weighted sum of the inputs provided on lines 35-38. Using the weights from Section 1 (0.40, 0.25, 0.20, 0.15) and the inputs (850, 800, 750, 700), the calculated score is 795 (340 + 200 + 150 + 105), not 801.
|
|
||
| ```js | ||
| { | ||
| score: 839, // 0..1000 composite, clamped |
Contributor
There was a problem hiding this comment.
The score in this example does not match the weighted sum of the inputs provided on lines 38-44. Using the weights from Section 1 and the provided inputs, the calculated score is 855.5, not 839. Please verify the example values against the reference implementation.
| ```js | ||
| { | ||
| address: "regenvaloper1chorus", | ||
| performance_score: 0.9961, // 0..1, rounded to 4 decimals |
Contributor
There was a problem hiding this comment.
The performance_score in this example does not match the weighted sum of the inputs provided on lines 28-30. Using the weights from Section 1 (0.4, 0.3, 0.3) and the inputs (0.9999, 1.0, 0.985), the calculated score is 0.9955 (0.39996 + 0.3 + 0.2955), not 0.9961.
|
|
||
| ```js | ||
| { | ||
| total_score: 247_500, // weighted sum in uregen-equivalent |
Contributor
There was a problem hiding this comment.
The total_score in this example does not match the sum of the weighted_value fields in the breakdown below (lines 88-113). The sum of the values provided is 245,000.45, not 247,500.
brawlaphant
added a commit
to brawlaphant/agentic-tokenomics
that referenced
this pull request
Apr 11, 2026
…ores Addresses Gemini review feedback on PR regen-network#97 / regen-network#98: * m008 line 14 claimed the attester_reputation default is 500; the reference impl and SPEC §5.2 both use 300. Align the doc with SPEC §5.2 and flag the cautious-default rationale inline. * m008 §3 example score 811 did not match the weighted sum of the inputs. Correct to 769 (225 + 204 + 250 + 90 with weights 0.30/0.30/0.25/0.15). * m009 §3 example score 801 did not match either. Correct to 795 (340 + 200 + 150 + 105 with weights 0.40/0.25/0.20/0.15). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
brawlaphant
added a commit
to brawlaphant/agentic-tokenomics
that referenced
this pull request
Apr 11, 2026
…m015 Addresses Gemini review feedback on PR regen-network#98 — every example score in the §3 "What you get back" snippets was wrong relative to the inputs + weights printed right above it. * m008: 811 → 769 (225 + 204 + 250 + 90 with 0.30/0.30/0.25/0.15). * m008 line 14: attester_reputation default 500 → 300 (SPEC §5.2 cautious default). * m009: 801 → 795 (340 + 200 + 150 + 105 with 0.40/0.25/0.20/0.15). * m011: 839 → 856 (Math.round(855.5) = 856; true weighted sum with 0.25/0.20/0.15/0.15/0.10/0.10/0.05). * m014: 0.9961 → 0.9955 (0.39996 + 0.30 + 0.2955). * m015: 247_500 → 245_000.45 (150_000 + 75_000 + 20_000 + 0.30 + 0.15). These fixes are applied both to PR regen-network#94/regen-network#97 (where the files were introduced) and here so PR regen-network#98 stays consistent on its own branch and the eventual rebase is a clean no-op. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Hey @brawlaphant — same situation as #97: this PR conflicts with main after #94 merged. Rebasing onto the new main should resolve it (the template path and any shared index file are the likely conflicts). Once #97 lands, please rebase #98 on top of that as well. |
brawlaphant
added a commit
to brawlaphant/agentic-tokenomics
that referenced
this pull request
Apr 25, 2026
…ores Addresses Gemini review feedback on PR regen-network#97 / regen-network#98: * m008 line 14 claimed the attester_reputation default is 500; the reference impl and SPEC §5.2 both use 300. Align the doc with SPEC §5.2 and flag the cautious-default rationale inline. * m008 §3 example score 811 did not match the weighted sum of the inputs. Correct to 769 (225 + 204 + 250 + 90 with weights 0.30/0.30/0.25/0.15). * m009 §3 example score 801 did not match either. Correct to 795 (340 + 200 + 150 + 105 with weights 0.40/0.25/0.20/0.15). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Follows the template landed in PR regen-network#94 (base of this branch) to add three more integrator guides, completing the "scoring + reputation" cluster. README index updated. ## m008 — Data Attestation Bonding Pure scoring mechanism (no recommendation). Four weighted factors: bond_adequacy × 0.30, attester_reputation × 0.30, evidence_completeness × 0.25, type_risk × 0.15. Unlike m001-enh and m009, m008 does NOT auto-classify — it returns a score and lets the integrator decide the threshold. Covers the "bond-heavy attack" vector: a well-funded attacker who pours REGEN into a bonded attestation with no real evidence still cannot clear the 700 threshold because bond alone contributes only 0.30×1000 + 0.15×1000 = 450 to the composite. Pinned by the `vector_v0_bond_heavy_evidence_zero` vector from PR regen-network#83. Also documents the subtle asymmetry in the confidence flags — `iri_resolvable` and `type_recognized` default to "available" when unset (guard is `!== false`), while `reputation_available` and `has_prior_attestations` default to "unavailable" (truthy check). This trips integrators porting from other mechanisms. ## m009 — Service Provision Escrow Dual-guard recommendation model (distinct from m001-enh's single guard). APPROVE requires BOTH `score >= 700` AND `confidence >= 750` — a conjunction, so a perfect 1000 score with low confidence does NOT auto-approve. FLAG_FOR_CLIENT fires when EITHER `score < 400` OR `confidence < 250` — a disjunction, so a high-score/zero- confidence submission DOES fire the flag, protecting the client from auto-approving unverifiable evidence. Four weighted factors: deliverable_quality × 0.40, evidence_completeness × 0.25, milestone_consistency × 0.20, provider_reputation × 0.15. Provider reputation defaults to 300 (not 500) because the SPEC treats first-time providers as higher risk in escrow agreements. Unlike m008, every m009 confidence flag uses strict `=== true` (unset counts as FALSE). Guide explicitly warns about this asymmetry for integrators re-using code between m008 and m009. ## m010 — Reputation Signal The odd one out in the cluster — event-driven rather than factor-driven. The integrator passes a list of endorsement signals (level 1..5 per signal) plus an `as_of` timestamp, and m010 returns a decay-weighted average in [0, 1]. No factors to tune, no defaults to remember. Documents the v0 → v1 migration path: today the score is unweighted decay-weighted average, the v1 target is stake-weighted `score × 1000`. The interface already accepts a `useStakeWeighting` flag and a per-event `stake` field for forward compatibility; v0 ignores both. Also documents the contributing-status filter — only `active` and `resolved_valid` signals contribute. Everything else (`withdrawn`, `challenged`, `escalated`, `resolved_invalid`, `invalidated`) is excluded entirely, not decayed-to-zero. The integrator can distinguish "no signal" from "score 0.0" by checking the event count upstream. Notes that m010 has dedicated verification scripts (`scripts/verify-m010-reference-impl.mjs` and `scripts/verify-m010-datasets.mjs`) that run as part of the repo-level `scripts/verify.mjs` — so breakage fails CI. ## README index update Moves m008, m009, m010 rows from the TODO section to the "Written" section. The three remaining TODOs are m011, m013, and m015 — those come in a follow-up PR. ## Scope Docs-only PR. Three new files, one index update: docs/integrators/m008.md (132 lines) docs/integrators/m009.md (120 lines) docs/integrators/m010.md (122 lines) docs/integrators/README.md (+6, -3) No mechanism code is changed. No schemas are touched. No CI configuration. ## Relationship to PR regen-network#94 This PR is based on PR regen-network#94's branch (not upstream/main directly). If PR regen-network#94 merges first, this PR rebases cleanly. If this PR is reviewed first, it implicitly reviews regen-network#94's template along with it — the two are complementary and review together better than separately. - Lands in: `docs/integrators/` - Changes: 3 new guides (m008, m009, m010) + index update - Validate: docs-only Refs `mechanisms/m008-attestation-bonding/SPEC.md` §5 Refs `mechanisms/m009-service-escrow/SPEC.md` §5 Refs `mechanisms/m010-reputation-signal/SPEC.md` §5
…hanism set Third and final PR in the integrator-guide series (after regen-network#94 and regen-network#97). Adds guides for m011 marketplace curation, m013 fee routing, and m015 contribution-weighted rewards. The README index is simplified: every mechanism is now written, so the "TODO" column goes away entirely and the status column is no longer needed. ## m011 — Marketplace Curation 7-factor composite (the most in the framework). Dominant weights are project_reputation (0.25) + class_reputation (0.20) = 0.45, so reputation drives nearly half the score. The smallest weight is additionality_confidence (0.05) — a factor cap that stops the methodology layer from single-handedly moving the composite. Documents the `vintage_known` asymmetric default (uses `!== false` semantics like two of m008's flags, while the other six m011 flags are strict truthy checks). Integrators porting confidence-flag code between mechanisms must re-audit every flag — the asymmetry is real and unavoidable. Also documents the clamp behavior that m011 shares with every other scoring mechanism: out-of-range inputs are clamped to [0, 1000] before weighting, pinned by the overflow_clamp vector from PR regen-network#85. ## m013 — Value-Based Fee Routing Two shapes in one mechanism: compute fee + distribute fee. The distribution enforces the **Fee Conservation invariant**: burn + validator + community + agent = fee_amount. This is achieved by flooring burn/community/agent independently and computing validator as the arithmetic remainder — any rounding dust is absorbed into the validator pool. A refactor that floors the validator share instead would leak dust, which is why vector_v0_rounding_remainder_validator_absorbs (PR regen-network#87) pins it. Documents the strict-inequality min-fee boundary (rawFee < minFee, not <=), the zero-value-still-pays-min behavior, and the custom distribution shares override (Economic Reboot Proposal A values 15/30/50/5 via fee_config.distribution_shares). Warns that unknown tx_type throws an exception rather than falling back to a default — callers must validate upstream. Also warns that the reference impl does NOT validate that distribution_shares sums to 1.0 — the pure JS impl trusts the input, so integrators that pass un-validated shares will get arithmetic drift. Real governance parameters are enforced on-chain, but the JS reference impl is permissive. ## m015 — Contribution-Weighted Rewards Two separate functions inside one mechanism: 1. computeActivityScore — per-participant weighted activity (credit_purchase 0.30, credit_retirement 0.30, facilitation 0.20, governance_voting 0.10, proposal_submission 0.10) 2. computeStabilityAllocation — per-period split of the community pool inflow between the stability tier and the activity pool, with a 30% cap on the stability share Documents the proposal anti-gaming credit rules: - passed + quorum -> 1.0 credit - failed + quorum -> 0.5 credit - no quorum reached -> 0.0 credit So a participant cannot game the proposal submission dimension by spamming low-quality proposals that never reach quorum. Pinned by the vector set in mechanisms/m015/reference-impl/. Also documents the 30% cap clamp behavior — when commitment obligations exceed the cap, the allocation is clamped and the stability tier gets less than its contractual return for that period. The activity pool retains the remainder. This is an intentional protection against the stability tier draining the activity pool during a low-inflow period. Warns about the unit mismatch across activity dimensions: credit_purchase / retirement / facilitation are in uregen, but governance_votes_cast is a count and proposal_submission is a unit-less credit. The total_score is a dimensionless ranking number — not a uregen amount — and downstream distribution logic divides by total_activity_score to compute shares. ## README index cleanup Removes the "Status" column (every entry was "✅ Written" or "⏳ TODO", and all 9 are now written). The table is now a clean three-column index: Guide / Mechanism / Mechanism type. Adds a note that future additions should follow the same five-section template. ## Scope Docs-only. Three new files (413 lines combined) and a 13-line README diff (mostly moving rows out of the TODO tier). No mechanism code is changed. No schemas are touched. No CI configuration. ## PR series context This completes the integrator-guide series: PR regen-network#94 — template + m001-enh, m012, m014 (exemplars) PR regen-network#97 — m008, m009, m010 PR #??? (this one) — m011, m013, m015 All nine mechanisms are now covered. Based on regen-network#97's branch so the README index updates compose cleanly with the prior two PRs. - Lands in: `docs/integrators/` - Changes: 3 new guides (m011, m013, m015) + README index finalization - Validate: docs-only Refs `mechanisms/m011-marketplace-curation/SPEC.md` §5 Refs `mechanisms/m013-value-based-fee-routing/SPEC.md` §5 Refs `mechanisms/m015-contribution-weighted-rewards/SPEC.md` §5
…m015 Addresses Gemini review feedback on PR regen-network#98 — every example score in the §3 "What you get back" snippets was wrong relative to the inputs + weights printed right above it. * m008: 811 → 769 (225 + 204 + 250 + 90 with 0.30/0.30/0.25/0.15). * m008 line 14: attester_reputation default 500 → 300 (SPEC §5.2 cautious default). * m009: 801 → 795 (340 + 200 + 150 + 105 with 0.40/0.25/0.20/0.15). * m011: 839 → 856 (Math.round(855.5) = 856; true weighted sum with 0.25/0.20/0.15/0.15/0.10/0.10/0.05). * m014: 0.9961 → 0.9955 (0.39996 + 0.30 + 0.2955). * m015: 247_500 → 245_000.45 (150_000 + 75_000 + 20_000 + 0.30 + 0.15). These fixes are applied both to PR regen-network#94/regen-network#97 (where the files were introduced) and here so PR regen-network#98 stays consistent on its own branch and the eventual rebase is a clean no-op. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
brawlaphant
force-pushed
the
docs/integrator-guides-m011-m013-m015
branch
from
273811a to
a19d1ed
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Third and final PR in the integrator-guide series (after #94 and #97). Adds guides for the last three mechanisms — m011 marketplace curation, m013 fee routing, m015 contribution-weighted rewards. Based on #97's branch so the README index composes cleanly.
The last three guides
README index cleanup
Removes the "Status" column — every row is now "Written" so the column carries no signal. The table is now a clean three-column index: Guide / Mechanism / Mechanism type. Adds a note that future additions (new mechanisms, upgraded versions) should follow the same five-section template.
PR series recap
This completes the integrator-guide series:
All nine mechanism guides are now in the repo. A future contributor adding a new mechanism has a clear template to follow and a set of five completed examples per mechanism flavor (scoring, dual-guard scoring, event-driven, supply dynamics, fee routing, validator performance, contribution rewards).
Pinned-to-test-vector references
Every error mode in the new guides links to the specific test vector that pins the behavior:
So if a refactor changes the behavior, both the vector AND the guide break in the same PR rather than drifting silently.
Scope
Docs-only. Three new files (413 lines combined) and a 13-line README diff. No mechanism code, no schemas, no CI configuration.
Relationship to #97 and #94
Based on #97's branch (which was based on #94's branch). If #94 and #97 merge first, this PR rebases cleanly against the completed index. If this PR is reviewed first, it implicitly reviews the full series.
Refs `mechanisms/m011-marketplace-curation/SPEC.md` §5
Refs `mechanisms/m013-value-based-fee-routing/SPEC.md` §5
Refs `mechanisms/m015-contribution-weighted-rewards/SPEC.md` §5