ADR 0020: Institutional Bootstrap Activation and Standing Read Model

Status

Accepted (2026-04-26). Records the reusable activation path that an institution package follows from manifest-on-disk to a member-facing standing surface on a running ICN node. Separates ICN's runtime contract (the activation pipeline, the standing read model) from the institution package layer (local vocabulary, fixtures, real-DID overlays).

Context

ICN now ships a working institutional-operability runtime: a package can be applied to a node, a charter can be activated against that node, real DIDs can be bound to package-side person ids, role assignments carry typed authority scope, and the member-facing /me/standing read model surfaces what a holder is allowed to do today. NYCN dogfoods this end-to-end (see InterCooperative-Network/nycn — institution package, person-directory overlays, /me/standing smoke verifier).

The pieces are in code; what is not yet recorded as a decision is the contract between the institution package layer and the ICN runtime. NYCN's package shape, fixture content, and verifier tools have been growing without a written rule for "what does ICN promise to consume, and what stays on the package side?" That ambiguity is the same drift hazard ADR-0011 (canonical truth ownership) and the institution-package boundary doc were filed against. Without an ADR locking the activation path, package authors will start expecting whatever the gateway happened to do this week.

Two pressures forced the decision now:

1. NYCN as reference institution package is shipping fixtures (signals, indicators, action-card templates, temporary authority, support institutions — see NYCN PR #7) ahead of the corresponding ICN runtime primitives (icn#1631, #1632, #1633, #1634, #1635). The package marks those icn_target_status: planned; that discipline is correct, but it depends on a stable ICN-side activation contract for the things that are implemented today. This ADR provides the stable spine.

2. Action cards (icn#1608) are about to ship and will be the next member-facing surface plugged into this same path. Recording the activation chain now means action cards plug into a written contract instead of an inferred one.

Decision

Institution package activation follows a single reusable path. Each step has a written contract surface; ICN owns each surface; institution packages bind their local vocabulary to it.

Activation chain

[1] package manifest (institution/package.yaml + bootstrap fixtures)
        ↓
[2] private operator overlay (real DIDs, contact bindings — never in public repo)
        ↓
[3] bootstrap apply (icnctl institution bootstrap apply)
        ↓
[4] live charter activation endpoint (POST /v1/charters/...)
        ↓
[5] entity / structure / role creation (governance domains persisted across restart)
        ↓
[6] /me/standing read model (member-facing standing surface)
        ↓
[7] action cards (FUTURE — icn#1608)

Contract surfaces (ICN owns; packages bind to)

Boundary rules

• ICN owns runtime and standing contract. The activation pipeline shape, the persistence guarantees, and the /me/standing schema are runtime contracts. Institution packages may not redefine them.
• Institution packages own local vocabulary and fixtures. Per-coop role names, per-program structures, package-specific operating_purpose strings, indicator definitions, signal rules, support-institution patterns. None of these are ICN core primitives. They live in the package; they do not infect ICN core.
• Private overlays bind real DIDs and sensitive data outside the public repo. Real names, emails, phone numbers, demographic data, payment identifiers, and pre-commit sponsor pipelines never enter the public package repo. The activation path resolves them at apply time from operator-controlled overlay files.
• Action cards are future surface. No package may claim icn_target_status: supported for action cards until icn#1608 ships and a stable schema is published.
• NYCN-specific nouns stay on the NYCN side. ICN core does not learn what a "Summit," a "sponsor tier," a "education-onboarding cohort," or a "community contract amendment" is. The package layer translates those into ICN's four entity primitives + structure + activity + role records.

What /me/standing promises today (the read-model contract)

The /me/standing response is the canonical answer to "what am I currently authorized to do, in which entities, under what scope?" for the calling DID. Its current shape:

• The caller's DID and the entities they are a member of (with operating_purpose metadata).
• For each membership, the role assignments held, with their authority_scope strings.
• For each role assignment, the structure (committee / working_group) the role is held in.

The schema is the runtime contract. NYCN's smoke verifier (tools/verify-standing.py) reads its expectations from institution/standing-smoke-test.example.yaml and asserts a superset match against the live response. The contract is match_mode: superset — ICN may add fields to the response without breaking package-side verifiers; ICN may not remove or rename fields without superseding this ADR.

What does NOT cross the contract

• Domain semantics. ICN does not know what "education-onboarding completion" means. It knows Activity { kind: Program, parent_entity_id: X } and RoleAssignment { authority_scope: [...] }. The operating_purpose and authority-scope strings are opaque to ICN.
• Real personal data. Names, emails, contact channels, accommodation needs are never in the public package or in the activation request body. They live in the operator overlay.
• Federation-side recognition. A package activated on coop A is not automatically visible to coop B. Cross-cooperative recognition is governed by federation primitives (ADR-0012, ADR-0013) and is independent of this ADR.

Implementation status

Consequences

• The activation path has a written contract that NYCN (and any future institution package) can pin to. Drift between "what NYCN expects" and "what ICN does" becomes detectable at the contract surface, not by reading code.
• The boundary between ICN core (runtime) and institution packages (local vocabulary) is locked. ICN does not accumulate NYCN-specific nouns; NYCN does not redefine ICN runtime contracts.
• Action cards (icn#1608) have a written place to plug in without inventing a new activation chain.
• The "private overlay" pattern is acknowledged as a first-class architectural concern: real-DID and sensitive-data binding happens outside the public package repo by design. Future operator-tooling work has a reference model.
• Future federation-side recognition work (ADR-0012/0013 territory) is explicitly out of scope here, which prevents this ADR from over-reaching into territory those ADRs already own.

Non-decisions (out of scope)

• Action card schema, semantics, lifecycle, or rendering. Those decisions go in a separate ADR after icn#1608 lands.
• Federation-side mandate or membership recognition. ADR-0012 and ADR-0013 own that.
• The CCL charter-document grammar. Charters are inputs to step 4; their internal shape is governed elsewhere.
• Authority enforcement (kernel dispatch gating on mandates). ADR-0019 records the minting seam; enforcement gating is its own future ADR.
• Signals, indicators, temporary-authority, obligation/allocation/settlement primitives. Each is open as a separate ICN issue (#1631 / #1632 / #1633 / #1634) and will graduate via its own ADR when accepted.

Alternatives Considered