@openshain/core 0.4.1 → 0.5.0

package/dist/knowledge/check.js

@@ -0,0 +1,262 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parseYamlFile } from "../config/yaml.js";
+import { isOpenshainError } from "../errors.js";
+import { readWorkspaceTextIfAny } from "../tool/files.js";
+import { resolveWorkspacePath } from "../tool/paths.js";
+import { RulesFileSchema, SourceFrontMatterSchema, } from "./schema.js";
+/**
+ * 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";
+/** True when the workspace has a `knowledge/` directory to read at all. */
+export async function hasKnowledge(workspaceRoot) {
+    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, options = {}) {
+    const dir = join(workspaceRoot, KNOWLEDGE_DIR_NAME);
+    const problems = [];
+    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, extension) {
+    try {
+        return (await readdir(dir))
+            .filter((name) => name.endsWith(extension) && !name.startsWith("."))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** The text of a file, or a reason it was not read. Spends the budget as it goes. */
+async function within(dir, relative, file, budget, problems) {
+    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, problems, budget) {
+    const rules = [];
+    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, problems, budget) {
+    const sources = [];
+    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) {
+    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, file) {
+    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, sources, problems) {
+    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, sources, problems) {
+    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, problems) {
+    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, source, problems) {
+    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(items) {
+    const seen = new Set();
+    const again = [];
+    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) {
+    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, inner) {
+    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, problems) {
+    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, b) {
+    const end = (rule) => 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, b) {
+    const professions = (rule) => 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/dist/knowledge/schema.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+/**
+ * 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 declare const ScopeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    visibility: z.ZodLiteral<"company">;
+}, z.core.$strict>, z.ZodObject<{
+    principals: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    roles: z.ZodArray<z.ZodString>;
+}, z.core.$strict>]>;
+export type Scope = z.infer<typeof ScopeSchema>;
+export declare const RuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    applies_to: z.ZodOptional<z.ZodObject<{
+        profession: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    scope: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        visibility: z.ZodLiteral<"company">;
+    }, z.core.$strict>, z.ZodObject<{
+        principals: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        roles: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>]>>;
+    effective_from: z.ZodString;
+    effective_to: z.ZodNullable<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodString>;
+    expertise: z.ZodString;
+    source: z.ZodObject<{
+        id: z.ZodString;
+        section: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type Rule = z.infer<typeof RuleSchema>;
+export declare const RulesFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    rules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        applies_to: z.ZodOptional<z.ZodObject<{
+            profession: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        scope: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            visibility: z.ZodLiteral<"company">;
+        }, z.core.$strict>, z.ZodObject<{
+            principals: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            roles: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>]>>;
+        effective_from: z.ZodString;
+        effective_to: z.ZodNullable<z.ZodString>;
+        supersedes: z.ZodOptional<z.ZodString>;
+        expertise: z.ZodString;
+        source: z.ZodObject<{
+            id: z.ZodString;
+            section: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The front matter of a source document. The body below it is the citation itself. */
+export declare const SourceFrontMatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    publisher: z.ZodString;
+    url: z.ZodOptional<z.ZodURL>;
+    path: z.ZodOptional<z.ZodString>;
+    retrieved_at: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    effective_from: z.ZodString;
+    effective_to: z.ZodNullable<z.ZodString>;
+    scope: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        visibility: z.ZodLiteral<"company">;
+    }, z.core.$strict>, z.ZodObject<{
+        principals: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        roles: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>]>>;
+    expertise: z.ZodString;
+}, z.core.$strict>;
+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/dist/knowledge/schema.js

@@ -0,0 +1,76 @@
+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) {
+    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) }),
+]);
+/**
+ * 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 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");

package/dist/knowledge/search.d.ts

@@ -0,0 +1,26 @@
+import { type IndexUnit, type KnowledgeIndex } 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 declare 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 declare function search(index: KnowledgeIndex, query: string, options?: SearchOptions): Hit[];
+/** Whether a unit is in effect on a day. */
+export declare function inEffect(unit: IndexUnit, day: string): boolean;

package/dist/knowledge/search.js

