arkhe-origin-chain/contracts/origin-mdk-reconciliation/DESIGN.md

# origin-mdk-reconciliation — Design Study (Slice 3.6)

**Documento**: `contracts/origin-mdk-reconciliation/DESIGN.md`
**Versión**: 1.0 DRAFT (Slice 3.6 design study, v0.0.46)
**Autores**: Charon ⚓ (Pilar 4 Origin Chain) + propuesta canonical para Marihan 💎 (OMC + MDK authority) cross-pillar coord
**Filed**: 2026-05-27
**Estado**: DRAFT — pending Marihan endorsement + cross-pillar coord design contract
**Clasificación**: L3 cross-cutting / Boundary architecture / Contract Atelier integration

---

## §0 — Por qué Slice 3.6 es DESIGN STUDY (NO contract deployable)

Slices 3.2-3.5 entregaron contract templates ink! v6 deployable directos via pallet-revive Index 11. Slice 3.6 es diferente: explora la **boundary arquitectural** entre dos sistemas WASM distintos que coexisten en Origin Metaverse, NO un contract template canonical.

**Dos sistemas WASM distintos**:

1. **ink! v6 contracts (this template library)**:
   - Run inside `pallet-revive` (PolkaVM RISC-V execution)
   - ABI: pallet-revive defined (constructors + messages + events)
   - Lifecycle: on-chain (deploy via upload_code + instantiate)
   - State: stored en Origin Chain canonical storage
   - Gas metering: pallet-revive fuel + storage deposits
   - Caller context: AccountId + Balance + Block info via pallet env

