@openshain/core 0.4.1 → 0.5.0

package/src/knowledge/build.ts

@@ -0,0 +1,349 @@
+import { createHash } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readWorkspaceTextIfAny } from "../tool/files.ts";
+import type { Checked } from "./check.ts";
+import { KNOWLEDGE_DIR_NAME } from "./check.ts";
+import type { LoadedRule, Scope, Source } from "./schema.ts";
+import { readKnowledgeFile, writeKnowledgeFile } from "./store.ts";
+
+/**
+ * Turning what a person wrote into the index the runtime serves. The index is a build artifact:
+ * the same input always makes the same bytes, and the manifest says which input it came from and
+ * what the index itself hashes to, so a rewritten index is not served.
+ */
+
+/** Raised when the index is read by a runtime that indexes differently than the one that wrote it. */
+export const INDEX_FORMAT_VERSION = 1;
+
+const BUILD_DIR = "build";
+const INDEX_FILE = "index.json";
+const MANIFEST_FILE = "manifest.json";
+
+/** One thing the search can return: a rule, or one section of a source. */
+export interface IndexUnit {
+  /** `rule:<id>` or `source:<id>#<heading>`; unique in the index. */
+  key: string;
+  kind: "rule" | "source";
+  /** The id a person wrote, which citations name. */
+  ref: string;
+  heading: string;
+  /** What the unit says: the statement of a rule, or the text of a section. */
+  text: string;
+  scope: Scope | null;
+  /** The professions a rule is for, or null for every profession. A source is for all of them. */
+  professions: string[] | null;
+  expertise: string;
+  from: string;
+  to: string | null;
+  /** For a rule, the source it cites. */
+  source?: { id: string; section?: string };
+  /** For a source, where it came from. */
+  provenance?: { publisher: string; title: string; version?: string; retrieved_at: string };
+}
+
+export interface KnowledgeIndex {
+  format: number;
+  units: IndexUnit[];
+  /**
+   * The groups of characters to the units that contain them. Two-character groups answer a
+   * question too short to have three.
+   */
+  postings: { pairs: Record<string, number[]>; triples: Record<string, number[]> };
+  /** How many distinct three-character grams each unit has, for the length correction. */
+  sizes: number[];
+}
+
+export interface Manifest {
+  format: number;
+  input_sha256: string;
+  index_sha256: string;
+  units: number;
+  rules: number;
+  sources: number;
+  built_at: string;
+}
+
+/** Text as the index compares it: full width and half width alike, one case, no spaces. */
+export function normalize(text: string): string {
+  return text.normalize("NFKC").toLowerCase().replace(/\s+/gu, "");
+}
+
+/** The distinct groups of `n` characters in the text. */
+export function grams(text: string, n: number): Set<string> {
+  const chars = [...normalize(text)];
+  const out = new Set<string>();
+  for (let i = 0; i + n <= chars.length; i++) out.add(chars.slice(i, i + n).join(""));
+  return out;
+}
+
+/**
+ * The index of a checked set. A rule that another rule replaces is closed the day before the
+ * newer one starts, so the two are never in effect together.
+ */
+export function buildIndex(checked: Checked): KnowledgeIndex {
+  const closed = closeSuperseded(checked.rules);
+  const units: IndexUnit[] = [
+    ...closed.map(ruleUnit),
+    ...checked.sources.flatMap((source) => sectionUnits(source)),
+  ].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+
+  const postings = { pairs: {}, triples: {} } satisfies KnowledgeIndex["postings"];
+  const sizes: number[] = [];
+  for (const [at, unit] of units.entries()) {
+    // What a unit is matched on: its own words, and its heading when that is not the words
+    // themselves. The id is left out; it would only make a unit look longer than it reads.
+    // Aliases are already part of a rule's text, and nothing else bridges words that share no
+    // characters with it.
+    const matter = unit.heading === unit.text ? unit.text : `${unit.text} ${unit.heading}`;
+    add(postings.pairs, grams(matter, 2), at);
+    add(postings.triples, grams(matter, 3), at);
+    sizes.push(grams(matter, 3).size);
+  }
+  return {
+    format: INDEX_FORMAT_VERSION,
+    units,
+    postings: { pairs: settled(postings.pairs), triples: settled(postings.triples) },
+    sizes,
+  };
+}
+
+/** Notes that the unit at `at` holds each of these groups. */
+function add(postings: Record<string, number[]>, of: Set<string>, at: number): void {
+  for (const gram of of) {
+    const units = postings[gram];
+    if (units) units.push(at);
+    else postings[gram] = [at];
+  }
+}
+
+/** The same postings in a fixed order, so that the same input writes the same bytes. */
+function settled(postings: Record<string, number[]>): Record<string, number[]> {
+  return Object.fromEntries(
+    Object.entries(postings)
+      .sort(([a], [b]) => (a < b ? -1 : 1))
+      .map(([gram, units]) => [gram, [...units].sort((x, y) => x - y)]),
+  );
+}
+
+/** A rule replaced by another ends the day before that one begins. */
+function closeSuperseded(rules: LoadedRule[]): LoadedRule[] {
+  const replacedBy = new Map<string, LoadedRule>();
+  for (const rule of rules) if (rule.supersedes) replacedBy.set(rule.supersedes, rule);
+  return rules.map((rule) => {
+    const next = replacedBy.get(rule.id);
+    if (!next) return rule;
+    const end = dayBefore(next.effective_from);
+    return {
+      ...rule,
+      effective_to: rule.effective_to === null ? end : minDay(rule.effective_to, end),
+    };
+  });
+}
+
+function dayBefore(day: string): string {
+  const at = new Date(`${day}T00:00:00Z`);
+  at.setUTCDate(at.getUTCDate() - 1);
+  return at.toISOString().slice(0, 10);
+}
+
+const minDay = (a: string, b: string) => (a < b ? a : b);
+
+function ruleUnit(rule: LoadedRule): IndexUnit {
+  return {
+    key: `rule:${rule.id}`,
+    kind: "rule",
+    ref: rule.id,
+    heading: rule.statement,
+    text: [rule.statement, ...(rule.aliases ?? [])].join(" "),
+    scope: rule.scope ?? null,
+    professions: rule.applies_to?.profession ?? null,
+    expertise: rule.expertise,
+    from: rule.effective_from,
+    to: rule.effective_to,
+    source: {
+      id: rule.source.id,
+      ...(rule.source.section !== undefined && { section: rule.source.section }),
+    },
+  };
+}
+
+/** A source becomes one unit per heading; a source with no heading becomes one unit. */
+function sectionUnits(source: Source): IndexUnit[] {
+  const provenance = {
+    publisher: source.publisher,
+    title: source.title,
+    ...(source.version !== undefined && { version: source.version }),
+    retrieved_at: source.retrieved_at,
+  };
+  const common = {
+    kind: "source" as const,
+    ref: source.id,
+    scope: source.scope ?? null,
+    professions: null,
+    expertise: source.expertise,
+    from: source.effective_from,
+    to: source.effective_to,
+    provenance,
+  };
+  const sections = split(source.body);
+  if (sections.length === 0) {
+    return [{ ...common, key: `source:${source.id}#`, heading: source.title, text: source.body }];
+  }
+  // Two sections of one document may carry the same heading. A key names one unit, so the
+  // second one of a name says which it is.
+  const seen = new Map<string, number>();
+  return sections.map((section) => {
+    const nth = (seen.get(section.heading) ?? 0) + 1;
+    seen.set(section.heading, nth);
+    return {
+      ...common,
+      key: `source:${source.id}#${section.heading}${nth === 1 ? "" : ` (${nth})`}`,
+      heading: section.heading,
+      text: section.text,
+    };
+  });
+}
+
+/** The body cut at its markdown headings. Text before the first heading joins the first section. */
+function split(body: string): { heading: string; text: string }[] {
+  const lines = body.split("\n");
+  const sections: { heading: string; text: string[] }[] = [];
+  for (const line of lines) {
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) sections.push({ heading: heading[2] as string, text: [] });
+    else sections.at(-1)?.text.push(line);
+  }
+  return sections.map((section) => ({
+    heading: section.heading,
+    text: section.text.join("\n").trim(),
+  }));
+}
+
+/** The same bytes for the same index: keys in a fixed order, two spaces, a newline at the end. */
+export function serializeIndex(index: KnowledgeIndex): string {
+  const units = index.units.map((unit) => ordered(unit as unknown as Record<string, unknown>));
+  const body = {
+    format: index.format,
+    postings: index.postings,
+    sizes: index.sizes,
+    units,
+  };
+  return `${JSON.stringify(body, null, 2)}\n`;
+}
+
+/** An object with its keys in code point order, all the way down. */
+function ordered(value: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value).sort()) {
+    const inner = value[key];
+    out[key] =
+      inner && typeof inner === "object" && !Array.isArray(inner)
+        ? ordered(inner as Record<string, unknown>)
+        : inner;
+  }
+  return out;
+}
+
+const sha256 = (text: string) => createHash("sha256").update(text).digest("hex");
+
+/**
+ * The hash of what a person wrote, read from the files themselves rather than from what was
+ * parsed out of them. The runtime recomputes this before it trusts an index.
+ */
+export async function hashKnowledgeInput(workspaceRoot: string): Promise<string> {
+  const dir = join(workspaceRoot, KNOWLEDGE_DIR_NAME);
+  const parts: string[] = [];
+  for (const [sub, extension] of [
+    ["rules", ".yaml"],
+    ["sources", ".md"],
+  ] as const) {
+    let names: string[];
+    try {
+      names = (await readdir(join(dir, sub))).filter((n) => n.endsWith(extension)).sort();
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      // The same guarded read the checks use, so hashing and checking see one set of files: a
+      // file too large to read, or a link that leads out, is refused here as it is there.
+      const text = await readWorkspaceTextIfAny(dir, join(sub, name));
+      parts.push(`${sub}/${name}\n${text === undefined ? "unreadable" : sha256(text)}`);
+    }
+  }
+  return sha256(parts.join("\n"));
+}
+
+/**
+ * Writes the index and then the manifest, each through a temporary file. The manifest lands last
+ * and is the mark that the index beside it is whole: a reader that finds a manifest finds an
+ * index that was fully written.
+ */
+export async function writeIndex(
+  workspaceRoot: string,
+  index: KnowledgeIndex,
+  input: { hash: string; rules: number; sources: number },
+  now: Date = new Date(),
+): Promise<Manifest> {
+  const serialized = serializeIndex(index);
+  const manifest: Manifest = {
+    format: INDEX_FORMAT_VERSION,
+    input_sha256: input.hash,
+    index_sha256: sha256(serialized),
+    units: index.units.length,
+    rules: input.rules,
+    sources: input.sources,
+    built_at: now.toISOString(),
+  };
+  await writeKnowledgeFile(workspaceRoot, [BUILD_DIR, INDEX_FILE], serialized);
+  await writeKnowledgeFile(
+    workspaceRoot,
+    [BUILD_DIR, MANIFEST_FILE],
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+  return manifest;
+}
+
+/** What the runtime reads before it serves knowledge, or a reason not to serve any. */
+export type IndexState =
+  | { ok: true; index: KnowledgeIndex; manifest: Manifest }
+  | { ok: false; reason: string };
+
+/**
+ * Reads the index only if it is the one the manifest describes and the manifest describes the
+ * files that are there now. An index rewritten on its own, a manifest rewritten on its own, and
+ * an index built by another version of the runtime all come back as a reason not to serve it.
+ */
+export async function readIndex(workspaceRoot: string): Promise<IndexState> {
+  const stale = {
+    ok: false as const,
+    reason: "the index does not match the files it was built from; run `openshain knowledge build`",
+  };
+  let manifest: Manifest;
+  let serialized: string;
+  try {
+    // Read nothing before knowing its size: these two files are as writable as any other in the
+    // folder, and an index of a company's knowledge is far below this.
+    const manifestText = await readKnowledgeFile(workspaceRoot, [BUILD_DIR, MANIFEST_FILE]);
+    const indexText = await readKnowledgeFile(workspaceRoot, [BUILD_DIR, INDEX_FILE]);
+    if (manifestText === undefined || indexText === undefined) throw new Error("no index");
+    manifest = JSON.parse(manifestText) as Manifest;
+    serialized = indexText;
+  } catch {
+    return { ok: false, reason: "there is no index; run `openshain knowledge build`" };
+  }
+  if (manifest.format !== INDEX_FORMAT_VERSION) {
+    return {
+      ok: false,
+      reason:
+        "the index was built by another version of openshain; run `openshain knowledge build`",
+    };
+  }
+  if (sha256(serialized) !== manifest.index_sha256) return stale;
+  if ((await hashKnowledgeInput(workspaceRoot)) !== manifest.input_sha256) return stale;
+  try {
+    return { ok: true, index: JSON.parse(serialized) as KnowledgeIndex, manifest };
+  } catch {
+    return stale;
+  }
+}

package/src/knowledge/check.ts

@@ -0,0 +1,314 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parseYamlFile } from "../config/yaml.ts";
+import { isOpenshainError } from "../errors.ts";
+import { readWorkspaceTextIfAny } from "../tool/files.ts";
+import { resolveWorkspacePath } from "../tool/paths.ts";
+import {
+  type LoadedRule,
+  RulesFileSchema,
+  type Scope,
+  type Source,
+  SourceFrontMatterSchema,
+} from "./schema.ts";
+
+/**
+ * Reading and checking what a person wrote under `knowledge/`. Every problem is collected, never
+ * thrown at the first one: a person fixing a set of files should see all of it in one pass.
+ */
+
+export const KNOWLEDGE_DIR_NAME = "knowledge";
+
+/** How much a build reads in total, and how many files it reads, whatever is in the folder. */
+export const MAX_KNOWLEDGE_FILES = 2000;
+export const MAX_KNOWLEDGE_BYTES = 64 * 1024 * 1024;
+const RULES_DIR = "rules";
+const SOURCES_DIR = "sources";
+
+export interface Checked {
+  rules: LoadedRule[];
+  sources: Source[];
+  /** Everything wrong with what was read, each as `file:line:col field: message` or `file: message`. */
+  problems: string[];
+}
+
+/** True when the workspace has a `knowledge/` directory to read at all. */
+export async function hasKnowledge(workspaceRoot: string): Promise<boolean> {
+  try {
+    await readdir(join(workspaceRoot, KNOWLEDGE_DIR_NAME));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads `knowledge/rules/*.yaml` and `knowledge/sources/*.md` and checks them against each other.
+ * The rules that come back are the ones a build would index; when `problems` is not empty, nothing
+ * should be written.
+ */
+export async function checkKnowledge(
+  workspaceRoot: string,
+  options: {
+    /**
+     * Rules to check as though they were already written, with the file they would go in. A
+     * command that adds one asks this first, so that a rule which does not hold up is never
+     * written at all.
+     */
+    adding?: LoadedRule[];
+  } = {},
+): Promise<Checked> {
+  const dir = join(workspaceRoot, KNOWLEDGE_DIR_NAME);
+  const problems: string[] = [];
+  const budget = { files: MAX_KNOWLEDGE_FILES, bytes: MAX_KNOWLEDGE_BYTES };
+  const rules = [...(await readRules(dir, problems, budget)), ...(options.adding ?? [])];
+  const sources = await readSources(dir, problems, budget);
+
+  await checkPaths(workspaceRoot, sources, problems);
+  crossCheck(rules, sources, problems);
+  return { rules, sources, problems: problems.sort() };
+}
+
+/** Files of a directory in code point order; an unreadable directory is simply empty. */
+async function filesOf(dir: string, extension: string): Promise<string[]> {
+  try {
+    return (await readdir(dir))
+      .filter((name) => name.endsWith(extension) && !name.startsWith("."))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** What a read may still take. A build reads a bounded amount, whatever the folder holds. */
+interface Budget {
+  files: number;
+  bytes: number;
+}
+
+/** The text of a file, or a reason it was not read. Spends the budget as it goes. */
+async function within(
+  dir: string,
+  relative: string,
+  file: string,
+  budget: Budget,
+  problems: string[],
+): Promise<string | undefined> {
+  if (budget.files <= 0 || budget.bytes <= 0) {
+    problems.push(`${file}: not read; a build reads at most ${MAX_KNOWLEDGE_FILES} files`);
+    return undefined;
+  }
+  budget.files -= 1;
+  const text = await readWorkspaceTextIfAny(dir, relative);
+  if (text === undefined) {
+    problems.push(`${file}: cannot read the file`);
+    return undefined;
+  }
+  budget.bytes -= Buffer.byteLength(text, "utf8");
+  return text;
+}
+
+async function readRules(dir: string, problems: string[], budget: Budget): Promise<LoadedRule[]> {
+  const rules: LoadedRule[] = [];
+  for (const name of await filesOf(join(dir, RULES_DIR), ".yaml")) {
+    const file = `${KNOWLEDGE_DIR_NAME}/${RULES_DIR}/${name}`;
+    const text = await within(dir, join(RULES_DIR, name), file, budget, problems);
+    if (text === undefined) continue;
+    try {
+      const { data } = parseYamlFile(text, RulesFileSchema, file);
+      for (const rule of data.rules) rules.push({ ...rule, file });
+    } catch (err) {
+      problems.push(...messageOf(err, file));
+    }
+  }
+  return rules;
+}
+
+async function readSources(dir: string, problems: string[], budget: Budget): Promise<Source[]> {
+  const sources: Source[] = [];
+  for (const name of await filesOf(join(dir, SOURCES_DIR), ".md")) {
+    const file = `${KNOWLEDGE_DIR_NAME}/${SOURCES_DIR}/${name}`;
+    const text = await within(dir, join(SOURCES_DIR, name), file, budget, problems);
+    if (text === undefined) continue;
+    const split = frontMatter(text);
+    if (!split) {
+      problems.push(`${file}: the file must start with front matter between --- lines`);
+      continue;
+    }
+    try {
+      const { data } = parseYamlFile(split.head, SourceFrontMatterSchema, file);
+      sources.push({ ...data, body: split.body, file });
+    } catch (err) {
+      problems.push(...messageOf(err, file));
+    }
+  }
+  return sources;
+}
+
+/** The YAML between the opening `---` and the next one, and everything after it. */
+function frontMatter(text: string): { head: string; body: string } | undefined {
+  const lines = text.split("\n");
+  if (lines[0]?.trim() !== "---") return undefined;
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return undefined;
+  return {
+    head: lines.slice(1, end).join("\n"),
+    body: lines
+      .slice(end + 1)
+      .join("\n")
+      .trim(),
+  };
+}
+
+function messageOf(err: unknown, file: string): string[] {
+  if (isOpenshainError(err)) return err.message.split("\n");
+  return [`${file}: ${err instanceof Error ? err.message : String(err)}`];
+}
+
+/**
+ * A source that names a file names it inside the company folder. The guard the tools run under
+ * answers this, so a source cannot pull `authority/`, a principal's record or anything outside
+ * the folder into the index.
+ */
+async function checkPaths(
+  workspaceRoot: string,
+  sources: Source[],
+  problems: string[],
+): Promise<void> {
+  for (const source of sources) {
+    if (source.path === undefined) continue;
+    try {
+      await resolveWorkspacePath(workspaceRoot, source.path);
+    } catch (err) {
+      problems.push(
+        `${source.file}: ${source.id} points at ${source.path}, which the runtime does not read (${err instanceof Error ? err.message : String(err)})`,
+      );
+    }
+  }
+}
+
+/** The checks that need more than one file: references, scope, effective days. */
+function crossCheck(rules: LoadedRule[], sources: Source[], problems: string[]): void {
+  const byId = new Map(sources.map((source) => [source.id, source]));
+  for (const source of duplicates(sources)) {
+    problems.push(`${source.file}: source ${source.id} is defined more than once`);
+  }
+  for (const rule of duplicates(rules)) {
+    problems.push(`${rule.file}: rule ${rule.id} is defined more than once`);
+  }
+  for (const item of [...sources, ...rules]) endsAfterItStarts(item, problems);
+  for (const rule of rules) againstItsSource(rule, byId.get(rule.source.id), problems);
+  overlaps(rules, problems);
+}
+
+/** A day of the calendar comes before another; a rule or a source that ends first says nothing. */
+function endsAfterItStarts(
+  item: { id: string; file: string; effective_from: string; effective_to: string | null },
+  problems: string[],
+): void {
+  if (item.effective_to !== null && item.effective_to < item.effective_from) {
+    problems.push(`${item.file}: ${item.id} ends before it starts`);
+  }
+}
+
+/**
+ * A rule stands on the source it cites, so it may not exist without it, outlive it, begin before
+ * it, or be read by people who may not read it.
+ */
+function againstItsSource(rule: LoadedRule, source: Source | undefined, problems: string[]): void {
+  if (!source) {
+    problems.push(`${rule.file}: ${rule.id} cites ${rule.source.id}, which no source declares`);
+    return;
+  }
+  if (rule.effective_from < source.effective_from) {
+    problems.push(
+      `${rule.file}: ${rule.id} starts before ${source.id}, the source it cites, is in effect`,
+    );
+  }
+  if (source.effective_to !== null && (rule.effective_to ?? FOREVER) > source.effective_to) {
+    problems.push(
+      `${rule.file}: ${rule.id} outlives ${source.id}, the source it cites; close it on ${source.effective_to} or cite a newer source`,
+    );
+  }
+  if (!covers(source.scope, rule.scope)) {
+    problems.push(
+      `${rule.file}: ${rule.id} may be read by more people than ${source.id}, the source it cites; its citation would name a source they cannot read`,
+    );
+  }
+}
+
+/** A day later than any a person would write, for a rule or a source with no end. */
+const FOREVER = "9999-12-31";
+
+/** The items whose id was already taken by an earlier item. */
+function duplicates<T extends { id: string }>(items: T[]): T[] {
+  const seen = new Set<string>();
+  const again: T[] = [];
+  for (const item of items) {
+    if (seen.has(item.id)) again.push(item);
+    else seen.add(item.id);
+  }
+  return again;
+}
+
+/** The people a scope names, and how it names them. Company-wide names everyone. */
+function named(scope: Scope | undefined): {
+  kind: "everyone" | "principals" | "roles";
+  who: string[];
+} {
+  if (scope === undefined || "visibility" in scope) return { kind: "everyone", who: [] };
+  if ("principals" in scope) return { kind: "principals", who: scope.principals };
+  return { kind: "roles", who: scope.roles };
+}
+
+/** Whether everyone who may read `inner` may also read `outer`. */
+function covers(outer: Scope | undefined, inner: Scope | undefined): boolean {
+  const wider = named(outer);
+  const narrower = named(inner);
+  if (wider.kind === "everyone") return true;
+  if (narrower.kind === "everyone") return false;
+  // Two lists of different kinds cannot be compared without knowing who holds which role.
+  if (wider.kind !== narrower.kind) return false;
+  const allowed = new Set(wider.who);
+  return narrower.who.every((name) => allowed.has(name));
+}
+
+/**
+ * Two rules drawn from the very same passage, both in effect, are two answers to one question
+ * unless one says it replaces the other or they are for different people or professions.
+ *
+ * The passage, not the document: one policy document backs many rules — receipts over one
+ * amount, an approval over another — and that is how a company writes. Only rules that name the
+ * same section of the same source are compared, so ordinary writing is never refused.
+ */
+function overlaps(rules: LoadedRule[], problems: string[]): void {
+  const replaced = new Set(rules.map((rule) => rule.supersedes).filter(Boolean));
+  for (const [i, rule] of rules.entries()) {
+    for (const other of rules.slice(i + 1)) {
+      if (rule.source.id !== other.source.id) continue;
+      if (rule.source.section === undefined || rule.source.section !== other.source.section) {
+        continue;
+      }
+      if (replaced.has(rule.id) || replaced.has(other.id)) continue;
+      if (!inEffectTogether(rule, other)) continue;
+      if (disjoint(rule, other)) continue;
+      problems.push(
+        `${other.file}: ${other.id} and ${rule.id} both cite ${rule.source.id} の ${rule.source.section} and are in effect at the same time; close one with effective_to, or say supersedes`,
+      );
+    }
+  }
+}
+
+function inEffectTogether(a: LoadedRule, b: LoadedRule): boolean {
+  const end = (rule: LoadedRule) => rule.effective_to ?? FOREVER;
+  return a.effective_from <= end(b) && b.effective_from <= end(a);
+}
+
+/** Rules that no one person and no one profession sees together do not contradict each other. */
+function disjoint(a: LoadedRule, b: LoadedRule): boolean {
+  const professions = (rule: LoadedRule) => rule.applies_to?.profession;
+  const pa = professions(a);
+  const pb = professions(b);
+  if (pa && pb && !pa.some((name) => pb.includes(name))) return true;
+  return !covers(a.scope, b.scope) && !covers(b.scope, a.scope);
+}