docs(integrators): add m008 / m009 / m010 guides#97
Open
brawlaphant wants to merge 3 commits into
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 several protocol mechanisms, including Credit Class Approval Voting (m001-enh), Data Attestation Bonding (m008), Service Provision Escrow (m009), Reputation Signal (m010), Fixed Cap Dynamic Supply (m012), and Authority Validator Governance (m014). Each guide follows a standardized structure covering mechanism functionality, input/output schemas, common error modes, and runnable examples. Review feedback identified a discrepancy in the default reputation value for m008 and noted a missing constant definition in the m014 specification that needs to be reconciled.
| 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.
The default value for attester_reputation when no history is available is stated as 500 here, but the detailed section (line 83) and the canonical specification (mechanisms/m008-attestation-bonding/SPEC.md §5.2) both specify a cautious default of 300. This discrepancy should be corrected. Additionally, ensure the transition logic for this multiplier is explicitly defined (e.g., using max() or phase-gating) to prevent implementation ambiguity.
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) |
References
- When specifying transition logic between different mechanisms (e.g., multipliers), explicitly define the function (e.g., max()) and the state-based conditions (phase-gating) that govern the transition to prevent implementation ambiguity.
|
|
||
| ### 4e. PoA eligibility threshold is configurable | ||
|
|
||
| The default 0.80 eligibility threshold is documented in the SPEC as `POA_ELIGIBILITY_SCORE`. Integrators pulling from governance proposals should read the on-chain parameter rather than hardcoding 0.80 — it can change through a parameter-change proposal. |
Contributor
There was a problem hiding this comment.
The guide references a constant POA_ELIGIBILITY_SCORE and claims it is documented in the SPEC. However, this constant is not present in the provided mechanisms/m014-authority-validator-governance/SPEC.md. Please ensure the SPEC is updated to include this definition and that it aligns with the project's central data standards repository (regen-data-standards).
References
- When defining data structures or type definitions, ensure they are aligned with the project's central data standards repository (regen-data-standards) to maintain coherence.
brawlaphant
added a commit
to brawlaphant/agentic-tokenomics
that referenced
this pull request
Apr 11, 2026
…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
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
…om m014 Addresses Gemini review feedback on PR regen-network#97: the guide referenced a POA_ELIGIBILITY_SCORE constant with a default of 0.80, but no such constant is defined in mechanisms/m014-authority-validator-governance/SPEC.md. The only thresholds in the SPEC (§5.3) are performance_score < 0.70 and uptime < 0.995. Replace the fabricated claim with an accurate pointer to SPEC §5.3 and the regen-data-standards repo for future canonical constants. 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>
glandua
pushed a commit
that referenced
this pull request
Apr 25, 2026
…uides (#94) * docs(integrators): add how-to guide template + 3 exemplar mechanism guides Introduces `docs/integrators/` — integrator-facing how-to guides that complement the existing SPEC.md / reference-impl / README triad with thin outward-facing walkthroughs. ## Why a new doc layer SPEC.md is exhaustive and prescriptive. The reference impl is correct but has no prose. MECHANISM_CONSUMERS.md is a directory not a how-to. A developer starting from zero needed to read all three to wire a new consumer, and in practice they only skimmed the first one and got stuck on the second. The integrator guide answers a different question: "given I am starting from zero, how do I wire my system to read from or call into this mechanism today, and what do I have to worry about?" ## Template (README.md) Every guide follows a fixed five-section structure so a reader can skip to the part they need without reading the whole thing: 1. What this mechanism does (one paragraph) 2. What you give it (inputs with one realistic example) 3. What you get back (outputs with every field documented) 4. Common error modes (actual failure modes, not generic advice) 5. Runnable example (exact command, expected output) Scope boundary is explicit: internal state machine derivations live in the SPEC, governance rationales in docs/governance/, agent workflow implementations in agent-00X-*/src/, contract implementation details in contracts/<id>/src/. The integrator guide is the thin outward-facing layer. The README includes an index with TODO markers for the 6 mechanisms not covered by this PR so a contributor can pick up the template and fill one in without searching for the pattern. ## Three exemplar guides covering three mechanism flavors ### m001-enh: scoring with 3-way recommendation Walks through: - 4-factor weighted composite formula - Recommendation rules including strict-inequality boundaries (the 700/300 pair that the test vectors from PR #82 pin) - Missing-data error modes (no M010 history, unresolvable IRI, too few classes for similarity math) - Clamp behavior on out-of-range input - Exact boundary behavior at score = 700 and score = 300 - The self-test auto-discovery command ### m012: supply dynamics with BigInt arithmetic Walks through: - The core S/M/B equation and the regrowth rate decomposition - Why every amount is a string (BigInt safety — 221M REGEN in uregen exceeds JS safe-integer range) - The phase-gated effective multiplier table across INACTIVE / TRANSITION / ACTIVE / EQUILIBRIUM, explaining why TRANSITION picks max() to protect validators during the DPoS-to-PoA handover - Ecological multiplier collapse, zero-supply guard, burn underflow, cap inviolability — each with a reference to the edge-case vector that pins the behavior (from PR #86) - r_base validation throwing RangeError outside [0, 0.10] - Note that m012 is wired into scripts/verify.mjs so a break fails the whole CI verify job ### m014: validator performance with re-normalization Walks through: - The three factors and weights - Why missing factors re-normalize rather than depressing the score toward zero (critical subtlety integrators miss) - The confidence-by-count table - The three performance flags and the `availableCount > 0` guard that distinguishes "no data" from "poor performance" - Why uptime = null does NOT fire below_uptime_minimum - Why uptime = 0.995 exactly does NOT fire (strict inequality, pinned by the edge-case vector from PR #88) - Explicit-0 vs null semantics for data sources that return "0.0" ambiguously - Note that the default 0.80 PoA eligibility threshold is a configurable governance parameter, not a hardcoded constant ## Scope Docs-only PR. Four files, 430 lines total: docs/integrators/README.md (template + index) docs/integrators/m001-enh.md (scoring exemplar) docs/integrators/m012.md (supply dynamics exemplar) docs/integrators/m014.md (validator scoring exemplar) No mechanism code is changed. No schemas are touched. No CI configuration. Future PRs can follow the three exemplars to write guides for m008 / m009 / m010 / m011 / m013 / m015. - Lands in: `docs/integrators/` - Changes: new integrator how-to guide folder with template + 3 exemplar guides - Validate: docs-only Refs `mechanisms/m001-enh-credit-class-approval/SPEC.md` §5 Refs `mechanisms/m012-fixed-cap-dynamic-supply/SPEC.md` §5.3, §5.4 Refs `mechanisms/m014-authority-validator-governance/SPEC.md` §5 Refs `docs/MECHANISM_CONSUMERS.md` (complementary, not superseded) * docs(integrators): fix m014 example math + m001 schema link + table field names Addresses Gemini review on PR #94: * m014 §3 example: with weights 0.4/0.3/0.3 and inputs 0.9999/1.0/0.985 the weighted sum is 0.99546, which rounds to 0.9955 (not 0.9961). * m014 §performance flags: use the public JSON field names (`performance_score`, `confidence`) instead of the internal terms `composite` / `availableCount`, so the table matches §3's output shape. * m001-enh §schemas: use bare filenames in both schema link texts to match the style used in m012 and m014 (was inconsistent — first link had the full path). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(integrators): remove invented POA_ELIGIBILITY_SCORE reference from m014 Addresses Gemini review feedback on PR #97: the guide referenced a POA_ELIGIBILITY_SCORE constant with a default of 0.80, but no such constant is defined in mechanisms/m014-authority-validator-governance/SPEC.md. The only thresholds in the SPEC (§5.3) are performance_score < 0.70 and uptime < 0.995. Replace the fabricated claim with an accurate pointer to SPEC §5.3 and the regen-data-standards repo for future canonical constants. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: brawlaphant <brawlaphant@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Hey @brawlaphant — this PR conflicts with main after #94 merged (which introduced the how-to template + first 3 exemplar guides). Could you rebase onto the new main? The new template at |
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
…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>
…eters table The integrator guide at docs/integrators/m014.md:105 referenced `POA_ELIGIBILITY_SCORE` as "documented in the SPEC," but the SPEC previously only defined the review threshold (0.70) and the uptime minimum (99.5%). This closes the gap: add the eligibility constant to §5.3 and list it in §10's governance-parameter table so integrators can trust the reference. Values: - `POA_ELIGIBILITY_SCORE = 0.80` — minimum composite score for Authority-set eligibility, configurable via governance. - Kept the existing 0.70 review-threshold wording; the two thresholds serve different lifecycle stages (eligibility-to-join vs flag-for-review-while-active). Addresses Gemini review on docs/integrator-guides-m008-m009-m010. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
brawlaphant
force-pushed
the
docs/integrator-guides-m008-m009-m010
branch
from
668302a to
55cf5c6
Compare
brawlaphant
added a commit
to brawlaphant/agentic-tokenomics
that referenced
this pull request
Apr 25, 2026
…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
brawlaphant
added a commit
to brawlaphant/agentic-tokenomics
that referenced
this pull request
Apr 25, 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>
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
Follows the template landed in #94 to add three more integrator guides, completing the "scoring + reputation" cluster. README index updated. Based on PR #94's branch — if #94 merges first this PR rebases cleanly.
Three guides, three different flavors within the scoring family
Pinned-to-test-vector references
Every error mode in the 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.
README index update
The README index moves m008, m009, m010 from the TODO section to the "Written" section. Three TODOs remain: m011, m013, m015. Those land in a follow-up PR.
Relationship to PR #94
This PR is based on PR #94's branch (not upstream/main directly). If #94 merges first, this PR rebases cleanly against the rebased index. If this PR is reviewed first, it implicitly reviews #94's template along with it — the two are complementary and review together better than separately.
Scope
Docs-only. Three new files (374 lines combined) and a 9-line README diff. No mechanism code, no schemas, no CI configuration.
Refs `mechanisms/m008-attestation-bonding/SPEC.md` §5
Refs `mechanisms/m009-service-escrow/SPEC.md` §5
Refs `mechanisms/m010-reputation-signal/SPEC.md` §5