normalizedfunctionno test imports itfunction normalized(population: readonly string[]): readonly string[]The population as the rule sees it: its items sorted, without duplicates.
Attestation by recorded sample (commons 0001-quality-evidence FR-041): a person samples records at random, and what was sampled, the rule and the seed that chose it, the result on each item, the person's name and role and the day are kept as chained records. The seed makes the sample reproducible: anyone given the population and the seed draws the same items (verifyDraw).
The rule hash-ranked/1 ranks each item of the population (sorted, without duplicates) by the SHA-256 of seed, a line feed and the item, and takes the first size of them; the items are listed sorted. It needs no random generator in the pure code: the randomness is the seed, which a person gives or freshSeed makes from the host's random bytes, and which is recorded either way. The population is recorded as its count and the SHA-256 of its sorted items, so a sample cannot be redrawn from another population without the digest saying so.
import { drawSample } from "./sample.ts";
// const drawn = await drawSample({ population: ["a", "b", "c", "d"], seed: "7f3a", size: 2 });normalizedfunctionno test imports itfunction normalized(population: readonly string[]): readonly string[]The population as the rule sees it: its items sorted, without duplicates.
populationDigestfunctionno test imports itfunction populationDigest(population: readonly string[]): Promise<Sha256>The digest of a population (its sorted items, one on each line).
freshSeedfunctionfunction freshSeed(random?: (bytes: Uint8Array<ArrayBuffer>) => Uint8Array<ArrayBufferLike>): stringA seed made of random bytes, for a person who gives none: 128 bits as hexadecimal. The one place a sample's randomness enters.
sizeOffunctionfunction sizeOf(count: number, size: number | undefined, ratePermille: number | undefined): Result<number, string>How many items a sample holds: the size given, or the share ratePermille of the population rounded up and at least one (FR-044's rate).
Drawntypeno test imports ittype Drawn = {
readonly size: number;
readonly items: readonly string[];
readonly population: { readonly count: number; readonly sha256: Sha256 };
};A sample as drawn.
DrawInputtypeno test imports ittype DrawInput = {
readonly population: readonly string[];
readonly seed: string;
readonly size?: number;
readonly ratePermille?: number;
};What a draw is given.
drawSamplefunctionfunction drawSample(input: DrawInput): Promise<Result<Drawn, string>>Draws a sample: the items of the population ranked by the SHA-256 of the seed and the item, the first size taken, listed sorted (FR-041).
SampleDrawntypeno test imports ittype SampleDrawn = Extract<LedgerEvent, { readonly kind: "sample-drawn" }>;The event of a sample drawn.
SampleAttestedtypeno test imports ittype SampleAttested = Extract<LedgerEvent, { readonly kind: "sample-attested" }>;The event of a person's attestation.
verifyDrawfunctionfunction verifyDraw(event: ObjectOf<{ kind: Decoder<"sample-drawn">; id: Decoder<string>; subject: Decoder<"agent-review… (582 characters)function verifyDraw(event: ObjectOf<{ kind: Decoder<"sample-drawn">; id: Decoder<string>; subject: Decoder<"agent-reviews" | "records" | "runs">; rule: Decoder<"hash-ranked/1">; seed: Decoder<string>; population: Decoder<ObjectOf<{ count: Decoder<number>; sha256: Decoder<Brand<string, "Sha256">>; }, Record<never, never>>>; size: Decoder<number>; items: Decoder<readonly string[]>; by: Decoder<ObjectOf<{ name: Decoder<string>; }, { role: Decoder<string>; }>>; day: Decoder<Day>; }, { ratePermille: Decoder<number>; }>, population: readonly string[]): Promise<Result<true, string>>Whether a recorded sample is the one its seed and population give (FR-041): the population is the one the record names (its count and digest), and drawing again gives the items the record lists. The first difference is named.
DrawEventInputtypeno test imports ittype DrawEventInput = DrawInput & {
readonly subject: SampleSubject;
readonly by: PersonRef;
readonly day: string;
/** The identifier the sample takes (the next the ledger holds). */
readonly id: string;
};What drawEvent is given.
drawEventfunctionfunction drawEvent(input: DrawEventInput): Promise<Result<import("/home/runner/work/.github/.github/commons/core/src/dec… (17590 characters)function drawEvent(input: DrawEventInput): Promise<Result<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"plan-registered">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; plan: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ title: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; cases: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; requirements: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">[]>; acceptance: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { file: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>[]>; }, Record<never, never>>>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Record<never, never>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"sample-drawn">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; subject: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent-reviews" | "records" | "runs">; rule: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"hash-ranked/1">; seed: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; population: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ count: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; sha256: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "Sha256">>; }, Record<never, never>>>; size: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; items: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly string[]>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { ratePermille: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"sample-attested">; sample: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; results: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ item: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; verdict: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"fail" | "pass">; }, { note: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>[]>; person: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, {}> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"mutation-run">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; tool: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { version: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; revision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; results: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; mutants: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; killed: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; survived: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }, { timeout: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; noCoverage: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; equivalent: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }>[]>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Record<never, never>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"nonconformance-opened">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; cause: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"budget-spent" | "failed" | "probe-failed" | "stale">; reason: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; evidence: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{}, { traceId: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; path: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; revision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; openedBy: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"system">; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent">; name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"role">; role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, {}> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"nonconformance-linked">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; problem: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ number: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }, { repo: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"capa-opened">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; nonconformance: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; action: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; test: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Record<never, never>>>; correctiveRevision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; openedBy: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"system">; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent">; name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"role">; role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { author: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"capa-verified">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; traceId: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; revision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"capa-closed">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; decision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; person: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"nonconformance-closed">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; capa: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"statement">; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent" | "person">; who: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { note: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"review">; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent" | "person">; who: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { sample: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<boolean>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"probe">; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; outcome: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"fail" | "pass">; source: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>>, string>>The event that records a sample drawn: its subject, the rule, the seed, the population's count and digest, the items and the person who drew it.