@kindgi/log 0.0.0-bootstrap.0 → 0.1.4-rc.5

package/dist/levels.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Log levels, most severe first. A level says how much attention a line
+ * needs: `error` (an operator should look), `warn` (unexpected but
+ * handled), `info` (what happened, at the operator's grain), `debug` (the
+ * decisions behind it), `trace` (internals, briefly).
+ */
+export const LOG_LEVELS = ['error', 'warn', 'info', 'debug', 'trace'];
+const RANK = {
+    error: 50,
+    warn: 40,
+    info: 30,
+    debug: 20,
+    trace: 10,
+};
+/** Cloud Logging's severity names: Cloud Run and GKE show levels with no agent configuration. */
+export const SEVERITY = {
+    error: 'ERROR',
+    warn: 'WARNING',
+    info: 'INFO',
+    debug: 'DEBUG',
+    trace: 'DEBUG',
+};
+/** Whether a record at `level` is written by a logger at `threshold`. */
+export function levelEnabled(level, threshold) {
+    return RANK[level] >= RANK[threshold];
+}
+/** A level's name, case and spaces aside; `undefined` when it isn't one. */
+export function parseLogLevel(raw) {
+    const value = raw.trim().toLowerCase();
+    return LOG_LEVELS.includes(value) ? value : undefined;
+}
+/**
+ * Per-subsystem levels, `KINDGI_LOG_LEVELS`'s form: a comma list of
+ * `subsystem=level`, such as `kernel=debug,http=warn`. Empty is none. An
+ * entry that isn't `name=level`, or names no known level, is an error that
+ * quotes it. Whether a subsystem exists is the caller's question.
+ */
+export function parseLogLevels(raw) {
+    const levels = {};
+    for (const entry of raw.split(',')) {
+        const trimmed = entry.trim();
+        if (trimmed === '')
+            continue;
+        const eq = trimmed.indexOf('=');
+        const subsystem = eq === -1 ? '' : trimmed.slice(0, eq).trim();
+        const level = eq === -1 ? undefined : parseLogLevel(trimmed.slice(eq + 1));
+        if (subsystem === '' || level === undefined) {
+            return {
+                kind: 'err',
+                message: `"${trimmed}" isn't subsystem=level (levels: ${LOG_LEVELS.join(', ')})`,
+            };
+        }
+        levels[subsystem] = level;
+    }
+    return { kind: 'ok', levels };
+}
+/**
+ * The level for `subsystem`: its own entry, else its nearest dotted
+ * parent's (`kernel=debug` covers `kernel.sweeper`), else `fallback`.
+ */
+export function levelFor(subsystem, levels, fallback) {
+    let name = subsystem;
+    for (;;) {
+        const own = levels[name];
+        if (own !== undefined)
+            return own;
+        const dot = name.lastIndexOf('.');
+        if (dot === -1)
+            return fallback;
+        name = name.slice(0, dot);
+    }
+}
+//# sourceMappingURL=levels.js.map

