harnery 0.35.0 → 0.37.0

package/src/core/storage/metrics.ts

@@ -0,0 +1,199 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+
+export interface HarneryLogMetricsDelta {
+  accepted?: number;
+  encoded?: number;
+  appended?: number;
+  synced?: number;
+  dropped?: number;
+  coalesced?: number;
+  sampled?: number;
+  bytes_accepted?: number;
+  bytes_appended?: number;
+  bytes_dropped?: number;
+  rotations?: number;
+  failures?: Record<string, number>;
+  append_latency_ms?: number;
+  flush_latency_ms?: number;
+  queue?: {
+    bytes: number;
+    capacity_bytes: number;
+    peak_bytes: number;
+    snapshot_at: string;
+  };
+}
+
+export interface HarneryLogMetricsV1 {
+  schema: "harnery.log-metrics/v1";
+  generation: string;
+  window_started_at: string;
+  last_merge_at: string;
+  last_successful_sink_at?: string;
+  counters: {
+    accepted: number;
+    encoded: number;
+    appended: number;
+    synced: number;
+    dropped: number;
+    coalesced: number;
+    sampled: number;
+    bytes_accepted: number;
+    bytes_appended: number;
+    bytes_dropped: number;
+    rotations: number;
+  };
+  failures: Record<string, number>;
+  append_latency_histogram: readonly number[];
+  flush_latency_histogram: readonly number[];
+  queue?: HarneryLogMetricsDelta["queue"];
+}
+
+const HISTOGRAM_BUCKETS = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1_000, 5_000];
+
+export class LogMetricsAccumulator {
+  #delta: HarneryLogMetricsDelta = {};
+  #peakQueueBytes = 0;
+
+  increment<K extends keyof HarneryLogMetricsDelta>(key: K, amount = 1): void {
+    if (key === "failures" || key === "queue") return;
+    const current = this.#delta[key];
+    if (typeof current === "number") this.#delta[key] = (current + amount) as never;
+    else this.#delta[key] = amount as never;
+  }
+
+  failure(reason: string, amount = 1): void {
+    if (!this.#delta.failures) this.#delta.failures = {};
+    const failures = this.#delta.failures;
+    failures[reason] = (failures[reason] ?? 0) + amount;
+  }
+
+  observeQueue(bytes: number, capacityBytes: number, now: Date): void {
+    this.#peakQueueBytes = Math.max(this.#peakQueueBytes, bytes);
+    this.#delta.queue = {
+      bytes,
+      capacity_bytes: capacityBytes,
+      peak_bytes: this.#peakQueueBytes,
+      snapshot_at: now.toISOString(),
+    };
+  }
+
+  observeLatency(kind: "append_latency_ms" | "flush_latency_ms", milliseconds: number): void {
+    this.#delta[kind] = Math.max(0, milliseconds);
+  }
+
+  take(): HarneryLogMetricsDelta {
+    const delta = this.#delta;
+    this.#delta = {};
+    this.#peakQueueBytes = 0;
+    return delta;
+  }
+}
+
+export function mergeMetricsSidecar(
+  path: string,
+  delta: HarneryLogMetricsDelta,
+  now = new Date(),
+): { merged: boolean; generation_reset: boolean } {
+  let current: HarneryLogMetricsV1;
+  let generationReset = false;
+  try {
+    current = existsSync(path)
+      ? validateMetrics(JSON.parse(readFileSync(path, "utf8")))
+      : emptyMetrics(now);
+    generationReset = !existsSync(path);
+  } catch {
+    current = emptyMetrics(now);
+    generationReset = true;
+  }
+  const merged = mergeMetrics(current, delta, now);
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(merged)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, path);
+    return { merged: true, generation_reset: generationReset };
+  } catch {
+    return { merged: false, generation_reset: generationReset };
+  }
+}
+
+export function readMetricsSidecar(path: string): HarneryLogMetricsV1 | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return validateMetrics(JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
+function mergeMetrics(
+  current: HarneryLogMetricsV1,
+  delta: HarneryLogMetricsDelta,
+  now: Date,
+): HarneryLogMetricsV1 {
+  const counters = { ...current.counters };
+  for (const key of Object.keys(counters) as Array<keyof typeof counters>) {
+    counters[key] += delta[key] ?? 0;
+  }
+  const failures = { ...current.failures };
+  for (const [reason, count] of Object.entries(delta.failures ?? {})) {
+    failures[reason] = (failures[reason] ?? 0) + count;
+  }
+  return {
+    ...current,
+    last_merge_at: now.toISOString(),
+    ...(delta.appended ? { last_successful_sink_at: now.toISOString() } : {}),
+    counters,
+    failures,
+    append_latency_histogram: addHistogram(
+      current.append_latency_histogram,
+      delta.append_latency_ms,
+    ),
+    flush_latency_histogram: addHistogram(current.flush_latency_histogram, delta.flush_latency_ms),
+    ...(delta.queue ? { queue: delta.queue } : {}),
+  };
+}
+
+function emptyMetrics(now: Date): HarneryLogMetricsV1 {
+  return {
+    schema: "harnery.log-metrics/v1",
+    generation: randomUUID(),
+    window_started_at: now.toISOString(),
+    last_merge_at: now.toISOString(),
+    counters: {
+      accepted: 0,
+      encoded: 0,
+      appended: 0,
+      synced: 0,
+      dropped: 0,
+      coalesced: 0,
+      sampled: 0,
+      bytes_accepted: 0,
+      bytes_appended: 0,
+      bytes_dropped: 0,
+      rotations: 0,
+    },
+    failures: {},
+    append_latency_histogram: HISTOGRAM_BUCKETS.map(() => 0),
+    flush_latency_histogram: HISTOGRAM_BUCKETS.map(() => 0),
+  };
+}
+
+function addHistogram(current: readonly number[], value: number | undefined): number[] {
+  const next = [...current];
+  if (value === undefined) return next;
+  const index = HISTOGRAM_BUCKETS.findIndex((bucket) => value <= bucket);
+  next[index < 0 ? next.length - 1 : index] += 1;
+  return next;
+}
+
+function validateMetrics(value: unknown): HarneryLogMetricsV1 {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    (value as HarneryLogMetricsV1).schema !== "harnery.log-metrics/v1"
+  ) {
+    throw new Error("invalid metrics sidecar");
+  }
+  return value as HarneryLogMetricsV1;
+}

