A worked example

One decision, followed all the way through.

Most explanations of institutional software stop at the diagram. This one follows a single piece of work inside a fictional cooperative — from who is recognized as a member, through the rule that let them act, to the record that can still answer why was this allowed? a year later.

Nothing here needs an account, a download, or a command line. Read it top to bottom in about four minutes.

The situation

Two fictional institutions and one piece of work. Everything that follows happens inside the first of them.

Cooperative

Brightworks Collective

A fictional forty-person worker cooperative that does metal finishing.

Federation

Northeast Worker Federation

A fictional federation Brightworks belongs to, which does not own or govern it.

The work

A failing extraction fan

The fan that clears fumes from the finishing room is failing. Replacing it costs real money and affects everyone who works that room.

01

Someone is recognized by their cooperative

Before anyone can act, the cooperative has to be able to say who counts as a member here — and be able to show why.

In ICN's vocabulary this step is about your recognized status (standing) .

A shop steward at Brightworks Collective is recognized in the workplace-safety area of the cooperative. That recognition is not a setting an administrator toggled. It exists because the members adopted a rule that says who holds this role, and because a decision under that rule assigned it.

The cooperative can check this for itself at any time. It does not have to ask a software vendor whether the person is really a member.

Show the underlying record — StandingResponse

Shape defined in icn/apps/governance/src/http/models.rs. The values below are fictional.

Field Value
did did:icn:example-brightworks-steward-not-live A fictional identifier. Real identifiers are self-held keypairs, not accounts issued by a platform.
domains[0].domain_id demo.coop.brightworks/workplace-safety
domains[0].membership_source static_list How the membership was established. The other value the model allows is trust_threshold.
domains[0].status member
roles[0].role shop_steward
roles[0].authority_scope ["safety.action_item.complete", "safety.proposal.submit"] What this role may do. Authority is a list of specific things, never a general permission level.
generated_at 1755043200 Standing is a snapshot taken when asked, not a cached status.

Standing attaches to a role in a scope, not to a person. The same human can hold different standing in a different cooperative, and neither cooperative learns about the other.

Next: Something comes up that needs a decision
02

Something comes up that needs a decision

A piece of work appears that somebody has to decide on — with a deadline, and with a note about how consequential it is.

In ICN's vocabulary this step is about how group decisions are made (governance) .

The extraction fan in the finishing room is failing. Replacing it is not a small purchase and it affects everyone who works that room, so it is not something one person quietly handles.

It arrives as a specific item of work with a stated deadline, not as a message in a thread that somebody may or may not read.

Show the underlying record — ActionCard

Shape defined in icn/apps/governance/src/http/models.rs. The values below are fictional.

Field Value
id demo-card-0417
source_kind proposal
action_kind review_and_decide
scope entity One of entity | structure | individual — which level of the institution is acting.
title Replace the failing extraction fan in the finishing room
risk_level elevated One of low | normal | elevated. Surfaced to the member before they act, not after.
deadline 1755302400
receipt_expected true
Next: The rules say who may decide it, and why
03

The rules say who may decide it, and why

Instead of a permission an administrator granted, there is a rule the members adopted — and the system can point at it.

In ICN's vocabulary this step is about what you are allowed to do (authority) .

The steward may act on this because the cooperative adopted a rule placing workplace-safety decisions with the safety stewards, and because a decision under that rule assigned them the role. Both of those are records, and both can be read back.

This is the part most software gets structurally wrong. Elsewhere, "who is allowed to do this" is an access-control setting held by whoever administers the tool. Here it is a consequence of decisions the members actually made.

Show the underlying record — ActionCard.authority_basis

Shape defined in icn/apps/governance/src/http/models.rs. The values below are fictional.

Field Value
authority_basis role_assignment_in_domain The member-facing basis is a named string. Other values in use include assigned_action_item, meeting_attendee, domain_membership, governing_body_agenda.
required_authority_scope ["safety.action_item.complete"] Compared against the standing record from step 01. If it does not match, the action is not offered.
domain_id demo.coop.brightworks/workplace-safety

Authority narrows as it travels. A role in one scope does not carry into another, and a federation cannot grant a role inside a cooperative that belongs to it.

Next: Before anything happens, you can see what would happen
04

Before anything happens, you can see what would happen

The system shows what record would be created, whether it can be undone, and what proof it would leave — before anyone confirms.

In ICN's vocabulary this step is about what actually happens (execution) .

Reading this screen changes nothing. That is the point: an institution should be able to look at a consequential action in full detail without the act of looking being the act of doing.

The three things shown before any confirmation are always the same three: what authorizes this, whether it can be reversed, and what record it will leave behind.

Show the underlying record — pending-publish-summary → mutation_preview

