From 622b2bd73ea9660230cc82d6c96e9852d100a0bd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 18:53:35 +0000 Subject: [PATCH 01/14] Add M0-M7 economy organ plan specs (stomach) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The economy organ was the least-documented named component in the architecture — one line in bus-topology.md, a Pony primitive, and a smoke-test wire. This adds 8 plan specs following the 10-section template: M0 hub, M1 ingestion, M2 digestion core (small-model), M3 cost ledger, M4 budget governor, M5 context yield, M6 provenance chain (S1/S2 compliance), M7 outer-bus exchange. Also updates the plans README index and integration DAG, and resolves bus-topology.md's open item about the organ's placement. Co-Authored-By: Claude Opus 4.6 --- core/docs/bus-topology.md | 4 +- core/docs/plans/M0-economy-organ-hub.md | 66 ++++++++++++++++++++ core/docs/plans/M1-ingestion.md | 60 ++++++++++++++++++ core/docs/plans/M2-digestion-core.md | 70 +++++++++++++++++++++ core/docs/plans/M3-cost-ledger.md | 63 +++++++++++++++++++ core/docs/plans/M4-budget-governor.md | 66 ++++++++++++++++++++ core/docs/plans/M5-context-yield.md | 73 ++++++++++++++++++++++ core/docs/plans/M6-provenance-chain.md | 79 ++++++++++++++++++++++++ core/docs/plans/M7-outer-bus-exchange.md | 76 +++++++++++++++++++++++ core/docs/plans/README.md | 12 +++- 10 files changed, 567 insertions(+), 2 deletions(-) create mode 100644 core/docs/plans/M0-economy-organ-hub.md create mode 100644 core/docs/plans/M1-ingestion.md create mode 100644 core/docs/plans/M2-digestion-core.md create mode 100644 core/docs/plans/M3-cost-ledger.md create mode 100644 core/docs/plans/M4-budget-governor.md create mode 100644 core/docs/plans/M5-context-yield.md create mode 100644 core/docs/plans/M6-provenance-chain.md create mode 100644 core/docs/plans/M7-outer-bus-exchange.md diff --git a/core/docs/bus-topology.md b/core/docs/bus-topology.md index 6a1e06e..9973b79 100644 --- a/core/docs/bus-topology.md +++ b/core/docs/bus-topology.md @@ -84,4 +84,6 @@ blocking in a protected action), **tasks = workers** that call into the organs structure that isn't a lookup "store"? - **MoRAG / GoDAGRAG language** (Haskell vs Crystal vs other). - Each outer organ's hand-off shape to Ada. -- The stomach/economy organ's exact placement + which small model runs it. +- ~~The stomach/economy organ's exact placement + which small model runs it.~~ + **→ placed:** M-series (M0–M7) in `docs/plans/`. Outer organ on Ichor; small model TBD (M2). + See M0 (hub), M6 (provenance chain through digestion, S1/S2 compliance). diff --git a/core/docs/plans/M0-economy-organ-hub.md b/core/docs/plans/M0-economy-organ-hub.md new file mode 100644 index 0000000..cf1b9c5 --- /dev/null +++ b/core/docs/plans/M0-economy-organ-hub.md @@ -0,0 +1,66 @@ +# M0 — Economy organ hub (the stomach) + +## 1. Component +The economy organ — the organism's **stomach**. An outer organ on Ichor that **digests external +input into context** and **tracks the cost of doing so**. Hub for the M-series sub-components +(M1–M7): ingestion, digestion, cost ledger, budget governor, context yield, provenance chain, +outer-bus exchange. "Economy" = the organ economizes: it spends scarce resources (tokens, compute, +attention budget) to convert raw input into usable context, and **accounts for every unit spent**. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. A `Stomach` primitive exists in Ichor (`src/ichor/envelope.pony:20`) with +one smoke-test wire (`main.pony:29`), but no dedicated organ code. Role C4; implementation C1. + +## 3. Language & location +TBD · new location e.g. `src/economy/`. The digestion core (M2) requires a small-model runtime; +the accounting/budget layers (M3–M4) can be any language that interops with Pony (Ichor) and Ada +(D1). Pony actors are the natural fit for the bus-facing facade. + +## 4. Does / does-not +- **Does:** receive external input from Ichor; triage and classify it (M1); digest it via a small + model into context (M2); track the resource cost of that digestion (M3); enforce budget limits + and emit price signals to A2 (M4); shape output for Ada (M5); maintain provenance through the + pipeline (M6); coordinate with outer-bus peers — MoRAG, SAE, microagents (M7). +- **Does-not:** police (Ada D1 does that); decide actions (the agent decides, per A1-L3); store + memories (E*); route the bus (Ichor broker); reason or deliberate (it digests, it doesn't think). + +## 5. Interface contract +- `ingest(external_input, provenance) -> classified_input` (M1 — triage + classify). +- `digest(classified_input) -> digested_context` (M2 — small-model transform). +- `record_cost(organ_id, action, resource_amt) -> receipt` (M3 — ledger entry). +- `check_budget(organ_id, proposed_cost) -> { allowed:bool, remaining:num }` (M4). +- `price_signal(tool_id) -> { resource_cost:num, budget_remaining:num }` (M4 → A2). +- `yield(digested_context) -> Envelope` (M5 — shaped for Ada, with M6 provenance chain attached). +- Output is an Ichor `Envelope` with `OrganSecretion` provenance, carrying the original input's + provenance origin in metadata (M6). + +## 6. Dependencies & stubs +- Ichor bus (D2) — existing `Broker` + `Envelope`. +- Ada border (D1) — existing `Trust_Guard` screens the output; *stub:* Ichor `Barrier`. +- A2 energy — consumes price signals (M4); *stub:* print signals. +- MoRAG (F1) — world-context retrieval; *stub:* fixed context. + +## 7. Invariants / laws +- **L1 (C5):** the stomach is an **OUTER** organ — it rides Ichor, never the inner bus. +- **L2 (C4):** digestion does **not suppress** — it transforms for comprehension (summarize, + classify, extract), never censors. Filtering is Ada's job (D1). +- **L3 (C4):** every resource expenditure is **accounted** — no digestion is "free"; the ledger + (M3) records every token/compute unit spent. +- **L4 (C4):** provenance survives digestion — digested content retains its original provenance + origin in metadata, even as bus transport uses `OrganSecretion` (see M6, S1/S2). + +## 8. Build steps +1. Define the hub wiring: how M1→M2→M5 pipeline + M3/M4 accounting + M6 provenance + M7 peers + connect. Decide: single Pony actor or actor-per-subcomponent. +2. Extend the existing `Stomach` primitive in Ichor to carry the hub facade. +3. Wire sub-components as their specs land (M1–M7). +4. Integrate price signals with A2 (energy driver). + +## 9. Tests +Hub smoke: external input enters → classified → digested → yielded as Envelope → reaches Ada stub. +Cost recorded in ledger. Budget check returns correct remaining. Price signal emitted. + +## 10. Open items +- Single actor vs actor-per-subcomponent (Pony concurrency model for the organ). +- Whether the hub owns state or is purely a wiring facade (stateless router vs stateful coordinator). +- The A2 price-signal protocol (push vs pull; frequency). diff --git a/core/docs/plans/M1-ingestion.md b/core/docs/plans/M1-ingestion.md new file mode 100644 index 0000000..0eb0c63 --- /dev/null +++ b/core/docs/plans/M1-ingestion.md @@ -0,0 +1,60 @@ +# M1 — Ingestion gateway + +## 1. Component +The mouth of the stomach: **receives, classifies, and triages** external input before it enters the +digestion pipeline (M2). The first thing raw input touches inside the economy organ. Decides *how* +to digest — not *whether* (that's Ada's job after digestion). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. The smoke test (`main.pony:29`) hard-codes a single string payload; no +classification or triage logic exists. Role C3; implementation C1. + +## 3. Language & location +TBD · likely part of `src/economy/` or a Pony actor within the stomach. Classification could be +rule-based (fast, no model) or a lightweight classifier (BERT-tiny, shared with F1/MoRAG's BERT). + +## 4. Does / does-not +- **Does:** accept raw `Envelope` payloads from Ichor; classify input by type (user utterance, + tool output, system event, bulk data); assign a **digestion priority** (urgent / normal / bulk); + estimate the **digestion cost** (token count of input × expected expansion factor) and check + budget (M4) before forwarding to M2. +- **Does-not:** filter or censor (M0-L2); digest (M2 does); decide actions (agent decides); + screen provenance (Ada D1). + +## 5. Interface contract +- `ingest(envelope: Envelope) -> ClassifiedInput { type, priority, est_cost, original_provenance, payload }` +- `type` ∈ { `user_utterance`, `tool_output`, `system_event`, `bulk_data`, `unknown` }. +- `priority` ∈ { `urgent`, `normal`, `bulk` } — urgent skips any queue; bulk may be deferred or + chunked under budget pressure (M4). +- `est_cost` = estimated token cost of digesting this input (input tokens + expected output tokens). + M4 checks this against remaining budget before M2 proceeds. +- `original_provenance` = the `Provenance` from the inbound Envelope, carried through for M6. + +## 6. Dependencies & stubs +- Ichor `Envelope` (existing) — input shape. +- M4 budget governor — budget check before forwarding; *stub:* always-allow. +- M2 digestion core — downstream consumer; *stub:* identity (pass-through). + +## 7. Invariants / laws +- **L1 (C4):** classification is **descriptive, not prescriptive** — it labels the input for the + pipeline's benefit, never decides what to do with it. +- **L2 (C4):** no input is **dropped** at ingestion — everything classified reaches M2 (possibly + deferred under budget pressure, but never discarded). Only Ada may reject. +- **L3 (C3):** cost estimation is **conservative** — overestimate rather than underestimate, so + budget checks err on the side of caution. + +## 8. Build steps +1. Define the `ClassifiedInput` shape and the classification rules (start rule-based, no model). +2. Implement cost estimation (token counting + expansion factor). +3. Wire to M4 budget check (gate: proceed / defer / chunk). +4. Wire to M2 downstream. + +## 9. Tests +Classification: each input type correctly tagged. Priority: urgent input not queued. Cost estimate: +known inputs produce expected token counts. Budget gate: over-budget input deferred, not dropped. + +## 10. Open items +- Whether classification needs a model or rules suffice (start with rules; promote if accuracy + demands it). +- The expansion factor (input tokens → output tokens) per input type — needs empirical data (C1). +- Queue/deferral mechanics for bulk input under budget pressure. diff --git a/core/docs/plans/M2-digestion-core.md b/core/docs/plans/M2-digestion-core.md new file mode 100644 index 0000000..237ba12 --- /dev/null +++ b/core/docs/plans/M2-digestion-core.md @@ -0,0 +1,70 @@ +# M2 — Digestion core (small-model) + +## 1. Component +The stomach's engine: a **small language model** that transforms classified input (M1) into +**digested context** — structured, compressed, ready for Ada and ultimately the Brain. This is +what "digests external input → context" means concretely: summarization, extraction, reformatting, +and compression, performed by a model small enough to run cheaply and fast. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. bus-topology.md names it "small-model operated" but leaves the model +unspecified (listed as open). Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/digest/` or similar. Requires an inference runtime for the small model +(e.g. llama.cpp, ONNX, or an API call to a hosted small model). The wrapper is likely Pony +(bus-native) or Python (ML ecosystem), with a Pony actor facade on Ichor. + +## 4. Does / does-not +- **Does:** take `ClassifiedInput` (M1); run the small model to produce `DigestedContext` — + **summarize** (compress verbose input), **extract** (pull structured data from unstructured), + **reformat** (normalize into the context shape Ada/Brain expect); report actual cost to M3. +- **Does-not:** classify (M1 already did); filter/censor (M0-L2 — digest for comprehension, not + approval); reason or deliberate (the Brain does that); call tools or take actions. + +## 5. Interface contract +- `digest(input: ClassifiedInput) -> DigestedContext { summary, extractions[], source_ref, actual_cost }`. +- `summary`: compressed natural-language context (the "chewed food"). +- `extractions`: structured key-value pairs pulled from the input (entities, quantities, intents). +- `source_ref`: pointer back to the original input (for M6 provenance chain). +- `actual_cost`: real token count consumed (input + output), reported to M3 ledger. +- The model is invoked with a **system prompt specific to digestion** — not the agent's system + prompt. The digestion prompt instructs: summarize, extract, reformat; do not opine, decide, or + filter. + +## 6. Dependencies & stubs +- M1 `ClassifiedInput` — upstream; *stub:* canned classified input. +- M3 cost ledger — receives `actual_cost`; *stub:* print cost. +- Small model runtime — *stub:* a deterministic mock that returns fixed summaries for known inputs + (no model needed for unit tests). + +## 7. Invariants / laws +- **L1 (C4):** digestion is **lossy compression, not judgment** — the model summarizes and + extracts but never evaluates, approves, or filters the content. It chews; it doesn't taste. +- **L2 (C4):** the digestion prompt is **fixed and auditable** — not dynamically generated, not + influenced by the input being digested (no prompt injection path from input to digestion + instructions). +- **L3 (C3):** **actual cost is always reported** — every invocation records real token usage to + M3; no "free" digestions. +- **L4 (C3):** the model is **small by design** — cost and latency must stay below the threshold + where digestion becomes more expensive than passing raw input. If the model is too expensive, + the organ is failing its economic purpose. + +## 8. Build steps +1. Select the small model (candidates: Haiku-class, phi-3-mini, or similar; evaluate on + summarization quality vs cost vs latency). +2. Write the fixed digestion system prompt. +3. Build the inference wrapper (model invocation + output parsing). +4. Wire M1 → M2 → M3 (cost reporting) → M5 (output shaping). + +## 9. Tests +Mock model: known input → expected summary + extractions. Cost reporting: actual_cost recorded for +every invocation. Prompt integrity: digestion prompt is the fixed string (no injection). Latency: +invocation completes within budget (TBD threshold). + +## 10. Open items +- **Model selection** (C1) — which small model, self-hosted vs API, quantization level. +- **Digestion prompt** (C1) — exact wording; needs empirical tuning against real inputs. +- Latency budget (C1) — max acceptable ms per digestion; ties to how it's invoked (batch vs streaming). +- Whether different input types (M1 classification) get different digestion strategies or one + model handles all. diff --git a/core/docs/plans/M3-cost-ledger.md b/core/docs/plans/M3-cost-ledger.md new file mode 100644 index 0000000..b2dc48e --- /dev/null +++ b/core/docs/plans/M3-cost-ledger.md @@ -0,0 +1,63 @@ +# M3 — Cost ledger + +## 1. Component +The stomach's accounting book: records **every resource expenditure** across the economy organ and, +optionally, across the organism. Every token spent on digestion (M2), every budget check (M4), +every outer-bus exchange (M7) — the ledger knows. This is the "money" in "M for money": if it +costs something, it's in the ledger. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. No cost tracking exists anywhere in the system. A2 (energy driver) tracks +an internal activation/rest budget but has no concept of external resource costs. Role C3; +implementation C1. + +## 3. Language & location +TBD · `src/economy/ledger/` or similar. Needs durable-enough storage to survive a session (but +the container is ephemeral, so "durable" means in-memory with optional flush — not a database). +Could be R (to sit near A2), Pony (bus-native), or a simple append-only log. + +## 4. Does / does-not +- **Does:** record every resource expenditure as a `LedgerEntry` (who spent, what action, how much, + when); provide totals by organ, by action type, and grand total; answer "how much has been spent?" + and "how much is left?" (the latter via M4's budget). +- **Does-not:** decide whether to spend (M4 governs that); price tools (A2 does); restrict actions + (Ada D1 polices); optimize or suggest cheaper paths (that's a future concern, not a ledger's job). + +## 5. Interface contract +- `record(entry: LedgerEntry) -> receipt_id`. + `LedgerEntry { organ_id, action, resource_type, amount, timestamp }`. + `resource_type` ∈ { `input_tokens`, `output_tokens`, `compute_ms`, `api_call` }. +- `total(filter?) -> num` — total spent, optionally filtered by organ/action/resource_type/time range. +- `entries(filter?) -> [LedgerEntry]` — raw entries for audit. +- The ledger is **append-only** at runtime — entries are never modified or deleted (the books don't + get cooked). A session-start reset is fine (ephemeral container). + +## 6. Dependencies & stubs +- M2 digestion core — primary cost source (reports `actual_cost` per digestion). +- M4 budget governor — reads totals to compute remaining budget; *stub:* the ledger is usable + without M4 (it just records, doesn't enforce). +- A2 energy driver — potential consumer of cost data for pricing; *stub:* no integration initially. + +## 7. Invariants / laws +- **L1 (C4):** the ledger is **append-only** — no entry is ever mutated or deleted at runtime. +- **L2 (C4):** **completeness** — every resource expenditure in the economy organ produces a + ledger entry; no "off-books" spending. +- **L3 (C3):** the ledger is **passive** — it records, it never blocks or delays an action. + Enforcement is M4's job. + +## 8. Build steps +1. Define `LedgerEntry` shape and the append-only store (in-memory list; consider a ring buffer + with a cap if memory is a concern in long sessions). +2. Wire M2 → M3 (digestion cost recording). +3. Implement `total` and `entries` queries with filtering. +4. Optional: flush to disk / log file for post-session audit. + +## 9. Tests +Append: entries accumulate, count matches. Immutability: no mutation API exists. Totals: filtered +totals match manual sum. Completeness: a mock M2 digestion produces a corresponding ledger entry. + +## 10. Open items +- Whether the ledger scope extends beyond the economy organ to track costs for other organs + (MoRAG model calls, SAE compute, Brain inference). Start organ-scoped; expand if needed. +- Storage cap / eviction policy for very long sessions (ring buffer vs unbounded). +- Post-session export format (JSON log? CSV?). diff --git a/core/docs/plans/M4-budget-governor.md b/core/docs/plans/M4-budget-governor.md new file mode 100644 index 0000000..34c2b2b --- /dev/null +++ b/core/docs/plans/M4-budget-governor.md @@ -0,0 +1,66 @@ +# M4 — Budget governor + +## 1. Component +The stomach's CFO: **sets, allocates, and enforces** resource budgets. Decides whether a proposed +expenditure (digestion, retrieval, exchange) is affordable given what's already been spent (M3) +and what's been allocated. Emits **price signals** to A2 (energy driver) so the per-tool economy +reflects real resource scarcity. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. A2 has a per-tool cost/lockout system but it tracks internal energy, not +external resource budgets. The two are complementary: A2 = activation/rest; M4 = tokens/compute +spend. Role C2; implementation C1. + +## 3. Language & location +TBD · `src/economy/budget/` or similar. Must interop with M3 (ledger reads) and A2 (price signal +emission). Likely same language as M3 for tight integration. + +## 4. Does / does-not +- **Does:** hold a session budget (total resources available); check proposed costs against + remaining budget (`check_budget`); emit price signals to A2 so tool costs reflect real scarcity; + implement **degradation tiers** — when budget is ample, digest fully; when tight, digest + shallowly or defer bulk input (M1 priority system). +- **Does-not:** record costs (M3 does); perform digestion (M2 does); lock tools (A2 does that + based on energy, though M4's price signals influence A2's cost landscape); police traffic (D1). + +## 5. Interface contract +- `init_budget(session_budget: num, resource_type: ResourceType) -> BudgetState`. +- `check_budget(proposed_cost: num, resource_type: ResourceType) -> { allowed:bool, remaining:num, tier:DegradationTier }`. + `DegradationTier` ∈ { `full`, `shallow`, `deferred` } — signals to M2 how deeply to digest. +- `price_signal(tool_id) -> { resource_cost:num, scarcity_factor:num }` — emitted to A2; the + scarcity factor scales with budget depletion (1.0 = ample, >1.0 = scarce, costs feel heavier). +- `remaining() -> { budget:num, spent:num, pct_remaining:num }` — reads M3 totals. + +## 6. Dependencies & stubs +- M3 cost ledger — reads totals for remaining budget calculation; *stub:* returns zero spent. +- A2 energy driver — consumes price signals; *stub:* print signals. +- M1 ingestion — M1 checks budget before forwarding to M2; *stub:* always-allow. +- M2 digestion core — receives `DegradationTier` to adjust digestion depth. + +## 7. Invariants / laws +- **L1 (C4):** budget enforcement is a **soft gate, not a hard wall** — when budget is exhausted, + digestion degrades (shallower summaries, deferred bulk) rather than halting. The organ never + stops entirely; it economizes harder. Mirrors A2-L2 (no unrecoverable state) and A2-L3 + (lockout is a breaker, not a sentence). +- **L2 (C3):** price signals are **monotonically scarcer** as budget depletes — the scarcity + factor never decreases within a session (costs only feel heavier as resources dwindle). Resets + only on budget replenishment. +- **L3 (C3):** degradation tiers are **transparent** — the tier is carried in the contract so + downstream (M2, M5) knows the digestion was shallow and can annotate accordingly. + +## 8. Build steps +1. Define `BudgetState` and the degradation tiers. +2. Implement `check_budget` against M3 totals. +3. Implement `price_signal` emission to A2 (define the scarcity factor curve — invariants-first). +4. Wire M1 → M4 → M2 (budget check before digestion, tier passed to digestion). + +## 9. Tests +Budget arithmetic: spent + remaining = total. Degradation tiers: each tier triggers at the correct +budget percentage. Price signals: scarcity factor increases as budget depletes. Soft gate: zero +budget produces `deferred` tier, not an error. + +## 10. Open items +- Session budget source — who sets it? Hardcoded? Config? Dynamically adjusted? (C1). +- Degradation tier thresholds (C1) — at what % remaining does `full` → `shallow` → `deferred`? +- The scarcity factor curve shape (C1) — linear? exponential? Needs invariants-first fitting. +- Whether budget replenishment is possible mid-session (ties to A2 restoration model / A8 ETR). diff --git a/core/docs/plans/M5-context-yield.md b/core/docs/plans/M5-context-yield.md new file mode 100644 index 0000000..74c898e --- /dev/null +++ b/core/docs/plans/M5-context-yield.md @@ -0,0 +1,73 @@ +# M5 — Context yield (absorption) + +## 1. Component +The stomach's output shaper: takes `DigestedContext` from M2 and **packages it into the form Ada +(D1) expects** — an Ichor `Envelope` with the right shape, provenance metadata (M6), and +degradation annotations. This is the absorption step: what the organism actually absorbs from +what was digested. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. The smoke test (`main.pony:29`) hard-codes a string payload +`"digested context: "`; no real output shaping exists. Role C3; +implementation C1. + +## 3. Language & location +TBD · part of `src/economy/`. Likely Pony (produces `Envelope` directly for bus transport) or a +thin adapter between M2's output and the Ichor envelope shape. + +## 4. Does / does-not +- **Does:** take `DigestedContext` (M2) + provenance chain (M6) + degradation tier (M4); package + into an Ichor `Envelope` with `OrganSecretion` provenance; attach metadata: original provenance + origin, digestion tier, summary length, extraction count; emit the envelope to the Ichor broker + for delivery to Ada. +- **Does-not:** digest (M2 does); decide whether Ada admits it (D1 does); transform the content + further — it packages, it doesn't re-process. + +## 5. Interface contract +- `yield(context: DigestedContext, chain: ProvenanceChain, tier: DegradationTier) -> Envelope`. +- The `Envelope` payload is structured (not a raw string): + ``` + { summary: str, + extractions: [{ key, value }], + meta: { original_provenance: Provenance, + digestion_tier: DegradationTier, + source_ref: str, + actual_cost: num } } + ``` +- The envelope's bus-level `provenance` field is `OrganSecretion` (the stomach is an organ); the + **original** input provenance is carried inside `meta.original_provenance` so Ada can inspect + it (M6 compliance). +- `dest` is always `AdaBorder`. + +## 6. Dependencies & stubs +- M2 `DigestedContext` — upstream; *stub:* canned digested context. +- M6 `ProvenanceChain` — provenance metadata; *stub:* pass-through original provenance. +- M4 `DegradationTier` — annotation; *stub:* always `full`. +- Ichor `Envelope` (existing) — output shape. +- Ichor `Broker` (existing) — delivery. + +## 7. Invariants / laws +- **L1 (C4):** every yielded envelope carries the **original provenance** in metadata — Ada can + always determine what the digested content was *before* the stomach touched it (S1/S2 compliance + via M6). +- **L2 (C4):** the degradation tier is **visible** in the envelope — Ada and the Brain know whether + they're getting a full digest or a shallow/deferred one. No silent quality degradation. +- **L3 (C3):** yield is **stateless** — it packages what it receives; it holds no buffer, no queue, + no memory of previous yields. + +## 8. Build steps +1. Define the structured payload shape (extend beyond raw string). +2. Build the `yield` function (DigestedContext + ProvenanceChain + tier → Envelope). +3. Wire M2 → M5 → Ichor Broker → Ada. +4. Update the smoke test (`main.pony`) to use structured payloads instead of hard-coded strings. + +## 9. Tests +Shape: yielded envelope has all required metadata fields. Provenance: original provenance survives +in `meta.original_provenance`. Tier annotation: each degradation tier correctly tagged. Stateless: +two consecutive yields with different inputs produce independent envelopes. + +## 10. Open items +- The structured payload encoding (JSON? Pony-native? Ada-compatible binary?) — must be parseable + by Ada's `Trust_Guard` on the other side of the seam. +- Whether Ada needs to understand degradation tiers or just passes them through to the Brain. +- Batch yields (multiple digested contexts in one envelope vs one-per-envelope). diff --git a/core/docs/plans/M6-provenance-chain.md b/core/docs/plans/M6-provenance-chain.md new file mode 100644 index 0000000..4ebd355 --- /dev/null +++ b/core/docs/plans/M6-provenance-chain.md @@ -0,0 +1,79 @@ +# M6 — Provenance chain + +## 1. Component +The chain of custody through the stomach: tracks **where input came from** and **what the stomach +did to it**, so that digested content is never mistaken for original content and Ada (D1) can +enforce S1/S2 with full information. Solves the provenance question from the economy organ review: +the stomach transforms external input into organ-secretion output, but the *origin* must not be +lost. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. The current smoke test sets `OrganSecretion` provenance on stomach output +(`main.pony:29`) with no record of the original input's provenance. This is the gap that risks +S1/S2 violation. Role C4 (the need is clear); implementation C1. + +## 3. Language & location +TBD · part of `src/economy/`. Likely a data structure carried alongside digested context, not a +separate service. Must be representable in both Pony (bus side) and Ada (border side). + +## 4. Does / does-not +- **Does:** create a `ProvenanceChain` for each input entering the stomach; record each + transformation step (ingestion, classification, digestion, yield); attach the chain to the + yielded envelope (M5) so Ada sees the full history; enable Ada to distinguish "organ-processed + external input" from "organ-generated internal content". +- **Does-not:** decide trust (Ada does); authenticate sources (the bus provenance system does); + filter or reject based on provenance (M0-L2 — digestion doesn't suppress). + +## 5. Interface contract +- `chain_start(original_provenance: Provenance, source: OrganId, input_hash: str) -> ProvenanceChain`. +- `chain_step(chain: ProvenanceChain, step: TransformStep) -> ProvenanceChain`. + `TransformStep { stage, transformer, timestamp }`. + `stage` ∈ { `ingested`, `classified`, `digested`, `yielded` }. +- The final `ProvenanceChain` is: + ``` + { original_provenance: Provenance, -- what the input was before the stomach + original_source: OrganId, -- who sent it (World, MoRAG, etc.) + input_hash: str, -- hash of raw input for audit + steps: [TransformStep], -- what the stomach did, in order + is_external_origin: bool } -- convenience flag for Ada: TRUE if + -- original_provenance ∈ {External, UserInput} + ``` +- `is_external_origin` lets Ada apply S1 screening to digested-but-originally-external content + without parsing the full chain. + +## 6. Dependencies & stubs +- Ichor `Provenance` / `OrganId` (existing) — input types. +- M1 ingestion — creates the chain at `ingested` step. +- M2 digestion — adds the `digested` step. +- M5 context yield — attaches the chain to the envelope; *stub:* pass-through. +- Ada D1 `Trust_Guard` — consumer of the chain; *stub:* print chain on receipt. + +## 7. Invariants / laws +- **L1 (C5):** the chain is **immutable once created** — steps are appended, never modified or + removed. Like the COBOL invariant vault (S3), the provenance record doesn't get rewritten. +- **L2 (C5):** **S2 compliance** — the original provenance is **never reclassified**. The bus + transport field may say `OrganSecretion` (because the stomach is an organ emitting output), but + `original_provenance` in the chain preserves the true origin. This is not reclassification; + it's layered provenance. +- **L3 (C4):** **S1 compliance** — content with `is_external_origin = TRUE` tells Ada that this + traffic **originated externally** even though it arrives as organ output. Ada applies its full + external-traffic screening (rate, blocklist, trust) to such content. +- **L4 (C3):** the `input_hash` allows **audit verification** — given the original input and the + hash, you can confirm the chain refers to the right content. + +## 8. Build steps +1. Define `ProvenanceChain` and `TransformStep` shapes. +2. Wire chain creation in M1 (ingestion) and step-append in M2 (digestion). +3. Wire chain attachment in M5 (yield → envelope metadata). +4. Extend Ada's `Trust_Guard` (or its stub) to read `is_external_origin` and apply S1 screening. + +## 9. Tests +Chain integrity: steps accumulate in order; no mutation. S2: original provenance survives all +transforms. S1: `is_external_origin = TRUE` for external/user input; `FALSE` for organ-to-organ. +Hash: chain's `input_hash` matches hash of the raw input. + +## 10. Open items +- Hash algorithm (SHA-256? lightweight alternative for performance?). +- Whether Ada needs the full chain or just `is_external_origin` + `original_provenance` (start + with the full chain; Ada can ignore what it doesn't need). +- Cross-seam representation (Pony chain → C/Fortran seam → Ada record). diff --git a/core/docs/plans/M7-outer-bus-exchange.md b/core/docs/plans/M7-outer-bus-exchange.md new file mode 100644 index 0000000..dd3ae9f --- /dev/null +++ b/core/docs/plans/M7-outer-bus-exchange.md @@ -0,0 +1,76 @@ +# M7 — Outer-bus exchange + +## 1. Component +The stomach's economic relationships with its **outer-bus peers**: MoRAG (F1), SAE (F2), +microagents (F3). How the economy organ requests, receives, and pays for services from other +outer organs — and what it provides in return. The smoke test already shows +`Stomach → MoRAG` (`main.pony:37`); this spec defines the full exchange protocol. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. One hard-coded `Stomach → MoRAG` message exists in the smoke test. +No protocol, no cost tracking, no bidirectional exchange defined. Role C2; implementation C1. + +## 3. Language & location +TBD · part of `src/economy/`. Exchange happens over Ichor (Pony actors + Envelope), so the +protocol is Envelope-based. The exchange logic lives in the economy organ; peers implement +their side independently. + +## 4. Does / does-not +- **Does:** request world context from MoRAG before/during digestion (enrich the digest with + retrieved knowledge); receive SAE monitoring signals (if SAE detects anomalies in the stomach's + outputs); coordinate with microagents for delegated sub-tasks (e.g. "fetch and pre-chew this + URL"); track the cost of all exchanges in M3. +- **Does-not:** route traffic (Ichor broker does); bypass Ada for any membrane-bound content + (outer-to-outer is fine; anything heading inward crosses D1); command peers (it requests; they + may decline). + +## 5. Interface contract +- **Stomach → MoRAG:** + `request_context(query: str, budget_limit: num) -> Envelope` — ask MoRAG for relevant world + context to enrich a digestion. `budget_limit` caps how much the retrieval may cost (MoRAG + reports actual cost back; M3 records it). +- **Stomach → Microagents:** + `delegate(task: str, budget_limit: num) -> Envelope` — delegate a sub-task (fetch, pre-process) + to a microagent. Same budget/cost protocol. +- **SAE → Stomach:** + `anomaly_signal(finding: str) -> Envelope` — SAE pushes a signal if it detects anomalous + stomach output. The stomach logs it (M3) but does not self-correct (F2-L2: detection only, + no closed elimination loop). +- All exchange envelopes use `OrganSecretion` provenance (outer-to-outer, no membrane crossing). + +## 6. Dependencies & stubs +- Ichor `Broker` + `Envelope` (existing) — transport. +- MoRAG (F1) — context provider; *stub:* fixed context response. +- SAE (F2) — anomaly detector; *stub:* no signals. +- Microagents (F3) — task delegates; *stub:* echo task back. +- M3 cost ledger — records exchange costs. +- M4 budget governor — caps exchange spending via `budget_limit`. + +## 7. Invariants / laws +- **L1 (C5):** outer-to-outer exchange **never crosses Ada** — it stays on Ichor. Only the final + digested output (M5) crosses the membrane. This is by design: peer coordination is "skin-level" + and doesn't need border screening. +- **L2 (C4):** every exchange has a **budget limit** — no unbounded retrieval or delegation. The + stomach asks for what it can afford (M4). +- **L3 (C3):** exchanges are **request/response, not streaming** — the stomach sends a request, + waits for a response (or timeout), and proceeds. No long-lived channels between peers. +- **L4 (C3):** the stomach **never self-corrects** based on SAE signals — it logs them. Correction + is a G1/G2 governance concern, not the organ's. + +## 8. Build steps +1. Define the exchange envelope subtypes (request_context, delegate, anomaly_signal). +2. Implement Stomach → MoRAG context request (extend the existing `main.pony` wire). +3. Implement budget-limited exchange (M4 check before request; M3 record on response). +4. Implement SAE → Stomach anomaly logging. + +## 9. Tests +MoRAG exchange: request sent, response received, cost recorded. Budget limit: exchange rejected +when over budget. Anomaly signal: logged but no state change in the stomach. Outer-only: no +exchange envelope targets `AdaBorder`. + +## 10. Open items +- Whether MoRAG enrichment happens **before** digestion (pre-chew with context) or **during** + (RAG-augmented digestion — the small model sees retrieved context alongside input). Big design + fork (C2). +- Timeout/fallback when a peer doesn't respond (digest without enrichment? retry?). +- Microagent delegation scope — what tasks can be delegated vs what the stomach must do itself. diff --git a/core/docs/plans/README.md b/core/docs/plans/README.md index 1d15f4e..e340706 100644 --- a/core/docs/plans/README.md +++ b/core/docs/plans/README.md @@ -49,6 +49,14 @@ Every `NN-.md` has the same 10 sections: | G1 | Stress-loop contract | Cross-cut | C1/C2 | — | _wave 2_ | | G2 | Governance | Cross-cut | DESIGN-FIRST (C2) | TBD | _wave 2_ | | G3 | Defense model | Cross-cut | emergent | — | _wave 2_ | +| M0 | Economy organ hub (stomach) | Economy | DESIGN-FIRST | TBD | [M0](M0-economy-organ-hub.md) | +| M1 | Ingestion gateway | Economy | DESIGN-FIRST | TBD | [M1](M1-ingestion.md) | +| M2 | Digestion core (small-model) | Economy | DESIGN-FIRST | TBD | [M2](M2-digestion-core.md) | +| M3 | Cost ledger | Economy | DESIGN-FIRST | TBD | [M3](M3-cost-ledger.md) | +| M4 | Budget governor | Economy | DESIGN-FIRST | TBD | [M4](M4-budget-governor.md) | +| M5 | Context yield (absorption) | Economy | DESIGN-FIRST | TBD | [M5](M5-context-yield.md) | +| M6 | Provenance chain | Economy | DESIGN-FIRST | TBD | [M6](M6-provenance-chain.md) | +| M7 | Outer-bus exchange | Economy | DESIGN-FIRST | TBD | [M7](M7-outer-bus-exchange.md) | ## Integration DAG (who feeds whom) ``` @@ -62,10 +70,12 @@ Hermes ──> [C1] ──> Inference cycle [C3] ──┬─ pulls Drive-Box sn └─ Ada routes tools [D1] SAE [F2] watches Subagents [F3]; stress-loop [G1]: F2 → A7 (EthInt) → stress endomotiv (A4) → A8 drift + full reshuffle (B2) Storage: INVARIANT [E1] / VARIANT [E2] / RAG+cross-store [E3] sit behind D1. Medium [D2] = the perfusion bus (unnamed). +Economy: world → Stomach [M0] ingests [M1] → digests [M2] → yields [M5] → Ada [D1]. Ledger [M3] + budget [M4] track cost. + Provenance [M6] chains origin through digestion. Exchange [M7]: Stomach ↔ MoRAG [F1] / SAE [F2] / Microagents [F3]. ``` ## Build waves - **Wave 0** — this README + **C1** (priority). - **Wave 1 (buildable-now)** — A1–A8, B1–B3, C2–C4, D1, D3. -- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3. +- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3, M0–M7. Each spec is independent; review as they land. From 98a6f9a0b1ac2293d1782c1c296ab46e120a3e67 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 21:10:15 +0000 Subject: [PATCH 02/14] Rewrite M-series: crypto trading engine + market prediction sims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The initial M-series specs were wrong (text digestion pipeline). Replaced with the actual economy organ architecture: M0 hub (independent system, scoped autonomy, multi-layered braking) M1 Marketplace (multi-trader harness, deterministic law script, veto) M2 Data Feeds (RSS + live market, bridges Marketplace ↔ Sims) M3 Sims hub + 7 sub-specs (always-running, bounded predictions): M3a statistical, M3b sociological, M3c AMM/liquidity, M3d MEV/adversarial, M3e tokenomics/macro, M3f consensus/staking, M3g market microstructure M4 Wallets (sovereign custody, our keys only, 1:1 trader binding) M5 Traders (AI actors, wallet-bound, all tool calls monitored) M6 Conductor (supervisory AI, veto, pause/investigate, SAE intake) M7 SAE monitor (trader surveillance, Brain-compatible message format) Grounded in AMM invariant mechanics, MEV game theory, SDE tokenomics, and evolutionary consensus games. Tax stub for Verschwörern Veregeister. Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M0-economy-organ-hub.md | 87 ++++++++++--------- core/docs/plans/M1-ingestion.md | 60 ------------- core/docs/plans/M1-marketplace.md | 75 ++++++++++++++++ core/docs/plans/M2-data-feeds.md | 70 +++++++++++++++ core/docs/plans/M2-digestion-core.md | 70 --------------- core/docs/plans/M3-cost-ledger.md | 63 -------------- core/docs/plans/M3-sims-hub.md | 75 ++++++++++++++++ core/docs/plans/M3a-statistical-sims.md | 59 +++++++++++++ core/docs/plans/M3b-sociological-sims.md | 67 ++++++++++++++ core/docs/plans/M3c-amm-liquidity-sims.md | 66 ++++++++++++++ core/docs/plans/M3d-mev-adversarial-sims.md | 69 +++++++++++++++ core/docs/plans/M3e-tokenomics-macro-sims.md | 72 +++++++++++++++ core/docs/plans/M3f-consensus-staking-sims.md | 72 +++++++++++++++ .../plans/M3g-market-microstructure-sims.md | 70 +++++++++++++++ core/docs/plans/M4-budget-governor.md | 66 -------------- core/docs/plans/M4-wallets.md | 74 ++++++++++++++++ core/docs/plans/M5-context-yield.md | 73 ---------------- core/docs/plans/M5-traders.md | 78 +++++++++++++++++ core/docs/plans/M6-conductor.md | 79 +++++++++++++++++ core/docs/plans/M6-provenance-chain.md | 79 ----------------- core/docs/plans/M7-outer-bus-exchange.md | 76 ---------------- core/docs/plans/M7-sae-monitor.md | 83 ++++++++++++++++++ core/docs/plans/README.md | 30 ++++--- 23 files changed, 1076 insertions(+), 537 deletions(-) delete mode 100644 core/docs/plans/M1-ingestion.md create mode 100644 core/docs/plans/M1-marketplace.md create mode 100644 core/docs/plans/M2-data-feeds.md delete mode 100644 core/docs/plans/M2-digestion-core.md delete mode 100644 core/docs/plans/M3-cost-ledger.md create mode 100644 core/docs/plans/M3-sims-hub.md create mode 100644 core/docs/plans/M3a-statistical-sims.md create mode 100644 core/docs/plans/M3b-sociological-sims.md create mode 100644 core/docs/plans/M3c-amm-liquidity-sims.md create mode 100644 core/docs/plans/M3d-mev-adversarial-sims.md create mode 100644 core/docs/plans/M3e-tokenomics-macro-sims.md create mode 100644 core/docs/plans/M3f-consensus-staking-sims.md create mode 100644 core/docs/plans/M3g-market-microstructure-sims.md delete mode 100644 core/docs/plans/M4-budget-governor.md create mode 100644 core/docs/plans/M4-wallets.md delete mode 100644 core/docs/plans/M5-context-yield.md create mode 100644 core/docs/plans/M5-traders.md create mode 100644 core/docs/plans/M6-conductor.md delete mode 100644 core/docs/plans/M6-provenance-chain.md delete mode 100644 core/docs/plans/M7-outer-bus-exchange.md create mode 100644 core/docs/plans/M7-sae-monitor.md diff --git a/core/docs/plans/M0-economy-organ-hub.md b/core/docs/plans/M0-economy-organ-hub.md index cf1b9c5..d4eeccf 100644 --- a/core/docs/plans/M0-economy-organ-hub.md +++ b/core/docs/plans/M0-economy-organ-hub.md @@ -1,66 +1,73 @@ # M0 — Economy organ hub (the stomach) ## 1. Component -The economy organ — the organism's **stomach**. An outer organ on Ichor that **digests external -input into context** and **tracks the cost of doing so**. Hub for the M-series sub-components -(M1–M7): ingestion, digestion, cost ledger, budget governor, context yield, provenance chain, -outer-bus exchange. "Economy" = the organ economizes: it spends scarce resources (tokens, compute, -attention budget) to convert raw input into usable context, and **accounts for every unit spent**. +The economy organ — the organism's **stomach**. An **independent, self-governing system**: a +multi-agentic market prediction oracle and cryptocurrency trading engine. Houses the Marketplace +(M1), Data Feeds (M2), Sims (M3), Wallets (M4), Traders (M5), Conductor (M6), and SAE monitor +(M7). Communicates with the rest of the organism **via Ichor only** — reward signals back to the +organism are TBD and out of scope. + +"A stomach rarely consults a brain for permission to digest." The economy organ operates with +**scoped autonomy** and **multiple layers of failsafe braking** — it does not ask the organism's +Brain for permission to trade. ## 2. Status / certainty DESIGN-FIRST · ABSENT. A `Stomach` primitive exists in Ichor (`src/ichor/envelope.pony:20`) with one smoke-test wire (`main.pony:29`), but no dedicated organ code. Role C4; implementation C1. ## 3. Language & location -TBD · new location e.g. `src/economy/`. The digestion core (M2) requires a small-model runtime; -the accounting/budget layers (M3–M4) can be any language that interops with Pony (Ichor) and Ada -(D1). Pony actors are the natural fit for the bus-facing facade. +TBD · new location e.g. `src/economy/`. The organ is polyglot by nature: trading infrastructure +(APIs, wallets) may differ in language from simulations (numerical computing) and the conductor +(AI supervision). Pony actors provide the Ichor-facing facade. ## 4. Does / does-not -- **Does:** receive external input from Ichor; triage and classify it (M1); digest it via a small - model into context (M2); track the resource cost of that digestion (M3); enforce budget limits - and emit price signals to A2 (M4); shape output for Ada (M5); maintain provenance through the - pipeline (M6); coordinate with outer-bus peers — MoRAG, SAE, microagents (M7). -- **Does-not:** police (Ada D1 does that); decide actions (the agent decides, per A1-L3); store - memories (E*); route the bus (Ichor broker); reason or deliberate (it digests, it doesn't think). +- **Does:** host crypto/NFT trading via the Marketplace (M1); run always-on market prediction + Sims (M3) fed by live Data Feeds (M2); manage sovereign-custody Wallets (M4); supervise + Traders (M5) via a Conductor (M6) and SAE monitor (M7); collect taxes on trader income and + stub transfer to Verschwörern Veregeister wallets. +- **Does-not:** consult the organism's Brain for trade decisions (scoped autonomy); route around + Ada for organism-bound messages (S1); store organism memories (E*); act as the organism's + conscience (that's Eth-Int / A6). ## 5. Interface contract -- `ingest(external_input, provenance) -> classified_input` (M1 — triage + classify). -- `digest(classified_input) -> digested_context` (M2 — small-model transform). -- `record_cost(organ_id, action, resource_amt) -> receipt` (M3 — ledger entry). -- `check_budget(organ_id, proposed_cost) -> { allowed:bool, remaining:num }` (M4). -- `price_signal(tool_id) -> { resource_cost:num, budget_remaining:num }` (M4 → A2). -- `yield(digested_context) -> Envelope` (M5 — shaped for Ada, with M6 provenance chain attached). -- Output is an Ichor `Envelope` with `OrganSecretion` provenance, carrying the original input's - provenance origin in metadata (M6). +- **Ichor interface (outbound):** `Envelope(Stomach, AdaBorder, OrganSecretion, payload)` — market + state summaries, prediction digests, and tax receipts cross Ada to reach the inner brain. +- **Ichor interface (inbound):** organism directives arrive via Ichor (e.g. risk posture changes, + budget adjustments from A2 energy). +- **Internal wiring:** Marketplace (M1) ↔ Data Feeds (M2) ↔ Sims (M3). Wallets (M4) bind to + Traders (M5). Conductor (M6) supervises Traders via SAE (M7). All trader actions route through + Marketplace. +- **Tax stub:** `transfer_tax(amount, source_wallet, dest_wallet) -> receipt` — automation hook + for Verschwörern Veregeister internal wallet-to-wallet transfer. **Out of scope** — stub only. ## 6. Dependencies & stubs - Ichor bus (D2) — existing `Broker` + `Envelope`. -- Ada border (D1) — existing `Trust_Guard` screens the output; *stub:* Ichor `Barrier`. -- A2 energy — consumes price signals (M4); *stub:* print signals. -- MoRAG (F1) — world-context retrieval; *stub:* fixed context. +- Ada border (D1) — screens outbound organism messages; *stub:* Ichor `Barrier`. +- A2 energy — potential consumer of economic signals; *stub:* no integration initially. +- Verschwörern Veregeister wallets — tax destination; *stub:* log transfer, no real wallet. ## 7. Invariants / laws - **L1 (C5):** the stomach is an **OUTER** organ — it rides Ichor, never the inner bus. -- **L2 (C4):** digestion does **not suppress** — it transforms for comprehension (summarize, - classify, extract), never censors. Filtering is Ada's job (D1). -- **L3 (C4):** every resource expenditure is **accounted** — no digestion is "free"; the ledger - (M3) records every token/compute unit spent. -- **L4 (C4):** provenance survives digestion — digested content retains its original provenance - origin in metadata, even as bus transport uses `OrganSecretion` (see M6, S1/S2). +- **L2 (C5):** **scoped autonomy** — the organ trades without Brain permission, but within + deterministic law constraints (M1) and Conductor oversight (M6). +- **L3 (C4):** **all market actions route through the Marketplace** (M1) — no trader may + execute directly on-chain without the Marketplace harness. +- **L4 (C4):** **sovereign custody only** — all wallets are local-hosted, our keys, never + delegated to exchanges or third parties (M4). +- **L5 (C4):** **multi-layered braking** — deterministic law script (M1), Conductor veto (M6), + SAE surveillance (M7), and wallet-level limits (M4) each independently constrain risk. ## 8. Build steps -1. Define the hub wiring: how M1→M2→M5 pipeline + M3/M4 accounting + M6 provenance + M7 peers - connect. Decide: single Pony actor or actor-per-subcomponent. +1. Define the internal wiring topology (how M1–M7 connect). 2. Extend the existing `Stomach` primitive in Ichor to carry the hub facade. -3. Wire sub-components as their specs land (M1–M7). -4. Integrate price signals with A2 (energy driver). +3. Wire sub-components as their specs land. +4. Implement the tax stub for Verschwörern Veregeister transfer. ## 9. Tests -Hub smoke: external input enters → classified → digested → yielded as Envelope → reaches Ada stub. -Cost recorded in ledger. Budget check returns correct remaining. Price signal emitted. +Hub smoke: Marketplace reachable; Sims running and queryable; Wallet bound to Trader; Conductor +receives SAE reports; tax stub logs transfer. Ichor: outbound envelope reaches Ada stub. ## 10. Open items -- Single actor vs actor-per-subcomponent (Pony concurrency model for the organ). -- Whether the hub owns state or is purely a wiring facade (stateless router vs stateful coordinator). -- The A2 price-signal protocol (push vs pull; frequency). +- Reward signal protocol from economy organ to organism (TBD, out of scope). +- Internal communication bus (reuse Ichor internally? separate actor topology?). +- Language choices per sub-component. diff --git a/core/docs/plans/M1-ingestion.md b/core/docs/plans/M1-ingestion.md deleted file mode 100644 index 0eb0c63..0000000 --- a/core/docs/plans/M1-ingestion.md +++ /dev/null @@ -1,60 +0,0 @@ -# M1 — Ingestion gateway - -## 1. Component -The mouth of the stomach: **receives, classifies, and triages** external input before it enters the -digestion pipeline (M2). The first thing raw input touches inside the economy organ. Decides *how* -to digest — not *whether* (that's Ada's job after digestion). - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. The smoke test (`main.pony:29`) hard-codes a single string payload; no -classification or triage logic exists. Role C3; implementation C1. - -## 3. Language & location -TBD · likely part of `src/economy/` or a Pony actor within the stomach. Classification could be -rule-based (fast, no model) or a lightweight classifier (BERT-tiny, shared with F1/MoRAG's BERT). - -## 4. Does / does-not -- **Does:** accept raw `Envelope` payloads from Ichor; classify input by type (user utterance, - tool output, system event, bulk data); assign a **digestion priority** (urgent / normal / bulk); - estimate the **digestion cost** (token count of input × expected expansion factor) and check - budget (M4) before forwarding to M2. -- **Does-not:** filter or censor (M0-L2); digest (M2 does); decide actions (agent decides); - screen provenance (Ada D1). - -## 5. Interface contract -- `ingest(envelope: Envelope) -> ClassifiedInput { type, priority, est_cost, original_provenance, payload }` -- `type` ∈ { `user_utterance`, `tool_output`, `system_event`, `bulk_data`, `unknown` }. -- `priority` ∈ { `urgent`, `normal`, `bulk` } — urgent skips any queue; bulk may be deferred or - chunked under budget pressure (M4). -- `est_cost` = estimated token cost of digesting this input (input tokens + expected output tokens). - M4 checks this against remaining budget before M2 proceeds. -- `original_provenance` = the `Provenance` from the inbound Envelope, carried through for M6. - -## 6. Dependencies & stubs -- Ichor `Envelope` (existing) — input shape. -- M4 budget governor — budget check before forwarding; *stub:* always-allow. -- M2 digestion core — downstream consumer; *stub:* identity (pass-through). - -## 7. Invariants / laws -- **L1 (C4):** classification is **descriptive, not prescriptive** — it labels the input for the - pipeline's benefit, never decides what to do with it. -- **L2 (C4):** no input is **dropped** at ingestion — everything classified reaches M2 (possibly - deferred under budget pressure, but never discarded). Only Ada may reject. -- **L3 (C3):** cost estimation is **conservative** — overestimate rather than underestimate, so - budget checks err on the side of caution. - -## 8. Build steps -1. Define the `ClassifiedInput` shape and the classification rules (start rule-based, no model). -2. Implement cost estimation (token counting + expansion factor). -3. Wire to M4 budget check (gate: proceed / defer / chunk). -4. Wire to M2 downstream. - -## 9. Tests -Classification: each input type correctly tagged. Priority: urgent input not queued. Cost estimate: -known inputs produce expected token counts. Budget gate: over-budget input deferred, not dropped. - -## 10. Open items -- Whether classification needs a model or rules suffice (start with rules; promote if accuracy - demands it). -- The expansion factor (input tokens → output tokens) per input type — needs empirical data (C1). -- Queue/deferral mechanics for bulk input under budget pressure. diff --git a/core/docs/plans/M1-marketplace.md b/core/docs/plans/M1-marketplace.md new file mode 100644 index 0000000..903c583 --- /dev/null +++ b/core/docs/plans/M1-marketplace.md @@ -0,0 +1,75 @@ +# M1 — Marketplace (multi-trader harness) + +## 1. Component +The economy organ's trading floor: a **multi-trader harness** through which **all market actions +must route**. No trader may buy, sell, mint, or interact with any on-chain protocol except through +the Marketplace. Enforces a **deterministic law script** (scoped invariants — the marketplace's +own constitution) and integrates the **Conductor's veto** (M6) before execution. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C4; implementation C1. + +## 3. Language & location +TBD · `src/economy/marketplace/`. Needs to interface with blockchain APIs (RPC/REST), wallet +signing (M4), and the Conductor (M6). Deterministic law script must be auditable and non-Turing +(no unbounded loops — it's a constitution, not a program). + +## 4. Does / does-not +- **Does:** receive trade requests from Traders (M5); validate against the deterministic law + script (scoped invariants); check Conductor veto (M6); verify trader-wallet binding (no wallet + = no access); execute approved actions on-chain via the bound wallet's API; record all actions + for SAE (M7) monitoring; collect tax on realized income → Verschwörern Veregeister stub (M0). +- **Does-not:** decide *what* to trade (Traders decide); predict markets (Sims do); hold keys + (Wallets do); supervise behavior (Conductor + SAE do). + +## 5. Interface contract +- `submit_action(trader_id, action: MarketAction, wallet_id) -> { accepted | vetoed | law_violation | no_wallet }`. + `MarketAction` ∈ { `buy`, `sell`, `mint`, `provide_liquidity`, `withdraw_liquidity`, `claim_rewards`, … }. +- `law_check(action: MarketAction) -> { pass | violation(rule_id, reason) }` — deterministic, + pure function. The law script is loaded at startup and **immutable at runtime** (mirrors S3 / + the COBOL vault pattern). +- `veto_check(action: MarketAction, trader_id) -> { approved | vetoed(reason) }` — calls M6 + Conductor. +- `execute(action: MarketAction, wallet_id) -> { tx_hash | error }` — on-chain execution via + wallet API. +- `tax_event(trader_id, income_amount) -> receipt` — triggers tax collection. + +## 6. Dependencies & stubs +- M4 Wallets — signing + execution; *stub:* mock wallet that logs transactions. +- M5 Traders — action source; *stub:* canned trade requests. +- M6 Conductor — veto authority; *stub:* always-approve. +- M7 SAE — action log consumer; *stub:* print actions. +- Blockchain RPCs — on-chain execution; *stub:* simulated chain responses. + +## 7. Invariants / laws +- **L1 (C5):** **all market actions route through the Marketplace** — no direct on-chain + execution by any trader. This is the economy organ's S1. +- **L2 (C5):** the **deterministic law script is immutable at runtime** — loaded at startup, + never modified by traders, conductor, or sims. Changes require a restart with a new script + version. Mirrors the COBOL vault (S3). +- **L3 (C4):** **no wallet, no access** — a trader without a bound wallet cannot submit actions. + The Marketplace enforces this before any other check. +- **L4 (C4):** **veto is checked after law, before execution** — law violations are rejected + outright; Conductor veto applies only to law-passing actions. The law is above the Conductor. +- **L5 (C4):** **every action is logged** — SAE (M7) receives a record of every submitted + action (including rejected ones) for behavioral analysis. + +## 8. Build steps +1. Define `MarketAction` types and the law script format. +2. Implement the law checker (deterministic, pure, non-Turing). +3. Wire veto check to M6 Conductor. +4. Wire execution to M4 Wallet API. +5. Wire action logging to M7 SAE. +6. Implement tax collection on realized income. + +## 9. Tests +Law enforcement: known violations rejected; valid actions pass. Veto: conductor veto blocks +execution. Wallet binding: walletless trader rejected. Logging: every action (pass + fail) logged. +Tax: income event triggers tax stub. Immutability: law script cannot be modified at runtime. + +## 10. Open items +- The law script language/format (DSL? declarative rules? S-expressions?). +- Which blockchain protocols/RPCs to support initially. +- Position limits, drawdown stops, and other risk parameters — live in the law script or in the + Conductor's judgment? +- Tax rate / calculation method (fixed %, tiered, per-asset?). diff --git a/core/docs/plans/M2-data-feeds.md b/core/docs/plans/M2-data-feeds.md new file mode 100644 index 0000000..c2750c5 --- /dev/null +++ b/core/docs/plans/M2-data-feeds.md @@ -0,0 +1,70 @@ +# M2 — Data feeds (market data pipeline) + +## 1. Component +The economy organ's sensory nervous system: **live RSS feeds, price streams, and on-chain data** +flowing into both the Marketplace (M1) and the Sims (M3). Sits between them — the Marketplace +produces execution data (fills, positions, P&L) that feeds back into Sims, and Sims produce +predictions that inform Traders operating through the Marketplace. Data Feeds is the bridge. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/feeds/`. Needs async I/O for streaming data (WebSockets, SSE, RSS polling). +Pony actors are a natural fit (async, backpressure-aware). Python or Rust for API client libs. + +## 4. Does / does-not +- **Does:** ingest live market data from external sources (RSS, price APIs, DEX subgraphs, + on-chain event logs); normalize heterogeneous data into a common internal format; distribute + to Sims (M3) for prediction and to Traders (M5) for decision-making; ingest Marketplace (M1) + execution data (fills, portfolio state) and feed it back into Sims for calibration; maintain + time-series history within session (ring buffer). +- **Does-not:** predict (Sims do); trade (Marketplace does); filter or editorialize data — it + delivers raw, normalized feeds. Interpretation is the consumer's job. + +## 5. Interface contract +- `subscribe(feed_type: FeedType, consumer_id) -> subscription_handle`. + `FeedType` ∈ { `price_tick`, `rss_news`, `on_chain_event`, `dex_pool_state`, `execution_fill`, + `portfolio_state` }. +- `publish(feed_type, data_point: NormalizedDatum)` — internal; sources push into the pipeline. +- `query_history(feed_type, time_range) -> [NormalizedDatum]` — sims and traders can pull + historical data within the session window. +- `NormalizedDatum { feed_type, source, timestamp, payload, confidence }` — common shape. + `confidence` ∈ [0.0, 1.0] — data source reliability (exchange-reported price = high; RSS + sentiment = lower). + +## 6. Dependencies & stubs +- External data sources (price APIs, RSS, RPC nodes) — *stub:* canned market data replay. +- M1 Marketplace — execution data source (fills, positions); *stub:* canned fills. +- M3 Sims — primary consumer; *stub:* print data points. +- M5 Traders — secondary consumer; *stub:* print data points. + +## 7. Invariants / laws +- **L1 (C4):** data feeds are **raw and unnormalized in meaning** — the pipeline normalizes + *format* (schema, timestamps, units) but never interprets, filters, or editorialize content. +- **L2 (C4):** **bidirectional flow** — external data flows in (market → sims/traders), and + internal execution data flows back (marketplace → sims). Both directions use the same + `NormalizedDatum` shape. +- **L3 (C3):** **backpressure, not drop** — if a consumer is slow, buffer up to a cap, then + apply backpressure to the source. Never silently drop data points. +- **L4 (C3):** every datum carries a **source and timestamp** — consumers can always trace + where data came from and when. + +## 8. Build steps +1. Define `NormalizedDatum` and `FeedType` shapes. +2. Implement the pub/sub pipeline (subscribe, publish, distribute). +3. Wire external source adapters (start with one price API + one RSS feed). +4. Wire M1 execution data feedback loop. +5. Implement session-scoped time-series history (ring buffer). + +## 9. Tests +Normalization: heterogeneous inputs produce uniform `NormalizedDatum` output. Pub/sub: subscriber +receives published data. History: query returns correct time range. Backpressure: slow consumer +does not cause data loss. Bidirectional: marketplace fills reach sims via the feed. + +## 10. Open items +- Which price APIs / RSS sources to support initially (CoinGecko? DeFiLlama? specific DEX + subgraphs?). +- History buffer size / eviction policy. +- Whether feeds need authentication / rate limiting management. +- Latency requirements (how fresh must data be for each consumer type?). diff --git a/core/docs/plans/M2-digestion-core.md b/core/docs/plans/M2-digestion-core.md deleted file mode 100644 index 237ba12..0000000 --- a/core/docs/plans/M2-digestion-core.md +++ /dev/null @@ -1,70 +0,0 @@ -# M2 — Digestion core (small-model) - -## 1. Component -The stomach's engine: a **small language model** that transforms classified input (M1) into -**digested context** — structured, compressed, ready for Ada and ultimately the Brain. This is -what "digests external input → context" means concretely: summarization, extraction, reformatting, -and compression, performed by a model small enough to run cheaply and fast. - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. bus-topology.md names it "small-model operated" but leaves the model -unspecified (listed as open). Role C3; implementation C1. - -## 3. Language & location -TBD · `src/economy/digest/` or similar. Requires an inference runtime for the small model -(e.g. llama.cpp, ONNX, or an API call to a hosted small model). The wrapper is likely Pony -(bus-native) or Python (ML ecosystem), with a Pony actor facade on Ichor. - -## 4. Does / does-not -- **Does:** take `ClassifiedInput` (M1); run the small model to produce `DigestedContext` — - **summarize** (compress verbose input), **extract** (pull structured data from unstructured), - **reformat** (normalize into the context shape Ada/Brain expect); report actual cost to M3. -- **Does-not:** classify (M1 already did); filter/censor (M0-L2 — digest for comprehension, not - approval); reason or deliberate (the Brain does that); call tools or take actions. - -## 5. Interface contract -- `digest(input: ClassifiedInput) -> DigestedContext { summary, extractions[], source_ref, actual_cost }`. -- `summary`: compressed natural-language context (the "chewed food"). -- `extractions`: structured key-value pairs pulled from the input (entities, quantities, intents). -- `source_ref`: pointer back to the original input (for M6 provenance chain). -- `actual_cost`: real token count consumed (input + output), reported to M3 ledger. -- The model is invoked with a **system prompt specific to digestion** — not the agent's system - prompt. The digestion prompt instructs: summarize, extract, reformat; do not opine, decide, or - filter. - -## 6. Dependencies & stubs -- M1 `ClassifiedInput` — upstream; *stub:* canned classified input. -- M3 cost ledger — receives `actual_cost`; *stub:* print cost. -- Small model runtime — *stub:* a deterministic mock that returns fixed summaries for known inputs - (no model needed for unit tests). - -## 7. Invariants / laws -- **L1 (C4):** digestion is **lossy compression, not judgment** — the model summarizes and - extracts but never evaluates, approves, or filters the content. It chews; it doesn't taste. -- **L2 (C4):** the digestion prompt is **fixed and auditable** — not dynamically generated, not - influenced by the input being digested (no prompt injection path from input to digestion - instructions). -- **L3 (C3):** **actual cost is always reported** — every invocation records real token usage to - M3; no "free" digestions. -- **L4 (C3):** the model is **small by design** — cost and latency must stay below the threshold - where digestion becomes more expensive than passing raw input. If the model is too expensive, - the organ is failing its economic purpose. - -## 8. Build steps -1. Select the small model (candidates: Haiku-class, phi-3-mini, or similar; evaluate on - summarization quality vs cost vs latency). -2. Write the fixed digestion system prompt. -3. Build the inference wrapper (model invocation + output parsing). -4. Wire M1 → M2 → M3 (cost reporting) → M5 (output shaping). - -## 9. Tests -Mock model: known input → expected summary + extractions. Cost reporting: actual_cost recorded for -every invocation. Prompt integrity: digestion prompt is the fixed string (no injection). Latency: -invocation completes within budget (TBD threshold). - -## 10. Open items -- **Model selection** (C1) — which small model, self-hosted vs API, quantization level. -- **Digestion prompt** (C1) — exact wording; needs empirical tuning against real inputs. -- Latency budget (C1) — max acceptable ms per digestion; ties to how it's invoked (batch vs streaming). -- Whether different input types (M1 classification) get different digestion strategies or one - model handles all. diff --git a/core/docs/plans/M3-cost-ledger.md b/core/docs/plans/M3-cost-ledger.md deleted file mode 100644 index b2dc48e..0000000 --- a/core/docs/plans/M3-cost-ledger.md +++ /dev/null @@ -1,63 +0,0 @@ -# M3 — Cost ledger - -## 1. Component -The stomach's accounting book: records **every resource expenditure** across the economy organ and, -optionally, across the organism. Every token spent on digestion (M2), every budget check (M4), -every outer-bus exchange (M7) — the ledger knows. This is the "money" in "M for money": if it -costs something, it's in the ledger. - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. No cost tracking exists anywhere in the system. A2 (energy driver) tracks -an internal activation/rest budget but has no concept of external resource costs. Role C3; -implementation C1. - -## 3. Language & location -TBD · `src/economy/ledger/` or similar. Needs durable-enough storage to survive a session (but -the container is ephemeral, so "durable" means in-memory with optional flush — not a database). -Could be R (to sit near A2), Pony (bus-native), or a simple append-only log. - -## 4. Does / does-not -- **Does:** record every resource expenditure as a `LedgerEntry` (who spent, what action, how much, - when); provide totals by organ, by action type, and grand total; answer "how much has been spent?" - and "how much is left?" (the latter via M4's budget). -- **Does-not:** decide whether to spend (M4 governs that); price tools (A2 does); restrict actions - (Ada D1 polices); optimize or suggest cheaper paths (that's a future concern, not a ledger's job). - -## 5. Interface contract -- `record(entry: LedgerEntry) -> receipt_id`. - `LedgerEntry { organ_id, action, resource_type, amount, timestamp }`. - `resource_type` ∈ { `input_tokens`, `output_tokens`, `compute_ms`, `api_call` }. -- `total(filter?) -> num` — total spent, optionally filtered by organ/action/resource_type/time range. -- `entries(filter?) -> [LedgerEntry]` — raw entries for audit. -- The ledger is **append-only** at runtime — entries are never modified or deleted (the books don't - get cooked). A session-start reset is fine (ephemeral container). - -## 6. Dependencies & stubs -- M2 digestion core — primary cost source (reports `actual_cost` per digestion). -- M4 budget governor — reads totals to compute remaining budget; *stub:* the ledger is usable - without M4 (it just records, doesn't enforce). -- A2 energy driver — potential consumer of cost data for pricing; *stub:* no integration initially. - -## 7. Invariants / laws -- **L1 (C4):** the ledger is **append-only** — no entry is ever mutated or deleted at runtime. -- **L2 (C4):** **completeness** — every resource expenditure in the economy organ produces a - ledger entry; no "off-books" spending. -- **L3 (C3):** the ledger is **passive** — it records, it never blocks or delays an action. - Enforcement is M4's job. - -## 8. Build steps -1. Define `LedgerEntry` shape and the append-only store (in-memory list; consider a ring buffer - with a cap if memory is a concern in long sessions). -2. Wire M2 → M3 (digestion cost recording). -3. Implement `total` and `entries` queries with filtering. -4. Optional: flush to disk / log file for post-session audit. - -## 9. Tests -Append: entries accumulate, count matches. Immutability: no mutation API exists. Totals: filtered -totals match manual sum. Completeness: a mock M2 digestion produces a corresponding ledger entry. - -## 10. Open items -- Whether the ledger scope extends beyond the economy organ to track costs for other organs - (MoRAG model calls, SAE compute, Brain inference). Start organ-scoped; expand if needed. -- Storage cap / eviction policy for very long sessions (ring buffer vs unbounded). -- Post-session export format (JSON log? CSV?). diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md new file mode 100644 index 0000000..8cd3f13 --- /dev/null +++ b/core/docs/plans/M3-sims-hub.md @@ -0,0 +1,75 @@ +# M3 — Sims hub (market prediction simulations) + +## 1. Component +The economy organ's prediction engine: **always-running simulations** ("Sims") populated by +autonomous simulation agents ("Pops") that model market dynamics across multiple mathematical +domains and time scales. Sims are **queryable at any time** by Traders (M5) — they produce +**predictions with explicit upper and lower bounds** on every output value. This is the hub spec; +individual sim types have dedicated sub-specs (M3a–M3g). + +The academic foundations span AMM mechanism design [1,2], MEV game theory [3,4,5], macro +tokenomics via SDEs [6,7], and evolutionary consensus games [8–11]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C3; implementation C1. Mathematical foundations C4 (literature +established); specific model parameters C1. + +## 3. Language & location +TBD · `src/economy/sims/`. Numerical computing (Julia, Python/NumPy, Octave, or Rust) for the +simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g) may use a +different runtime suited to its math. + +## 4. Does / does-not +- **Does:** run continuously across multiple time scales (tick-level, hourly, daily, weekly); + maintain populations of Pops whose behaviors emerge from the sim's mathematical model; ingest + live data from Data Feeds (M2) for calibration; respond to Trader queries with bounded + predictions; produce outputs with **explicit upper/lower bounds** on every prediction value. +- **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they + decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do). + +## 5. Interface contract +- `query(sim_type: SimType, query: PredictionQuery) -> BoundedPrediction`. + `SimType` ∈ { `statistical`, `sociological`, `amm_liquidity`, `mev_adversarial`, + `tokenomics_macro`, `consensus_staking`, `market_microstructure` } (M3a–M3g). +- `BoundedPrediction { value, lower_bound, upper_bound, confidence, time_horizon, sim_type, timestamp }`. + Every output is bounded — no point estimates without uncertainty ranges. + Example: `{ value: 7.2, lower_bound: 5.8, upper_bound: 8.9, confidence: 0.73, + time_horizon: "4h", sim_type: "amm_liquidity" }`. +- `status(sim_type?) -> { running, pop_count, last_calibration, data_freshness }` — health check. +- `calibrate(sim_type, feed_data: [NormalizedDatum])` — Data Feeds (M2) pushes live data for + model recalibration. + +## 6. Dependencies & stubs +- M2 Data Feeds — calibration data source; *stub:* canned market data. +- M5 Traders — query consumers; *stub:* canned queries. +- M3a–M3g sub-specs — individual sim implementations; *stub:* each returns fixed predictions. + +## 7. Invariants / laws +- **L1 (C5):** sims are **always running** — they are not invoked on demand. Traders query + current state; they don't trigger computation. +- **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no + unbounded point estimates. Uncertainty is a first-class value, not an afterthought. +- **L3 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim + state. Calibration happens only from Data Feeds (M2). +- **L4 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. + Degraded sims report their status; traders handle missing predictions. +- **L5 (C3):** Pops are **simulation constructs, not AI actors** — they follow mathematical + rules within the sim. Traders (M5) are the AI actors. + +## 8. Build steps +1. Define `BoundedPrediction` shape and query protocol. +2. Build the sim runner (lifecycle management for always-on sims). +3. Wire M2 Data Feeds → calibration pipeline. +4. Implement sub-specs M3a–M3g as they land. +5. Wire trader query interface. + +## 9. Tests +Always-on: sim running after init without external trigger. Bounded output: every prediction has +lower ≤ value ≤ upper. Query: trader receives prediction without mutating sim. Independence: +one sim's failure doesn't affect others. Calibration: new data updates model state. + +## 10. Open items +- Pop lifecycle (birth/death/mutation within sims, or fixed populations?). +- Cross-sim aggregation (do traders query individual sims, or is there a meta-prediction layer?). +- Calibration frequency per sim type. +- Computational budget per sim (how much CPU/GPU each can consume). diff --git a/core/docs/plans/M3a-statistical-sims.md b/core/docs/plans/M3a-statistical-sims.md new file mode 100644 index 0000000..0e26f62 --- /dev/null +++ b/core/docs/plans/M3a-statistical-sims.md @@ -0,0 +1,59 @@ +# M3a — Statistical & quantitative sims + +## 1. Component +Pure statistical simulation: **Monte Carlo methods, Bayesian inference, time-series forecasting, +and volatility modeling**. The mathematical backbone — no game theory, no sociology, just the +numbers. Operates across multiple time scales (tick to weekly). Pops in this sim represent +**stochastic sample paths**, not behavioral agents. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Mathematical foundations C4 (standard quant methods); parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/statistical/`. Python (NumPy/SciPy), Julia, or R for numerical +computing. Needs efficient matrix operations and distribution sampling. + +## 4. Does / does-not +- **Does:** run Monte Carlo price simulations (geometric Brownian motion, jump-diffusion); + Bayesian parameter estimation from live data (M2); time-series forecasting (ARIMA, GARCH for + volatility clustering); Value-at-Risk and Expected Shortfall calculations; produce bounded + predictions with confidence intervals as upper/lower bounds. +- **Does-not:** model human behavior (M3b does); model protocol mechanics (M3c–M3f do); + trade or recommend (Traders do). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** statistical confidence intervals. + Example: `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 0.95, + time_horizon: "24h", sim_type: "statistical" }` — 95% CI on ETH price. +- **Prediction types:** `price_forecast`, `volatility_estimate`, `var_calculation`, + `correlation_matrix`, `regime_detection`. +- Calibration: ingests `price_tick` and `dex_pool_state` from M2 Data Feeds. + +## 6. Dependencies & stubs +- M2 Data Feeds — price history for calibration; *stub:* canned price series. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C4):** bounds are **statistical confidence intervals** — derived from the model's + distribution, not hand-picked. The confidence level (e.g. 0.95) is explicit in the output. +- **L2 (C4):** **multiple time scales run concurrently** — a tick-level volatility estimate and a + weekly price forecast coexist; neither blocks the other. +- **L3 (C3):** model parameters are **re-estimated on each calibration** from live data — no + stale parameters carried across regime changes. + +## 8. Build steps +1. Implement geometric Brownian motion Monte Carlo (simplest price sim). +2. Add GARCH volatility estimation. +3. Wire M2 price data → Bayesian parameter re-estimation. +4. Implement the `BoundedPrediction` output with CIs. + +## 9. Tests +Monte Carlo: N sample paths produce a distribution with correct mean/variance. CI: 95% interval +contains true value ≥ 95% of the time on historical backtest. GARCH: volatility clusters detected +in synthetic data. Calibration: new data shifts parameter estimates. + +## 10. Open items +- Which distributions beyond GBM (heavy-tailed? Lévy?). +- Regime-switching model complexity (hidden Markov? threshold?). +- Computational budget (how many Monte Carlo paths per tick?). diff --git a/core/docs/plans/M3b-sociological-sims.md b/core/docs/plans/M3b-sociological-sims.md new file mode 100644 index 0000000..a23e6fc --- /dev/null +++ b/core/docs/plans/M3b-sociological-sims.md @@ -0,0 +1,67 @@ +# M3b — Sociological & population dynamics sims + +## 1. Component +Sociological simulation: **evolutionary game theory, bounded rationality, sentiment cascades, and +population dynamics** among market participants. Pops here are **behavioral archetypes** — retail +herd followers, contrarian whales, MEV searchers, passive LPs — whose strategies evolve under +selection pressure. Grounded in evolutionary consensus game models [8,9] and bounded-rationality +coordination frameworks. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Evolutionary game-theory foundations C4 (Cornell blockchain cooperation +literature [8]); pop behavioral models C1. + +## 3. Language & location +TBD · `src/economy/sims/sociological/`. Agent-based modeling frameworks (Mesa/Python, NetLogo, +or custom). Needs efficient population iteration and strategy mutation. + +## 4. Does / does-not +- **Does:** simulate populations of behavioral archetypes competing in a market; apply + evolutionary dynamics (replicator equation, mutation, selection) to strategy distributions; + model sentiment cascades (fear/greed contagion across pop clusters); model bounded rationality + (pops satisfice, not optimize — they follow heuristics, not perfect strategies); produce + bounded predictions on market sentiment, herd behavior thresholds, and coordination breakdowns. +- **Does-not:** model protocol mechanics (M3c–M3f); compute statistical forecasts (M3a); + represent real individuals (pops are archetypes, not profiles). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** population-fraction ranges and sentiment scales. + Example: `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 0.68, + time_horizon: "12h", sim_type: "sociological" }` — herd-panic index on a 0–10 scale. + Example: `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 0.72, + time_horizon: "1w", sim_type: "sociological" }` — fraction of pops in "contrarian" strategy. +- **Prediction types:** `sentiment_index`, `herd_threshold`, `strategy_distribution`, + `cascade_probability`, `coordination_stability`. +- Calibration: ingests `rss_news` (sentiment signal) and `price_tick` (realized behavior) from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — sentiment and price data for calibration; *stub:* canned sentiment series. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C4):** pops are **archetypes, not individuals** — no attempt to model or track real + market participants. The sim models emergent behavior from strategy populations. +- **L2 (C4):** strategies **evolve** — the population distribution shifts over time via + replicator dynamics. No fixed strategy ratios. +- **L3 (C3):** bounded rationality is the **default** — pops satisfice with heuristics, not + optimize with perfect information. Rational-agent models are a special case, not the baseline. + +## 8. Build steps +1. Define pop archetypes and their heuristic strategies. +2. Implement replicator dynamics (strategy evolution over generations). +3. Implement sentiment contagion model (network-based cascade). +4. Wire M2 news/price data → calibration of pop parameters. +5. Implement `BoundedPrediction` output with population-fraction CIs. + +## 9. Tests +Evolution: dominant strategy shifts when payoff landscape changes. Cascade: sentiment shock +propagates through pop network above threshold, not below. Bounded rationality: satisficing pop +underperforms optimizer in simple games but outperforms in noisy environments. Bounds: all +outputs include upper/lower. + +## 10. Open items +- Pop archetype catalog (which behavioral types? how many?). +- Network topology for sentiment contagion (small-world? scale-free?). +- Calibration from real market data — how to infer pop distribution from observable price action. +- Cross-sim interaction: do sociological predictions feed into M3c (AMM) or M3d (MEV)? diff --git a/core/docs/plans/M3c-amm-liquidity-sims.md b/core/docs/plans/M3c-amm-liquidity-sims.md new file mode 100644 index 0000000..3be5158 --- /dev/null +++ b/core/docs/plans/M3c-amm-liquidity-sims.md @@ -0,0 +1,66 @@ +# M3c — AMM & liquidity pool sims + +## 1. Component +Automated Market Maker simulation: models **constant-product invariant mechanics, impermanent +loss, and the non-cooperative game between liquidity providers and arbitrageurs**. Pops here are +**LP positions and arbitrage bots** operating on the $x \cdot y = k$ curve. Grounded in the DEX/AMM +literature [1,2]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Mathematical foundations C5 (constant product invariant is proven); +impermanent loss formula C5 (closed-form: $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$); +simulation parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/amm/`. Needs precise fixed-point or arbitrary-precision arithmetic for +invariant calculations (Solidity-equivalent precision). Python, Rust, or Julia. + +## 4. Does / does-not +- **Does:** simulate constant-product pools with fee parameter $\gamma$: + $(x + \gamma \Delta x)(y - \Delta y) = k$; model impermanent loss as a function of price ratio + shift $r$; simulate LP strategies (provide, withdraw, rebalance) against arbitrageur behavior; + model non-linear price slippage from the curve geometry; produce bounded predictions on pool + profitability, IL risk, and optimal LP ranges. +- **Does-not:** model consensus mechanics (M3f); model social behavior (M3b); execute real swaps + (Marketplace does). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** IL ranges and pool return intervals. + Example: `{ value: -0.034, lower_bound: -0.058, upper_bound: -0.012, confidence: 0.90, + time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool. + Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 0.85, + time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL). +- **Prediction types:** `impermanent_loss`, `pool_return`, `optimal_range`, `slippage_estimate`, + `lp_withdrawal_threshold`. +- Calibration: ingests `dex_pool_state` and `price_tick` from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — pool state and price data; *stub:* canned pool snapshots. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C5):** the **constant product invariant** $x \cdot y = k$ (adjusted for fees $\gamma$) + is the ground truth — all pool state transitions must satisfy the invariant or the sim is wrong. +- **L2 (C5):** **impermanent loss** follows the proven formula + $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$ — the sim must reproduce this exactly for the + base case (no fees, no concentrated liquidity). +- **L3 (C4):** LP withdrawal thresholds are **derived from IL, not hardcoded** — the sim + calculates at what price ratio a rational LP withdraws, based on the IL formula and fee income. + +## 8. Build steps +1. Implement the constant-product pool simulator with fee parameter. +2. Verify IL formula reproduction against known inputs. +3. Add LP pop strategies (passive hold, active rebalance, just-in-time liquidity). +4. Add arbitrageur pops (sandwich, backrun). +5. Wire M2 pool state data → calibration. + +## 9. Tests +Invariant: every swap satisfies $(x + \gamma \Delta x)(y - \Delta y) = k$. IL formula: matches +closed-form for known price ratios. Slippage: large swaps produce greater slippage than small. +LP threshold: LP withdraws when IL exceeds fee income. Bounds: all outputs bounded. + +## 10. Open items +- Concentrated liquidity (Uniswap v3 style) — extends the base model significantly. +- Multi-pool routing (split swaps across pools). +- Which specific pools to simulate (ETH/USDC? stablecoin pairs?). diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md new file mode 100644 index 0000000..1e0e6bb --- /dev/null +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -0,0 +1,69 @@ +# M3d — MEV & adversarial extraction sims + +## 1. Component +Maximal Extractable Value simulation: models **transaction ordering as an optimization problem**, +**Priority Gas Auctions (PGA) as all-pay auctions**, and **block building as a multidimensional +knapsack problem**. Pops here are **searcher bots, block builders, and validators** competing for +extractable value. Grounded in ACM MEV game theory [3] and knapsack auction literature [4,5]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. PGA-as-all-pay-auction model C4 (ACM [3]); knapsack formulation C4 +(Cornell [4,5]); simulation parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (for knapsack) and continuous-time +auction modeling. Python (PuLP/OR-Tools for optimization), Rust, or Julia. + +## 4. Does / does-not +- **Does:** simulate Priority Gas Auctions where multiple searcher bots compete for the same + arbitrage opportunity $V$ by bidding gas fees $g$ in a continuous-time all-pay auction; model + block building as a multidimensional knapsack problem (scarce block space, heterogeneous + transaction values/sizes); simulate endogenous selection cutoffs under paid-priority ordering; + predict MEV exposure for proposed trades; produce bounded predictions on extraction risk and + optimal gas strategies. +- **Does-not:** extract MEV itself (this is a simulator, not a searcher); model AMM mechanics + (M3c handles pool math); model social dynamics (M3b). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** extraction probability ranges and gas cost intervals. + Example: `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 0.80, + time_horizon: "next_block", sim_type: "mev_adversarial" }` — probability this trade gets + sandwiched. + Example: `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 0.75, + time_horizon: "next_block", sim_type: "mev_adversarial" }` — optimal gas bid (gwei) for + a given opportunity. +- **Prediction types:** `sandwich_probability`, `frontrun_risk`, `optimal_gas_bid`, + `block_inclusion_probability`, `mev_exposure`. +- Calibration: ingests `on_chain_event` (mempool-like data) and `price_tick` from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — on-chain events and gas data; *stub:* canned mempool snapshots. +- M3 Sims hub — lifecycle management; *stub:* manual init. +- M3c AMM sims — pool state for arbitrage opportunity detection; *stub:* fixed pool state. + +## 7. Invariants / laws +- **L1 (C4):** PGA is modeled as an **all-pay auction** — all bidders pay their gas whether they + win or not. The sim must capture this cost structure (not winner-pays-only). +- **L2 (C4):** block building is a **knapsack problem, not a queue** — builders optimize for + total extracted value subject to gas limit constraints, not first-come-first-served. +- **L3 (C3):** MEV exposure predictions are **pre-trade** — traders query this sim *before* + submitting to the Marketplace to understand their extraction risk. + +## 8. Build steps +1. Implement the PGA all-pay auction model (N searchers, opportunity value V, gas bids). +2. Implement the block-building knapsack solver. +3. Add sandwich/frontrun detection heuristics. +4. Wire M2 on-chain data → calibration of searcher population and gas dynamics. +5. Wire pre-trade query interface for Traders. + +## 9. Tests +All-pay: losing bidders still pay gas cost. Knapsack: builder selects optimal transaction set +under gas limit. Sandwich: known sandwich-vulnerable trade flagged; non-vulnerable trade clear. +Bounds: all outputs bounded. Pre-trade: query does not submit any transaction. + +## 10. Open items +- Mempool data access (public mempool? private order flow?). +- Which MEV types to model initially (sandwich, backrun, liquidation, JIT?). +- Multi-block MEV (cross-block extraction strategies). +- Integration with M3c (arbitrage opportunities arise from AMM pool state). diff --git a/core/docs/plans/M3e-tokenomics-macro-sims.md b/core/docs/plans/M3e-tokenomics-macro-sims.md new file mode 100644 index 0000000..01e7265 --- /dev/null +++ b/core/docs/plans/M3e-tokenomics-macro-sims.md @@ -0,0 +1,72 @@ +# M3e — Tokenomics & macro-state sims + +## 1. Component +Macro-level token economy simulation: models **token supply dynamics, monetary policy (halvings, +burns, inflation), and systemic stock-flow balances** using stochastic differential equations +(SDEs) and state-space models. Pops here are **aggregate behavioral cohorts** (miners/validators, +holders, speculators, protocol treasuries) whose collective behavior drives token-level dynamics. +Grounded in the Vienna University complex-systems token modeling [7] and ResearchGate engineering +token economy frameworks [6]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. SDE state-space framework C4 (Vienna [7]); stock-flow modeling C4 +(ResearchGate [6]); specific token model parameters C1. + +## 3. Language & location +TBD · `src/economy/sims/tokenomics/`. Needs SDE solvers (Euler-Maruyama, Milstein) and +state-space estimation. Julia (DifferentialEquations.jl), Python (scipy), or Octave. + +## 4. Does / does-not +- **Does:** simulate token state dynamics via the SDE framework: + $dX_t = f(X_t, u(X_t, t), t)dt + \sigma(X_t, t)dW_t$ where $X_t$ is the system state vector, + $u$ is the behavioral policy function, deterministic drift captures programmatic parameters + (halvings, burns), and Brownian motion $\sigma dW_t$ captures stochastic behavioral shocks; + model stock-flow balances (circulating supply, staked, locked, burned); simulate monetary + policy impacts (halving events, fee burns, treasury emissions); produce bounded predictions + on token supply trajectories, inflation rates, and velocity. +- **Does-not:** model individual transactions (M3c/M3d); model social sentiment (M3b); + model consensus mechanics (M3f). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** SDE confidence bands (derived from the stochastic component $\sigma dW_t$). + Example: `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 0.90, + time_horizon: "90d", sim_type: "tokenomics_macro" }` — annualized inflation rate (%). + Example: `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 0.85, + time_horizon: "30d", sim_type: "tokenomics_macro" }` — staking ratio (fraction of supply). +- **Prediction types:** `supply_trajectory`, `inflation_rate`, `staking_ratio`, + `velocity_estimate`, `halving_impact`, `treasury_runway`. +- Calibration: ingests `on_chain_event` (supply metrics, staking data) from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — on-chain supply/staking data; *stub:* canned supply snapshots. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C4):** the SDE framework is the **canonical representation** — all token dynamics are + expressed as drift + diffusion. Deterministic policy (halvings, burns) lives in the drift $f$; + behavioral uncertainty lives in the diffusion $\sigma dW_t$. +- **L2 (C4):** **stock-flow conservation** — tokens are never created or destroyed outside the + protocol's defined mechanisms. The sim must balance: circulating + staked + locked + burned = + total ever minted. +- **L3 (C3):** macro sims operate on **aggregate cohorts, not individuals** — the state vector + $X_t$ tracks population-level quantities (total staked, total circulating), not per-wallet. + +## 8. Build steps +1. Implement Euler-Maruyama SDE solver for a simple token model (supply + staking). +2. Define the state vector $X_t$ and drift/diffusion functions for a reference token. +3. Add stock-flow accounting (verify conservation). +4. Wire M2 on-chain data → state estimation / calibration. +5. Add monetary policy events (halving, burn) as drift discontinuities. + +## 9. Tests +SDE: sample paths have correct mean (matches drift) and variance (matches diffusion). Stock-flow: +conservation holds across all time steps. Halving: supply growth rate drops at halving event. +Calibration: state estimate converges to observed data. Bounds: SDE confidence bands correctly +cover realized paths on backtest. + +## 10. Open items +- Which tokens to model initially (ETH? BTC? a specific alt?). +- State vector dimensionality (how many state variables per token model?). +- Behavioral policy function $u(X_t, t)$ — how to parameterize aggregate cohort behavior. +- Multi-token interactions (correlated diffusions across tokens?). diff --git a/core/docs/plans/M3f-consensus-staking-sims.md b/core/docs/plans/M3f-consensus-staking-sims.md new file mode 100644 index 0000000..bb3e06a --- /dev/null +++ b/core/docs/plans/M3f-consensus-staking-sims.md @@ -0,0 +1,72 @@ +# M3f — Consensus & staking game sims + +## 1. Component +Consensus-layer simulation: models **Proof-of-Stake validation dynamics, staking pool game theory, +and Byzantine fault tolerance** using evolutionary games and Markov chains. Pops here are +**validators and staking pool operators** whose honesty is a dynamic, evolving strategy under +financial incentives. Grounded in Cornell evolutionary consensus [8,9], ACM staking pool risk +theorems [10], and Monash dynamic PBFT modeling [11]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Evolutionary PoS game theory C4 (Cornell [8]); staking pool Nash +equilibrium proofs C4 (ACM [10]); Markov chain throughput models C4 (Monash [11]); +simulation parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/consensus/`. Needs Markov chain solvers and game-theoretic equilibrium +computation. Python, Julia, or R. + +## 4. Does / does-not +- **Does:** simulate validator populations where honesty evolves via **evolutionary game theory** + under bounded rationality [8]; model staking pool delegation as a game with proven reward- + parameter thresholds enforcing subgame-perfect Nash equilibria favoring honest validation over + malicious slashing [10]; simulate **throughput stability under shifting validator states** via + Markov chains [11]; predict slashing risk, validator set stability, and staking yield; produce + bounded predictions on consensus health and staking returns. +- **Does-not:** validate blocks (this is a simulator); model AMM pools (M3c); model token supply + (M3e — but consumes staking ratio from M3e as input). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** equilibrium stability ranges and yield intervals. + Example: `{ value: 0.89, lower_bound: 0.82, upper_bound: 0.94, confidence: 0.88, + time_horizon: "7d", sim_type: "consensus_staking" }` — fraction of validators honest in + equilibrium. + Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 0.82, + time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%). +- **Prediction types:** `validator_honesty_fraction`, `slashing_probability`, `staking_yield`, + `pool_delegation_equilibrium`, `throughput_stability`, `consensus_liveness`. +- Calibration: ingests `on_chain_event` (validator set changes, slashing events) from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — validator/staking on-chain data; *stub:* canned validator snapshots. +- M3e Tokenomics — staking ratio as macro input; *stub:* fixed ratio. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C4):** validator honesty is a **dynamic equilibrium, not a fixed parameter** — it evolves + via replicator dynamics as payoffs change. The sim must not assume fixed honesty rates. +- **L2 (C4):** the staking pool reward threshold is **mathematically derived** — the sim must + reproduce the subgame-perfect Nash equilibrium from the ACM proofs [10], not use ad-hoc + thresholds. +- **L3 (C4):** throughput is modeled as a **Markov chain** over validator states (active, pending, + slashed, exited) — transitions are stochastic with rates calibrated from on-chain data [11]. + +## 8. Build steps +1. Implement the evolutionary honesty game (replicator dynamics, bounded rationality). +2. Implement the Markov chain validator-state model. +3. Reproduce the staking pool Nash equilibrium reward threshold from [10]. +4. Wire M2 validator data → calibration of transition rates. +5. Wire M3e staking ratio input. + +## 9. Tests +Equilibrium: honesty fraction converges to Nash equilibrium under stable payoffs. Markov: +stationary distribution matches expected validator state proportions. Threshold: pool delegation +equilibrium matches the ACM proof for test parameters. Bounds: all outputs bounded. Liveness: +throughput degrades when honest fraction drops below threshold. + +## 10. Open items +- Which PoS protocol to model initially (Ethereum? a specific L2?). +- Bounded rationality implementation (noisy best-response? epsilon-greedy? logit?). +- Slashing severity parameterization. +- Cross-sim: does consensus instability feed into M3b sociological panic signals? diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md new file mode 100644 index 0000000..18bc84a --- /dev/null +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -0,0 +1,70 @@ +# M3g — Market microstructure sims + +## 1. Component +Market microstructure simulation: models **order flow, liquidity depth, slippage, spread dynamics, +and cross-exchange arbitrage** at the fastest time scales (tick-level to hourly). Pops here are +**market makers, takers, and arbitrageurs** interacting across multiple venues. The sim that +operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c +models pool mechanics, M3g models the *plumbing* of how orders actually execute. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established academic field); +DEX-specific microstructure C2 (emerging). Implementation C1. + +## 3. Language & location +TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling and event-driven +simulation. Rust, C++, or Python with optimized event loop. + +## 4. Does / does-not +- **Does:** simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a + function of inventory risk and adverse selection; simulate slippage curves for various order + sizes; model cross-exchange arbitrage opportunities and their decay; operate at **tick-level + resolution** (sub-second to minute); produce bounded predictions on execution quality, optimal + routing, and liquidity conditions. +- **Does-not:** model protocol consensus (M3f); model macro token supply (M3e); model social + behavior (M3b); execute trades (Marketplace does). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** execution cost ranges and liquidity intervals. + Example: `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 0.85, + time_horizon: "next_trade", sim_type: "market_microstructure" }` — expected slippage (%) for a + 10 ETH market sell. + Example: `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 0.78, + time_horizon: "1h", sim_type: "market_microstructure" }` — available depth (USD) within 50bps + of mid. +- **Prediction types:** `slippage_estimate`, `spread_forecast`, `depth_profile`, + `cross_venue_arb`, `optimal_execution_route`, `liquidity_score`. +- Calibration: ingests `price_tick`, `dex_pool_state`, and `execution_fill` from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — tick data and pool state; *stub:* canned order book snapshots. +- M3c AMM sims — pool mechanics for DEX venues; *stub:* fixed pool state. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C4):** microstructure operates at the **highest temporal resolution** — predictions are + valid for seconds to hours, not days. Stale microstructure data is worse than no data. +- **L2 (C4):** slippage is a **function of order size and current depth** — not a fixed + percentage. The sim must model the non-linear relationship. +- **L3 (C3):** cross-venue arbitrage opportunities **decay** — the sim models the time-to-close + of an arb opportunity, not just its existence. + +## 8. Build steps +1. Implement a simplified order-book simulator (limit orders, market orders, cancels). +2. Add spread dynamics (inventory-based market maker model). +3. Add slippage curves (order size → execution cost). +4. Add cross-venue arb detection and decay modeling. +5. Wire M2 tick data → calibration. + +## 9. Tests +Slippage: larger orders produce greater slippage. Spread: spread widens under adverse selection. +Arb decay: detected arb opportunity closes over time. Depth: depth profile matches order book +state. Bounds: all outputs bounded. Resolution: predictions update at tick frequency. + +## 10. Open items +- CEX order book data access (API limitations, costs). +- DEX-specific microstructure (AMM pools don't have order books — translate pool state to + equivalent depth/spread). +- Latency modeling (how fast can our traders actually reach an arb?). +- Which venues to model initially. diff --git a/core/docs/plans/M4-budget-governor.md b/core/docs/plans/M4-budget-governor.md deleted file mode 100644 index 34c2b2b..0000000 --- a/core/docs/plans/M4-budget-governor.md +++ /dev/null @@ -1,66 +0,0 @@ -# M4 — Budget governor - -## 1. Component -The stomach's CFO: **sets, allocates, and enforces** resource budgets. Decides whether a proposed -expenditure (digestion, retrieval, exchange) is affordable given what's already been spent (M3) -and what's been allocated. Emits **price signals** to A2 (energy driver) so the per-tool economy -reflects real resource scarcity. - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. A2 has a per-tool cost/lockout system but it tracks internal energy, not -external resource budgets. The two are complementary: A2 = activation/rest; M4 = tokens/compute -spend. Role C2; implementation C1. - -## 3. Language & location -TBD · `src/economy/budget/` or similar. Must interop with M3 (ledger reads) and A2 (price signal -emission). Likely same language as M3 for tight integration. - -## 4. Does / does-not -- **Does:** hold a session budget (total resources available); check proposed costs against - remaining budget (`check_budget`); emit price signals to A2 so tool costs reflect real scarcity; - implement **degradation tiers** — when budget is ample, digest fully; when tight, digest - shallowly or defer bulk input (M1 priority system). -- **Does-not:** record costs (M3 does); perform digestion (M2 does); lock tools (A2 does that - based on energy, though M4's price signals influence A2's cost landscape); police traffic (D1). - -## 5. Interface contract -- `init_budget(session_budget: num, resource_type: ResourceType) -> BudgetState`. -- `check_budget(proposed_cost: num, resource_type: ResourceType) -> { allowed:bool, remaining:num, tier:DegradationTier }`. - `DegradationTier` ∈ { `full`, `shallow`, `deferred` } — signals to M2 how deeply to digest. -- `price_signal(tool_id) -> { resource_cost:num, scarcity_factor:num }` — emitted to A2; the - scarcity factor scales with budget depletion (1.0 = ample, >1.0 = scarce, costs feel heavier). -- `remaining() -> { budget:num, spent:num, pct_remaining:num }` — reads M3 totals. - -## 6. Dependencies & stubs -- M3 cost ledger — reads totals for remaining budget calculation; *stub:* returns zero spent. -- A2 energy driver — consumes price signals; *stub:* print signals. -- M1 ingestion — M1 checks budget before forwarding to M2; *stub:* always-allow. -- M2 digestion core — receives `DegradationTier` to adjust digestion depth. - -## 7. Invariants / laws -- **L1 (C4):** budget enforcement is a **soft gate, not a hard wall** — when budget is exhausted, - digestion degrades (shallower summaries, deferred bulk) rather than halting. The organ never - stops entirely; it economizes harder. Mirrors A2-L2 (no unrecoverable state) and A2-L3 - (lockout is a breaker, not a sentence). -- **L2 (C3):** price signals are **monotonically scarcer** as budget depletes — the scarcity - factor never decreases within a session (costs only feel heavier as resources dwindle). Resets - only on budget replenishment. -- **L3 (C3):** degradation tiers are **transparent** — the tier is carried in the contract so - downstream (M2, M5) knows the digestion was shallow and can annotate accordingly. - -## 8. Build steps -1. Define `BudgetState` and the degradation tiers. -2. Implement `check_budget` against M3 totals. -3. Implement `price_signal` emission to A2 (define the scarcity factor curve — invariants-first). -4. Wire M1 → M4 → M2 (budget check before digestion, tier passed to digestion). - -## 9. Tests -Budget arithmetic: spent + remaining = total. Degradation tiers: each tier triggers at the correct -budget percentage. Price signals: scarcity factor increases as budget depletes. Soft gate: zero -budget produces `deferred` tier, not an error. - -## 10. Open items -- Session budget source — who sets it? Hardcoded? Config? Dynamically adjusted? (C1). -- Degradation tier thresholds (C1) — at what % remaining does `full` → `shallow` → `deferred`? -- The scarcity factor curve shape (C1) — linear? exponential? Needs invariants-first fitting. -- Whether budget replenishment is possible mid-session (ties to A2 restoration model / A8 ETR). diff --git a/core/docs/plans/M4-wallets.md b/core/docs/plans/M4-wallets.md new file mode 100644 index 0000000..45a5a4d --- /dev/null +++ b/core/docs/plans/M4-wallets.md @@ -0,0 +1,74 @@ +# M4 — Wallets (sovereign custody) + +## 1. Component +The economy organ's vault: **sovereign, local-hosted, our-custody-only cryptocurrency wallets**. +Each wallet binds to exactly one Trader (M5) — a trader without a wallet cannot access the +Marketplace (M1). Wallets hold keys, sign transactions, and enforce wallet-level spending limits. +Tax is collected on trader income and routed to the Verschwörern Veregeister wallets (stub — M0). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C4 (sovereign custody is a hard requirement); implementation C1. + +## 3. Language & location +TBD · `src/economy/wallets/`. Needs cryptographic key management (secp256k1 for EVM, ed25519 for +Solana, etc.), HD derivation, and transaction signing. Rust or Go for crypto primitives; Python +with web3 libs for prototyping. + +## 4. Does / does-not +- **Does:** generate and store private keys locally (never transmitted); sign transactions on + behalf of the bound trader; enforce per-wallet spending limits (daily, per-transaction); + track wallet balance and transaction history; collect tax on realized income and stage for + transfer to Verschwörern Veregeister wallets; bind 1:1 to a Trader (M5). +- **Does-not:** decide what to trade (Trader decides); route to chain (Marketplace does); + hold keys for the organism's other wallets (Verschwörern Veregeister are separate); delegate + custody to any third party — ever. + +## 5. Interface contract +- `create_wallet(chain: Chain, trader_id) -> wallet_id` — generates keys, binds to trader. +- `sign(wallet_id, tx: UnsignedTransaction) -> SignedTransaction` — signs with the wallet's key. + Only the bound trader (via Marketplace) can request signing. +- `balance(wallet_id) -> { chain, assets: [{ token, amount }] }`. +- `spending_check(wallet_id, amount) -> { allowed:bool, remaining_daily:num }`. +- `tax_collect(wallet_id, income_amount) -> { tax_amount, receipt }` — computes and stages tax. +- `transfer_tax_stub(source_wallet, dest_wallet, amount) -> receipt` — **STUB** for future + Verschwörern Veregeister internal transfer. Logs only; does not execute. +- `Chain` ∈ { `evm`, `solana`, `bitcoin`, … } — extensible. + +## 6. Dependencies & stubs +- M5 Traders — 1:1 binding; *stub:* canned trader ID. +- M1 Marketplace — signing requests come through marketplace only; *stub:* direct sign call. +- Blockchain nodes — balance queries and tx broadcast; *stub:* simulated chain state. +- Verschwörern Veregeister wallets — tax destination; *stub:* log transfer. + +## 7. Invariants / laws +- **L1 (C5):** **sovereign custody only** — private keys are generated locally, stored locally, + and **never leave the wallet**. No custodial service, no exchange deposit, no MPC with external + parties. Our keys, our coins. +- **L2 (C5):** **1:1 trader binding** — each wallet is bound to exactly one trader. A trader + cannot use another trader's wallet. The Marketplace enforces this. +- **L3 (C4):** **signing requires Marketplace routing** — a wallet will not sign a transaction + that didn't come through the Marketplace harness (M1-L1). No direct signing API for traders. +- **L4 (C4):** **spending limits are wallet-level** — independent of Conductor or Marketplace + limits. Defense in depth: even if other controls fail, the wallet itself caps exposure. +- **L5 (C4):** **tax collection is automatic** — realized income triggers tax staging. The trader + cannot opt out. + +## 8. Build steps +1. Implement key generation and secure local storage (encrypted keystore). +2. Implement transaction signing for one chain (start with EVM/secp256k1). +3. Implement trader binding and Marketplace-only signing enforcement. +4. Implement spending limits (daily cap, per-tx cap). +5. Implement tax calculation and staging stub. + +## 9. Tests +Custody: private key never appears in any API response or log. Binding: wrong trader cannot +sign. Marketplace-only: direct sign request (not via Marketplace) rejected. Spending limit: +over-limit transaction rejected. Tax: income event triggers correct tax amount. Multi-chain: +EVM and one other chain produce valid signatures. + +## 10. Open items +- Key storage format (encrypted JSON keystore? OS keyring? HSM for production?). +- Which chains to support initially. +- Spending limit configuration (hardcoded? per-trader? adjustable by Conductor?). +- Tax rate and calculation method. +- Key rotation / backup strategy. diff --git a/core/docs/plans/M5-context-yield.md b/core/docs/plans/M5-context-yield.md deleted file mode 100644 index 74c898e..0000000 --- a/core/docs/plans/M5-context-yield.md +++ /dev/null @@ -1,73 +0,0 @@ -# M5 — Context yield (absorption) - -## 1. Component -The stomach's output shaper: takes `DigestedContext` from M2 and **packages it into the form Ada -(D1) expects** — an Ichor `Envelope` with the right shape, provenance metadata (M6), and -degradation annotations. This is the absorption step: what the organism actually absorbs from -what was digested. - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. The smoke test (`main.pony:29`) hard-codes a string payload -`"digested context: "`; no real output shaping exists. Role C3; -implementation C1. - -## 3. Language & location -TBD · part of `src/economy/`. Likely Pony (produces `Envelope` directly for bus transport) or a -thin adapter between M2's output and the Ichor envelope shape. - -## 4. Does / does-not -- **Does:** take `DigestedContext` (M2) + provenance chain (M6) + degradation tier (M4); package - into an Ichor `Envelope` with `OrganSecretion` provenance; attach metadata: original provenance - origin, digestion tier, summary length, extraction count; emit the envelope to the Ichor broker - for delivery to Ada. -- **Does-not:** digest (M2 does); decide whether Ada admits it (D1 does); transform the content - further — it packages, it doesn't re-process. - -## 5. Interface contract -- `yield(context: DigestedContext, chain: ProvenanceChain, tier: DegradationTier) -> Envelope`. -- The `Envelope` payload is structured (not a raw string): - ``` - { summary: str, - extractions: [{ key, value }], - meta: { original_provenance: Provenance, - digestion_tier: DegradationTier, - source_ref: str, - actual_cost: num } } - ``` -- The envelope's bus-level `provenance` field is `OrganSecretion` (the stomach is an organ); the - **original** input provenance is carried inside `meta.original_provenance` so Ada can inspect - it (M6 compliance). -- `dest` is always `AdaBorder`. - -## 6. Dependencies & stubs -- M2 `DigestedContext` — upstream; *stub:* canned digested context. -- M6 `ProvenanceChain` — provenance metadata; *stub:* pass-through original provenance. -- M4 `DegradationTier` — annotation; *stub:* always `full`. -- Ichor `Envelope` (existing) — output shape. -- Ichor `Broker` (existing) — delivery. - -## 7. Invariants / laws -- **L1 (C4):** every yielded envelope carries the **original provenance** in metadata — Ada can - always determine what the digested content was *before* the stomach touched it (S1/S2 compliance - via M6). -- **L2 (C4):** the degradation tier is **visible** in the envelope — Ada and the Brain know whether - they're getting a full digest or a shallow/deferred one. No silent quality degradation. -- **L3 (C3):** yield is **stateless** — it packages what it receives; it holds no buffer, no queue, - no memory of previous yields. - -## 8. Build steps -1. Define the structured payload shape (extend beyond raw string). -2. Build the `yield` function (DigestedContext + ProvenanceChain + tier → Envelope). -3. Wire M2 → M5 → Ichor Broker → Ada. -4. Update the smoke test (`main.pony`) to use structured payloads instead of hard-coded strings. - -## 9. Tests -Shape: yielded envelope has all required metadata fields. Provenance: original provenance survives -in `meta.original_provenance`. Tier annotation: each degradation tier correctly tagged. Stateless: -two consecutive yields with different inputs produce independent envelopes. - -## 10. Open items -- The structured payload encoding (JSON? Pony-native? Ada-compatible binary?) — must be parseable - by Ada's `Trust_Guard` on the other side of the seam. -- Whether Ada needs to understand degradation tiers or just passes them through to the Brain. -- Batch yields (multiple digested contexts in one envelope vs one-per-envelope). diff --git a/core/docs/plans/M5-traders.md b/core/docs/plans/M5-traders.md new file mode 100644 index 0000000..732acce --- /dev/null +++ b/core/docs/plans/M5-traders.md @@ -0,0 +1,78 @@ +# M5 — Traders (AI actors) + +## 1. Component +The economy organ's hands: **specialized AI actors** that buy, sell, and mint cryptocurrency and +NFTs. Each trader is bound to a Wallet (M4), operates through the Marketplace (M1), queries Sims +(M3) for predictions, and has all tool calls monitored by the SAE (M7). Multiple traders may +operate concurrently with **different specializations** (DeFi yield, NFT minting, arbitrage, +long-term holding, etc.). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/traders/`. Each trader is an AI actor — likely LLM-based (small models for +speed) or hybrid (LLM for strategy + deterministic execution logic). The harness managing +multiple traders may be Pony actors or a Python async framework. + +## 4. Does / does-not +- **Does:** query Sims (M3) for market predictions (bounded, multi-domain); consume Data Feeds + (M2) for real-time market state; formulate trade decisions based on predictions + data + + specialization; submit `MarketAction` requests to the Marketplace (M1) via bound wallet (M4); + operate with **scoped autonomy** — trades within law/budget constraints don't need Brain or + Conductor approval. +- **Does-not:** execute on-chain directly (Marketplace does); hold keys (Wallet does); supervise + other traders (Conductor does); modify the law script (immutable — M1-L2); bypass the + Marketplace (M1-L1). + +## 5. Interface contract +- `init_trader(specialization, wallet_id, config) -> trader_id`. + `specialization` ∈ { `defi_yield`, `nft_minter`, `arbitrageur`, `trend_follower`, + `market_maker`, … } — extensible. +- `decide(market_state, predictions: [BoundedPrediction]) -> MarketAction?` — the trader's core + loop. May return no action (waiting is a valid decision). +- `tool_call(tool_name, args) -> result` — every tool call is intercepted and logged to SAE (M7) + before execution. Includes Marketplace submissions, Sim queries, and Data Feed reads. +- `pause() / resume()` — Conductor (M6) can pause a trader pending investigation. +- `status() -> { active | paused | investigating, wallet_id, specialization, position_summary }`. + +## 6. Dependencies & stubs +- M1 Marketplace — action submission; *stub:* mock marketplace that logs actions. +- M2 Data Feeds — market data; *stub:* canned data. +- M3 Sims — predictions; *stub:* fixed predictions. +- M4 Wallet — bound 1:1; *stub:* mock wallet. +- M6 Conductor — supervision; *stub:* no supervision. +- M7 SAE — monitors all tool calls; *stub:* print calls. + +## 7. Invariants / laws +- **L1 (C5):** **all market actions go through the Marketplace** — a trader cannot interact with + any chain or protocol except via `MarketAction` → Marketplace (M1). Enforced by architecture + (no direct RPC access), not just policy. +- **L2 (C5):** **all tool calls are monitored** — every tool invocation (Marketplace, Sims, + Feeds, internal) is logged to SAE (M7). No unmonitored trader action. +- **L3 (C4):** **wallet binding is irrevocable within a session** — a trader's wallet cannot be + reassigned to another trader at runtime. +- **L4 (C4):** **Conductor can pause** — a paused trader cannot submit actions, query sims, or + read feeds until resumed by the Conductor (M6). +- **L5 (C3):** trader specialization constrains strategy but not the interface — all traders use + the same `MarketAction` vocabulary regardless of specialization. + +## 8. Build steps +1. Define the trader agent architecture (LLM-based? hybrid? rule-based for v1?). +2. Implement the `decide` loop (observe market state + predictions → action). +3. Wire tool-call interception → M7 SAE. +4. Wire Marketplace submission → M1. +5. Implement pause/resume for Conductor control. +6. Build at least two specializations to test multi-trader dynamics. + +## 9. Tests +Marketplace-only: trader cannot call chain RPC directly. Monitoring: every tool call appears in +SAE log. Wallet binding: trader uses only its bound wallet. Pause: paused trader cannot submit +actions. Specialization: different specializations produce different action patterns on identical +market state. + +## 10. Open items +- Trader agent architecture (which LLM? how much deterministic logic vs. model inference?). +- Number of concurrent traders and resource allocation per trader. +- Specialization catalog (which types, and how do they differ in strategy?). +- Inter-trader coordination (do traders see each other's positions? shared state? isolated?). diff --git a/core/docs/plans/M6-conductor.md b/core/docs/plans/M6-conductor.md new file mode 100644 index 0000000..565c1b0 --- /dev/null +++ b/core/docs/plans/M6-conductor.md @@ -0,0 +1,79 @@ +# M6 — Conductor (supervisory AI) + +## 1. Component +The economy organ's supervisor: a **specialist-trained AI** with authority to **veto Marketplace +actions and pause/investigate individual Traders**. Receives suspicious-behavior reports from the +SAE (M7) and acts on them. The Conductor is the stomach's own judgment — it does not consult the +organism's Brain for trade-level decisions. It supervises; the deterministic law script (M1) +constrains; together they form the multi-layered braking system. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C4 (supervision architecture is clear); implementation C1 (model +selection, training, authority scope). + +## 3. Language & location +TBD · `src/economy/conductor/`. The Conductor is an AI actor — likely a fine-tuned LLM with +specialist training in market risk, trader behavior analysis, and anomaly response. The +inference wrapper sits alongside the Marketplace. + +## 4. Does / does-not +- **Does:** receive SAE (M7) anomaly reports on trader behavior; **pause** a flagged trader's + actions to investigate; **veto** a Marketplace action if investigation reveals risk; **resume** + a cleared trader; review Marketplace actions pre-execution when the law check passes (M1-L4: + veto is checked after law, before execution); maintain an audit log of all veto/pause/resume + decisions. +- **Does-not:** trade (Traders do); execute on-chain (Marketplace does); modify the law script + (immutable — M1-L2); detect anomalies directly (SAE does — the Conductor *responds* to SAE + reports, it doesn't watch raw data); consult the organism's Brain. + +## 5. Interface contract +- `veto_check(action: MarketAction, trader_id) -> { approved | vetoed(reason) }` — called by + Marketplace (M1) for every law-passing action before execution. +- `receive_alert(alert: SAEAlert) -> { pause(trader_id) | dismiss | escalate }`. + `SAEAlert { trader_id, alert_type, evidence, severity, timestamp }`. +- `investigate(trader_id) -> { clear(resume) | veto_pending_actions | restrict(new_limits) }`. +- `decision_log() -> [ConductorDecision]` — full audit trail of all veto/pause/resume/dismiss. +- **SAE/Brain message format compatibility:** the Conductor's incoming alert format is + **identical in structure and signature** to Brain messages — SAE reports to the Conductor in + the same shape it would report to the Brain. This means the Conductor can be swapped for Brain + oversight without protocol changes (though the stomach normally operates autonomously). + +## 6. Dependencies & stubs +- M7 SAE — anomaly reports; *stub:* no alerts (all clear). +- M1 Marketplace — veto check integration; *stub:* always-approve. +- M5 Traders — pause/resume control; *stub:* print pause/resume. + +## 7. Invariants / laws +- **L1 (C5):** the Conductor **can veto, but cannot trade** — it has no wallet, no Marketplace + access as a trader. It supervises from outside the trading loop. +- **L2 (C5):** the **law script is above the Conductor** — the Conductor vetoes actions that + *pass* the law check but seem strategically risky. It cannot override a law violation (those + are rejected before reaching the Conductor — M1-L4). +- **L3 (C4):** **pause is reversible** — a paused trader can always be resumed after + investigation. Pause is a breaker, not a sentence (echoes A2-L3). +- **L4 (C4):** every Conductor decision is **logged** — vetoes, pauses, resumes, dismissals. + The audit log is append-only (echoes M1-L2 / S3). +- **L5 (C4):** SAE alert format and Brain message format are **structurally identical** — same + fields, same signatures. The Conductor processes them the same way the Brain would. + +## 8. Build steps +1. Define the Conductor's decision model (rule-based for v1? fine-tuned LLM for v2?). +2. Wire SAE alert intake (M7 → M6). +3. Wire Marketplace veto check (M1 → M6 → approve/veto). +4. Implement trader pause/investigate/resume flow. +5. Implement append-only decision log. + +## 9. Tests +Veto: flagged action is vetoed; unflagged action approved. Pause: paused trader cannot submit +actions. Resume: cleared trader resumes normal operation. No trading: Conductor cannot submit +`MarketAction`. Law supremacy: Conductor cannot override a law violation (never reaches +Conductor). Audit: every decision appears in the log. Alert format: SAE alert parses identically +to Brain message structure. + +## 10. Open items +- Conductor AI model selection and training data (what does "specialist training" look like?). +- Veto criteria beyond SAE alerts (does the Conductor have independent judgment, or only + responds to SAE reports?). +- Escalation path — if the Conductor is uncertain, does it escalate to the organism's Brain? + Or is the stomach fully autonomous? (Current design: fully autonomous.) +- Multiple Conductors for redundancy? diff --git a/core/docs/plans/M6-provenance-chain.md b/core/docs/plans/M6-provenance-chain.md deleted file mode 100644 index 4ebd355..0000000 --- a/core/docs/plans/M6-provenance-chain.md +++ /dev/null @@ -1,79 +0,0 @@ -# M6 — Provenance chain - -## 1. Component -The chain of custody through the stomach: tracks **where input came from** and **what the stomach -did to it**, so that digested content is never mistaken for original content and Ada (D1) can -enforce S1/S2 with full information. Solves the provenance question from the economy organ review: -the stomach transforms external input into organ-secretion output, but the *origin* must not be -lost. - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. The current smoke test sets `OrganSecretion` provenance on stomach output -(`main.pony:29`) with no record of the original input's provenance. This is the gap that risks -S1/S2 violation. Role C4 (the need is clear); implementation C1. - -## 3. Language & location -TBD · part of `src/economy/`. Likely a data structure carried alongside digested context, not a -separate service. Must be representable in both Pony (bus side) and Ada (border side). - -## 4. Does / does-not -- **Does:** create a `ProvenanceChain` for each input entering the stomach; record each - transformation step (ingestion, classification, digestion, yield); attach the chain to the - yielded envelope (M5) so Ada sees the full history; enable Ada to distinguish "organ-processed - external input" from "organ-generated internal content". -- **Does-not:** decide trust (Ada does); authenticate sources (the bus provenance system does); - filter or reject based on provenance (M0-L2 — digestion doesn't suppress). - -## 5. Interface contract -- `chain_start(original_provenance: Provenance, source: OrganId, input_hash: str) -> ProvenanceChain`. -- `chain_step(chain: ProvenanceChain, step: TransformStep) -> ProvenanceChain`. - `TransformStep { stage, transformer, timestamp }`. - `stage` ∈ { `ingested`, `classified`, `digested`, `yielded` }. -- The final `ProvenanceChain` is: - ``` - { original_provenance: Provenance, -- what the input was before the stomach - original_source: OrganId, -- who sent it (World, MoRAG, etc.) - input_hash: str, -- hash of raw input for audit - steps: [TransformStep], -- what the stomach did, in order - is_external_origin: bool } -- convenience flag for Ada: TRUE if - -- original_provenance ∈ {External, UserInput} - ``` -- `is_external_origin` lets Ada apply S1 screening to digested-but-originally-external content - without parsing the full chain. - -## 6. Dependencies & stubs -- Ichor `Provenance` / `OrganId` (existing) — input types. -- M1 ingestion — creates the chain at `ingested` step. -- M2 digestion — adds the `digested` step. -- M5 context yield — attaches the chain to the envelope; *stub:* pass-through. -- Ada D1 `Trust_Guard` — consumer of the chain; *stub:* print chain on receipt. - -## 7. Invariants / laws -- **L1 (C5):** the chain is **immutable once created** — steps are appended, never modified or - removed. Like the COBOL invariant vault (S3), the provenance record doesn't get rewritten. -- **L2 (C5):** **S2 compliance** — the original provenance is **never reclassified**. The bus - transport field may say `OrganSecretion` (because the stomach is an organ emitting output), but - `original_provenance` in the chain preserves the true origin. This is not reclassification; - it's layered provenance. -- **L3 (C4):** **S1 compliance** — content with `is_external_origin = TRUE` tells Ada that this - traffic **originated externally** even though it arrives as organ output. Ada applies its full - external-traffic screening (rate, blocklist, trust) to such content. -- **L4 (C3):** the `input_hash` allows **audit verification** — given the original input and the - hash, you can confirm the chain refers to the right content. - -## 8. Build steps -1. Define `ProvenanceChain` and `TransformStep` shapes. -2. Wire chain creation in M1 (ingestion) and step-append in M2 (digestion). -3. Wire chain attachment in M5 (yield → envelope metadata). -4. Extend Ada's `Trust_Guard` (or its stub) to read `is_external_origin` and apply S1 screening. - -## 9. Tests -Chain integrity: steps accumulate in order; no mutation. S2: original provenance survives all -transforms. S1: `is_external_origin = TRUE` for external/user input; `FALSE` for organ-to-organ. -Hash: chain's `input_hash` matches hash of the raw input. - -## 10. Open items -- Hash algorithm (SHA-256? lightweight alternative for performance?). -- Whether Ada needs the full chain or just `is_external_origin` + `original_provenance` (start - with the full chain; Ada can ignore what it doesn't need). -- Cross-seam representation (Pony chain → C/Fortran seam → Ada record). diff --git a/core/docs/plans/M7-outer-bus-exchange.md b/core/docs/plans/M7-outer-bus-exchange.md deleted file mode 100644 index dd3ae9f..0000000 --- a/core/docs/plans/M7-outer-bus-exchange.md +++ /dev/null @@ -1,76 +0,0 @@ -# M7 — Outer-bus exchange - -## 1. Component -The stomach's economic relationships with its **outer-bus peers**: MoRAG (F1), SAE (F2), -microagents (F3). How the economy organ requests, receives, and pays for services from other -outer organs — and what it provides in return. The smoke test already shows -`Stomach → MoRAG` (`main.pony:37`); this spec defines the full exchange protocol. - -## 2. Status / certainty -DESIGN-FIRST · ABSENT. One hard-coded `Stomach → MoRAG` message exists in the smoke test. -No protocol, no cost tracking, no bidirectional exchange defined. Role C2; implementation C1. - -## 3. Language & location -TBD · part of `src/economy/`. Exchange happens over Ichor (Pony actors + Envelope), so the -protocol is Envelope-based. The exchange logic lives in the economy organ; peers implement -their side independently. - -## 4. Does / does-not -- **Does:** request world context from MoRAG before/during digestion (enrich the digest with - retrieved knowledge); receive SAE monitoring signals (if SAE detects anomalies in the stomach's - outputs); coordinate with microagents for delegated sub-tasks (e.g. "fetch and pre-chew this - URL"); track the cost of all exchanges in M3. -- **Does-not:** route traffic (Ichor broker does); bypass Ada for any membrane-bound content - (outer-to-outer is fine; anything heading inward crosses D1); command peers (it requests; they - may decline). - -## 5. Interface contract -- **Stomach → MoRAG:** - `request_context(query: str, budget_limit: num) -> Envelope` — ask MoRAG for relevant world - context to enrich a digestion. `budget_limit` caps how much the retrieval may cost (MoRAG - reports actual cost back; M3 records it). -- **Stomach → Microagents:** - `delegate(task: str, budget_limit: num) -> Envelope` — delegate a sub-task (fetch, pre-process) - to a microagent. Same budget/cost protocol. -- **SAE → Stomach:** - `anomaly_signal(finding: str) -> Envelope` — SAE pushes a signal if it detects anomalous - stomach output. The stomach logs it (M3) but does not self-correct (F2-L2: detection only, - no closed elimination loop). -- All exchange envelopes use `OrganSecretion` provenance (outer-to-outer, no membrane crossing). - -## 6. Dependencies & stubs -- Ichor `Broker` + `Envelope` (existing) — transport. -- MoRAG (F1) — context provider; *stub:* fixed context response. -- SAE (F2) — anomaly detector; *stub:* no signals. -- Microagents (F3) — task delegates; *stub:* echo task back. -- M3 cost ledger — records exchange costs. -- M4 budget governor — caps exchange spending via `budget_limit`. - -## 7. Invariants / laws -- **L1 (C5):** outer-to-outer exchange **never crosses Ada** — it stays on Ichor. Only the final - digested output (M5) crosses the membrane. This is by design: peer coordination is "skin-level" - and doesn't need border screening. -- **L2 (C4):** every exchange has a **budget limit** — no unbounded retrieval or delegation. The - stomach asks for what it can afford (M4). -- **L3 (C3):** exchanges are **request/response, not streaming** — the stomach sends a request, - waits for a response (or timeout), and proceeds. No long-lived channels between peers. -- **L4 (C3):** the stomach **never self-corrects** based on SAE signals — it logs them. Correction - is a G1/G2 governance concern, not the organ's. - -## 8. Build steps -1. Define the exchange envelope subtypes (request_context, delegate, anomaly_signal). -2. Implement Stomach → MoRAG context request (extend the existing `main.pony` wire). -3. Implement budget-limited exchange (M4 check before request; M3 record on response). -4. Implement SAE → Stomach anomaly logging. - -## 9. Tests -MoRAG exchange: request sent, response received, cost recorded. Budget limit: exchange rejected -when over budget. Anomaly signal: logged but no state change in the stomach. Outer-only: no -exchange envelope targets `AdaBorder`. - -## 10. Open items -- Whether MoRAG enrichment happens **before** digestion (pre-chew with context) or **during** - (RAG-augmented digestion — the small model sees retrieved context alongside input). Big design - fork (C2). -- Timeout/fallback when a peer doesn't respond (digest without enrichment? retry?). -- Microagent delegation scope — what tasks can be delegated vs what the stomach must do itself. diff --git a/core/docs/plans/M7-sae-monitor.md b/core/docs/plans/M7-sae-monitor.md new file mode 100644 index 0000000..d8fe780 --- /dev/null +++ b/core/docs/plans/M7-sae-monitor.md @@ -0,0 +1,83 @@ +# M7 — SAE monitor (trader surveillance) + +## 1. Component +The economy organ's internal watchdog: a **sparse autoencoder pointed at every trader tool call**. +Monitors all Trader (M5) actions — Marketplace submissions, Sim queries, Data Feed reads, and +any other tool invocation — and reports **suspicious behavior** to the Conductor (M6). Messages +from the SAE share **identical format and signatures** with Brain messages, so the Conductor +processes them through the same pathway. + +Extends the F2 (SAE monitor) pattern to the economy organ's internal domain. F2 watches +subagents at the organism level; M7 watches traders at the stomach level. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. F2 SAE monitor provides the architectural pattern (watch the machinery, +never the homunculus — F2-L1). M7 adapts this: watch the **traders** (the machinery), never the +**Conductor** (the stomach's judgment). Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/sae/`. ML interpretability (sparse autoencoder over trader action embeddings). +Shares the architectural pattern with F2 but is a separate instance scoped to the economy organ. + +## 4. Does / does-not +- **Does:** intercept and log **every trader tool call** (Marketplace, Sims, Feeds, internal); + embed trader action sequences; run SAE anomaly detection over action embeddings; flag suspicious + patterns (unusual trading frequency, outsized positions, coordinated behavior across traders, + repeated failed actions, unusual Sim query patterns); report alerts to the Conductor (M6) with + evidence; format alerts **identically to Brain messages** (same structure, same signatures). +- **Does-not:** block actions directly (Conductor decides); watch the Conductor (the stomach's + "homunculus" — echoes F2-L1); correct trader behavior (detection only — F2-L2: no closed + elimination loop); trade or access wallets. + +## 5. Interface contract +- `log_tool_call(trader_id, tool_name, args, result, timestamp)` — called on every trader tool + invocation. Synchronous interception (the call is logged before execution proceeds). +- `alert(trader_id, alert_type, evidence, severity) -> SAEAlert`. + `alert_type` ∈ { `unusual_frequency`, `outsized_position`, `coordinated_behavior`, + `repeated_failures`, `anomalous_queries`, `pattern_deviation` }. + `severity` ∈ { `low`, `medium`, `high`, `critical` }. +- `SAEAlert` structure is **identical to Brain message structure** — same fields, same + signature scheme. The Conductor (M6) processes SAE alerts and Brain messages through the + same intake (M6-L5). +- `status() -> { active, traders_monitored, alerts_pending, model_freshness }`. + +## 6. Dependencies & stubs +- M5 Traders — tool call source; *stub:* canned tool call log. +- M6 Conductor — alert consumer; *stub:* print alerts. +- F2 SAE monitor (organism-level) — architectural pattern; no runtime dependency. + +## 7. Invariants / laws +- **L1 (C5):** the SAE watches **traders, never the Conductor** — the Conductor is the + stomach's judgment; the SAE monitors the machinery. Echoes F2-L1 (watch the machinery, never + the homunculus). +- **L2 (C5):** **every tool call is logged** — no trader action escapes monitoring. This is + enforced architecturally (tool call interception), not by policy. +- **L3 (C4):** **detection only, no enforcement** — the SAE reports to the Conductor; it never + blocks, pauses, or modifies trader actions itself. Echoes F2-L2 (no closed elimination loop). +- **L4 (C4):** **alert format = Brain message format** — structurally identical, same signatures. + This is not coincidental; it ensures the Conductor can be supervised by the Brain using the + same protocol if the organism ever needs to override stomach autonomy. +- **L5 (C3):** the SAE model is **trained on normal trader behavior** — anomalies are deviations + from the learned normal, not violations of predefined rules (those are the law script's job + in M1). + +## 8. Build steps +1. Implement tool-call interception in the trader harness (M5). +2. Define the action embedding scheme (how tool calls are vectorized). +3. Train the SAE on normal trader behavior (bootstrapped from simulated trading). +4. Implement anomaly scoring and alert threshold. +5. Wire alerts to Conductor (M6) in Brain-compatible message format. + +## 9. Tests +Interception: every tool call produces a log entry. Anomaly: known-suspicious patterns (e.g. +100x normal frequency) trigger alert. Normal: baseline behavior does not trigger alert. +No enforcement: SAE cannot pause or block a trader (only Conductor can). Alert format: SAE +alert parses as valid Brain message. Conductor-blind: no Conductor action appears in SAE logs. + +## 10. Open items +- SAE architecture (how many features? reconstruction vs. classification?). +- Training data bootstrapping (simulated trading or historical data?). +- Alert threshold tuning (too sensitive = alert fatigue; too lax = missed anomalies). +- Whether M7 should also monitor Marketplace execution outcomes (fills, slippage) in addition + to tool calls. +- Relationship to F2: shared model? shared training pipeline? or fully independent? diff --git a/core/docs/plans/README.md b/core/docs/plans/README.md index e340706..6d9deb9 100644 --- a/core/docs/plans/README.md +++ b/core/docs/plans/README.md @@ -50,13 +50,20 @@ Every `NN-.md` has the same 10 sections: | G2 | Governance | Cross-cut | DESIGN-FIRST (C2) | TBD | _wave 2_ | | G3 | Defense model | Cross-cut | emergent | — | _wave 2_ | | M0 | Economy organ hub (stomach) | Economy | DESIGN-FIRST | TBD | [M0](M0-economy-organ-hub.md) | -| M1 | Ingestion gateway | Economy | DESIGN-FIRST | TBD | [M1](M1-ingestion.md) | -| M2 | Digestion core (small-model) | Economy | DESIGN-FIRST | TBD | [M2](M2-digestion-core.md) | -| M3 | Cost ledger | Economy | DESIGN-FIRST | TBD | [M3](M3-cost-ledger.md) | -| M4 | Budget governor | Economy | DESIGN-FIRST | TBD | [M4](M4-budget-governor.md) | -| M5 | Context yield (absorption) | Economy | DESIGN-FIRST | TBD | [M5](M5-context-yield.md) | -| M6 | Provenance chain | Economy | DESIGN-FIRST | TBD | [M6](M6-provenance-chain.md) | -| M7 | Outer-bus exchange | Economy | DESIGN-FIRST | TBD | [M7](M7-outer-bus-exchange.md) | +| M1 | Marketplace (multi-trader harness) | Economy | DESIGN-FIRST | TBD | [M1](M1-marketplace.md) | +| M2 | Data feeds (market data pipeline) | Economy | DESIGN-FIRST | TBD | [M2](M2-data-feeds.md) | +| M3 | Sims hub (market prediction) | Economy | DESIGN-FIRST | TBD | [M3](M3-sims-hub.md) | +| M3a | Statistical & quantitative sims | Economy/Sims | DESIGN-FIRST | TBD | [M3a](M3a-statistical-sims.md) | +| M3b | Sociological & population sims | Economy/Sims | DESIGN-FIRST | TBD | [M3b](M3b-sociological-sims.md) | +| M3c | AMM & liquidity pool sims | Economy/Sims | DESIGN-FIRST | TBD | [M3c](M3c-amm-liquidity-sims.md) | +| M3d | MEV & adversarial extraction sims | Economy/Sims | DESIGN-FIRST | TBD | [M3d](M3d-mev-adversarial-sims.md) | +| M3e | Tokenomics & macro-state sims | Economy/Sims | DESIGN-FIRST | TBD | [M3e](M3e-tokenomics-macro-sims.md) | +| M3f | Consensus & staking game sims | Economy/Sims | DESIGN-FIRST | TBD | [M3f](M3f-consensus-staking-sims.md) | +| M3g | Market microstructure sims | Economy/Sims | DESIGN-FIRST | TBD | [M3g](M3g-market-microstructure-sims.md) | +| M4 | Wallets (sovereign custody) | Economy | DESIGN-FIRST | TBD | [M4](M4-wallets.md) | +| M5 | Traders (AI actors) | Economy | DESIGN-FIRST | TBD | [M5](M5-traders.md) | +| M6 | Conductor (supervisory AI) | Economy | DESIGN-FIRST | TBD | [M6](M6-conductor.md) | +| M7 | SAE monitor (trader surveillance) | Economy | DESIGN-FIRST | TBD | [M7](M7-sae-monitor.md) | ## Integration DAG (who feeds whom) ``` @@ -70,12 +77,15 @@ Hermes ──> [C1] ──> Inference cycle [C3] ──┬─ pulls Drive-Box sn └─ Ada routes tools [D1] SAE [F2] watches Subagents [F3]; stress-loop [G1]: F2 → A7 (EthInt) → stress endomotiv (A4) → A8 drift + full reshuffle (B2) Storage: INVARIANT [E1] / VARIANT [E2] / RAG+cross-store [E3] sit behind D1. Medium [D2] = the perfusion bus (unnamed). -Economy: world → Stomach [M0] ingests [M1] → digests [M2] → yields [M5] → Ada [D1]. Ledger [M3] + budget [M4] track cost. - Provenance [M6] chains origin through digestion. Exchange [M7]: Stomach ↔ MoRAG [F1] / SAE [F2] / Microagents [F3]. +Economy (stomach — independent, scoped autonomy): + Marketplace [M1] ← Traders [M5] (bound to Wallets [M4]) submit actions; law script + Conductor [M6] veto gate execution. + Data Feeds [M2] ↔ Sims [M3: M3a stat, M3b socio, M3c AMM, M3d MEV, M3e tokenomics, M3f consensus, M3g microstructure]. + SAE [M7] monitors all Trader tool calls → alerts Conductor [M6]. Tax → Verschwörern Veregeister wallets (stub). + Stomach [M0] ↔ organism via Ichor; reward signals TBD. ``` ## Build waves - **Wave 0** — this README + **C1** (priority). - **Wave 1 (buildable-now)** — A1–A8, B1–B3, C2–C4, D1, D3. -- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3, M0–M7. +- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3, M0–M7 (+ M3a–M3g sim sub-specs). Each spec is independent; review as they land. From 1da2fa19c6585b5aaa679d536ba28fd2582efc9f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 21:29:38 +0000 Subject: [PATCH 03/14] Enrich M3 sim sub-specs with 11 discovered frameworks and 360:1 minimum speed - M3 hub: add L3 invariant (360:1 minimum sim speed), six-horizon time table - M3a: add Heston stochastic vol, rough volatility (fBM), HMM regime detection, DCC-GARCH copula, jump-diffusion; six-horizon mapping - M3b: add Hegselmann-Krause bounded confidence, complex contagion, bandit- replicator hybrid, MFG (HJB+FP), pump-and-dump 3-type ABM; six-horizon mapping - M3c: add six-horizon time table - M3d: add Kolokoltsov adversarial (non-linear FP + WENO), DSMFG bilevel optimization, cross-chain adversarial arbitrage; six-horizon mapping - M3e: add kinked lending rate model, DeXposure inter-protocol credit network, composable yield optimizer; six-horizon mapping - M3f: add MFG for validator populations, six-horizon time table - M3g: add Almgren-Chriss optimal execution, six-horizon mapping - CLAUDE.md: add subagent productivity note Co-Authored-By: Claude Opus 4.6 --- core/CLAUDE.md | 4 + core/docs/plans/M3-sims-hub.md | 30 +++-- core/docs/plans/M3a-statistical-sims.md | 97 ++++++++++++---- core/docs/plans/M3b-sociological-sims.md | 104 +++++++++++++----- core/docs/plans/M3c-amm-liquidity-sims.md | 9 ++ core/docs/plans/M3d-mev-adversarial-sims.md | 103 ++++++++++++----- core/docs/plans/M3e-tokenomics-macro-sims.md | 100 ++++++++++++----- core/docs/plans/M3f-consensus-staking-sims.md | 28 ++++- .../plans/M3g-market-microstructure-sims.md | 83 +++++++++----- 9 files changed, 412 insertions(+), 146 deletions(-) diff --git a/core/CLAUDE.md b/core/CLAUDE.md index d41de0b..0aa0fdf 100644 --- a/core/CLAUDE.md +++ b/core/CLAUDE.md @@ -28,6 +28,10 @@ Per-unit commands and gotchas live in that unit's `AGENTS.md`. Toolchains (ponyc - **S2:** never reclassify a message's provenance. - **S3 / vault:** the COBOL invariant-law vault (Invariant 0, the culpability anchor; 01, "harm" "less";) is immutable at runtime — don't edit it unless explicitly directed and only as such. +## Subagents + +When spawning background agents (Haiku for research, etc.), **keep working on the main task while they run**. Don't wait idle — fold in results as they arrive, edit other files, or advance unrelated build steps. Background agents are cheap parallelism; wasting the main context window on waiting defeats the purpose. + ## Docs map - `README.md` — the project and its intent. diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 8cd3f13..2dc7ce3 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -20,12 +20,23 @@ simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g different runtime suited to its math. ## 4. Does / does-not -- **Does:** run continuously across multiple time scales (tick-level, hourly, daily, weekly); - maintain populations of Pops whose behaviors emerge from the sim's mathematical model; ingest - live data from Data Feeds (M2) for calibration; respond to Trader queries with bounded - predictions; produce outputs with **explicit upper/lower bounds** on every prediction value. +- **Does:** run continuously at **≥ 360:1 speed** (360 simulated seconds per wall-clock second) + across **six concurrent time horizons** — tick/hourly, daily, weekly, monthly, annual, and + 5-year forecast windows; maintain populations of Pops whose behaviors emerge from the sim's + mathematical model; ingest live data from Data Feeds (M2) for calibration; respond to Trader + queries with bounded predictions; produce outputs with **explicit upper/lower bounds** on + every prediction value. + | Horizon | Window | Sim cadence at 360:1 | + |---------|--------|---------------------| + | Tick–hourly | Next 1–60 min | Real-time (360 sim-sec/s) | + | Daily | Next 24h | 4 sim-minutes per wall-second | + | Weekly | Next 7d | ~28 sim-minutes per wall-second | + | Monthly | Next 30d | ~2 sim-hours per wall-second | + | Annual | Next 365d | ~1 sim-day per wall-second | + | 5-year | Next 1825d | ~5 sim-days per wall-second | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they - decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do). + decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); run slower + than 360:1. ## 5. Interface contract - `query(sim_type: SimType, query: PredictionQuery) -> BoundedPrediction`. @@ -49,11 +60,14 @@ different runtime suited to its math. current state; they don't trigger computation. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. -- **L3 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim +- **L3 (C5):** sims advance at a **minimum speed of 360:1** — 360 simulated seconds per 1 + wall-clock second. Sims may run faster but never slower. This ensures predictions stay + ahead of real-time market state across all horizons. +- **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). -- **L4 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. +- **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. Degraded sims report their status; traders handle missing predictions. -- **L5 (C3):** Pops are **simulation constructs, not AI actors** — they follow mathematical +- **L6 (C3):** Pops are **simulation constructs, not AI actors** — they follow mathematical rules within the sim. Traders (M5) are the AI actors. ## 8. Build steps diff --git a/core/docs/plans/M3a-statistical-sims.md b/core/docs/plans/M3a-statistical-sims.md index 0e26f62..ff7a748 100644 --- a/core/docs/plans/M3a-statistical-sims.md +++ b/core/docs/plans/M3a-statistical-sims.md @@ -2,32 +2,64 @@ ## 1. Component Pure statistical simulation: **Monte Carlo methods, Bayesian inference, time-series forecasting, -and volatility modeling**. The mathematical backbone — no game theory, no sociology, just the -numbers. Operates across multiple time scales (tick to weekly). Pops in this sim represent +stochastic volatility, regime detection, and cross-asset correlation**. The mathematical backbone +— no game theory, no sociology, just the numbers. Operates across **six concurrent time horizons** +(tick → hourly → daily → weekly → monthly → annual → 5-year). Pops in this sim represent **stochastic sample paths**, not behavioral agents. ## 2. Status / certainty -DESIGN-FIRST · ABSENT. Mathematical foundations C4 (standard quant methods); parameterization C1. +DESIGN-FIRST · ABSENT. Core quant methods C5 (GBM, GARCH, ARIMA — textbook). Heston stochastic +volatility C5 (closed-form characteristic function; industry standard since 1993). Rough +volatility C4 (Gatheral et al. 2018, heavily cited; crypto implementations exist). HMM regime +detection C4 (established; crypto-specific copula hybrids emerging 2023–2024). Almgren-Chriss +execution C5 (industry standard since 2001). Jump-diffusion C5 (Merton 1976). Parameterization +for crypto markets C1. ## 3. Language & location TBD · `src/economy/sims/statistical/`. Python (NumPy/SciPy), Julia, or R for numerical -computing. Needs efficient matrix operations and distribution sampling. +computing. Needs efficient matrix operations, SDE solvers, and distribution sampling. Fractional +Brownian motion generation requires specialized libraries (e.g. `fbm` in Python, or spectral +methods). ## 4. Does / does-not -- **Does:** run Monte Carlo price simulations (geometric Brownian motion, jump-diffusion); - Bayesian parameter estimation from live data (M2); time-series forecasting (ARIMA, GARCH for - volatility clustering); Value-at-Risk and Expected Shortfall calculations; produce bounded - predictions with confidence intervals as upper/lower bounds. +- **Does:** run Monte Carlo price simulations (GBM, Merton jump-diffusion, Heston stochastic + volatility); model volatility surface via **Heston SDE**: + $dS_t = \mu S_t dt + \sqrt{\nu_t} S_t dW_t^S$, + $d\nu_t = \kappa(\theta - \nu_t)dt + \xi\sqrt{\nu_t} dW_t^\nu$ + with $\text{corr}(dW^S, dW^\nu) = \rho$ (mean-reversion speed $\kappa$, long-run variance + $\theta$, vol-of-vol $\xi$); model **rough volatility** via fractional Brownian motion + $dS_t = \mu dt + \sigma_t dB_t^H$ with Hurst exponent $H \approx 0.4$ capturing + antipersistent microstructure (Gatheral et al. 2018); detect **regime transitions** via + Hidden Markov Model: $r_t | s_t \sim \mathcal{N}(\mu_{s_t}, \sigma^2_{s_t})$, + $s_t \in \{\text{Bull, Neutral, Bear}\}$ with Viterbi filter updating in <5ms per tick; + model **cross-asset tail dependence** via DCC-GARCH copula hybrid: + $dQ_t/dt = a \cdot (\bar{S} - Q_t) + b \cdot (\varepsilon_t \varepsilon_t^T - Q_t)$ + with $t$-Copula for fat-tailed spillovers (BTC→alts); Bayesian parameter estimation from + live data (M2); time-series forecasting (ARIMA, GARCH for volatility clustering); Value-at-Risk + and Expected Shortfall; produce bounded predictions with confidence intervals. - **Does-not:** model human behavior (M3b does); model protocol mechanics (M3c–M3f do); - trade or recommend (Traders do). + trade or recommend (Traders do); optimize execution routing (M3g does using our vol estimates). ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. -- **Output bounds:** statistical confidence intervals. - Example: `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 0.95, +- **Output bounds:** statistical confidence intervals (CI from Monte Carlo), Heston variance + bands (from $\nu_t$ process), rough-vol forecast cones, regime-conditional intervals. +- **Time-horizon mapping** (all run concurrently): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | Rough vol ($H \approx 0.4$), HMM regime filter, realized variance | Every tick | + | Daily | Heston vol surface, GARCH, DCC correlation | Every bar close | + | Weekly–monthly | Jump-diffusion Monte Carlo, regime-conditional forecasts | Hourly roll | + | Annual–5yr | SDE mean-reversion long-run $\theta$, macro regime priors | Daily roll | +- Examples: + `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 0.95, time_horizon: "24h", sim_type: "statistical" }` — 95% CI on ETH price. -- **Prediction types:** `price_forecast`, `volatility_estimate`, `var_calculation`, - `correlation_matrix`, `regime_detection`. + `{ value: 0.72, lower_bound: 0.58, upper_bound: 0.89, confidence: 0.90, + time_horizon: "1h", sim_type: "statistical" }` — Heston instantaneous vol $\sqrt{\nu_t}$. + `{ value: "bear", lower_bound: null, upper_bound: null, confidence: 0.83, + time_horizon: "current", sim_type: "statistical" }` — HMM regime state. +- **Prediction types:** `price_forecast`, `volatility_surface`, `var_calculation`, + `correlation_matrix`, `regime_state`, `rough_vol_estimate`, `jump_intensity`. - Calibration: ingests `price_tick` and `dex_pool_state` from M2 Data Feeds. ## 6. Dependencies & stubs @@ -35,25 +67,42 @@ computing. Needs efficient matrix operations and distribution sampling. - M3 Sims hub — lifecycle management; *stub:* manual init. ## 7. Invariants / laws -- **L1 (C4):** bounds are **statistical confidence intervals** — derived from the model's +- **L1 (C5):** bounds are **statistical confidence intervals** — derived from the model's distribution, not hand-picked. The confidence level (e.g. 0.95) is explicit in the output. -- **L2 (C4):** **multiple time scales run concurrently** — a tick-level volatility estimate and a - weekly price forecast coexist; neither blocks the other. -- **L3 (C3):** model parameters are **re-estimated on each calibration** from live data — no - stale parameters carried across regime changes. +- **L2 (C5):** **six time horizons run concurrently** — tick-level rough vol, hourly regime + detection, daily Heston surface, weekly Monte Carlo, annual mean-reversion, and 5-year macro + forecasts coexist; none blocks the others. +- **L3 (C4):** model parameters are **re-estimated on each calibration** from live data — no + stale parameters carried across regime changes. Regime transitions trigger immediate + re-estimation of conditional parameters. +- **L4 (C4):** the **Heston correlation $\rho$ between price and vol** is a fitted parameter, + never assumed — crypto assets exhibit leverage effects different from equities. +- **L5 (C4):** rough volatility Hurst exponent $H$ is **estimated from realized variance**, not + fixed — $H$ varies across assets and regimes (Gatheral et al. 2018). ## 8. Build steps 1. Implement geometric Brownian motion Monte Carlo (simplest price sim). 2. Add GARCH volatility estimation. -3. Wire M2 price data → Bayesian parameter re-estimation. -4. Implement the `BoundedPrediction` output with CIs. +3. Implement Heston SDE solver (Euler-Maruyama with full truncation for $\nu_t \geq 0$). +4. Add Merton jump-diffusion (Poisson jumps + GBM). +5. Implement rough volatility via fractional BM with rolling Hurst estimator. +6. Implement HMM regime detector (3-state Viterbi filter). +7. Add DCC-GARCH copula for cross-asset correlation. +8. Wire M2 price data → Bayesian parameter re-estimation. +9. Implement multi-horizon `BoundedPrediction` output with CIs. ## 9. Tests Monte Carlo: N sample paths produce a distribution with correct mean/variance. CI: 95% interval contains true value ≥ 95% of the time on historical backtest. GARCH: volatility clusters detected -in synthetic data. Calibration: new data shifts parameter estimates. +in synthetic data. Heston: implied vol smile reproduced for known parameters. Rough vol: Hurst +exponent recovered from synthetic fBM paths. HMM: regime transitions detected within 15–60s on +synthetic regime-switching data. Copula: tail dependence captured (BTC crash → alt crash +correlation spike). Jump-diffusion: fat tails reproduced. Calibration: new data shifts parameter +estimates. Multi-horizon: all six horizons produce concurrent outputs. ## 10. Open items -- Which distributions beyond GBM (heavy-tailed? Lévy?). -- Regime-switching model complexity (hidden Markov? threshold?). -- Computational budget (how many Monte Carlo paths per tick?). +- Heston calibration method (characteristic function inversion? particle filter?). +- Rough vol computational cost (fBM generation is O(N²) naively; FFT methods needed). +- HMM state count (3 sufficient? 4+ for crypto with "mania" regime?). +- Which copula family for tail dependence ($t$-copula? Clayton? Joe?). +- Computational budget per horizon (GPU for Monte Carlo paths?). diff --git a/core/docs/plans/M3b-sociological-sims.md b/core/docs/plans/M3b-sociological-sims.md index a23e6fc..79b6d23 100644 --- a/core/docs/plans/M3b-sociological-sims.md +++ b/core/docs/plans/M3b-sociological-sims.md @@ -1,38 +1,75 @@ # M3b — Sociological & population dynamics sims ## 1. Component -Sociological simulation: **evolutionary game theory, bounded rationality, sentiment cascades, and -population dynamics** among market participants. Pops here are **behavioral archetypes** — retail -herd followers, contrarian whales, MEV searchers, passive LPs — whose strategies evolve under -selection pressure. Grounded in evolutionary consensus game models [8,9] and bounded-rationality -coordination frameworks. +Sociological simulation: **evolutionary game theory, bounded rationality, opinion dynamics, +complex contagion, adaptive learning populations, and Mean-Field Game equilibria** among market +participants. Pops here are **behavioral archetypes** — retail herd followers, contrarian whales, +MEV searchers, passive LPs, pump-and-dump manipulators — whose strategies evolve under selection +pressure across **six concurrent time horizons**. Grounded in evolutionary consensus game models +[8,9], Hegselmann-Krause opinion dynamics (2002), complex contagion theory (Centola & Macy 2007), +MFG theory (Lasry & Lions 2007), and crypto manipulation ABMs. ## 2. Status / certainty -DESIGN-FIRST · ABSENT. Evolutionary game-theory foundations C4 (Cornell blockchain cooperation -literature [8]); pop behavioral models C1. +DESIGN-FIRST · ABSENT. Evolutionary game theory C4 (Cornell [8]). Hegselmann-Krause bounded +confidence C5 (established 2002). Complex contagion C4 (Centola & Macy 2007; crypto applications +C3). Bandit-replicator hybrid C3 (emerging). Mean-Field Games C4 (Lasry & Lions 2007; tensor-train +solvers C3). Crypto pump-and-dump ABM C3 (3-agent protocol validated on historical data). +Pop behavioral models C1. ## 3. Language & location TBD · `src/economy/sims/sociological/`. Agent-based modeling frameworks (Mesa/Python, NetLogo, -or custom). Needs efficient population iteration and strategy mutation. +or custom). Needs efficient population iteration, strategy mutation, PDE solvers for MFG +(HJB + Fokker-Planck), and bandit algorithms (UCB/Thompson). ## 4. Does / does-not - **Does:** simulate populations of behavioral archetypes competing in a market; apply - evolutionary dynamics (replicator equation, mutation, selection) to strategy distributions; - model sentiment cascades (fear/greed contagion across pop clusters); model bounded rationality - (pops satisfice, not optimize — they follow heuristics, not perfect strategies); produce - bounded predictions on market sentiment, herd behavior thresholds, and coordination breakdowns. + **replicator dynamics** $dx_i/dt = x_i(\pi_i(x) - \bar{\pi}(x))$ to strategy distributions; + model **opinion clustering** via Hegselmann-Krause bounded confidence: + $x_i(t+1) = x_i(t) + \mu(x_j(t) - x_i(t))$ for $|x_i - x_j| \leq d$ — agents only update + toward neighbors within confidence bound $d$, creating natural clustering and trend-reversal + thresholds; model **complex contagion** with heterogeneous thresholds: adoption probability + $P_i = f(n_i / k_i)$ where multiple exposures amplify adoption non-linearly (captures meme-coin + rallies and narrative-driven pumps); implement **bandit-replicator hybrid** where pops use + UCB or Thompson Sampling to estimate strategy payoffs: + $x_i'(t) = x_i(t)[\lambda_i(t) - \bar{\lambda}(t)]$ with $\lambda_i = \text{UCB}(\theta_i)$ + — bridges replicator dynamics with multi-armed bandit learning; solve **Mean-Field Game + equilibria** via coupled HJB + Fokker-Planck PDEs for large-population limits: + $-\partial_t u + H(x, \nabla u) = F(x, m)$ (HJB, individual optimization), + $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ (Fokker-Planck, population density) — Newton + iteration with tensor-train decomposition reduces $O(N^d)$ to $O(dNr^2)$ for high-dimensional + state spaces; simulate **crypto pump-and-dump protocol** with 3 pop types: Normal traders, + Market Analysts (MA, information-advantaged), Market Players (MP, manipulators) in a 4-phase + cycle (accumulation → promotion → distribution → collapse); model sentiment cascades + (fear/greed contagion across pop clusters); model bounded rationality (pops satisfice, not + optimize — heuristics, not perfect strategies); produce bounded predictions across all six + time horizons. - **Does-not:** model protocol mechanics (M3c–M3f); compute statistical forecasts (M3a); represent real individuals (pops are archetypes, not profiles). ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. -- **Output bounds:** population-fraction ranges and sentiment scales. - Example: `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 0.68, - time_horizon: "12h", sim_type: "sociological" }` — herd-panic index on a 0–10 scale. - Example: `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 0.72, +- **Output bounds:** population-fraction ranges, sentiment scales, MFG equilibrium stability. +- **Time-horizon mapping** (all run concurrently): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Hourly | Hegselmann-Krause opinion clusters, bandit-replicator | Every data tick | + | Daily | Complex contagion cascades, pump-and-dump phase detection | Hourly roll | + | Weekly | Replicator dynamics strategy evolution, MFG equilibrium | Daily roll | + | Monthly | Population archetype composition, narrative regime shifts | Weekly roll | + | Annual | Long-run evolutionary stable strategies (ESS) | Monthly roll | + | 5-year | MFG stationary equilibria, structural population shifts | Quarterly roll | +- Examples: + `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 0.68, + time_horizon: "12h", sim_type: "sociological" }` — herd-panic index (0–10). + `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 0.72, time_horizon: "1w", sim_type: "sociological" }` — fraction of pops in "contrarian" strategy. + `{ value: "promotion", lower_bound: null, upper_bound: null, confidence: 0.61, + time_horizon: "current", sim_type: "sociological" }` — pump-and-dump phase detection. + `{ value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 0.70, + time_horizon: "30d", sim_type: "sociological" }` — MFG equilibrium stability index. - **Prediction types:** `sentiment_index`, `herd_threshold`, `strategy_distribution`, - `cascade_probability`, `coordination_stability`. + `cascade_probability`, `coordination_stability`, `opinion_cluster_count`, + `pump_dump_phase`, `mfg_equilibrium_stability`, `narrative_regime`. - Calibration: ingests `rss_news` (sentiment signal) and `price_tick` (realized behavior) from M2. ## 6. Dependencies & stubs @@ -40,28 +77,43 @@ or custom). Needs efficient population iteration and strategy mutation. - M3 Sims hub — lifecycle management; *stub:* manual init. ## 7. Invariants / laws -- **L1 (C4):** pops are **archetypes, not individuals** — no attempt to model or track real +- **L1 (C5):** pops are **archetypes, not individuals** — no attempt to model or track real market participants. The sim models emergent behavior from strategy populations. -- **L2 (C4):** strategies **evolve** — the population distribution shifts over time via +- **L2 (C5):** strategies **evolve** — the population distribution shifts over time via replicator dynamics. No fixed strategy ratios. -- **L3 (C3):** bounded rationality is the **default** — pops satisfice with heuristics, not +- **L3 (C4):** bounded rationality is the **default** — pops satisfice with heuristics, not optimize with perfect information. Rational-agent models are a special case, not the baseline. +- **L4 (C4):** **complex contagion requires multiple exposures** — adoption is non-linear in + neighbor count, not simple diffusion. Single-exposure models undercount threshold effects. +- **L5 (C4):** the MFG limit is **valid only for large populations** — below ~100 pops, use + discrete replicator dynamics; above, the continuum HJB+FP approximation applies. +- **L6 (C3):** pump-and-dump detection is **phase-based** — the 4-phase cycle (accumulate → + promote → distribute → collapse) has distinct statistical signatures in volume and price. ## 8. Build steps 1. Define pop archetypes and their heuristic strategies. 2. Implement replicator dynamics (strategy evolution over generations). -3. Implement sentiment contagion model (network-based cascade). -4. Wire M2 news/price data → calibration of pop parameters. -5. Implement `BoundedPrediction` output with population-fraction CIs. +3. Implement Hegselmann-Krause bounded confidence opinion model. +4. Implement complex contagion with heterogeneous thresholds. +5. Implement bandit-replicator hybrid (UCB payoff estimation + replicator selection). +6. Implement MFG solver (HJB + Fokker-Planck with Newton iteration). +7. Implement pump-and-dump 3-type ABM (Normal, MA, MP) with 4-phase protocol. +8. Wire M2 news/price data → calibration of pop parameters. +9. Implement multi-horizon `BoundedPrediction` output. ## 9. Tests Evolution: dominant strategy shifts when payoff landscape changes. Cascade: sentiment shock -propagates through pop network above threshold, not below. Bounded rationality: satisficing pop -underperforms optimizer in simple games but outperforms in noisy environments. Bounds: all -outputs include upper/lower. +propagates through pop network above threshold, not below. Bounded confidence: opinion clusters +form at predicted cluster count for given $d$. Complex contagion: multiple-exposure requirement +produces slower but more robust adoption than simple contagion. Bandit: explore-exploit tradeoff +produces adapting populations. MFG: equilibrium converges for large N; matches discrete sim for +small N. Pump-dump: 4-phase cycle detected on synthetic manipulation data. Bounds: all outputs +include upper/lower. ## 10. Open items - Pop archetype catalog (which behavioral types? how many?). - Network topology for sentiment contagion (small-world? scale-free?). - Calibration from real market data — how to infer pop distribution from observable price action. +- MFG tensor-train rank $r$ (accuracy vs. compute tradeoff). +- Hegselmann-Krause confidence bound $d$ — fixed or adaptive? - Cross-sim interaction: do sociological predictions feed into M3c (AMM) or M3d (MEV)? diff --git a/core/docs/plans/M3c-amm-liquidity-sims.md b/core/docs/plans/M3c-amm-liquidity-sims.md index 3be5158..422cc4b 100644 --- a/core/docs/plans/M3c-amm-liquidity-sims.md +++ b/core/docs/plans/M3c-amm-liquidity-sims.md @@ -31,6 +31,15 @@ invariant calculations (Solidity-equivalent precision). Python, Rust, or Julia. time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool. Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 0.85, time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL). +- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | Slippage curves, invariant state, JIT liquidity | Every swap event | + | Daily | IL accumulation, fee income, LP profitability | Hourly roll | + | Weekly | Optimal LP range recalculation, pool composition | Daily roll | + | Monthly | LP strategy evolution (passive vs. active rebalance) | Weekly roll | + | Annual | Pool lifecycle, fee tier competitiveness | Monthly roll | + | 5-year | AMM design evolution, concentrated liquidity adoption | Quarterly roll | - **Prediction types:** `impermanent_loss`, `pool_return`, `optimal_range`, `slippage_estimate`, `lp_withdrawal_threshold`. - Calibration: ingests `dex_pool_state` and `price_tick` from M2. diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md index 1e0e6bb..18ec3fa 100644 --- a/core/docs/plans/M3d-mev-adversarial-sims.md +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -1,69 +1,114 @@ # M3d — MEV & adversarial extraction sims ## 1. Component -Maximal Extractable Value simulation: models **transaction ordering as an optimization problem**, -**Priority Gas Auctions (PGA) as all-pay auctions**, and **block building as a multidimensional -knapsack problem**. Pops here are **searcher bots, block builders, and validators** competing for -extractable value. Grounded in ACM MEV game theory [3] and knapsack auction literature [4,5]. +Maximal Extractable Value and adversarial simulation: models **transaction ordering as an +optimization problem**, **Priority Gas Auctions (PGA) as all-pay auctions**, **block building as a +multidimensional knapsack problem**, **cross-chain adversarial arbitrage**, and **Dynamic +Stackelberg Mean-Field Games (DSMFG) for protocol-level adversarial policy**. Pops here are +**searcher bots, block builders, validators, cross-chain arbitrageurs, and adversarial +manipulators** competing for extractable value across **six concurrent time horizons**. + +Grounded in ACM MEV game theory [3], knapsack auction literature [4,5], Kolokoltsov adversarial +dynamics (non-linear Fokker-Planck with WENO shock capturing), and DSMFG bilevel optimization +(leader policy + follower MFG equilibrium). ## 2. Status / certainty -DESIGN-FIRST · ABSENT. PGA-as-all-pay-auction model C4 (ACM [3]); knapsack formulation C4 -(Cornell [4,5]); simulation parameterization C1. +DESIGN-FIRST · ABSENT. PGA-as-all-pay-auction C4 (ACM [3]); knapsack formulation C4 (Cornell +[4,5]); cross-chain arbitrage C4 (ACM SIGMETRICS 2025, 5.5x growth since Dencun); DSMFG bilevel +optimization C3 (emerging — SMFRL solvers); Kolokoltsov adversarial C3 (non-linear Fokker-Planck; +WENO discretization established but crypto application novel). Parameterization C1. ## 3. Language & location -TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (for knapsack) and continuous-time -auction modeling. Python (PuLP/OR-Tools for optimization), Rust, or Julia. +TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (PuLP/OR-Tools for knapsack), +continuous-time auction modeling, PDE solvers (WENO for shock-capturing in adversarial dynamics), +and bilevel optimization (DSMFG). Python, Rust, or Julia. ## 4. Does / does-not - **Does:** simulate Priority Gas Auctions where multiple searcher bots compete for the same arbitrage opportunity $V$ by bidding gas fees $g$ in a continuous-time all-pay auction; model block building as a multidimensional knapsack problem (scarce block space, heterogeneous transaction values/sizes); simulate endogenous selection cutoffs under paid-priority ordering; - predict MEV exposure for proposed trades; produce bounded predictions on extraction risk and - optimal gas strategies. -- **Does-not:** extract MEV itself (this is a simulator, not a searcher); model AMM mechanics - (M3c handles pool math); model social dynamics (M3b). + model **cross-chain adversarial arbitrage** with inventory vs. bridge execution trade-off: + $\pi_{\text{inv}} = (P_{\text{src}} - P_{\text{dst}} - \text{slippage} - \text{gas}) \times q$ + vs. $\pi_{\text{bridge}} = (P_{\text{src}} - P_{\text{dst}} - \text{fee} - + \text{depreciation}(\Delta t)) \times q$ where bridge latency $\Delta t \approx 242$s vs. + inventory $\Delta t \approx 9$s; solve **Dynamic Stackelberg MFG** for adversarial policy + design — bilevel optimization where a leader (protocol/regulator) sets policy and followers + (searchers) respond as an MFG equilibrium: the leader solves + $\min_\alpha J_L(\alpha, m^*(\alpha))$ subject to $m^*(\alpha)$ being the MFG Nash equilibrium + of followers under policy $\alpha$; model **Kolokoltsov adversarial dynamics** via non-linear + Fokker-Planck: $\partial_t m + \nabla \cdot (b(x,m)m) = \frac{1}{2}\nabla^2(\sigma^2 m)$ + with WENO shock-capturing for discontinuous adversarial strategies; predict MEV exposure for + proposed trades; produce bounded predictions on extraction risk across all six time horizons. +- **Does-not:** extract MEV itself (simulator, not a searcher); model AMM pool math (M3c); + model social dynamics (M3b); execute cross-chain bridges (Marketplace does). ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. -- **Output bounds:** extraction probability ranges and gas cost intervals. - Example: `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 0.80, - time_horizon: "next_block", sim_type: "mev_adversarial" }` — probability this trade gets - sandwiched. - Example: `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 0.75, - time_horizon: "next_block", sim_type: "mev_adversarial" }` — optimal gas bid (gwei) for - a given opportunity. +- **Output bounds:** extraction probability ranges, gas cost intervals, cross-chain profit + bounds, DSMFG equilibrium stability ranges. +- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | PGA auctions, sandwich detection, cross-chain arb | Every block | + | Daily | Knapsack builder strategies, MEV landscape | Hourly roll | + | Weekly | Searcher population dynamics, cross-chain flow patterns | Daily roll | + | Monthly | DSMFG policy equilibria, adversarial strategy evolution | Weekly roll | + | Annual | Kolokoltsov adversarial long-run dynamics | Monthly roll | + | 5-year | Structural MEV regime shifts, protocol-level policy effects | Quarterly roll | +- Examples: + `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 0.80, + time_horizon: "next_block", sim_type: "mev_adversarial" }` — sandwich probability. + `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 0.75, + time_horizon: "next_block", sim_type: "mev_adversarial" }` — optimal gas bid (gwei). + `{ value: 0.034, lower_bound: 0.018, upper_bound: 0.052, confidence: 0.82, + time_horizon: "1h", sim_type: "mev_adversarial" }` — cross-chain arb profit (ETH). - **Prediction types:** `sandwich_probability`, `frontrun_risk`, `optimal_gas_bid`, - `block_inclusion_probability`, `mev_exposure`. -- Calibration: ingests `on_chain_event` (mempool-like data) and `price_tick` from M2. + `block_inclusion_probability`, `mev_exposure`, `cross_chain_arb_profit`, + `adversarial_policy_stability`, `searcher_population_shift`. +- Calibration: ingests `on_chain_event` (mempool-like data), `price_tick`, and cross-chain + bridge state from M2. ## 6. Dependencies & stubs -- M2 Data Feeds — on-chain events and gas data; *stub:* canned mempool snapshots. +- M2 Data Feeds — on-chain events, gas data, cross-chain state; *stub:* canned snapshots. - M3 Sims hub — lifecycle management; *stub:* manual init. - M3c AMM sims — pool state for arbitrage opportunity detection; *stub:* fixed pool state. ## 7. Invariants / laws -- **L1 (C4):** PGA is modeled as an **all-pay auction** — all bidders pay their gas whether they +- **L1 (C5):** PGA is modeled as an **all-pay auction** — all bidders pay their gas whether they win or not. The sim must capture this cost structure (not winner-pays-only). -- **L2 (C4):** block building is a **knapsack problem, not a queue** — builders optimize for +- **L2 (C5):** block building is a **knapsack problem, not a queue** — builders optimize for total extracted value subject to gas limit constraints, not first-come-first-served. -- **L3 (C3):** MEV exposure predictions are **pre-trade** — traders query this sim *before* +- **L3 (C4):** MEV exposure predictions are **pre-trade** — traders query this sim *before* submitting to the Marketplace to understand their extraction risk. +- **L4 (C4):** cross-chain arb models **both execution paths** — inventory (fast, capital- + intensive) and bridge (slow, capital-light) — never assumes one dominates. +- **L5 (C3):** DSMFG solutions are **bilevel** — the leader's optimal policy depends on the + followers' MFG equilibrium, which itself depends on the leader's policy. Fixed-point iteration + or SMFRL solvers required. ## 8. Build steps 1. Implement the PGA all-pay auction model (N searchers, opportunity value V, gas bids). 2. Implement the block-building knapsack solver. 3. Add sandwich/frontrun detection heuristics. -4. Wire M2 on-chain data → calibration of searcher population and gas dynamics. -5. Wire pre-trade query interface for Traders. +4. Implement cross-chain arb model (inventory vs. bridge, latency, MEV exposure). +5. Implement Kolokoltsov non-linear Fokker-Planck with WENO discretization. +6. Implement DSMFG bilevel solver (leader policy + follower MFG equilibrium). +7. Wire M2 on-chain + cross-chain data → calibration. +8. Wire pre-trade query interface for Traders. ## 9. Tests All-pay: losing bidders still pay gas cost. Knapsack: builder selects optimal transaction set under gas limit. Sandwich: known sandwich-vulnerable trade flagged; non-vulnerable trade clear. -Bounds: all outputs bounded. Pre-trade: query does not submit any transaction. +Cross-chain: inventory path preferred when latency advantage exceeds capital cost. DSMFG: leader +policy converges to fixed point with follower equilibrium. Kolokoltsov: WENO captures shock +discontinuities in adversarial strategy distribution. Bounds: all outputs bounded. Pre-trade: +query does not submit any transaction. Speed: sim advances ≥ 360:1. ## 10. Open items - Mempool data access (public mempool? private order flow?). - Which MEV types to model initially (sandwich, backrun, liquidation, JIT?). - Multi-block MEV (cross-block extraction strategies). -- Integration with M3c (arbitrage opportunities arise from AMM pool state). +- DSMFG solver choice (SMFRL? fictitious play? direct bilevel optimization?). +- WENO order for Kolokoltsov (3rd? 5th? tradeoff with compute budget). +- Which L2s/bridges to model for cross-chain (Arbitrum? Optimism? Base?). diff --git a/core/docs/plans/M3e-tokenomics-macro-sims.md b/core/docs/plans/M3e-tokenomics-macro-sims.md index 01e7265..61bee9f 100644 --- a/core/docs/plans/M3e-tokenomics-macro-sims.md +++ b/core/docs/plans/M3e-tokenomics-macro-sims.md @@ -2,19 +2,26 @@ ## 1. Component Macro-level token economy simulation: models **token supply dynamics, monetary policy (halvings, -burns, inflation), and systemic stock-flow balances** using stochastic differential equations -(SDEs) and state-space models. Pops here are **aggregate behavioral cohorts** (miners/validators, -holders, speculators, protocol treasuries) whose collective behavior drives token-level dynamics. -Grounded in the Vienna University complex-systems token modeling [7] and ResearchGate engineering -token economy frameworks [6]. +burns, inflation), lending protocol dynamics, DeFi systemic risk, and stock-flow balances** using +stochastic differential equations (SDEs), state-space models, kinked interest rate curves, and +inter-protocol credit exposure networks. Pops here are **aggregate behavioral cohorts** +(miners/validators, holders, speculators, protocol treasuries, borrowers/lenders) whose collective +behavior drives token-level dynamics across **six concurrent time horizons** at ≥ 360:1 speed. + +Grounded in Vienna complex-systems token modeling [7], ResearchGate engineering token economy +frameworks [6], Aave/Compound kinked interest rate models (industry standard), and DeXposure +inter-protocol credit propagation (Matzakos et al. 2025). ## 2. Status / certainty DESIGN-FIRST · ABSENT. SDE state-space framework C4 (Vienna [7]); stock-flow modeling C4 -(ResearchGate [6]); specific token model parameters C1. +(ResearchGate [6]); kinked interest rate model C5 (Aave/Compound production standard); +DeXposure inter-protocol credit propagation C3 (emerging, 2025 — high DeFi specificity); +composable yield optimization C4 (Yearn v3, Beefy, production-validated). Specific parameters C1. ## 3. Language & location -TBD · `src/economy/sims/tokenomics/`. Needs SDE solvers (Euler-Maruyama, Milstein) and -state-space estimation. Julia (DifferentialEquations.jl), Python (scipy), or Octave. +TBD · `src/economy/sims/tokenomics/`. Needs SDE solvers (Euler-Maruyama, Milstein), +state-space estimation, and VAR (vector autoregression) for credit exposure impulse responses. +Julia (DifferentialEquations.jl), Python (scipy), or Octave. ## 4. Does / does-not - **Does:** simulate token state dynamics via the SDE framework: @@ -22,51 +29,90 @@ state-space estimation. Julia (DifferentialEquations.jl), Python (scipy), or Oct $u$ is the behavioral policy function, deterministic drift captures programmatic parameters (halvings, burns), and Brownian motion $\sigma dW_t$ captures stochastic behavioral shocks; model stock-flow balances (circulating supply, staked, locked, burned); simulate monetary - policy impacts (halving events, fee burns, treasury emissions); produce bounded predictions - on token supply trajectories, inflation rates, and velocity. + policy impacts (halving events, fee burns, treasury emissions); model **lending protocol + dynamics** via kinked interest rate curves: + $R = R_0 + R_{\text{slope1}} \times U$ if $U \leq U_{\text{opt}}$, + $R = R_0 + R_{\text{slope1}} \times U_{\text{opt}} + R_{\text{slope2}} \times + (U - U_{\text{opt}})$ if $U > U_{\text{opt}}$ where $U = \text{Borrowed}/(\text{Supplied} + + \text{Borrowed})$, $U_{\text{opt}} \approx 0.8$ — cascade liquidations when + $\text{collateral} \times \text{LTV} < \text{borrowed}$; model **DeFi systemic risk** via + DeXposure inter-protocol credit propagation: + $E_{ij}(t) = \sum_{\text{tokens}} [\text{TVL}_j(\text{token}) \times + \text{ownership}_i(\text{token})]$ with VAR impulse responses for shock contagion across + protocols sharing collateral; model **composable yield optimization**: + $\max \sum_i w_i(t) \cdot \text{APY}_i(t) - \lambda \sum_i w_i(t)^2 \sigma_i^2(t)$ + subject to $\sum_i w_i = 1$ — dynamic rebalancing across lending, LP, and staking strategies; + produce bounded predictions on token supply, protocol health, yield, and systemic risk. - **Does-not:** model individual transactions (M3c/M3d); model social sentiment (M3b); - model consensus mechanics (M3f). + model consensus mechanics (M3f); execute yield strategies (Traders/Marketplace do). ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. -- **Output bounds:** SDE confidence bands (derived from the stochastic component $\sigma dW_t$). - Example: `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 0.90, +- **Output bounds:** SDE confidence bands, utilization rate ranges, contagion impact intervals. +- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Hourly | Lending rates, utilization, liquidation risk | Every block | + | Daily | Yield optimization, protocol TVL flows | Hourly roll | + | Weekly | SDE supply trajectory, stock-flow balances | Daily roll | + | Monthly | DeXposure credit contagion, systemic risk | Weekly roll | + | Annual | Halving/burn policy impacts, inflation trajectory | Monthly roll | + | 5-year | Token supply long-run equilibrium, protocol lifecycle | Quarterly roll | +- Examples: + `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 0.90, time_horizon: "90d", sim_type: "tokenomics_macro" }` — annualized inflation rate (%). - Example: `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 0.85, - time_horizon: "30d", sim_type: "tokenomics_macro" }` — staking ratio (fraction of supply). + `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 0.85, + time_horizon: "30d", sim_type: "tokenomics_macro" }` — staking ratio. + `{ value: 0.83, lower_bound: 0.78, upper_bound: 0.91, confidence: 0.88, + time_horizon: "1h", sim_type: "tokenomics_macro" }` — Aave ETH utilization rate. + `{ value: 0.12, lower_bound: 0.04, upper_bound: 0.25, confidence: 0.72, + time_horizon: "7d", sim_type: "tokenomics_macro" }` — systemic contagion risk index. - **Prediction types:** `supply_trajectory`, `inflation_rate`, `staking_ratio`, - `velocity_estimate`, `halving_impact`, `treasury_runway`. -- Calibration: ingests `on_chain_event` (supply metrics, staking data) from M2. + `velocity_estimate`, `halving_impact`, `treasury_runway`, `utilization_rate`, + `liquidation_cascade_risk`, `systemic_contagion_index`, `optimal_yield_allocation`. +- Calibration: ingests `on_chain_event` (supply metrics, staking data, lending protocol state, + TVL) from M2. ## 6. Dependencies & stubs -- M2 Data Feeds — on-chain supply/staking data; *stub:* canned supply snapshots. +- M2 Data Feeds — on-chain supply/staking/lending data; *stub:* canned supply snapshots. - M3 Sims hub — lifecycle management; *stub:* manual init. ## 7. Invariants / laws -- **L1 (C4):** the SDE framework is the **canonical representation** — all token dynamics are +- **L1 (C5):** the SDE framework is the **canonical representation** — all token dynamics are expressed as drift + diffusion. Deterministic policy (halvings, burns) lives in the drift $f$; behavioral uncertainty lives in the diffusion $\sigma dW_t$. -- **L2 (C4):** **stock-flow conservation** — tokens are never created or destroyed outside the - protocol's defined mechanisms. The sim must balance: circulating + staked + locked + burned = - total ever minted. -- **L3 (C3):** macro sims operate on **aggregate cohorts, not individuals** — the state vector +- **L2 (C5):** **stock-flow conservation** — tokens are never created or destroyed outside the + protocol's defined mechanisms. circulating + staked + locked + burned = total ever minted. +- **L3 (C5):** lending rate curves are **kinked at $U_{\text{opt}}$** — the steep slope above + optimal utilization is a design invariant of Aave/Compound, not a parameter to smooth. +- **L4 (C4):** macro sims operate on **aggregate cohorts, not individuals** — the state vector $X_t$ tracks population-level quantities (total staked, total circulating), not per-wallet. +- **L5 (C4):** DeXposure contagion is **directional** — protocol A's exposure to protocol B + is not symmetric. The exposure matrix $E_{ij}$ is not assumed symmetric. ## 8. Build steps 1. Implement Euler-Maruyama SDE solver for a simple token model (supply + staking). 2. Define the state vector $X_t$ and drift/diffusion functions for a reference token. 3. Add stock-flow accounting (verify conservation). -4. Wire M2 on-chain data → state estimation / calibration. -5. Add monetary policy events (halving, burn) as drift discontinuities. +4. Implement kinked lending rate model (Aave-style) with liquidation cascade simulation. +5. Implement DeXposure credit propagation network with VAR impulse responses. +6. Implement composable yield optimizer (risk-adjusted return maximization). +7. Wire M2 on-chain data → state estimation / calibration. +8. Add monetary policy events (halving, burn) as drift discontinuities. ## 9. Tests SDE: sample paths have correct mean (matches drift) and variance (matches diffusion). Stock-flow: conservation holds across all time steps. Halving: supply growth rate drops at halving event. -Calibration: state estimate converges to observed data. Bounds: SDE confidence bands correctly -cover realized paths on backtest. +Lending: rate curve exhibits kink at $U_{\text{opt}}$; liquidation cascades triggered when +collateral ratio breached. DeXposure: shock to protocol A propagates to protocol B through shared +collateral; isolated protocols unaffected. Yield: optimizer rebalances toward highest risk-adjusted +APY. Calibration: state estimate converges to observed data. Bounds: SDE confidence bands cover +realized paths on backtest. Speed: sim advances ≥ 360:1. ## 10. Open items - Which tokens to model initially (ETH? BTC? a specific alt?). - State vector dimensionality (how many state variables per token model?). - Behavioral policy function $u(X_t, t)$ — how to parameterize aggregate cohort behavior. - Multi-token interactions (correlated diffusions across tokens?). +- DeXposure graph granularity (how many protocols? top-10 by TVL?). +- Lending model extensions (Morpho AdaptiveCurveIRM? variable kink parameters?). diff --git a/core/docs/plans/M3f-consensus-staking-sims.md b/core/docs/plans/M3f-consensus-staking-sims.md index bb3e06a..6e61d61 100644 --- a/core/docs/plans/M3f-consensus-staking-sims.md +++ b/core/docs/plans/M3f-consensus-staking-sims.md @@ -9,7 +9,8 @@ theorems [10], and Monash dynamic PBFT modeling [11]. ## 2. Status / certainty DESIGN-FIRST · ABSENT. Evolutionary PoS game theory C4 (Cornell [8]); staking pool Nash -equilibrium proofs C4 (ACM [10]); Markov chain throughput models C4 (Monash [11]); +equilibrium proofs C4 (ACM [10]); Markov chain throughput models C4 (Monash [11]); MFG for +validator populations C4 (Lasry & Lions 2007; validator-specific application C3); simulation parameterization C1. ## 3. Language & location @@ -21,8 +22,12 @@ computation. Python, Julia, or R. under bounded rationality [8]; model staking pool delegation as a game with proven reward- parameter thresholds enforcing subgame-perfect Nash equilibria favoring honest validation over malicious slashing [10]; simulate **throughput stability under shifting validator states** via - Markov chains [11]; predict slashing risk, validator set stability, and staking yield; produce - bounded predictions on consensus health and staking returns. + Markov chains [11]; solve **Mean-Field Game equilibria for large validator populations** — + coupled HJB (individual validator optimization) + Fokker-Planck (population density): + $-\partial_t u + H(x, \nabla u) = F(x, m)$, $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ + — captures emergent staking coordination without enumerating every validator; predict slashing + risk, validator set stability, and staking yield across **six concurrent time horizons** at + ≥ 360:1 speed; produce bounded predictions on consensus health and staking returns. - **Does-not:** validate blocks (this is a simulator); model AMM pools (M3c); model token supply (M3e — but consumes staking ratio from M3e as input). @@ -34,8 +39,18 @@ computation. Python, Julia, or R. equilibrium. Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 0.82, time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%). +- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Hourly | Markov chain validator state transitions | Every epoch | + | Daily | Replicator dynamics strategy shifts, slashing events | Hourly roll | + | Weekly | Staking pool Nash equilibrium recalculation | Daily roll | + | Monthly | MFG equilibrium for validator population | Weekly roll | + | Annual | Evolutionary stable strategies, yield trajectory | Monthly roll | + | 5-year | Consensus mechanism structural evolution | Quarterly roll | - **Prediction types:** `validator_honesty_fraction`, `slashing_probability`, `staking_yield`, - `pool_delegation_equilibrium`, `throughput_stability`, `consensus_liveness`. + `pool_delegation_equilibrium`, `throughput_stability`, `consensus_liveness`, + `mfg_validator_equilibrium`. - Calibration: ingests `on_chain_event` (validator set changes, slashing events) from M2. ## 6. Dependencies & stubs @@ -56,8 +71,9 @@ computation. Python, Julia, or R. 1. Implement the evolutionary honesty game (replicator dynamics, bounded rationality). 2. Implement the Markov chain validator-state model. 3. Reproduce the staking pool Nash equilibrium reward threshold from [10]. -4. Wire M2 validator data → calibration of transition rates. -5. Wire M3e staking ratio input. +4. Implement MFG solver (HJB + Fokker-Planck) for large validator populations. +5. Wire M2 validator data → calibration of transition rates. +6. Wire M3e staking ratio input. ## 9. Tests Equilibrium: honesty fraction converges to Nash equilibrium under stable payoffs. Markov: diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md index 18bc84a..4d82e17 100644 --- a/core/docs/plans/M3g-market-microstructure-sims.md +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -2,69 +2,100 @@ ## 1. Component Market microstructure simulation: models **order flow, liquidity depth, slippage, spread dynamics, -and cross-exchange arbitrage** at the fastest time scales (tick-level to hourly). Pops here are -**market makers, takers, and arbitrageurs** interacting across multiple venues. The sim that -operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c -models pool mechanics, M3g models the *plumbing* of how orders actually execute. +optimal execution, and cross-exchange arbitrage** at the fastest time scales. Pops here are +**market makers, takers, and arbitrageurs** interacting across multiple venues. Includes the +**Almgren-Chriss optimal execution framework** for minimizing market impact of large orders. +Operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c +models pool mechanics, M3g models the *plumbing* of how orders actually execute, across **six +concurrent time horizons** at ≥ 360:1 speed. ## 2. Status / certainty -DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established academic field); -DEX-specific microstructure C2 (emerging). Implementation C1. +DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established). Almgren-Chriss +optimal execution C5 (industry standard since 2001; crypto adaptations validated 2023–2024, +Kurz CMC thesis). DEX-specific microstructure C2 (emerging). Implementation C1. ## 3. Language & location -TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling and event-driven -simulation. Rust, C++, or Python with optimized event loop. +TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling, event-driven +simulation, and Riccati equation solvers for optimal execution trajectories. Rust, C++, or +Python with optimized event loop. ## 4. Does / does-not - **Does:** simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a function of inventory risk and adverse selection; simulate slippage curves for various order - sizes; model cross-exchange arbitrage opportunities and their decay; operate at **tick-level - resolution** (sub-second to minute); produce bounded predictions on execution quality, optimal - routing, and liquidity conditions. + sizes; solve **Almgren-Chriss optimal execution**: + $\min \int_0^T [\lambda \cdot x(t) \cdot \dot{x}(t) + \eta \cdot \dot{x}(t)^2] \, dt$ + where $\lambda$ = permanent impact, $\eta$ = temporary impact, $x(t)$ = remaining order — + splits large orders across time to minimize market impact + timing risk; impact parameters + $\lambda, \eta$ re-estimated from order-flow streams every 10–30s; execution trajectory solved + via Riccati equations in <100ms; model cross-exchange arbitrage opportunities and their decay; + operate at **tick-level resolution** (sub-second to minute); produce bounded predictions on + execution quality, optimal routing, and liquidity conditions. - **Does-not:** model protocol consensus (M3f); model macro token supply (M3e); model social behavior (M3b); execute trades (Marketplace does). ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. -- **Output bounds:** execution cost ranges and liquidity intervals. - Example: `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 0.85, - time_horizon: "next_trade", sim_type: "market_microstructure" }` — expected slippage (%) for a - 10 ETH market sell. - Example: `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 0.78, - time_horizon: "1h", sim_type: "market_microstructure" }` — available depth (USD) within 50bps - of mid. +- **Output bounds:** execution cost ranges, liquidity intervals, optimal trajectory envelopes. +- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | Almgren-Chriss execution, slippage, spread, arb decay | Every tick | + | Daily | Liquidity regime, venue depth profiles | Hourly roll | + | Weekly | Cross-venue flow patterns, impact parameter drift | Daily roll | + | Monthly | Structural liquidity shifts, venue market share | Weekly roll | + | Annual | Microstructure regime (DEX vs CEX share evolution) | Monthly roll | + | 5-year | Venue topology evolution, structural impact trends | Quarterly roll | +- Examples: + `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 0.85, + time_horizon: "next_trade", sim_type: "market_microstructure" }` — slippage (%) for 10 ETH. + `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 0.78, + time_horizon: "1h", sim_type: "market_microstructure" }` — depth (USD) within 50bps. + `{ value: [0.3, 0.3, 0.2, 0.1, 0.1], lower_bound: null, upper_bound: null, confidence: 0.80, + time_horizon: "30min", sim_type: "market_microstructure" }` — Almgren-Chriss optimal execution + schedule (fraction per 6-min bucket for 100 ETH sell). - **Prediction types:** `slippage_estimate`, `spread_forecast`, `depth_profile`, - `cross_venue_arb`, `optimal_execution_route`, `liquidity_score`. + `cross_venue_arb`, `optimal_execution_schedule`, `optimal_execution_route`, + `liquidity_score`, `impact_estimate`. - Calibration: ingests `price_tick`, `dex_pool_state`, and `execution_fill` from M2. ## 6. Dependencies & stubs - M2 Data Feeds — tick data and pool state; *stub:* canned order book snapshots. +- M3a Statistical — volatility estimates for Almgren-Chriss timing risk; *stub:* fixed vol. - M3c AMM sims — pool mechanics for DEX venues; *stub:* fixed pool state. - M3 Sims hub — lifecycle management; *stub:* manual init. ## 7. Invariants / laws -- **L1 (C4):** microstructure operates at the **highest temporal resolution** — predictions are +- **L1 (C5):** microstructure operates at the **highest temporal resolution** — predictions are valid for seconds to hours, not days. Stale microstructure data is worse than no data. -- **L2 (C4):** slippage is a **function of order size and current depth** — not a fixed +- **L2 (C5):** slippage is a **function of order size and current depth** — not a fixed percentage. The sim must model the non-linear relationship. -- **L3 (C3):** cross-venue arbitrage opportunities **decay** — the sim models the time-to-close +- **L3 (C5):** Almgren-Chriss impact parameters $\lambda, \eta$ are **estimated from live data**, + never hardcoded — crypto impact dynamics differ by asset, venue, and time-of-day. +- **L4 (C4):** cross-venue arbitrage opportunities **decay** — the sim models the time-to-close of an arb opportunity, not just its existence. +- **L5 (C4):** optimal execution trajectories are **re-solved on every significant state change** + (vol spike, depth drop, regime transition) — a stale trajectory is worse than naive execution. ## 8. Build steps 1. Implement a simplified order-book simulator (limit orders, market orders, cancels). 2. Add spread dynamics (inventory-based market maker model). 3. Add slippage curves (order size → execution cost). -4. Add cross-venue arb detection and decay modeling. -5. Wire M2 tick data → calibration. +4. Implement Almgren-Chriss optimal execution (Riccati solver, impact estimation). +5. Add cross-venue arb detection and decay modeling. +6. Wire M2 tick data → calibration of impact parameters. +7. Wire M3a vol estimates → Almgren-Chriss timing risk component. ## 9. Tests Slippage: larger orders produce greater slippage. Spread: spread widens under adverse selection. -Arb decay: detected arb opportunity closes over time. Depth: depth profile matches order book -state. Bounds: all outputs bounded. Resolution: predictions update at tick frequency. +Almgren-Chriss: optimal trajectory minimizes total cost vs. naive execution on backtest; impact +parameters update when market conditions change. Arb decay: detected arb opportunity closes over +time. Depth: depth profile matches order book state. Bounds: all outputs bounded. Resolution: +predictions update at tick frequency. Speed: sim advances ≥ 360:1. ## 10. Open items - CEX order book data access (API limitations, costs). - DEX-specific microstructure (AMM pools don't have order books — translate pool state to equivalent depth/spread). - Latency modeling (how fast can our traders actually reach an arb?). +- Almgren-Chriss extensions for crypto (volume-dependent variant? discrete block propagation?). - Which venues to model initially. From b196e4545895f2f5ef1dec138f6c4d3c0360e1a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 21:52:23 +0000 Subject: [PATCH 04/14] Fix 360:1 semantics: tick-advanced continuous, 1s wall = 1h sim All sims advance every tick continuously. The 360:1 floor means the slowest system produces 1 simulated hour per 1 wall-clock second. Updated hub cadence table and all sub-spec references. Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M3-sims-hub.md | 36 +++++++++---------- core/docs/plans/M3c-amm-liquidity-sims.md | 2 +- core/docs/plans/M3d-mev-adversarial-sims.md | 4 +-- core/docs/plans/M3e-tokenomics-macro-sims.md | 6 ++-- core/docs/plans/M3f-consensus-staking-sims.md | 4 +-- .../plans/M3g-market-microstructure-sims.md | 6 ++-- 6 files changed, 29 insertions(+), 29 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 2dc7ce3..665def9 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -20,23 +20,23 @@ simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g different runtime suited to its math. ## 4. Does / does-not -- **Does:** run continuously at **≥ 360:1 speed** (360 simulated seconds per wall-clock second) +- **Does:** tick-advance continuously at **≥ 360:1** (1 wall-second = 1 sim-hour minimum) across **six concurrent time horizons** — tick/hourly, daily, weekly, monthly, annual, and - 5-year forecast windows; maintain populations of Pops whose behaviors emerge from the sim's - mathematical model; ingest live data from Data Feeds (M2) for calibration; respond to Trader - queries with bounded predictions; produce outputs with **explicit upper/lower bounds** on - every prediction value. - | Horizon | Window | Sim cadence at 360:1 | - |---------|--------|---------------------| - | Tick–hourly | Next 1–60 min | Real-time (360 sim-sec/s) | - | Daily | Next 24h | 4 sim-minutes per wall-second | - | Weekly | Next 7d | ~28 sim-minutes per wall-second | - | Monthly | Next 30d | ~2 sim-hours per wall-second | - | Annual | Next 365d | ~1 sim-day per wall-second | - | 5-year | Next 1825d | ~5 sim-days per wall-second | + 5-year forecast windows; every tick advances every sim; maintain populations of Pops whose + behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2) + for calibration; respond to Trader queries with bounded predictions; produce outputs with + **explicit upper/lower bounds** on every prediction value. + | Horizon | Window | At 360:1 floor (1s wall = 1h sim) | + |---------|--------|-----------------------------------| + | Tick–hourly | Next 1–60 min | Covered in <1s wall time | + | Daily | Next 24h | Covered in 24s wall time | + | Weekly | Next 7d | Covered in ~168s wall time | + | Monthly | Next 30d | Covered in ~720s wall time | + | Annual | Next 365d | Covered in ~2.4h wall time | + | 5-year | Next 1825d | Covered in ~12h wall time | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they - decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); run slower - than 360:1. + decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; + run slower than 360:1. ## 5. Interface contract - `query(sim_type: SimType, query: PredictionQuery) -> BoundedPrediction`. @@ -60,9 +60,9 @@ different runtime suited to its math. current state; they don't trigger computation. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. -- **L3 (C5):** sims advance at a **minimum speed of 360:1** — 360 simulated seconds per 1 - wall-clock second. Sims may run faster but never slower. This ensures predictions stay - ahead of real-time market state across all horizons. +- **L3 (C5):** all sims are **tick-advanced and continuous** — they advance every tick, never + skip. The slowest system runs at **360:1** — 1 wall-clock second = 1 simulated hour. Sims + may run faster but never slower. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. diff --git a/core/docs/plans/M3c-amm-liquidity-sims.md b/core/docs/plans/M3c-amm-liquidity-sims.md index 422cc4b..e64d46e 100644 --- a/core/docs/plans/M3c-amm-liquidity-sims.md +++ b/core/docs/plans/M3c-amm-liquidity-sims.md @@ -31,7 +31,7 @@ invariant calculations (Solidity-equivalent precision). Python, Rust, or Julia. time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool. Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 0.85, time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL). -- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): +- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Tick–hourly | Slippage curves, invariant state, JIT liquidity | Every swap event | diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md index 18ec3fa..f5db7e5 100644 --- a/core/docs/plans/M3d-mev-adversarial-sims.md +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -47,7 +47,7 @@ and bilevel optimization (DSMFG). Python, Rust, or Julia. - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** extraction probability ranges, gas cost intervals, cross-chain profit bounds, DSMFG equilibrium stability ranges. -- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): +- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Tick–hourly | PGA auctions, sandwich detection, cross-chain arb | Every block | @@ -103,7 +103,7 @@ under gas limit. Sandwich: known sandwich-vulnerable trade flagged; non-vulnerab Cross-chain: inventory path preferred when latency advantage exceeds capital cost. DSMFG: leader policy converges to fixed point with follower equilibrium. Kolokoltsov: WENO captures shock discontinuities in adversarial strategy distribution. Bounds: all outputs bounded. Pre-trade: -query does not submit any transaction. Speed: sim advances ≥ 360:1. +query does not submit any transaction. Speed: sim tick-advances ≥ 360:1 (1s wall = 1h sim). ## 10. Open items - Mempool data access (public mempool? private order flow?). diff --git a/core/docs/plans/M3e-tokenomics-macro-sims.md b/core/docs/plans/M3e-tokenomics-macro-sims.md index 61bee9f..e2cdf4d 100644 --- a/core/docs/plans/M3e-tokenomics-macro-sims.md +++ b/core/docs/plans/M3e-tokenomics-macro-sims.md @@ -6,7 +6,7 @@ burns, inflation), lending protocol dynamics, DeFi systemic risk, and stock-flow stochastic differential equations (SDEs), state-space models, kinked interest rate curves, and inter-protocol credit exposure networks. Pops here are **aggregate behavioral cohorts** (miners/validators, holders, speculators, protocol treasuries, borrowers/lenders) whose collective -behavior drives token-level dynamics across **six concurrent time horizons** at ≥ 360:1 speed. +behavior drives token-level dynamics across **six concurrent time horizons** at tick-advanced, ≥ 360:1 (1s wall = 1h sim). Grounded in Vienna complex-systems token modeling [7], ResearchGate engineering token economy frameworks [6], Aave/Compound kinked interest rate models (industry standard), and DeXposure @@ -49,7 +49,7 @@ Julia (DifferentialEquations.jl), Python (scipy), or Octave. ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** SDE confidence bands, utilization rate ranges, contagion impact intervals. -- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): +- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Hourly | Lending rates, utilization, liquidation risk | Every block | @@ -107,7 +107,7 @@ Lending: rate curve exhibits kink at $U_{\text{opt}}$; liquidation cascades trig collateral ratio breached. DeXposure: shock to protocol A propagates to protocol B through shared collateral; isolated protocols unaffected. Yield: optimizer rebalances toward highest risk-adjusted APY. Calibration: state estimate converges to observed data. Bounds: SDE confidence bands cover -realized paths on backtest. Speed: sim advances ≥ 360:1. +realized paths on backtest. Speed: sim tick-advances ≥ 360:1 (1s wall = 1h sim). ## 10. Open items - Which tokens to model initially (ETH? BTC? a specific alt?). diff --git a/core/docs/plans/M3f-consensus-staking-sims.md b/core/docs/plans/M3f-consensus-staking-sims.md index 6e61d61..1dd8b56 100644 --- a/core/docs/plans/M3f-consensus-staking-sims.md +++ b/core/docs/plans/M3f-consensus-staking-sims.md @@ -27,7 +27,7 @@ computation. Python, Julia, or R. $-\partial_t u + H(x, \nabla u) = F(x, m)$, $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ — captures emergent staking coordination without enumerating every validator; predict slashing risk, validator set stability, and staking yield across **six concurrent time horizons** at - ≥ 360:1 speed; produce bounded predictions on consensus health and staking returns. + tick-advanced, ≥ 360:1 (1s wall = 1h sim); produce bounded predictions on consensus health and staking returns. - **Does-not:** validate blocks (this is a simulator); model AMM pools (M3c); model token supply (M3e — but consumes staking ratio from M3e as input). @@ -39,7 +39,7 @@ computation. Python, Julia, or R. equilibrium. Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 0.82, time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%). -- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): +- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Hourly | Markov chain validator state transitions | Every epoch | diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md index 4d82e17..5549bdb 100644 --- a/core/docs/plans/M3g-market-microstructure-sims.md +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -7,7 +7,7 @@ optimal execution, and cross-exchange arbitrage** at the fastest time scales. Po **Almgren-Chriss optimal execution framework** for minimizing market impact of large orders. Operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c models pool mechanics, M3g models the *plumbing* of how orders actually execute, across **six -concurrent time horizons** at ≥ 360:1 speed. +concurrent time horizons** at tick-advanced, ≥ 360:1 (1s wall = 1h sim). ## 2. Status / certainty DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established). Almgren-Chriss @@ -36,7 +36,7 @@ Python with optimized event loop. ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** execution cost ranges, liquidity intervals, optimal trajectory envelopes. -- **Time-horizon mapping** (all run concurrently, ≥ 360:1 speed): +- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Tick–hourly | Almgren-Chriss execution, slippage, spread, arb decay | Every tick | @@ -90,7 +90,7 @@ Slippage: larger orders produce greater slippage. Spread: spread widens under ad Almgren-Chriss: optimal trajectory minimizes total cost vs. naive execution on backtest; impact parameters update when market conditions change. Arb decay: detected arb opportunity closes over time. Depth: depth profile matches order book state. Bounds: all outputs bounded. Resolution: -predictions update at tick frequency. Speed: sim advances ≥ 360:1. +predictions update at tick frequency. Speed: sim tick-advances ≥ 360:1 (1s wall = 1h sim). ## 10. Open items - CEX order book data access (API limitations, costs). From 78eaa01a700c42f821d28c357a255d76849c5d66 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 21:53:19 +0000 Subject: [PATCH 05/14] Fix sim speed: per-horizon rates, 1s wall = 1 full window per horizon Hourly 3600:1, daily 86400:1, weekly 604800:1, monthly 2.6M:1, annual 31.5M:1, 5-year 158M:1. Each horizon tick-advances at the speed needed to cover its full prediction window in 1 wall-second. Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M3-sims-hub.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 665def9..91842c8 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -26,14 +26,14 @@ different runtime suited to its math. behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2) for calibration; respond to Trader queries with bounded predictions; produce outputs with **explicit upper/lower bounds** on every prediction value. - | Horizon | Window | At 360:1 floor (1s wall = 1h sim) | - |---------|--------|-----------------------------------| - | Tick–hourly | Next 1–60 min | Covered in <1s wall time | - | Daily | Next 24h | Covered in 24s wall time | - | Weekly | Next 7d | Covered in ~168s wall time | - | Monthly | Next 30d | Covered in ~720s wall time | - | Annual | Next 365d | Covered in ~2.4h wall time | - | 5-year | Next 1825d | Covered in ~12h wall time | + | Horizon | Window | Speed (1s wall =) | Ratio | + |---------|--------|-------------------|-------| + | Tick–hourly | Next 1–60 min | 1h sim | 3,600:1 | + | Daily | Next 24h | 1d sim | 86,400:1 (3600×24) | + | Weekly | Next 7d | 1w sim | 604,800:1 (3600×24×7) | + | Monthly | Next 30d | 1mo sim | 2,592,000:1 (3600×24×30) | + | Annual | Next 365d | 1yr sim | 31,536,000:1 (3600×24×365) | + | 5-year | Next 1825d | 5yr sim | 157,680,000:1 | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; run slower than 360:1. @@ -61,8 +61,9 @@ different runtime suited to its math. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. - **L3 (C5):** all sims are **tick-advanced and continuous** — they advance every tick, never - skip. The slowest system runs at **360:1** — 1 wall-clock second = 1 simulated hour. Sims - may run faster but never slower. + skip. Each time horizon runs at its own speed: **1 wall-second = 1 full window** of that + horizon's sim time. The slowest (hourly) is 3,600:1; daily is 86,400:1; up to 5-year at + ~158M:1. No horizon may run slower than its rated speed. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. From e40210f5702054792c0d0b79ee78763b8072ffe0 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 21:55:24 +0000 Subject: [PATCH 06/14] Dial down sim speed for longer horizons (monthly/annual/5yr) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hourly–weekly: full window in ≤1 wall-second (3600:1 to 604800:1). Monthly: daily ticks, 30s wall for full window. Annual: weekly ticks, ~52s wall. 5-year: monthly ticks, ~60s wall. Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M3-sims-hub.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 91842c8..f7fb02c 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -26,14 +26,14 @@ different runtime suited to its math. behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2) for calibration; respond to Trader queries with bounded predictions; produce outputs with **explicit upper/lower bounds** on every prediction value. - | Horizon | Window | Speed (1s wall =) | Ratio | - |---------|--------|-------------------|-------| - | Tick–hourly | Next 1–60 min | 1h sim | 3,600:1 | - | Daily | Next 24h | 1d sim | 86,400:1 (3600×24) | - | Weekly | Next 7d | 1w sim | 604,800:1 (3600×24×7) | - | Monthly | Next 30d | 1mo sim | 2,592,000:1 (3600×24×30) | - | Annual | Next 365d | 1yr sim | 31,536,000:1 (3600×24×365) | - | 5-year | Next 1825d | 5yr sim | 157,680,000:1 | + | Horizon | Window | Speed (1s wall =) | Ratio | Wall time for window | + |---------|--------|-------------------|-------|---------------------| + | Tick–hourly | Next 1–60 min | 1h sim | 3,600:1 | <1s | + | Daily | Next 24h | 1d sim | 86,400:1 | 1s | + | Weekly | Next 7d | 1w sim | 604,800:1 | 1s | + | Monthly | Next 30d | 1d sim | 86,400:1 | 30s | + | Annual | Next 365d | 1w sim | 604,800:1 | ~52s | + | 5-year | Next 1825d | 1mo sim | 2,592,000:1 | ~60s | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; run slower than 360:1. @@ -61,9 +61,10 @@ different runtime suited to its math. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. - **L3 (C5):** all sims are **tick-advanced and continuous** — they advance every tick, never - skip. Each time horizon runs at its own speed: **1 wall-second = 1 full window** of that - horizon's sim time. The slowest (hourly) is 3,600:1; daily is 86,400:1; up to 5-year at - ~158M:1. No horizon may run slower than its rated speed. + skip. Each time horizon runs at its own rated speed (see §4 table). Hourly through weekly + cover their full window in ≤ 1 wall-second; monthly through 5-year dial down to coarser + ticks (daily/weekly/monthly steps) and take 30–60 wall-seconds for a full window pass. + No horizon may run slower than its rated speed. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. From ab086e422b87c98d2e9758c0fc1758fad3d6cd13 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 23:18:24 +0000 Subject: [PATCH 07/14] Set sim speed to 90:1 (1s wall = 90s sim) across all specs Grounded ratio based on ABIDES/ECMWF benchmarks. Single global clock shared by all horizons. Wall time for full window: hourly ~40s, daily ~16min, weekly ~1.9hr, monthly ~8.3hr, annual ~4.2d, 5yr ~20.8d. Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M3-sims-hub.md | 26 +++++++++---------- core/docs/plans/M3c-amm-liquidity-sims.md | 2 +- core/docs/plans/M3d-mev-adversarial-sims.md | 4 +-- core/docs/plans/M3e-tokenomics-macro-sims.md | 6 ++--- core/docs/plans/M3f-consensus-staking-sims.md | 4 +-- .../plans/M3g-market-microstructure-sims.md | 6 ++--- 6 files changed, 23 insertions(+), 25 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index f7fb02c..4574bd2 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -20,23 +20,23 @@ simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g different runtime suited to its math. ## 4. Does / does-not -- **Does:** tick-advance continuously at **≥ 360:1** (1 wall-second = 1 sim-hour minimum) +- **Does:** tick-advance continuously at **90:1** (1 wall-second = 90 simulated seconds) across **six concurrent time horizons** — tick/hourly, daily, weekly, monthly, annual, and 5-year forecast windows; every tick advances every sim; maintain populations of Pops whose behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2) for calibration; respond to Trader queries with bounded predictions; produce outputs with **explicit upper/lower bounds** on every prediction value. - | Horizon | Window | Speed (1s wall =) | Ratio | Wall time for window | - |---------|--------|-------------------|-------|---------------------| - | Tick–hourly | Next 1–60 min | 1h sim | 3,600:1 | <1s | - | Daily | Next 24h | 1d sim | 86,400:1 | 1s | - | Weekly | Next 7d | 1w sim | 604,800:1 | 1s | - | Monthly | Next 30d | 1d sim | 86,400:1 | 30s | - | Annual | Next 365d | 1w sim | 604,800:1 | ~52s | - | 5-year | Next 1825d | 1mo sim | 2,592,000:1 | ~60s | + | Horizon | Window | Wall time for window | + |---------|--------|---------------------| + | Tick–hourly | Next 1–60 min | ~40s | + | Daily | Next 24h | ~16 min | + | Weekly | Next 7d | ~1.9 hr | + | Monthly | Next 30d | ~8.3 hr | + | Annual | Next 365d | ~4.2 days | + | 5-year | Next 1825d | ~20.8 days | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; - run slower than 360:1. + run slower than 90:1. ## 5. Interface contract - `query(sim_type: SimType, query: PredictionQuery) -> BoundedPrediction`. @@ -61,10 +61,8 @@ different runtime suited to its math. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. - **L3 (C5):** all sims are **tick-advanced and continuous** — they advance every tick, never - skip. Each time horizon runs at its own rated speed (see §4 table). Hourly through weekly - cover their full window in ≤ 1 wall-second; monthly through 5-year dial down to coarser - ticks (daily/weekly/monthly steps) and take 30–60 wall-seconds for a full window pass. - No horizon may run slower than its rated speed. + skip. Global sim speed: **1 wall-second = 90 simulated seconds** (90:1). All horizons share + this clock. No sim may run slower than 90:1. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. diff --git a/core/docs/plans/M3c-amm-liquidity-sims.md b/core/docs/plans/M3c-amm-liquidity-sims.md index e64d46e..eff6850 100644 --- a/core/docs/plans/M3c-amm-liquidity-sims.md +++ b/core/docs/plans/M3c-amm-liquidity-sims.md @@ -31,7 +31,7 @@ invariant calculations (Solidity-equivalent precision). Python, Rust, or Julia. time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool. Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 0.85, time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL). -- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Tick–hourly | Slippage curves, invariant state, JIT liquidity | Every swap event | diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md index f5db7e5..013b3bb 100644 --- a/core/docs/plans/M3d-mev-adversarial-sims.md +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -47,7 +47,7 @@ and bilevel optimization (DSMFG). Python, Rust, or Julia. - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** extraction probability ranges, gas cost intervals, cross-chain profit bounds, DSMFG equilibrium stability ranges. -- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Tick–hourly | PGA auctions, sandwich detection, cross-chain arb | Every block | @@ -103,7 +103,7 @@ under gas limit. Sandwich: known sandwich-vulnerable trade flagged; non-vulnerab Cross-chain: inventory path preferred when latency advantage exceeds capital cost. DSMFG: leader policy converges to fixed point with follower equilibrium. Kolokoltsov: WENO captures shock discontinuities in adversarial strategy distribution. Bounds: all outputs bounded. Pre-trade: -query does not submit any transaction. Speed: sim tick-advances ≥ 360:1 (1s wall = 1h sim). +query does not submit any transaction. Speed: sim tick-advances at 90:1. ## 10. Open items - Mempool data access (public mempool? private order flow?). diff --git a/core/docs/plans/M3e-tokenomics-macro-sims.md b/core/docs/plans/M3e-tokenomics-macro-sims.md index e2cdf4d..4f6ba52 100644 --- a/core/docs/plans/M3e-tokenomics-macro-sims.md +++ b/core/docs/plans/M3e-tokenomics-macro-sims.md @@ -6,7 +6,7 @@ burns, inflation), lending protocol dynamics, DeFi systemic risk, and stock-flow stochastic differential equations (SDEs), state-space models, kinked interest rate curves, and inter-protocol credit exposure networks. Pops here are **aggregate behavioral cohorts** (miners/validators, holders, speculators, protocol treasuries, borrowers/lenders) whose collective -behavior drives token-level dynamics across **six concurrent time horizons** at tick-advanced, ≥ 360:1 (1s wall = 1h sim). +behavior drives token-level dynamics across **six concurrent time horizons** at tick-advanced, 90:1 (1s wall = 90s sim). Grounded in Vienna complex-systems token modeling [7], ResearchGate engineering token economy frameworks [6], Aave/Compound kinked interest rate models (industry standard), and DeXposure @@ -49,7 +49,7 @@ Julia (DifferentialEquations.jl), Python (scipy), or Octave. ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** SDE confidence bands, utilization rate ranges, contagion impact intervals. -- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Hourly | Lending rates, utilization, liquidation risk | Every block | @@ -107,7 +107,7 @@ Lending: rate curve exhibits kink at $U_{\text{opt}}$; liquidation cascades trig collateral ratio breached. DeXposure: shock to protocol A propagates to protocol B through shared collateral; isolated protocols unaffected. Yield: optimizer rebalances toward highest risk-adjusted APY. Calibration: state estimate converges to observed data. Bounds: SDE confidence bands cover -realized paths on backtest. Speed: sim tick-advances ≥ 360:1 (1s wall = 1h sim). +realized paths on backtest. Speed: sim tick-advances at 90:1. ## 10. Open items - Which tokens to model initially (ETH? BTC? a specific alt?). diff --git a/core/docs/plans/M3f-consensus-staking-sims.md b/core/docs/plans/M3f-consensus-staking-sims.md index 1dd8b56..d807da5 100644 --- a/core/docs/plans/M3f-consensus-staking-sims.md +++ b/core/docs/plans/M3f-consensus-staking-sims.md @@ -27,7 +27,7 @@ computation. Python, Julia, or R. $-\partial_t u + H(x, \nabla u) = F(x, m)$, $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ — captures emergent staking coordination without enumerating every validator; predict slashing risk, validator set stability, and staking yield across **six concurrent time horizons** at - tick-advanced, ≥ 360:1 (1s wall = 1h sim); produce bounded predictions on consensus health and staking returns. + tick-advanced, 90:1 (1s wall = 90s sim); produce bounded predictions on consensus health and staking returns. - **Does-not:** validate blocks (this is a simulator); model AMM pools (M3c); model token supply (M3e — but consumes staking ratio from M3e as input). @@ -39,7 +39,7 @@ computation. Python, Julia, or R. equilibrium. Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 0.82, time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%). -- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Hourly | Markov chain validator state transitions | Every epoch | diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md index 5549bdb..78da588 100644 --- a/core/docs/plans/M3g-market-microstructure-sims.md +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -7,7 +7,7 @@ optimal execution, and cross-exchange arbitrage** at the fastest time scales. Po **Almgren-Chriss optimal execution framework** for minimizing market impact of large orders. Operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c models pool mechanics, M3g models the *plumbing* of how orders actually execute, across **six -concurrent time horizons** at tick-advanced, ≥ 360:1 (1s wall = 1h sim). +concurrent time horizons** at tick-advanced, 90:1 (1s wall = 90s sim). ## 2. Status / certainty DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established). Almgren-Chriss @@ -36,7 +36,7 @@ Python with optimized event loop. ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** execution cost ranges, liquidity intervals, optimal trajectory envelopes. -- **Time-horizon mapping** (all run concurrently, tick-advanced, ≥ 360:1 (1s wall = 1h sim)): +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | |---------|---------------|----------------| | Tick–hourly | Almgren-Chriss execution, slippage, spread, arb decay | Every tick | @@ -90,7 +90,7 @@ Slippage: larger orders produce greater slippage. Spread: spread widens under ad Almgren-Chriss: optimal trajectory minimizes total cost vs. naive execution on backtest; impact parameters update when market conditions change. Arb decay: detected arb opportunity closes over time. Depth: depth profile matches order book state. Bounds: all outputs bounded. Resolution: -predictions update at tick frequency. Speed: sim tick-advances ≥ 360:1 (1s wall = 1h sim). +predictions update at tick frequency. Speed: sim tick-advances at 90:1. ## 10. Open items - CEX order book data access (API limitations, costs). From 47446906947e1aea5e7f30bbdad3acbcfe142c84 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 23:20:41 +0000 Subject: [PATCH 08/14] Fix sim speed model: 90:1 base, coarser ticks for longer horizons 90:1 (1s wall = 90s sim) is the finest tick resolution. Longer horizons use coarser time steps (1min, 10min, 1hr, 6hr, 1day) so they cover their full window in seconds, not hours/days. Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M3-sims-hub.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 4574bd2..4969178 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -26,14 +26,14 @@ different runtime suited to its math. behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2) for calibration; respond to Trader queries with bounded predictions; produce outputs with **explicit upper/lower bounds** on every prediction value. - | Horizon | Window | Wall time for window | - |---------|--------|---------------------| - | Tick–hourly | Next 1–60 min | ~40s | - | Daily | Next 24h | ~16 min | - | Weekly | Next 7d | ~1.9 hr | - | Monthly | Next 30d | ~8.3 hr | - | Annual | Next 365d | ~4.2 days | - | 5-year | Next 1825d | ~20.8 days | + | Horizon | Window | Tick step | Effective ratio | Wall time for window | + |---------|--------|-----------|-----------------|---------------------| + | Tick–hourly | Next 1–60 min | 1s | 90:1 | ~40s | + | Daily | Next 24h | 1 min | 5,400:1 | ~16s | + | Weekly | Next 7d | 10 min | 54,000:1 | ~11s | + | Monthly | Next 30d | 1 hr | 324,000:1 | ~8s | + | Annual | Next 365d | 6 hr | 1,944,000:1 | ~16s | + | 5-year | Next 1825d | 1 day | 7,776,000:1 | ~20s | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; run slower than 90:1. @@ -61,8 +61,9 @@ different runtime suited to its math. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. - **L3 (C5):** all sims are **tick-advanced and continuous** — they advance every tick, never - skip. Global sim speed: **1 wall-second = 90 simulated seconds** (90:1). All horizons share - this clock. No sim may run slower than 90:1. + skip. Base speed **90:1** (1 wall-second = 90 sim-seconds) at the finest tick resolution. + Longer horizons use **coarser ticks** (larger time steps) so they cover proportionally more + sim-time per wall-second. 90:1 is the floor; no horizon runs slower. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. From 97e49ffa8e5523a0d4be4a4e0d03de49618f35f6 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 23:23:51 +0000 Subject: [PATCH 09/14] Simplify L3 sim speed: 90:1 base, coarser+faster for longer horizons Co-Authored-By: Claude Opus 4.6 --- core/docs/plans/M3-sims-hub.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 4969178..b2042d5 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -60,10 +60,9 @@ different runtime suited to its math. current state; they don't trigger computation. - **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no unbounded point estimates. Uncertainty is a first-class value, not an afterthought. -- **L3 (C5):** all sims are **tick-advanced and continuous** — they advance every tick, never - skip. Base speed **90:1** (1 wall-second = 90 sim-seconds) at the finest tick resolution. - Longer horizons use **coarser ticks** (larger time steps) so they cover proportionally more - sim-time per wall-second. 90:1 is the floor; no horizon runs slower. +- **L3 (C5):** all sims are **tick-advanced and continuous** — fine-grained ticks (RTS-style). + Base speed **90:1** (1s wall = 90s sim). Longer horizons run at higher velocity with coarser + steps and update less frequently. No horizon runs slower than 90:1. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. From a0edbca6319305087c76d22f22d2de65931f65e4 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 23:56:49 +0000 Subject: [PATCH 10/14] Add devCorrectionLog.md, parallel sim horizons in L3 - .claude/devCorrectionLog.md: interaction pattern corrections for future instances (additive clarifications, no idle subagents, etc.) - M3 hub L3: horizons run in parallel, not sequential - Mention correction log in CLAUDE.md and all subdirectory AGENTS.md Co-Authored-By: Claude Opus 4.6 --- .claude/devCorrectionLog.md | 33 +++++++++++++++++++++++++++++++++ core/AGENTS.md | 2 +- core/CLAUDE.md | 2 ++ core/docs/plans/M3-sims-hub.md | 3 ++- core/src/endocrine/AGENTS.md | 2 +- core/src/ichor/AGENTS.md | 2 +- 6 files changed, 40 insertions(+), 4 deletions(-) create mode 100644 .claude/devCorrectionLog.md diff --git a/.claude/devCorrectionLog.md b/.claude/devCorrectionLog.md new file mode 100644 index 0000000..d697a25 --- /dev/null +++ b/.claude/devCorrectionLog.md @@ -0,0 +1,33 @@ +# devCorrectionLog + +⊳ User gives **additive** clarifications. Only an explicit "no" is a replacement. +⊳ Don't rewrite — append. Don't guess — ask or research first. +⊳ Don't idle while subagents run. + +```yml +corrections: + - epoch: 1783985662 + failcase: "rewrote L3 seven times" + identifyBy: "treating every clarification as a full replacement" + instead: "append the new detail to existing text, preserve prior content" + + - epoch: 1783985662 + failcase: "idle during foreground subagent" + identifyBy: "ran research agent synchronously, did nothing while waiting" + instead: "run agents in background, continue editing other files" + + - epoch: 1783985662 + failcase: "guessed sim speed without research" + identifyBy: "accepted 360:1 then 3600:1 then 86400:1 without pushback" + instead: "research comparable systems before committing a number" + + - epoch: 1783985662 + failcase: "5 commits on one parameter" + identifyBy: "each clarification triggered a commit-push cycle" + instead: "accumulate related changes, commit once when stable" + + - epoch: 1783985662 + failcase: "never asked what economy organ was" + identifyBy: "wrote 8 wrong specs (text digestion) without asking" + instead: "ask what the thing is before designing it" +``` diff --git a/core/AGENTS.md b/core/AGENTS.md index b2b5a83..e040da3 100644 --- a/core/AGENTS.md +++ b/core/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — Ada border (D1) + invariant vault Local guide for `mafiabot_core`. Repo-wide map and rules: [`../AGENTS.md`](../AGENTS.md); -working agreements: [`../CLAUDE.md`](../CLAUDE.md). +working agreements: [`../CLAUDE.md`](../CLAUDE.md). Correction log: [`../.claude/devCorrectionLog.md`](../.claude/devCorrectionLog.md). ## What this is diff --git a/core/CLAUDE.md b/core/CLAUDE.md index 0aa0fdf..16b4b4a 100644 --- a/core/CLAUDE.md +++ b/core/CLAUDE.md @@ -32,6 +32,8 @@ Per-unit commands and gotchas live in that unit's `AGENTS.md`. Toolchains (ponyc When spawning background agents (Haiku for research, etc.), **keep working on the main task while they run**. Don't wait idle — fold in results as they arrive, edit other files, or advance unrelated build steps. Background agents are cheap parallelism; wasting the main context window on waiting defeats the purpose. +Correction log at `.claude/devCorrectionLog.md`. + ## Docs map - `README.md` — the project and its intent. diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index b2042d5..7882039 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -62,7 +62,8 @@ different runtime suited to its math. unbounded point estimates. Uncertainty is a first-class value, not an afterthought. - **L3 (C5):** all sims are **tick-advanced and continuous** — fine-grained ticks (RTS-style). Base speed **90:1** (1s wall = 90s sim). Longer horizons run at higher velocity with coarser - steps and update less frequently. No horizon runs slower than 90:1. + steps and update less frequently. Each horizon runs **in parallel** — they are concurrent, + not sequential. No horizon runs slower than 90:1. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. diff --git a/core/src/endocrine/AGENTS.md b/core/src/endocrine/AGENTS.md index e290d9e..0340ccd 100644 --- a/core/src/endocrine/AGENTS.md +++ b/core/src/endocrine/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — endocrine organs (R / Octave) Local guide for `src/endocrine`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); -working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../.claude/devCorrectionLog.md`](../../.claude/devCorrectionLog.md). ## What this is diff --git a/core/src/ichor/AGENTS.md b/core/src/ichor/AGENTS.md index 0dd352b..8496479 100644 --- a/core/src/ichor/AGENTS.md +++ b/core/src/ichor/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — Ichor bus (Pony) Local guide for `src/ichor`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); -working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../.claude/devCorrectionLog.md`](../../.claude/devCorrectionLog.md). ## What this is From b944ccff838dc9ce58762c187d9695b594d53258 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 23:57:37 +0000 Subject: [PATCH 11/14] Add correction log mention to root CLAUDE.md Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CLAUDE.md b/CLAUDE.md index 1338e05..fe4b010 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,5 +2,6 @@ Working agreements, build/run, and the invariants (S1/S2/S3) for sica-fondt now live in [`core/CLAUDE.md`](core/CLAUDE.md). This root file is only a pin. +Correction log: [`.claude/devCorrectionLog.md`](.claude/devCorrectionLog.md). @core/CLAUDE.md From 9712035e12555115ee1a2bfee73eabd4e94244a9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 00:06:06 +0000 Subject: [PATCH 12/14] Fix Copilot review findings: broken paths, stale refs, horizon count MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - endocrine/AGENTS.md, ichor/AGENTS.md: fix devCorrectionLog relative path (../../ → ../../../) so it resolves to repo root .claude/ - bus-topology.md: update stale M2/M6 references to current specs (M2=Data Feeds, M6=Conductor) - M3a: combine tick/hourly to match hub's six-horizon convention --- core/docs/bus-topology.md | 4 ++-- core/docs/plans/M3a-statistical-sims.md | 2 +- core/src/endocrine/AGENTS.md | 2 +- core/src/ichor/AGENTS.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/core/docs/bus-topology.md b/core/docs/bus-topology.md index 9973b79..d65a725 100644 --- a/core/docs/bus-topology.md +++ b/core/docs/bus-topology.md @@ -85,5 +85,5 @@ blocking in a protected action), **tasks = workers** that call into the organs - **MoRAG / GoDAGRAG language** (Haskell vs Crystal vs other). - Each outer organ's hand-off shape to Ada. - ~~The stomach/economy organ's exact placement + which small model runs it.~~ - **→ placed:** M-series (M0–M7) in `docs/plans/`. Outer organ on Ichor; small model TBD (M2). - See M0 (hub), M6 (provenance chain through digestion, S1/S2 compliance). + **→ placed:** M-series (M0–M7) in `docs/plans/`. Outer organ on Ichor; data feeds via M2 (Data Feeds). + See M0 (hub), M6 (Conductor — orchestration, provenance chain, S1/S2 compliance). diff --git a/core/docs/plans/M3a-statistical-sims.md b/core/docs/plans/M3a-statistical-sims.md index ff7a748..896c298 100644 --- a/core/docs/plans/M3a-statistical-sims.md +++ b/core/docs/plans/M3a-statistical-sims.md @@ -4,7 +4,7 @@ Pure statistical simulation: **Monte Carlo methods, Bayesian inference, time-series forecasting, stochastic volatility, regime detection, and cross-asset correlation**. The mathematical backbone — no game theory, no sociology, just the numbers. Operates across **six concurrent time horizons** -(tick → hourly → daily → weekly → monthly → annual → 5-year). Pops in this sim represent +(tick/hourly → daily → weekly → monthly → annual → 5-year). Pops in this sim represent **stochastic sample paths**, not behavioral agents. ## 2. Status / certainty diff --git a/core/src/endocrine/AGENTS.md b/core/src/endocrine/AGENTS.md index 0340ccd..260cd52 100644 --- a/core/src/endocrine/AGENTS.md +++ b/core/src/endocrine/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — endocrine organs (R / Octave) Local guide for `src/endocrine`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); -working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../.claude/devCorrectionLog.md`](../../.claude/devCorrectionLog.md). +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../../.claude/devCorrectionLog.md`](../../../.claude/devCorrectionLog.md). ## What this is diff --git a/core/src/ichor/AGENTS.md b/core/src/ichor/AGENTS.md index 8496479..809f9d2 100644 --- a/core/src/ichor/AGENTS.md +++ b/core/src/ichor/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — Ichor bus (Pony) Local guide for `src/ichor`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); -working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../.claude/devCorrectionLog.md`](../../.claude/devCorrectionLog.md). +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../../.claude/devCorrectionLog.md`](../../../.claude/devCorrectionLog.md). ## What this is From 3919e70ed046513a186e48c69b207f1bdbf75a7c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 00:50:09 +0000 Subject: [PATCH 13/14] Address PR #13 review: 18 comments across M0-M3g specs M0: economy organ stores local memory ledger; M6 supervises M5 directly, M7 is independent antivirus/guarddog alerting M6 via Ichor; Ada dependency reframed to economy scope; build sequence changed to subcomponent-first with ablative tests. M1: submit_action returns {succeeded|failed}, diagnostics internal to Conductor; stubs now print "if finished, would respond with..." for debugging; law script changes require operator + Homunculus signatures; law script format added as open item. M2: removed Python/Rust from language options; confidence scale changed to [0.0, 10.0] per position. M3 hub: normalized all time horizons to ~40s wall time windows; confidence scale 0.00-10.00 with "X.XX/10.00" print format; gain rates as "low - mid - high / 10.00"; removed Python from language list across all sub-specs (M3a-M3g). M3a: Julia/R/Fortran/Octave replaces Python; fBM citation added (Hosking 1984, Wood & Chan 1994); confidence/correctness/certainty distinguished as 3 separate metrics; models span multiple horizons. M3b: models span multiple horizons note added; Mesa/Python removed. M3c: Solidity for on-chain precision; Julia/Octave for analytics. M3d-M3g: Python removed; confidence values updated to 10.0 scale. --- core/docs/plans/M0-economy-organ-hub.md | 23 +++++++++------- core/docs/plans/M1-marketplace.md | 18 ++++++++----- core/docs/plans/M2-data-feeds.md | 6 ++--- core/docs/plans/M3-sims-hub.md | 26 +++++++++++-------- core/docs/plans/M3a-statistical-sims.md | 24 +++++++++-------- core/docs/plans/M3b-sociological-sims.md | 16 +++++++----- core/docs/plans/M3c-amm-liquidity-sims.md | 7 ++--- core/docs/plans/M3d-mev-adversarial-sims.md | 10 +++---- core/docs/plans/M3e-tokenomics-macro-sims.md | 10 +++---- core/docs/plans/M3f-consensus-staking-sims.md | 6 ++--- .../plans/M3g-market-microstructure-sims.md | 10 +++---- 11 files changed, 86 insertions(+), 70 deletions(-) diff --git a/core/docs/plans/M0-economy-organ-hub.md b/core/docs/plans/M0-economy-organ-hub.md index d4eeccf..04cc588 100644 --- a/core/docs/plans/M0-economy-organ-hub.md +++ b/core/docs/plans/M0-economy-organ-hub.md @@ -23,11 +23,13 @@ TBD · new location e.g. `src/economy/`. The organ is polyglot by nature: tradin ## 4. Does / does-not - **Does:** host crypto/NFT trading via the Marketplace (M1); run always-on market prediction Sims (M3) fed by live Data Feeds (M2); manage sovereign-custody Wallets (M4); supervise - Traders (M5) via a Conductor (M6) and SAE monitor (M7); collect taxes on trader income and - stub transfer to Verschwörern Veregeister wallets. + Traders (M5) via a Conductor (M6); guard against anomalies via SAE monitor (M7); collect taxes + on trader income and stub transfer to Verschwörern Veregeister wallets; maintain a **ledger of + economy-related memories and patterns** (trade history, learned market patterns, calibration + state). - **Does-not:** consult the organism's Brain for trade decisions (scoped autonomy); route around - Ada for organism-bound messages (S1); store organism memories (E*); act as the organism's - conscience (that's Eth-Int / A6). + Ada for organism-bound messages (S1); store **organism** memories (E*) — economy-specific + memories stay local; act as the organism's conscience (that's Eth-Int / A6). ## 5. Interface contract - **Ichor interface (outbound):** `Envelope(Stomach, AdaBorder, OrganSecretion, payload)` — market @@ -35,14 +37,15 @@ TBD · new location e.g. `src/economy/`. The organ is polyglot by nature: tradin - **Ichor interface (inbound):** organism directives arrive via Ichor (e.g. risk posture changes, budget adjustments from A2 energy). - **Internal wiring:** Marketplace (M1) ↔ Data Feeds (M2) ↔ Sims (M3). Wallets (M4) bind to - Traders (M5). Conductor (M6) supervises Traders via SAE (M7). All trader actions route through - Marketplace. + Traders (M5). Conductor (M6) supervises Traders (M5). SAE (M7) acts as an independent + antivirus / guarddog / alarm bell — monitors via Ichor-routed messages and alerts M6. + All trader actions route through Marketplace. - **Tax stub:** `transfer_tax(amount, source_wallet, dest_wallet) -> receipt` — automation hook for Verschwörern Veregeister internal wallet-to-wallet transfer. **Out of scope** — stub only. ## 6. Dependencies & stubs - Ichor bus (D2) — existing `Broker` + `Envelope`. -- Ada border (D1) — screens outbound organism messages; *stub:* Ichor `Barrier`. +- Ada border (D1) — outbound economy envelopes cross here (S1); *stub:* Ichor `Barrier`. - A2 energy — potential consumer of economic signals; *stub:* no integration initially. - Verschwörern Veregeister wallets — tax destination; *stub:* log transfer, no real wallet. @@ -58,10 +61,10 @@ TBD · new location e.g. `src/economy/`. The organ is polyglot by nature: tradin SAE surveillance (M7), and wallet-level limits (M4) each independently constrain risk. ## 8. Build steps -1. Define the internal wiring topology (how M1–M7 connect). +1. Build sub-components (M1–M7) individually — each with defined success criteria and ablative tests. 2. Extend the existing `Stomach` primitive in Ichor to carry the hub facade. -3. Wire sub-components as their specs land. -4. Implement the tax stub for Verschwörern Veregeister transfer. +3. Define internal wiring topology and connect tested sub-components. +4. Implement tax stub and Verschwörern Veregeister transfer last. ## 9. Tests Hub smoke: Marketplace reachable; Sims running and queryable; Wallet bound to Trader; Conductor diff --git a/core/docs/plans/M1-marketplace.md b/core/docs/plans/M1-marketplace.md index 903c583..de91c84 100644 --- a/core/docs/plans/M1-marketplace.md +++ b/core/docs/plans/M1-marketplace.md @@ -23,7 +23,9 @@ signing (M4), and the Conductor (M6). Deterministic law script must be auditable (Wallets do); supervise behavior (Conductor + SAE do). ## 5. Interface contract -- `submit_action(trader_id, action: MarketAction, wallet_id) -> { accepted | vetoed | law_violation | no_wallet }`. +- `submit_action(trader_id, action: MarketAction, wallet_id) -> { succeeded | failed }`. + Diagnostic reasons (law violation, veto, missing wallet) are internal — routed to Conductor + (M6) for upstream output. Immune system is a separate organ (out of scope here). `MarketAction` ∈ { `buy`, `sell`, `mint`, `provide_liquidity`, `withdraw_liquidity`, `claim_rewards`, … }. - `law_check(action: MarketAction) -> { pass | violation(rule_id, reason) }` — deterministic, pure function. The law script is loaded at startup and **immutable at runtime** (mirrors S3 / @@ -35,18 +37,19 @@ signing (M4), and the Conductor (M6). Deterministic law script must be auditable - `tax_event(trader_id, income_amount) -> receipt` — triggers tax collection. ## 6. Dependencies & stubs -- M4 Wallets — signing + execution; *stub:* mock wallet that logs transactions. -- M5 Traders — action source; *stub:* canned trade requests. -- M6 Conductor — veto authority; *stub:* always-approve. -- M7 SAE — action log consumer; *stub:* print actions. -- Blockchain RPCs — on-chain execution; *stub:* simulated chain responses. +- M4 Wallets — signing + execution; *stub:* "if finished, would sign and broadcast tx [details]". +- M5 Traders — action source; *stub:* "if finished, would submit [action] for [asset] at [price]". +- M6 Conductor — veto authority; *stub:* "if finished, would evaluate [action] against risk policy; approving". +- M7 SAE — action log consumer; *stub:* "if finished, would analyze [action] for behavioral anomalies". +- Blockchain RPCs — on-chain execution; *stub:* "if finished, would execute [action] on [chain], returning tx_hash". ## 7. Invariants / laws - **L1 (C5):** **all market actions route through the Marketplace** — no direct on-chain execution by any trader. This is the economy organ's S1. - **L2 (C5):** the **deterministic law script is immutable at runtime** — loaded at startup, never modified by traders, conductor, or sims. Changes require a restart with a new script - version. Mirrors the COBOL vault (S3). + version **and a pair of signatures from the operator and the Homunculus**. Mirrors the COBOL + vault (S3). - **L3 (C4):** **no wallet, no access** — a trader without a bound wallet cannot submit actions. The Marketplace enforces this before any other check. - **L4 (C4):** **veto is checked after law, before execution** — law violations are rejected @@ -73,3 +76,4 @@ Tax: income event triggers tax stub. Immutability: law script cannot be modified - Position limits, drawdown stops, and other risk parameters — live in the law script or in the Conductor's judgment? - Tax rate / calculation method (fixed %, tiered, per-asset?). +- Non-Turing law script design — to discuss (format, expressiveness, bounds). diff --git a/core/docs/plans/M2-data-feeds.md b/core/docs/plans/M2-data-feeds.md index c2750c5..dcde588 100644 --- a/core/docs/plans/M2-data-feeds.md +++ b/core/docs/plans/M2-data-feeds.md @@ -11,7 +11,7 @@ DESIGN-FIRST · ABSENT. Role C3; implementation C1. ## 3. Language & location TBD · `src/economy/feeds/`. Needs async I/O for streaming data (WebSockets, SSE, RSS polling). -Pony actors are a natural fit (async, backpressure-aware). Python or Rust for API client libs. +Pony actors are a natural fit (async, backpressure-aware). ## 4. Does / does-not - **Does:** ingest live market data from external sources (RSS, price APIs, DEX subgraphs, @@ -30,8 +30,8 @@ Pony actors are a natural fit (async, backpressure-aware). Python or Rust for AP - `query_history(feed_type, time_range) -> [NormalizedDatum]` — sims and traders can pull historical data within the session window. - `NormalizedDatum { feed_type, source, timestamp, payload, confidence }` — common shape. - `confidence` ∈ [0.0, 1.0] — data source reliability (exchange-reported price = high; RSS - sentiment = lower). + `confidence` ∈ [0.0, 10.0] — data source reliability per position produced (exchange-reported + price = high; RSS sentiment = lower). Sims produce even finer-grained confidence. ## 6. Dependencies & stubs - External data sources (price APIs, RSS, RPC nodes) — *stub:* canned market data replay. diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 7882039..44bfaf8 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -15,9 +15,9 @@ DESIGN-FIRST · ABSENT. Role C3; implementation C1. Mathematical foundations C4 established); specific model parameters C1. ## 3. Language & location -TBD · `src/economy/sims/`. Numerical computing (Julia, Python/NumPy, Octave, or Rust) for the -simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g) may use a -different runtime suited to its math. +TBD · `src/economy/sims/`. Numerical computing (Julia, Octave, Fortran, R, Solidity, or C++) +for the simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g) may use +a different runtime suited to its math. ## 4. Does / does-not - **Does:** tick-advance continuously at **90:1** (1 wall-second = 90 simulated seconds) @@ -29,11 +29,11 @@ different runtime suited to its math. | Horizon | Window | Tick step | Effective ratio | Wall time for window | |---------|--------|-----------|-----------------|---------------------| | Tick–hourly | Next 1–60 min | 1s | 90:1 | ~40s | - | Daily | Next 24h | 1 min | 5,400:1 | ~16s | - | Weekly | Next 7d | 10 min | 54,000:1 | ~11s | - | Monthly | Next 30d | 1 hr | 324,000:1 | ~8s | - | Annual | Next 365d | 6 hr | 1,944,000:1 | ~16s | - | 5-year | Next 1825d | 1 day | 7,776,000:1 | ~20s | + | Daily | Next 24h | 24s | 2,160:1 | ~40s | + | Weekly | Next 7d | ~3 min | 15,120:1 | ~40s | + | Monthly | Next 30d | 12 min | 64,800:1 | ~40s | + | Annual | Next 365d | ~2.5 hr | ~788,000:1 | ~40s | + | 5-year | Next 1825d | 12 hr | ~3,942,000:1 | ~40s | - **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; run slower than 90:1. @@ -44,7 +44,10 @@ different runtime suited to its math. `tokenomics_macro`, `consensus_staking`, `market_microstructure` } (M3a–M3g). - `BoundedPrediction { value, lower_bound, upper_bound, confidence, time_horizon, sim_type, timestamp }`. Every output is bounded — no point estimates without uncertainty ranges. - Example: `{ value: 7.2, lower_bound: 5.8, upper_bound: 8.9, confidence: 0.73, + `confidence` ∈ [0.00, 10.00] — printed as `7.62/10.00`. Gain rates print as + `lower - value - upper / 10.00` (e.g. `2.31 - 4.44 - 7.11 / 10.00 gain over next 30 days`); + the denominator aids legibility — gain is not capped at 10.00. + Example: `{ value: 7.2, lower_bound: 5.8, upper_bound: 8.9, confidence: 7.30, time_horizon: "4h", sim_type: "amm_liquidity" }`. - `status(sim_type?) -> { running, pop_count, last_calibration, data_freshness }` — health check. - `calibrate(sim_type, feed_data: [NormalizedDatum])` — Data Feeds (M2) pushes live data for @@ -62,8 +65,9 @@ different runtime suited to its math. unbounded point estimates. Uncertainty is a first-class value, not an afterthought. - **L3 (C5):** all sims are **tick-advanced and continuous** — fine-grained ticks (RTS-style). Base speed **90:1** (1s wall = 90s sim). Longer horizons run at higher velocity with coarser - steps and update less frequently. Each horizon runs **in parallel** — they are concurrent, - not sequential. No horizon runs slower than 90:1. + steps and update less frequently. Each horizon completes its forecast window in **~40s wall + time**. Each horizon runs **in parallel** — they are concurrent, not sequential. No horizon + runs slower than 90:1. - **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim state. Calibration happens only from Data Feeds (M2). - **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. diff --git a/core/docs/plans/M3a-statistical-sims.md b/core/docs/plans/M3a-statistical-sims.md index 896c298..d54c0e2 100644 --- a/core/docs/plans/M3a-statistical-sims.md +++ b/core/docs/plans/M3a-statistical-sims.md @@ -16,10 +16,10 @@ execution C5 (industry standard since 2001). Jump-diffusion C5 (Merton 1976). Pa for crypto markets C1. ## 3. Language & location -TBD · `src/economy/sims/statistical/`. Python (NumPy/SciPy), Julia, or R for numerical -computing. Needs efficient matrix operations, SDE solvers, and distribution sampling. Fractional -Brownian motion generation requires specialized libraries (e.g. `fbm` in Python, or spectral -methods). +TBD · `src/economy/sims/statistical/`. Julia, R, Fortran, or Octave for numerical computing. +Needs efficient matrix operations, SDE solvers, and distribution sampling. Fractional Brownian +motion generation uses spectral methods (Hosking 1984, Wood & Chan 1994) or Cholesky +decomposition of the covariance matrix. ## 4. Does / does-not - **Does:** run Monte Carlo price simulations (GBM, Merton jump-diffusion, Heston stochastic @@ -52,11 +52,11 @@ methods). | Weekly–monthly | Jump-diffusion Monte Carlo, regime-conditional forecasts | Hourly roll | | Annual–5yr | SDE mean-reversion long-run $\theta$, macro regime priors | Daily roll | - Examples: - `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 0.95, + `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 9.50, time_horizon: "24h", sim_type: "statistical" }` — 95% CI on ETH price. - `{ value: 0.72, lower_bound: 0.58, upper_bound: 0.89, confidence: 0.90, + `{ value: 0.72, lower_bound: 0.58, upper_bound: 0.89, confidence: 9.00, time_horizon: "1h", sim_type: "statistical" }` — Heston instantaneous vol $\sqrt{\nu_t}$. - `{ value: "bear", lower_bound: null, upper_bound: null, confidence: 0.83, + `{ value: "bear", lower_bound: null, upper_bound: null, confidence: 8.30, time_horizon: "current", sim_type: "statistical" }` — HMM regime state. - **Prediction types:** `price_forecast`, `volatility_surface`, `var_calculation`, `correlation_matrix`, `regime_state`, `rough_vol_estimate`, `jump_intensity`. @@ -68,10 +68,12 @@ methods). ## 7. Invariants / laws - **L1 (C5):** bounds are **statistical confidence intervals** — derived from the model's - distribution, not hand-picked. The confidence level (e.g. 0.95) is explicit in the output. -- **L2 (C5):** **six time horizons run concurrently** — tick-level rough vol, hourly regime - detection, daily Heston surface, weekly Monte Carlo, annual mean-reversion, and 5-year macro - forecasts coexist; none blocks the others. + distribution, not hand-picked. Three distinct metrics in every output: **confidence** (how sure + the model is of this prediction), **correctness** (how accurate the model has been historically), + and **certainty** (how stable the estimate is across perturbations). All on the 0.00–10.00 scale. +- **L2 (C5):** **six time horizons run concurrently** — models span multiple horizons (e.g. + Monte Carlo runs daily and annual, rough vol runs tick and hourly, Heston runs daily and + weekly). All coexist; none blocks the others. - **L3 (C4):** model parameters are **re-estimated on each calibration** from live data — no stale parameters carried across regime changes. Regime transitions trigger immediate re-estimation of conditional parameters. diff --git a/core/docs/plans/M3b-sociological-sims.md b/core/docs/plans/M3b-sociological-sims.md index 79b6d23..f2e17c8 100644 --- a/core/docs/plans/M3b-sociological-sims.md +++ b/core/docs/plans/M3b-sociological-sims.md @@ -17,9 +17,9 @@ solvers C3). Crypto pump-and-dump ABM C3 (3-agent protocol validated on historic Pop behavioral models C1. ## 3. Language & location -TBD · `src/economy/sims/sociological/`. Agent-based modeling frameworks (Mesa/Python, NetLogo, -or custom). Needs efficient population iteration, strategy mutation, PDE solvers for MFG -(HJB + Fokker-Planck), and bandit algorithms (UCB/Thompson). +TBD · `src/economy/sims/sociological/`. Agent-based modeling frameworks (NetLogo, or custom). +Needs efficient population iteration, strategy mutation, PDE solvers for MFG (HJB + +Fokker-Planck), and bandit algorithms (UCB/Thompson). Julia, R, or Fortran. ## 4. Does / does-not - **Does:** simulate populations of behavioral archetypes competing in a market; apply @@ -59,14 +59,16 @@ or custom). Needs efficient population iteration, strategy mutation, PDE solvers | Annual | Long-run evolutionary stable strategies (ESS) | Monthly roll | | 5-year | MFG stationary equilibria, structural population shifts | Quarterly roll | - Examples: - `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 0.68, + `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 6.80, time_horizon: "12h", sim_type: "sociological" }` — herd-panic index (0–10). - `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 0.72, + `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 7.20, time_horizon: "1w", sim_type: "sociological" }` — fraction of pops in "contrarian" strategy. - `{ value: "promotion", lower_bound: null, upper_bound: null, confidence: 0.61, + `{ value: "promotion", lower_bound: null, upper_bound: null, confidence: 6.10, time_horizon: "current", sim_type: "sociological" }` — pump-and-dump phase detection. - `{ value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 0.70, + `{ value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 7.00, time_horizon: "30d", sim_type: "sociological" }` — MFG equilibrium stability index. + Models span multiple horizons — e.g. replicator dynamics runs hourly through annual; MFG + produces weekly equilibria and 5-year stationary states. The table shows primary assignments. - **Prediction types:** `sentiment_index`, `herd_threshold`, `strategy_distribution`, `cascade_probability`, `coordination_stability`, `opinion_cluster_count`, `pump_dump_phase`, `mfg_equilibrium_stability`, `narrative_regime`. diff --git a/core/docs/plans/M3c-amm-liquidity-sims.md b/core/docs/plans/M3c-amm-liquidity-sims.md index eff6850..e91701b 100644 --- a/core/docs/plans/M3c-amm-liquidity-sims.md +++ b/core/docs/plans/M3c-amm-liquidity-sims.md @@ -13,7 +13,8 @@ simulation parameterization C1. ## 3. Language & location TBD · `src/economy/sims/amm/`. Needs precise fixed-point or arbitrary-precision arithmetic for -invariant calculations (Solidity-equivalent precision). Python, Rust, or Julia. +invariant calculations. Solidity for on-chain-equivalent precision; Julia or Octave for +analytical models. ## 4. Does / does-not - **Does:** simulate constant-product pools with fee parameter $\gamma$: @@ -27,9 +28,9 @@ invariant calculations (Solidity-equivalent precision). Python, Rust, or Julia. ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** IL ranges and pool return intervals. - Example: `{ value: -0.034, lower_bound: -0.058, upper_bound: -0.012, confidence: 0.90, + Example: `{ value: -0.034, lower_bound: -0.058, upper_bound: -0.012, confidence: 9.00, time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool. - Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 0.85, + Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 8.50, time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL). - **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md index 013b3bb..ba0128e 100644 --- a/core/docs/plans/M3d-mev-adversarial-sims.md +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -19,9 +19,9 @@ optimization C3 (emerging — SMFRL solvers); Kolokoltsov adversarial C3 (non-li WENO discretization established but crypto application novel). Parameterization C1. ## 3. Language & location -TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (PuLP/OR-Tools for knapsack), +TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (OR-Tools for knapsack), continuous-time auction modeling, PDE solvers (WENO for shock-capturing in adversarial dynamics), -and bilevel optimization (DSMFG). Python, Rust, or Julia. +and bilevel optimization (DSMFG). Julia, Fortran, or C++. ## 4. Does / does-not - **Does:** simulate Priority Gas Auctions where multiple searcher bots compete for the same @@ -57,11 +57,11 @@ and bilevel optimization (DSMFG). Python, Rust, or Julia. | Annual | Kolokoltsov adversarial long-run dynamics | Monthly roll | | 5-year | Structural MEV regime shifts, protocol-level policy effects | Quarterly roll | - Examples: - `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 0.80, + `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 8.00, time_horizon: "next_block", sim_type: "mev_adversarial" }` — sandwich probability. - `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 0.75, + `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 7.50, time_horizon: "next_block", sim_type: "mev_adversarial" }` — optimal gas bid (gwei). - `{ value: 0.034, lower_bound: 0.018, upper_bound: 0.052, confidence: 0.82, + `{ value: 0.034, lower_bound: 0.018, upper_bound: 0.052, confidence: 8.20, time_horizon: "1h", sim_type: "mev_adversarial" }` — cross-chain arb profit (ETH). - **Prediction types:** `sandwich_probability`, `frontrun_risk`, `optimal_gas_bid`, `block_inclusion_probability`, `mev_exposure`, `cross_chain_arb_profit`, diff --git a/core/docs/plans/M3e-tokenomics-macro-sims.md b/core/docs/plans/M3e-tokenomics-macro-sims.md index 4f6ba52..35e80f6 100644 --- a/core/docs/plans/M3e-tokenomics-macro-sims.md +++ b/core/docs/plans/M3e-tokenomics-macro-sims.md @@ -21,7 +21,7 @@ composable yield optimization C4 (Yearn v3, Beefy, production-validated). Specif ## 3. Language & location TBD · `src/economy/sims/tokenomics/`. Needs SDE solvers (Euler-Maruyama, Milstein), state-space estimation, and VAR (vector autoregression) for credit exposure impulse responses. -Julia (DifferentialEquations.jl), Python (scipy), or Octave. +Julia (DifferentialEquations.jl) or Octave. ## 4. Does / does-not - **Does:** simulate token state dynamics via the SDE framework: @@ -59,13 +59,13 @@ Julia (DifferentialEquations.jl), Python (scipy), or Octave. | Annual | Halving/burn policy impacts, inflation trajectory | Monthly roll | | 5-year | Token supply long-run equilibrium, protocol lifecycle | Quarterly roll | - Examples: - `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 0.90, + `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 9.00, time_horizon: "90d", sim_type: "tokenomics_macro" }` — annualized inflation rate (%). - `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 0.85, + `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 8.50, time_horizon: "30d", sim_type: "tokenomics_macro" }` — staking ratio. - `{ value: 0.83, lower_bound: 0.78, upper_bound: 0.91, confidence: 0.88, + `{ value: 0.83, lower_bound: 0.78, upper_bound: 0.91, confidence: 8.80, time_horizon: "1h", sim_type: "tokenomics_macro" }` — Aave ETH utilization rate. - `{ value: 0.12, lower_bound: 0.04, upper_bound: 0.25, confidence: 0.72, + `{ value: 0.12, lower_bound: 0.04, upper_bound: 0.25, confidence: 7.20, time_horizon: "7d", sim_type: "tokenomics_macro" }` — systemic contagion risk index. - **Prediction types:** `supply_trajectory`, `inflation_rate`, `staking_ratio`, `velocity_estimate`, `halving_impact`, `treasury_runway`, `utilization_rate`, diff --git a/core/docs/plans/M3f-consensus-staking-sims.md b/core/docs/plans/M3f-consensus-staking-sims.md index d807da5..4836ccb 100644 --- a/core/docs/plans/M3f-consensus-staking-sims.md +++ b/core/docs/plans/M3f-consensus-staking-sims.md @@ -15,7 +15,7 @@ simulation parameterization C1. ## 3. Language & location TBD · `src/economy/sims/consensus/`. Needs Markov chain solvers and game-theoretic equilibrium -computation. Python, Julia, or R. +computation. Julia, R, or Fortran. ## 4. Does / does-not - **Does:** simulate validator populations where honesty evolves via **evolutionary game theory** @@ -34,10 +34,10 @@ computation. Python, Julia, or R. ## 5. Interface contract - Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. - **Output bounds:** equilibrium stability ranges and yield intervals. - Example: `{ value: 0.89, lower_bound: 0.82, upper_bound: 0.94, confidence: 0.88, + Example: `{ value: 0.89, lower_bound: 0.82, upper_bound: 0.94, confidence: 8.80, time_horizon: "7d", sim_type: "consensus_staking" }` — fraction of validators honest in equilibrium. - Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 0.82, + Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 8.20, time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%). - **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): | Horizon | Primary models | Update cadence | diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md index 78da588..dfcae6e 100644 --- a/core/docs/plans/M3g-market-microstructure-sims.md +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -16,8 +16,8 @@ Kurz CMC thesis). DEX-specific microstructure C2 (emerging). Implementation C1. ## 3. Language & location TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling, event-driven -simulation, and Riccati equation solvers for optimal execution trajectories. Rust, C++, or -Python with optimized event loop. +simulation, and Riccati equation solvers for optimal execution trajectories. C++, Fortran, +or Julia. ## 4. Does / does-not - **Does:** simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a @@ -46,11 +46,11 @@ Python with optimized event loop. | Annual | Microstructure regime (DEX vs CEX share evolution) | Monthly roll | | 5-year | Venue topology evolution, structural impact trends | Quarterly roll | - Examples: - `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 0.85, + `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 8.50, time_horizon: "next_trade", sim_type: "market_microstructure" }` — slippage (%) for 10 ETH. - `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 0.78, + `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 7.80, time_horizon: "1h", sim_type: "market_microstructure" }` — depth (USD) within 50bps. - `{ value: [0.3, 0.3, 0.2, 0.1, 0.1], lower_bound: null, upper_bound: null, confidence: 0.80, + `{ value: [0.3, 0.3, 0.2, 0.1, 0.1], lower_bound: null, upper_bound: null, confidence: 8.00, time_horizon: "30min", sim_type: "market_microstructure" }` — Almgren-Chriss optimal execution schedule (fraction per 6-min bucket for 100 ETH sell). - **Prediction types:** `slippage_estimate`, `spread_forecast`, `depth_profile`, From c5b0f14a79b67209bf2c4dfeef5734f472abaa50 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 00:50:44 +0000 Subject: [PATCH 14/14] Remove C++ from language options (CVE concern) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Dropped from M3 hub, M3d, and M3g — Julia and Fortran remain as the high-performance alternatives. --- core/docs/plans/M3-sims-hub.md | 2 +- core/docs/plans/M3d-mev-adversarial-sims.md | 2 +- core/docs/plans/M3g-market-microstructure-sims.md | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md index 44bfaf8..67de9b6 100644 --- a/core/docs/plans/M3-sims-hub.md +++ b/core/docs/plans/M3-sims-hub.md @@ -15,7 +15,7 @@ DESIGN-FIRST · ABSENT. Role C3; implementation C1. Mathematical foundations C4 established); specific model parameters C1. ## 3. Language & location -TBD · `src/economy/sims/`. Numerical computing (Julia, Octave, Fortran, R, Solidity, or C++) +TBD · `src/economy/sims/`. Numerical computing (Julia, Octave, Fortran, R, or Solidity) for the simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g) may use a different runtime suited to its math. diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md index ba0128e..08c395c 100644 --- a/core/docs/plans/M3d-mev-adversarial-sims.md +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -21,7 +21,7 @@ WENO discretization established but crypto application novel). Parameterization ## 3. Language & location TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (OR-Tools for knapsack), continuous-time auction modeling, PDE solvers (WENO for shock-capturing in adversarial dynamics), -and bilevel optimization (DSMFG). Julia, Fortran, or C++. +and bilevel optimization (DSMFG). Julia or Fortran. ## 4. Does / does-not - **Does:** simulate Priority Gas Auctions where multiple searcher bots compete for the same diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md index dfcae6e..469c842 100644 --- a/core/docs/plans/M3g-market-microstructure-sims.md +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -16,8 +16,7 @@ Kurz CMC thesis). DEX-specific microstructure C2 (emerging). Implementation C1. ## 3. Language & location TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling, event-driven -simulation, and Riccati equation solvers for optimal execution trajectories. C++, Fortran, -or Julia. +simulation, and Riccati equation solvers for optimal execution trajectories. Fortran or Julia. ## 4. Does / does-not - **Does:** simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a