Runtime Surface Map

For current project truth, defer to `docs/STATE.md` and `docs/PHASE_PROGRESS.md`. This map is a routing guide for the surfaces a member or app actually touches today.

This document points at the gateway endpoints, primitives, and proof artifacts that exist as real runtime surfaces in the current main. It is not exhaustive — a full API reference lives in `docs/reference/api/API_REFERENCE.md` — and it does not over-document implementation details. It is a fast routing layer.

For a mechanical inventory of every gateway route declaration (Actix attribute macros) versus OpenAPI coverage, see the generated `generated/route-inventory.md` (regenerate/check with docs/scripts/route_inventory.py; issue #2112). It proves declarations exist in source — not correctness, auth, tests, or production readiness.

The gateway

The icn-gateway crate exposes the REST + WebSocket surface used by member-facing apps and SDKs.

• Crate: icn/crates/icn-gateway/
• HTTP module: icn/apps/governance/src/http/ (governance app handlers), plus equivalent paths in other apps.
• Default port: 8080 (see icn-core/src/config/gateway.rs). Never 8000.
• API contract: OpenAPI generated by icnctl api export-openapi; TypeScript types regenerated via cd sdk/typescript && npm run generate-types.

Member-facing read models

These are the canonical answers to "who am I, what can I do, what needs my attention?". The surfaces below exist; some have richer specs in docs/architecture/.

Discovery commands:

grep -RIn "me/action-cards\|me/standing\|completion-receipt" icn/apps icn/crates docs | head -100
grep -RIn "route\|service\|configure" icn/apps/governance/src/http icn/crates/icn-gateway/src | head -100

Action-card source paths and proof loops

The action-card runtime emits closed source/action pairs. Currently emitted source paths are proof-bearing — completing the action produces an append-only receipt that can be retrieved over HTTP.

Receipt and provenance retrieval

Governance primitives (data surface)

The governance domain is the deepest implemented today. Primitives live in icn-governance (kernel-side type model) and apps/governance (runtime, HTTP, persistence).

Identity, trust, ledger surfaces

Generated SDK surfaces

When the gateway API changes, both must be regenerated and committed. The CI "Check API Types Drift" job catches drift; the canonical regen recipe lives in `CLAUDE.md` under "CI Failure Index → Drift fix recipe".

Vocabulary

ICN's runtime surfaces use:

• identity, position, obligation, allocation, settlement, unit — preferred.
• payment, currency, wallet, balance — avoided. A unit is not a currency. A position is not a balance. A settlement is not a payment. The Regulatory Compliance Linter enforces this.

Reviewing public/API claims against generated evidence

Before a public, demo, or docs surface claims anything about ICN's API/route surface, check it against the mechanical evidence, not prose. This supports the public-surface truth-sync work in #1779 and the route/API inventory lane #2112.

• `generated/route-inventory.md` — gateway route-macro declarations, unparsed gateway candidates, governance-app route-registration candidates, and OpenAPI matched/unmatched (regenerate/check with docs/scripts/route_inventory.py).
• `generated/icnctl-command-inventory.md` — icnctl CLI command declarations from the clap tree, grouped by a curated role heuristic, uniform unknown / needs local verification status and L1 proof (regenerate/check with docs/scripts/icnctl_command_inventory.py; issue #2113). Declarations exist in source — not correctness, auth, live wiring, or organizer/production readiness.
• `docs/api/openapi.generated.yaml` — the documented contract.

What this evidence proves / does not prove: it proves route declarations / registration sites exist in source at a snapshot commit. It does not prove correctness, authn/authz, mounting, test coverage, runtime health, or production readiness. OpenAPI presence does not prove a route is served; a route being served does not prove it is public-safe.

Shape of the surface (see the inventory for live counts): the gateway has hundreds of route-macro declarations, plus a separate governance-app registration surface (served under the gateway's /v1/gov scope, not gateway macros), while the generated OpenAPI documents only a handful of paths. So "the API" is far larger than OpenAPI describes — most of it is undocumented, not absent.

Safe vs unsafe public/API claim patterns — use the existing status vocabulary from `source-of-truth-map.md`, bound by proof level in `proof-level-taxonomy-capability-matrix.md`, and demo limits in `show-readiness-map.md`:

Rule: keep public claims at or below what the generated evidence plus current canonical state (`docs/STATE.md`, `docs/PHASE_PROGRESS.md`) support. When unsure, say unknown / needs local verification rather than implying coverage.

Where to read deeper