IF Commons GitHub

logical/group

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

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.entitySnapshotconstno 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.EntitySnapshottypeno test imports it
type EntitySnapshot = Decoded<typeof entitySnapshot.decode>;

A snapshot of one entity.

logical.SnapshotInputtypeno 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.snapshotOffunctionno 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.ReadFaulttypeno test imports it
type ReadFault = { readonly kind: "unreachable" | "denied" | "malformed"; readonly message: string };

Why an entity could not be read.

logical.EntityReadertypeno 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.Readerstypeno test imports it
type Readers = ReadonlyMap<EntityId, EntityReader>;

The readers of a group, by entity.

logical.EntityReadingtypeno 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.entityOffunctionno 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.normalizeSnapshotfunctionno 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.readGroupfunctionno 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.GroupCoveragetypeno 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.

logical.GROUP_COVERAGE_ORDERconstno test imports it
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.joinCoveragefunctionno 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.GroupCelltypeno 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.ControlRolluptypeno 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.EntityRolluptypeno 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.GroupViewtypeno 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.GroupViewInputtypeno 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;
};

What groupView reads.

logical.groupViewfunctionno 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;
entitySnapshotconst
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

EntitySnapshottype
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

SnapshotInputtypeno 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.

snapshotOffunction
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

ReadFaulttypeno test imports it
type ReadFault = { readonly kind: "unreachable" | "denied" | "malformed"; readonly message: string };

Why an entity could not be read.

EntityReadertype
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

Readerstypeno test imports it
type Readers = ReadonlyMap<EntityId, EntityReader>;

The readers of a group, by entity.

EntityReadingtype
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

entityOffunctionno test imports it
function entityOf(reading: EntityReading): EntityId

The entity a reading is of.

// entityOf({ kind: "unread", entity, fault: { kind: "unreachable", message: "down" } }) === entity;
normalizeSnapshotfunctionno 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
readGroupfunction
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

GroupCoveragetype
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

GROUP_COVERAGE_ORDERconst
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

joinCoveragefunction
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

GroupCelltypeno 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.

ControlRolluptypeno 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.

EntityRolluptypeno 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).

GroupViewtype
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

GroupViewInputtypeno 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;
};

What groupView reads.

groupViewfunction
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

Titles, headings, exports, tables, columns and requirements. Esc closes.