package/src/core/storage/policy.ts

@@ -0,0 +1,141 @@
+import type {
+  HarneryStorageBudget,
+  HarneryStorageFamily,
+  HarneryStoragePolicy,
+} from "./contract.ts";
+
+export class HarneryStoragePolicyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "HarneryStoragePolicyError";
+  }
+}
+
+const UNITS = new Set(["milliseconds", "bytes", "files", "records"]);
+const RETENTION_MODES = new Set([
+  "indefinite",
+  "oldest-sealed",
+  "owner-lifecycle",
+  "ttl",
+  "expired-only",
+  "delegated",
+]);
+
+export function validateStoragePolicy(
+  value: unknown,
+  label = "storage policy",
+): asserts value is HarneryStoragePolicy {
+  const policy = record(value, `${label} must be an object`);
+  if (policy.schema !== "harnery.storage-policy/v1") fail(label, "has an unsupported schema");
+  if (!identifier(policy.policy_version)) fail(label, "has an invalid policy_version");
+  if (policy.writes !== "active" && policy.writes !== "disabled") {
+    fail(label, "has an invalid writes state");
+  }
+
+  const rotation = record(policy.rotation, `${label}.rotation must be an object`);
+  if (!new Set(["none", "size", "owner-protocol"]).has(String(rotation.mode))) {
+    fail(label, "has an invalid rotation mode");
+  }
+  budget(rotation.max_segment_bytes, "bytes", `${label}.rotation.max_segment_bytes`);
+  budget(rotation.max_open_age, "milliseconds", `${label}.rotation.max_open_age`);
+
+  const retention = record(policy.retention, `${label}.retention must be an object`);
+  if (!new Set(["active", "proposed", "inactive"]).has(String(retention.status))) {
+    fail(label, "has an invalid retention status");
+  }
+  if (!RETENTION_MODES.has(String(retention.mode))) fail(label, "has an invalid retention mode");
+  budget(retention.max_age, "milliseconds", `${label}.retention.max_age`);
+  budget(retention.max_bytes, "bytes", `${label}.retention.max_bytes`);
+  budget(retention.max_files, "files", `${label}.retention.max_files`);
+  budget(retention.max_records, "records", `${label}.retention.max_records`);
+  if (!nonempty(retention.reason)) fail(label, "must explain its retention rule");
+
+  const records = record(policy.records, `${label}.records must be an object`);
+  budget(records.max_record_bytes, "bytes", `${label}.records.max_record_bytes`);
+
+  const privacy = record(policy.privacy, `${label}.privacy must be an object`);
+  if (!new Set(["private", "internal-metadata", "public"]).has(String(privacy.sensitivity))) {
+    fail(label, "has an invalid privacy sensitivity");
+  }
+  if (!new Set(["metadata-only", "owner-content", "public-content"]).has(String(privacy.content))) {
+    fail(label, "has an invalid privacy content class");
+  }
+  if (
+    !Array.isArray(privacy.forbidden_fields) ||
+    privacy.forbidden_fields.some((field) => !nonempty(field)) ||
+    new Set(privacy.forbidden_fields).size !== privacy.forbidden_fields.length
+  ) {
+    fail(label, "has invalid forbidden_fields");
+  }
+  if (
+    !new Set(["fail-closed", "best-effort", "reject-before-write", "owner-protocol"]).has(
+      String(policy.failure_behavior),
+    )
+  ) {
+    fail(label, "has an invalid failure_behavior");
+  }
+  if (policy.reconstruction_source !== undefined && !nonempty(policy.reconstruction_source)) {
+    fail(label, "has an invalid reconstruction_source");
+  }
+}
+
+export function validateFamilyPolicy(family: HarneryStorageFamily): void {
+  validateStoragePolicy(family.policy, `storage family ${family.id} policy`);
+  if (family.policy.privacy.sensitivity !== family.sensitivity) {
+    throw new HarneryStoragePolicyError(
+      `storage family ${family.id} policy sensitivity does not match its descriptor`,
+    );
+  }
+  if (family.storage_class === "repairable-cache" && !family.policy.reconstruction_source) {
+    throw new HarneryStoragePolicyError(
+      `storage family ${family.id} repairable cache must name its reconstruction source`,
+    );
+  }
+  if (
+    (family.storage_class === "operational-log" || family.storage_class === "debug-log") &&
+    family.policy.retention.status === "active" &&
+    family.policy.retention.mode === "indefinite"
+  ) {
+    throw new HarneryStoragePolicyError(
+      `storage family ${family.id} active log retention cannot be indefinite`,
+    );
+  }
+}
+
+function budget(value: unknown, unit: HarneryStorageBudget["unit"], label: string): void {
+  const candidate = record(value, `${label} must be an object`);
+  if (!UNITS.has(String(candidate.unit)) || candidate.unit !== unit) {
+    throw new HarneryStoragePolicyError(`${label} must use ${unit}`);
+  }
+  if (candidate.limit === null) {
+    if (!nonempty(candidate.unbounded_reason)) {
+      throw new HarneryStoragePolicyError(`${label} is unbounded without a reason`);
+    }
+    return;
+  }
+  if (!Number.isSafeInteger(candidate.limit) || (candidate.limit as number) <= 0) {
+    throw new HarneryStoragePolicyError(`${label} limit must be a positive safe integer or null`);
+  }
+  if (candidate.unbounded_reason !== undefined) {
+    throw new HarneryStoragePolicyError(`${label} has a limit and an unbounded_reason`);
+  }
+}
+
+function record(value: unknown, message: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new HarneryStoragePolicyError(message);
+  }
+  return value as Record<string, unknown>;
+}
+
+function identifier(value: unknown): boolean {
+  return typeof value === "string" && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(value);
+}
+
+function nonempty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function fail(label: string, detail: string): never {
+  throw new HarneryStoragePolicyError(`${label} ${detail}`);
+}