Shape defined in docs/contracts/pending-publish-summary.schema.json. The values below are fictional.

Field Value
mutation_preview.would_create action_item_record
mutation_preview.summary Would record completion of the extraction fan replacement in Workplace Safety (demo). No record is created by rendering this row. That closing sentence is part of the contract, not decoration — the preview must state its own inertness.
receipt_expected.category action_item_completion_receipt
review_actions ["approve", "reject", "edit", "request_info", "defer"] Deferring and asking for more information are first-class outcomes, not failures to decide.

This walkthrough is read-only. There is no confirm step here, and no record is created anywhere by visiting this page.

Next: What happened leaves a record that can be checked
05

What happened leaves a record that can be checked

Once the work is done, there is a durable record of what happened, who recorded it, and when — one that can be verified later without trusting whoever is telling you about it.

In ICN's vocabulary this step is about history and proof (provenance) .

The fan gets replaced and the completion is recorded. The record is not a line in an activity feed that an administrator can quietly edit; it is content-addressed, so any later change to it produces a different hash and stops matching.

A receipt says an act occurred. It does not make the act legitimate — the authority for that came from step 03, before anything happened.

Show the underlying record — ActionItemCompletionReceipt

Shape defined in icn/crates/icn-governance/src/proof.rs. The values below are fictional.

Field Value
item_id demo-item-0417
domain_id demo.coop.brightworks/workplace-safety
actor_did did:icn:example-brightworks-steward-not-live
transition assigned → completed
completed_at 1755216000
record_hash 9f2a7c41d8e0b3… Shown hex-encoded and truncated for reading. On the wire this is a 32-byte array.

The field is named recorded_by / actor_did rather than approver, deliberately. Recording an act is not the same as having had the authority to perform it, and the data model refuses to conflate them.

Next: The record joins the institution’s memory
06

The record joins the institution’s memory

Each record points back at the one that led to it, so a year later the cooperative can reconstruct not just what it did but why it was allowed to.

In ICN's vocabulary this step is about how resources and obligations are tracked (accounting) .

Every record in the chain carries the previous record’s hash. Follow them backwards and you arrive at the decision that authorized the work, and then at the rule that made the decision binding.

This is what an institution loses when its history lives across a chat archive, a spreadsheet, and a shared drive: not the individual facts, but the links between them. Reconstructing "why were we allowed to do this" becomes an archaeology project instead of a query.

Show the underlying record — ADR-0026 process receipt chain

Shape defined in icn/crates/icn-governance/src/proof.rs. The values below are fictional.

Field Value
DecisionRecordedReceipt.record_hash 4b81e0… The decision that authorized the work.
ActivationCrossedReceipt.decision_record_hash 4b81e0… Points back at the decision — same hash, now carried forward.
MutationPlanRecordedReceipt.activation_record_hash c70d95…
MutationAppliedReceipt.plan_record_hash a1f3b8…
EvidencePacketProducedReceipt.mutation_applied_record_hash 2e6470…

Not every step of this chain is implemented to the same depth today. The maturity page states which parts carry real evidence and which do not.

Each record carries the previous record's hash
  1. 01 Decision recorded the start of the chain
  2. 02 Activation crossed carries the decision’s hash
  3. 03 Change planned carries the activation’s hash
  4. 04 Change applied carries the plan’s hash
  5. 05 Evidence packet produced carries the applied change’s hash

Read upward and each record points at the one that authorized it. That backward path is what lets a cooperative answer “why were we allowed to do this?” without relying on anyone's memory.

What this walkthrough does and does not show

A demonstration that does not draw its own boundaries is a sales pitch. Here are ours.

What is real in the implementation

  • The record shapes, field names, and the hash-chaining between receipts are the ones the implementation uses.
  • The distinction between authority (why an act was permitted) and a receipt (that it occurred) is enforced in the data model, not just in this description.
  • Standing, action cards, previews, and completion receipts all exist as implemented surfaces in the repository.

What is invented for this page

  • Brightworks Collective, the workplace-safety domain, the extraction fan, and every identifier and hash on this page are invented for this walkthrough.
  • No live institution, partner, or deployment is involved, and no data is fetched when you load this page.
  • The values are literals in the site source, so the page renders identically every time.

What is still ahead

  • This guided sequence is not itself a shipped product surface — it is an explanation assembled from the record shapes.
  • The member-facing interface that would present this to an actual member is the part of the system furthest behind the rest of it.
  • Some steps of the receipt chain are implemented more deeply than others; the maturity page is where that is stated per subsystem.
Where to check this yourself

Every record shape named above is defined in the repository, and the file is cited on each step. The per-subsystem maturity account — which parts carry test evidence, which are demonstrated against fixtures, and which are still asserted — is on What's real now.