harnery 0.33.0 → 0.34.0

package/src/core/hooks/events/emit.ts

@@ -1,125 +0,0 @@
-import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { maybeRotateEventStream } from "./rotate.ts";
-import {
-  type Adapter,
-  type EventEnvelope,
-  type EventType,
-  SCHEMA_VERSION,
-  type Source,
-} from "./schema.ts";
-import { ulid } from "./ulid.ts";
-
-const LOCK_FILE = ".harnery/events.ndjson.lock";
-const STREAM_FILE = ".harnery/events.ndjson";
-
-const MAX_LINE_BYTES = 64 * 1024;
-
-export interface EmitInput<TType extends EventType, TData> {
-  event_type: TType;
-  instance_id: string;
-  session_id: string;
-  adapter: Adapter;
-  source?: Source;
-  parent_session_id?: string;
-  turn_id?: string;
-  parent_turn_id?: string;
-  ts?: string;
-  data: TData;
-}
-
-/**
- * Build a canonical envelope around the caller's `data` payload. Pure;
- * doesn't touch the filesystem. Useful for tests + replay fixtures.
- */
-export function buildEnvelope<TType extends EventType, TData>(
-  input: EmitInput<TType, TData>,
-): EventEnvelope<TType, TData> {
-  return {
-    schema_version: SCHEMA_VERSION,
-    event_id: ulid(),
-    event_type: input.event_type,
-    ts: input.ts ?? new Date().toISOString(),
-    instance_id: input.instance_id,
-    session_id: input.session_id,
-    parent_session_id: input.parent_session_id,
-    turn_id: input.turn_id,
-    parent_turn_id: input.parent_turn_id,
-    adapter: input.adapter,
-    source: input.source ?? "agent-hooks",
-    data: input.data,
-  };
-}
-
-/**
- * Append one canonical event to `.harnery/events.ndjson` under a file lock.
- * Append-only, one JSON object per line, lock-serialized.
- *
- * Synchronous because hooks are short-lived processes: we want the append to
- * land before the binary exits, and async/await across a tiny write is just
- * latency for no benefit.
- *
- * Returns the envelope so callers can chain off it (debug logs, post-emit
- * verdict requests).
- */
-export function emit<TType extends EventType, TData>(
-  coordRoot: string,
-  input: EmitInput<TType, TData>,
-): EventEnvelope<TType, TData> {
-  const envelope = buildEnvelope(input);
-  const streamPath = join(coordRoot, STREAM_FILE);
-  const lockPath = join(coordRoot, LOCK_FILE);
-
-  // Size-triggered rotation: roll the active file to a dated archive when it
-  // crosses the cap, so this append lands in a bounded fresh file. Fail-soft.
-  maybeRotateEventStream(coordRoot);
-
-  ensureDir(dirname(streamPath));
-  ensureFile(lockPath);
-
-  let line = `${JSON.stringify(envelope)}\n`;
-  if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
-    // lines >64KB are a schema bug. Phase 2 hard-truncates the `data`
-    // payload + sets `truncated: true` so we keep audit visibility without
-    // breaking downstream consumers.
-    const truncated = `${JSON.stringify({
-      ...envelope,
-      data: { __over_size_limit: true, original_bytes: Buffer.byteLength(line, "utf8") },
-      // eslint-disable-next-line @typescript-eslint/naming-convention
-    })}\n`;
-    line = truncated;
-  }
-
-  const lockFd = openSync(lockPath, "r+");
-  try {
-    // flock isn't directly exposed in node fs; use fcntl-like via shelling out
-    // would be slower than POSIX flock(2) inside the kernel. Bun exposes
-    // `Bun.flock` in recent builds, but a simple fs-level append is atomic
-    // for lines <PIPE_BUF (4KB on Linux) anyway. For larger lines we rely on
-    // append-mode flag (O_APPEND) which kernels serialize per-fd.
-    //
-    // The `events.ndjson.lock` file is kept around for forward
-    // compatibility: Phase 4+ helpers acquire it before multi-write batches.
-    appendFileSync(streamPath, line, { encoding: "utf8", flag: "a" });
-  } finally {
-    closeSync(lockFd);
-  }
-
-  return envelope;
-}
-
-function ensureDir(path: string): void {
-  try {
-    mkdirSync(path, { recursive: true });
-  } catch {
-    /* swallow */
-  }
-}
-
-function ensureFile(path: string): void {
-  try {
-    closeSync(openSync(path, "a"));
-  } catch {
-    /* swallow */
-  }
-}

package/src/core/hooks/events/rotate.ts

