@mark1russell7/netdiag 0.0.0-stage → 0.1.1

package/src/diagnosis/model.ts

@@ -0,0 +1,322 @@
+import { err, ok, type Result } from "@mark1russell7/optional";
+import type { Layer } from "../layer.ts";
+
+/** A probability for each value of a feature. The probabilities are more than 0, and their sum is 1. */
+export type Distribution = Readonly<Record<string, number>>;
+
+/**
+ * A feature is one discrete observation that the facts give, for example the outcome of a TCP connect.
+ *
+ * The distribution `healthy` gives the probability of each value when the network has no fault.
+ */
+export interface Feature {
+  readonly id: string;
+  readonly layer: Layer;
+  readonly summary: string;
+  readonly values: readonly string[];
+  readonly healthy: Distribution;
+}
+
+/** The parts of the model. Each fault is in one part. */
+export const PARTS = ["interface", "wifi", "gateway", "resolver", "path", "service"] as const;
+
+/** A part of the model: the network interface, the Wi-Fi link, the gateway, the DNS resolver, the path or the remote service. */
+export type Part = (typeof PARTS)[number];
+
+/**
+ * The reach of a fault.
+ *
+ * - `shared`: the fault changes the observations of each host, for example a TLS proxy of the local network.
+ * - `target`: the fault changes only the observations of the primary target, for example a slow server.
+ */
+export type Reach = "shared" | "target";
+
+/**
+ * The strength of a prediction. The rules of practice use these strengths. The lab runs then replace them with fitted
+ * distributions.
+ */
+export type Strength = "sure" | "strong" | "usual" | "weak";
+
+/** The probability that each strength gives to the expected values together. */
+export const STRENGTHS: Readonly<Record<Strength, number>> = { sure: 0.98, strong: 0.9, usual: 0.75, weak: 0.6 };
+
+/**
+ * A prediction of a fault for one feature: a full distribution, or the expected values and a strength.
+ *
+ * With `expect`, the expected values share the probability of the strength equally. The other values share the rest.
+ */
+export type Prediction = Distribution | Expectation;
+
+/** The expected values of a feature, and the strength of the prediction. */
+export interface Expectation {
+  readonly expect: string | readonly string[];
+  readonly strength: Strength;
+}
+
+function isExpectation(prediction: Prediction): prediction is Expectation {
+  return typeof prediction.strength === "string";
+}
+
+/**
+ * A fault of the catalog.
+ *
+ * The fault predicts a distribution for each feature that it changes. For each other feature, it predicts the
+ * distribution `healthy` of the feature. The prior is a relative weight. The default prior is 1.
+ */
+export interface Fault {
+  readonly id: string;
+  readonly part: Part;
+  readonly reach: Reach;
+  /** The cause in plain words, for example "No program listens on the port." */
+  readonly summary: string;
+  /** The next step for the user in plain words. */
+  readonly step: string;
+  readonly prior?: number | undefined;
+  readonly predicts: Readonly<Record<string, Prediction>>;
+}
+
+/** The data of a catalog: the features, the faults, and the priors of the hypotheses "no fault" and "unknown cause". */
+export interface CatalogSpec {
+  readonly version: string;
+  readonly features: readonly Feature[];
+  readonly faults: readonly Fault[];
+  readonly priors?: { readonly none?: number | undefined; readonly unknown?: number | undefined } | undefined;
+}
+
+/**
+ * A hypothesis of the model.
+ *
+ * - `none`: the network has no fault.
+ * - `fault`: one fault of the catalog.
+ * - `unknown`: a cause that the catalog does not have. It gives each value of a feature the same probability.
+ */
+export interface Hypothesis {
+  readonly id: string;
+  readonly kind: "none" | "fault" | "unknown";
+  readonly summary: string;
+  readonly step: string;
+  readonly part?: Part | undefined;
+  readonly reach?: Reach | undefined;
+}
+
+/** The id of the hypothesis "no fault". */
+export const NONE = "none";
+/** The id of the hypothesis "unknown cause". */
+export const UNKNOWN = "unknown";
+
+/** A catalog with each distribution in its full form, and the logarithms of the probabilities. */
+export interface Catalog {
+  readonly version: string;
+  readonly features: ReadonlyMap<string, Feature>;
+  readonly hypotheses: readonly Hypothesis[];
+  /** This function gives the probability of a value of a feature under a hypothesis, for a primary or a reference host. */
+  likelihood(hypothesis: string, feature: string, value: string, primary: boolean): number;
+  prior(hypothesis: string): number;
+}
+
+/** The lowest probability of a value. With a probability of 0, one wrong observation removes a cause. */
+export const FLOOR = 0.001;
+
+const SUM_TOLERANCE = 1e-9;
+
+function distributionProblems(where: string, feature: Feature, dist: Distribution): string[] {
+  const problems: string[] = [];
+  for (const value of Object.keys(dist)) if (!feature.values.includes(value)) problems.push(`${where}: "${value}" is not a value of ${feature.id}.`);
+  for (const value of feature.values) {
+    const p = dist[value];
+    if (p === undefined) problems.push(`${where}: the value "${value}" of ${feature.id} has no probability.`);
+    else if (!Number.isFinite(p) || p < FLOOR) problems.push(`${where}: the probability of "${value}" is ${p}. It must be ${FLOOR} or more.`);
+  }
+  const sum = Object.values(dist).reduce((a, b) => a + b, 0);
+  if (Math.abs(sum - 1) > SUM_TOLERANCE) problems.push(`${where}: the sum of the probabilities is ${sum}, not 1.`);
+  return problems;
+}
+
+/** This function gives the full distribution of a prediction, or the problems of the prediction. */
+export function expand(feature: Feature, prediction: Prediction): Result<Distribution, string[]> {
+  if (!isExpectation(prediction)) return ok(prediction);
+  const expected = typeof prediction.expect === "string" ? [prediction.expect] : [...prediction.expect];
+  const unknown = expected.filter((value) => !feature.values.includes(value));
+  if (unknown.length > 0) return err(unknown.map((value) => `"${value}" is not a value of ${feature.id}.`));
+  if (expected.length === 0 || new Set(expected).size !== expected.length) return err([`The expected values of ${feature.id} are empty or repeated.`]);
+  const others = feature.values.filter((value) => !expected.includes(value));
+  const mass = others.length === 0 ? 1 : STRENGTHS[prediction.strength];
+  const dist: Record<string, number> = {};
+  for (const value of expected) dist[value] = mass / expected.length;
+  for (const value of others) dist[value] = (1 - mass) / others.length;
+  return ok(dist);
+}
+
+const ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+
+/**
+ * This function examines a catalog and makes its tables.
+ *
+ * It refuses a repeated id, an unknown feature or value, a probability below `FLOOR`, and a distribution with a sum that is not 1.
+ */
+export function compileCatalog(spec: CatalogSpec): Result<Catalog, string[]> {
+  const problems: string[] = [];
+  const features = new Map<string, Feature>();
+  for (const feature of spec.features) {
+    if (!ID.test(feature.id)) problems.push(`"${feature.id}" is not a valid feature id.`);
+    if (features.has(feature.id)) problems.push(`The feature ${feature.id} is repeated.`);
+    if (feature.values.length < 2 || new Set(feature.values).size !== feature.values.length) {
+      problems.push(`The feature ${feature.id} must have two or more different values.`);
+    }
+    problems.push(...distributionProblems(`healthy of ${feature.id}`, feature, feature.healthy));
+    features.set(feature.id, feature);
+  }
+  const hypotheses: Hypothesis[] = [{ id: NONE, kind: "none", summary: "The network has no fault.", step: "No step is necessary." }];
+  const priors = new Map<string, number>([[NONE, spec.priors?.none ?? 1]]);
+  const tables = new Map<string, Map<string, Distribution>>();
+  for (const fault of spec.faults) {
+    if (!ID.test(fault.id) || fault.id === NONE || fault.id === UNKNOWN) problems.push(`"${fault.id}" is not a valid fault id.`);
+    if (priors.has(fault.id)) problems.push(`The fault ${fault.id} is repeated.`);
+    priors.set(fault.id, fault.prior ?? 1);
+    hypotheses.push({ id: fault.id, kind: "fault", summary: fault.summary, step: fault.step, part: fault.part, reach: fault.reach });
+    const table = new Map<string, Distribution>();
+    for (const [featureId, prediction] of Object.entries(fault.predicts)) {
+      const feature = features.get(featureId);
+      if (feature === undefined) {
+        problems.push(`The fault ${fault.id} predicts the unknown feature ${featureId}.`);
+        continue;
+      }
+      const dist = expand(feature, prediction);
+      if (dist.tag === "err") problems.push(...dist.error.map((problem) => `${fault.id}: ${problem}`));
+      else {
+        problems.push(...distributionProblems(`${fault.id} for ${featureId}`, feature, dist.value));
+        table.set(featureId, dist.value);
+      }
+    }
+    if (table.size === 0) problems.push(`The fault ${fault.id} predicts no feature.`);
+    tables.set(fault.id, table);
+  }
+  hypotheses.push({
+    id: UNKNOWN,
+    kind: "unknown",
+    summary: "The catalog does not have the cause.",
+    step: "Collect more facts, and report the facts as a new fault of the catalog.",
+  });
+  priors.set(UNKNOWN, spec.priors?.unknown ?? 1);
+  for (const [id, prior] of priors) if (!Number.isFinite(prior) || prior <= 0) problems.push(`The prior of ${id} is ${prior}. It must be more than 0.`);
+  if (problems.length > 0) return err(problems);
+
+  const total = [...priors.values()].reduce((a, b) => a + b, 0);
+  const reach = new Map(hypotheses.map((h) => [h.id, h.reach]));
+  return ok({
+    version: spec.version,
+    features,
+    hypotheses,
+    prior: (hypothesis) => (priors.get(hypothesis) ?? 0) / total,
+    likelihood(hypothesis, featureId, value, primary) {
+      const feature = features.get(featureId);
+      if (feature === undefined || !feature.values.includes(value)) return Number.NaN;
+      if (hypothesis === UNKNOWN) return 1 / feature.values.length;
+      const fault = tables.get(hypothesis);
+      const changed = fault?.get(featureId);
+      const applies = primary || reach.get(hypothesis) === "shared";
+      return (applies && changed !== undefined ? changed : feature.healthy)[value] ?? Number.NaN;
+    },
+  });
+}
+
+/**
+ * One observation of a feature.
+ *
+ * `primary` tells if the observation is of the primary target or of a reference host. `facts` gives the ids of the facts
+ * that gave the observation, for the explanation.
+ */
+export interface Evidence {
+  readonly feature: string;
+  readonly value: string;
+  readonly primary: boolean;
+  readonly facts?: readonly string[] | undefined;
+}
+
+/** A cause with its probability. */
+export interface Cause extends Hypothesis {
+  readonly probability: number;
+}
+
+/** The result of a diagnosis: the causes from the most probable, and the evidence that the model did not use, with the reason. */
+export interface Diagnosis {
+  readonly causes: readonly Cause[];
+  readonly used: readonly Evidence[];
+  readonly ignored: readonly { readonly evidence: Evidence; readonly reason: string }[];
+}
+
+function usable(catalog: Catalog, evidence: readonly Evidence[]): Pick<Diagnosis, "used" | "ignored"> {
+  const used: Evidence[] = [];
+  const ignored: { evidence: Evidence; reason: string }[] = [];
+  for (const item of evidence) {
+    const feature = catalog.features.get(item.feature);
+    if (feature === undefined) ignored.push({ evidence: item, reason: `The catalog has no feature ${item.feature}.` });
+    else if (!feature.values.includes(item.value)) ignored.push({ evidence: item, reason: `"${item.value}" is not a value of ${item.feature}.` });
+    else used.push(item);
+  }
+  return { used, ignored };
+}
+
+/**
+ * This function gives the probability of each hypothesis from the evidence, with the rule of Bayes.
+ *
+ * The model takes the observations as independent for a given hypothesis. The calculation uses logarithms, so a long
+ * list of evidence does not go to zero. The order of the evidence does not change the result.
+ * An exact tie keeps the order of the catalog, with "no fault" first.
+ */
+export function diagnose(catalog: Catalog, evidence: readonly Evidence[]): Diagnosis {
+  const { used, ignored } = usable(catalog, evidence);
+  const logs = catalog.hypotheses.map((h) => {
+    let sum = Math.log(catalog.prior(h.id));
+    for (const item of used) sum += Math.log(catalog.likelihood(h.id, item.feature, item.value, item.primary));
+    return sum;
+  });
+  const top = Math.max(...logs);
+  const weights = logs.map((log) => Math.exp(log - top));
+  const total = weights.reduce((a, b) => a + b, 0);
+  // An exact tie keeps the order of the catalog: "no fault" first, then the faults, then "unknown cause". Thus a fault
+  // whose features are not observed does not come before "no fault".
+  const causes = catalog.hypotheses
+    .map((h, i) => ({ ...h, probability: (weights[i] ?? 0) / total, order: i }))
+    .sort((a, b) => b.probability - a.probability || a.order - b.order)
+    .map(({ order: _order, ...cause }) => cause);
+  return { causes, used, ignored };
+}
+
+/** The part of one observation in the comparison of two hypotheses. */
+export interface Contribution {
+  readonly evidence: Evidence;
+  /** The ratio of the likelihoods of the two hypotheses, as a base-10 logarithm. 1 is a factor of 10 for the first hypothesis. */
+  readonly weight: number;
+}
+
+/**
+ * This function tells why the model prefers one hypothesis to a second hypothesis.
+ *
+ * It gives each observation with its weight, from the largest weight in absolute value. The default second hypothesis is
+ * "no fault".
+ */
+export function explain(catalog: Catalog, evidence: readonly Evidence[], hypothesis: string, versus: string = NONE): Contribution[] {
+  const { used } = usable(catalog, evidence);
+  return used
+    .map((item) => ({
+      evidence: item,
+      weight: Math.log10(catalog.likelihood(hypothesis, item.feature, item.value, item.primary)) -
+        Math.log10(catalog.likelihood(versus, item.feature, item.value, item.primary)),
+    }))
+    .sort((a, b) => Math.abs(b.weight) - Math.abs(a.weight));
+}
+
+/**
+ * This function gives the probability of each value of a feature that is not observed yet, from the probabilities of
+ * the causes. The choice of the next probe uses it.
+ */
+export function predictive(catalog: Catalog, diagnosis: Diagnosis, feature: string, primary: boolean): Distribution {
+  const known = catalog.features.get(feature);
+  if (known === undefined) throw new RangeError(`The catalog has no feature ${feature}`);
+  const dist: Record<string, number> = {};
+  for (const value of known.values) {
+    dist[value] = diagnosis.causes.reduce((sum, cause) => sum + cause.probability * catalog.likelihood(cause.id, feature, value, primary), 0);
+  }
+  return dist;
+}

