NYCN × ICN Implementation Matrix

Status: Execution ledger, grounded against main at 37ec91e0 (2026-04-14) Companions: NYCN-Repo-Architecture-Spec.md (architectural map), NYCN-Execution-Tranches.md (merge-order plan) Working instruction: Treat the architecture spec as the map and this matrix as the execution ledger. Before writing code, reconcile any disagreement between them and current repo state — reality wins.

⚠️ Authoritative routing correction (2026-04-17)

This document predates docs/architecture/INSTITUTION_PACKAGE_BOUNDARY.md. On any routing conflict between this matrix and the boundary doc, the boundary doc wins.

Several rows below route institution-specific nouns (sponsor, budget-item, session, registration, venue accessibility, source-ref, institutional-document, speaker/attendee/sponsor-contact participation variants, institution-specific ProgramKind / MilestoneType names like AnnualSummit / VenueLocked / BudgetLocked / PublicLaunchReady) into icn-governance::*. That is drift. ICN core — icn-governance and apps/governance — must stay institution-agnostic. In this monorepo, those institution-owned artifacts now belong under institutions/nycn/ until they are split into their own repo.

Corrected routing (authoritative):

Originally routed to	Re-routed to
icn-governance::sponsor	Institution package (future apps/nycn/ or external nycn-icn)
icn-governance::budget_item	Institution package (or icn-ledger integration if generic treasury)
icn-governance::session	Institution package
icn-governance::registration	Institution package
icn-governance::accessibility	Institution package
icn-governance::source_ref	Institution package (deferred)
icn-governance::document	Institution package or a generic content-addressed crate; not a governance-core concept
icn-governance::participation with sponsor-contact / speaker / attendee / volunteer variants	Institution package; ICN core only knows authority-bearing membership/roles
Program { kind: AnnualSummit } and MilestoneType::{VenueLocked, BudgetLocked, PublicLaunchReady, EventReady, ClosureComplete}	ICN core uses ProgramKind::Custom("annual_summit") and free-form completion_criteria: Vec<String> — see icn-governance/src/program.rs. Named summit-shaped variants live in the institution package (or in CCL contract bodies) only.

Touchpoint shorthand (D = domain module in icn-governance::<name>, etc.) should be read as "institution-package equivalent" for any corrected row. The rows themselves are left intact below as historical context for the drift.

Rule going forward: before adding anything to icn-governance or apps/governance, ask: "Could a different institution (a worker co-op federation, a credit union, a housing co-op) use this without renaming?" If no, it belongs in the institution package.

Legend

Lifecycle

• ✅ exists — canonical state lives on main, tests passing
• 🚧 partial — work exists but not on main (see Source column)
• ⚠️ adjacent — something close exists but does not fully cover the need
• ❌ missing — no code, no branch

Source (mechanical state)

• main — merged into main, covered by CI on main
• open_pr — on an open pull request targeting main
• branch_only — local/remote branch with no PR yet opened
• spec_only — described in docs, no code
• external — lives in a non-governance crate (e.g., icn-entity, icn-ledger)

Touch points (expected implementation surfaces per row)

• D domain module in icn-governance::<name>
• S sled store in apps/governance/src/manager.rs
• M GovernanceManager wiring
• Hm HTTP models in apps/governance/src/http/models.rs
• Hh HTTP handlers/routes in apps/governance/src/http/{handlers,configure}.rs
• E gateway event variant(s) in icn-gateway::events
• T unit + scenario tests
• SDK regenerate sdk/typescript/src/generated/api-types.ts

1. Canonical objects

2. Bounded domains → module map

3. Authority & scope gaps

4. Storage indexes

Needed (new keys follow the existing <thing>_by_<scope>:... convention, not a fabricated _idx: prefix):

Migration-safe index rule: every new index gets a _meta:idx_version:<name> marker. On store init, if absent or below current version, walk rows and populate. Test coverage must include both "empty store" and "pre-populated store".

5. Gateway events

Current GatewayEvent governance-related variants on main (verified in icn/crates/icn-gateway/src/events.rs):

Proposed additions — none of these exist on main yet:

Naming convention: follow the existing Governance<Thing><Verb> pattern on GatewayEvent. Do not invent a parallel naming scheme.

6. HTTP API surface