package/src/core/storage/process-log.ts

@@ -0,0 +1,203 @@
+import { type ChildProcess, spawn, spawnSync } from "node:child_process";
+import {
+  closeSync,
+  existsSync,
+  fdatasyncSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createStorageCatalog } from "./catalog.ts";
+import { familyLogDirectory } from "./segments.ts";
+
+export interface RotatingTextSinkOptions {
+  path: string;
+  max_bytes: number;
+  backups?: number;
+  durable?: boolean;
+}
+
+export interface ProcessLogDestinationOptions {
+  coord_root: string;
+  project_root?: string;
+  family_id: string;
+  filename: string;
+  legacy_path: string;
+  env?: Readonly<Record<string, string | undefined>>;
+}
+
+export interface RotatingProcessOptions {
+  path: string;
+  command: string;
+  arguments?: string[];
+  env?: Readonly<Record<string, string | undefined>>;
+  max_bytes?: number;
+  backups?: number;
+}
+
+const DEFAULT_PROCESS_LOG_BYTES = 5 * 1024 * 1024;
+const DEFAULT_PROCESS_LOG_BACKUPS = 3;
+
+/** Resolve one catalog-owned partition path, with an explicit legacy rollback. */
+export function processLogDestination(options: ProcessLogDestinationOptions): string {
+  const env = options.env ?? process.env;
+  if (env.HARNERY_SHARED_LOGS === "0") return resolve(options.legacy_path);
+  if (
+    basename(options.filename) !== options.filename ||
+    !/^[a-z0-9][a-z0-9.-]*$/i.test(options.filename)
+  ) {
+    throw new Error("invalid process log filename");
+  }
+  const catalog = createStorageCatalog({
+    coord_root: resolve(options.coord_root),
+    project_root: resolve(options.project_root ?? options.coord_root),
+  });
+  return join(familyLogDirectory(catalog.require(options.family_id)), options.filename);
+}
+
+export class RotatingTextSink {
+  readonly #options: Required<RotatingTextSinkOptions>;
+  #closed = false;
+
+  constructor(options: RotatingTextSinkOptions) {
+    if (!Number.isSafeInteger(options.max_bytes) || options.max_bytes <= 0)
+      throw new Error("invalid text log size limit");
+    const backups = options.backups ?? 3;
+    if (!Number.isSafeInteger(backups) || backups < 1)
+      throw new Error("invalid text log backup limit");
+    this.#options = {
+      ...options,
+      backups,
+      durable: options.durable ?? false,
+    };
+  }
+
+  append(text: string): void {
+    if (this.#closed) throw new Error("text sink is closed");
+    const bytes = Buffer.from(text, "utf8");
+    mkdirSync(dirname(this.#options.path), { recursive: true, mode: 0o700 });
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      let current = existsSync(this.#options.path) ? statSync(this.#options.path).size : 0;
+      if (current >= this.#options.max_bytes) {
+        this.#rotate();
+        current = 0;
+      }
+      const length = Math.min(bytes.byteLength - offset, this.#options.max_bytes - current);
+      const fd = openSync(this.#options.path, "a", 0o600);
+      try {
+        writeSync(fd, bytes.subarray(offset, offset + length));
+        if (this.#options.durable) fdatasyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+      offset += length;
+    }
+  }
+
+  startGeneration(): void {
+    if (this.#closed) throw new Error("text sink is closed");
+    if (existsSync(this.#options.path) && statSync(this.#options.path).size > 0) this.#rotate();
+  }
+
+  flush(): void {}
+  close(): void {
+    this.#closed = true;
+  }
+
+  #rotate(): void {
+    for (let index = this.#options.backups; index >= 1; index -= 1) {
+      const from = index === 1 ? this.#options.path : `${this.#options.path}.${index - 1}`;
+      const to = `${this.#options.path}.${index}`;
+      if (existsSync(from)) renameSync(from, to);
+    }
+  }
+}
+
+/** Spawn a detached-compatible Bun wrapper that continuously rotates child stdout/stderr. */
+export function spawnRotatingProcess(options: RotatingProcessOptions): ChildProcess {
+  const path = resolve(options.path);
+  const sink = new RotatingTextSink({
+    path,
+    max_bytes: options.max_bytes ?? DEFAULT_PROCESS_LOG_BYTES,
+    backups: options.backups ?? DEFAULT_PROCESS_LOG_BACKUPS,
+  });
+  sink.startGeneration();
+  sink.close();
+  const specification = JSON.stringify({
+    path,
+    max_bytes: options.max_bytes ?? DEFAULT_PROCESS_LOG_BYTES,
+    backups: options.backups ?? DEFAULT_PROCESS_LOG_BACKUPS,
+    command: options.command,
+    arguments: options.arguments ?? [],
+  });
+  return spawn("bun", [fileURLToPath(import.meta.url), "--run", specification], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...(options.env ?? process.env) } as NodeJS.ProcessEnv,
+  });
+}
+
+/** Run a short process synchronously while keeping its captured output bounded. */
+export function runRotatingProcessSync(options: RotatingProcessOptions): number | null {
+  const sink = new RotatingTextSink({
+    path: options.path,
+    max_bytes: options.max_bytes ?? DEFAULT_PROCESS_LOG_BYTES,
+    backups: options.backups ?? DEFAULT_PROCESS_LOG_BACKUPS,
+  });
+  sink.startGeneration();
+  const result = spawnSync(options.command, options.arguments ?? [], {
+    encoding: "utf8",
+    env: { ...(options.env ?? process.env) } as NodeJS.ProcessEnv,
+  });
+  if (result.stdout) sink.append(result.stdout);
+  if (result.stderr) sink.append(result.stderr);
+  if (result.error) sink.append(`${result.error.message}\n`);
+  sink.close();
+  return result.status;
+}
+
+async function runProcessLogWorker(raw: string | undefined): Promise<void> {
+  const parsed = JSON.parse(raw ?? "null") as RotatingProcessOptions | null;
+  if (!parsed || typeof parsed.command !== "string" || !Array.isArray(parsed.arguments)) {
+    throw new Error("invalid process log worker specification");
+  }
+  const sink = new RotatingTextSink({
+    path: resolve(parsed.path),
+    max_bytes: parsed.max_bytes ?? DEFAULT_PROCESS_LOG_BYTES,
+    backups: parsed.backups ?? DEFAULT_PROCESS_LOG_BACKUPS,
+  });
+  sink.startGeneration();
+  const child = spawn(parsed.command, parsed.arguments, {
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => sink.append(String(chunk)));
+  child.stderr?.on("data", (chunk) => sink.append(String(chunk)));
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.on(signal, () => child.kill(signal));
+  }
+  const code = await new Promise<number>((resolveExit) => {
+    child.once("error", (error) => {
+      sink.append(`${error.message}\n`);
+      resolveExit(1);
+    });
+    child.once("exit", (exitCode) => resolveExit(exitCode ?? 1));
+  });
+  sink.close();
+  process.exitCode = code;
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
+if (invokedPath === resolve(fileURLToPath(import.meta.url)) && process.argv[2] === "--run") {
+  void runProcessLogWorker(process.argv[3]).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}