IF Commons GitHub

governance/requirement

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-archon-governance FR-003, 0002-archon-governance FR-004

A requirement: what a subject must be, said once. It names what must hold and why, for which subjects, of which kind of resource, how much a change to it matters (its change class) and how it is verified. defineRequirement is the one way to make one, and it refuses, with every reason, what is not one.

import { defineRequirement } from "./requirement.ts";
const r = defineRequirement({
  id: "baseline.openssh",
  summary: "OpenSSH is installed.",
  why: ["the only way in"],
  subject: { by: "all" },
  kind: "package",
  desired: { name: "openssh-server" },
  change: "additive",
});
r.kind; // "ok"

Source: commons/archon/src/governance/requirement.ts

3 of 13 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

ChangeClasstypeno test imports it
type ChangeClass = "additive" | "mutating" | "destructive";

How much a change to a resource matters: it adds, it changes what is there, or it destroys.

CHANGE_CLASSESconstno test imports it
const CHANGE_CLASSES: readonly ChangeClass[]

Every change class.

Rollbacktypeno test imports it
type Rollback = "reversible" | "restore-from-backup" | "none";

How a change can be undone.

ROLLBACKSconstno test imports it
const ROLLBACKS: readonly Rollback[]

Every rollback stance.

PlanFidelitytypeno test imports it
type PlanFidelity = "faithful" | "best-effort";

How faithful a plan must be: faithful shows what would change, best-effort accepts a partial plan.

Ensuretypeno test imports it
type Ensure = "present" | "absent";

Whether the resource must be there or must not.

SubjectSelectortypeno test imports it
type SubjectSelector =
  | { readonly by: "all" }
  | { readonly by: "names"; readonly names: readonly SubjectName[] }
  | { readonly by: "class"; readonly class: SubjectClass };

Which subjects a requirement is for: every subject, some by name, or every subject of a class.

Verificationtypeno test imports it
type Verification =
  | { readonly by: "osquery"; readonly query: string }
  | { readonly by: "dialect" }
  | { readonly by: "none"; readonly reason: string };

How the state of a resource is verified afterwards: by an osquery query, by the dialect's own check, or not (with the reason).

Requirementtype
type Requirement = { readonly id: RequirementId; readonly summary: string; /** Why it holds: the specifications, c… (686 characters)
type Requirement = {
  readonly id: RequirementId;
  readonly summary: string;
  /** Why it holds: the specifications, controls or sentences it answers to; never empty. */
  readonly why: readonly string[];
  readonly subject: SubjectSelector;
  readonly kind: ResourceKindId;
  readonly ensure: Ensure;
  /** What must hold: data, with references to secrets and never secrets. */
  readonly desired: JsonValue;
  readonly change: ChangeClass;
  readonly plan: PlanFidelity;
  /** The name of the tier a person needs to approve a change to it. */
  readonly tier: string;
  readonly verify: Verification;
  readonly rollback: Rollback;
  readonly dependsOn: readonly RequirementId[];
};

A requirement.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

SubjectSelectorInputtypeno test imports it
type SubjectSelectorInput =
  | { readonly by: "all" }
  | { readonly by: "names"; readonly names: readonly string[] }
  | { readonly by: "class"; readonly class: string };

A selector as written, with its names and class as text.

RequirementInputtype
type RequirementInput = { readonly id: string; readonly summary: string; readonly why: readonly string[]; readon… (423 characters)
type RequirementInput = {
  readonly id: string;
  readonly summary: string;
  readonly why: readonly string[];
  readonly subject: SubjectSelectorInput;
  readonly kind: string;
  readonly desired: unknown;
  readonly change: string;
  readonly ensure?: string;
  readonly plan?: string;
  readonly tier?: string;
  readonly verify?: Verification;
  readonly rollback?: string;
  readonly dependsOn?: readonly string[];
};

What defineRequirement takes: names as text, and defaults for what is left out (present, a faithful plan, the tier operator, verified by the dialect, reversible, no dependencies).

Imported by 20 tests of the run (20 passed, 0 failed): the library's results

defineRequirementfunction
function defineRequirement(input: RequirementInput, catalogue?: readonly KindSpec[]): Result<Requirement, readonly string[]>

A requirement, or every reason the input is not one.

Imported by 20 tests of the run (20 passed, 0 failed): the library's results

selectsfunctionno test imports it
function selects(selector: SubjectSelector, subject: { readonly name: SubjectName; readonly class: SubjectClass; }): boolean

Whether a selector matches a subject of this name and class.

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