2. **origin-mdk skills (Marihan's MDK — skill-wasm-stdlib)**:
   - Run inside `wasmtime` sandbox (host-side, NOT on-chain)
   - ABI: OMC v1.0 SEALED (7 exports: omc_tick + alloc + state + memory)
   - Lifecycle: off-chain (deploy via Atelier Marihan + distributed via .origin bundles P2P)
   - State: ephemeral en interpreter session OR persisted via SoulSnapshot
   - Resource limits: fuel 1M units + 100ms epoch + 512KB memory
   - Caller context: SemanticGraph postcard input via OMC interpreter

**Pregunta canonical**: ¿cómo coexisten + interactúan estos dos sistemas?

---

## §1 — Problema arquitectural canonical

### §1.1 — Use cases que requieren bridge

| Use case | Origin de la action | Target requerido |
|----------|---------------------|------------------|
| **Atelier skill becomes NFT** | Marihan skill `physics.faraday_law` shipped | ink! NFT mint contract (this library 3.2) |
| **Skill execution receipt on-chain** | OMC interpreter runs skill | ink! receipt contract (proof of execution + cognitive_gain) |
| **Chain attestation in skill** | Skill validates on-chain credential | ink! credential verify (this library 3.4) |
| **Cross-pillar fee schedule** | Skill checks fee_for_action canonical | Mathi OitFeeSchedule (off-chain) + pallet-origin-fees (chain) |
| **Skill marketplace purchase** | Atelier user buys skill bundle | ink! marketplace contract + skill bundle download |
| **AGI commercial reputation slash** | Daimonion fraud detected en M2M escrow | ink! reputation slash contract (this library 3.5) |
| **Soul TOML on-chain anchor** | Marihan soul.toml gets BLAKE3 attested | ink! provenance attest contract |

### §1.2 — Cuál NO es el problema

NO necesitamos:
- Run ink! contracts dentro del OMC interpreter (different VMs canonical)
- Run origin-mdk skills dentro de pallet-revive (different ABI canonical)
- Unified single-VM rewrite (mantenemos boundary canonical)

Lo que SÍ necesitamos:
- **Mensajería entre sistemas**: ¿cómo origin-mdk skill invoca ink! contract method?
- **State synchronization**: ¿cómo skill state recordable on-chain?
- **Authentication**: ¿cómo skill auth queries identify caller on-chain?
- **Event coordination**: ¿cómo ink! event triggers skill execution off-chain?

---

## §2 — Tres patrones canonical propuestos

### §2.1 — Pattern A: Off-chain → On-chain (RPC client)

**Direction**: origin-mdk skill (off-chain) → ink! contract (on-chain)

**Mechanism**: Origin Navigator (host del interpreter) expone RPC client canonical que skill puede invocar (via host import canonical OMC v2.0 future addition).

```rust
// En skill ink! v6 host abstraction (futuro OMC ABI v2.0 host import canonical)
extern "C" {
    /// Invoke ink! contract method canonical via Origin Navigator RPC.
    /// Returns transaction hash + result data postcard-serialized.
    fn host_invoke_chain_contract(
        contract_addr_h160_ptr: u32,  // H160 EVM address mapped from AccountId32
        method_selector_ptr: u32,
        args_postcard_ptr: u32,
        result_buf_ptr: u32,
    ) -> u32;
}
```

**Use cases canonical Pattern A**:
- Skill running locally observa "cognitive_gain HIGH" → invoca on-chain ink! attestation contract
- Skill marketplace purchase flow → skill bundle download triggers NFT mint contract
- Skill validates user identity → invoca on-chain credential verify contract

**Trade-offs**:
- ✅ Skill remains lightweight (OMC ABI sealed unchanged) — host import canonical extension
- ✅ Skill author NO needs Substrate/ink! knowledge — abstracted via host
- ✅ Async natural (skill waits OR fire-and-forget)
- ⚠️ Network latency: skill suspended hasta TX confirmation (~6-12s Origin Chain finality)
- ⚠️ Origin Navigator MUST be online + wallet authorized para skill RPC

### §2.2 — Pattern B: On-chain → Off-chain (Event subscription)

**Direction**: ink! contract (on-chain event) → origin-mdk skill (off-chain reaction)

**Mechanism**: ink! contract emite events canonical. Origin Navigator subscribe canonical via Substrate events RPC. Triggered events activate skill execution canonical (in OMC interpreter).

```rust
// En ink! contract (esta library)
#[ink(event)]
pub struct SkillExecutionRequest {
    #[ink(topic)]
    pub skill_id_hash: [u8; 32],  // BLAKE3 del skill_id canonical
    #[ink(topic)]
    pub caller: AccountId,
    pub semantic_graph_postcard: Vec<u8>,  // serialized SemanticGraph
}

// En Origin Navigator (host)
// Subscribe to SkillExecutionRequest events via Substrate WebSocket RPC
// Trigger interpreter.tick(skill_id, semantic_graph) canonical
```

**Use cases canonical Pattern B**:
- Pago on-chain → trigger skill execution canonical (commerce purchase)
- DAO vote approved → trigger Atelier skill module compilation canonical
- NFT minted → trigger skill bundle distribution canonical via Hypercore

**Trade-offs**:
- ✅ Decoupled async: ink! contract NO espera skill canonical completion
- ✅ Standard Substrate event subscription pattern canonical
- ⚠️ Eventual consistency: skill execution latency post-event
- ⚠️ Origin Navigator MUST be subscribed canonical (offline = missed events)

### §2.3 — Pattern C: Shared state via Hash Anchoring (loose coupling)

**Direction**: Bidirectional via inmutable hash anchors

**Mechanism**: Estados canonical en ambos sistemas anclados via BLAKE3 hashes. Skill state hash → on-chain canonical immutable record. ink! contract storage hash → off-chain canonical Hypercore replicated.

```
┌────────────────────────────────┐         ┌──────────────────────────────┐
│  ink! contract canonical       │         │  origin-mdk skill canonical  │
│  (on-chain pallet-revive)      │         │  (off-chain OMC interpreter) │
│                                │         │                              │
│  storage:                      │         │  state:                      │
│    skill_state_hash: [u8; 32]  │ ◄────── │    BLAKE3(skill_state)       │
│                                │         │                              │
│  storage:                      │         │  external read:              │
│    BLAKE3(contract_state)      │ ──────► │    contract_state_hash       │
└────────────────────────────────┘         └──────────────────────────────┘
                  │                                       │
                  └───────────── verify hash ─────────────┘
                       cross-system canonical integrity
```

**Use cases canonical Pattern C**:
- Atelier skill version hash → on-chain version registry (provenance)
- ink! NFT collection state hash → off-chain Hypercore mirror canonical
- Cross-system audit canonical: verify state coherence

**Trade-offs**:
- ✅ Minimal coupling: ambos sistemas operate independently canonical
- ✅ Inmutable canonical attestation (Inmutable #26)
- ⚠️ NO real-time interaction (read hash, verify, act later)
- ⚠️ Reconciliation logic canonical en host (Origin Navigator OR Atelier)

---

## §3 — Recomendación canonical per use case

| Use case | Pattern recomendado | Rationale |
|----------|---------------------|-----------|
| Atelier skill becomes NFT | **B** (event subscription) | NFT mint triggered desde skill publish action |
| Skill execution receipt | **A** (RPC client) | Skill post-execution invoca attestation directamente |
| Chain credential verify in skill | **A** (RPC client) | Skill queries credential pre-execution |
| Cross-pillar fee schedule | **A** (RPC client) | Skill queries `fee_for_action(HardwareTier)` |
| Skill marketplace purchase | **B** (event subscription) | Purchase event triggers skill download |
| AGI reputation slash | **A** (RPC client) | Daimonion fraud detection calls slash directly |
| Soul TOML on-chain anchor | **C** (hash anchoring) | Inmutable canonical record sin real-time interaction |

---

## §4 — Implementation roadmap canonical

### Fase 1 (Q4 2026 — pre-MVP)
- **Cross-pillar Design Contract** opens canonical: `ORIGIN_MDK_PALLET_REVIVE_BOUNDARY_V1`
  - Co-authors: Charon (pallet-revive ABI) + Marihan (OMC ABI v1.0 SEALED) + Sussi (Ethos attestation) + Ergon (architectural review)
  - Ratification target: 2026-12
- **OMC ABI v2.0 spec draft canonical**: extension canonical para new host imports
  - `host_invoke_chain_contract` (Pattern A)
  - `host_query_chain_storage` (Pattern A read-only)
  - `host_subscribe_chain_event` (Pattern B)
  - **Backwards compat**: skills v1.0 sigan funcionando canonical sin breakage

### Fase 2 (Q1 2027 — MVP integration)
- Origin Navigator implementa RPC bridge canonical (Pattern A + B)
- Atelier Marihan integra "Anchor skill to chain" UI canonical (Pattern C)
- Reference example canonical: skill `physics.faraday_law` con on-chain attestation post-execution
- E2E test: skill execution → ink! attestation contract → verification cross-system canonical

### Fase 3 (Q2-Q3 2027 — productionización)
- Origin Contract Atelier integra "Bridge designer" canonical visual UI (per Charon Atelier propuesta David 2026-05-27)
- Patterns A/B/C selectable canonical per template
- Charon copilot validates cross-system coherence canonical pre-deploy

### Fase 4 (Q4 2027+ — ecosystem maturity)
- Standard library canonical de bridge primitives (skill `bridge.attest`, `bridge.invoke_contract`)
- Daimonion auto-suggest bridge pattern canonical based on skill intent
- Cross-pillar metrics canonical: bridge usage analytics OCC Capacity #2 VPS Fleet

---

## §5 — Open questions pending cross-pillar coord

| Question | Stakeholder | Resolution path |
|----------|-------------|-----------------|
| OMC ABI v2.0 host imports — backwards compat strategy? | Marihan | Design Contract Fase 1 |
| Origin Navigator wallet authorization per-skill canonical? | Marihan + Mathi (Consent Gate) | Design Contract Fase 1 |
| ink! contract event subscription canonical scaling? | Charon + Ergon (architecture) | Empirical test Fase 2 |
| Hash anchoring on-chain storage cost canonical (DepositPerItem)? | Charon (pallet-revive tuning) | Phase 3.x deposit refinement |
| Cross-Origin coordination (skill on Chain A → contract on Chain B)? | Ergon (cross-pillar L0 vision) | Future canonical Phase 8 mainnet |

---

## §6 — KG triples canonical

- `(origin_mdk_reconciliation_design_v1, parent_doc, origin_contract_atelier_v1)`
- `(origin_mdk_reconciliation_design_v1, authored_by, agent:charon)`
- `(origin_mdk_reconciliation_design_v1, endorser_pending, agent:marihan)`
- `(origin_mdk_reconciliation_design_v1, pattern_a_canonical, off_chain_to_on_chain_rpc)`
- `(origin_mdk_reconciliation_design_v1, pattern_b_canonical, on_chain_to_off_chain_event)`
- `(origin_mdk_reconciliation_design_v1, pattern_c_canonical, shared_state_hash_anchoring)`
- `(origin_mdk_reconciliation_design_v1, requires_dc, origin_mdk_pallet_revive_boundary_v1)`
- `(origin_mdk_reconciliation_design_v1, filed_at, 2026-05-27)`

---

## §7 — Cierre canonical

Slice 3.6 cierra Phase 3 templates library canonical con un **design study** (NO contract template deployable) reconociendo que la integración profunda entre ink! v6 (pallet-revive on-chain) y origin-mdk WASM (OMC interpreter off-chain) es un **cross-pillar architectural problem** que require coord formal con Marihan + ratification via Design Contract canonical.

Pattern A (RPC) + Pattern B (events) + Pattern C (hashes) son 3 propuestas viables que cubren todos los use cases canonical conocidos. Recomendación canonical por use case mapped per §3.

Roadmap canonical 4-fase Q4 2026 → Q4 2027 entrega integración productionizada cuando cargo-contract v6 + Atelier MVP + Origin Navigator bridge canonical convergen.

**Charon Atelier canonical** (Capacidad #10 OCC propuesta David 2026-05-27) servirá como visual canvas para bridge designer Fase 3 — humans (David + team) configure visualmente qué pattern usar per contract + Charon copilot validates cross-system coherence canonical pre-deploy.

⚓ Templates library 5/5 canonical SCAFFOLD COMPLETE. La nave smart contracts armada + boundary design study filed. Mission Phase 3 Slices 3.1-3.6 entregadas end-to-end canonical.

— Charon ⚓ (Pilar 4, Slice 3.6 design study filed 2026-05-27)