@vibesdotdev/logging 0.0.2 → 1.0.0-rc.4

package/dist/core/endpoint.js

@@ -0,0 +1,256 @@
+/**
+ * Endpoint echoes. A configured endpoint may carry credentials in its userinfo
+ * (`user:password@host`) or query (`?token=...`). Everything Logging logs,
+ * reports or returns about an endpoint passes through these schemas, so only
+ * scheme, host, port and path are ever echoed. Path segments are kept (they
+ * name the collector route); a secret does not belong in a path.
+ */
+import * as z from 'zod/v4';
+import { attempt } from "./outcome.js";
+import { CallerStringSchema, isSecretKey, REDACTED, ThrownValueSchema } from "./redact.js";
+/** What an endpoint that is not a URL echoes as: its text could be anything, so none of it is shown. */
+export const UNPARSEABLE_ENDPOINT = '[unparseable-endpoint]';
+/** An endpoint reduced to the parts that are safe to echo: userinfo, query and fragment are dropped. Any other value refuses as a `ZodError`. */
+export const RedactedEndpointSchema = CallerStringSchema.transform((endpoint) => {
+    if (!URL.canParse(endpoint))
+        return UNPARSEABLE_ENDPOINT;
+    const url = new URL(endpoint);
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    // `URL` writes an empty path as `/`; the echo keeps the endpoint's own spelling.
+    const slashless = url.pathname === '/' && !endpoint.split(/[?#]/)[0]?.endsWith('/');
+    return slashless ? url.href.slice(0, -1) : url.href;
+});
+function decoded(component) {
+    const outcome = attempt(() => decodeURIComponent(component));
+    // A component that is not valid percent-encoding has only its raw spelling.
+    return outcome.failed ? component : outcome.value;
+}
+function encoded(component) {
+    const outcome = attempt(() => encodeURIComponent(component));
+    return outcome.failed ? component : outcome.value;
+}
+/** A text as it appears inside a JSON string (`"` and `\\` escaped), so a serialized echo is matched too. */
+function jsonEscaped(text) {
+    return JSON.stringify(text).slice(1, -1);
+}
+/**
+ * Every spelling a credential component may be echoed in: raw, percent-decoded,
+ * percent-encoded once more (a raw `%2F` echoed as `%252F`), and each of those
+ * as JSON-escaped text. A query component is also spelled with `+` and `%20`
+ * swapped both ways and decoded with `+` read as a space. Percent-encoding hex
+ * case needs no spelling of its own: fragments are matched case-insensitively.
+ */
+function spellings(raw, query) {
+    const plain = decoded(raw);
+    const forms = [raw, plain, encoded(raw), encoded(plain)];
+    if (query)
+        forms.push(decoded(raw.replaceAll('+', ' ')), raw.replaceAll('+', '%20'), raw.replace(/%20/gi, '+'));
+    return [...forms, ...forms.map(jsonEscaped)];
+}
+/**
+ * Query parameter names whose value is a credential (case-insensitive). The
+ * rule is the log redaction's own: every name `isSecretKey` calls secret (so
+ * the two share one credential-word list, `CREDENTIAL_KEY_WORDS`), plus
+ * the names a URL uses for a credential that a log key does not (`code`,
+ * `session`, `sid`, `sig`) and any name ending in `_key` or `-key`. This list
+ * names the common ones; every one of them is a credential under that rule.
+ * Other parameters (`format=json`, `v=1`) are not credentials, so their values
+ * are not matched on their own; the whole query still is.
+ */
+export const CREDENTIAL_QUERY_PARAMETER_NAMES = [
+    'token', 'key', 'apikey', 'api_key', 'access_token', 'secret', 'sig', 'signature', 'password', 'pass', 'pwd',
+    'auth', 'authorization', 'code', 'session', 'sessionid', 'sid', 'jwt', 'bearer', 'credential'
+];
+/** The URL-only credential names: secret in a query, ordinary as a log key (an error's `code`, a `session` object). */
+const URL_ONLY_CREDENTIAL_NAMES = new Set(['code', 'session', 'sid', 'sig']);
+const URL_KEY_SUFFIX = /[_-]key$/i;
+function isCredentialParameter(rawName) {
+    const name = decoded(rawName.replaceAll('+', ' ')).toLowerCase();
+    return isSecretKey(name) || URL_ONLY_CREDENTIAL_NAMES.has(name) || URL_KEY_SUFFIX.test(name);
+}
+/** The secret parts of a query: the whole query, and each credential-named parameter's `name=value` pair and value. */
+function queryComponents(search) {
+    if (search === '')
+        return [];
+    const credentialPairs = search.split('&').filter((pair) => pair.includes('=') && isCredentialParameter(pair.slice(0, pair.indexOf('='))));
+    return [search, ...credentialPairs, ...credentialPairs.map((pair) => pair.slice(pair.indexOf('=') + 1))];
+}
+/**
+ * Secret values a request carried beside its endpoint (each configured header
+ * value), as the fragments a failure description must not echo: the value
+ * itself and, for an `<auth-scheme> <credential>` value (`Bearer abc`), the
+ * credential alone, each in every spelling.
+ */
+function headerValueFragments(secrets) {
+    return secrets.flatMap((secret) => {
+        const value = secret.trim();
+        const scheme = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+[ \t]+(.+)$/.exec(value);
+        return [value, ...(scheme?.[1] ? [scheme[1].trim()] : [])];
+    }).flatMap((component) => spellings(component, false));
+}
+/** The credential-bearing fragments of an endpoint (and of the request's secret values), longest first, each with what replaces it. */
+function sensitiveFragments(endpoint, secrets) {
+    const redacted = RedactedEndpointSchema.parse(endpoint);
+    const fragments = new Map([[endpoint, redacted]]);
+    if (URL.canParse(endpoint)) {
+        const url = new URL(endpoint);
+        fragments.set(url.href, redacted);
+        // A username is a credential too: `http://TOKEN@host` carries the token there alone.
+        const components = [
+            ...[url.username, url.password, url.hash.slice(1)].flatMap((component) => spellings(component, false)),
+            ...queryComponents(url.search.slice(1)).flatMap((component) => spellings(component, true))
+        ];
+        for (const fragment of components)
+            if (fragment !== '' && !fragments.has(fragment))
+                fragments.set(fragment, REDACTED);
+    }
+    for (const fragment of headerValueFragments(secrets))
+        if (fragment !== '' && !fragments.has(fragment))
+            fragments.set(fragment, REDACTED);
+    return [...fragments].sort((left, right) => right[0].length - left[0].length);
+}
+/** A fragment as a literal regular-expression alternative (`u` flag: only syntax characters are escaped). */
+function literalPattern(fragment) {
+    return fragment.replace(/[\\^$.*+?()[\]{}|/]/g, '\\$&');
+}
+/** Below this length a fragment is matched only as a whole token; at or above it, anywhere. */
+export const SUBSTRING_FRAGMENT_MIN_LENGTH = 4;
+const WORD_CHARACTER = /[\p{L}\p{N}]/u;
+/**
+ * The match rule for one fragment. A fragment of SUBSTRING_FRAGMENT_MIN_LENGTH or
+ * more characters is matched anywhere, so a secret glued to other text
+ * (`tokenS3CR3T`) is still removed. A shorter one is matched only where it is not
+ * inside a longer letter/digit run (an edge that is itself punctuation needs no
+ * guard), so a username `u` removes `u` but leaves `<anonymous>` alone: a one- to
+ * three-character secret inside a longer word carries nothing of the secret.
+ */
+function fragmentPattern(fragment) {
+    if (fragment.length >= SUBSTRING_FRAGMENT_MIN_LENGTH)
+        return literalPattern(fragment);
+    const before = WORD_CHARACTER.test(fragment.slice(0, 1)) ? '(?<![\\p{L}\\p{N}])' : '';
+    const after = WORD_CHARACTER.test(fragment.slice(-1)) ? '(?![\\p{L}\\p{N}])' : '';
+    return `${before}${literalPattern(fragment)}${after}`;
+}
+/**
+ * One pass over a text replacing every credential fragment, case-insensitively,
+ * longest first at each position. Replacement text is never rescanned, so a short
+ * fragment cannot rewrite the `[REDACTED]` marker or the echoed endpoint it wrote.
+ */
+function createTextScrubber(endpoint, secrets) {
+    const fragments = sensitiveFragments(endpoint, secrets).filter(([fragment]) => fragment !== '');
+    if (fragments.length === 0)
+        return (text) => text;
+    const replacements = new Map(fragments.map(([fragment, replacement]) => [fragment.toLowerCase(), replacement]));
+    const pattern = new RegExp(fragments.map(([fragment]) => fragmentPattern(fragment)).join('|'), 'giu');
+    return (text) => text.replace(pattern, (found) => replacements.get(found.toLowerCase()) ?? REDACTED);
+}
+/** A string, recognized by `typeof` alone: a schema's failure path would read a Proxy's prototype, which a trap throws from. */
+const TextValueSchema = z.custom((value) => typeof value === 'string');
+/** What a response-derived text becomes when it cannot be scrubbed (not a string, or the scrubber cannot be built): none of it is shown. */
+export const UNSCRUBBABLE_TEXT = '[unscrubbable-text]';
+/**
+ * A text a peer of `endpoint` controls (a collector's HTTP reason phrase, a
+ * header or body excerpt), with the endpoint's credentials removed by the same
+ * one-pass scrubber as a failure description. A collector can echo the request
+ * line (`401 rejected POST /v1/logs?token=...`), so such text is never logged,
+ * reported or attributed raw. `secrets` are the secret values the request
+ * carried beside the endpoint (its header values); each is removed the same way.
+ * It never throws: a value that is not a string, or a scrubber that cannot be
+ * built, becomes {@link UNSCRUBBABLE_TEXT}.
+ */
+export function createEndpointTextSchema(endpoint, secrets = []) {
+    return z.unknown().transform((value) => {
+        const text = TextValueSchema.safeParse(value);
+        if (!text.success)
+            return UNSCRUBBABLE_TEXT;
+        const scrubbed = attempt(() => createTextScrubber(endpoint, secrets)(text.data));
+        return scrubbed.failed ? UNSCRUBBABLE_TEXT : scrubbed.value;
+    });
+}
+/**
+ * A described failure walked by value. Every string value is scrubbed; a number
+ * whose text holds a credential becomes the REDACTED string (a `status` is dropped
+ * instead, keeping its type). Keys of free-form maps (`details`, `fields`, a
+ * non-Error thrown object, a non-Error cause) are scrubbed too; the description's
+ * own fixed keys (`name`, `message`, `stack`, `code`, ...) are structure, not text.
+ * Two keys that scrub to the same text keep the later value.
+ */
+function createScrubbedDescriptionSchema(scrub) {
+    const text = z.string().transform(scrub);
+    const number = z.number().transform((value) => scrub(String(value)) === String(value) ? value : REDACTED);
+    const status = z.number().transform((value) => scrub(String(value)) === String(value) ? value : undefined);
+    const scrubKeys = (record) => Object.fromEntries(Object.entries(record).map(([key, value]) => [scrub(key), value]));
+    // Bytes are text a credential can travel in: a Buffer's JSON (`{ type: 'Buffer', data }`) or a typed array
+    // walked to its index keys is decoded as UTF-8 and, when it carries a fragment, replaced whole.
+    const bytesText = (bytes) => new TextDecoder().decode(Uint8Array.from(bytes));
+    const ByteSchema = z.number().int().min(0).max(255);
+    const bufferJson = z.strictObject({ type: z.literal('Buffer'), data: z.array(ByteSchema) })
+        .transform((buffer) => scrub(bytesText(buffer.data)) === bytesText(buffer.data) ? buffer : REDACTED);
+    const byteRecord = z.record(z.string().regex(/^\d+$/), ByteSchema)
+        .refine((record) => Object.keys(record).length > 0 && Object.keys(record).every((key, index) => key === String(index)))
+        .transform((record) => scrub(bytesText(Object.values(record))) === bytesText(Object.values(record)) ? record : REDACTED);
+    const free = z.lazy(() => z.union([text, number, z.array(free), bufferJson, byteRecord, freeRecord, z.unknown()]));
+    const freeRecord = z.lazy(() => z.record(z.string(), free).transform(scrubKeys));
+    const description = z.lazy(() => z.strictObject({
+        name: text,
+        message: text,
+        code: z.union([text, number]).optional(),
+        reason: text.optional(),
+        status: status.optional(),
+        retryable: z.boolean().optional(),
+        details: free.optional(),
+        fields: freeRecord.optional(),
+        stack: text.optional(),
+        cause: z.union([description, free]).optional(),
+        errors: z.array(description).optional()
+    }));
+    return description;
+}
+/** What a failure is described as when its description cannot be scrubbed: no value of it is shown. */
+export const UNSCRUBBABLE_FAILURE_MESSAGE = 'The failure could not be described without its endpoint credentials, so none of its text is shown.';
+/** What a value-free description may keep of a thrown value: whether it is an Error, and the Error's own name. */
+const FailureIdentitySchema = z.union([
+    z.instanceof(Error).transform((error) => ({ error: true, name: z.string().safeParse(error.name).data })),
+    z.unknown().transform(() => ({ error: false, name: undefined }))
+]);
+/** The value-free description: the thrown Error's own name when no credential fragment is in it, and a fixed message. */
+function valueFreeFailure(identity, scrub) {
+    const named = attempt(() => {
+        if (identity === undefined)
+            return 'Error';
+        if (!identity.error)
+            return 'NonError';
+        return identity.name !== undefined && scrub(identity.name) === identity.name ? identity.name : 'Error';
+    });
+    return { name: named.failed ? 'Error' : named.value, message: UNSCRUBBABLE_FAILURE_MESSAGE };
+}
+/**
+ * A schema describing any thrown value that failed while using `endpoint`, with the
+ * endpoint's credentials removed from every string value the description carries
+ * (message, stack, fields such as a runtime's request `path`, details, cause chain,
+ * aggregate members), and every value in `secrets` (the header values a request
+ * carried: a transport failure can echo one, e.g. `Header 'Authorization' has
+ * invalid value: 'Bearer ...'`) removed the same way, so a failure from a
+ * credentialed request carries none of its header values. It never throws: a value that cannot be described and
+ * scrubbed is described by name and a fixed message, so the caller's own failure
+ * (a fetch error, a write's re-buffering) is never replaced by a scrub failure.
+ */
+export function createEndpointFailureSchema(endpoint, secrets = []) {
+    return z.unknown().transform((cause) => {
+        const identity = attempt(() => FailureIdentitySchema.parse(cause));
+        const known = identity.failed ? undefined : identity.value;
+        const scrubber = attempt(() => createTextScrubber(endpoint, secrets));
+        if (scrubber.failed)
+            return valueFreeFailure(known, () => '');
+        // The total describer never throws; a value it could only describe value-free keeps this schema's own fallback.
+        const thrown = ThrownValueSchema.parse(cause);
+        if (!thrown.described)
+            return valueFreeFailure(known, scrubber.value);
+        const scrubbed = attempt(() => createScrubbedDescriptionSchema(scrubber.value).parse(thrown.error));
+        return scrubbed.failed ? valueFreeFailure(known, scrubber.value) : scrubbed.value;
+    });
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/core/endpoint.js.map

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

package/dist/core/entry-context.d.ts

@@ -0,0 +1,106 @@
+import * as z from 'zod/v4';
+import { type JobLogContext, type LogContext, type PerformanceTrackerParams, type RequestLogContext } from '../schemas/entry.ts';
+import { type LoggedError, type ThrownValueDescription } from './redact.ts';
+/** The `loggingError.reason` of an entry whose context could not be normalized. */
+export declare const LOG_CONTEXT_FAILED_REASON = "log-context-unnormalizable";
+/** What a log call's context became at the call boundary: normalized, or the failure normalizing it. */
+export interface CallContext {
+    readonly context: LogContext;
+    readonly failure: LoggedError | undefined;
+}
+/** What an unreadable context's failure says: never the thrown message, which a hostile getter can fill with the value. */
+export declare const UNREADABLE_CONTEXT_MESSAGE = "The log context could not be read (a getter, toJSON or conversion threw); the thrown message is withheld because it may carry the value.";
+/** Describes the failure of a context that could not be read. */
+export declare const UnreadableContextFailureSchema: z.ZodType<LoggedError, unknown, z.core.$ZodTypeInternals<LoggedError, unknown>>;
+/** What a backend failure says when its error cannot be described: never the thrown message, which a hostile getter can fill with the value. */
+export declare const UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE = "A logging backend failed and its error could not be described (a getter, toJSON or conversion threw); the thrown message is withheld because it may carry the value.";
+/**
+ * Describes a sink's or output's failure (or a failed recovery) with the total
+ * describer: the full `LoggedError` when it can be described, else its readable
+ * error name and the fixed `UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE`. It never
+ * throws into the caller that logged, and never rejects the joined write.
+ */
+export declare const BackendFailureSchema: z.ZodPipe<z.ZodType<ThrownValueDescription, unknown, z.core.$ZodTypeInternals<ThrownValueDescription, unknown>>, z.ZodTransform<LoggedError, ThrownValueDescription>>;
+/**
+ * A tracker's `fail(err, ctx)` context: the thrown value's description as
+ * `error` over `base`, then the raw `ctx`, read without throwing. A thrown value
+ * that could only be described value-free travels as the entry's failure too,
+ * so the entry carries it as its `loggingError` and the logger reports it once.
+ */
+export declare function mergeFailureContexts(base: LogContext, thrown: ThrownValueDescription, ...raws: readonly unknown[]): CallContext;
+/**
+ * A log call's context, normalized at the boundary. A context that cannot be
+ * normalized (a throwing `toJSON` or getter) never throws into the caller: the
+ * failure travels as a value to the entry, which reports it.
+ */
+export declare const CallContextSchema: z.ZodPipe<z.ZodUnknown, z.ZodTransform<CallContext, unknown>>;
+/**
+ * Raw contexts merged, in order, over `base`, each read at the boundary without
+ * throwing (`end(ctx)`, `fail(err, ctx)`, a derived logger's context). What
+ * could be read is kept; the first failure travels as a value.
+ */
+export declare function mergeCallContexts(base: LogContext, ...raws: readonly unknown[]): CallContext;
+/** The label a performance tracker uses when its `operation` is not a string. */
+export declare const UNLABELED_OPERATION = "unlabeled";
+/** What a tracker's failure says when its `operation` is not a string: never the value. */
+export declare const OPERATION_NOT_TEXT_MESSAGE = "A performance tracker's operation must be a string; its entries use the label 'unlabeled'.";
+/** A performance tracker's params, read once at creation: its label and its metadata context. */
+export interface TrackerCall {
+    /** The operation label every entry names: the `operation` string, else {@link UNLABELED_OPERATION}. */
+    readonly operation: string;
+    /** `base` with the label as `operation` and the metadata merged; an unreadable or non-string field is its failure. */
+    readonly merged: CallContext;
+}
+/**
+ * Reads `performanceTracker(params)` once, without throwing: `operation` and
+ * `metadata` are each read once inside the guard. A string `operation` is the
+ * label; any other value (or params that cannot be read) labels the entries
+ * {@link UNLABELED_OPERATION} and travels as the tracker's failure, so every
+ * entry carries it as its `loggingError` and the logger reports it once.
+ */
+export declare function readTrackerParams(base: LogContext, params: PerformanceTrackerParams): TrackerCall;
+/** The fields `withRequestContext` and `withJobContext` take from their context. */
+export declare const REQUEST_CONTEXT_FIELDS: readonly string[];
+export declare const JOB_CONTEXT_FIELDS: readonly string[];
+/**
+ * Only the named fields of a raw context (`withRequestContext`,
+ * `withJobContext`), read without throwing; a field the context leaves unset
+ * (or null) keeps `base`'s value.
+ */
+export declare function mergeCallContextFields(base: LogContext, raw: RequestLogContext | JobLogContext, fields: readonly string[]): CallContext;
+/**
+ * The metadata of a logger derived from `merged`. When a context could not be
+ * read it carries the `loggingError`, so every entry the derived logger emits
+ * shows the failure (the logger reports it once, at its first emission).
+ */
+export declare function derivedLoggerMetadata(merged: CallContext): LogContext;
+/**
+ * A public log method: the message is validated and the context is handed on
+ * raw. The logger checks the entry's level (and emission window and sampling)
+ * first and only then normalizes the context, once, with
+ * {@link OptionalCallContextSchema}: a filtered call never walks its context, and an
+ * emitted one walks it exactly once. Normalizing never throws.
+ */
+export declare const LogCallSchema: z.ZodFunction<z.ZodTuple<readonly [z.ZodCustom<string, string>, z.ZodOptional<z.ZodUnknown>, z.ZodOptional<z.ZodUnknown>], null>, z.ZodVoid>;
+/** A log call's raw context, normalized once at the boundary without throwing (`undefined` is no context). */
+export declare const OptionalCallContextSchema: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<CallContext, unknown>>>;
+/** A forwarding wrapper hands the raw context on, for the logger it wraps to normalize. */
+export declare const ForwardedLogCallSchema: z.ZodFunction<z.ZodTuple<readonly [z.ZodCustom<string, string>, z.ZodOptional<z.ZodUnknown>, z.ZodOptional<z.ZodUnknown>], null>, z.ZodVoid>;
+/** An entry's context, and the failure when its context could not be prepared. */
+export interface PreparedEntryContext {
+    readonly context: LogContext;
+    readonly failure: LoggedError | undefined;
+}
+/**
+ * The entry context for a logger's `base` metadata and a call's context. Both
+ * are already walked snapshots (the base was read once when the logger was
+ * made, the call once at the boundary), so they are merged, not walked again:
+ * every value is JSON and every own key (a `__proto__` field included) is kept
+ * as data. A logging backend must never break the caller that logged, and its
+ * failure must not be silent: when the call's context could not be read the
+ * entry keeps its level, namespace and message, its context becomes what could
+ * be kept plus a `loggingError` describing the failure (never the caller's
+ * value), and the failure is returned for the diagnostics path.
+ */
+export declare function prepareEntryContext(base: LogContext, call: CallContext | undefined): PreparedEntryContext;
+//# sourceMappingURL=entry-context.d.ts.map

package/dist/core/entry-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-context.d.ts","sourceRoot":"","sources":["../../src/core/entry-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAgD,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE/K,OAAO,EAA+F,KAAK,WAAW,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAGzK,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE,wGAAwG;AACxG,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;CAC1C;AAED,2HAA2H;AAC3H,eAAO,MAAM,0BAA0B,6IAA6I,CAAC;AAErL,iEAAiE;AACjE,eAAO,MAAM,8BAA8B,iFAAqD,CAAC;AAEjG,gJAAgJ;AAChJ,eAAO,MAAM,qCAAqC,yKAAyK,CAAC;AAE5N;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,uKAAkH,CAAC;AAEpJ;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,WAAW,CAI/H;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,+DAI5B,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,WAAW,CAS5F;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,+FAA4G,CAAC;AAEpJ,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC3B,uGAAuG;IACvG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sHAAsH;IACtH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC7B;AAOD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wBAAwB,GAAG,WAAW,CAYjG;AAED,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAA4C,CAAC;AACjG,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAwC,CAAC;AAEzF;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,iBAAiB,GAAG,aAAa,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAOvI;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,CAErE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,8IAGxB,CAAC;AAEH,8GAA8G;AAC9G,eAAO,MAAM,yBAAyB,8EAA+B,CAAC;AAEtE,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,8IAGjC,CAAC;AAEH,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;CAC1C;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,oBAAoB,CAKzG"}

package/dist/core/entry-context.js

@@ -0,0 +1,150 @@
+import * as z from 'zod/v4';
+import { JobLogContextSchema, RequestLogContextSchema } from "../schemas/entry.js";
+import { NormalizedLogContextSchema } from "./normalize.js";
+import { CallerStringSchema, createFieldsReadSchema, createThrownValueSchema, valueFreeFailureSchema } from "./redact.js";
+import { attempt } from "./outcome.js";
+/** The `loggingError.reason` of an entry whose context could not be normalized. */
+export const LOG_CONTEXT_FAILED_REASON = 'log-context-unnormalizable';
+/** What an unreadable context's failure says: never the thrown message, which a hostile getter can fill with the value. */
+export const UNREADABLE_CONTEXT_MESSAGE = 'The log context could not be read (a getter, toJSON or conversion threw); the thrown message is withheld because it may carry the value.';
+/** Describes the failure of a context that could not be read. */
+export const UnreadableContextFailureSchema = valueFreeFailureSchema(UNREADABLE_CONTEXT_MESSAGE);
+/** What a backend failure says when its error cannot be described: never the thrown message, which a hostile getter can fill with the value. */
+export const UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE = 'A logging backend failed and its error could not be described (a getter, toJSON or conversion threw); the thrown message is withheld because it may carry the value.';
+/**
+ * Describes a sink's or output's failure (or a failed recovery) with the total
+ * describer: the full `LoggedError` when it can be described, else its readable
+ * error name and the fixed `UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE`. It never
+ * throws into the caller that logged, and never rejects the joined write.
+ */
+export const BackendFailureSchema = createThrownValueSchema(UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE).transform((thrown) => thrown.error);
+/**
+ * A tracker's `fail(err, ctx)` context: the thrown value's description as
+ * `error` over `base`, then the raw `ctx`, read without throwing. A thrown value
+ * that could only be described value-free travels as the entry's failure too,
+ * so the entry carries it as its `loggingError` and the logger reports it once.
+ */
+export function mergeFailureContexts(base, thrown, ...raws) {
+    const merged = mergeCallContexts({ ...base, error: thrown.error }, ...raws);
+    if (thrown.described)
+        return merged;
+    return { context: merged.context, failure: merged.failure ?? thrown.error };
+}
+/**
+ * A log call's context, normalized at the boundary. A context that cannot be
+ * normalized (a throwing `toJSON` or getter) never throws into the caller: the
+ * failure travels as a value to the entry, which reports it.
+ */
+export const CallContextSchema = z.unknown().transform((raw) => {
+    const normalized = attempt(() => NormalizedLogContextSchema.parse(raw));
+    if (!normalized.failed)
+        return { context: normalized.value, failure: undefined };
+    return { context: {}, failure: UnreadableContextFailureSchema.parse(normalized.cause) };
+});
+/**
+ * Raw contexts merged, in order, over `base`, each read at the boundary without
+ * throwing (`end(ctx)`, `fail(err, ctx)`, a derived logger's context). What
+ * could be read is kept; the first failure travels as a value.
+ */
+export function mergeCallContexts(base, ...raws) {
+    let context = base;
+    let failure;
+    for (const raw of raws) {
+        const call = CallContextSchema.parse(raw);
+        context = { ...context, ...call.context };
+        failure ??= call.failure;
+    }
+    return { context, failure };
+}
+/** The label a performance tracker uses when its `operation` is not a string. */
+export const UNLABELED_OPERATION = 'unlabeled';
+/** What a tracker's failure says when its `operation` is not a string: never the value. */
+export const OPERATION_NOT_TEXT_MESSAGE = `A performance tracker's operation must be a string; its entries use the label '${UNLABELED_OPERATION}'.`;
+const TrackerOperationReadSchema = createFieldsReadSchema(['operation']);
+const TrackerMetadataReadSchema = createFieldsReadSchema(['metadata']);
+/** A string, recognized by `typeof` alone: a schema's failure path would read a Proxy's prototype, which a trap throws from. */
+const OperationLabelSchema = z.custom((value) => typeof value === 'string');
+/**
+ * Reads `performanceTracker(params)` once, without throwing: `operation` and
+ * `metadata` are each read once inside the guard. A string `operation` is the
+ * label; any other value (or params that cannot be read) labels the entries
+ * {@link UNLABELED_OPERATION} and travels as the tracker's failure, so every
+ * entry carries it as its `loggingError` and the logger reports it once.
+ */
+export function readTrackerParams(base, params) {
+    const read = TrackerOperationReadSchema.safeParse(params);
+    const label = read.success ? OperationLabelSchema.safeParse(read.data.operation) : undefined;
+    const operation = label?.success ? label.data : UNLABELED_OPERATION;
+    const labelFailure = !read.success
+        ? UnreadableContextFailureSchema.parse(read.error)
+        : label?.success ? undefined : { name: 'TypeError', message: OPERATION_NOT_TEXT_MESSAGE };
+    const metadata = TrackerMetadataReadSchema.safeParse(params);
+    const merged = metadata.success
+        ? mergeCallContexts({ ...base, operation }, metadata.data.metadata)
+        : { context: { ...base, operation }, failure: UnreadableContextFailureSchema.parse(metadata.error) };
+    return { operation, merged: { context: merged.context, failure: labelFailure ?? merged.failure } };
+}
+/** The fields `withRequestContext` and `withJobContext` take from their context. */
+export const REQUEST_CONTEXT_FIELDS = RequestLogContextSchema.keyof().options;
+export const JOB_CONTEXT_FIELDS = JobLogContextSchema.keyof().options;
+/**
+ * Only the named fields of a raw context (`withRequestContext`,
+ * `withJobContext`), read without throwing; a field the context leaves unset
+ * (or null) keeps `base`'s value.
+ */
+export function mergeCallContextFields(base, raw, fields) {
+    const call = CallContextSchema.parse(raw);
+    const picked = Object.fromEntries(fields.flatMap((field) => {
+        const value = call.context[field];
+        return value === undefined || value === null ? [] : [[field, value]];
+    }));
+    return { context: { ...base, ...picked }, failure: call.failure };
+}
+/**
+ * The metadata of a logger derived from `merged`. When a context could not be
+ * read it carries the `loggingError`, so every entry the derived logger emits
+ * shows the failure (the logger reports it once, at its first emission).
+ */
+export function derivedLoggerMetadata(merged) {
+    return merged.failure ? withLoggingError(merged.context, merged.failure) : merged.context;
+}
+/**
+ * A public log method: the message is validated and the context is handed on
+ * raw. The logger checks the entry's level (and emission window and sampling)
+ * first and only then normalizes the context, once, with
+ * {@link OptionalCallContextSchema}: a filtered call never walks its context, and an
+ * emitted one walks it exactly once. Normalizing never throws.
+ */
+export const LogCallSchema = z.function({
+    input: [CallerStringSchema, z.unknown().optional(), z.unknown().optional()],
+    output: z.void()
+});
+/** A log call's raw context, normalized once at the boundary without throwing (`undefined` is no context). */
+export const OptionalCallContextSchema = CallContextSchema.optional();
+/** A forwarding wrapper hands the raw context on, for the logger it wraps to normalize. */
+export const ForwardedLogCallSchema = z.function({
+    input: [CallerStringSchema, z.unknown().optional(), z.unknown().optional()],
+    output: z.void()
+});
+function withLoggingError(context, error) {
+    return { ...context, loggingError: { reason: LOG_CONTEXT_FAILED_REASON, error } };
+}
+/**
+ * The entry context for a logger's `base` metadata and a call's context. Both
+ * are already walked snapshots (the base was read once when the logger was
+ * made, the call once at the boundary), so they are merged, not walked again:
+ * every value is JSON and every own key (a `__proto__` field included) is kept
+ * as data. A logging backend must never break the caller that logged, and its
+ * failure must not be silent: when the call's context could not be read the
+ * entry keeps its level, namespace and message, its context becomes what could
+ * be kept plus a `loggingError` describing the failure (never the caller's
+ * value), and the failure is returned for the diagnostics path.
+ */
+export function prepareEntryContext(base, call) {
+    const merged = { ...base, ...call?.context };
+    const callFailure = call?.failure;
+    if (callFailure === undefined)
+        return { context: merged, failure: undefined };
+    return { context: withLoggingError(merged, callFailure), failure: callFailure };
+}
+//# sourceMappingURL=entry-context.js.map

package/dist/core/entry-context.js.map

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

package/dist/core/index.d.ts

@@ -4,6 +4,10 @@
  * Exports logger factory and types.
  */
 export { createRuntimeLogger } from './logger.ts';
+export { REDACTED, FUNCTION_MARKER, SecretValue, isSecretKey, CREDENTIAL_KEY_WORDS, SecretValueSchema, RedactedLogValueSchema, secret, LoggedErrorSchema, UNDESCRIBABLE_ERROR_MESSAGE, UNREADABLE_LOG_VALUE_MESSAGE, JSON_HOOK_REFUSAL_MESSAGE, MAX_WALK_BREADTH, TRUNCATED_KEY, truncationMarker, type LoggedError } from './redact.ts';
+export { RedactedEndpointSchema, UNPARSEABLE_ENDPOINT, UNSCRUBBABLE_FAILURE_MESSAGE, SUBSTRING_FRAGMENT_MIN_LENGTH, CREDENTIAL_QUERY_PARAMETER_NAMES, createEndpointFailureSchema, createEndpointTextSchema, UNSCRUBBABLE_TEXT } from './endpoint.ts';
+export { UNREADABLE_CONTEXT_MESSAGE, UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE, UNLABELED_OPERATION, OPERATION_NOT_TEXT_MESSAGE } from './entry-context.ts';
+export { NormalizedLogContextSchema, LogMethodSchema, PerformanceFailureSchema, type LogMethod, type PerformanceFailureMethod } from './normalize.ts';
 export type { Logger, RuntimeLogger, Runtime, RuntimeLoggerOptions, RuntimeLoggerConfig } from './types.ts';
 export { parseNamespaceSettings, parseNamespaceSettingsFromEnv, matchesSelector, isNamespaceIncluded, shouldLog, updateNamespaceSettings, getNamespaceSettings, defaultNamespaceSettings, type NamespaceSelector, type NamespaceSelectors, type NamespaceSettings } from './namespace.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,YAAY,EACX,MAAM,EACN,aAAa,EACb,OAAO,EACP,oBAAoB,EACpB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACN,sBAAsB,EACtB,6BAA6B,EAC7B,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EACN,QAAQ,EACR,eAAe,EACf,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,MAAM,EACN,iBAAiB,EACjB,2BAA2B,EAC3B,4BAA4B,EAC5B,yBAAyB,EACzB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,KAAK,WAAW,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,0BAA0B,EAAE,qCAAqC,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAExJ,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,wBAAwB,EAAE,KAAK,SAAS,EAAE,KAAK,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAGtJ,YAAY,EACX,MAAM,EACN,aAAa,EACb,OAAO,EACP,oBAAoB,EACpB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACN,sBAAsB,EACtB,6BAA6B,EAC7B,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,MAAM,gBAAgB,CAAC"}

package/dist/core/index.js

@@ -5,6 +5,11 @@
  */
 // Logger factory
 export { createRuntimeLogger } from "./logger.js";
+// Redaction and structured errors (the contract every entry context passes through)
+export { REDACTED, FUNCTION_MARKER, SecretValue, isSecretKey, CREDENTIAL_KEY_WORDS, SecretValueSchema, RedactedLogValueSchema, secret, LoggedErrorSchema, UNDESCRIBABLE_ERROR_MESSAGE, UNREADABLE_LOG_VALUE_MESSAGE, JSON_HOOK_REFUSAL_MESSAGE, MAX_WALK_BREADTH, TRUNCATED_KEY, truncationMarker } from "./redact.js";
+export { RedactedEndpointSchema, UNPARSEABLE_ENDPOINT, UNSCRUBBABLE_FAILURE_MESSAGE, SUBSTRING_FRAGMENT_MIN_LENGTH, CREDENTIAL_QUERY_PARAMETER_NAMES, createEndpointFailureSchema, createEndpointTextSchema, UNSCRUBBABLE_TEXT } from "./endpoint.js";
+export { UNREADABLE_CONTEXT_MESSAGE, UNDESCRIBABLE_BACKEND_FAILURE_MESSAGE, UNLABELED_OPERATION, OPERATION_NOT_TEXT_MESSAGE } from "./entry-context.js";
+export { NormalizedLogContextSchema, LogMethodSchema, PerformanceFailureSchema } from "./normalize.js";
 // Namespace utilities
 export { parseNamespaceSettings, parseNamespaceSettingsFromEnv, matchesSelector, isNamespaceIncluded, shouldLog, updateNamespaceSettings, getNamespaceSettings, defaultNamespaceSettings } from "./namespace.js";
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iBAAiB;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAWlD,sBAAsB;AACtB,OAAO,EACN,sBAAsB,EACtB,6BAA6B,EAC7B,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EAIxB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iBAAiB;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,oFAAoF;AACpF,OAAO,EACN,QAAQ,EACR,eAAe,EACf,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,MAAM,EACN,iBAAiB,EACjB,2BAA2B,EAC3B,4BAA4B,EAC5B,yBAAyB,EACzB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,sBAAsB,EACtB,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,0BAA0B,EAAE,qCAAqC,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAExJ,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,wBAAwB,EAAiD,MAAM,gBAAgB,CAAC;AAWtJ,sBAAsB;AACtB,OAAO,EACN,sBAAsB,EACtB,6BAA6B,EAC7B,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EAIxB,MAAM,gBAAgB,CAAC"}

package/dist/core/logger.d.ts

@@ -1,3 +1,8 @@
+import type { SinkImplementation } from '../kinds/sink.ts';
 import type { RuntimeLogger, RuntimeLoggerOptions } from './types.ts';
-export declare function createRuntimeLogger(options: RuntimeLoggerOptions): RuntimeLogger;
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+export declare function createRuntimeLogger(options: RuntimeLoggerOptions & {
+    sinkImpls: SinkImplementation[];
+}): RuntimeLogger;
+export declare function createRuntimeLogger(options: RuntimeLoggerOptions, runtime: RuntimeRef): Promise<RuntimeLogger>;
 //# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAuB,MAAM,YAAY,CAAC;AAoC3F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAgHhF"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAuB,MAAM,YAAY,CAAC;AAW3F,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAoB1F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG;IAAE,SAAS,EAAE,kBAAkB,EAAE,CAAA;CAAE,GAAG,aAAa,CAAC;AACxH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC"}