@mark1russell7/layout-contract 0.2.4 → 0.2.6

package/src/hash.ts

@@ -0,0 +1,198 @@
+import { RECORD_EPS } from "./tolerance.ts";
+import { utf8 } from "./utf8.ts";
+
+/** The round constants of SHA-256. */
+const K: readonly number[] = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
+  0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+/**
+ * This function gives the SHA-256 digest of the UTF-8 bytes of a string, as 64 lowercase hex characters.
+ * It uses no API of Node or of the browser.
+ */
+export function sha256Hex(text: string): string {
+  const bytes = utf8(text);
+  const bits = bytes.length * 8;
+  const total = Math.ceil((bytes.length + 9) / 64) * 64;
+  const data = new Uint8Array(total);
+  data.set(bytes);
+  data[bytes.length] = 0x80;
+  const view = new DataView(data.buffer);
+  view.setUint32(total - 8, Math.floor(bits / 0x100000000));
+  view.setUint32(total - 4, bits >>> 0);
+  const h = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+  const w = new Uint32Array(64);
+  const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+  for (let off = 0; off < total; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + 4 * i);
+    for (let i = 16; i < 64; i++) {
+      const a = w[i - 15]!;
+      const b = w[i - 2]!;
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, k] = h as [number, number, number, number, number, number, number, number];
+    for (let i = 0; i < 64; i++) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (k + s1 + ch + K[i]! + w[i]!) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (s0 + maj) >>> 0;
+      k = g;
+      g = f;
+      f = e;
+      e = (d + t1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0]! + a) >>> 0;
+    h[1] = (h[1]! + b) >>> 0;
+    h[2] = (h[2]! + c) >>> 0;
+    h[3] = (h[3]! + d) >>> 0;
+    h[4] = (h[4]! + e) >>> 0;
+    h[5] = (h[5]! + f) >>> 0;
+    h[6] = (h[6]! + g) >>> 0;
+    h[7] = (h[7]! + k) >>> 0;
+  }
+  return h.map((x) => x.toString(16).padStart(8, "0")).join("");
+}
+
+/**
+ * This function gives the canonical form of a value: sorted keys and no whitespace, with the numbers of `JSON.stringify`.
+ * A key with the value `undefined` is not in the form. An `undefined` in an array becomes `null`.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map((v: unknown) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`;
+  const o = value as Record<string, unknown>;
+  const keys = Object.keys(o)
+    .filter((k) => o[k] !== undefined)
+    .sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+}
+
+/** The options of `outputHash` and `documentHash`. */
+export interface HashOptions {
+  /**
+   * The step of the grid of the numbers. The default is `RECORD_EPS`, so a number keeps 3 decimals.
+   * The value `0` keeps the exact numbers. A negative value or a value that is not finite causes a `RangeError`.
+   */
+  readonly grid?: number;
+}
+
+/** This function gives the factor of a grid: `1 / grid`, or `undefined` for the exact numbers. */
+function gridFactor(options: HashOptions): number | undefined {
+  const grid = options.grid ?? RECORD_EPS;
+  if (!Number.isFinite(grid) || grid < 0) throw new RangeError(`The grid ${grid} is not a finite number of 0 or more.`);
+  return grid === 0 ? undefined : 1 / grid;
+}
+
+/**
+ * This function gives a copy of a value with each number on the grid. The value `-0` becomes `0`.
+ * It throws a `RangeError` for a number that is not finite.
+ */
+function onGrid(value: unknown, path: string, k: number | undefined): unknown {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new RangeError(`The value has the number ${value} at ${path}. JSON has no form for it.`);
+    if (k === undefined) return value;
+    const r = Math.round(value * k) / k;
+    if (!Number.isFinite(r)) throw new RangeError(`The number at ${path} is too large for the grid.`);
+    return r === 0 ? 0 : r;
+  }
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((v: unknown, i) => onGrid(v, `${path}[${i}]`, k));
+  const o = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(o)) out[key] = onGrid(o[key], `${path}.${key}`, k);
+  return out;
+}
+
+/**
+ * This function gives the hash of an output: the first 16 hex characters of the SHA-256 of its canonical form.
+ * Before the canonical form, each number goes to the nearest point of the grid, and `-0` becomes `0`.
+ * With the default grid, the rounding is `round3` of `packing`: `Math.round(x * 1000) / 1000`.
+ * The function throws a `RangeError` for `NaN` and for an infinite number.
+ *
+ * The grid can split two outputs. Two numbers near a rounding boundary can go to two different points.
+ * The grid can also merge two outputs whose numbers go to the same points. This merge is intentional: it removes the noise of floating-point numbers.
+ */
+export function outputHash(value: unknown, options: HashOptions = {}): string {
+  return sha256Hex(canonicalJson(onGrid(value, "$", gridFactor(options)))).slice(0, 16);
+}
+
+/**
+ * This function gives the hash of a document. It uses the rule of `outputHash`, but the form does not include the field `hash` of the document.
+ * With the default grid, it is the input hash of `docs/FORMAT.md` of `packing`.
+ */
+export function documentHash(doc: object, options: HashOptions = {}): string {
+  const { hash: _hash, ...rest } = doc as { readonly hash?: unknown };
+  return outputHash(rest, options);
+}
+
+/** One output group: the candidates with the same output hash on each decision input. */
+export interface OutputGroup {
+  /** The id of the group: its first member. */
+  readonly id: string;
+  /** The ids of the candidates of the group, in sorted order. */
+  readonly members: readonly string[];
+}
+
+/**
+ * This function gives the output groups of the candidates. The key of `hashes` is the id of a candidate.
+ * Its value is the list of the output hashes of the candidate, in the order of the decision inputs.
+ * Candidates with equal lists make one group. The groups are in the order of their ids.
+ * The function throws a `RangeError` when two lists have different lengths.
+ */
+export function outputGroups(hashes: Readonly<Record<string, readonly string[]>>): OutputGroup[] {
+  const byList = new Map<string, string[]>();
+  let first: string | undefined;
+  for (const id of Object.keys(hashes)) {
+    const list = hashes[id]!;
+    if (first === undefined) first = id;
+    else if (list.length !== hashes[first]!.length)
+      throw new RangeError(`The candidate "${id}" has ${list.length} hashes, but "${first}" has ${hashes[first]!.length}.`);
+    const key = JSON.stringify(list);
+    const members = byList.get(key);
+    if (members) members.push(id);
+    else byList.set(key, [id]);
+  }
+  const groups = [...byList.values()].map((members): OutputGroup => {
+    const sorted = [...members].sort();
+    return { id: sorted[0]!, members: sorted };
+  });
+  return groups.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/** The evidence that a candidate is exercised on its decision inputs. */
+export interface ExerciseEvidence {
+  /** The move counts of the candidate, by name. A record keeps each one as the trace measure `move.<name>`. */
+  readonly moves?: Readonly<Record<string, number>>;
+  /** The output hashes of the candidate, in the order of the decision inputs. */
+  readonly hashes?: readonly string[];
+  /** The output hashes of the base of the candidate, in the same order. */
+  readonly baseHashes?: readonly string[];
+}
+
+/**
+ * This function tells if a candidate is exercised. It gives `true` when a move count is more than 0.
+ * It also gives `true` when `hashes` and `baseHashes` are different at one place or more.
+ * Without evidence, it gives `false`.
+ * The function throws a `RangeError` when only one of the two lists is given, or when their lengths are different.
+ */
+export function exercised(evidence: ExerciseEvidence): boolean {
+  const { moves, hashes, baseHashes } = evidence;
+  if ((hashes === undefined) !== (baseHashes === undefined)) throw new RangeError("The evidence must have both hashes and baseHashes, or neither of them.");
+  if (hashes && baseHashes && hashes.length !== baseHashes.length)
+    throw new RangeError(`The candidate has ${hashes.length} hashes, but its base has ${baseHashes.length}.`);
+  if (moves && Object.values(moves).some((n) => n > 0)) return true;
+  if (hashes && baseHashes) return hashes.some((h, i) => h !== baseHashes[i]);
+  return false;
+}

package/src/index.ts

@@ -9,3 +9,5 @@ export * from "./measures.ts";
 export * from "./strategy.ts";
 export * from "./random.ts";
 export * from "./edges.ts";
+export * from "./hash.ts";
+export * from "./portfolio.ts";

package/src/portfolio.ts

@@ -0,0 +1,300 @@
+import { outputHash } from "./hash.ts";
+import { compareMeasure, type MeasureSpec } from "./measures.ts";
+
+/** The part of a `MeasureSpec` that a pick uses: the direction and the `minEffect`. */
+export type PickSpec = Pick<MeasureSpec, "direction" | "minEffect">;
+
+/** A member of a portfolio: a function with an id. A portfolio is also a member. */
+export interface Member<I, O> {
+  readonly id: string;
+  /** This function gives the output of the member for an input. */
+  run(input: I): O;
+}
+
+/** One level of the key of a portfolio: a measure of an output. */
+export interface PortfolioLevel<I, O> {
+  /** The id of the level. The id `hard` is reserved. */
+  readonly id: string;
+  readonly spec: PickSpec;
+  /** This function gives the value of the measure for the output of a member. The value must be finite. */
+  value(input: I, output: O): number;
+}
+
+/** The key of a portfolio: the hard level, then the other levels in order. */
+export interface PortfolioKey<I, O> {
+  /** This function gives the count of hard breaks. It is level 0, with the direction `lower` and the `minEffect` 0. */
+  hard(input: I, output: O): number;
+  /** The levels after the hard level, in the order of the pick. */
+  readonly levels: readonly PortfolioLevel<I, O>[];
+  /** This function gives the hash of an output. The default is `outputHash` with the default grid. */
+  hash?(output: O): string;
+}
+
+/** The options of a portfolio. */
+export interface PortfolioOptions {
+  /** The time limit in milliseconds, 0 or more. The first member always starts. A member that starts always finishes. */
+  readonly budgetMs?: number;
+  /** The largest count of members that run, a whole number of 1 or more. The other members are cut. */
+  readonly maxMembers?: number;
+  /** The clock in milliseconds. The default is `performance.now`, or `Date.now` without `performance`. */
+  readonly now?: () => number;
+}
+
+/** The status of a member in a pick. */
+export type MemberStatus = "ran" | "cut" | "error";
+
+/** The trace of one member in a pick. */
+export interface MemberTrace {
+  readonly id: string;
+  readonly status: MemberStatus;
+  /** The value of each level, with the key `hard` for the hard level. Only a member with the status `ran` has values. */
+  readonly values?: Readonly<Record<string, number>>;
+  /** The time of the run of the member, in milliseconds. */
+  readonly ms?: number;
+  /** The hash of the output of the member. */
+  readonly outputHash?: string;
+  /** The message of the error of a member with the status `error`. */
+  readonly error?: string;
+}
+
+/** The trace of one pick of a portfolio. */
+export interface PortfolioTrace {
+  /** One entry for each member, in the order of the members. A cut member is also in the list. */
+  readonly members: readonly MemberTrace[];
+  readonly winner: string;
+  /** The index of the winner in the list of the members. */
+  readonly winnerIndex: number;
+  /** The value `true` tells that the winner is not member 0 and has a different output hash. */
+  readonly picked: boolean;
+  /** The time of the full pick, in milliseconds. */
+  readonly totalMs: number;
+  readonly budgetMs?: number;
+  readonly maxMembers?: number;
+  /** The count of the cut members. */
+  readonly cut: number;
+  /** The value `false` tells that the time limit cut one member or more. Then a run on a different computer can give a different pick. */
+  readonly deterministic: boolean;
+  /** The ids of the members that stay in after each level of `selectBest`. The first list is for the hard level. */
+  readonly kept: readonly (readonly string[])[];
+}
+
+/** The result of one pick of a portfolio: the output of the winner, its id and the trace. */
+export interface PortfolioPick<O> {
+  readonly output: O;
+  readonly winner: string;
+  readonly trace: PortfolioTrace;
+}
+
+/** A portfolio: a member that runs its members and gives the output of the best member. */
+export interface Portfolio<I, O> extends Member<I, O> {
+  /** This function starts the members on an input and gives the output of the winner with the trace. */
+  pick(input: I): PortfolioPick<O>;
+}
+
+/** A candidate of `selectBest`: an id and the value of each level. */
+export interface SelectCandidate {
+  readonly id: string;
+  readonly values: Readonly<Record<string, number>>;
+}
+
+/** A level of `selectBest`: the id of a value and its spec. */
+export interface SelectLevel {
+  readonly id: string;
+  readonly spec: PickSpec;
+}
+
+/** The result of `selectBest`. */
+export interface Selection {
+  readonly winner: string;
+  /** The ids of the candidates that stay in after each level, in the given order. */
+  readonly kept: readonly (readonly string[])[];
+}
+
+/**
+ * This function picks the best candidate. For each level, it finds the best value of the candidates that stay in.
+ * It keeps each candidate that is not worse than that best value by `compareMeasure`.
+ * The winner is the first candidate, in the given order, that stays in after the last level.
+ * Without levels, the winner is the first candidate and `kept` is empty.
+ *
+ * The reason for the rule: a scan that compares each candidate with the current winner is not transitive, because of the `minEffect` ties.
+ * Such a scan can drift away from the best value. An example: "a" is lower with the `minEffect` 0.005, and "b" is higher.
+ * The candidates A (0, 1), B (0.004, 2) and C (0.008, 3) give the winner B.
+ * The scan picks C, but A is better than C on "a".
+ *
+ * The function throws a `RangeError` for an empty list of candidates, for a missing value, and for a value that is not finite.
+ */
+export function selectBest(candidates: readonly SelectCandidate[], levels: readonly SelectLevel[]): Selection {
+  if (candidates.length === 0) throw new RangeError("selectBest: the list of candidates is empty.");
+  for (const level of levels) {
+    for (const c of candidates) {
+      const v = c.values[level.id];
+      if (typeof v !== "number") throw new RangeError(`selectBest: the candidate "${c.id}" has no value for the level "${level.id}".`);
+      if (!Number.isFinite(v)) throw new RangeError(`selectBest: the candidate "${c.id}" has the value ${v} for the level "${level.id}".`);
+    }
+  }
+  let alive: readonly SelectCandidate[] = candidates;
+  const kept: (readonly string[])[] = [];
+  for (const level of levels) {
+    const at = (c: SelectCandidate): number => c.values[level.id]!;
+    let best = at(alive[0]!);
+    for (const c of alive) best = level.spec.direction === "lower" ? Math.min(best, at(c)) : Math.max(best, at(c));
+    alive = alive.filter((c) => compareMeasure(at(c), best, level.spec) !== "worse");
+    kept.push(alive.map((c) => c.id));
+  }
+  return { winner: alive[0]!.id, kept };
+}
+
+/** This function gives the move `pick` of a pick: 1 when `picked` is true, else 0. A record keeps it as the trace measure `move.pick`. */
+export function pickMoves(trace: Pick<PortfolioTrace, "picked">): { pick: number } {
+  return { pick: trace.picked ? 1 : 0 };
+}
+
+/** This function gives the default clock: `performance.now`, or `Date.now` without `performance`. */
+function defaultClock(): () => number {
+  const perf = (globalThis as { readonly performance?: { now(): number } }).performance;
+  return perf ? () => perf.now() : () => Date.now();
+}
+
+/** This function gives the message of an error value. */
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** This function throws a `RangeError` for an empty list of members or for two members with the same id. */
+function checkMembers(id: string, members: readonly Member<unknown, unknown>[]): void {
+  if (members.length === 0) throw new RangeError(`The portfolio "${id}" has no members.`);
+  const seen = new Set<string>();
+  for (const m of members) {
+    if (seen.has(m.id)) throw new RangeError(`The portfolio "${id}" has two members with the id "${m.id}".`);
+    seen.add(m.id);
+  }
+}
+
+/** The result of the run of one member. */
+type Ran<O> = { readonly ok: true; readonly output: O; readonly values: Record<string, number>; readonly hash: string } | { readonly ok: false; readonly error: unknown };
+
+/**
+ * This function makes a portfolio. Its `pick` starts the members in their order. `selectBest` picks the winner of the members with the status `ran`.
+ * The first level is the hard level, then the levels of the key follow.
+ * `members` is a list, or a function of the input that gives the list.
+ *
+ * A member that throws, or that gives a value that is not finite, gets the status `error`. It does not win.
+ * When each member has an error, `pick` throws the error of the first member.
+ * `docs/PORTFOLIO.md` tells the rules of the time limit, the trace and `picked`.
+ *
+ * The function throws a `RangeError` for a level with the id `hard`, for two levels with the same id and for a bad option.
+ * It also throws a `RangeError` for an empty list of members, or for two members with the same id.
+ */
+export function portfolio<I, O>(
+  id: string,
+  members: readonly Member<I, O>[] | ((input: I) => readonly Member<I, O>[]),
+  key: PortfolioKey<I, O>,
+  options: PortfolioOptions = {},
+): Portfolio<I, O> {
+  const levelIds = new Set<string>();
+  for (const level of key.levels) {
+    if (level.id === "hard") throw new RangeError(`The portfolio "${id}" has a level with the reserved id "hard".`);
+    if (levelIds.has(level.id)) throw new RangeError(`The portfolio "${id}" has two levels with the id "${level.id}".`);
+    levelIds.add(level.id);
+  }
+  const { budgetMs, maxMembers } = options;
+  if (budgetMs !== undefined && !(budgetMs >= 0)) throw new RangeError(`The portfolio "${id}" has the budgetMs ${budgetMs}. It must be 0 or more.`);
+  if (maxMembers !== undefined && !(Number.isInteger(maxMembers) && maxMembers >= 1))
+    throw new RangeError(`The portfolio "${id}" has the maxMembers ${maxMembers}. It must be a whole number of 1 or more.`);
+  if (typeof members !== "function") checkMembers(id, members);
+  const levels: readonly SelectLevel[] = [{ id: "hard", spec: { direction: "lower", minEffect: 0 } }, ...key.levels.map((l) => ({ id: l.id, spec: l.spec }))];
+  const now = options.now ?? defaultClock();
+
+  const evaluate = (m: Member<I, O>, input: I, output: O): Ran<O> => {
+    const values: Record<string, number> = {};
+    const measure = (level: string, f: () => number): void => {
+      let v: number;
+      try {
+        v = f();
+      } catch (e) {
+        throw new RangeError(`The level "${level}" of the member "${m.id}" of the portfolio "${id}" throws: ${messageOf(e)}`, { cause: e });
+      }
+      if (typeof v !== "number" || !Number.isFinite(v))
+        throw new RangeError(`The member "${m.id}" of the portfolio "${id}" has the value ${v} for the level "${level}".`);
+      values[level] = v;
+    };
+    try {
+      measure("hard", () => key.hard(input, output));
+      for (const level of key.levels) measure(level.id, () => level.value(input, output));
+      let hash: string;
+      try {
+        hash = key.hash ? key.hash(output) : outputHash(output);
+      } catch (e) {
+        throw new RangeError(`The hash of the member "${m.id}" of the portfolio "${id}" throws: ${messageOf(e)}`, { cause: e });
+      }
+      return { ok: true, output, values, hash };
+    } catch (e) {
+      return { ok: false, error: e };
+    }
+  };
+
+  const pick = (input: I): PortfolioPick<O> => {
+    const list = typeof members === "function" ? members(input) : members;
+    if (typeof members === "function") checkMembers(id, list);
+    const start = now();
+    const traces: MemberTrace[] = [];
+    const outputs = new Map<string, O>();
+    const ran: SelectCandidate[] = [];
+    let firstError: { readonly error: unknown } | undefined;
+    let cut = 0;
+    let outOfTime = false;
+    for (let i = 0; i < list.length; i++) {
+      const m = list[i]!;
+      if (maxMembers !== undefined && i >= maxMembers) {
+        traces.push({ id: m.id, status: "cut" });
+        cut++;
+        continue;
+      }
+      if (i > 0 && budgetMs !== undefined && (outOfTime || now() - start >= budgetMs)) {
+        outOfTime = true;
+        traces.push({ id: m.id, status: "cut" });
+        cut++;
+        continue;
+      }
+      const t0 = now();
+      let result: Ran<O>;
+      let ms: number;
+      try {
+        const output = m.run(input);
+        ms = now() - t0;
+        result = evaluate(m, input, output);
+      } catch (e) {
+        ms = now() - t0;
+        result = { ok: false, error: e };
+      }
+      if (result.ok) {
+        traces.push({ id: m.id, status: "ran", values: result.values, ms, outputHash: result.hash });
+        outputs.set(m.id, result.output);
+        ran.push({ id: m.id, values: result.values });
+      } else {
+        traces.push({ id: m.id, status: "error", ms, error: messageOf(result.error) });
+        firstError ??= { error: result.error };
+      }
+    }
+    if (ran.length === 0) throw firstError!.error;
+    const { winner, kept } = selectBest(ran, levels);
+    const winnerIndex = traces.findIndex((t) => t.id === winner);
+    const base = traces[0]!;
+    const picked = winnerIndex > 0 && (base.status !== "ran" || traces[winnerIndex]!.outputHash !== base.outputHash);
+    const trace: PortfolioTrace = {
+      members: traces,
+      winner,
+      winnerIndex,
+      picked,
+      totalMs: now() - start,
+      ...(budgetMs !== undefined ? { budgetMs } : {}),
+      ...(maxMembers !== undefined ? { maxMembers } : {}),
+      cut,
+      deterministic: !outOfTime,
+      kept,
+    };
+    return { output: outputs.get(winner)!, winner, trace };
+  };
+
+  return { id, pick, run: (input: I): O => pick(input).output };
+}

package/src/random.ts

@@ -1,3 +1,5 @@
+import { utf8 } from "./utf8.ts";
+
 /** This function gives a generator of random numbers in [0, 1). It is `mulberry32`, as in `docs/FORMAT.md` of `packing`. */
 export function mulberry32(seed: number): () => number {
   let s = seed >>> 0;
@@ -16,19 +18,6 @@ export function fnv1a32(text: string): number {
   return h;
 }
 
-/** The UTF-8 bytes of a string. The package has no runtime dependencies, thus it does not use `TextEncoder`. */
-function utf8(text: string): number[] {
-  const bytes: number[] = [];
-  for (const ch of text) {
-    const c = ch.codePointAt(0)!;
-    if (c < 0x80) bytes.push(c);
-    else if (c < 0x800) bytes.push(0xc0 | (c >> 6), 0x80 | (c & 63));
-    else if (c < 0x10000) bytes.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
-    else bytes.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
-  }
-  return bytes;
-}
-
 /** This function gives the generator of one step of a seeded generator: `mulberry32(fnv1a32("<seed>:<step>"))`. */
 export function stepRandom(seed: number, step: string): () => number {
   return mulberry32(fnv1a32(`${seed}:${step}`));

package/src/utf8.ts

@@ -0,0 +1,12 @@
+/** This function gives the UTF-8 bytes of a string. The package has no runtime dependencies, thus it does not use `TextEncoder`. */
+export function utf8(text: string): number[] {
+  const bytes: number[] = [];
+  for (const ch of text) {
+    const c = ch.codePointAt(0)!;
+    if (c < 0x80) bytes.push(c);
+    else if (c < 0x800) bytes.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+    else if (c < 0x10000) bytes.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    else bytes.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+  }
+  return bytes;
+}