IF Commons GitHub

governance/proof

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0008-repoctl-prove FR-002

The facts of proof proportional to blast radius (commons repoctl 0008-repoctl-prove FR-002 to FR-005, FR-009): the seven tiers of proof with their budgets, the change classes with the proofs each one needs, the proofs as a closed union (each belongs to exactly one tier by an exhaustive function), the reasons a proof is left out, the foundation libraries and the files whose change is every proof's change. The planner of the Logical layer reads these tables and decides nothing of its own that is not here.

import { CLASS_RULES, tierOfProof } from "./proof.ts";
CLASS_RULES.prose.tiers; // ["T0"]
tierOfProof({ kind: "sync-check" }); // "T0"

Source: commons/repoctl/src/governance/proof.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.

governance.ProofTiertypeno test imports it
type ProofTier = "T0" | "T1" | "T2" | "T3" | "T4" | "T5" | "T6";

The seven tiers of proof, cheapest first: a closed union.

governance.PROOF_TIER_IDSconstno test imports it
const PROOF_TIER_IDS: readonly ProofTier[]

Every tier of proof, cheapest first.

governance.Occasiontypeno test imports it
type Occasion = "edit" | "push" | "main" | "nightly" | "release";

When a tier runs.

governance.TierFactstypeno test imports it
type TierFacts = {
  readonly id: ProofTier;
  readonly name: string;
  readonly proves: string;
  readonly budgetSeconds: number;
  readonly runsOn: readonly Occasion[];
};

What a tier is: its name, what it proves, its budget in seconds and the occasions it runs on.

governance.PROOF_TIERSconstno test imports it
const PROOF_TIERS: Readonly<Record<ProofTier, TierFacts>>

The tiers of proof by their words.

governance.parseProofTierfunctionno test imports it
function parseProofTier(text: string): Result<ProofTier, string>

A tier from 3 or T3, or why the text is none.

governance.ChangeClasstypeno test imports it
type ChangeClass = "prose" | "spec" | "spec-requirements" | "generated" | "version" | "test" | "source" | "packaging" | "planner" | "outside";

What a changed file is: a closed union.

governance.CHANGE_CLASSESconstno test imports it
const CHANGE_CLASSES: readonly ChangeClass[]

Every class, in the order the table and the plan list them.

governance.ClassRuletypeno test imports it
type ClassRule = {
  readonly class: ChangeClass;
  readonly means: string;
  readonly proofs: string;
  readonly tiers: readonly ProofTier[];
};

What a class is and what it needs: one row for each class.

governance.CLASS_RULESconstno test imports it
const CLASS_RULES: Readonly<Record<ChangeClass, ClassRule>>

The class rules: the one table the planner, the documentation and the tests read.

governance.SpecScopetypeno test imports it
type SpecScope = LibraryName | "repository";

What a scope of the specification check is: one library's kit or the repository's.