package/src/diagnosis/score.ts

@@ -0,0 +1,160 @@
+import { err, ok, type Result } from "@mark1russell7/optional";
+import { type ClassScore, type Confusion, type Proportion, brier, classScores, confusion, wilson } from "@mark1russell7/rigor-statistics";
+import type { Catalog, Diagnosis } from "./model.ts";
+
+/** The format of a lab record. */
+export const LAB_RECORD_FORMAT = "netdiag.lab-record/1";
+
+/** The probability that a diagnosis gives to one cause. */
+export interface LabCause {
+  readonly id: string;
+  readonly probability: number;
+}
+
+/** One run of a lab case: the hypothesis that the lab made true, and the diagnosis of netdiag. */
+export interface LabRecord {
+  readonly format: typeof LAB_RECORD_FORMAT;
+  /** The id of the case, for example `tls.cert-invalid/expired`. */
+  readonly case: string;
+  /** The version of the catalog that gave the diagnosis. */
+  readonly catalog: string;
+  /** The hypothesis that the lab made true: a fault of the catalog, `none` or `unknown`. */
+  readonly truth: string;
+  /** The most probable cause of the diagnosis. */
+  readonly predicted: string;
+  /** The rank of the truth in the causes, from 1. */
+  readonly rank: number;
+  /** The probability of each cause, from the most probable. */
+  readonly causes: readonly LabCause[];
+}
+
+/**
+ * This function makes the record of one run of a lab case. The truth must be a hypothesis of the catalog, and the
+ * diagnosis must have a cause.
+ */
+export function labRecordOf(catalog: Catalog, caseId: string, truth: string, diagnosis: Diagnosis): Result<LabRecord, string> {
+  if (!catalog.hypotheses.some((hypothesis) => hypothesis.id === truth)) return err(`The truth "${truth}" is not a hypothesis of the catalog ${catalog.version}.`);
+  const first = diagnosis.causes[0];
+  if (first === undefined) return err("The diagnosis has no cause.");
+  const index = diagnosis.causes.findIndex((cause) => cause.id === truth);
+  if (index < 0) return err(`The diagnosis has no cause "${truth}".`);
+  return ok({
+    format: LAB_RECORD_FORMAT,
+    case: caseId,
+    catalog: catalog.version,
+    truth,
+    predicted: first.id,
+    rank: index + 1,
+    causes: diagnosis.causes.map((cause) => ({ id: cause.id, probability: cause.probability })),
+  });
+}
+
+/** The scores of the lab records of one catalog. */
+export interface LabScore {
+  /** The version of the catalog. */
+  readonly catalog: string;
+  /** The number of records. */
+  readonly n: number;
+  /** The number of records where the predicted cause is the truth. */
+  readonly correct: number;
+  /** The Wilson interval of the part of the records where the predicted cause is the truth. */
+  readonly accuracy: Proportion;
+  /** The confusion table. It has a row for each hypothesis of the catalog, in the order of the catalog. */
+  readonly table: Confusion<string>;
+  /** The scores of each hypothesis, in the order of the catalog. */
+  readonly classes: readonly ClassScore<string>[];
+  /** The mean Brier score of the records: the squared distance of the probabilities from the truth, from 0 to 2. */
+  readonly brier: number | undefined;
+}
+
+/**
+ * This function scores the lab records of one catalog. The recall of a hypothesis is the part of its runs where the
+ * diagnosis names it. A record of a different catalog version, or with a hypothesis that is not in the catalog, is an error.
+ */
+export function scoreLab(catalog: Catalog, records: readonly LabRecord[]): Result<LabScore, string[]> {
+  const ids = catalog.hypotheses.map((hypothesis) => hypothesis.id);
+  const known = new Set(ids);
+  const problems: string[] = [];
+  records.forEach((record, i) => {
+    const name = `Record ${i} (${record.case})`;
+    if (record.format !== LAB_RECORD_FORMAT) problems.push(`${name} has the format "${String(record.format)}", not "${LAB_RECORD_FORMAT}".`);
+    if (record.catalog !== catalog.version) problems.push(`${name} comes from the catalog ${record.catalog}, not ${catalog.version}.`);
+    for (const id of new Set([record.truth, record.predicted, ...record.causes.map((cause) => cause.id)])) {
+      if (!known.has(id)) problems.push(`${name} names "${id}", which is not a hypothesis of the catalog.`);
+    }
+  });
+  if (problems.length > 0) return err(problems);
+  const table = confusion(
+    records.map((record) => record.truth),
+    records.map((record) => record.predicted),
+    ids,
+  );
+  const forecasts = records.flatMap((record) => {
+    const probability = new Map(record.causes.map((cause) => [cause.id, cause.probability]));
+    return ids.map((id) => ({ p: probability.get(id) ?? 0, hit: id === record.truth }));
+  });
+  return ok({
+    catalog: catalog.version,
+    n: table.n,
+    correct: table.correct,
+    accuracy: wilson(table.correct, table.n),
+    table,
+    classes: classScores(table),
+    brier: records.length === 0 ? undefined : brier(forecasts) * ids.length,
+  });
+}
+
+/** The least lower end of the Wilson interval of the recall, for each hypothesis that the gate holds. */
+export type LabBars = Readonly<Record<string, number>>;
+
+/** The verdict of the gate on one hypothesis: `no-read` when no record has it as the truth. */
+export type LabStatus = "pass" | "fail" | "no-read";
+
+/** The verdict of the gate on one hypothesis. */
+export interface LabVerdict {
+  readonly hypothesis: string;
+  readonly status: LabStatus;
+  /** The bar of the hypothesis. */
+  readonly bar: number;
+  /** The lower end of the recall interval. It is `undefined` when no record has the hypothesis as the truth. */
+  readonly low: number | undefined;
+  /** The number of records with the hypothesis as the truth. */
+  readonly support: number;
+}
+
+/** The result of the accuracy gate. */
+export interface LabGate {
+  /** It is `true` only when each verdict is `pass`. A hypothesis with no read does not pass. */
+  readonly pass: boolean;
+  /** The verdicts, in the order of the catalog. */
+  readonly verdicts: readonly LabVerdict[];
+  /** The hypotheses with no bar, for example a fault that no lab can make. */
+  readonly unbarred: readonly string[];
+}
+
+/**
+ * This function holds the recall of each hypothesis with a bar. A hypothesis passes when the lower end of its
+ * recall interval is the bar or more. A bar for a hypothesis that is not in the score is an error.
+ */
+export function labGate(score: LabScore, bars: LabBars): Result<LabGate, string[]> {
+  const problems: string[] = [];
+  const labels = new Set(score.table.labels);
+  for (const [hypothesis, bar] of Object.entries(bars)) {
+    if (!labels.has(hypothesis)) problems.push(`The bar of "${hypothesis}" is not for a hypothesis of the catalog ${score.catalog}.`);
+    if (!(bar >= 0 && bar <= 1)) problems.push(`The bar of "${hypothesis}" is ${bar}. A bar is from 0 to 1.`);
+  }
+  if (problems.length > 0) return err(problems);
+  const verdicts: LabVerdict[] = [];
+  const unbarred: string[] = [];
+  for (const scores of score.classes) {
+    const bar = bars[scores.label];
+    if (bar === undefined) {
+      unbarred.push(scores.label);
+      continue;
+    }
+    const low = scores.support === 0 ? undefined : scores.recallInterval.low;
+    const status: LabStatus = low === undefined ? "no-read" : low >= bar ? "pass" : "fail";
+    verdicts.push({ hypothesis: scores.label, status, bar, low, support: scores.support });
+  }
+  return ok({ pass: verdicts.length > 0 && verdicts.every((verdict) => verdict.status === "pass"), verdicts, unbarred });
+}

