@openshain/core 0.4.0 → 0.5.0

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);
+}

package/src/knowledge/schema.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+
+/**
+ * What a person writes under `knowledge/`: the company's own rules, and the sources behind them.
+ * The shapes only; what makes a set of them consistent is in `check.ts`.
+ */
+
+/** An id a person writes: lowercase, and readable as a path of meaning (`expenses.receipt-required`). */
+const knowledgeId = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(
+    /^[a-z0-9][a-z0-9._-]*$/,
+    "use lowercase letters, digits, . - or _, starting with a letter or a digit",
+  );
+
+/**
+ * A date as the company writes it. The runtime compares these as strings, so the form is fixed,
+ * and it must be a day that exists: the index closes a superseded rule the day before the next
+ * one starts, and `2026-13-45` would end that arithmetic in an error rather than a refusal.
+ */
+const day = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, "write a date as YYYY-MM-DD")
+  .refine(isDay, "that day does not exist");
+
+function isDay(text: string): boolean {
+  const at = new Date(`${text}T00:00:00Z`);
+  return !Number.isNaN(at.getTime()) && at.toISOString().startsWith(text);
+}
+
+/**
+ * Who may read it. A company with one principal may leave it out; with two or more it is written,
+ * because from then on leaving it out would mean deciding by accident.
+ */
+export const ScopeSchema = z.union([
+  z.strictObject({ visibility: z.literal("company") }),
+  z.strictObject({ principals: z.array(knowledgeId).min(1) }),
+  z.strictObject({ roles: z.array(knowledgeId).min(1) }),
+]);
+export type Scope = z.infer<typeof ScopeSchema>;
+
+/**
+ * The professional domain a piece of knowledge belongs to. `none` is the only value core knows;
+ * the rest is a string a profession pack or the company defines. Core compares it and holds no
+ * list of qualifications (docs/design/core.md, spec/professional-boundary.md).
+ */
+const expertise = z
+  .string()
+  .min(1)
+  .max(40)
+  .regex(/^[a-z][a-z0-9-]*$/, "use lowercase letters, digits and -");
+
+export const RuleSchema = z.strictObject({
+  id: knowledgeId,
+  statement: z.string().min(10).max(240),
+  aliases: z.array(z.string().min(1).max(80)).max(20).optional(),
+  applies_to: z.strictObject({ profession: z.array(knowledgeId).min(1) }).optional(),
+  scope: ScopeSchema.optional(),
+  effective_from: day,
+  // Written even when there is no end, so that an open-ended rule is a decision, not an omission.
+  effective_to: day.nullable(),
+  supersedes: knowledgeId.optional(),
+  expertise,
+  source: z.strictObject({ id: knowledgeId, section: z.string().min(1).max(200).optional() }),
+});
+export type Rule = z.infer<typeof RuleSchema>;
+
+export const RulesFileSchema = z.strictObject({
+  version: z.literal(1),
+  rules: z.array(RuleSchema).min(1),
+});
+
+/** The front matter of a source document. The body below it is the citation itself. */
+export const SourceFrontMatterSchema = z
+  .strictObject({
+    id: knowledgeId,
+    title: z.string().min(1).max(200),
+    publisher: z.string().min(1).max(200),
+    url: z.url().optional(),
+    path: z.string().min(1).max(1000).optional(),
+    retrieved_at: day,
+    version: z.string().min(1).max(80).optional(),
+    effective_from: day,
+    effective_to: day.nullable(),
+    scope: ScopeSchema.optional(),
+    expertise,
+  })
+  .refine(
+    (source) => source.url !== undefined || source.path !== undefined,
+    "say where it came from: url or path",
+  );
+export type SourceFrontMatter = z.infer<typeof SourceFrontMatterSchema>;
+
+/** A source as it was read: its front matter, the body, and the file it came from. */
+export interface Source extends SourceFrontMatter {
+  body: string;
+  file: string;
+}
+
+/** A rule as it was read, with the file it came from for the messages. */
+export interface LoadedRule extends Rule {
+  file: string;
+}

package/src/knowledge/search.ts

