@kar-mi/spirit-vale-tools-logging 0.9.0

package/dist/index.js

@@ -0,0 +1,984 @@
+// @bun
+// src/logger.ts
+import { mkdir, open, readFile, rename, stat, writeFile } from "fs/promises";
+import { Buffer as Buffer2 } from "buffer";
+import path2 from "path";
+
+// src/paths.ts
+import path from "path";
+function defaultLogDirectory(workingDirectory = process.cwd()) {
+  return path.resolve(workingDirectory, "logs");
+}
+function streamCategoryDirectory(stream, logDirectory = defaultLogDirectory()) {
+  return path.join(logDirectory, stream);
+}
+function streamSessionPath(stream, sessionId, logDirectory = defaultLogDirectory()) {
+  return path.join(streamCategoryDirectory(stream, logDirectory), `${sessionId}.jsonl`);
+}
+function currentStreamPointerPath(stream, logDirectory = defaultLogDirectory()) {
+  return path.join(logDirectory, "current", `${stream}.json`);
+}
+
+// src/predicates.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissing(error) {
+  return isRecord(error) && error["code"] === "ENOENT";
+}
+function decimal(value) {
+  return typeof value === "string" && /^-?\d+$/.test(value);
+}
+function nullableString(value) {
+  return value === null || typeof value === "string";
+}
+
+// src/record-codec.ts
+var V2_SEQUENCE_KEY = "seq";
+var V2_TIMESTAMP_KEY = "at";
+function encodeLogRecord(sequence, atMs, type, data) {
+  return JSON.stringify({
+    [V2_SEQUENCE_KEY]: sequence,
+    [V2_TIMESTAMP_KEY]: atMs,
+    type,
+    data
+  });
+}
+function encodeLogStreamHeader(header) {
+  return JSON.stringify(header);
+}
+function isLogStreamHeader(value) {
+  return isRecord(value) && value["schemaVersion"] === 2 && isNonEmptyString(value["sessionId"]);
+}
+function parseLogStreamHeader(value) {
+  if (!isLogStreamHeader(value))
+    return;
+  const candidate = value;
+  if (!isLogStream(candidate["stream"]) || !isNonEmptyString(candidate["producer"]) || !isIsoDate(candidate["startedAt"]))
+    return;
+  return value;
+}
+function parseLogRecord(value, header) {
+  if (!isRecord(value))
+    return;
+  if (value["schemaVersion"] === 1)
+    return parseV1(value);
+  if (isLogStreamHeader(value))
+    return;
+  return parseV2(value, header);
+}
+function parseV1(value) {
+  if (!isNonEmptyString(value["sessionId"]) || !isSequence(value["sequence"]))
+    return;
+  if (!isIsoDate(value["recordedAt"]) || !isNonEmptyString(value["source"]) || !isNonEmptyString(value["type"]))
+    return;
+  if (!isRecord(value["data"]))
+    return;
+  return value;
+}
+function parseV2(value, header) {
+  const sequence = value[V2_SEQUENCE_KEY];
+  const at = value[V2_TIMESTAMP_KEY];
+  if (!isSequence(sequence) || typeof at !== "number" || !Number.isFinite(at))
+    return;
+  if (!isNonEmptyString(value["type"]) || !isRecord(value["data"]))
+    return;
+  return {
+    schemaVersion: 2,
+    sessionId: header?.sessionId ?? "",
+    sequence,
+    recordedAt: new Date(at).toISOString(),
+    source: header?.producer ?? "",
+    type: value["type"],
+    data: value["data"]
+  };
+}
+function isSequence(value) {
+  return Number.isSafeInteger(value) && value >= 1;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isIsoDate(value) {
+  return isNonEmptyString(value) && Number.isFinite(Date.parse(value));
+}
+function isLogStream(value) {
+  return value === "capture" || value === "combat" || value === "rewards" || value === "other";
+}
+
+// src/combat-sanitizer.ts
+var IDENTITY_KEYS = new Set(["kind", "operation", "tick", "actorId", "displayName", "archetype", "ownerConnectionId", "uid"]);
+var COMBAT_KEYS = new Set(["kind", "operation", "tick", "actorId", "mobId", "displayName", "value", "team", "sourceId", "sourceLabel", "recoveryStyle", "hitResult", "duplicatesDamageEvent", "critical", "targetId", "statusId", "level", "action", "phase", "skillId", "stacks", "rpc", "remainingSeconds"]);
+function sanitizeCombatData(type, data) {
+  if (type === "combat.lifecycle" || type === "capture.lifecycle")
+    return pick(data, new Set(["state"]));
+  if (type === "combat.actorIdentity")
+    return pick(data, IDENTITY_KEYS);
+  if (type === "combat.event")
+    return pick(data, COMBAT_KEYS);
+  return;
+}
+function pick(data, keys) {
+  const result = {};
+  for (const key of keys) {
+    const value = data[key];
+    if (value !== undefined && (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null))
+      result[key] = value;
+  }
+  return result;
+}
+
+// src/logger.ts
+var DEFAULT_BATCH_BYTES = 256 * 1024;
+var DEFAULT_FLUSH_INTERVAL_MS = 50;
+var DEFAULT_MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+
+class JsonLinesLogger {
+  path;
+  sessionId;
+  source;
+  options;
+  sequence = 0;
+  lines = [];
+  currentBytes = 0;
+  bufferedBytes = 0;
+  queuedBatches = 0;
+  droppedRecords = 0;
+  timer;
+  tail = Promise.resolve();
+  firstFailure;
+  reportedFailure = false;
+  overflowing = false;
+  closed = false;
+  headerWritten = false;
+  handle;
+  batchBytes;
+  flushIntervalMs;
+  maxBufferedBytes;
+  constructor(path3, sessionId, source, options = { stream: "other" }) {
+    this.path = path3;
+    this.sessionId = sessionId;
+    this.source = source;
+    this.options = options;
+    this.batchBytes = options.batchBytes ?? DEFAULT_BATCH_BYTES;
+    this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    this.maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  }
+  log(type, data) {
+    const safeData = this.options.stream === "combat" ? sanitizeCombatData(type, data) : data;
+    if (!safeData)
+      return;
+    if (this.closed) {
+      this.droppedRecords += 1;
+      return;
+    }
+    this.ensureHeader();
+    const line = `${encodeLogRecord(++this.sequence, Date.now(), type, safeData)}
+`;
+    const bytes = Buffer2.byteLength(line);
+    if (this.bufferedBytes + bytes > this.maxBufferedBytes) {
+      this.droppedRecords += 1;
+      if (!this.overflowing) {
+        this.overflowing = true;
+        this.notify(new Error(`log buffer exceeded ${this.maxBufferedBytes} bytes; records are being dropped`));
+      }
+      return;
+    }
+    this.overflowing = false;
+    this.lines.push(line);
+    this.currentBytes += bytes;
+    this.bufferedBytes += bytes;
+    if (this.currentBytes >= this.batchBytes)
+      this.enqueueCurrent();
+    else
+      this.scheduleFlush();
+  }
+  async flush() {
+    this.enqueueCurrent();
+    await this.tail;
+    if (this.firstFailure)
+      throw this.firstFailure;
+  }
+  async close() {
+    if (this.closed) {
+      await this.tail;
+      if (this.firstFailure)
+        throw this.firstFailure;
+      return;
+    }
+    this.closed = true;
+    this.enqueueCurrent();
+    await this.tail;
+    const handle = this.handle;
+    this.handle = undefined;
+    if (handle)
+      await handle.then((open2) => open2.close(), () => {
+        return;
+      });
+    if (this.firstFailure)
+      throw this.firstFailure;
+  }
+  stats() {
+    return {
+      bufferedBytes: this.bufferedBytes,
+      queuedBatches: this.queuedBatches,
+      failed: this.firstFailure !== undefined,
+      droppedRecords: this.droppedRecords
+    };
+  }
+  ensureHeader() {
+    if (this.headerWritten)
+      return;
+    this.headerWritten = true;
+    const header = {
+      schemaVersion: 2,
+      stream: this.options.stream,
+      sessionId: this.sessionId,
+      producer: this.source,
+      startedAt: new Date().toISOString()
+    };
+    const line = `${encodeLogStreamHeader(header)}
+`;
+    const bytes = Buffer2.byteLength(line);
+    this.lines.push(line);
+    this.currentBytes += bytes;
+    this.bufferedBytes += bytes;
+  }
+  scheduleFlush() {
+    if (this.timer)
+      return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.enqueueCurrent();
+    }, this.flushIntervalMs);
+  }
+  enqueueCurrent() {
+    if (this.timer)
+      clearTimeout(this.timer);
+    this.timer = undefined;
+    if (this.lines.length === 0)
+      return;
+    const text = this.lines.join("");
+    const bytes = this.currentBytes;
+    this.lines = [];
+    this.currentBytes = 0;
+    this.queuedBatches += 1;
+    this.tail = this.tail.then(() => this.write(text)).catch((error) => {
+      const failure = toError(error);
+      this.firstFailure ??= failure;
+      if (!this.reportedFailure) {
+        this.reportedFailure = true;
+        this.notify(failure);
+      }
+    }).finally(() => {
+      this.bufferedBytes = Math.max(0, this.bufferedBytes - bytes);
+      this.queuedBatches = Math.max(0, this.queuedBatches - 1);
+    });
+  }
+  async write(text) {
+    if (this.options.append) {
+      await this.options.append(this.path, text, "utf8");
+      return;
+    }
+    this.handle ??= open(this.path, "a");
+    let handle;
+    try {
+      handle = await this.handle;
+    } catch (error) {
+      this.handle = undefined;
+      throw error;
+    }
+    await handle.appendFile(text, "utf8");
+  }
+  notify(error) {
+    try {
+      this.options.onWriteError?.({ stream: this.options.stream, path: this.path, error });
+    } catch {}
+  }
+}
+async function ensureDirectory(directory) {
+  try {
+    if ((await stat(directory)).isDirectory())
+      return;
+  } catch {}
+  try {
+    await mkdir(directory, { recursive: true });
+  } catch (error) {
+    if (error.code !== "EEXIST")
+      throw error;
+  }
+}
+async function createLogSession(options) {
+  const logDirectory = options.logDirectory ?? defaultLogDirectory();
+  const id = createSessionId();
+  const createdAt = new Date().toISOString();
+  const streams = [...new Set(options.streams)];
+  if (streams.length === 0)
+    throw new Error("a log session requires at least one stream");
+  const activate = options.activate ?? true;
+  const loggers = new Map;
+  for (const stream of streams) {
+    const override = options.outputPaths?.[stream];
+    const streamPath = override ?? streamSessionPath(stream, id, logDirectory);
+    await ensureDirectory(path2.dirname(streamPath));
+    await writeFile(streamPath, "", override ? undefined : { flag: "wx" });
+    loggers.set(stream, new JsonLinesLogger(streamPath, id, options.producer, {
+      stream,
+      onWriteError: options.onWriteError,
+      ...tuning(options)
+    }));
+    if (!override && activate) {
+      const pointer = {
+        schemaVersion: 1,
+        stream,
+        sessionId: id,
+        startedAt: createdAt,
+        relativePath: path2.relative(logDirectory, streamPath)
+      };
+      await writeAtomicJson(currentStreamPointerPath(stream, logDirectory), pointer);
+    }
+  }
+  return {
+    id,
+    logger(stream) {
+      const logger = loggers.get(stream);
+      if (!logger)
+        throw new Error(`stream ${stream} is not part of session ${id}`);
+      return logger;
+    },
+    async flush() {
+      await settleAll([...loggers.values()].map((logger) => logger.flush()));
+    },
+    async close() {
+      await settleAll([...loggers.values()].map((logger) => logger.close()));
+    }
+  };
+}
+async function writeCurrentLogStreamPointer(pointer, logDirectory = defaultLogDirectory()) {
+  await writeAtomicJson(currentStreamPointerPath(pointer.stream, logDirectory), pointer);
+}
+async function activateLogSession(session, streams, logDirectory = defaultLogDirectory()) {
+  await session.flush?.();
+  const startedAt = new Date().toISOString();
+  for (const stream of streams) {
+    const streamPath = streamSessionPath(stream, session.id, logDirectory);
+    const pointer = {
+      schemaVersion: 1,
+      stream,
+      sessionId: session.id,
+      startedAt,
+      relativePath: path2.relative(logDirectory, streamPath)
+    };
+    await writeCurrentLogStreamPointer(pointer, logDirectory);
+  }
+}
+async function readCurrentLogStream(stream, logDirectory = defaultLogDirectory()) {
+  let value;
+  try {
+    value = JSON.parse(await readFile(currentStreamPointerPath(stream, logDirectory), "utf8"));
+  } catch (error) {
+    if (isMissing(error) || error instanceof SyntaxError)
+      return;
+    throw error;
+  }
+  if (!isRecord(value) || value["schemaVersion"] !== 1 || value["stream"] !== stream || !isNonEmptyString2(value["sessionId"]) || !isIsoDate2(value["startedAt"]) || !isNonEmptyString2(value["relativePath"]))
+    return;
+  const resolved = path2.resolve(logDirectory, value["relativePath"]);
+  const root = `${path2.resolve(logDirectory)}${path2.sep}`;
+  if (!resolved.startsWith(root))
+    return;
+  return { ...value, path: resolved };
+}
+function tuning(options) {
+  return {
+    ...options.batchBytes === undefined ? {} : { batchBytes: options.batchBytes },
+    ...options.flushIntervalMs === undefined ? {} : { flushIntervalMs: options.flushIntervalMs },
+    ...options.maxBufferedBytes === undefined ? {} : { maxBufferedBytes: options.maxBufferedBytes }
+  };
+}
+async function settleAll(operations) {
+  const results = await Promise.allSettled(operations);
+  const rejected = results.find((result) => result.status === "rejected");
+  if (rejected)
+    throw toError(rejected.reason);
+}
+function createSessionId() {
+  const timestamp = new Date().toISOString().replace(/[-:.]/g, "").replace("Z", "Z");
+  return `${timestamp}-${crypto.randomUUID().slice(0, 8)}`;
+}
+async function writeAtomicJson(target, value) {
+  await ensureDirectory(path2.dirname(target));
+  const temporary = `${target}.${crypto.randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  await rename(temporary, target);
+}
+function isNonEmptyString2(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isIsoDate2(value) {
+  return isNonEmptyString2(value) && Number.isFinite(Date.parse(value));
+}
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+// src/sessions.ts
+import { lstat, open as open2, readFile as readFile2, readdir } from "fs/promises";
+import path3 from "path";
+var HEADER_PROBE_BYTES = 4096;
+async function listLogSessions(stream, logDirectory = defaultLogDirectory(), limit = 25) {
+  if (!Number.isSafeInteger(limit) || limit < 0)
+    throw new RangeError("session limit must be a non-negative integer");
+  const categoryDirectory = streamCategoryDirectory(stream, logDirectory);
+  let entries;
+  try {
+    entries = await readdir(categoryDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (isMissing(error))
+      return [];
+    throw error;
+  }
+  const current = await readCurrentPointer(stream, logDirectory);
+  const sessions = await Promise.all(entries.map(async (entry) => {
+    if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith(".jsonl"))
+      return;
+    const sessionId = entry.name.slice(0, -".jsonl".length);
+    const filePath = path3.join(categoryDirectory, entry.name);
+    try {
+      const info = await lstat(filePath);
+      if (!info.isFile() || info.isSymbolicLink())
+        return;
+      const header = await readHeaderLine(filePath);
+      if (header && (header.sessionId !== sessionId || header.stream !== stream))
+        return;
+      const createdAt = header?.startedAt ?? info.mtime.toISOString();
+      return {
+        id: sessionId,
+        createdAt,
+        path: filePath,
+        active: current?.sessionId === sessionId && current.path === path3.resolve(filePath)
+      };
+    } catch {
+      return;
+    }
+  }));
+  return sessions.filter((session) => session !== undefined).sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt) || right.id.localeCompare(left.id)).slice(0, limit);
+}
+async function readHeaderLine(filePath) {
+  let handle;
+  try {
+    handle = await open2(filePath, "r");
+  } catch {
+    return;
+  }
+  try {
+    const buffer = Buffer.alloc(HEADER_PROBE_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, HEADER_PROBE_BYTES, 0);
+    const text = buffer.toString("utf8", 0, bytesRead);
+    const newline = text.indexOf(`
+`);
+    const line = newline === -1 ? text : text.slice(0, newline);
+    if (!line.trim())
+      return;
+    return parseLogStreamHeader(JSON.parse(line));
+  } catch {
+    return;
+  } finally {
+    await handle.close();
+  }
+}
+async function readCurrentPointer(stream, logDirectory) {
+  try {
+    const value = JSON.parse(await readFile2(currentStreamPointerPath(stream, logDirectory), "utf8"));
+    if (!isRecord(value) || value["schemaVersion"] !== 1 || value["stream"] !== stream || typeof value["sessionId"] !== "string" || typeof value["startedAt"] !== "string" || !Number.isFinite(Date.parse(value["startedAt"])) || typeof value["relativePath"] !== "string")
+      return;
+    const resolved = path3.resolve(logDirectory, value["relativePath"]);
+    const root = `${path3.resolve(logDirectory)}${path3.sep}`;
+    if (!resolved.startsWith(root))
+      return;
+    return { ...value, path: resolved };
+  } catch {
+    return;
+  }
+}
+// src/jsonl-tail-reader.ts
+import { open as open3, stat as stat2 } from "fs/promises";
+var NEWLINE = 10;
+
+class JsonlTailReader {
+  path;
+  readOffset;
+  partialBytes = 0;
+  pending = "";
+  decoder;
+  createDecoder;
+  maxReadBytes;
+  constructor(path4, options = {}) {
+    this.path = path4;
+    this.createDecoder = options.createDecoder ?? (() => new TextDecoder);
+    const startOffset = options.startOffset ?? 0;
+    if (!Number.isSafeInteger(startOffset) || startOffset < 0) {
+      throw new RangeError("startOffset must be a non-negative integer");
+    }
+    const maxReadBytes = options.maxReadBytes ?? Number.POSITIVE_INFINITY;
+    if (maxReadBytes < 1)
+      throw new RangeError("maxReadBytes must be at least 1");
+    this.maxReadBytes = maxReadBytes;
+    this.readOffset = startOffset;
+  }
+  get offset() {
+    return this.readOffset - this.partialBytes;
+  }
+  get bytePosition() {
+    return this.readOffset;
+  }
+  async read(limitBytes = Number.POSITIVE_INFINITY) {
+    let size;
+    try {
+      size = (await stat2(this.path)).size;
+    } catch (error) {
+      if (isMissing(error))
+        return { missing: true, reset: false, lines: [], size: this.offset, bytesRead: 0 };
+      throw error;
+    }
+    const reset = size < this.readOffset;
+    if (reset)
+      this.reset();
+    if (size === this.readOffset)
+      return { missing: false, reset, lines: [], size, bytesRead: 0 };
+    const length = Math.min(size - this.readOffset, this.maxReadBytes, limitBytes);
+    if (length < 1)
+      return { missing: false, reset, lines: [], size, bytesRead: 0 };
+    const bytes = Buffer.allocUnsafe(length);
+    const file = await open3(this.path, "r");
+    try {
+      const { bytesRead } = await file.read(bytes, 0, length, this.readOffset);
+      this.readOffset += bytesRead;
+      const chunk = bytes.subarray(0, bytesRead);
+      this.trackPartial(chunk);
+      return { missing: false, reset, lines: this.consume(chunk), size, bytesRead };
+    } finally {
+      await file.close();
+    }
+  }
+  reset() {
+    this.readOffset = 0;
+    this.partialBytes = 0;
+    this.pending = "";
+    this.decoder = undefined;
+  }
+  trackPartial(chunk) {
+    const lastNewline = chunk.lastIndexOf(NEWLINE);
+    this.partialBytes = lastNewline === -1 ? this.partialBytes + chunk.length : chunk.length - lastNewline - 1;
+  }
+  consume(bytes) {
+    this.decoder ??= this.createDecoder(bytes);
+    this.pending += this.decoder.decode(bytes, { stream: true });
+    const lines = this.pending.split(/\r?\n/);
+    this.pending = lines.pop() ?? "";
+    return lines;
+  }
+}
+// src/stream-source.ts
+import { watch } from "fs";
+import path4 from "path";
+var DEFAULT_STREAM_DEBOUNCE_MS = 20;
+var DEFAULT_STREAM_FALLBACK_POLL_MS = 1000;
+var DEFAULT_STREAM_BATCH_BYTES = 1024 * 1024;
+
+class LogStreamSource {
+  stream;
+  logDirectory;
+  pointerPath;
+  fallbackPollMs;
+  debounceMs;
+  persistent;
+  readerOptions;
+  subscribers = new Set;
+  current;
+  reader;
+  pointerLoaded = false;
+  pointerDirty = true;
+  pointerWatcher;
+  fileWatcher;
+  debounceTimer;
+  fallbackTimer;
+  draining;
+  waiting = 0;
+  closed = false;
+  constructor(options) {
+    this.stream = options.stream;
+    this.logDirectory = options.logDirectory ?? defaultLogDirectory();
+    this.pointerPath = currentStreamPointerPath(this.stream, this.logDirectory);
+    this.fallbackPollMs = options.fallbackPollMs ?? DEFAULT_STREAM_FALLBACK_POLL_MS;
+    this.debounceMs = options.debounceMs ?? DEFAULT_STREAM_DEBOUNCE_MS;
+    this.persistent = options.persistent ?? false;
+    this.readerOptions = options.readerOptions ?? {};
+  }
+  subscribe() {
+    const subscriber = new Subscriber(this);
+    subscriber.catchUpFrom = this.reader === undefined ? undefined : this.reader.bytePosition;
+    this.subscribers.add(subscriber);
+    this.start();
+    return subscriber;
+  }
+  release(subscriber) {
+    if (!this.subscribers.delete(subscriber))
+      return;
+    if (this.subscribers.size === 0)
+      this.dispose();
+  }
+  async drain() {
+    this.draining ??= this.runDrain().finally(() => {
+      this.draining = undefined;
+    });
+    await this.draining;
+  }
+  async forceDrain() {
+    this.pointerDirty = true;
+    await this.drain();
+    if (this.pointerDirty)
+      await this.drain();
+  }
+  start() {
+    if (this.closed || this.fallbackTimer)
+      return;
+    this.ensurePointerWatcher();
+    this.fallbackTimer = this.hold(setInterval(() => void this.forceDrain(), this.fallbackPollMs));
+  }
+  hold(timer) {
+    if (!this.persistent && this.waiting === 0)
+      timer.unref?.();
+    return timer;
+  }
+  awaitingChanged(delta) {
+    this.waiting += delta;
+    if (this.persistent || !this.fallbackTimer)
+      return;
+    if (this.waiting > 0)
+      this.fallbackTimer.ref?.();
+    else if (this.waiting === 0)
+      this.fallbackTimer.unref?.();
+  }
+  dispose() {
+    this.closed = true;
+    releaseSource(this);
+    if (this.fallbackTimer)
+      clearInterval(this.fallbackTimer);
+    if (this.debounceTimer)
+      clearTimeout(this.debounceTimer);
+    this.fallbackTimer = undefined;
+    this.debounceTimer = undefined;
+    this.pointerWatcher?.close();
+    this.fileWatcher?.close();
+    this.pointerWatcher = undefined;
+    this.fileWatcher = undefined;
+  }
+  schedule() {
+    if (this.closed || this.debounceTimer)
+      return;
+    this.debounceTimer = this.hold(setTimeout(() => {
+      this.debounceTimer = undefined;
+      this.drain();
+    }, this.debounceMs));
+  }
+  async runDrain() {
+    if (this.closed)
+      return;
+    const changedSession = await this.syncPointer();
+    if (!this.reader) {
+      if (changedSession) {
+        this.publish({ missing: true, reset: false, lines: [], size: 0, bytesRead: 0, changedSession, capped: false });
+      }
+      return;
+    }
+    const result = await this.reader.read();
+    const capped = result.bytesRead > 0 && this.reader.bytePosition < result.size;
+    if (!changedSession && !result.reset && !result.missing && result.lines.length === 0)
+      return;
+    this.publish({ ...result, changedSession, capped, ...this.current ? { current: this.current } : {} });
+    if (capped)
+      this.schedule();
+  }
+  async syncPointer() {
+    if (this.pointerLoaded && !this.pointerDirty)
+      return false;
+    this.pointerDirty = false;
+    this.pointerLoaded = true;
+    const pointer = await readCurrentLogStream(this.stream, this.logDirectory);
+    if (!pointer) {
+      if (!this.current)
+        return false;
+      this.current = undefined;
+      this.reader = undefined;
+      this.fileWatcher?.close();
+      this.fileWatcher = undefined;
+      return true;
+    }
+    if (pointer.sessionId === this.current?.sessionId)
+      return false;
+    this.current = { path: pointer.path, sessionId: pointer.sessionId };
+    this.reader = new JsonlTailReader(pointer.path, this.readerOptions);
+    for (const subscriber of this.subscribers)
+      subscriber.catchUpFrom = undefined;
+    this.watchActiveFile(pointer.path);
+    return true;
+  }
+  publish(read) {
+    for (const subscriber of this.subscribers)
+      subscriber.push(read);
+  }
+  ensurePointerWatcher() {
+    if (this.pointerWatcher || this.closed)
+      return;
+    const directory = path4.dirname(this.pointerPath);
+    const name = path4.basename(this.pointerPath);
+    this.pointerWatcher = this.tryWatch(directory, (filename) => {
+      if (filename === null || filename === name) {
+        this.pointerDirty = true;
+        this.schedule();
+      }
+    });
+  }
+  watchActiveFile(activePath) {
+    this.fileWatcher?.close();
+    this.fileWatcher = this.tryWatch(activePath, () => this.schedule());
+  }
+  tryWatch(target, onEvent) {
+    let watcher;
+    try {
+      watcher = watch(target, { persistent: this.persistent }, (_event, filename) => {
+        onEvent(typeof filename === "string" ? filename : null);
+      });
+    } catch (error) {
+      if (isMissing(error))
+        return;
+      throw error;
+    }
+    watcher.on("error", () => watcher.close());
+    return watcher;
+  }
+  async catchUp(subscriber) {
+    const target = subscriber.catchUpFrom;
+    if (target === undefined || !this.current)
+      return [];
+    const reader = new JsonlTailReader(this.current.path, this.readerOptions);
+    const reads = [];
+    while (reader.bytePosition < target) {
+      const result = await reader.read(target - reader.bytePosition);
+      if (result.missing || result.bytesRead === 0)
+        break;
+      reads.push({ ...result, changedSession: false, capped: false, current: this.current });
+    }
+    subscriber.catchUpFrom = undefined;
+    if (reads.length > 0)
+      reads[0].changedSession = true;
+    return reads;
+  }
+  emptyRead() {
+    return {
+      missing: this.current === undefined,
+      reset: false,
+      lines: [],
+      size: this.reader?.offset ?? 0,
+      bytesRead: 0,
+      changedSession: false,
+      capped: false,
+      ...this.current ? { current: this.current } : {}
+    };
+  }
+  get loaded() {
+    return this.pointerLoaded;
+  }
+}
+
+class Subscriber {
+  source;
+  catchUpFrom;
+  replayQueue = [];
+  pending;
+  waiter;
+  closed = false;
+  constructor(source) {
+    this.source = source;
+  }
+  push(read) {
+    if (this.closed)
+      return;
+    this.pending = this.pending ? mergeReads(this.pending, read) : read;
+    const waiter = this.waiter;
+    if (!waiter)
+      return;
+    this.waiter = undefined;
+    waiter(this.take());
+  }
+  async poll() {
+    if (this.closed)
+      return this.source.emptyRead();
+    const replayed = await this.replay();
+    if (replayed)
+      return replayed;
+    await this.source.forceDrain();
+    return this.take() ?? this.source.emptyRead();
+  }
+  async next() {
+    if (this.closed)
+      return this.source.emptyRead();
+    const replayed = await this.replay();
+    if (replayed)
+      return replayed;
+    if (!this.source.loaded)
+      await this.source.drain();
+    const taken = this.take();
+    if (taken)
+      return taken;
+    this.source.awaitingChanged(1);
+    try {
+      return await new Promise((resolve) => {
+        this.waiter = resolve;
+      });
+    } finally {
+      this.source.awaitingChanged(-1);
+    }
+  }
+  async* [Symbol.asyncIterator]() {
+    while (!this.closed)
+      yield await this.next();
+  }
+  close() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    this.waiter?.(this.source.emptyRead());
+    this.waiter = undefined;
+    this.source.release(this);
+  }
+  async replay() {
+    if (this.catchUpFrom === undefined)
+      return;
+    if (this.replayQueue.length === 0)
+      this.replayQueue = await this.source.catchUp(this);
+    return this.replayQueue.shift();
+  }
+  take() {
+    const pending = this.pending;
+    this.pending = undefined;
+    return pending;
+  }
+}
+function mergeReads(previous, next) {
+  const changedSession = previous.changedSession || next.changedSession;
+  if (next.reset)
+    return { ...next, changedSession };
+  return {
+    ...next,
+    lines: previous.lines.concat(next.lines),
+    reset: previous.reset,
+    changedSession,
+    bytesRead: previous.bytesRead + next.bytesRead
+  };
+}
+var sources = new Map;
+var keys = new WeakMap;
+function subscribeToLogStream(options) {
+  const key = `${options.logDirectory ?? defaultLogDirectory()}\x00${options.stream}`;
+  let source = sources.get(key);
+  if (!source) {
+    source = new LogStreamSource(options);
+    sources.set(key, source);
+    keys.set(source, key);
+  }
+  return source.subscribe();
+}
+function releaseSource(source) {
+  const key = keys.get(source);
+  if (key !== undefined && sources.get(key) === source)
+    sources.delete(key);
+}
+
+// src/session-follower.ts
+class LiveLogSessionFollower {
+  options;
+  sessionId;
+  follower;
+  subscription;
+  closed = false;
+  constructor(options) {
+    this.options = options;
+  }
+  async poll() {
+    return this.apply(await this.source().poll());
+  }
+  async next() {
+    return this.apply(await this.source().next());
+  }
+  async* [Symbol.asyncIterator]() {
+    this.closed = false;
+    while (!this.closed) {
+      const read = await this.source().next();
+      if (this.closed)
+        return;
+      yield this.apply(read);
+    }
+  }
+  close() {
+    this.closed = true;
+    this.subscription?.close();
+    this.subscription = undefined;
+  }
+  source() {
+    this.subscription ??= subscribeToLogStream({
+      stream: this.options.stream,
+      ...this.options.logDirectory === undefined ? {} : { logDirectory: this.options.logDirectory },
+      ...this.options.fallbackPollMs === undefined ? {} : { fallbackPollMs: this.options.fallbackPollMs },
+      ...this.options.debounceMs === undefined ? {} : { debounceMs: this.options.debounceMs },
+      ...this.options.persistent === undefined ? {} : { persistent: this.options.persistent },
+      ...this.options.readerOptions === undefined ? {} : { readerOptions: this.options.readerOptions }
+    });
+    return this.subscription;
+  }
+  apply(read) {
+    if (!read.current) {
+      const reset = this.follower !== undefined;
+      this.follower = undefined;
+      this.sessionId = undefined;
+      return this.options.noStreamBatch(reset);
+    }
+    const changedSession = read.current.sessionId !== this.sessionId;
+    if (changedSession) {
+      this.sessionId = read.current.sessionId;
+      this.follower = this.options.createFollower(read.current.path);
+    }
+    const batch = this.follower.consumeRead(read);
+    const merged = this.options.mergeSessionChange(batch, changedSession);
+    return { ...merged, path: read.current.path, sessionId: read.current.sessionId };
+  }
+}
+export {
+  DEFAULT_STREAM_BATCH_BYTES,
+  DEFAULT_STREAM_DEBOUNCE_MS,
+  DEFAULT_STREAM_FALLBACK_POLL_MS,
+  JsonLinesLogger,
+  JsonlTailReader,
+  LiveLogSessionFollower,
+  activateLogSession,
+  createLogSession,
+  currentStreamPointerPath,
+  decimal,
+  defaultLogDirectory,
+  encodeLogRecord,
+  encodeLogStreamHeader,
+  isLogStreamHeader,
+  isMissing,
+  isRecord,
+  listLogSessions,
+  nullableString,
+  parseLogRecord,
+  parseLogStreamHeader,
+  readCurrentLogStream,
+  sanitizeCombatData,
+  streamCategoryDirectory,
+  streamSessionPath,
+  subscribeToLogStream,
+  writeCurrentLogStreamPointer
+};