@openshain/core 0.1.0

package/src/tool/validate.ts

@@ -0,0 +1,78 @@
+import type { ErrorObject } from "ajv";
+import Ajv2020 from "ajv/dist/2020.js";
+import safeRegex from "safe-regex2";
+import { OpenshainError } from "../errors.ts";
+import type { JsonSchema } from "./types.ts";
+
+export type InputValidation = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Compiles a tool's input schema once. Unknown keywords are tolerated because
+ * third-party schemas may carry vendor extensions; the schema itself must be
+ * valid, must describe an object, and may not contain a regular expression
+ * that can be made to backtrack catastrophically (the model controls the input).
+ */
+export function compileInputValidator(schema: JsonSchema): (input: unknown) => InputValidation {
+  if (schema.type !== "object") {
+    throw new OpenshainError("invalid_tool", 'input schema must have "type": "object"');
+  }
+  const unsafe = findUnsafePattern(schema);
+  if (unsafe !== undefined) {
+    throw new OpenshainError(
+      "invalid_tool",
+      `input schema contains a regular expression that can backtrack catastrophically: ${unsafe}`,
+    );
+  }
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  let validate: ReturnType<typeof ajv.compile>;
+  try {
+    validate = ajv.compile(schema);
+  } catch (cause) {
+    throw new OpenshainError(
+      "invalid_tool",
+      `input schema does not compile: ${(cause as Error).message}`,
+      { cause },
+    );
+  }
+  return (input) =>
+    validate(input) ? { ok: true } : { ok: false, reason: describe(validate.errors ?? []) };
+}
+
+/** Walks the schema and returns the first `pattern` or `patternProperties` key that is unsafe. */
+function findUnsafePattern(node: unknown): string | undefined {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const found = findUnsafePattern(item);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+  if (node === null || typeof node !== "object") return undefined;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "pattern" && typeof value === "string" && !safeRegex(value)) return value;
+    if (key === "patternProperties" && value !== null && typeof value === "object") {
+      for (const pattern of Object.keys(value)) {
+        if (!safeRegex(pattern)) return pattern;
+      }
+    }
+    const found = findUnsafePattern(value);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+function describe(errors: ErrorObject[]): string {
+  return errors
+    .map((error) => {
+      const where = error.instancePath || "/";
+      const params = error.params as Record<string, unknown>;
+      const detail =
+        error.keyword === "additionalProperties"
+          ? ` (${String(params.additionalProperty)})`
+          : error.keyword === "required"
+            ? ` (${String(params.missingProperty)})`
+            : "";
+      return `${where} ${error.message ?? error.keyword}${detail}`;
+    })
+    .join("; ");
+}

package/src/work/artifacts.ts

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolveWorkspacePath } from "../tool/paths.ts";
+import type { Artifact } from "./events.ts";
+
+/**
+ * The artifact as it is now. The runtime computes the hash rather than taking anyone's word.
+ * When the file cannot be read, because a later call moved or deleted it or because nobody
+ * wrote it, the artifact keeps the hash that was reported and is marked missing.
+ */
+export async function verifyArtifact(
+  root: string,
+  path: string,
+  reported: string,
+): Promise<Artifact> {
+  try {
+    const resolved = await resolveWorkspacePath(root, path);
+    const sha256 = createHash("sha256")
+      .update(await readFile(resolved))
+      .digest("hex");
+    return { path, sha256 };
+  } catch {
+    return { path, sha256: reported, missing: true };
+  }
+}

package/src/work/event-log.ts

