Nodes & Collections — v10
A Kristal node is an operational endpoint with a stable node_id, described by kristal_node_manifest. It can expose one or more states and related services. A hosting repository is an operational boundary, not automatically a single Kristal.
Node roles
collection: one or many related independent Kristal states.directory: advertises nodes and their host locations.publisher: publishes immutable state representations.gateway: exposes read/query access without necessarily owning the state.
A node may have several roles. A collection boundary reflects ownership, confidentiality, lifecycle or scale, and does not merge semantic authority.
Reference GitHub layout
account or organization
├── private root directory (recommended for mixed visibility)
├── public collection repository
│ └── kristals/<slug>/
└── private collection repository
└── kristals/<slug>/
Use a new collection repository when permissions, governance, retention or publication lifecycle actually diverge. Many small Kristals can coexist in one repository with independent State Snapshots.
See GitHub-Reference-Profile-v10, GitHub-Read-Surfaces-v10 and Directories-and-Federation-v10.
Normative source: Framework spec/v10/Nodes-and-Collections.md.