Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0009-grc-groups FR-006 , 0009-grc-groups FR-007 , 0009-grc-groups FR-008 , 0009-grc-groups FR-009 , 0009-grc-groups FR-010
The group view (0009-grc-groups ): an entity gives the group a snapshot of statuses and digests through a reader function it owns, and the group joins the snapshots into coverage and a roll-up with the functions the single-entity view already has (join, coverage, rollup). An entity that cannot be read is pending, never an assumed pass. Nothing here takes the data of two entities from one place: the group learns of an entity through its reader alone. The entities form a tree (0012-grc-subtenants ): the view gives each entity its own status and its rolled-up status, the join of its own and its subtenants', made from the snapshots alone.
pending (a question not yet answered) and gap (a control that nothing shows) are unaligned: no outside standard defines them.
import { groupView } from "./group.ts" ;
// groupView({ tree, scope, controls, readings, exceptions: [], at: "2026-06-01T00:00:00Z" }).overall.worst; // "pending" while an entity is unread Limits
It does not resolve a port, a key or a secret, and it does not say how an entity's data is stored: the host makes each entity's reader.
Source: commons/grc/src/logical/group.ts
11 of 40 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.
logical.entitySnapshotconst no test imports it const entitySnapshot: DocumentKind<Document & { readonly entity: EntityId; readonly ledgerHead: string; readonly control… (524 characters) const entitySnapshot : DocumentKind <Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}>What an entity gives the group: statuses and digests of its controls, the head of its ledger, and nothing else.
// entitySnapshot.decode(document).kind; logical.EntitySnapshottype no test imports it type EntitySnapshot = Decoded <typeof entitySnapshot.decode>;A snapshot of one entity.
logical.SnapshotInputtype no test imports it type SnapshotInput = {
readonly entity : EntityId ;
readonly frameworks : readonly Framework [];
readonly crosswalks : readonly Crosswalk [];
readonly checks : readonly Check [];
readonly results : readonly Outcome [];
readonly exceptions : readonly Exception [];
readonly ledgerHead : string ;
};What an entity's own side is given to make its snapshot: its own results and exceptions, and the group's frameworks, crosswalks and checks, defined once.
logical.snapshotOffunction no test imports it function snapshotOf(input: SnapshotInput, at: string): Promise<Result<Document & { readonly entity: EntityId; readonly l… (568 characters) function snapshotOf (input : SnapshotInput , at : string ): Promise <Result <Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}, string >>The snapshot of an entity at at, made from its own data: the newest results with the exceptions applied, and the coverage of every control.
// const made = await snapshotOf({ entity, frameworks, crosswalks, checks, results, exceptions, ledgerHead }, "2026-06-01T00:00:00Z"); logical.ReadFaulttype no test imports it type ReadFault = { readonly kind : "unreachable" | "denied" | "malformed" ; readonly message : string };Why an entity could not be read.
logical.EntityReadertype no test imports it type EntityReader = (at : string ) => Promise <Result <EntitySnapshot , ReadFault >>;The reader of one entity, made by the host for that entity alone: given the instant, nothing else, it answers with a snapshot or a fault.
logical.Readerstype no test imports it type Readers = ReadonlyMap <EntityId , EntityReader >;The readers of a group, by entity.
logical.EntityReadingtype no test imports it type EntityReading =
| { readonly kind : "read" ; readonly snapshot : EntitySnapshot }
| { readonly kind : "unread" ; readonly entity : EntityId ; readonly fault : ReadFault };What reading an entity gave.
logical.entityOffunction no test imports it function entityOf (reading : EntityReading ): EntityId The entity a reading is of.
// entityOf({ kind: "unread", entity, fault: { kind: "unreachable", message: "down" } }) === entity; logical.normalizeSnapshotfunction no test imports it function normalizeSnapshot(s: Document & { readonly entity: EntityId; readonly ledgerHead: string; readonly controls: re… (1009 characters) function normalizeSnapshot (s : Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}): Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}A snapshot rebuilt from its known fields, so that nothing else passes through.
// normalizeSnapshot(snapshot); // the same snapshot with nothing but its known fields logical.readGroupfunction no test imports it function readGroup(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<Entity… (417 characters) function readGroup (group : Document & { readonly title : string ; readonly entities : readonly ObjectOf <{ id : Decoder <EntityId >; title : Decoder <string >; ledger : Decoder <PortRef >; store : Decoder <PortRef >; keys : Decoder <readonly PortRef []>; secrets : Decoder <readonly SecretRef []>; }, { parent : Decoder <EntityId >; }>[]; } & { readonly [x : string ]: unknown ; }, readers : Readers , at : string ): Promise <readonly EntityReading []>Reads each entity of the group through its own reader, given the instant and nothing else; a reader that rejects, throws, gives another entity's snapshot or gives what is not a snapshot is a fault, and an entity with no reader is unreachable.
// const readings = await readGroup(group, new Map([[unitA, readerOfA]]), "2026-06-01T00:00:00Z"); // the others are unread logical.GroupCoveragetype no test imports it type GroupCoverage = CoverageState | "unknown" ;The coverage of a group's cell: an entity's own, or unknown for one that could not be read.
const GROUP_COVERAGE_ORDER : readonly ["covered" , "accepted" , "stale" , "partial" , "untested" , "unknown" , "failing" , "gap" ]Group coverage from the best to the worst; unknown is worse than anything an entity shows short of failing.
GROUP_COVERAGE_ORDER .indexOf ("unknown" ) > GROUP_COVERAGE_ORDER .indexOf ("partial" ); // true logical.joinCoveragefunction no test imports it function joinCoverage (a : GroupCoverage , b : GroupCoverage ): GroupCoverage The worse of two group coverages: associative, commutative and idempotent.
joinCoverage ("covered" , "unknown" ); // "unknown" logical.GroupCelltype no test imports it type GroupCell = {
readonly control : string ;
readonly entity : EntityId ;
readonly status : Status ;
readonly coverage : GroupCoverage | "not-applicable" ;
readonly severity : Severity ;
readonly reading : "read" | "unread" ;
};One control of one entity in the group view.
logical.ControlRolluptype no test imports it type ControlRollup = {
readonly control : string ;
readonly status : Status ;
readonly coverage : GroupCoverage | "not-applicable" ;
readonly applicable : number ;
};One control across the entities it applies to.
logical.EntityRolluptype no test imports it type EntityRollup = {
readonly entity: EntityId;
readonly parent?: EntityId;
readonly children: readonly EntityId[… (402 characters) type EntityRollup = {
readonly entity : EntityId ;
readonly parent ?: EntityId ;
readonly children : readonly EntityId [];
readonly depth : number ;
readonly own : Status ;
readonly rolledUp : Status ;
readonly ownCoverage : GroupCoverage | "not-applicable" ;
readonly rolledUpCoverage : GroupCoverage | "not-applicable" ;
readonly reading : "read" | "unread" ;
readonly share : number | undefined ;
};One entity of the tree in the view: its place, its own status and coverage (the join of its cells), and its rolled-up status and coverage (the join of its own and its subtenants' rolled-up).
logical.GroupViewtype no test imports it type GroupView = {
readonly at : string ;
readonly roots : readonly EntityId [];
readonly cells : readonly GroupCell [];
readonly controls : readonly ControlRollup [];
readonly entities : readonly EntityRollup [];
readonly overall : Rollup ;
};The view of a group at an instant.
logical.GroupViewInputtype no test imports it type GroupViewInput = {
readonly tree : EntityTree ;
readonly scope : ControlScope ;
readonly controls : readonly string [];
readonly readings : readonly EntityReading [];
readonly exceptions : readonly Exception [];
readonly at : string ;
};logical.groupViewfunction no test imports it function groupView (input : GroupViewInput ): GroupView The group view at at: a cell for every control and entity (the controls and the entities in order), rolled up by control, by entity with its subtenants and overall; the same for any order of the readings, of the controls and of the entities. Nothing is read but the readings: a snapshot holds no evidence.
// groupView({ tree, scope, controls, readings, exceptions: [], at }).entities[0]?.rolledUp; const entitySnapshot: DocumentKind<Document & { readonly entity: EntityId; readonly ledgerHead: string; readonly control… (524 characters) const entitySnapshot : DocumentKind <Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}>What an entity gives the group: statuses and digests of its controls, the head of its ledger, and nothing else.
// entitySnapshot.decode(document).kind; Imported by 15 tests of the run (15 passed, 0 failed): the library's results
type EntitySnapshot = Decoded <typeof entitySnapshot.decode>;A snapshot of one entity.
Imported by 27 tests of the run (27 passed, 0 failed): the library's results
SnapshotInputtype no test imports it type SnapshotInput = {
readonly entity : EntityId ;
readonly frameworks : readonly Framework [];
readonly crosswalks : readonly Crosswalk [];
readonly checks : readonly Check [];
readonly results : readonly Outcome [];
readonly exceptions : readonly Exception [];
readonly ledgerHead : string ;
};What an entity's own side is given to make its snapshot: its own results and exceptions, and the group's frameworks, crosswalks and checks, defined once.
function snapshotOf(input: SnapshotInput, at: string): Promise<Result<Document & { readonly entity: EntityId; readonly l… (568 characters) function snapshotOf (input : SnapshotInput , at : string ): Promise <Result <Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}, string >>The snapshot of an entity at at, made from its own data: the newest results with the exceptions applied, and the coverage of every control.
// const made = await snapshotOf({ entity, frameworks, crosswalks, checks, results, exceptions, ledgerHead }, "2026-06-01T00:00:00Z"); Imported by 12 tests of the run (12 passed, 0 failed): the library's results
ReadFaulttype no test imports it type ReadFault = { readonly kind : "unreachable" | "denied" | "malformed" ; readonly message : string };Why an entity could not be read.
type EntityReader = (at : string ) => Promise <Result <EntitySnapshot , ReadFault >>;The reader of one entity, made by the host for that entity alone: given the instant, nothing else, it answers with a snapshot or a fault.
Imported by 27 tests of the run (27 passed, 0 failed): the library's results
Readerstype no test imports it type Readers = ReadonlyMap <EntityId , EntityReader >;The readers of a group, by entity.
type EntityReading =
| { readonly kind : "read" ; readonly snapshot : EntitySnapshot }
| { readonly kind : "unread" ; readonly entity : EntityId ; readonly fault : ReadFault };What reading an entity gave.
Imported by 27 tests of the run (27 passed, 0 failed): the library's results
entityOffunction no test imports it function entityOf (reading : EntityReading ): EntityId The entity a reading is of.
// entityOf({ kind: "unread", entity, fault: { kind: "unreachable", message: "down" } }) === entity; normalizeSnapshotfunction no test imports it function normalizeSnapshot(s: Document & { readonly entity: EntityId; readonly ledgerHead: string; readonly controls: re… (1009 characters) function normalizeSnapshot (s : Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}): Document & { readonly entity : EntityId ; readonly ledgerHead : string ; readonly controls : readonly ObjectOf <{ control : Decoder <string >; status : Decoder <"accepted" | "error" | "fail" | "gap" | "not-applicable" | "pass" | "pending" | "warn" >; coverage : Decoder <"accepted" | "covered" | "failing" | "gap" | "partial" | "stale" | "untested" >; severity : Decoder <"critical" | "high" | "info" | "low" | "medium" >; digests : Decoder <readonly string []>; }, { observedAt : Decoder <string >; }>[]; } & {}A snapshot rebuilt from its known fields, so that nothing else passes through.
// normalizeSnapshot(snapshot); // the same snapshot with nothing but its known fields function readGroup(group: Document & { readonly title: string; readonly entities: readonly ObjectOf<{ id: Decoder<Entity… (417 characters) function readGroup (group : Document & { readonly title : string ; readonly entities : readonly ObjectOf <{ id : Decoder <EntityId >; title : Decoder <string >; ledger : Decoder <PortRef >; store : Decoder <PortRef >; keys : Decoder <readonly PortRef []>; secrets : Decoder <readonly SecretRef []>; }, { parent : Decoder <EntityId >; }>[]; } & { readonly [x : string ]: unknown ; }, readers : Readers , at : string ): Promise <readonly EntityReading []>Reads each entity of the group through its own reader, given the instant and nothing else; a reader that rejects, throws, gives another entity's snapshot or gives what is not a snapshot is a fault, and an entity with no reader is unreachable.
// const readings = await readGroup(group, new Map([[unitA, readerOfA]]), "2026-06-01T00:00:00Z"); // the others are unread Imported by 27 tests of the run (27 passed, 0 failed): the library's results
type GroupCoverage = CoverageState | "unknown" ;The coverage of a group's cell: an entity's own, or unknown for one that could not be read.
Imported by 12 tests of the run (12 passed, 0 failed): the library's results
const GROUP_COVERAGE_ORDER : readonly ["covered" , "accepted" , "stale" , "partial" , "untested" , "unknown" , "failing" , "gap" ]Group coverage from the best to the worst; unknown is worse than anything an entity shows short of failing.
GROUP_COVERAGE_ORDER .indexOf ("unknown" ) > GROUP_COVERAGE_ORDER .indexOf ("partial" ); // true Imported by 27 tests of the run (27 passed, 0 failed): the library's results
function joinCoverage (a : GroupCoverage , b : GroupCoverage ): GroupCoverage The worse of two group coverages: associative, commutative and idempotent.
joinCoverage ("covered" , "unknown" ); // "unknown" Imported by 12 tests of the run (12 passed, 0 failed): the library's results
GroupCelltype no test imports it type GroupCell = {
readonly control : string ;
readonly entity : EntityId ;
readonly status : Status ;
readonly coverage : GroupCoverage | "not-applicable" ;
readonly severity : Severity ;
readonly reading : "read" | "unread" ;
};One control of one entity in the group view.
ControlRolluptype no test imports it type ControlRollup = {
readonly control : string ;
readonly status : Status ;
readonly coverage : GroupCoverage | "not-applicable" ;
readonly applicable : number ;
};One control across the entities it applies to.
EntityRolluptype no test imports it type EntityRollup = {
readonly entity: EntityId;
readonly parent?: EntityId;
readonly children: readonly EntityId[… (402 characters) type EntityRollup = {
readonly entity : EntityId ;
readonly parent ?: EntityId ;
readonly children : readonly EntityId [];
readonly depth : number ;
readonly own : Status ;
readonly rolledUp : Status ;
readonly ownCoverage : GroupCoverage | "not-applicable" ;
readonly rolledUpCoverage : GroupCoverage | "not-applicable" ;
readonly reading : "read" | "unread" ;
readonly share : number | undefined ;
};One entity of the tree in the view: its place, its own status and coverage (the join of its cells), and its rolled-up status and coverage (the join of its own and its subtenants' rolled-up).
type GroupView = {
readonly at : string ;
readonly roots : readonly EntityId [];
readonly cells : readonly GroupCell [];
readonly controls : readonly ControlRollup [];
readonly entities : readonly EntityRollup [];
readonly overall : Rollup ;
};The view of a group at an instant.
Imported by 15 tests of the run (15 passed, 0 failed): the library's results
GroupViewInputtype no test imports it type GroupViewInput = {
readonly tree : EntityTree ;
readonly scope : ControlScope ;
readonly controls : readonly string [];
readonly readings : readonly EntityReading [];
readonly exceptions : readonly Exception [];
readonly at : string ;
};function groupView (input : GroupViewInput ): GroupView The group view at at: a cell for every control and entity (the controls and the entities in order), rolled up by control, by entity with its subtenants and overall; the same for any order of the readings, of the controls and of the entities. Nothing is read but the readings: a snapshot holds no evidence.
// groupView({ tree, scope, controls, readings, exceptions: [], at }).entities[0]?.rolledUp; Imported by 27 tests of the run (27 passed, 0 failed): the library's results