IF Commons GitHub

attestation/host

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-quality-evidence FR-041

The records of Tier 2 on the quality branch, with real git (commons 0001-quality-evidence FR-041 to FR-044): a plan registered, a sample drawn from what the branch holds and attested by a person, a mutation report ingested, and the judgement of every run against the plan it names. Each record is one more file of the ledger (host/ledger-branch.ts), chained, in a commit that Git signs where it is set to sign.

Where a record stands on the branch is where its commit stands among the commits of the branch (listCommits): a plan registered before a run is a plan whose commit comes before the commit of the run's file. Nothing here reads a clock; the day of each record is an argument.

Source: commons/quality/src/attestation/host.ts

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

Tier2Errortypeno test imports it
type Tier2Error = LedgerHostError | { readonly kind: "tier2"; readonly reason: string };

Why a record of Tier 2 could not be read or kept.

formatTier2Errorfunctionno test imports it
function formatTier2Error(e: Tier2Error): string

A Tier 2 error as one sentence.

Tier2Statetypeno test imports it
type Tier2State = { readonly ledger: LedgerRead; readonly assurance: Assurance; readonly plans: readonly PlanRegis… (470 characters)
type Tier2State = {
  readonly ledger: LedgerRead;
  readonly assurance: Assurance;
  readonly plans: readonly PlanRegistration[];
  readonly runs: readonly PlanRun[];
  readonly findings: readonly PlanFinding[];
  /** The trace ids of the runs kept, in the order they were kept. */
  readonly runIds: readonly string[];
  /** Where the commit of each ledger record stands on the branch, by the record's number. */
  readonly recordOrder: ReadonlyMap<number, number>;
};

Where the branch stands: the ledger, its Tier 2 records, the plans as registered and each run judged against the plan it names.

ReadOptionstypeno test imports it
type ReadOptions = {
  /** Whether a plan must be in a signed commit (FR-042): where Git is set to sign, true is the harness's choice. */
  readonly requireSigned?: boolean;
  readonly allowedSigners?: string;
};

What reading the state is given.

readTier2function
function readTier2(repo: string, options?: ReadOptions): Promise<Result<Tier2State, Tier2Error>>

Reads the branch and judges every run against the plan it names.

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

Tier2KeepOptionstypeno test imports it
type Tier2KeepOptions = { readonly sign?: boolean };

What every record is kept with.

registerPlanfunction
function registerPlan(repo: string, planText: string, by: ObjectOf<{ name: Decoder<string>; }, { role: Decoder<string>; }>, day: string, options?: Tier2KeepOptions): Promise<Result<{ readonly id: string; readonly read: LedgerRead; }, Tier2Error>>

Registers a plan from the text of its file (FR-042); the record is its title and cases, and the hash a run will name is returned with the record's number.

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

DrawRequesttypeno test imports it
type DrawRequest = {
  readonly subject: SampleSubject;
  readonly by: PersonRef;
  readonly day: string;
  /** The seed a person gives; fresh random bytes where not given. It is recorded either way. */
  readonly seed?: string;
  readonly size?: number;
  readonly ratePermille?: number;
};

What a sample is drawn with.

populationOffunctionno test imports it
function populationOf(repo: string, subject: "agent-reviews" | "records" | "runs"): Promise<Result<readonly string[], Tier2Error>>

The population a sample of a subject is drawn from, as the branch holds it before the record that will keep the sample.

drawAndKeepfunction
function drawAndKeep(repo: string, request: DrawRequest, options?: Tier2KeepOptions): Promise<Result<{ readonly id: string; readonly items: readonly string[]; readonly seed: string; }, Tier2Error>>

Draws a sample of what the branch holds and keeps it as a record (FR-041): the rule, the seed, the population's count and digest and the items.

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

attestAndKeepfunction
function attestAndKeep(repo: string, input: { readonly sample: string; readonly results: readonly { readonly item: string; readonly verdict: "fail" | "pass"; readonly note?: string | undefined; }[]; readonly person: ObjectOf<{ name: Decoder<string>; }, { role: Decoder<string>; }>; readonly day: string; }, options?: Tier2KeepOptions): Promise<Result<LedgerRead, Tier2Error>>

Keeps a person's attestation of a sample (FR-041): a verdict on each item, the person's name and role and the day.

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

verifySamplesfunction
function verifySamples(repo: string): Promise<Result<readonly string[], Tier2Error>>

Whether every sample drawn on the branch is the one its seed and population give, drawn again from the population as it stood (FR-041).

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

ingestMutationfunction
function ingestMutation(repo: string, reportText: string, day: string, options?: Tier2KeepOptions): Promise<Result<{ readonly id: string; }, Tier2Error>>

Ingests the report of a mutation tool as a record (FR-043): the tool is named by the report, the rows by requirement.

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

agentsOffunction
function agentsOf(repo: string, ratePermille: number): Promise<Result<AgentStanding, Tier2Error>>

Where the sampling of the agents' reviews stands against the rate a harness states (FR-044).

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

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