docs(P00): research — v0.7 fraternal groups + persona assessment
RESEARCH stage for v0.7. Delegated to ci-researcher subagent for 7-area domain + codebase research. Key findings: - x/cover module layout mirrors x/hub (D-039 precedent, D-084) — types/ keeper/module.go/expected_keepers.go/msg_server.go/simtest - Cover-Fee category tagging in x/cover (CoverFeeTag struct), NOT x/bread (no Grain struct today; avoids GrainsPerBread locked-const risk) - Standing gate via expected-keeper shim (G-003; StandingKeeper interface) - MAB as x/bond extension (anonymous embed, GrowthBond precedent); CouponDenom enum with CouponDenomBread rejected at ValidateBasic (MissionLockAmendmentRejected pattern) - D-080 tagged streaming + Watcher-witnessed release; auto-Still on misuse - Anti-Capture Bill = 13 RightID consts + 13 Waivable* bool consts (all false) + RightIsWaivable always false (dual firewall) - Anti-Crowding-Out firewall = x/cover/firewall + lexicon_meta_cover meta-test (defense in depth; D-079) - Guild extension: ParentGuildID + IsChapter + SecessionTermsHash + GoodStandingLiens (no GuildKind enum; schema-additive) - Shadow vouch 50% = ShadowVouchWeightMultiplier const + IsShadow field + post-multiplier branch (const makes it locked-const firewall visible) - Cover Claims Voucher in x/cover/types (NOT x/standing); slash via x/standing.Slash cross-Pool D-085 escalation candidate (13th Anti-Capture right): spec enumerates 12 of 13 rights. Best candidate (confidence 0.55): NonParticipationNoDenial (REQ-085/FR-NORM-4). NOT auto-decided; lead-developer surfaces to PO before P5. Persona assessment: backend-engineer + lead-developer + security-engineer + cosmos-engineer active (highest security density since v0.5). frontend-engineer + docs-writer + mesh-engineer + data-engineer deactivated. ci-security-auditor off until P6. ARCHITECTURE.md extended with v0.7 component index + cross-component dependencies + 11 new locked-const additions (pending GRILL ratification). RESEARCH.md extended with v0.7 section (10 design recommendations + pitfalls). PERSONAS.md rewritten for v0.7. ---ci--- project: oy phase: 0 milestone: v0.7 status: research ---/ci---
This commit is contained in:
@@ -6,9 +6,9 @@
|
||||
"project": "oy",
|
||||
"phase": 0,
|
||||
"phase_role": "pre_execution",
|
||||
"stage": "clarify",
|
||||
"stage": "research",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-19T00:01:00Z",
|
||||
"updated_at": "2026-08-19T00:02:00Z",
|
||||
"next_milestone": null,
|
||||
"previous_milestone": {
|
||||
"milestone": "v0.6",
|
||||
|
||||
@@ -512,4 +512,100 @@ skeleton-only in v0.3):
|
||||
Standing by reach-id at runtime (the v0.3 by-ID-string field becomes a
|
||||
query).
|
||||
- **Forge/Fold** — unchanged in v0.5 (no forge/fold runtime promotion this
|
||||
milestone).
|
||||
milestone).
|
||||
|
||||
---
|
||||
|
||||
## v0.7 Architecture (Fraternal Groups Foundation)
|
||||
|
||||
This section appends the v0.7 component map. v0.7 introduces a NEW module
|
||||
`x/cover` (D-084, D-039 precedent) and extends 4 existing modules. No
|
||||
breaking schema changes to locked-const firewall; G-003 production firewall
|
||||
intact; G-006 go.mod unchanged (`x/cover` uses existing cosmos-sdk substrate).
|
||||
|
||||
### v0.7 Component Index (new + extended modules)
|
||||
|
||||
| # | Component | Vision § | v0.7 Module | New/Ext | Phase | v0.7 Runtime Depth |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 8 | Cover Pool Factory (Pact #4 Cover graduated) | §16 | `x/cover` | New | P1-P5 | CoverPool + CoverCharter + CoverCall + CoverFeeTag structs + Factory keeper + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights (13 rights) + Cover Claims Voucher role + Pool governance hybrid + category staging; simtest-grade runtime (D-020) |
|
||||
| 8 | Mutual Aid Bond (Pact #5 Bonds extended) | §17 | `x/bond` | Extended | P4 | MAB struct (anonymous embed of Bond) + CouponDenom enum (CoverCall/MutualAidCredit/Bread-rejected) + 3× annual surplus ceiling + tagged streaming use-of-proceeds (D-080); simtest |
|
||||
| 10 | Chapter Federation (Orgs extended) | §12 | `x/guild` | Extended | P3 | ParentGuildID + IsChapter + SecessionTermsHash + GoodStandingLiens fields on Guild + SecessionTerms struct + cooling consts (21d/14d) + Household simplified + Confederation Voice; simtest |
|
||||
| 6 | Shadow vouch weight + Cover Claims Voucher slash | §9.1, §9.4 | `x/standing` | Extended | P4 | ShadowVouchWeightMultiplier=0.5 const + IsShadow field on Vouch + SlashReasonFraudulentCoverCall const; simtest |
|
||||
| 10 | Stand→Pier boundary + Household/Confederation keeper logic | §11, §13 | `x/stand` | Extended | P3, P5 | StandPierEscalationAnnualPassVolumeCents const + Household one-tap exit + Confederation Voice aggregation (switch on existing StandType, no struct change); simtest |
|
||||
| 8 | Pact Cover cross-reference (no change) | §16 | `x/pact` | Unchanged | — | PactCover enum value stays as cross-reference (D-084, mirrors PactHubAPI ↔ x/hub); ExecuteCover() stub stays |
|
||||
|
||||
> The Cover Pool Factory is Pact #4 (Cover) per REQ-020/D-027. v0.2 stubbed
|
||||
> it as a PactType enum value inside `x/pact`; v0.7 promotes it to its own
|
||||
> `x/cover` module for the Factory + Charter + Bill of Rights + Voucher
|
||||
> runtime (D-084). The `x/pact` PactCover enum value stays as a
|
||||
> cross-reference; `x/cover` owns the runtime surface. This mirrors the
|
||||
> D-039 precedent (`x/hub` split from `x/pact`'s PactHubAPI in v0.3).
|
||||
|
||||
### v0.7 Cross-Component Dependencies (within v0.7)
|
||||
|
||||
Per the G-003 invariant (by-ID-string inter-module references; no struct
|
||||
imports across `x/<module>/types`), v0.7 components reference each other and
|
||||
the v0.2-v0.6 baseline by ID string only. The dependency edges that affect
|
||||
v0.7 phase ordering:
|
||||
|
||||
```
|
||||
x/cover ──(StandingKeeper shim)──► x/standing (P1: gate query; G-003 expected_keepers.go)
|
||||
x/cover ──(WatcherKeeper shim)──► x/watcher (P1: attestation pipeline; P4: MAB release witness)
|
||||
x/cover ──(BondKeeper shim)──► x/bond (P4: MAB issuance ceiling query)
|
||||
x/bond ──(Stand by id)──► x/stand (v0.2 baseline; MAB issuer-stand-id, unchanged)
|
||||
x/guild ──(Stand by id)──► x/stand (v0.2 baseline; Guild StandAffiliationID, unchanged)
|
||||
x/guild ──(Cover Pool by id)──► x/cover (P3: Chapter Federation liens reference Cover Pool covenants)
|
||||
x/cover ──(Still by id)──► x/still (P1: auto-pause on below-floor; P4: auto-Still on MAB misuse)
|
||||
x/cover ──(PactCover by id)──► x/pact (cross-reference only; no struct import)
|
||||
```
|
||||
|
||||
**Phase-ordering implication (informs D-082):** `x/cover` P1 lands the
|
||||
Factory + firewall + locked floors + gates + tagging first (firewall-first
|
||||
pattern). P2 extends `x/cover` with Charter + governance + staging. P3
|
||||
extends `x/guild` (Chapter Federation depends on Cover Pool existing for
|
||||
lien/covenant references). P4 extends `x/bond` (MAB depends on Cover Pool
|
||||
reserve existing for use-of-proceeds) + `x/standing` (Shadow vouch + Voucher
|
||||
slash). P5 lands the Anti-Capture Bill (cross-cutting; constrains all prior
|
||||
surfaces) + secession cooling + Pier boundary. Confidence 0.82.
|
||||
|
||||
### v0.7 Interface Contracts (6 cross-component — extended this milestone)
|
||||
|
||||
The six cross-component interfaces are EXTENDED in v0.7:
|
||||
|
||||
- **Standing API** — `x/cover` Factory queries Standing via expected-keeper
|
||||
shim (StandingKeeper.GetStandingBucket) for the Cover Pool Standing gate
|
||||
(REQ-049, D-077). By-ID-string at type level (G-003).
|
||||
- **Watcher Attestation Interface** — `x/cover` Factory + MAB release invoke
|
||||
Watcher attestation via WatcherKeeper shim. Cover-Charter signed by Pool
|
||||
Host + witnessed by Watcher (REQ-052). MAB proceeds release requires
|
||||
Watcher quorum (D-080).
|
||||
- **Window Lifecycle Interface** — unchanged in v0.7 (Cover-Charter
|
||||
amendments cooling uses the existing Window Duration semantics; secession
|
||||
cooling is a separate const-based mechanism, not a Window).
|
||||
- **Fee Covenant Interface** — unchanged in v0.7 (Cover-Fees are a separate
|
||||
tagging surface, not a Fee-Covenant route; the Anti-Crowding-Out firewall
|
||||
enforces the separation).
|
||||
- **Voice/Council Interface** — `x/cover` Pool governance hybrid (REQ-062)
|
||||
= Pool Host + 3 elected Masons + Watcher observer. No Anchor seat (§5
|
||||
Anchor no-Voice). MAB holders have NO Voice (REQ-063). Confederation Voice
|
||||
(REQ-058) aggregates one-per-Stand.
|
||||
- **Forge/Fold** — unchanged in v0.7.
|
||||
|
||||
### v0.7 Locked-Const Firewall Additions (pending GRILL ratification)
|
||||
|
||||
Per oy-state §3, v0.7 adds 10 new locked consts (all net-new, no amendments
|
||||
to existing consts):
|
||||
|
||||
| Const | Value | Module | REQ |
|
||||
|-------|-------|--------|-----|
|
||||
| CoverReserveFloorAnnualContribX | 1.5 | x/cover | REQ-047 (locked) |
|
||||
| CoverReserveCeilingAnnualContribX | 2.5 | x/cover | REQ-048 (not locked) |
|
||||
| CoverStandingGateTrusted | 4.0 | x/cover | REQ-049 (locked) |
|
||||
| CoverStandingGatePreferred | 4.5 | x/cover | REQ-049 (locked) |
|
||||
| MABIssuanceCeilingAnnualSurplusMultiple | 3 | x/bond | REQ-054 (locked) |
|
||||
| CoolingSecessionCoverActiveDays | 21 | x/guild | REQ-064 (locked) |
|
||||
| CoolingSecessionNonCoverDays | 14 | x/guild | REQ-064 (locked) |
|
||||
| StandPierEscalationAnnualPassVolumeCents | 10000000 | x/stand | REQ-059 (not locked) |
|
||||
| CoverClaimsVoucherBondMultipleAvgCall | 10 | x/cover | REQ-055 (not locked) |
|
||||
| AntiCaptureBillOfRightsCount | 13 | x/cover | REQ-056 (locked) |
|
||||
| ShadowVouchWeightMultiplier | 0.5 | x/standing | REQ-060 (locked) |
|
||||
+54
-110
@@ -3,131 +3,75 @@ active_personas:
|
||||
- id: backend-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Owns the v0.5 runtime promotion across P1..P7 — every keeper MsgServer message handler + simtest end-to-end flow for x/exit, x/bridge, x/bearers, x/partner, x/hub, x/services, x/bond, and x/council. This is the bulk of the milestone: the v0.3 skeletons were types + in-memory keeper stubs (verified — e.g. `x/partner/types/types.go:101 type Keeper struct{...}` with `NewKeeper()` returning `&Keeper{partners: make(map[string]Partner)}`, zero cosmos-sdk imports in `x/`). v0.5 adds `keeper/keeper.go` (store-backed), `keeper/msg_server.go` (one handler per `Msg*`), `types/msg_*.go` (`sdk.Msg` impls), `module.go` (RegisterServices), and a simtest exercising each handler against an in-memory `sdk.Context`. backend-engineer is the single persona that spans all seven runtime phases (P1..P7) plus the lexicon/locked-const regression guards that carry forward from v0.4. The reactivated cosmos-engineer/security-engineer/mesh-engineer personas advise on conventions and invariants but the implementation is backend-engineer's territory.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x (D-055 GRILL-approved), ibc-go v8.x, Go testing, simtest, lexicon firewall, locked-const invariant tests]
|
||||
territory: ["x/exit/**", "x/bridge/**", "x/bearers/**", "x/partner/**", "x/hub/**", "x/services/**", "x/bond/**", "x/council/**", "lexicon/**", "lexicon_meta_test.go", "lexicon_meta_docs/**"]
|
||||
constraints: ["G-003 production firewall intact — keeper-to-keeper cross-module calls use expected_keepers.go interface shims (ibc-go convention), NOT struct imports of x/<module>/types; by-ID-string rule preserved at the type level", "G-006 controlled exception (D-055) — go.mod gains cosmos-sdk v0.50.x + ibc-go v8.x (GRILL-ratified); types/ packages gain sdk.Msg imports for Msg* types but invariant/lexicon tests stay stdlib-only and green", "locked-const invariants unchanged — 8%/0% bond cap (D-028), 6 bearers, 4 Partner tiers, MissionLockAmendable=false, SignalKindCount=4 (P1-2 defensible), BearerTypeCount=6, BridgeStatusCount=4, ExitStatusCount=5, etc. — v0.5 ADDS ProposalKind/ProposalStatus/VoteOption enums (AUDIT §193 P1-1) but does NOT change existing locked consts", "lexicon firewall stays green on both x/ and docs/ after runtime promotion — Msg* struct names are the new lexicon surface (e.g. AVOID 'deposit' in x/hub custody message names; use MsgCustodyReceiveAsset/MsgCustodyReleaseAsset per A-542)", "simtest NOT mainnet (D-054) — handlers exercised against in-memory sdk.Context + dbm in-memory store; no real IBC light clients, no real MPC, no real bearer hardware, no real DEX venues, no real Watcher attestations (all stubbed)", "≥80% coverage on runtime packages (D-033 carries forward) — every keeper/msg_server.go + simtest must hit the bar; table-driven handler tests per Msg*", "Mission Lock const firewall intact (G-003) — MissionLockAmendment-Rejected ProposalKind is rejected at ValidateBasic (A-572); the const + the ValidateBasic gate are the dual firewall"]
|
||||
reason: "Owns the v0.7 runtime across all execution phases — the bulk of the milestone. v0.7 introduces a NEW module `x/cover` (Cover Pool Factory + Anti-Crowding-Out firewall + Anti-Capture Bill of Rights, per D-084) following the D-039 precedent (`x/hub` split from `x/pact` in v0.3). backend-engineer builds the `x/cover` types/ + keeper/ + module.go + expected_keepers.go + msg_server.go + simtest, mirroring the x/hub layout. Also owns EXTENSIONS: `x/bond` (MAB as anonymous-embed extension, mirroring GrowthBond), `x/guild` (ParentGuildID + IsChapter + SecessionTermsHash + GoodStandingLiens), `x/standing` (ShadowVouchWeightMultiplier const + IsShadow field + SlashReasonFraudulentCoverCall const), `x/stand` (Household/Confederation keeper logic — switch on existing StandType, no struct change), `x/pact` (PactCover stays as cross-reference, no change)."
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x (D-055), ibc-go v8.x, Go testing, simtest, lexicon firewall, locked-const invariant tests]
|
||||
territory: ["x/cover/**", "x/bond/**", "x/guild/**", "x/standing/**", "x/stand/**", "x/pact/**", "lexicon/**", "lexicon_meta_test.go", "lexicon_meta_docs/**", "lexicon_meta_web/**"]
|
||||
constraints:
|
||||
- "G-003 production firewall intact — x/cover references x/standing (StandingKeeper shim), x/watcher (WatcherKeeper shim), x/bond (BondKeeper shim) via expected_keepers.go interfaces; by-ID-string rule at type level; x/pact.PactCover stays as cross-reference (D-084, mirrors x/pact.PactHubAPI ↔ x/hub)"
|
||||
- "G-006 controlled exception (D-055) — go.mod unchanged in v0.7 (x/cover uses existing cosmos-sdk substrate); target G-028 diff baseline EMPTY"
|
||||
- "locked-const invariants — v0.7 ADDS consts (CoverReserveFloorAnnualContribX=1.5, CoverStandingGateTrusted=4.0, CoverStandingGatePreferred=4.5, MABIssuanceCeilingAnnualSurplusMultiple=3, CoolingSecessionCoverActiveDays=21, CoolingSecessionNonCoverDays=14, CoverClaimsVoucherBondMultipleAvgCall=10, AntiCaptureBillOfRightsCount=13, ShadowVouchWeightMultiplier=0.5, StandPierEscalationAnnualPassVolumeCents=10000000) but does NOT change existing locked consts"
|
||||
- "lexicon firewall stays green — Msg* names avoid banned terms (no 'deposit', no 'account', no 'insurance' — use 'Cover', 'Cover-Fee', 'Cover Call', 'Cover-Charter')"
|
||||
- "simtest NOT mainnet (D-054 continues) — x/cover keeper handlers exercised against in-memory sdk.Context"
|
||||
- "≥80% coverage on x/cover + extensions (D-033 carries forward)"
|
||||
- "Anti-Crowding-Out firewall (D-079) — x/cover/firewall subpackage rejects Cover-Fee routing outside contributor-pool semantics"
|
||||
- "MAB use-of-proceeds (D-080) — tagged streaming + Watcher-witnessed release; auto-Still on misuse"
|
||||
|
||||
- id: lead-developer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Coordinates v0.5 phase decomposition (P1 exit+bridge → P2 bearers → P3 anchors → P4 hub → P5 services → P6 bond → P7 council → P8 final review/audit/ship per D-056), territory enforcement (warn mode per config.json), and the final-phase feature purity gate audit (no breaking schema changes; locked-const firewall intact; G-003 production firewall intact). Owns the v0.5 ROADMAP.md / REQUIREMENTS.md status updates at milestone completion and the milestone ship. Also owns the GRILL-ratification follow-through for the cosmos-sdk version pin (A-504) and the planner-escalation items (A-562 reject-vs-clamp, A-572 reject-at-ValidateBasic, A-574 Watcher Veto quorum value) — these are escalated through the normal decision flow, not auto-decided.
|
||||
reason: "Coordinates v0.7 phase decomposition (P1..P6), territory enforcement (warn mode), and the final-phase feature purity gate audit. Owns the D-085 escalation (13th right identification — confidence 0.55; surfaced through normal decision flow before P5). Owns the §7 acceptance 'pen-test ≥1 independent third party' — at full autonomy, runs self-administered adversarial review (ci-griller) and logs as assumption unless PO rules otherwise."
|
||||
frameworks: [cross-cutting, Gitea Actions, Markdown, YAML, git]
|
||||
territory: [".ciagent/**", ".gitea/workflows/**", ".ciagent/oy/ARCHITECTURE.md", ".ciagent/oy/ROADMAP.md", ".ciagent/oy/REQUIREMENTS.md"]
|
||||
constraints: ["D-056 phase ordering (P1 exit → P2 bearers → P3 anchors → P4 hub → P5 services → P6 bond → P7 council → P8 final); each phase independently shippable (vertical slices)", "milestone versioning (v0.5 feature / tag_base v0.4.x); final-phase patch IS the milestone release (D-008)", "feature purity gate: zero breaking schema changes; zero locked-const amendments (Mission Lock non-amendable; SignalKind 4-not-5 unchanged); G-003 production firewall intact; G-006 controlled exception GRILL-ratified", "persona territory warn-mode enforcement (config.json)", "planner-escalation items (A-504 cosmos-sdk version pin, A-562 bond match reject-vs-clamp, A-572 MissionLockAmendment ValidateBasic rejection, A-574 Watcher Veto quorum) surfaced through the normal decision flow, not auto-decided"]
|
||||
constraints:
|
||||
- "D-082 phase ordering — P1 Cover Factory (foundation+firewall) → P2 Charter/governance/staging → P3 Federation/Household/Confederation → P4 MAB/Voucher/Shadow → P5 Bill of Rights/secession/Pier → P6 final; each phase independently shippable"
|
||||
- "milestone versioning (v0.7 feature / tag_base v0.6.x); final-phase patch IS the milestone release (D-008)"
|
||||
- "feature purity gate: zero breaking schema changes; zero locked-const amendments to EXISTING consts; G-003 intact; G-006/G-028 go.mod diff EMPTY"
|
||||
- "D-085 escalation (13th right) — low-confidence (0.55); surface to PO via normal decision flow before P5"
|
||||
- "§7 pen-test acceptance — self-administered adversarial review if no external third party; log as assumption"
|
||||
|
||||
- id: security-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: REACTIVATED for v0.5. Owns the security-critical invariant surfaces introduced by runtime promotion: (1) the CustodyKeyring interface boundary in x/hub (D-058) — the Sign/Derive/Status contract + the in-memory memKeyring test impl, with key-rotation semantics (Status reports active key version; no caching across blocks); (2) the CLOB mission-lock clamp in x/bond (D-057) — the per-match coupon clamp to [0, 800] bps via the v0.3 Clamp helper, with a match above 800 REJECTED (fails closed, A-562; planner confirms reject-vs-clamp before P6); (3) IBC packet replay protection in x/bridge — the delete-on-ack / refund-on-timeout contract mirroring ibc-go (the CVE-class pitfall); simtest must cover both replay and timeout-refund; (4) the governance Mission-Lock const firewall in x/council (G-003) — MissionLockAmendable=false unchanged, the MissionLockAmendment-Rejected ProposalKind rejected at ValidateBasic (A-572), and the Watcher Veto quorum semantics (single Veto does NOT block; quorum-based, default 6 per REQ-004 6-of-9; A-574). The v0.3/v0.4 locked-const regression tests (TestMissionLockAmendableFalse, TestSignalKindShapeIntentional, the REQ-030 cross-const test) stay green.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x, ibc-go v8.x, Go testing, simtest, locked-const invariant tests, lexicon firewall]
|
||||
territory: ["x/hub/types/keyring.go", "x/hub/keeper/keyring_mem*.go", "x/bond/types/types.go", "x/bond/keeper/**", "x/bridge/keeper/**", "x/council/types/types.go", "x/council/keeper/**", "lexicon/**"]
|
||||
constraints: ["CustodyKeyring interface supports key rotation (Status reports active key version; handler consults keyring per operation, no cross-block caching)", "CLOB per-match coupon clamp to [0, 800] bps (D-028/D-057); match above 800 REJECTED (fails closed, A-562) — planner confirms reject-vs-clamp before P6", "IBC ack/timeout replay protection mirrors ibc-go (delete-on-ack, refund-on-timeout); simtest MUST cover both replay and timeout-refund cases (CVE-class pitfall)", "Mission Lock const firewall intact (G-003): MissionLockAmendable=false unchanged; MissionLockAmendment-Rejected ProposalKind rejected at ValidateBasic (A-572); Watcher Veto quorum-based (default 6, REQ-004 6-of-9), single Veto does NOT block (anti-greed, vision §19)", "locked-const regression tests stay green: TestMissionLockAmendableFalse, TestSignalKindShapeIntentional, the REQ-030 cross-const test (hub.LendingCouponCapBps==bond.CouponCapBps)", "compliance-before-custody ordering enforced in x/hub (withdrawal checks compliance status before the custody debit, A-544)", "lexicon firewall stays green — Msg* names avoid banned terms (e.g. 'deposit' banned; use MsgCustodyReceiveAsset/MsgCustodyReleaseAsset)"]
|
||||
reason: "REACTIVATED for v0.7 (carried from v0.5). v0.7 has the HIGHEST security-critical density since v0.5: (1) Anti-Capture Bill of Rights v0.2 (REQ-056) — 13 non-amendable, non-waivable rights as const firewall + ValidateBasic gate (mirroring MissionLockAmendable=false + MissionLockAmendmentRejected); (2) Anti-Crowding-Out firewall (D-079) — x/cover/firewall + lexicon_meta_cover meta-test; (3) Cover Claims Voucher slashing (REQ-055) — bond 10× avg Call size, no self-adjudication (FR-CPCV-2), slash via x/standing.Slash cross-Pool; (4) MAB use-of-proceeds lock (D-080) — tagged streaming + Watcher-witnessed release + auto-Still; (5) secession cooling + lien bounding (REQ-064/REQ-081); (6) Cover Pool reserve floor 1.5× (REQ-047) below-floor auto-pause."
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x, Go testing, simtest, locked-const invariant tests, lexicon firewall]
|
||||
territory: ["x/cover/types/rights.go", "x/cover/firewall/**", "x/cover/keeper/**", "x/bond/keeper/**", "x/bond/types/types.go", "x/guild/types/types.go", "x/standing/types/types.go", "x/council/types/types.go", "lexicon/**"]
|
||||
constraints:
|
||||
- "Bill of Rights = 13 separate RightID consts + 13 Waivable* bool consts (all false) + RightIsWaivable(id) always returns false (dual firewall: const + ValidateBasic gate on Cover-Charter waiver list)"
|
||||
- "Anti-Crowding-Out firewall = x/cover/firewall subpackage (runtime CheckCoverFeeRouting) + lexicon_meta_cover meta-test (test-time doc-drift rejection) — defense in depth (D-079)"
|
||||
- "Cover Claims Voucher: CoverClaimsVoucher struct in x/cover/types (NOT x/standing); bond = CoverClaimsVoucherBondMultipleAvgCall=10 × avg Call size; slash via x/standing.Slash with SlashReasonFraudulentCoverCall const; cross-Pool via Standing bucket drop"
|
||||
- "MAB coupons NEVER Bread — CouponDenom enum with CouponDenomBread rejected at ValidateBasic (MissionLockAmendmentRejected pattern)"
|
||||
- "Secession cooling consts secured at founding, not reducible (REQ-064 locked); GoodStandingLiens SecuredAtFounding=true not freely increasable (REQ-053/REQ-081)"
|
||||
|
||||
- id: cosmos-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: REACTIVATED for v0.5. cosmos-sdk is now a load-bearing dependency (D-055 GRILL-approved controlled exception to G-006), so Cosmos-SDK convention alignment is owned rather than advisory. Owns: (1) the MsgServer promotion pattern across all 8 target modules — keeper/keeper.go (store-backed, wraps sdk.KVStore), types/msg_*.go (sdk.Msg: ValidateBasic + GetSigners), keeper/msg_server.go (one *Response,error method per Msg*), module.go (AppModule + RegisterServices), simtest exercising each handler against an in-memory sdk.Context; (2) the IBC v2 / IBC Eureka patterns in x/bridge (OnRecvPacket/OnAcknowledgementPacket/OnTimeoutPacket, timestamp-only timeouts for EVM chains, the ICS-20 v1 payload parser); (3) the expected_keepers.go shim convention (ibc-go standard for breaking cross-module keeper dep cycles — e.g. x/exit/types/expected_keepers.go defines a BridgeKeeper interface that the x/bridge keeper satisfies structurally; preserves G-003 by-ID-string rule at the type level); (4) the simtest scaffolding (in-memory store, sdk.Context construction, event emission assertions). The v0.3 in-memory Keeper stubs (in types/types.go) are retired or wrapped as test helpers — the types/ public API is not broken.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x (D-055), ibc-go v8.x, cometbft (simtest in-memory store only), Go testing, simtest]
|
||||
territory: ["x/exit/keeper/**", "x/exit/types/msg_*.go", "x/exit/types/expected_keepers.go", "x/exit/module.go", "x/bridge/keeper/**", "x/bridge/types/msg_*.go", "x/bridge/types/expected_keepers.go", "x/bridge/module.go", "x/bearers/keeper/**", "x/bearers/types/msg_*.go", "x/bearers/module.go", "x/partner/keeper/**", "x/partner/types/msg_*.go", "x/partner/types/expected_keepers.go", "x/partner/module.go", "x/hub/keeper/**", "x/hub/types/msg_*.go", "x/hub/types/expected_keepers.go", "x/hub/module.go", "x/services/keeper/**", "x/services/types/msg_*.go", "x/services/types/expected_keepers.go", "x/services/module.go", "x/bond/keeper/**", "x/bond/types/msg_*.go", "x/bond/types/expected_keepers.go", "x/bond/module.go", "x/council/keeper/**", "x/council/types/msg_*.go", "x/council/types/expected_keepers.go", "x/council/module.go"]
|
||||
constraints: ["MsgServer convention (cosmos-sdk v0.40+ Stargate): MsgServer struct wraps the module Keeper; one method per Msg* returning (*Response, error); routed by base app MsgServiceRouter", "sdk.Msg contract: ValidateBasic (stateless gate, runs before handler), GetSigners (authz), ProtoMessage/JSONCodec registration", "handler state-machine ordering: (1) ValidateBasic (in msg), (2) keeper authz check, (3) state mutation under store, (4) ctx.EventManager().EmitEvent — reordering causes double-spend/replay", "expected_keepers.go convention: cross-module keeper deps are INTERFACES defined in the consuming module's types/ (e.g. x/exit/types/expected_keepers.go BridgeKeeper); the concrete keeper satisfies it structurally; NOT a struct import of x/bridge/types — G-003 preserved", "IBC handlers implement the ibc-go IBCModule / PacketExecutor contract (OnRecvPacket/OnAcknowledgementPacket/OnTimeoutPacket); ICS-20 v1 payload pinned to the v0.2 satellite packet shape", "simtest uses SDK in-memory store (dbm in-memory backend) + sdk.NewContext; no live CometBFT node, no real IBC light clients (D-054)", "version pin (A-504, planner/GRILL confirms): cosmos-sdk v0.50.x LTS + ibc-go v8.x (stable); ibc-go v10 IBC-v2/Eureka is the documented pattern but a newer pin"]
|
||||
reason: "Advisory-density for v0.7. The `x/cover` module is new but follows the established x/hub D-039 pattern (types/ + keeper/ + module.go + expected_keepers.go + msg_server.go + simtest). The MsgServer promotion pattern is established (v0.5). cosmos-engineer reviews the x/cover AppModule wiring, RegisterServices, MsgServer() accessor, and the expected_keepers.go interface shims (StandingKeeper, WatcherKeeper, BondKeeper) for G-003 compliance. Less novel than v0.5 (where cosmos-sdk was first introduced)."
|
||||
frameworks: [cosmos-sdk v0.50.x, ibc-go v8.x, Go testing, simtest]
|
||||
territory: ["x/cover/keeper/**", "x/cover/types/msg_*.go", "x/cover/types/expected_keepers.go", "x/cover/module.go"]
|
||||
constraints:
|
||||
- "x/cover module follows x/hub layout (D-039 precedent): module.go AppModule + RegisterServices + MsgServer() accessor"
|
||||
- "expected_keepers.go interfaces for cross-module keeper access (G-003): StandingKeeper.GetStandingBucket, WatcherKeeper.Attest, BondKeeper.GetBond"
|
||||
- "Msg* structs implement sdk.Msg; ValidateBasic on each (cover-firewall, category-tag, standing-gate, reserve-floor, MAB-ceiling, rights-waiver-rejection)"
|
||||
- "simtest pattern: msg_server_simtest_test.go exercising handlers against in-memory sdk.Context (x/hub/keeper/msg_server_simtest_test.go precedent)"
|
||||
|
||||
- id: mesh-engineer
|
||||
active: true
|
||||
phase_specific: true
|
||||
reason: REACTIVATED for the bearer transport runtime in P2 (REQ-034). Owns the OY-SAT + OY-QR message handlers in x/bearers: MsgSendOYSATFrame, MsgReceiveOYSATFrame, MsgIssueOYQR, MsgConsumeOYQR, and the session lifecycle (Open/Active/Closed/Revoked). The v0.3 OYSATLink (surveillance-resistant=true locked) and OYQRCode (one-shot consumed flag) become the handler state objects. Key mesh-specific invariants: (1) OY-QR is one-shot — MsgConsumeOYQR flips consumed BEFORE the transfer effect (replay rejected idempotently, A-521); (2) the surveillance-resistant const is a runtime invariant — the handler must NOT emit geolocation or sender physical location (simtest asserts the event set has NO geolocation fields, a negative test); (3) the BearerTransport interface gains a store-backed impl (the keeper acts as the transport in simtest; no hardware/RF dep, D-054). Hardware integration is explicitly deferred. mesh-engineer is phase-specific (P2 only) — outside P2 the bearer transport territory reverts to backend-engineer.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x, Go testing, simtest, lexicon firewall]
|
||||
territory: ["x/bearers/keeper/**", "x/bearers/types/msg_bearer*.go", "x/bearers/types/types.go", "x/bearers/module.go", "x/bearers/simtest/**"]
|
||||
constraints: ["OY-QR one-shot: MsgConsumeOYQR flips consumed BEFORE the transfer effect (atomic per-tx; replay finds consumed==true and returns error idempotently, A-521)", "surveillance-resistant const is a runtime invariant — handler emits NO geolocation / sender physical location; simtest negative-test asserts the event set is geolocation-free", "BearerTransport interface gets a store-backed impl (keeper as transport in simtest); NO hardware/RF/LoRa/BLE/satellite Go libraries (D-054 — runtime = message-handling + session lifecycle, not hardware)", "session lifecycle mirrors the v0.2 Window lifecycle (Open/Active/Closed/Revoked) for consistency; frames received on Closed/Revoked sessions are rejected", "lexicon-safe: 'session', 'frame', 'bearer', 'QR', 'SAT' are safe; AVOID 'account'/'deposit' (use reach-id/Stash by ID)"]
|
||||
|
||||
phase_specific_personas:
|
||||
- id: data-engineer
|
||||
active: true
|
||||
phase_specific: true
|
||||
reason: REACTIVATED for P4 (Hub API runtime) ONLY — owns the hub custody state via an in-memory test store (the memKeyring + the keeper's store-backed custody asset records). The custody asset records are the closest thing to a data store in v0.5; there is NO real database and NO migration (the SDK in-memory store is the substrate). data-engineer's role is narrow: ensure the custody state shape (assetID → custody entry + sig ref + key version) is consistent with the CustodyKeyring interface and supports rotation. Removed after P4 (the hub runtime ships; later phases do not touch custody state shape). This mirrors the v0.3 data-engineer pattern (genesis schemas) but scoped to the P4 custody store.
|
||||
frameworks: [Go 1.22, cosmos-sdk v0.50.x store, Go testing]
|
||||
territory: ["x/hub/keeper/keyring_mem*.go", "x/hub/keeper/custody_state*.go"]
|
||||
constraints: ["in-memory test store ONLY — no real database, no migration (D-054 simtest grade)", "custody state shape consistent with CustodyKeyring interface (assetID → custody entry + sig ref + key version); supports rotation", "removed after P4 (hub runtime ships; later phases do not touch custody state shape)"]
|
||||
|
||||
deactivated:
|
||||
deactivated_personas:
|
||||
- id: frontend-engineer
|
||||
reason: INACTIVE for v0.5. The v0.3 docs site (docs/**, mkdocs.yml) is COMPLETE; v0.5 has no UI/docs-content work. The docs build CI (REQ-032, v0.4) already covers docs-build on every push. Reactivate in v0.6+ if docs content is restructured or i18n is added.
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "v0.7 is protocol-heavy, zero UI. The v0.6 web UI (web/) is complete; v0.7 does not touch web/. No frontend work in REQ-046..REQ-066."
|
||||
- id: docs-writer
|
||||
reason: INACTIVE for v0.5. Same reason as frontend-engineer — v0.3's docs-writer owned page content authoring; v0.5 has zero new docs pages. The only documentation work is the ARCHITECTURE.md v0.5 runtime section + this PERSONAS.md + RESEARCH.md, which is lead-developer/researcher architecture territory, not audience-content authoring. Reactivate if a future milestone adds docs pages.
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "No docs-content work in v0.7. The only docs work is ARCHITECTURE.md v0.7 section + PERSONAS.md + RESEARCH.md, which is lead-developer territory."
|
||||
- id: mesh-engineer
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "No bearer transport work in v0.7. The bearer runtime shipped in v0.5 and is untouched. Cover Pools are a protocol/financial surface, not a bearer/transport surface."
|
||||
- id: data-engineer
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: "No genesis-schema or custody-state work in v0.7. x/cover uses the SDK in-memory store pattern from v0.5; no new data-shape work."
|
||||
- id: ci-security-auditor
|
||||
reason: Default deactivated; activate in P8 (final review/audit/ship) for the v0.5 milestone audit and feature purity gate enforcement (no breaking schema changes; locked-const firewall intact; G-003 production firewall intact; G-006 controlled exception GRILL-ratified).
|
||||
|
||||
custom_personas: []
|
||||
---
|
||||
|
||||
# Personas: OpenYield (oy) — v0.5 (Bearers Runtime — Feature)
|
||||
|
||||
> This file supersedes the v0.4 PERSONAS.md for the v0.5 milestone. v0.5 is a
|
||||
> **feature** milestone (D-054): the v0.3 Bearers skeletons are promoted
|
||||
> from types + in-memory keeper stubs + invariant tests to live keeper
|
||||
> MsgServer message handlers + simtest-grade end-to-end flows. This is
|
||||
> NOT mainnet — D-020 continues to govern network deployment; runtime =
|
||||
> simtest-grade handlers, not live chain.
|
||||
>
|
||||
> The active roster is **backend-engineer + lead-developer + security-
|
||||
> engineer (REACTIVATED) + cosmos-engineer (REACTIVATED) + mesh-engineer
|
||||
> (REACTIVATED, P2 phase-specific)**. The v0.3 docs personas (frontend-
|
||||
> engineer, docs-writer) are deactivated because v0.5 has no docs-content
|
||||
> work (the docs site is complete from v0.3; the docs build CI is complete
|
||||
> from v0.4). data-engineer is reactivated as a P4-phase-specific persona
|
||||
> for the hub custody state (in-memory test store only; removed after P4).
|
||||
> ci-security-auditor is default off; activate in P8 for the final audit.
|
||||
>
|
||||
> cosmos-sdk is now a load-bearing dependency (D-055 GRILL-approved
|
||||
> controlled exception to G-006); go.mod gains cosmos-sdk v0.50.x +
|
||||
> ibc-go v8.x (A-504, planner/GRILL confirms the exact pin).
|
||||
|
||||
## Active Roster
|
||||
|
||||
| Persona | Active | Phase-specific | Territory |
|
||||
|---------|--------|-----------------|-----------|
|
||||
| backend-engineer | yes | no (all runtime phases P1..P7) | `x/{exit,bridge,bearers,partner,hub,services,bond,council}/**`, `lexicon*` |
|
||||
| lead-developer | yes | no (all phases) | `.ciagent/**`, `.gitea/workflows/**` |
|
||||
| security-engineer | yes | no (all runtime phases) | `x/hub` keyring, `x/bond` keeper, `x/bridge` keeper, `x/council` keeper, `lexicon/**` |
|
||||
| cosmos-engineer | yes | no (all runtime phases) | `keeper/**`, `types/msg_*.go`, `types/expected_keepers.go`, `module.go` across all 8 target modules |
|
||||
| mesh-engineer | yes | yes (P2 only) | `x/bearers/keeper/**`, `x/bearers/types/msg_bearer*.go`, `x/bearers/simtest/**` |
|
||||
| data-engineer | yes | yes (P4 only) | `x/hub/keeper/keyring_mem*.go`, `x/hub/keeper/custody_state*.go` |
|
||||
|
||||
## Phase-Persona Matrix
|
||||
|
||||
| Phase | Personas | Work |
|
||||
|-------|----------|------|
|
||||
| P0 (pre-execution) | lead-developer (spec/clarify/research/plan/grill/mvp-ux + ship) | this file + RESEARCH.md + ARCHITECTURE.md v0.5 sections; planner-escalation items surfaced |
|
||||
| P1 (exit + bridge runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-033: `x/exit` DEX swap routing + `x/bridge` L2↔L1 IBC packet handlers (5 L2 chains, D-059); ibc-go IBCModule contract; Solana wormhole-adapter branch; replay/timeout simtest |
|
||||
| P2 (bearers transport runtime) | backend-engineer + cosmos-engineer + mesh-engineer (phase-specific) | REQ-034: OY-SAT + OY-QR message handlers; session lifecycle; OY-QR one-shot consumed-before-transfer; surveillance-resistant invariant |
|
||||
| P3 (anchors onboarding runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-035: `x/partner` Anchor credential issuance + revocation handlers; Watcher-quorum authz via expected-keeper shim; P3→P4 hub dep broken by HubKeeper interface shim |
|
||||
| P4 (hub API B2B runtime) | backend-engineer + cosmos-engineer + security-engineer + data-engineer (phase-specific) | REQ-036: custody/lending/compliance handlers; CustodyKeyring interface + memKeyring (D-058); lending coupon clamp [0,800]; compliance-before-custody ordering; lexicon (avoid 'deposit' in Msg names) |
|
||||
| P5 (services runtime) | backend-engineer + cosmos-engineer | REQ-037: Care/SIM/Vault/Mail service lifecycle handlers; per-kind Msg* (typed dispatch); window-grant checked on every op |
|
||||
| P6 (bond market runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-038: Growth Bond issuance + secondary-market CLOB matching (D-057); per-match coupon clamp [0,800] (A-562 reject-above-cap, planner confirms); price-time priority FCFS (REQ-007); no AMM |
|
||||
| P7 (council governance runtime) | backend-engineer + cosmos-engineer + security-engineer | REQ-039: Proposal/VoteOption enums (AUDIT §193 P1-1); Voice lifecycle handlers; MissionLockAmendment-Rejected rejected at ValidateBasic (A-572); Watcher Veto quorum (A-574, default 6); SignalKind stays 4 |
|
||||
| P8 (final review/audit/ship) | lead-developer + ci-security-auditor (activated) | feature purity gate audit; locked-const firewall verification; G-003 + G-006 (D-055 exception) verification; milestone ship |
|
||||
|
||||
## Constraints Carried Forward
|
||||
|
||||
- **G-003 production firewall intact**: keeper-to-keeper cross-module calls use `expected_keepers.go` interface shims (ibc-go convention), NOT struct imports of `x/<module>/types`. The by-ID-string rule is preserved at the type level. Test-only cross-package imports remain exempt (the G-003 test exemption, used by REQ-030 in v0.4; simtest may import multiple `x/*/keeper` packages to wire shims).
|
||||
- **G-006 controlled exception (D-055)**: `go.mod` gains `cosmos-sdk v0.50.x` + `ibc-go v8.x` (GRILL-ratified). Scoped to runtime phases P1..P7; P0 + P8 stay dep-neutral where possible. `types/` packages gain `sdk.Msg` imports for `Msg*` types (isolated in `types/msg_*.go`); invariant/lexicon tests stay stdlib-only and green. Exact version pin is A-504 (planner/GRILL confirms).
|
||||
- **Locked-const invariants unchanged**: v0.5 ADDS `ProposalKind` (4) / `ProposalStatus` (5) / `VoteOption` (4) enums to `x/council/types` (AUDIT §193 P1-1 promotion, D-060) but does NOT change existing locked consts — `CouponCapBps=800` / `CouponFloorBps=0` (D-028), `BearerTypeCount=6`, `PartnerTierCount=4`, `MissionLockAmendable=false`, `SignalKindCount=4` (P1-2 defensible; v0.4 `TestSignalKindShapeIntentional` stays green), `BridgeStatusCount=4`, `ExitStatusCount=5`, `ServiceKindCount=4`, `HubServiceCount=3`, `CouncilKindCount=3`, etc. The REQ-030 cross-const test (`hub.LendingCouponCapBps==bond.CouponCapBps`) stays green.
|
||||
- **Lexicon firewall stays green**: the `lexicon_meta_test.go` (x/**/*.go) + `lexicon_meta_docs_test.go` (docs) automatically cover the new `keeper/`, `msg_server.go`, `simtest/` files. The new `Msg*` struct names are the lexicon surface — AVOID "deposit" in `x/hub` custody message names (use `MsgCustodyReceiveAsset`/`MsgCustodyReleaseAsset`, A-542); "coupon" not "interest"/"yield" in `x/bond`; "session"/"frame" safe in `x/bearers`; "veto" safe in `x/council`. Per-module lexicon assertions added to each new `keeper/` package.
|
||||
- **Simtest NOT mainnet (D-054)**: handlers exercised against in-memory `sdk.Context` + dbm in-memory store; no real IBC light clients, no real MPC, no real bearer hardware, no real DEX venues, no real Watcher attestations (all stubbed). The simtest does NOT assert front-running safety (out of scope for simtest-grade runtime; the CLOB handler is documented as NOT front-running-safe for mainnet, a Year-3+ concern).
|
||||
- **≥80% coverage on runtime packages (D-033 carries forward)**: every `keeper/msg_server.go` + simtest must hit the bar; table-driven handler tests per `Msg*`.
|
||||
|
||||
## Planner-Escalation Items (low-confidence assumptions, surfaced through the normal decision flow)
|
||||
|
||||
These are NOT auto-decided; the planner must resolve them before the corresponding phase lands:
|
||||
|
||||
1. **A-504** — cosmos-sdk / ibc-go version pin (proposed: cosmos-sdk v0.50.x + ibc-go v8.x; alternative: ibc-go v10 IBC-v2/Eureka). GRILL review. Confidence 0.78.
|
||||
2. **A-562** — bond CLOB match above 800 bps: REJECT (fails closed, proposed) vs CLAMP-with-refund (D-057 says "clamp"). Resolve before P6. Confidence 0.70.
|
||||
3. **A-572** — `MissionLockAmendment-Rejected` ProposalKind: reject at `ValidateBasic` (proposed, the message never reaches the handler) vs propose-then-fail (record Pending → auto-transition Failed with event). Resolve before P7. Confidence 0.80.
|
||||
4. **A-574** — Watcher Veto quorum value (proposed default: 6, matching REQ-004 6-of-9). Resolve before P7. Confidence 0.75.
|
||||
|
||||
## Removal Notes
|
||||
|
||||
- frontend-engineer and docs-writer were deactivated in v0.4 (no docs-content phase); they remain deactivated in v0.5 for the same reason (the docs site is complete from v0.3; the docs build CI is complete from v0.4). They will reactivate in v0.6+ if docs content is restructured or i18n is added.
|
||||
- cosmos-engineer, security-engineer, and mesh-engineer were deactivated in v0.3/v0.4 (lower Cosmos-convention / invariant density, no bearer hardware runtime); they are REACTIVATED in v0.5 because cosmos-sdk is now load-bearing (D-055), the runtime introduces new security-critical invariant surfaces (CustodyKeyring, CLOB clamp, IBC replay, Mission-Lock const firewall), and the bearer transport gets live handlers (P2).
|
||||
- data-engineer is reactivated as a P4-phase-specific persona (hub custody state, in-memory test store only) and removed after P4. This mirrors the v0.3 genesis-schema pattern but scoped narrowly to the P4 custody store.
|
||||
- ci-security-auditor is default off; activate in P8 for the final audit + feature purity gate.
|
||||
active: false
|
||||
phase_specific: true
|
||||
reason: "Default off; activates in P6 (final review/audit/ship) for the feature purity gate + the §7 acceptance pen-test (self-administered adversarial review)."
|
||||
+144
-4
@@ -2720,7 +2720,147 @@ component map → per-concern firewall/dep sections → interface contracts).
|
||||
POST (form submit) + path params (`/reaches/{id}`) is the full routing
|
||||
surface; no middleware, no wildcard host matching needed. Confidence
|
||||
0.95.
|
||||
5. **`web/main.go` is the entrypoint (not `cmd/oyd-ui/main.go`)** — D-068
|
||||
says `web/` contains `main.go` (or `cmd/oyd-ui/main.go`); the simpler
|
||||
`web/main.go` matches the mock-server scope (single binary, no
|
||||
subcommands). Confidence 0.80.
|
||||
5. **`web/main.go` is the entrypoint (not `cmd/oyd-ui/main.go`)** — D-068
|
||||
says `web/` contains `main.go` (or `cmd/oyd-ui/main.go`); the simpler
|
||||
`web/main.go` matches the mock-server scope (single binary, no
|
||||
subcommands). Confidence 0.80.
|
||||
|
||||
---
|
||||
|
||||
## v0.7 Research — Fraternal Groups Foundation (Phase 0, RESEARCH stage)
|
||||
|
||||
Scope: REQ-046..REQ-066 (21 REQs). Feature milestone. Tags run on v0.6.x
|
||||
patch line. Simtest-grade runtime only (D-020 continues). Research covered
|
||||
7 areas: (1) fraternal benefit society historical prior art, (2) Cover Pool
|
||||
runtime design, (3) MAB mechanics, (4) Anti-Capture Bill of Rights, (5)
|
||||
Chapter Federation + secession, (6) anti-gaming/Sybil surfaces, (7) persona
|
||||
assessment. Full findings in ci-researcher subagent output; key decisions
|
||||
and design recommendations summarized here.
|
||||
|
||||
### D-085 escalation candidate (13th Anti-Capture right)
|
||||
|
||||
The spec enumerates 12 of 13 rights in REQ-056 acceptance criteria: one-tap
|
||||
exit, no tax on personal Stash, audit-able Voice, cooling, Watcher
|
||||
inspection, Freeholder voucher, Counsel escalation, Anchored-Bread
|
||||
conversion, Wayfarer's Record, secession (founding terms), non-Cover-access,
|
||||
category-mismatch refusal. The 13th is NOT enumerated. Best candidate
|
||||
(confidence 0.55): "non-participation MUST NOT deny other mesh products"
|
||||
(REQ-085 / FR-NORM-4 norm-chilling defense). Alternatives: "Standing
|
||||
portability", "Mesh migration". This is a low-confidence assumption —
|
||||
escalated through normal decision flow; NOT auto-decided. The lead-developer
|
||||
must surface D-085 to the PO before P5 (Anti-Capture Bill lands in P5). If
|
||||
unresolved at full autonomy by P5, log as assumption with the
|
||||
NonParticipationNoDenial candidate and proceed.
|
||||
|
||||
### Design recommendations (grounded in codebase)
|
||||
|
||||
1. **`x/cover` module layout mirrors `x/hub` (D-039 precedent, D-084).**
|
||||
Verified at `x/hub/types/types.go:33-57` + `x/hub/module.go:32-55`. Layout:
|
||||
`x/cover/{module.go, types/{types.go,rights.go,firewall.go,expected_keepers.go,msg_cover.go}, keeper/{keeper.go,msg_server.go,firewall.go,msg_server_simtest_test.go}}`.
|
||||
The `x/pact` `PactCover` enum value (`x/pact/types/types.go:36`) stays as
|
||||
cross-reference; `x/cover` owns the runtime. Confidence 0.90.
|
||||
|
||||
2. **Cover-Fee category tagging in `x/cover`, NOT `x/bread` (REQ-050).** No
|
||||
`Grain` struct exists today (`x/bread/types/types.go` has only
|
||||
`BreadScale`/`Params`/`GenesisState`). Adding a tag field to `x/bread`
|
||||
risks the `GrainsPerBread=10000` locked-const firewall. A `CoverFeeTag`
|
||||
struct in `x/cover/types` (`{GrainAmount int64, CategoryTag string,
|
||||
PoolID string}`) is schema-additive and puts the tag where the
|
||||
category-mismatch rejection (FR-COVER-11) lives. Confidence 0.82.
|
||||
|
||||
3. **Standing gate via expected-keeper shim (G-003, D-077).** `x/cover`
|
||||
defines a `StandingKeeper` interface
|
||||
(`GetStandingBucket(reachID, category string) (bucket string, score
|
||||
float64, err error)`); the `x/standing` keeper satisfies it structurally.
|
||||
The gate compares the returned bucket string against LOCAL `x/cover`
|
||||
consts `CoverStandingGateTrusted=4.0` / `CoverStandingGatePreferred=4.5`
|
||||
(cross-documented to `x/standing.BucketTrusted`/`BucketPreferred`).
|
||||
Mirrors `x/bond/types/expected_keepers.go:43-49` `StandKeeper` pattern.
|
||||
Confidence 0.88.
|
||||
|
||||
4. **MAB as `x/bond` extension (anonymous embed), NOT a new module.**
|
||||
`MAB struct { Bond; CouponKind CouponDenom; AnnualSurplusAtIssuance
|
||||
int64; UseOfProceedsTag string }` in `x/bond/types`. Mirrors GrowthBond
|
||||
at `x/bond/types/types.go:262-265`. `CouponDenom` enum with
|
||||
`CouponDenomBread` rejected at `ValidateBasic` (MissionLockAmendmentRejected
|
||||
pattern at `x/council/types/types.go:242`). 3× ceiling as keeper-level
|
||||
runtime check against current annual surplus. Confidence 0.88.
|
||||
|
||||
5. **D-080 tagged streaming + Watcher-witnessed release.** `UseOfProceedsTag`
|
||||
field locked to `"reserve_build_out"` at issuance; keeper enforces
|
||||
proceeds only debit to `CoverPool.ReserveAccount`; misuse → auto-Still
|
||||
(`x/still` exists). `MsgWitnessMABProceedsRelease` requires Watcher quorum
|
||||
(6-of-9, `x/watcher/types/types.go:23`). Confidence 0.84.
|
||||
|
||||
6. **Anti-Capture Bill of Rights = 13 RightID consts + 13 Waivable* bool
|
||||
consts (all false) + `RightIsWaivable(id)` always returns false.** Dual
|
||||
firewall: const + `ValidateBasic` gate on Cover-Charter `WaivedRights`
|
||||
field (mirrors `MissionLockAmendable=false` +
|
||||
`MissionLockAmendmentRejected`). In `x/cover/types/rights.go` (NOT a
|
||||
separate `x/cover/rights` package — D-079 specifies separate
|
||||
`x/cover/firewall` package for enforcement, but rights *declaration* is a
|
||||
type/const surface). Confidence 0.90.
|
||||
|
||||
7. **Anti-Crowding-Out firewall (D-079) = `x/cover/firewall` subpackage
|
||||
(runtime `CheckCoverFeeRouting`) + `lexicon_meta_cover` meta-test
|
||||
(test-time doc-drift rejection).** Defense in depth. The firewall is the
|
||||
enforcement mechanism for the `RightNoTaxOnPersonalStash` right (the
|
||||
right is policy; the firewall is implementation). Confidence 0.82.
|
||||
|
||||
8. **Guild extension: `ParentGuildID string` + `IsChapter bool` +
|
||||
`SecessionTermsHash []byte` + `GoodStandingLiens []Lien`.** No `GuildKind`
|
||||
enum (schema-additive without a new locked-const count).
|
||||
`SecessionTerms` struct hash-pinned at creation (immutable).
|
||||
`Lien.SecuredAtFounding=true` liens NOT freely increasable. Cooling consts
|
||||
`CoolingSecessionCoverActiveDays=21` / `CoolingSecessionNonCoverDays=14`
|
||||
in `x/guild/types` (protocol minimum; Chapter MAY specify longer, NOT
|
||||
shorter). Confidence 0.85.
|
||||
|
||||
9. **Shadow vouch 50% weight (REQ-060) = new const
|
||||
`ShadowVouchWeightMultiplier=0.5` + new `IsShadow bool` field on `Vouch`
|
||||
+ post-multiplier branch in `GetVoucherWeight`.** The const makes the 0.5×
|
||||
mission-locked (REQ-060 locked) and regression-testable. A hardcoded 0.5
|
||||
in a branch is invisible to the locked-const firewall. Confidence 0.85.
|
||||
|
||||
10. **Cover Claims Voucher (REQ-055) = `CoverClaimsVoucher` struct in
|
||||
`x/cover/types` (NOT `x/standing`).** Bond =
|
||||
`CoverClaimsVoucherBondMultipleAvgCall=10` × Pool avg Call size. Slash
|
||||
via existing `x/standing.Slash` with new
|
||||
`SlashReasonFraudulentCoverCall` const (cross-Pool via Standing bucket
|
||||
drop). No self-adjudication: `MsgFileCoverCall` handler rejects if
|
||||
`voucherReachID == claimantReachID` (FR-CPCV-2). Confidence 0.82.
|
||||
|
||||
### Persona assessment
|
||||
|
||||
Active for v0.7: backend-engineer (all phases — the bulk), lead-developer
|
||||
(all phases — coordination + D-085 escalation + pen-test assumption),
|
||||
security-engineer (all phases — highest security density since v0.5),
|
||||
cosmos-engineer (all phases — advisory; x/cover follows x/hub pattern).
|
||||
|
||||
Deactivated: frontend-engineer (zero UI), docs-writer (no docs-content),
|
||||
mesh-engineer (no bearer work), data-engineer (no genesis-schema work).
|
||||
ci-security-auditor: off until P6 (final review/audit/ship).
|
||||
|
||||
Full PERSONAS.md written to `.ciagent/oy/PERSONAS.md`.
|
||||
|
||||
### Pitfalls (avoid)
|
||||
|
||||
- Do NOT centralize Cover risk at the Root-Pool (historic AOUW collapse
|
||||
reproduced; Anti-Crowding-Out firewall is the defense).
|
||||
- Do NOT enforce uniform SoB content (historic centralization; FR-CHTR-5).
|
||||
- Do NOT add `CategoryTag` to `x/bread/types.Grain` (risks GrainsPerBread
|
||||
locked-const firewall; use CoverFeeTag in x/cover).
|
||||
- Do NOT import `x/standing/types` structs in `x/cover` (G-003; use
|
||||
expected-keeper shim).
|
||||
- Do NOT retire `x/pact.PactCover` enum value (stays as cross-reference).
|
||||
- Do NOT make 1.5× floor a Params field (locked const; only 2.5× ceiling is
|
||||
governance-tunable within bounds).
|
||||
- Do NOT allow `CouponDenomBread` MAB (rejected at ValidateBasic).
|
||||
- Do NOT give MAB holders Voice (REQ-063 locked; claimants, not Masons).
|
||||
- Do NOT add a `GuildKind` enum (bool IsChapter + ParentGuildID string is
|
||||
schema-additive without a new locked-const count).
|
||||
- Do NOT make cooling periods reducible (REQ-064 locked; secured at founding).
|
||||
- Do NOT implement Shadow vouch 50% without a const (locked-const firewall
|
||||
invisibility).
|
||||
- Do NOT put `CoverClaimsVoucher` in `x/standing` (role is Cover-specific).
|
||||
- Do NOT auto-decide the 13th right (D-085 escalation; confidence 0.55).
|
||||
Reference in New Issue
Block a user