EvidencePathtypeno test imports ittype EvidencePath = Brand<string, "EvidencePath">;A path of an evidence file on the quality branch, made only by evidencePath and parseEvidencePath.
Where a run's evidence lives and how a file proves the one before it (commons 0001-quality-evidence FR-021 to FR-023, FR-026): the path quality/evidence/YYYY/MM/DD/<trace id>.otlp.json (a branded EvidencePath), the chain of ifc.quality.previous.sha256 over the files in the order they were kept and its verification, which names the first file that does not match (as 0007-grc FR-007 does for a ledger), the note a commit carries (refs/notes/quality) and the grade evidence is worth given what is known of it.
A file's digest is the SHA-256 of its bytes. The chain cannot see a change to the last file kept, since nothing yet points to it; the note on the tested commit does (verifyNote), and so the grade of a commit whose note does not match its file falls to E0 (0021-ifqs Edge cases).
import { evidencePath } from "./chain.ts";
// evidencePath("4bf92f3577b34da6a3ce929d0e0e4736", 1_700_000_000_000_000_000n)
// // "quality/evidence/2023/11/14/4bf92f3577b34da6a3ce929d0e0e4736.otlp.json"EvidencePathtypeno test imports ittype EvidencePath = Brand<string, "EvidencePath">;A path of an evidence file on the quality branch, made only by evidencePath and parseEvidencePath.
evidencePathfunctionno test imports itfunction evidencePath(traceId: string, endNanos: bigint): Result<EvidencePath, string>The path of the file of a run: its trace id and the UTC day the run ended (FR-021).
parseEvidencePathfunctionno test imports itfunction parseEvidencePath(text: string): Result<{ readonly path: EvidencePath; readonly day: string; readonly traceId: string; }, string>A path as an evidence path, with its day and trace id, or why it is not one.
fileDigestfunctionno test imports itfunction fileDigest(text: string | Uint8Array<ArrayBufferLike>): Promise<Sha256>The digest of a file (FR-022): the SHA-256 of its bytes.
KeptFiletypeno test imports ittype KeptFile = { readonly path: string; readonly text: string };A file of the branch as the verifier is given it: its path and its text, in the order the commits kept them.
ChainBreaktypeno test imports ittype ChainBreak =
| { readonly kind: "path"; readonly file: string; readonly reason: string }
| { readonly kind: "un… (510 characters)type ChainBreak =
| { readonly kind: "path"; readonly file: string; readonly reason: string }
| { readonly kind: "unreadable"; readonly file: string; readonly error: QualityError }
| { readonly kind: "first"; readonly file: string; readonly found: string }
| { readonly kind: "unlinked"; readonly file: string }
| { readonly kind: "mismatch"; readonly file: string; readonly after: string; readonly expected: Sha256; readonly found: Sha256 }
| { readonly kind: "duplicate"; readonly file: string };The first thing wrong with a chain, naming the file (FR-022).
formatChainBreakfunctionno test imports itfunction formatChainBreak(b: ChainBreak): stringA break as one sentence.
ChainHeadtypeno test imports ittype ChainHead = { readonly count: number; readonly head: Sha256; readonly records: readonly QualityRecord[] };What a chain that verifies is: how many files, and the digest of the last (the next file's predecessor).
verifyChainfunctionno test imports itfunction verifyChain(files: readonly KeptFile[]): Promise<Result<ChainHead, ChainBreak>>Whether files, in the order they were kept, form the chain (FR-022): each at a path of its trace id and day, each a record that names the digest of the file before it (64 zeros for the first). The first file that does not match is named.
EvidenceNotetypeno test imports ittype EvidenceNote = { readonly path: EvidencePath; readonly sha256: Sha256; readonly grade: Grade };What a commit's note says of its evidence: the file's path, its SHA-256 and its grade (FR-023).
formatNotefunctionno test imports itfunction formatNote(n: EvidenceNote): stringThe text of a note: three lines.
parseNotesfunctionfunction parseNotes(text: string): Result<readonly EvidenceNote[], string>The notes of a commit, oldest first: a note holds one stanza for each run kept for the commit, separated by a blank line.
verifyNotefunctionno test imports itfunction verifyNote(note: EvidenceNote, file: string | Uint8Array<ArrayBufferLike>): Promise<boolean>Whether a note matches the file it names (FR-023): the SHA-256 of the file is the note's.
EvidenceFactstypeno test imports ittype EvidenceFacts = {
/** The record exists, and reads. */
readonly record: boolean;
/** It is kept on the `quali… (535 characters)type EvidenceFacts = {
/** The record exists, and reads. */
readonly record: boolean;
/** It is kept on the `quality` branch, in a chain that verifies. */
readonly chained: boolean;
/** The commit that kept it carries a signature (FR-021). */
readonly signed: boolean;
/** The tested commit's note names this file and its SHA-256 matches (FR-023). */
readonly linked: boolean;
/** A note exists and its SHA-256 does not match the file, or the chain is broken: the evidence is broken. */
readonly broken: boolean;
};What is known of a run's evidence when its grade is judged.
gradeOffunctionno test imports itfunction gradeOf(f: EvidenceFacts): GradeThe grade of a run's evidence (FR-026): E3 where the record exists, E4 where it is kept on the branch, chained, signed and linked to its commit, and E0 where the evidence is broken (a note whose SHA-256 differs from its file, or a chain that does not verify) until a new run. The grades E1, E2 and E5 are those of statements, reviews and probes, which a record of a run does not give.