package/dist/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../src/levels.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAI/E,MAAM,IAAI,GAAuC;IAC/C,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,iGAAiG;AACjG,MAAM,CAAC,MAAM,QAAQ,GAAuC;IAC1D,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,KAAe,EAAE,SAAmB;IAC/D,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,OAAQ,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAkB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F,CAAC;AAMD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,MAAM,GAA6B,EAAE,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO,KAAK,EAAE;YAAE,SAAS;QAC7B,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,SAAS,KAAK,EAAE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5C,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,OAAO,EAAE,IAAI,OAAO,oCAAoC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;aACjF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC;IAC5B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,SAAiB,EACjB,MAA0C,EAC1C,QAAkB;IAElB,IAAI,IAAI,GAAG,SAAS,CAAC;IACrB,SAAS,CAAC;QACR,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,QAAQ,CAAC;QAChC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,28 @@
+import { type LogLevel } from './levels.js';
+import type { LogFormat, Logger } from './types.js';
+export interface CreateLoggerOptions {
+    /** Records below this level aren't written (`KINDGI_LOG_LEVEL`). Default `info`. */
+    readonly level?: LogLevel;
+    /** Per-subsystem levels; a dotted name inherits its parent's (`KINDGI_LOG_LEVELS`). */
+    readonly levels?: Readonly<Record<string, LogLevel>>;
+    /** `json` (one record per line) or `pretty` (for a terminal). Default `json`. */
+    readonly format?: LogFormat;
+    /** Colours in the pretty format (a terminal, `NO_COLOR` unset). Default off. */
+    readonly color?: boolean;
+    /** Where each line goes: one complete line, no trailing newline. */
+    readonly write: (line: string) => void;
+    /** More field keys to redact, on top of the built-in ones. */
+    readonly redact?: readonly string[];
+    /** The records' subsystem until a child names one. Default `root`. */
+    readonly subsystem?: string;
+    /** The clock (tests). */
+    readonly now?: () => Date;
+}
+/**
+ * A logger: records at or above its level (per subsystem, `levels`) are
+ * redacted and written to `write` as JSON or pretty lines. Logging never
+ * throws, and a failing sink is ignored.
+ */
+export declare function createLogger(options: CreateLoggerOptions): Logger;
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,QAAQ,EAAoC,MAAM,aAAa,CAAC;AAE9E,OAAO,KAAK,EAEV,SAAS,EAGT,MAAM,EAEP,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACrD,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AA8HD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAWjE;AAKD,eAAO,MAAM,UAAU,EAAE,MAQxB,CAAC"}

