ICN Repo Reality Map

Generated: 2026-02-17 | Branch: main @ 6943792e Purpose: Evidence-driven inventory of every ICN plane. Every claim cites a file path. If a claim cannot cite a file path, it is labeled [SPECULATION].

Table of Contents

1. Red-Flag Questions (Answered First)
2. Governance → Effects → Ledger Saga
3. Identity Plane
4. Network Plane
5. Gossip Plane
6. Ledger/Economics Plane
7. Compute Plane
8. Gateway/UI Surface
9. Privacy/Crypto Plane
10. Idempotency Layer Map
11. Critical Gap Summary

1. Red-Flag Questions

Q1: Where is the canonical decision hash derived?

Answer: icn-governance/src/proof.rs:330-345

pub fn compute_decision_hash(
    proposal_id: &str,
    domain_id: &str,
    outcome: ProofOutcome,
    vote_tally: &VoteTally,
    vote_hash: &Hash,
) -> Hash

What it hashes (domain tag b"icn:gov:decision:v1"):

• proposal_id (length-prefixed)
• domain_id (length-prefixed)
• outcome ordinal (0=Accepted, 1=Rejected, 2=NoQuorum)
• vote_tally: for_votes, against_votes, abstain_votes (each u64 LE)
• vote_hash: 32-byte Merkle root of sorted votes

Vote hash (proof.rs:116-139): Sorts votes by (voter_did, choice_ordinal) deterministically, creates Merkle root from [voter_did, choice_ordinal, weight] tuples. Domain tag: b"icn:vote-hash:v1".

Property: Canonical — same decision produces same hash across all nodes. This is the idempotency key for the entire execution pipeline.

Q2: Where is the treasury nonce checked on the actual mutation path?

Answer: IT IS NOT. The nonce mechanism exists but is not wired into the execution path.

• Nonce mechanism defined: icn-coop/src/store.rs:112-206 — check_and_increment_treasury_nonce() does atomic sled CAS (compare-and-swap)
• Not called from: KernelGovernanceExecutor::execute_treasury_operation() in icn-core/src/supervisor/governance_executor.rs:318-571
• Result: A single governance decision could replay at the ledger level if the executor store write crashes after the ledger write but before the execution record is marked Confirmed

Q3: What ledger-level idempotency mechanism exists?

Answer: None today. Idempotency is enforced only at:

• Level 1: ExecutionStore (decision_hash → terminal check) — icn-core/src/supervisor/decision_executor.rs:225
• Level 2: Domain stores (BudgetRecord tracks decision_hash per spend; EscrowRecord tracks release_decision_hash)
• Level 3: [MISSING] — No ledger-level deduplication. No (decision_hash, entry_hash) mapping in the ledger.

Q4: What is the minimal gateway API contract for a pilot UI + wallet?

Answer: The gateway has 40+ route modules but no unified service layer boundary.