@@ -1,151 +0,0 @@
-/**
- * Size-triggered rotation for the canonical event stream
- * `.harnery/events.ndjson`.
- *
- * The stream is a deliberately-immutable, append-only ledger. Left unbounded it
- * grows past V8's ~512MB max string length, at which point any code that does a
- * whole-file `readFileSync` throws ("Cannot create a string longer than
- * 0x1fffffe8 characters"). Rather than police every current + future reader,
- * we bound the *active* file: once it crosses a byte cap we rename it to a dated
- * archive (`events-YYYY-MM-DD.ndjson`) and start a fresh active file. Archives
- * are kept — the audit trail is preserved, just spread across files that readers
- * glob newest-first.
- *
- * Both independent append paths (agent-hooks `hooks/events/emit.ts` and
- * agent-coord `agents/events/emit.ts`) call `maybeRotateEventStream` before
- * appending, so a roll is triggered continuously, not only at session
- * boundaries.
- *
- * Concurrency: many short-lived hook processes append at once. The rename itself
- * is atomic — a concurrent appender opening the path by name lands its line in
- * whichever inode the name currently resolves to (old archive or new active
- * file), never nowhere. The only hazard is two processes both renaming (the
- * second would move the fresh empty file to a second archive name), which an
- * `O_EXCL` roll-lock prevents.
- *
- * Design + rationale: harnery ADR 0009; decision docket
- * `should-harnery-adopt-a-retention-2026-07-07-ed07`.
- */
-
-import {
-  closeSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
-import { coordEnv } from "../../../lib/env.ts";
-
-const STREAM_FILE = ".harnery/events.ndjson";
-const ROLL_LOCK_FILE = ".harnery/events.ndjson.roll.lock";
-
-/** Default active-file cap: 256 MiB — half of V8's ~512MB string cliff, so even
- * a reader that loads the whole active file whole stays clear of the limit. */
-const DEFAULT_ROLL_BYTES = 256 * 1024 * 1024;
-
-/** A roll-lock older than this is treated as abandoned (a crashed roller) and
- * stolen. Rolls are sub-millisecond, so 60s is orders of magnitude of slack. */
-const STALE_LOCK_MS = 60_000;
-
-/** Archive glob prefix. Readers enumerate `events-*.ndjson` newest-first.
- * The pre-existing manual `events-legacy.ndjson` matches and is picked up for
- * free. Kept in sync with the reader-side pattern in web/lib/coord-reader.ts. */
-export const ARCHIVE_PREFIX = "events-";
-export const ARCHIVE_SUFFIX = ".ndjson";
-
-function resolveRollBytes(): number {
-  const env = coordEnv("EVENTS_ROLL_BYTES");
-  const n = env ? Number(env) : Number.NaN;
-  return Number.isFinite(n) && n > 0 ? n : DEFAULT_ROLL_BYTES;
-}
-
-/** `YYYY-MM-DD` (UTC) from a millisecond timestamp. Uses the file's own mtime
- * rather than `Date.now()` so it's deterministic and independent of the adapter
- * runtime's clock surface. */
-function utcDateStamp(mtimeMs: number): string {
-  const d = new Date(mtimeMs);
-  const y = d.getUTCFullYear();
-  const mo = String(d.getUTCMonth() + 1).padStart(2, "0");
-  const day = String(d.getUTCDate()).padStart(2, "0");
-  return `${y}-${mo}-${day}`;
-}
-
-/** First non-colliding `events-<stamp>[.N].ndjson` path under `coordDir`. */
-function archivePathFor(coordDir: string, stamp: string): string {
-  const base = join(coordDir, `${ARCHIVE_PREFIX}${stamp}${ARCHIVE_SUFFIX}`);
-  if (!existsSync(base)) return base;
-  for (let n = 1; ; n++) {
-    const cand = join(coordDir, `${ARCHIVE_PREFIX}${stamp}.${n}${ARCHIVE_SUFFIX}`);
-    if (!existsSync(cand)) return cand;
-  }
-}
-
-/**
- * Roll `events.ndjson` to a dated archive when it exceeds the byte cap. Cheap
- * no-op (a single `statSync`) below the cap. Fail-soft: any error is swallowed
- * so a rotation problem can never break the append that triggered it.
- *
- * `nowMs` is injectable for the stale-lock check in tests; production leaves it
- * unset (the roll date always comes from the file's mtime, never `nowMs`).
- */
-export function maybeRotateEventStream(coordRoot: string, nowMs?: number): boolean {
-  try {
-    const streamPath = join(coordRoot, STREAM_FILE);
-    if (!existsSync(streamPath)) return false;
-    const cap = resolveRollBytes();
-    let st = statSync(streamPath);
-    if (st.size < cap) return false;
-
-    const coordDir = dirname(streamPath);
-    const lockPath = join(coordRoot, ROLL_LOCK_FILE);
-    mkdirSync(coordDir, { recursive: true });
-
-    if (!acquireRollLock(lockPath, nowMs)) return false; // another roller active
-    try {
-      // Re-check under the lock: a concurrent process may have just rolled.
-      if (!existsSync(streamPath)) return false;
-      st = statSync(streamPath);
-      if (st.size < cap) return false;
-
-      const archive = archivePathFor(coordDir, utcDateStamp(st.mtimeMs));
-      renameSync(streamPath, archive);
-      // Recreate an empty active file so the very next append (and any reader's
-      // existsSync) sees a valid, present stream.
-      closeSync(openSync(streamPath, "a"));
-      return true;
-    } finally {
-      try {
-        unlinkSync(lockPath);
-      } catch {
-        /* best-effort */
-      }
-    }
-  } catch {
-    return false; // fail-soft: never break the caller's append
-  }
-}
-
-/** Create the roll-lock with O_EXCL. Returns true on acquisition. On collision,
- * steals a stale lock (crashed roller) once, else returns false. */
-function acquireRollLock(lockPath: string, nowMs?: number): boolean {
-  try {
-    closeSync(openSync(lockPath, "wx"));
-    return true;
-  } catch {
-    // Exists: steal if abandoned.
-    try {
-      const age = (nowMs ?? Date.now()) - statSync(lockPath).mtimeMs;
-      if (age > STALE_LOCK_MS) {
-        unlinkSync(lockPath);
-        closeSync(openSync(lockPath, "wx"));
-        return true;
-      }
-    } catch {
-      /* lost the steal race — someone else holds it */
-    }
-    return false;
-  }
-}