Brightworks Collective
A fictional forty-person worker cooperative that does metal finishing.
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.
Two fictional institutions and one piece of work. Everything that follows happens inside the first of them.
A fictional forty-person worker cooperative that does metal finishing.
A fictional federation Brightworks belongs to, which does not own or govern it.
The fan that clears fumes from the finishing room is failing. Replacing it costs real money and affects everyone who works that room.
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.
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.
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.
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 |
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.
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.
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.
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.
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.
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.
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.
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.
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.
A demonstration that does not draw its own boundaries is a sales pitch. Here are ours.
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.