package/src/fact.ts

@@ -0,0 +1,87 @@
+import type { Layer } from "./layer.ts";
+import type { Target } from "./target.ts";
+
+/**
+ * The time of a fact, in milliseconds on the monotonic clock of the runner.
+ *
+ * The field `origin` of the runner gives the wall-clock time of one monotonic time. Thus each fact time has a wall-clock time.
+ */
+export interface FactTime {
+  readonly start: number;
+  readonly end: number;
+}
+
+/** The source of a fact: the probe and its version, and the outside tool when the probe starts one. */
+export interface FactSource {
+  readonly probe: string;
+  readonly version: string;
+  readonly tool?: string | undefined;
+}
+
+/**
+ * A typed fact of one layer of the network stack.
+ *
+ * A fact has a layer, a time, a source and a value. Its kind names the type of its value, for example `tcp.connect`.
+ * The subject is the target of the fact. A fact is plain data, so a record of facts is JSON.
+ */
+export interface Fact<V = unknown> {
+  /** The id is unique in the facts of one runner, for example `f12`. */
+  readonly id: string;
+  readonly kind: string;
+  readonly layer: Layer;
+  readonly subject: Target;
+  readonly time: FactTime;
+  readonly source: FactSource;
+  readonly value: V;
+}
+
+/**
+ * The definition of a kind of fact: its name, its layer and the check of its value.
+ *
+ * The check is the contract of the value. The runner refuses a value that does not pass it, thus each fact of a kind has a
+ * value of the type `V`.
+ */
+export interface FactKind<V> {
+  readonly kind: string;
+  readonly layer: Layer;
+  readonly summary: string;
+  readonly check: (value: unknown) => value is V;
+}
+
+/** The value type of a fact kind. */
+export type ValueOf<K> = K extends FactKind<infer V> ? V : never;
+
+const KIND_NAME = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+
+/** This function makes a fact kind. The name has lower-case words with dots, for example `tls.handshake`. */
+export function defineFactKind<V>(spec: FactKind<V>): FactKind<V> {
+  if (!KIND_NAME.test(spec.kind)) throw new RangeError(`"${spec.kind}" is not a valid name of a fact kind`);
+  return Object.freeze({ ...spec });
+}
+
+/** This function tells if a fact is of a kind, and if its value passes the check of the kind. */
+export function isFactOf<V>(kind: FactKind<V>, fact: Fact): fact is Fact<V> {
+  return fact.kind === kind.kind && fact.layer === kind.layer && kind.check(fact.value);
+}
+
+/** This function gives the facts of one kind, in their order. */
+export function factsOf<V>(kind: FactKind<V>, facts: readonly Fact[]): Fact<V>[] {
+  return facts.filter((fact): fact is Fact<V> => isFactOf(kind, fact));
+}
+
+/**
+ * An observation is a fact that a probe parsed, before the runner gives it an id, a layer and a source.
+ *
+ * The time is optional. Without a time, the fact gets the time of the run of the probe.
+ */
+export interface Observation<V = unknown> {
+  readonly kind: FactKind<V>;
+  readonly subject: Target;
+  readonly value: V;
+  readonly time?: FactTime | undefined;
+}
+
+/** This function makes an observation with a type check of its value against its kind. */
+export function observe<V>(kind: FactKind<V>, subject: Target, value: V, time?: FactTime): Observation<V> {
+  return time === undefined ? { kind, subject, value } : { kind, subject, value, time };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+export { LAYERS, isLayer, layerRank, type Layer } from "./layer.ts";
+export { canonicalHost, formatTarget, hostKind, parseTarget, sameTarget, target, type HostKind, type Target } from "./target.ts";
+export {
+  defineFactKind,
+  factsOf,
+  isFactOf,
+  observe,
+  type Fact,
+  type FactKind,
+  type FactSource,
+  type FactTime,
+  type Observation,
+  type ValueOf,
+} from "./fact.ts";
+export { defineProbe, type Availability, type Probe, type ProbeContext, type ProbeMode } from "./probe.ts";
+export {
+  DEFAULT_MAX_PORTS_PER_HOST,
+  decideScope,
+  grantProblems,
+  namedGrant,
+  resolvedGrant,
+  scopeOf,
+  widen,
+  type Grant,
+  type GrantBasis,
+  type HostGrant,
+  type PortLedger,
+  type RangeGrant,
+  type Scope,
+  type ScopeDecision,
+} from "./scope.ts";
+export { createRunner, type ClockOrigin, type ProbeOutcome, type Runner, type RunnerOptions } from "./run.ts";
+export * from "./address/index.ts";
+export * from "./diagnosis/index.ts";
+export * from "./kinds.ts";
+export {
+  DEFAULT_MAX_BYTES,
+  DNS_PROBE,
+  HTTP_PROBE,
+  TCP_PROBE,
+  TLS_PROBE,
+  dnsOutcome,
+  httpProbe,
+  tcpProbe,
+  tlsProbe,
+  type DnsInput,
+  type DnsRaw,
+  type HttpInput,
+  type HttpRaw,
+  type TcpInput,
+  type TcpRaw,
+  type TlsInput,
+  type TlsProbeOptions,
+  type TlsRaw,
+} from "./probes/native.ts";
+export {
+  DEFAULT_TIMEOUT_MS,
+  KEPT_FIELDS,
+  certProblem,
+  connectOutcome,
+  handshakeOutcome,
+  type ConnectOptions,
+  type Dial,
+  type HttpPhase,
+  type TcpPhase,
+  type TlsPhase,
+} from "./probes/socket.ts";
+export * from "./readers.ts";