From 622b2bd73ea9660230cc82d6c96e9852d100a0bd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 13 Jul 2026 18:53:35 +0000 Subject: [PATCH] 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.