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.

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/.

Surface	Method + path	What it does	Canonical doc
Member standing	`GET /v1/gov/me/standing`	Caller identity, memberships, roles, capabilities, currently selected scope, plain-language hooks.	`docs/architecture/MEMBER_STANDING.md`
Action cards	`GET /v1/gov/me/action-cards`	Closed source/action enums; the things waiting on the caller, with proof linkage to the receipt that closes the loop.	`STATE.md` (action-card runtime section)

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.

Source path	Receipt type	Status
`proposal` / `vote`	`GovernanceDecisionReceipt`	✅ proof loop verified end-to-end
`action_item` / `complete`	`ActionItemCompletionReceipt`	✅ proof loop verified end-to-end
`meeting` / `attend`	`MeetingAttendanceReceipt`	✅ proof loop verified end-to-end (`Present` and `Remote` are receipt-bearing; `Absent` is not)
`signal_rule`	(RFC-gated)	⏳ pending #1631, tracked under #1646
`obligation_lifecycle`	(RFC-gated)	⏳ pending #1634, tracked under #1646

Receipt and provenance retrieval

Surface	Method + path	Notes
Action-item completion-receipt retrieval	`GET /v1/gov/domains/{domain_id}/action-items/{item_id}/completion-receipt`	Closes the proof loop on the read side. `governance:read` scope + domain membership; receipt's bound `domain_id` is asserted to match the path parameter so cross-domain probes are rejected.
Local HTTP proof loop runbook	(local script)	Closure recorded under PR #1676; proof-path runbook lives in the partner NYCN repo.
K3s smoke proof loop runbook	(operator-authorized)	Closure recorded under PR #1677 against deployed image `91a63eec`; proof-path runbook lives in the partner NYCN repo.

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).

Primitive	Notes
Governance domains	Persisted across gateway restart in standalone mode. Bootstrap creates them via a generic institution bootstrap package path.
Structures	Non-sovereign, parent-entity-owned bodies (committees, working groups, etc.).
Activities	Time-bounded, parent-entity-owned (events, summits, initiatives).
Programs / milestones	Wraps recurring Activity cycles; tranche framing.
Meetings	Schedule, agenda, attendance, minutes. Dual-key sled scheme prevents domain-id leak.
Action items	Decision-to-action bridge from accepted proposals; status update via `PUT`.
Proposals + votes	Consent-based decision mode plus thresholded modes.
Charter activation	Live charter activation endpoint; person-directory overlay binds DIDs to package-side person ids.
Notification digest	Pending votes, overdue items, upcoming meetings.

Identity, trust, ledger surfaces

Subsystem	Role	Canonical doc
Identity	DIDs (`did:icn:<base58-pubkey>`), Ed25519 keypairs, Age-encrypted keystore, DID-TLS binding.	`icn/crates/icn-identity/`, `docs/architecture/IDENTITY_MEMBERSHIP_ARCHITECTURE.md`
Trust graph	`TrustPolicyOracle` translates trust scores into `ConstraintSet` (the meaning firewall in action).	`docs/architecture/KERNEL_APP_SEPARATION.md`
Ledger	Double-entry mutual credit / state-change journal (Merkle-DAG).	`icn/crates/icn-ledger/`, `docs/design/economics/ECONOMIC_ARCHITECTURE.md`
Settlement	Settlement engine in `apps/ledger`. Vocabulary note: ICN uses "settlement," not "payment."	`docs/design/economics/`
Compute	Trust-gated distributed task execution.	`icn/crates/icn-compute/`, `docs/design/compute-substrate-design.md`

Generated SDK surfaces

Surface	Where	Generated from
OpenAPI spec	`docs/api/openapi.generated.yaml`	`icnctl api export-openapi` (run from `icn/`)
TypeScript types	`sdk/typescript/src/generated/api-types.ts`	`cd sdk/typescript && npm run generate-types`

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.

Where to read deeper

Topic	Doc
API reference	`docs/reference/api/API_REFERENCE.md`
Member standing contract	`docs/architecture/MEMBER_STANDING.md`
Charter system	`docs/PHASE_PROGRESS.md` §"Phase 1: The Charter Engine"
Kernel/app separation	`docs/architecture/KERNEL_APP_SEPARATION.md`
Phase model and gates	`docs/PHASE_PROGRESS.md`