package/dist/logger.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { formatJson, formatPretty } from './format.js';
+import { SEVERITY, levelEnabled, levelFor } from './levels.js';
+import { redactValue, scrubText } from './redact.js';
+/** Correlation fields, in the order a record carries them, after the fixed five. */
+const CORRELATION = [
+    'traceId',
+    'spanId',
+    'runTraceId',
+    'requestId',
+    'tenantId',
+    'projectId',
+    'orgId',
+    'runId',
+    'parentRunId',
+    'agentId',
+    'agentVersion',
+    'flowId',
+    'flowVersion',
+    'toolId',
+    'conversationId',
+    'approvalId',
+];
+const FIXED = new Set(['time', 'level', 'severity', 'subsystem', 'message']);
+function serializeError(err, withStack, depth = 0) {
+    if (!(err instanceof Error))
+        return scrubText(String(err));
+    const code = err.code;
+    const cause = err.cause;
+    return {
+        name: err.name,
+        message: scrubText(err.message),
+        ...(typeof code === 'string' || typeof code === 'number' ? { code: String(code) } : {}),
+        ...(withStack && err.stack !== undefined && { stack: scrubText(err.stack) }),
+        ...(cause !== undefined && depth < 3 && { cause: serializeError(cause, withStack, depth + 1) }),
+    };
+}
+/**
+ * Copy a record's own fields into `out`, after the fixed five and the
+ * correlation ones; an `Error` among them is serialized. A field named
+ * like one of the fixed five can't replace it: it comes back to be kept
+ * under `fields`.
+ */
+function copyFields(out, merged, level) {
+    const reserved = {};
+    for (const [key, value] of Object.entries(merged)) {
+        if (value === undefined || key === 'subsystem' || key === 'err')
+            continue;
+        if (CORRELATION.includes(key))
+            continue;
+        if (FIXED.has(key))
+            reserved[key] = value;
+        else
+            out[key] = value instanceof Error ? serializeError(value, level === 'error') : value;
+    }
+    return reserved;
+}
+function build(shared, bindings) {
+    const subsystem = typeof bindings.subsystem === 'string' && bindings.subsystem !== ''
+        ? bindings.subsystem
+        : (shared.options.subsystem ?? 'root');
+    const threshold = levelFor(subsystem, shared.levels, shared.threshold);
+    const extra = shared.options.redact ?? [];
+    function record(level, message, fields) {
+        const merged = { ...bindings, ...fields };
+        const out = {
+            time: shared.now().toISOString(),
+            level,
+            severity: SEVERITY[level],
+            subsystem,
+            message: scrubText(message),
+        };
+        for (const key of CORRELATION) {
+            if (merged[key] !== undefined)
+                out[key] = redactValue(merged[key], extra);
+        }
+        const reserved = copyFields(out, merged, level);
+        const redacted = redactValue(out, extra);
+        // The fixed five are the record's own, never redacted as fields.
+        for (const key of FIXED)
+            redacted[key] = out[key];
+        if (Object.keys(reserved).length > 0)
+            redacted.fields = redactValue(reserved, extra);
+        if (merged.err !== undefined) {
+            const withStack = level === 'error' || levelEnabled('debug', threshold);
+            redacted.err = serializeError(merged.err, withStack);
+        }
+        return redacted;
+    }
+    function write(level, message, fields, how) {
+        if (!levelEnabled(level, threshold))
+            return;
+        const rec = record(level, message, fields);
+        const line = shared.format === 'pretty'
+            ? formatPretty(rec, {
+                color: shared.options.color === true,
+                ...(how?.inMessage !== undefined && { omit: how.inMessage }),
+            })
+            : formatJson(rec);
+        try {
+            shared.options.write(line);
+        }
+        catch {
+            // A sink that fails must never fail the code that logged.
+        }
+    }
+    return {
+        error: (message, fields, how) => write('error', message, fields, how),
+        warn: (message, fields, how) => write('warn', message, fields, how),
+        info: (message, fields, how) => write('info', message, fields, how),
+        debug: (message, fields, how) => write('debug', message, fields, how),
+        trace: (message, fields, how) => write('trace', message, fields, how),
+        child: (more) => build(shared, { ...bindings, ...more }),
+        isLevelEnabled: (level) => levelEnabled(level, threshold),
+    };
+}
+/**
+ * A logger: records at or above its level (per subsystem, `levels`) are
+ * redacted and written to `write` as JSON or pretty lines. Logging never
+ * throws, and a failing sink is ignored.
+ */
+export function createLogger(options) {
+    return build({
+        options,
+        threshold: options.level ?? 'info',
+        levels: options.levels ?? {},
+        format: options.format ?? 'json',
+        now: options.now ?? (() => new Date()),
+    }, {});
+}
+/** A logger that writes nothing: the default where one isn't given (`createApp`). */
+const noop = () => undefined;
+export const noopLogger = {
+    error: noop,
+    warn: noop,
+    info: noop,
+    debug: noop,
+    trace: noop,
+    child: () => noopLogger,
+    isLevelEnabled: () => false,
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/redact.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Redaction, applied to every record before it's written, at every level.
+ *
+ *   1. **Keys.** A field whose key looks secret has its value replaced
+ *      with `[redacted]`, at any depth: its key, lowercased with `-` and
+ *      `_` removed, ends with `authorization`, `cookie`, `token`,
+ *      `password`, `passwd`, `secret`, `secrets`, `apikey`, `privatekey`,
+ *      `passphrase` or `credential(s)` (`accessToken`, `x-api-key`,
+ *      `secrets`), plus any the caller adds. `tokenCount` and
+ *      `promptTokens` are not secret, and stay.
+ *   2. **Values.** Every string (the message, fields, an error's message
+ *      and stack) is scrubbed of known shapes only, so ids are never
+ *      mangled: a Kindgi token (`kgi_bt_…`, `kgi_pt_…`) keeps its prefix
+ *      and its last four characters; `Bearer <anything>` becomes
+ *      `Bearer [redacted]`; a URL's password (`postgres://user:pass@`)
+ *      becomes `user:***@`.
+ *
+ * The first rule is the code rule's net: secret values are never fields
+ * to begin with (pass a secret's name, not its value).
+ */
+export declare const REDACTED = "[redacted]";
+/** Whether a field's key looks secret (see rule 1). */
+export declare function isSecretKey(key: string, extra?: readonly string[]): boolean;
+/** A string with known secret shapes masked (see rule 2). */
+export declare function scrubText(text: string): string;
+/**
+ * A value with both rules applied, recursively: secret keys redacted,
+ * strings scrubbed. Plain objects and arrays are copied; anything deeper
+ * than a few levels, or a cycle (an object inside itself), becomes a
+ * marker. An object referenced twice side by side is copied twice.
+ */
+export declare function redactValue(value: unknown, extraKeys?: readonly string[], depth?: number, seen?: WeakSet<object>): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,QAAQ,eAAe,CAAC;AAmBrC,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,OAAO,CAG/E;AAOD,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ9C;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,SAAS,MAAM,EAAO,EACjC,KAAK,SAAI,EACT,IAAI,GAAE,OAAO,CAAC,MAAM,CAAiB,GACpC,OAAO,CAoBT"}

package/dist/redact.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Redaction, applied to every record before it's written, at every level.
+ *
+ *   1. **Keys.** A field whose key looks secret has its value replaced
+ *      with `[redacted]`, at any depth: its key, lowercased with `-` and
+ *      `_` removed, ends with `authorization`, `cookie`, `token`,
+ *      `password`, `passwd`, `secret`, `secrets`, `apikey`, `privatekey`,
+ *      `passphrase` or `credential(s)` (`accessToken`, `x-api-key`,
+ *      `secrets`), plus any the caller adds. `tokenCount` and
+ *      `promptTokens` are not secret, and stay.
+ *   2. **Values.** Every string (the message, fields, an error's message
+ *      and stack) is scrubbed of known shapes only, so ids are never
+ *      mangled: a Kindgi token (`kgi_bt_…`, `kgi_pt_…`) keeps its prefix
+ *      and its last four characters; `Bearer <anything>` becomes
+ *      `Bearer [redacted]`; a URL's password (`postgres://user:pass@`)
+ *      becomes `user:***@`.
+ *
+ * The first rule is the code rule's net: secret values are never fields
+ * to begin with (pass a secret's name, not its value).
+ */
+export const REDACTED = '[redacted]';
+const SECRET_KEY_ENDINGS = [
+    'authorization',
+    'cookie',
+    'token',
+    'password',
+    'passwd',
+    'secret',
+    'secrets',
+    'apikey',
+    'privatekey',
+    'passphrase',
+    'credential',
+    'credentials',
+];
+const normalize = (key) => key.toLowerCase().replace(/[-_]/g, '');
+/** Whether a field's key looks secret (see rule 1). */
+export function isSecretKey(key, extra = []) {
+    const k = normalize(key);
+    return [...SECRET_KEY_ENDINGS, ...extra.map(normalize)].some((end) => k.endsWith(end));
+}
+/** A Kindgi token: `kgi_` and a two-letter kind, then its body. */
+const KINDGI_TOKEN = /\bkgi_([a-z]{2})_([A-Za-z0-9._~+/=-]+)/g;
+const BEARER = /\b(Bearer)\s+[^\s"',;]+/gi;
+const URL_PASSWORD = /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+):[^\s@/]+@/gi;
+/** A string with known secret shapes masked (see rule 2). */
+export function scrubText(text) {
+    return text
+        .replace(KINDGI_TOKEN, (_m, kind, body) => {
+        const tail = body.length >= 16 ? body.slice(-4) : '';
+        return `kgi_${kind}_…${tail}`;
+    })
+        .replace(BEARER, '$1 [redacted]')
+        .replace(URL_PASSWORD, '$1:***@');
+}
+const MAX_DEPTH = 8;
+/**
+ * A value with both rules applied, recursively: secret keys redacted,
+ * strings scrubbed. Plain objects and arrays are copied; anything deeper
+ * than a few levels, or a cycle (an object inside itself), becomes a
+ * marker. An object referenced twice side by side is copied twice.
+ */
+export function redactValue(value, extraKeys = [], depth = 0, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return scrubText(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value.toISOString();
+    if (seen.has(value))
+        return '[circular]';
+    if (depth >= MAX_DEPTH)
+        return '[too deep]';
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((v) => redactValue(v, extraKeys, depth + 1, seen));
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            out[key] = isSecretKey(key, extraKeys)
+                ? REDACTED
+                : redactValue(v, extraKeys, depth + 1, seen);
+        }
+        return out;
+    }
+    finally {
+        // `seen` holds the path from the root: a cycle is an object inside itself.
+        seen.delete(value);
+    }
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"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"}

package/dist/trace.d.ts

@@ -0,0 +1,40 @@
+/**
+ * W3C Trace Context (`traceparent`), the ids every record written inside a
+ * request or a run carries: honour a caller's trace, or start one, and give
+ * each request its own span. Pure functions on Web Crypto, so they run in
+ * Node and in workers alike. No spans are recorded or exported here.
+ */
+export interface TraceContext {
+    /** 32 lowercase hex characters, not all zero. */
+    readonly traceId: string;
+    /** 16 lowercase hex characters, not all zero: this span. */
+    readonly spanId: string;
+    /** The span this one is a child of, when there is one. */
+    readonly parentSpanId?: string;
+    /** Trace flags, two hex characters; `01` is sampled. */
+    readonly flags: string;
+}
+/**
+ * An incoming `traceparent`'s trace id and parent span, or `undefined`
+ * when the header is absent or malformed: then the caller starts a fresh
+ * trace (a bad header is replaced, never trusted). Version `ff` is
+ * invalid; a future version is read by its first four fields, as the
+ * spec says. All-zero ids are invalid.
+ */
+export declare function parseTraceparent(header: string | null | undefined): {
+    readonly traceId: string;
+    readonly parentSpanId: string;
+    readonly flags: string;
+} | undefined;
+/** A fresh trace: a new trace id and a first span, sampled. */
+export declare function newTraceContext(): TraceContext;
+/** A new span in the same trace, whose parent is `parent`'s span. */
+export declare function childSpan(parent: TraceContext): TraceContext;
+/**
+ * The context for a request: a child span of the caller's trace when its
+ * `traceparent` is valid, else a fresh trace.
+ */
+export declare function traceFromHeader(header: string | null | undefined): TraceContext;
+/** The `traceparent` (and `traceresponse`) value for a context: `00-<trace>-<span>-<flags>`. */
+export declare function formatTraceparent(ctx: TraceContext): string;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAgBjG;AAWD,+DAA+D;AAC/D,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAO5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAS/E;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE3D"}

package/dist/trace.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(?:-.*)?$/;
+/**
+ * An incoming `traceparent`'s trace id and parent span, or `undefined`
+ * when the header is absent or malformed: then the caller starts a fresh
+ * trace (a bad header is replaced, never trusted). Version `ff` is
+ * invalid; a future version is read by its first four fields, as the
+ * spec says. All-zero ids are invalid.
+ */
+export function parseTraceparent(header) {
+    if (typeof header !== 'string')
+        return undefined;
+    // Hex must be lowercase (the spec): an uppercase header is malformed.
+    const m = TRACEPARENT.exec(header.trim());
+    if (m === null)
+        return undefined;
+    const [, version, traceId, parentSpanId, flags] = m;
+    if (version === 'ff')
+        return undefined;
+    if (version === '00' && header.trim().length !== 55)
+        return undefined;
+    if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+        return undefined;
+    return { traceId, parentSpanId, flags };
+}
+function randomHex(bytes) {
+    for (;;) {
+        const buf = new Uint8Array(bytes);
+        globalThis.crypto.getRandomValues(buf);
+        const hex = [...buf].map((b) => b.toString(16).padStart(2, '0')).join('');
+        if (!/^0+$/.test(hex))
+            return hex;
+    }
+}
+/** A fresh trace: a new trace id and a first span, sampled. */
+export function newTraceContext() {
+    return { traceId: randomHex(16), spanId: randomHex(8), flags: '01' };
+}
+/** A new span in the same trace, whose parent is `parent`'s span. */
+export function childSpan(parent) {
+    return {
+        traceId: parent.traceId,
+        spanId: randomHex(8),
+        parentSpanId: parent.spanId,
+        flags: parent.flags,
+    };
+}
+/**
+ * The context for a request: a child span of the caller's trace when its
+ * `traceparent` is valid, else a fresh trace.
+ */
+export function traceFromHeader(header) {
+    const incoming = parseTraceparent(header);
+    if (incoming === undefined)
+        return newTraceContext();
+    return {
+        traceId: incoming.traceId,
+        spanId: randomHex(8),
+        parentSpanId: incoming.parentSpanId,
+        flags: incoming.flags,
+    };
+}
+/** The `traceparent` (and `traceresponse`) value for a context: `00-<trace>-<span>-<flags>`. */
+export function formatTraceparent(ctx) {
+    return `00-${ctx.traceId}-${ctx.spanId}-${ctx.flags}`;
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAoBjC,MAAM,WAAW,GAAG,qEAAqE,CAAC;AAE1F;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAiC;IAEjC,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjD,sEAAsE;IACtE,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,GAAG,CAMjD,CAAC;IACF,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtE,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,SAAS,CAAC;QACR,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QAClC,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;IACpC,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,SAAS,CAAC,MAAoB;IAC5C,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiC;IAC/D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,eAAe,EAAE,CAAC;IACrD,OAAO;QACL,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QACpB,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,OAAO,MAAM,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+import type { LogLevel } from './levels.js';
+/** A record's fields: values, never text pasted into the message. */
+export type LogFields = Readonly<Record<string, unknown>>;
+/**
+ * One log record, the JSON format's line. `time` (RFC 3339), `level`,
+ * `severity` (Cloud Logging's name for the level), `subsystem` and
+ * `message` are always there; the correlation fields come next when
+ * known, then the event's own fields. An error is `err`.
+ */
+export interface LogRecord {
+    readonly time: string;
+    readonly level: LogLevel;
+    readonly severity: string;
+    readonly subsystem: string;
+    readonly message: string;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly requestId?: string;
+    readonly tenantId?: string;
+    readonly projectId?: string;
+    readonly runId?: string;
+    readonly err?: SerializedError;
+    readonly [field: string]: unknown;
+}
+/** An error, as a record carries it. `stack` at `error`, or when the logger is at `debug` or below. */
+export interface SerializedError {
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly stack?: string;
+    readonly cause?: SerializedError | string;
+}
+/**
+ * How one record is written, beyond its fields.
+ *
+ *   - `inMessage`: the fields its message already states. The access
+ *     line `GET /v1/runs/:runId 200 12ms` states `method`, `route`,
+ *     `status` and `durationMs`. The pretty format leaves them out, so
+ *     a terminal line doesn't say everything twice; JSON keeps every
+ *     field, for queries.
+ */
+export interface LogOptions {
+    readonly inMessage?: readonly string[];
+}
+/**
+ * A logger. `child` returns one whose records all carry `bindings`
+ * (`log.child({ subsystem: 'leases' })`, `log.child({ runId })`); a
+ * child's `subsystem` replaces its parent's, so name it in full
+ * (`kernel.sweeper`). Pass an error as `{ err: error }`.
+ */
+export interface Logger {
+    error(message: string, fields?: LogFields, options?: LogOptions): void;
+    warn(message: string, fields?: LogFields, options?: LogOptions): void;
+    info(message: string, fields?: LogFields, options?: LogOptions): void;
+    debug(message: string, fields?: LogFields, options?: LogOptions): void;
+    trace(message: string, fields?: LogFields, options?: LogOptions): void;
+    child(bindings: LogFields): Logger;
+    /** Whether a record at `level` would be written: skip building costly fields when it wouldn't. */
+    isLevelEnabled(level: LogLevel): boolean;
+}
+export type LogFormat = 'json' | 'pretty';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC;IAC/B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACvE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACtE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACtE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACvE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACvE,KAAK,CAAC,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IACnC,kGAAkG;IAClG,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}