@@ -0,0 +1,74 @@
+import { grams, type IndexUnit, type KnowledgeIndex, normalize } from "./build.ts";
+
+/**
+ * Finding a unit by the characters it shares with a question. There is no embedding and no
+ * outside search engine: the index is groups of two and three characters, and the score is how
+ * much of the question a unit accounts for.
+ */
+
+export interface Hit {
+  unit: IndexUnit;
+  /** Between 0 and 1. The share of the question's grams the unit holds, corrected for length. */
+  score: number;
+}
+
+/** The shortest question the index can answer. One character matches almost everything. */
+export const MIN_QUERY_LENGTH = 2;
+
+export interface SearchOptions {
+  /** How many hits to return. */
+  limit?: number;
+  /** Only these units are searched. Everything else is invisible, count included. */
+  allowed?: (unit: IndexUnit) => boolean;
+}
+
+/**
+ * The best units for a question, most fitting first. Two hits with the same score keep the order
+ * of their keys, so the same index and question always answer the same way.
+ */
+export function search(index: KnowledgeIndex, query: string, options: SearchOptions = {}): Hit[] {
+  const text = normalize(query);
+  if (text.length < MIN_QUERY_LENGTH) return [];
+  // A question of two characters has no group of three, and two-character words are ordinary in
+  // Japanese business writing, so the shorter grams answer it.
+  const n = text.length < 3 ? 2 : 3;
+  const wanted = grams(query, n);
+  if (wanted.size === 0) return [];
+  const postings = n === 2 ? index.postings.pairs : index.postings.triples;
+
+  const allowed = options.allowed ?? (() => true);
+  // Narrow before scoring: what a person may not read costs nothing to rank, and the time a
+  // search takes then says nothing about how much of it there is.
+  const visible = new Set<number>();
+  for (const [at, unit] of index.units.entries()) if (allowed(unit)) visible.add(at);
+
+  const matched = new Map<number, number>();
+  for (const gram of wanted) {
+    for (const at of postings[gram] ?? []) {
+      if (visible.has(at)) matched.set(at, (matched.get(at) ?? 0) + 1);
+    }
+  }
+
+  const hits: Hit[] = [];
+  for (const [at, count] of matched) {
+    const unit = index.units[at];
+    if (!unit) continue;
+    hits.push({ unit, score: (count / wanted.size) * lengthCorrection(index.sizes[at] ?? 0) });
+  }
+  hits.sort((a, b) => b.score - a.score || (a.unit.key < b.unit.key ? -1 : 1));
+  return hits.slice(0, options.limit ?? 5);
+}
+
+/**
+ * A long document holds more groups of characters and so matches more questions by size alone.
+ * The correction keeps a short rule from losing to a page of prose that happens to contain the
+ * same words; it lowers a long unit's score without ever ruling it out.
+ */
+function lengthCorrection(size: number): number {
+  return 1 / (1 + Math.log10(1 + size / 40));
+}
+
+/** Whether a unit is in effect on a day. */
+export function inEffect(unit: IndexUnit, day: string): boolean {
+  return unit.from <= day && (unit.to === null || day <= unit.to);
+}

package/src/knowledge/store.ts

