@interactive-inc/claude-funnel 0.58.0 → 0.59.0

package/dist/logger.d.ts

@@ -0,0 +1,384 @@
+//#region lib/logger/funnel-log-entry.d.ts
+/**
+ * Wrapper that `FunnelLog.emit` puts around every event before handing it
+ * to a sink. `seq` is monotonic across the lifetime of the underlying store —
+ * sinks persist it as the primary key so replay (and broadcaster seeding
+ * after restart) is an indexed range scan, not a full table walk. `ts` is
+ * epoch milliseconds. `event` is the caller-defined payload validated by the
+ * Zod schema passed to the bus.
+ */
+type FunnelLogEntry<E> = {
+  seq: number;
+  ts: number;
+  event: E;
+};
+//#endregion
+//#region lib/logger/funnel-log-sink.d.ts
+/**
+ * Relay sink. Receives records that already have a `seq` assigned by the
+ * primary and stores or forwards them — memory ring, stdout, network push,
+ * a second SQLite mirror, etc. Does not generate seq itself, so any number
+ * can be attached and they all observe the same monotonic stream.
+ *
+ * `write` returns `void` on success or an `Error` the bus surfaces via
+ * `onSinkError`. Throwing is also tolerated (the bus catches), but
+ * returning is preferred so the failure path is part of the type.
+ */
+type FunnelLogSink<E> = {
+  write(record: FunnelLogEntry<E>): void | Error;
+  close?(): void;
+};
+/**
+ * Primary sink. Owns the canonical seq sequence for the bus. `insert` is
+ * the atomic boundary — it assigns a seq strictly greater than every
+ * previously assigned one, persists the record, and returns it. SQLite
+ * implementations get atomicity for free by delegating to `INTEGER PRIMARY
+ * KEY` so two processes sharing one database file see one monotonic
+ * stream without bus-level coordination.
+ *
+ * `getMaxSeq` is the highest seq currently in the sink — used for
+ * observability and for replay seeding by clients reading the store.
+ */
+type FunnelLogPrimarySink<E> = {
+  insert(input: {
+    ts: number;
+    event: E;
+  }): FunnelLogEntry<E> | Error;
+  getMaxSeq(): number;
+  close?(): void;
+};
+//#endregion
+//#region lib/logger/funnel-log.d.ts
+type Listener<E> = (record: FunnelLogEntry<E>) => void;
+type SinkErrorHandler<E> = (error: Error, record: FunnelLogEntry<E>, sink: FunnelLogSink<E>) => void;
+type FunnelLogValidator<E> = (event: unknown) => {
+  success: true;
+  data: E;
+} | {
+  success: false;
+  error: Error;
+};
+type Props$5<E> = {
+  /** Validates each event before emission. Use `schema.safeParse` from any validation library, or a plain function. */validate: FunnelLogValidator<E>; /** Owns seq assignment + durability. Use `FunnelLogSqliteSink` for multi-process safety. */
+  primary: FunnelLogPrimarySink<E>; /** Optional fanout for already-sequenced records (memory ring, stdout, network mirror). */
+  relays?: ReadonlyArray<FunnelLogSink<E>>; /** Override for tests. Defaults to `Date.now`. */
+  now?: () => number; /** Observer for relay failures. Default: silently swallow. */
+  onSinkError?: SinkErrorHandler<E>;
+};
+/**
+ * Validated event log bus. Three responsibilities and nothing else:
+ * validate the event, delegate seq + persistence to the primary sink, and
+ * fan the resulting record out to relays and live subscribers.
+ *
+ * Splitting "primary" from "relays" makes the seq invariant honest: there
+ * is exactly one source of truth (the primary's atomic insert). Two
+ * `FunnelLog` instances pointed at the same SQLite file therefore see
+ * one monotonic stream without bus-level coordination. Relays mirror
+ * already-sequenced records, so they can be added or removed without
+ * affecting correctness.
+ *
+ * Failure isolation:
+ *   - Primary failure short-circuits emit and is returned to the caller.
+ *   - Relay failures never block the primary path — they surface via the
+ *     optional `onSinkError` callback so the caller can observe without
+ *     being interrupted.
+ *   - A subscriber that throws is contained; the rest of the fanout
+ *     completes normally.
+ */
+declare class FunnelLog<E> {
+  private readonly validate;
+  private readonly primary;
+  private readonly relays;
+  private readonly now;
+  private readonly onSinkError;
+  private readonly listeners;
+  constructor(props: Props$5<E>);
+  emit(event: E): FunnelLogEntry<E> | Error;
+  subscribe(listener: Listener<E>): () => void;
+  getMaxSeq(): number;
+  close(): void;
+  private callPrimary;
+  private fanOutToRelays;
+  private callRelay;
+  private fanOutToListeners;
+  private callClose;
+}
+//#endregion
+//#region lib/logger/funnel-log-sqlite-sink.d.ts
+type IndexValues<I extends ReadonlyArray<string>> = Record<I[number], string | null>;
+/**
+ * Constructor props. The shape narrows on `I`: when no indexes are
+ * declared (the default), `extractIndexes` is forbidden; when indexes
+ * are declared, both `indexes` and `extractIndexes` are required and
+ * `extractIndexes` is type-checked against the index keys.
+ */
+type Props$4<E, I extends ReadonlyArray<string>> = I extends readonly [] ? {
+  path: string;
+  maxRows?: number;
+  maxAgeMs?: number;
+  maxBytes?: number;
+  targetBytes?: number;
+  now?: () => number;
+  indexes?: I;
+  extractIndexes?: never;
+} : {
+  path: string;
+  maxRows?: number;
+  maxAgeMs?: number;
+  maxBytes?: number;
+  targetBytes?: number;
+  now?: () => number;
+  indexes: I;
+  extractIndexes: (event: E) => IndexValues<I>;
+};
+type QueryFilter<I extends ReadonlyArray<string>> = {
+  /** Return only records with seq strictly greater than this. */sinceSeq?: number; /** Filter by the top-level `event.type` discriminator. */
+  type?: string; /** Filter by indexed columns. Keys are constrained to the declared `indexes`. */
+  where?: Partial<IndexValues<I>>; /** Maximum rows returned. Default 1000. */
+  limit?: number;
+  /**
+   * Which end of the seq range to take when `limit` clips the result.
+   * "asc" (default) returns the oldest matching rows; "desc" returns the
+   * newest. Rows are always sorted ascending by seq before returning, so the
+   * caller sees a chronological slice either way — "desc" just picks the tail.
+   */
+  order?: "asc" | "desc";
+};
+/**
+ * SQLite-backed sink built on `bun:sqlite`. Implements both primary and
+ * relay roles so the same instance can own seq generation for one bus and
+ * mirror records from another (e.g. cross-process replication, restore
+ * from a backup stream).
+ *
+ * Concurrency model: seq is `INTEGER PRIMARY KEY`, so SQLite assigns it
+ * atomically via `lastInsertRowid`. Two `FunnelLog` instances pointed
+ * at the same database file therefore see one monotonically increasing
+ * seq stream without any bus-level coordination — the database itself is
+ * the synchronization point.
+ *
+ * Schema is version-managed via `PRAGMA user_version`. Migrations are
+ * append-only and run in a transaction on every construct so a partial
+ * upgrade rolls back cleanly. Caller-defined `indexes` are layered on top
+ * via `ALTER TABLE ADD COLUMN` + `CREATE INDEX IF NOT EXISTS`, so adding
+ * a new index to an existing database is a no-downtime operation.
+ *
+ * Type safety: the second generic parameter `I` is the literal tuple of
+ * index column names. `extractIndexes` and `query({ where })` are
+ * both type-checked against this tuple, so a typo at the call site is a
+ * compile-time error rather than a silent miss at runtime.
+ *
+ * Retention is bounded by `maxRows` and/or `maxAgeMs`. Both run on every
+ * insert as a single indexed DELETE that no-ops below the cap.
+ *
+ * Bulk inserts use `insertMany`, which wraps the batch in one transaction
+ * for ~10–100x throughput at the cost of one fsync per batch instead of
+ * one per row.
+ */
+declare class FunnelLogSqliteSink<E, const I extends ReadonlyArray<string> = readonly []> implements FunnelLogPrimarySink<E>, FunnelLogSink<E> {
+  private readonly db;
+  private readonly maxRows;
+  private readonly maxAgeMs;
+  private readonly maxBytes;
+  private readonly targetBytes;
+  private readonly now;
+  private readonly indexes;
+  private readonly extractIndexes;
+  private readonly insertStmt;
+  private readonly insertWithSeqStmt;
+  private readonly maxSeqStmt;
+  private readonly countStmt;
+  private readonly trimRowsStmt;
+  private readonly trimAgeStmt;
+  private readonly trimOldestStmt;
+  private insertsSinceByteCheck;
+  constructor(props: Props$4<E, I>);
+  insert(input: {
+    ts: number;
+    event: E;
+  }): FunnelLogEntry<E> | Error;
+  insertMany(inputs: ReadonlyArray<{
+    ts: number;
+    event: E;
+  }>): FunnelLogEntry<E>[] | Error;
+  write(record: FunnelLogEntry<E>): void | Error;
+  getMaxSeq(): number;
+  query(props?: QueryFilter<I>): FunnelLogEntry<E>[];
+  /**
+   * Current schema version. Useful for diagnostics and for tests that want
+   * to verify migrations ran. Reads `PRAGMA user_version` once per call.
+   */
+  getSchemaVersion(): number;
+  close(): void;
+  private buildInsertParams;
+  private appendWhereConditions;
+  private trim;
+  /**
+   * Throttled byte-size enforcement. Only every BYTE_CHECK_INTERVAL inserts do
+   * we measure the file; on overflow we estimate how many of the oldest rows to
+   * drop to land near targetBytes (by the byte/row ratio), delete them in one
+   * statement, then VACUUM once to return the freed pages to the filesystem (a
+   * plain DELETE only frees pages inside the file). One DELETE + one VACUUM per
+   * overflow keeps the expensive rewrite rare — the file must refill the whole
+   * maxBytes→targetBytes delta before the next overflow can trigger.
+   */
+  private maybeTrimBytes;
+  private byteSize;
+  /** Drop every row and reclaim the file space. Used by `<log>.clear()`. */
+  clear(): void;
+  private syncIndexColumns;
+  private migrate;
+}
+//#endregion
+//#region lib/logger/funnel-log-memory-sink.d.ts
+type Props$3 = {
+  /** Hard cap on retained records. The oldest is evicted on overflow. 0 disables retention. */capacity?: number;
+};
+/**
+ * In-memory ring buffer that doubles as primary or relay. As primary it
+ * owns its own seq counter (single-process only — for multi-process
+ * safety, use `FunnelLogSqliteSink` as primary and place this as a
+ * relay). As relay it accepts whatever seq the primary assigned and
+ * advances its own counter to match, so `getMaxSeq` stays meaningful.
+ *
+ * Useful as a test double, as a short-window replay buffer paired with a
+ * persistent primary (covering reconnects without round-tripping disk),
+ * or as a backing store for live subscribers.
+ */
+declare class FunnelLogMemorySink<E> implements FunnelLogPrimarySink<E>, FunnelLogSink<E> {
+  private readonly capacity;
+  private readonly buffer;
+  private seq;
+  constructor(props?: Props$3);
+  insert(input: {
+    ts: number;
+    event: E;
+  }): FunnelLogEntry<E>;
+  write(record: FunnelLogEntry<E>): void;
+  getMaxSeq(): number;
+  query(): ReadonlyArray<FunnelLogEntry<E>>;
+  clear(): void;
+  private append;
+}
+//#endregion
+//#region lib/logger/funnel-text-entry.d.ts
+type FunnelTextLevel = "info" | "warn" | "error";
+/**
+ * One human-facing diagnostic log entry. Distinct from `FunnelLogEntry`
+ * (which wraps a schema-validated domain event) — this is the free-form,
+ * for-humans-tailing-a-log shape: a level, a message, and optional meta.
+ *
+ * `meta` is `null` rather than `undefined` when absent so writers can
+ * persist a uniform shape (no missing-key ambiguity in JSON Lines).
+ */
+type FunnelTextEntry = {
+  ts: number;
+  level: FunnelTextLevel;
+  message: string;
+  meta: Record<string, unknown> | null;
+};
+//#endregion
+//#region lib/logger/funnel-text-writer.d.ts
+/**
+ * Plugin port for `FunnelTextLog`. Writers decide where diagnostic
+ * records land — stdout, JSONL file, syslog, network, etc. — without the
+ * logger having to know about persistence shape.
+ *
+ * `write` returns `void` on success or an `Error` the logger surfaces via
+ * `onWriteError`. Throwing is also tolerated; the logger catches.
+ */
+type FunnelTextWriter = {
+  write(record: FunnelTextEntry): void | Error;
+  close?(): void;
+};
+//#endregion
+//#region lib/logger/funnel-text-log.d.ts
+type WriteErrorHandler = (error: Error, record: FunnelTextEntry) => void;
+type Props$2 = {
+  /** Where records go. Use `FunnelTextStdoutWriter`, `FunnelTextFileWriter`, or your own. */writer: FunnelTextWriter; /** Minimum level to emit. Lower-rank records are dropped. Default: "info". */
+  level?: FunnelTextLevel; /** Override for tests. Defaults to `Date.now`. */
+  now?: () => number; /** Observer for writer failures. Default: silently swallow. */
+  onWriteError?: WriteErrorHandler;
+};
+/**
+ * Human-facing diagnostic logger. The companion to `FunnelLog`: where
+ * `FunnelLog` is for schema-validated, replayable domain events,
+ * `FunnelTextLog` is for free-form info/warn/error messages destined
+ * for a human tailing a log or skimming during incident response.
+ *
+ * Keeping the two separate matters operationally:
+ *   - Diagnostics typically out-volume domain events 10–1000x; mixing
+ *     them in the same store would push events out under retention.
+ *   - Diagnostics are unstructured by design; mixing them in would defeat
+ *     the schema-first guarantee that makes domain events replayable.
+ *   - Different audiences and queries (humans grep `tail -f` vs. tools
+ *     query `WHERE seq > ?`).
+ *
+ * The writer is a port. Level gating happens here so writers receive only
+ * what is worth persisting. Failure isolation matches `FunnelLog`: a
+ * writer that throws or returns Error is contained, surfaced via
+ * `onWriteError`, and never blocks the caller.
+ */
+declare class FunnelTextLog {
+  private readonly writer;
+  private readonly minRank;
+  private readonly now;
+  private readonly onWriteError;
+  constructor(props: Props$2);
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+  close(): void;
+  private emit;
+  private callWriter;
+}
+//#endregion
+//#region lib/logger/funnel-text-file-writer.d.ts
+type Props$1 = {
+  /** Filesystem path. Parent directory is created on construct. */path: string;
+  /**
+   * Optional size cap in bytes. When the next write would push the file
+   * over the cap, the existing file becomes `<path>.1` (replacing any
+   * prior `.1`) and a fresh file takes its place. Single-keep rotation —
+   * a second cycle drops the previous `.1`.
+   */
+  maxBytes?: number;
+};
+/**
+ * Appends one JSON line per record to a file. Optional one-keep size
+ * rotation. Designed for diagnostic logs a human tails (`tail -f file |
+ * jq`); not for replay or queries — use `FunnelLogSqliteSink` if you
+ * need indexed lookups.
+ *
+ * Writes are synchronous (`appendFileSync`), so each line is durable
+ * before `write` returns. Throughput matches the OS file cache; for
+ * high-volume logging consider buffering at the call site or using a
+ * different writer.
+ */
+declare class FunnelTextFileWriter implements FunnelTextWriter {
+  private readonly path;
+  private readonly maxBytes;
+  constructor(props: Props$1);
+  write(record: FunnelTextEntry): void | Error;
+  private ensureDir;
+  private rotateIfNeeded;
+}
+//#endregion
+//#region lib/logger/funnel-text-stdout-writer.d.ts
+type Stream = {
+  write(s: string): void;
+};
+type Props = {
+  /** Override for tests. Defaults to `process.stdout`. */out?: Stream;
+};
+/**
+ * Writes one JSON line per record to stdout. Useful as the default writer
+ * for foreground daemons, dev runs, and short-lived processes where a
+ * file-backed log would be overkill.
+ */
+declare class FunnelTextStdoutWriter implements FunnelTextWriter {
+  private readonly out;
+  constructor(props?: Props);
+  write(record: FunnelTextEntry): void;
+}
+//#endregion
+export { FunnelLog, FunnelLogEntry, FunnelLogMemorySink, FunnelLogPrimarySink, FunnelLogSink, FunnelLogSqliteSink, FunnelLogValidator, FunnelTextEntry, FunnelTextFileWriter, FunnelTextLevel, FunnelTextLog, FunnelTextStdoutWriter, FunnelTextWriter };

