IF Commons GitHub

assessor/pack

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

The assessor pack (commons 0001-quality-evidence FR-060 to FR-063, FR-066): a self-contained bundle for one revision and one span of time, made from what PackSource holds and nothing else, deterministic (the same source gives the same bytes), with a manifest that gives each file's SHA-256, size and media type.

PathWhat
quality/evidence/YYYY/MM/DD/<trace>.otlp.jsonthe evidence files of the span, as kept, with their chain
quality/records/NNNNNN-<kind>.jsonthe ledger of nonconformances, CAPA, attestations, plans, samples and mutation runs
notes/<commit>.notethe notes that link a tested commit to its evidence file
specs/<slug>/<digest>.md and specs/index.jsonthe specifications at the tested revisions
trace/matrix.tsvthe traceability matrix: each requirement, its mechanism, grade, freshness, last proof and the strength of its proof
oscal/<trace>.assessment-results.jsonthe OSCAL assessment results of each run
index.jsonthe index of the quality branch (0001-quality-evidence FR-024)
signatures/pack.dsse.json, keys/allowed_signersthe signed statement over every file and the keys that verify it
verify/verify-pack.ts, verify/verify.tsthe verifier, so that the pack checks itself
manifest.jsonthe audience, the span, the chain, the figures, the redactions and the files

What a pack must not leak is stopped at the source: the evidence and the ledger are written redacted of secrets and e-mail addresses (0021-ifqs FR-020), and changing a file now would break its chain, so a file that still holds a secret refuses the pack (naming it), and a file that holds an e-mail address (the author of a corrective change, say) is kept as it is and named in the manifest's retained. The files made here (matrix, OSCAL, index) are redacted and their redactions counted (FR-061).

Source: commons/quality/src/assessor/pack.ts

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

PACK_PREDICATEconstno test imports it
const PACK_PREDICATE: "https://github.com/intellectual-frontiers/.github/tree/main/commons/spec-kit/specs/0022-trust/pack"

The predicate type of the statement a pack is signed with.

SourceFiletypeno test imports it
type SourceFile = { readonly path: string; readonly text: string };

A file of the pack's source: its path in the pack and its text.

PackSourcetypeno test imports it
type PackSource = { readonly harness: string; readonly revision: string; readonly asOf: string; /** The span of … (1338 characters)
type PackSource = {
  readonly harness: string;
  readonly revision: string;
  readonly asOf: string;
  /** The span of days to include, both ends included; the whole branch where not given. */
  readonly span?: { readonly from?: string; readonly to?: string };
  /** Every evidence file of the branch, in the order they were kept. */
  readonly evidence: readonly SourceFile[];
  /** Every file of the ledger, in order. */
  readonly records: readonly SourceFile[];
  /** The notes of tested commits: the commit and the note's text. */
  readonly notes: readonly { readonly commit: string; readonly text: string }[];
  /** The specifications at the tested revisions, at their paths in the pack, and the index that maps a revision to each. */
  readonly specs: readonly SourceFile[];
  readonly specIndex: string;
  readonly matrix: string;
  readonly index: string;
  readonly oscal: readonly { readonly traceId: string; readonly text: string }[];
  /** The verifier's own source files, copied into the pack byte for byte. */
  readonly verifier: { readonly pack: string; readonly main: string };
  /** The keys that sign it and the allowed-signers file that verifies it; none where the pack is not signed (it then verifies as `not_run`). */
  readonly signing?: { readonly keys: readonly DsseKey[]; readonly allowedSigners: string };
};

What the pack is made from: the evidence of a harness at a revision, read once.

ManifestFiletypeno test imports it
type ManifestFile = { readonly path: string; readonly sha256: string; readonly bytes: number; readonly mediaType: string };

The manifest's entry for a file.

BuiltPacktypeno test imports it
type BuiltPack = {
  readonly files: PackFiles;
  readonly manifest: string;
  readonly figures: Figures;
  readonly redactions: number;
};

A pack: its files, with the manifest among them.

mediaTypeOffunctionno test imports it
function mediaTypeOf(path: string): string

The IANA media type of a file of a pack, from its name.

buildPackfunction
function buildPack(source: PackSource): Promise<Result<BuiltPack, string>>

The pack of a source (FR-060 to FR-062, FR-066), or why it cannot be made: a span that is not a contiguous part of the chain, a file that holds a secret (it cannot be redacted without breaking its chain: it is named so that its source is fixed), or a key that cannot sign.

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

matrixTsvfunctionno test imports it
function matrixTsv(register: readonly { readonly requirement: string; readonly mechanism: string; }[], requirements: readonly TrustRequirement[]): string

The traceability matrix (FR-060): each requirement of the proof register with its mechanism, grade, freshness, the day and run of its last proof and the strength of that proof, tab separated, sorted by requirement.

packTarfunctionno test imports it
function packTar(pack: BuiltPack): Result<Uint8Array<ArrayBufferLike>, string>

The pack as one deterministic tar archive (ustar, no time, no owner), the distribution of FR-063.

dcatOffunctionno test imports it
function dcatOf(input: { readonly title: string; readonly file: string; readonly sha256: string; readonly bytes: number; readonly revision: string; readonly downloadUrl?: string | undefined; }): string

The DCAT distribution of a pack (FR-063): a JSON-LD description of the file, with its SHA-256 beside it.

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