@@ -0,0 +1,82 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { OpenshainError } from "../errors.ts";
+import { KNOWLEDGE_DIR_NAME } from "./check.ts";
+
+/**
+ * Touching the files under `knowledge/`. The tools cannot reach them — it is a reserved path, so
+ * that what the index filters cannot be read around — which leaves the runtime to read and write
+ * them itself, without the guard the tools go through. These functions are that guard: the
+ * directory must be the one inside the company folder, and a link must never carry a write.
+ */
+
+/** How large a file under `knowledge/` may be for the runtime to read it whole. */
+const MAX_BYTES = 64 * 1024 * 1024;
+
+/**
+ * The directory the path names inside `knowledge/`, once it is known to be that directory. A
+ * link left in the folder would otherwise send a write anywhere the person can write.
+ */
+async function directory(workspaceRoot: string, parts: string[]): Promise<string> {
+  const root = await realpath(workspaceRoot);
+  const dir = join(root, KNOWLEDGE_DIR_NAME, ...parts);
+  await mkdir(dir, { recursive: true });
+  if ((await realpath(dir)) !== dir) {
+    throw new OpenshainError(
+      "invalid_path",
+      `${[KNOWLEDGE_DIR_NAME, ...parts].join("/")} leads out of the company folder; nothing was written`,
+    );
+  }
+  return dir;
+}
+
+/**
+ * Writes a file under `knowledge/` through a temporary file renamed into place, so a reader
+ * never sees half of one. The temporary name is easy to guess, so it is opened without following
+ * a link.
+ */
+export async function writeKnowledgeFile(
+  workspaceRoot: string,
+  parts: string[],
+  text: string,
+): Promise<void> {
+  const name = parts.at(-1) as string;
+  const dir = await directory(workspaceRoot, parts.slice(0, -1));
+  const path = join(dir, name);
+  const temporary = `${path}.writing`;
+  const flags =
+    constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | (constants.O_NOFOLLOW ?? 0);
+  const handle = await open(temporary, flags, 0o644);
+  try {
+    await handle.writeFile(text, "utf8");
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, path);
+}
+
+/** Reads a file under `knowledge/`, or nothing when it is missing, a link, or too large. */
+export async function readKnowledgeFile(
+  workspaceRoot: string,
+  parts: string[],
+): Promise<string | undefined> {
+  const path = join(workspaceRoot, KNOWLEDGE_DIR_NAME, ...parts);
+  try {
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const { size } = await handle.stat();
+      if (size > MAX_BYTES) return undefined;
+      return await handle.readFile("utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+/** Where a file under `knowledge/` is, for a message a person reads. */
+export function knowledgePath(parts: string[]): string {
+  return [KNOWLEDGE_DIR_NAME, ...parts].join("/");
+}

package/src/runtime.ts

@@ -11,6 +11,7 @@ import { loadConfig } from "./config/load.ts";
 import type { Config, ModelConfig } from "./config/schema.ts";
 import { isOpenshainError, OpenshainError } from "./errors.ts";
 import type { ModelProvider } from "./model/types.ts";
+import { businessDate } from "./time.ts";
 import { loadToolModule } from "./tool/load-module.ts";
 import type { HiddenTool } from "./tool/registry.ts";
 import { type RegisteredTool, ToolRegistry } from "./tool/registry.ts";
@@ -24,7 +25,9 @@ export interface RuntimeProviders {
   /** Model providers by the id used in openshain.yaml. */
   models: Record<string, (model: ModelConfig) => ModelProvider>;
   /** Tool providers by the id used in openshain.yaml. Modules are loaded from the config directly. */
-  tools: Record<string, () => ToolProvider>;
+  /** By the provider id used in openshain.yaml. The workspace is given, since what a provider
+   * offers can depend on what is in it. */
+  tools: Record<string, (workspaceRoot: string) => ToolProvider>;
 }
 
 export interface CreateRuntimeOptions {
@@ -150,7 +153,7 @@ export async function createToolRegistry(
           `unknown tool provider "${entry.provider}"; known providers: ${Object.keys(tools).join(", ")}`,
         );
       }
-      await registry.register(factory(), registerOptions);
+      await registry.register(factory(workspaceRoot), registerOptions);
     } else {
       await registry.register(await loadToolModule(workspaceRoot, entry.module), registerOptions);
     }
@@ -215,7 +218,7 @@ async function callTool(input: {
       principal: config.principal.id,
       profession: config.profession.id,
       workType: (await work.current()).type,
-      businessDate: businessDate(),
+      businessDate: businessDate(config.company.timezone),
     });
     if (judged.kind === "deny") return reject("denied", judged.reason);
     if (judged.kind === "approval_required" || judged.kind === "review_required") {
@@ -282,6 +285,8 @@ async function callTool(input: {
     result = await tool.provider.call(call, {
       workId: work.id,
       principalId: config.principal.id,
+      profession: config.profession.id,
+      businessDate: businessDate(config.company.timezone),
       workspaceRoot,
     });
   } catch (err) {
@@ -370,11 +375,6 @@ function pathOf(input: unknown): string | undefined {
 }
 
 /** Today's date on this machine's clock, YYYY-MM-DD. */
-function businessDate(): string {
-  const now = new Date();
-  const pad = (n: number) => String(n).padStart(2, "0");
-  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
-}
 
 function isRejectionCode(code: string): code is ToolRejectionCode {
   return (TOOL_REJECTION_CODES as readonly string[]).includes(code);

package/src/schemas.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { DelegationsFileSchema, PolicyFileSchema } from "./authority/policy.ts";
 import { ConfigFileSchema } from "./config/schema.ts";
+import { RulesFileSchema, SourceFrontMatterSchema } from "./knowledge/schema.ts";
 import type { JsonSchema } from "./tool/types.ts";
 import { EventFileSchema, payloadFileSchemas } from "./work/events.ts";
 import { WorkFileSchema } from "./work/work.ts";
@@ -10,7 +11,9 @@ export type SchemaName =
   | "events.v1"
   | "work.v1"
   | "authority-policy.v1"
-  | "authority-delegations.v1";
+  | "authority-delegations.v1"
+  | "knowledge-rules.v1"
+  | "knowledge-source.v1";
 
 /**
  * The JSON Schemas (draft 2020-12) of the files openshain reads and writes, derived from the zod
@@ -41,6 +44,16 @@ export function jsonSchemas(): Record<SchemaName, JsonSchema> {
       "authority/delegations.yaml",
       "Who the agent may act for, as which profession, and when.",
     ),
+    "knowledge-rules.v1": describe(
+      RulesFileSchema,
+      "knowledge/rules/*.yaml",
+      "The company's own rules, each with the source behind it and the days it is in effect.",
+    ),
+    "knowledge-source.v1": describe(
+      SourceFrontMatterSchema,
+      "knowledge/sources/*.md (front matter)",
+      "Where a cited document came from, when it applies, and who may read it.",
+    ),
   };
 }