All governance routes are mounted under the /gov scope (see icn/crates/icn-gateway/src/server.rs:2008).

6.1 On main (verified in apps/governance/src/http/configure.rs)

• Domains: POST/GET /gov/domains, GET /gov/domains/{domain_id}, POST/DELETE /gov/domains/{domain_id}/members
• Proposals: POST/GET /gov/proposals, GET /gov/proposals/{id}, POST /gov/proposals/{id}/{open,close,vote}, GET /gov/proposals/{id}/{tally,proof,chain,discussion}, discussion comment CRUD
• Delegations (vote-level): POST/GET /gov/delegations, DELETE /gov/delegations/{id} (revoke — no GET-by-id handler exists on main)
• Action items (domain-scoped): POST/GET /gov/domains/{domain_id}/action-items, GET /gov/domains/{domain_id}/action-items/{item_id}, PUT .../status, POST .../notes
• Structures (entity-scoped): POST/GET /gov/entities/{entity_id}/structures, GET /gov/structures/{structure_id}, POST /gov/structures/{structure_id}/roles
• Activities (entity-scoped): POST/GET /gov/entities/{entity_id}/activities, GET /gov/activities/{activity_id}
• Federation / SDIS proposal shortcuts: /gov/proposals/federation/..., /gov/proposals/sdis/...

6.2 On PR #1543

• POST /gov/meetings, GET, GET /{id}, PATCH /{id}
• POST /gov/meetings/{id}/agenda-items, PATCH .../{aid}
• POST /gov/meetings/{id}/start, POST .../end
• Attendance endpoint (verify exact shape against impl)

6.3 On feat/notification-digests

• GET /gov/digest?did=...

6.4 Proposed per tranche

• Tranche 1 (Program): POST/GET /gov/entities/{entity_id}/programs, GET /gov/programs/{program_id}, POST /gov/programs/{id}/milestones, PATCH .../{mid}, POST /gov/programs/{id}/close, GET /gov/programs/{id}/dashboard; GET /gov/me/scopes, GET /gov/me/work; scope-partitioned GET /gov/digest?scope=...
• Tranche 2 (Funding): /gov/sponsors CRUD, /gov/programs/{id}/sponsors, /gov/budget-items CRUD, /gov/programs/{id}/budget
• Tranche 3 (Content/Attendees): /gov/sessions CRUD, /gov/programs/{id}/sessions, /gov/registrations CRUD, /gov/programs/{id}/registrations, /gov/programs/{id}/accessibility-status, /gov/programs/{id}/representation
• Tranche 4 (Migration): provenance reads /gov/history/{ref}, /gov/provenance/{ref} (if not deferred to Tranche 5)
• Tranche 5 (Documents): /gov/documents CRUD, version history, search
• Tranche 6 (IAM/Onboarding): /gov/role-delegations CRUD, /gov/onboarding CRUD

6.5 SDK drift

Every added model in apps/governance/src/http/models.rs → regenerate sdk/typescript/src/generated/api-types.ts → commit as chore(sdk): regenerate TypeScript API types (no mixed commits).

7. Derived views

8. External integration status

Rule: no external-source data enters ICN canonical state without a SourceRef attached.

9. ny-coop-net → ICN import crosswalk

Concrete per-domain migration mapping the importer must implement (Tranche 4). Every row carries SourceRef { source_system: NyCoopNetRow, external_identifier: "<table>:<pk>", provenance_type: Imported }.

Idempotence rule: every importer write is keyed on (source_system, external_identifier). Re-running the importer must not create duplicates. The importer writes via the gateway HTTP API (not directly to sled) so validation is exercised identically to normal create flows.

10. Bootstrap & seed data (missing operational artifact)

Bootstrapping NYCN on a running ICN node requires seed data. This is not currently scripted. It is part of making the institution reproducible and belongs in Tranche 1 / Tranche 4 scope.

Deliverable: docs/strategy/NYCN-Bootstrap-Runbook.md + a reproducible seed script (shell or Rust binary under bins/). Create alongside Tranche 1 merge.

11. Docs-update triggers

12. Open questions — phase-gated

Each must be resolved before the named phase begins. Do not let these float.

13. Tests required per tranche

14. Agent assignments

Every tranche gets one pass by icn-invariants-guardian before merge.