@@ -0,0 +1,165 @@
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { OpenshainError } from "../errors.ts";
+import { newEventId, type WorkId } from "../ids.ts";
+import {
+  type AnyEvent,
+  type Event,
+  type EventPayloads,
+  type EventType,
+  eventFromFile,
+  eventToFile,
+} from "./events.ts";
+
+export const EVENTS_FILE_NAME = "events.jsonl";
+
+/** Appends to one file are serialized within the process, so two instances cannot interleave the size check and the write. */
+const appendQueues = new Map<string, Promise<unknown>>();
+
+function serialized<T>(path: string, task: () => Promise<T>): Promise<T> {
+  const previous = appendQueues.get(path) ?? Promise.resolve();
+  const run = previous.then(task, task);
+  const settled = run
+    .catch(() => undefined)
+    .then(() => {
+      if (appendQueues.get(path) === settled) appendQueues.delete(path);
+    });
+  appendQueues.set(path, settled);
+  return run;
+}
+
+export interface NewEvent<T extends EventType = EventType> {
+  type: T;
+  payload: EventPayloads[T];
+  /** When the thing happened. Defaults to the time of recording. */
+  occurredAt?: string;
+}
+
+/**
+ * Append-only log of one work's events. The file is the source of truth.
+ *
+ * Every line is checked on open and on read; a line that cannot be read stops
+ * the reader. Every event is checked on append by reading its own line back
+ * before it is written, so what is written can always be read. A change to the
+ * file by someone else between two operations of this instance is refused.
+ */
+export class EventLog {
+  private constructor(
+    private readonly path: string,
+    private readonly workId: WorkId,
+    private nextSeq: number,
+    private size: number,
+  ) {}
+
+  /** Opens (creating the directory if needed) and checks the existing log end to end. */
+  static async open(dir: string, workId: WorkId): Promise<EventLog> {
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, EVENTS_FILE_NAME);
+    const { events, size } = await readAll(path, workId);
+    const last = events.at(-1);
+    return new EventLog(path, workId, (last?.seq ?? 0) + 1, size);
+  }
+
+  async append<T extends EventType>(input: NewEvent<T>): Promise<Event<T>> {
+    const now = new Date().toISOString();
+    const event = {
+      v: 1 as const,
+      id: newEventId(),
+      workId: this.workId,
+      seq: this.nextSeq,
+      type: input.type,
+      occurredAt: input.occurredAt ?? now,
+      recordedAt: now,
+      payload: input.payload,
+    } as Event<T>;
+
+    let line: string;
+    try {
+      line = `${JSON.stringify(eventToFile(event))}\n`;
+      eventFromFile(JSON.parse(line));
+    } catch (cause) {
+      throw new OpenshainError(
+        "invalid_event",
+        `${input.type} event cannot be read back once written: ${(cause as Error).message}`,
+        { cause },
+      );
+    }
+
+    await serialized(this.path, async () => {
+      const current = await fileSize(this.path);
+      if (current !== this.size) {
+        throw new OpenshainError(
+          "concurrent_write",
+          `${this.path} changed since it was opened (expected ${this.size} bytes, found ${current}); another writer is active`,
+        );
+      }
+      await appendFile(this.path, line, "utf8");
+      this.size += Buffer.byteLength(line, "utf8");
+      this.nextSeq += 1;
+    });
+    return event;
+  }
+
+  async read(): Promise<AnyEvent[]> {
+    return (await readAll(this.path, this.workId)).events;
+  }
+}
+
+async function fileSize(path: string): Promise<number> {
+  try {
+    return (await stat(path)).size;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return 0;
+    throw err;
+  }
+}
+
+async function readAll(
+  path: string,
+  workId: WorkId,
+): Promise<{ events: AnyEvent[]; size: number }> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { events: [], size: 0 };
+    throw err;
+  }
+  const corrupt = (detail: string, cause?: unknown) =>
+    new OpenshainError("corrupt_log", `${path}: ${detail}`, { cause });
+
+  if (text.length > 0 && !text.endsWith("\n")) {
+    throw corrupt("does not end with a newline; the last write did not complete");
+  }
+
+  const events: AnyEvent[] = [];
+  const lines = text.split("\n");
+  lines.forEach((line, index) => {
+    const lineNo = index + 1;
+    if (line === "") {
+      if (index === lines.length - 1) return; // trailing newline
+      throw corrupt(`line ${lineNo} is empty`);
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch (cause) {
+      throw corrupt(`line ${lineNo} is not valid JSON`, cause);
+    }
+    let event: AnyEvent;
+    try {
+      event = eventFromFile(parsed);
+    } catch (cause) {
+      throw corrupt(`line ${lineNo} is not a valid event: ${(cause as Error).message}`, cause);
+    }
+    if (event.workId !== workId) {
+      throw corrupt(`line ${lineNo} belongs to ${event.workId}, expected ${workId}`);
+    }
+    const expectedSeq = events.length + 1;
+    if (event.seq !== expectedSeq) {
+      throw corrupt(`line ${lineNo} has seq ${event.seq}, expected ${expectedSeq}`);
+    }
+    events.push(event);
+  });
+  return { events, size: Buffer.byteLength(text, "utf8") };
+}