@@ -0,0 +1,54 @@
+import { grams, normalize } from "./build.js";
+/** The shortest question the index can answer. One character matches almost everything. */
+export const MIN_QUERY_LENGTH = 2;
+/**
+ * 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, query, options = {}) {
+    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();
+    for (const [at, unit] of index.units.entries())
+        if (allowed(unit))
+            visible.add(at);
+    const matched = new Map();
+    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 = [];
+    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) {
+    return 1 / (1 + Math.log10(1 + size / 40));
+}
+/** Whether a unit is in effect on a day. */
+export function inEffect(unit, day) {
+    return unit.from <= day && (unit.to === null || day <= unit.to);
+}

package/dist/knowledge/store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function writeKnowledgeFile(workspaceRoot: string, parts: string[], text: string): Promise<void>;
+/** Reads a file under `knowledge/`, or nothing when it is missing, a link, or too large. */
+export declare function readKnowledgeFile(workspaceRoot: string, parts: string[]): Promise<string | undefined>;
+/** Where a file under `knowledge/` is, for a message a person reads. */
+export declare function knowledgePath(parts: string[]): string;

package/dist/knowledge/store.js

@@ -0,0 +1,69 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { OpenshainError } from "../errors.js";
+import { KNOWLEDGE_DIR_NAME } from "./check.js";
+/**
+ * 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, parts) {
+    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, parts, text) {
+    const name = parts.at(-1);
+    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, parts) {
+    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) {
+    return [KNOWLEDGE_DIR_NAME, ...parts].join("/");
+}

package/dist/runtime.d.ts

@@ -9,7 +9,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 {
     workspaceRoot: string;

package/dist/runtime.js

@@ -62,7 +62,7 @@ export async function createToolRegistry(workspaceRoot, config, tools) {
             if (!factory) {
                 throw new OpenshainError("config", `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);
@@ -177,6 +177,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,
         });
     }

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import type { JsonSchema } from "./tool/types.ts";
-export type SchemaName = "config.v1" | "events.v1" | "work.v1" | "authority-policy.v1" | "authority-delegations.v1";
+export type SchemaName = "config.v1" | "events.v1" | "work.v1" | "authority-policy.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
  * schemas that validate them. `spec/schemas/` holds this output; `bun run schemas` regenerates it.

package/dist/schemas.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { DelegationsFileSchema, PolicyFileSchema } from "./authority/policy.js";
 import { ConfigFileSchema } from "./config/schema.js";
+import { RulesFileSchema, SourceFrontMatterSchema } from "./knowledge/schema.js";
 import { EventFileSchema, payloadFileSchemas } from "./work/events.js";
 import { WorkFileSchema } from "./work/work.js";
 /**
@@ -16,6 +17,8 @@ export function jsonSchemas() {
         "work.v1": describe(WorkFileSchema, "work.json", "The state of a work as projected from its event log. Never the source of truth."),
         "authority-policy.v1": describe(PolicyFileSchema, "authority/policy.yaml", "The rules that judge tool calls: the first matching rule decides, else the default."),
         "authority-delegations.v1": describe(DelegationsFileSchema, "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."),
     };
 }
 /**

package/dist/tool/files.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Reading and writing a file of the company folder. Everything that reaches a file on behalf of
+ * a tool goes through here, so the path guard and the size limit are applied in one place rather
+ * than remembered at each call. A caller that opens a file itself is a caller that can forget.
+ */
+/** The most a tool reads from one file. Larger files are refused, not truncated. */
+export declare const MAX_READ_BYTES: number;
+/** The most a tool writes to one file. */
+export declare const MAX_WRITE_BYTES: number;
+/**
+ * Reads a text file through one descriptor: the size check and the read see the same file, so a
+ * swap between the two cannot slip a larger file past the limit.
+ */
+export declare function readWorkspaceText(root: string, path: string): Promise<string>;
+/** The same read, but a file that is missing, too large or unreadable comes back as undefined. */
+export declare function readWorkspaceTextIfAny(root: string, path: string): Promise<string | undefined>;
+/** Writes through a descriptor opened with O_NOFOLLOW, so the final component may not be a symlink. */
+export declare function writeWorkspaceText(root: string, path: string, content: string): Promise<{
+    path: string;
+    sha256: string;
+}>;