• icn-api/src/lib.rs exists (45 lines) with partial ComputeService — no LedgerService, GovernanceService, EntityService
• Gateway routes in icn-gateway/src/api/*.rs call managers directly (not through icn-api)
• RPC handlers in icn-rpc/src/handler/compute.rs:50-95 DO use icn_api::SubmitTaskParams
• Result: Two code paths to the same operation (REST vs RPC), likely with divergent behavior

2. Governance → Effects → Ledger Saga

This is the critical vertical path for the pilot. End-to-end:

Step 1: Proposal Closes → Decision Receipt

Source: icn-governance/src/proof.rs:250-271

When a proposal closes with Accepted/Rejected/NoQuorum, a GovernanceDecisionReceipt is created containing the canonical decision_hash.

Proposal state machine: icn-governance/src/proposal.rs:1-217

• States: Draft → Deliberation → Open → {Accepted | Rejected | NoQuorum | Cancelled | Vetoed | ForceClosed}
• Transitions enforced by methods: start_deliberation(), open(), close(), etc.

Step 2: Event Emission

Source: apps/governance/src/actor.rs (event bus integration)

Emits SystemEvent::ProposalAccepted { proposal_id, domain_id, payload, decided_at } via EventBus::emit().

Step 3: Effect Translation (Payload → KernelEffect)

Status: [GAP] — No explicit code translates ProposalPayload → KernelEffect[].

• Tests manually construct effects
• Payload variants defined in icn-governance/src/proposal.rs:220+: Budget, FreezeMember, ResourceAccess, ConfigChange, ProtocolChange, TextResolution
• Effect variants defined in icn-kernel-api/src/effects.rs: TreasuryEffect::Spend, CreateBudget, ReleaseEscrow, etc.
• Risk: Payload variants and effect variants could drift silently

Step 4: Decision Executor

Source: icn-core/src/supervisor/decision_executor.rs:217-379

execute(effects, decision_receipt_id, decision_hash, proposal_id) → Vec<EffectResult>

Idempotency check (line 225): If store.get(decision_hash)?.is_terminal() → skip.

Status machine: icn-kernel-api/src/execution.rs:14-166

Pending → Executing → Confirmed
                   ↘ Failed → (retry) → Executing
                            ↘ PermanentlyFailed (MAX_RETRIES=3)

Persistence: Sled-backed ExecutionStore. Effects stored in record for crash recovery.

Backpressure: tokio::sync::Semaphore with MAX_CONCURRENT_EXECUTIONS=16.

Observability (PR #1203):

• Recovery scan log with status distribution counts
• Per-decision status_before → status_after transition logs
• Semaphore saturation warning (>100ms wait)

Step 5: Effect Dispatch

Source: icn-core/src/supervisor/governance_executor.rs:318-571

KernelGovernanceExecutor implements EffectExecutor trait. Routes to specialized executors:

• TreasuryExecutor (Spend, Allocate, Release)
• ProtocolExecutor (SetParameter, Config)
• ControlExecutor (Veto, ForceClose)
• MembershipExecutor (Add, Remove, Freeze)
• FederationExecutor (Join, Vouch)

Step 6: Treasury Sagas

Budget Spend (governance_executor.rs, Path 2):

1. budget.begin_spend(decision_hash, amount) → validates capacity, stores pending
2. Ledger mutation via submit_treasury_entry()
3. budget.confirm_spend() → transitions Pending → Spent

Escrow Release (governance_executor.rs, Path 3):

1. escrow.begin_release(decision_hash) → transitions Locked → Releasing, stores release_decision_hash
2. Ledger mutation via submit_treasury_entry()
3. escrow.confirm_release() → transitions Releasing → Released

Step 7: Ledger Mutation

Source: icn-ledger/src/ledger.rs (5,447 LOC)

• Double-entry accounting: each journal entry has debit[] and credit[] sides
• append_entry() returns entry_hash
• Merkle-DAG for immutable history

Gap: submit_treasury_entry() exists and returns entry_hash, but:

• Entry hash is NOT routed back to ExecutionRecord.ledger_entry_ids (audit trail incomplete)
• No state_change_hash computed for treasury operations (protocol/federation effects DO compute them)
• Ledger service integration is stubbed in tests — if let Some(ledger) = &self.ledger falls back to placeholder

What Tests Prove

3. Identity Plane

What Exists

What Tests Prove

Missing/Risky

• HSM/TPM backends feature-gated and experimental (keystore_pkcs11.rs, keystore_tpm.rs)
• Recovery → KeyBundle rotation integration unclear (RecoveryReason::Recovery exists but wiring not visible)
• Revocation appeal deadline enforcement: no periodic task auto-finalizes
• DID resolution over network: DidDocument exists but no resolution endpoint in identity crate [SPECULATION: likely in gateway]
• PQ upgrade path (icnctl id upgrade-pq) not exercised in tests

4. Network Plane

What Exists

What Tests Prove

Missing/Risky

• No Hello handshake timeout — peer can delay indefinitely before identity proof
• Broadcast dedup only at gossip layer (no network-level nonce guard)
• Blob registry no refresh protocol — announced blob from failed peer still returned to callers
• E2E encryption fail-closed (init_send_callback.rs:197-206) — messages dropped if peer can't decrypt
• Misbehavior detector created but not wired (actor/mod.rs:1122-1129)

5. Gossip Plane

What Exists

What Tests Prove

Missing/Risky

• Storage quota manager created but never called (gossip.rs:131)
• Blob transfer no expiry reaper (expires_at set but not enforced)
• Partition healing no retry logic (PartitionHeal messages may be lost)
• Pull request no priority (critical topics starved under load)
• Bloom filter auto-resize not triggered (scalability.rs exists but not wired)
• Key rotation grace period incomplete (cache created but not used in publish handler)

6. Ledger/Economics Plane

What Exists

What Tests Prove

Missing/Risky

• Treasury nonce NOT in execution path — defined but not called from treasury executor
• Ledger service integration stubbed — tests use mock/placeholder
• No ledger-level dedup — no (decision_hash → entry_hash) mapping
• Recurring payment scheduler not wired — execute_due_payments() exists, never called from daemon loop
• Budget enforcement in Gateway only — BudgetStore in-memory, not in ledger consensus
• No GL account types — DID→currency→balance only (no financial statement classification)
• Cross-coop settlement unproven — netting engine designed, never exercised
• Dispute workflow missing — types exist, no submission API

7. Compute Plane

What Exists

What Tests Prove

Missing/Risky

• CCL interpreter bridge to icn_ccl::Interpreter not visible in read code paths [SPECULATION]
• WASM executor feature-gated (#[cfg(feature = "wasm")]) — default builds may not support WASM
• Multi-executor consensus algorithm incomplete (how to break ties if 2/3 disagree)
• Actor migration rollback strategy unclear (Phase 16D migration_manager)
• Federated executor attestation verification not read

8. Gateway/UI Surface

What Exists

What Tests Prove

20 integration test files in icn-gateway/tests/:

• compute_events_integration.rs — events flow compute→WebSocket
• websocket_integration.rs — WebSocket connection
• governance_flows_integration.rs — governance proposal workflow
• budget_integration.rs — member budget enforcement
• escrow_integration.rs — escrow hold/release
• recurring_payments_integration.rs — subscription payments
• entity_integration.rs — entity lifecycle
• treasury_custody_test.rs — treasury multi-sig
• pilot_features_integration.rs — pilot-specific features
• Plus 10+ more (SDIS, service discovery, commons, steward, dissolution, constitutional, metrics, i18n, services, queries)

Missing/Risky

• No unified service layer — icn-api exists with partial ComputeService only. Gateway routes bypass it entirely.
• Two code paths — RPC uses icn_api::SubmitTaskParams; Gateway uses managers directly → divergent behavior
• Error inconsistency — Gateway uses GatewayError + i18n; RPC uses RpcErrorCode (JSON-RPC). Not bridged.
• WebSocket event filtering — EventBroadcaster broadcasts to channels but no visible coop_id scope filtering
• Coop isolation audit needed — managers likely scoped to coop_id but enforcement not visible in route handlers
• OpenAPI schema vs reality — 80+ schemas registered but endpoint-path mapping not verified complete

9. Privacy/Crypto Plane

What Exists

What Tests Prove

Missing/Risky

• Onion routing not end-to-end tested (types exist, no circuit creation test)
• ZKP proofs simulated only (simulated: true → no cryptographic security)
• ZKP circuits marked #[allow(dead_code)] — STARK proving/verification likely stubbed
• PQ key distribution not implemented — hybrid verification deferred in SignedEnvelope
• Cover traffic disabled by default (bandwidth intensive)

10. Idempotency Layer Map

Layer 1: Decision Hash (canonical, deterministic)
├── Source: icn-governance/src/proof.rs:330-345
├── Key: blake3(domain_tag || proposal_id || domain_id || outcome || vote_tally || vote_hash)
└── Property: Same decision → same hash across all nodes

Layer 2: ExecutionStore (sled, persistent)
├── Source: icn-core/src/supervisor/decision_executor.rs:225
├── Check: If decision_hash already terminal → skip
├── Record: Pending → Executing → Confirmed | Failed | PermanentlyFailed
└── Test: test_callback_idempotent_no_double_execute

Layer 3: Domain Stores (per-effect-type)
├── BudgetRecord: stores decision_hash per spend (begin_spend/confirm_spend)
│   └── Source: icn-kernel-api/src/budget.rs
├── EscrowRecord: stores release_decision_hash (one decision per escrow)
│   └── Source: icn-kernel-api/src/escrow.rs
│   └── Test: test_conflicting_decisions_rejected
└── Property: Domain-specific dedup before ledger mutation

Layer 4: Treasury Nonce (DEFINED BUT NOT WIRED)
├── Source: icn-coop/src/store.rs:112-206
├── Mechanism: Atomic sled CAS — check_and_increment_treasury_nonce()
├── NOT called from: governance_executor.rs::execute_treasury_operation()
└── Issue: #1204 (created for this gap)

Layer 5: Ledger Deduplication (DOES NOT EXIST)
├── No (decision_hash → entry_hash) mapping in ledger
├── No append_entry() idempotency check
└── Risk: Crash between ledger write and executor store write → double-apply

11. Critical Gap Summary

Tier 1: Blocking for Pilot

Tier 2: Hardening for Pilot v1+1

Tier 3: Post-Pilot Robustness