governance.Prooftypeno test imports it
type Proof = | { readonly kind: "docs-check" } | { readonly kind: "spec-check"; readonly scope: SpecScope } | { re… (774 characters)
type Proof =
  | { readonly kind: "docs-check" }
  | { readonly kind: "spec-check"; readonly scope: SpecScope }
  | { readonly kind: "trace-check"; readonly library: LibraryName }
  | { readonly kind: "types"; readonly library: LibraryName }
  | { readonly kind: "sync-check" }
  | { readonly kind: "versions-check" }
  | { readonly kind: "suite"; readonly library: LibraryName }
  | { readonly kind: "smoke"; readonly library: LibraryName }
  | { readonly kind: "seam"; readonly provider: LibraryName; readonly consumer: LibraryName }
  | { readonly kind: "pack"; readonly library: LibraryName }
  | { readonly kind: "end-to-end" }
  | { readonly kind: "platform"; readonly library: LibraryName; readonly system: "windows" | "macos" }
  | { readonly kind: "release-gate" };

A proof: one check or run, for a library where it has one. A closed union, so that every proof has its tier, its command and its sentence by an exhaustive match.

governance.tierOfProoffunctionno test imports it
function tierOfProof(p: Proof): ProofTier

The tier a proof belongs to: every proof is in exactly one.

governance.proofKeyfunctionno test imports it
function proofKey(p: Proof): string

The proof as one stable key: the same proof has the same key, so a plan holds each once.

governance.SkipReasontypeno test imports it
type SkipReason = "class-needs-none" | "surface-unchanged" | "symbols-unused" | "tests-unaffected" | "cache-hit" | "tier-scheduled" | "quarantined";

Why a proof is left out: a closed union, each with one sentence in the plan.

governance.SKIP_REASONSconstno test imports it
const SKIP_REASONS: readonly SkipReason[]

Every reason, in the order of the documentation.

governance.FOUNDATIONconstno test imports it
const FOUNDATION: readonly string[]

The foundation libraries: what the rest of commons stands on, so a change of their behaviour runs a smoke gate before anything wider.

governance.PLANNER_GLOBSconstno test imports it
const PLANNER_GLOBS: readonly string[]

The paths whose change is the change of every proof: the planner, the generators, the workflow definitions and the tier rules (globs; * is one segment, ** any number).

governance.QuarantineEntrytypeno test imports it
type QuarantineEntry = { readonly test: string; readonly owner: string; readonly expires: string; readonly reason: string };

A quarantined test: named by its path from the repository's root, with the person who owns getting it fixed, the day it must be fixed by (it runs again after) and why.

governance.parseQuarantinefunctionno test imports it
function parseQuarantine(text: string): Result<readonly QuarantineEntry[], string>

The quarantine record from its JSON text, or why it is not one: a list of entries, each with a test, an owner, an expiry day (YYYY-MM-DD) and a reason.

ProofTiertypeno test imports it
type ProofTier = "T0" | "T1" | "T2" | "T3" | "T4" | "T5" | "T6";

The seven tiers of proof, cheapest first: a closed union.

PROOF_TIER_IDSconst
const PROOF_TIER_IDS: readonly ProofTier[]

Every tier of proof, cheapest first.

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

Occasiontypeno test imports it
type Occasion = "edit" | "push" | "main" | "nightly" | "release";

When a tier runs.

TierFactstypeno test imports it
type TierFacts = {
  readonly id: ProofTier;
  readonly name: string;
  readonly proves: string;
  readonly budgetSeconds: number;
  readonly runsOn: readonly Occasion[];
};

What a tier is: its name, what it proves, its budget in seconds and the occasions it runs on.

PROOF_TIERSconst
const PROOF_TIERS: Readonly<Record<ProofTier, TierFacts>>

The tiers of proof by their words.

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

parseProofTierfunction
function parseProofTier(text: string): Result<ProofTier, string>

A tier from 3 or T3, or why the text is none.

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

ChangeClasstypeno test imports it
type ChangeClass = "prose" | "spec" | "spec-requirements" | "generated" | "version" | "test" | "source" | "packaging" | "planner" | "outside";

What a changed file is: a closed union.

CHANGE_CLASSESconst
const CHANGE_CLASSES: readonly ChangeClass[]

Every class, in the order the table and the plan list them.

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

ClassRuletypeno test imports it
type ClassRule = {
  readonly class: ChangeClass;
  readonly means: string;
  readonly proofs: string;
  readonly tiers: readonly ProofTier[];
};

What a class is and what it needs: one row for each class.

CLASS_RULESconst
const CLASS_RULES: Readonly<Record<ChangeClass, ClassRule>>

The class rules: the one table the planner, the documentation and the tests read.

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

SpecScopetypeno test imports it
type SpecScope = LibraryName | "repository";

What a scope of the specification check is: one library's kit or the repository's.

Prooftype
type Proof = | { readonly kind: "docs-check" } | { readonly kind: "spec-check"; readonly scope: SpecScope } | { re… (774 characters)
type Proof =
  | { readonly kind: "docs-check" }
  | { readonly kind: "spec-check"; readonly scope: SpecScope }
  | { readonly kind: "trace-check"; readonly library: LibraryName }
  | { readonly kind: "types"; readonly library: LibraryName }
  | { readonly kind: "sync-check" }
  | { readonly kind: "versions-check" }
  | { readonly kind: "suite"; readonly library: LibraryName }
  | { readonly kind: "smoke"; readonly library: LibraryName }
  | { readonly kind: "seam"; readonly provider: LibraryName; readonly consumer: LibraryName }
  | { readonly kind: "pack"; readonly library: LibraryName }
  | { readonly kind: "end-to-end" }
  | { readonly kind: "platform"; readonly library: LibraryName; readonly system: "windows" | "macos" }
  | { readonly kind: "release-gate" };

A proof: one check or run, for a library where it has one. A closed union, so that every proof has its tier, its command and its sentence by an exhaustive match.

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

tierOfProoffunction
function tierOfProof(p: Proof): ProofTier

The tier a proof belongs to: every proof is in exactly one.

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

proofKeyfunction
function proofKey(p: Proof): string

The proof as one stable key: the same proof has the same key, so a plan holds each once.

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

SkipReasontypeno test imports it
type SkipReason = "class-needs-none" | "surface-unchanged" | "symbols-unused" | "tests-unaffected" | "cache-hit" | "tier-scheduled" | "quarantined";

Why a proof is left out: a closed union, each with one sentence in the plan.

SKIP_REASONSconst
const SKIP_REASONS: readonly SkipReason[]

Every reason, in the order of the documentation.

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

FOUNDATIONconst
const FOUNDATION: readonly string[]

The foundation libraries: what the rest of commons stands on, so a change of their behaviour runs a smoke gate before anything wider.

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

PLANNER_GLOBSconstno test imports it
const PLANNER_GLOBS: readonly string[]

The paths whose change is the change of every proof: the planner, the generators, the workflow definitions and the tier rules (globs; * is one segment, ** any number).

QuarantineEntrytypeno test imports it
type QuarantineEntry = { readonly test: string; readonly owner: string; readonly expires: string; readonly reason: string };

A quarantined test: named by its path from the repository's root, with the person who owns getting it fixed, the day it must be fixed by (it runs again after) and why.

parseQuarantinefunction
function parseQuarantine(text: string): Result<readonly QuarantineEntry[], string>

The quarantine record from its JSON text, or why it is not one: a list of entries, each with a test, an owner, an expiry day (YYYY-MM-DD) and a reason.

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

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