package/dist/logger.js

@@ -0,0 +1,281 @@
+import { t as FunnelLogSqliteSink } from "./funnel-log-sqlite-sink-B_5_4ybn.js";
+import { dirname } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+//#region lib/logger/funnel-log.ts
+/**
+* Validated event log bus. Three responsibilities and nothing else:
+* validate the event, delegate seq + persistence to the primary sink, and
+* fan the resulting record out to relays and live subscribers.
+*
+* Splitting "primary" from "relays" makes the seq invariant honest: there
+* is exactly one source of truth (the primary's atomic insert). Two
+* `FunnelLog` instances pointed at the same SQLite file therefore see
+* one monotonic stream without bus-level coordination. Relays mirror
+* already-sequenced records, so they can be added or removed without
+* affecting correctness.
+*
+* Failure isolation:
+*   - Primary failure short-circuits emit and is returned to the caller.
+*   - Relay failures never block the primary path — they surface via the
+*     optional `onSinkError` callback so the caller can observe without
+*     being interrupted.
+*   - A subscriber that throws is contained; the rest of the fanout
+*     completes normally.
+*/
+var FunnelLog = class {
+	validate;
+	primary;
+	relays;
+	now;
+	onSinkError;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(props) {
+		this.validate = props.validate;
+		this.primary = props.primary;
+		this.relays = props.relays ?? [];
+		this.now = props.now ?? (() => Date.now());
+		this.onSinkError = props.onSinkError ?? null;
+	}
+	emit(event) {
+		const parsed = this.validate(event);
+		if (!parsed.success) return parsed.error;
+		const result = this.callPrimary(parsed.data);
+		if (result instanceof Error) return result;
+		this.fanOutToRelays(result);
+		this.fanOutToListeners(result);
+		return result;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	getMaxSeq() {
+		return this.primary.getMaxSeq();
+	}
+	close() {
+		this.listeners.clear();
+		this.callClose(this.primary);
+		for (const relay of this.relays) this.callClose(relay);
+	}
+	callPrimary(event) {
+		try {
+			return this.primary.insert({
+				ts: this.now(),
+				event
+			});
+		} catch (e) {
+			return e instanceof Error ? e : new Error(String(e));
+		}
+	}
+	fanOutToRelays(record) {
+		for (const relay of this.relays) {
+			const error = this.callRelay(relay, record);
+			if (!error) continue;
+			if (this.onSinkError) this.onSinkError(error, record, relay);
+		}
+	}
+	callRelay(relay, record) {
+		try {
+			const outcome = relay.write(record);
+			return outcome instanceof Error ? outcome : null;
+		} catch (e) {
+			return e instanceof Error ? e : new Error(String(e));
+		}
+	}
+	fanOutToListeners(record) {
+		for (const listener of this.listeners) try {
+			listener(record);
+		} catch {}
+	}
+	callClose(sink) {
+		if (!sink.close) return;
+		try {
+			sink.close();
+		} catch {}
+	}
+};
+//#endregion
+//#region lib/logger/funnel-log-memory-sink.ts
+/**
+* In-memory ring buffer that doubles as primary or relay. As primary it
+* owns its own seq counter (single-process only — for multi-process
+* safety, use `FunnelLogSqliteSink` as primary and place this as a
+* relay). As relay it accepts whatever seq the primary assigned and
+* advances its own counter to match, so `getMaxSeq` stays meaningful.
+*
+* Useful as a test double, as a short-window replay buffer paired with a
+* persistent primary (covering reconnects without round-tripping disk),
+* or as a backing store for live subscribers.
+*/
+var FunnelLogMemorySink = class {
+	capacity;
+	buffer = [];
+	seq = 0;
+	constructor(props = {}) {
+		this.capacity = Math.max(0, props.capacity ?? 1e3);
+	}
+	insert(input) {
+		this.seq += 1;
+		const record = {
+			seq: this.seq,
+			ts: input.ts,
+			event: input.event
+		};
+		this.append(record);
+		return record;
+	}
+	write(record) {
+		if (record.seq > this.seq) this.seq = record.seq;
+		this.append(record);
+	}
+	getMaxSeq() {
+		return this.seq;
+	}
+	query() {
+		return this.buffer;
+	}
+	clear() {
+		this.buffer.length = 0;
+		this.seq = 0;
+	}
+	append(record) {
+		if (this.capacity === 0) return;
+		this.buffer.push(record);
+		if (this.buffer.length > this.capacity) this.buffer.shift();
+	}
+};
+//#endregion
+//#region lib/logger/funnel-text-log.ts
+const LEVEL_RANK = {
+	info: 0,
+	warn: 1,
+	error: 2
+};
+/**
+* Human-facing diagnostic logger. The companion to `FunnelLog`: where
+* `FunnelLog` is for schema-validated, replayable domain events,
+* `FunnelTextLog` is for free-form info/warn/error messages destined
+* for a human tailing a log or skimming during incident response.
+*
+* Keeping the two separate matters operationally:
+*   - Diagnostics typically out-volume domain events 10–1000x; mixing
+*     them in the same store would push events out under retention.
+*   - Diagnostics are unstructured by design; mixing them in would defeat
+*     the schema-first guarantee that makes domain events replayable.
+*   - Different audiences and queries (humans grep `tail -f` vs. tools
+*     query `WHERE seq > ?`).
+*
+* The writer is a port. Level gating happens here so writers receive only
+* what is worth persisting. Failure isolation matches `FunnelLog`: a
+* writer that throws or returns Error is contained, surfaced via
+* `onWriteError`, and never blocks the caller.
+*/
+var FunnelTextLog = class {
+	writer;
+	minRank;
+	now;
+	onWriteError;
+	constructor(props) {
+		this.writer = props.writer;
+		this.minRank = LEVEL_RANK[props.level ?? "info"];
+		this.now = props.now ?? (() => Date.now());
+		this.onWriteError = props.onWriteError ?? null;
+	}
+	info(message, meta) {
+		this.emit("info", message, meta);
+	}
+	warn(message, meta) {
+		this.emit("warn", message, meta);
+	}
+	error(message, meta) {
+		this.emit("error", message, meta);
+	}
+	close() {
+		if (!this.writer.close) return;
+		try {
+			this.writer.close();
+		} catch {}
+	}
+	emit(level, message, meta) {
+		if (LEVEL_RANK[level] < this.minRank) return;
+		const record = {
+			ts: this.now(),
+			level,
+			message,
+			meta: meta ?? null
+		};
+		const error = this.callWriter(record);
+		if (error && this.onWriteError) this.onWriteError(error, record);
+	}
+	callWriter(record) {
+		try {
+			const outcome = this.writer.write(record);
+			return outcome instanceof Error ? outcome : null;
+		} catch (e) {
+			return e instanceof Error ? e : new Error(String(e));
+		}
+	}
+};
+//#endregion
+//#region lib/logger/funnel-text-file-writer.ts
+/**
+* Appends one JSON line per record to a file. Optional one-keep size
+* rotation. Designed for diagnostic logs a human tails (`tail -f file |
+* jq`); not for replay or queries — use `FunnelLogSqliteSink` if you
+* need indexed lookups.
+*
+* Writes are synchronous (`appendFileSync`), so each line is durable
+* before `write` returns. Throughput matches the OS file cache; for
+* high-volume logging consider buffering at the call site or using a
+* different writer.
+*/
+var FunnelTextFileWriter = class {
+	path;
+	maxBytes;
+	constructor(props) {
+		this.path = props.path;
+		this.maxBytes = props.maxBytes ?? null;
+		this.ensureDir();
+	}
+	write(record) {
+		try {
+			const line = `${JSON.stringify(record)}\n`;
+			this.rotateIfNeeded(Buffer.byteLength(line));
+			appendFileSync(this.path, line);
+		} catch (e) {
+			return e instanceof Error ? e : new Error(String(e));
+		}
+	}
+	ensureDir() {
+		const dir = dirname(this.path);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	}
+	rotateIfNeeded(incomingBytes) {
+		if (this.maxBytes === null) return;
+		if (!existsSync(this.path)) return;
+		if (statSync(this.path).size + incomingBytes <= this.maxBytes) return;
+		const backup = `${this.path}.1`;
+		if (existsSync(backup)) unlinkSync(backup);
+		renameSync(this.path, backup);
+	}
+};
+//#endregion
+//#region lib/logger/funnel-text-stdout-writer.ts
+/**
+* Writes one JSON line per record to stdout. Useful as the default writer
+* for foreground daemons, dev runs, and short-lived processes where a
+* file-backed log would be overkill.
+*/
+var FunnelTextStdoutWriter = class {
+	out;
+	constructor(props = {}) {
+		this.out = props.out ?? process.stdout;
+	}
+	write(record) {
+		this.out.write(`${JSON.stringify(record)}\n`);
+	}
+};
+//#endregion
+export { FunnelLog, FunnelLogMemorySink, FunnelLogSqliteSink, FunnelTextFileWriter, FunnelTextLog, FunnelTextStdoutWriter };