@vibesdotdev/logging 0.0.2 → 1.0.0-rc.4

package/dist/contexts/logger.js

@@ -3,86 +3,265 @@
  *
  * Provides logger instances to runtime assets via context injection.
  * Loggers are resolved from the runtime and cached for sync access.
+ *
+ * `getLogger(id)` expects `id` to match a registered `logging/logger` descriptor
+ * (not a dotted namespace). Use `descriptor.namespace` or `.child()` for namespacing.
+ */
+import * as z from 'zod/v4';
+import { CapabilityError, getVibesRuntime } from '@vibesdotdev/kernel';
+import { childOptionsSnapshot, deriveChildConfig } from "../kinds/logger.utils.js";
+import { ForwardedLogCallSchema } from "../core/entry-context.js";
+import { LoggedErrorSchema } from "../core/redact.js";
+import { settle } from "../core/outcome.js";
+import { prepareFallbackLoggerFactory, prepareUndeclaredLoggerFactory } from "./fallback-logger.js";
+import { isLoggingEmissionClosed } from "../core/emission-window.js";
+import { loggingRootOf } from "../core/root-identity.js";
+export const LoggerContextConfigSchema = z.object({
+    defaultNamespace: z.string().min(1),
+    defaultRuntime: z.enum(['server', 'cli', 'worker', 'browser', 'mcp'])
+});
+/**
+ * Lazy logger: created without touching any runtime, bound at emit time.
+ *
+ * Each emit requires a bound Runtime prepared by initializeLoggers(runtime).
+ * It re-resolves its base target: that Root's registered logger, then that
+ * Root's resolved logger, then its prepared fallback. Caches follow the Root's
+ * identity, so another Root never inherits the first host's console. Derivations
+ * (child/with*) are replayed onto the base and cached by base identity.
+ *
+ * `namespace`/`fullNamespace` read the last bound target (the descriptor
+ * logger's own semantics) and use the id-based derivation until first bound;
+ * they never read the runtime.
  */
-import { createFallbackLogger } from "./fallback-logger.js";
-const defaultConfig = {
+class LazyLoggerImplementation {
+    source;
+    handedRuntime;
+    derivations;
+    unboundNamespace;
+    unboundFullNamespace;
+    derivedByBase = new WeakMap();
+    lastDerived = null;
+    constructor(source, unboundId, fullNamespace = unboundId, derivations = [], handedRuntime) {
+        this.source = source;
+        this.handedRuntime = handedRuntime;
+        this.unboundNamespace = unboundId;
+        this.unboundFullNamespace = fullNamespace;
+        this.derivations = derivations;
+    }
+    get namespace() {
+        return this.lastDerived?.namespace ?? this.unboundNamespace;
+    }
+    get fullNamespace() {
+        return this.lastDerived?.fullNamespace ?? this.unboundFullNamespace;
+    }
+    resolveBase() {
+        const runtime = this.handedRuntime ?? getVibesRuntime();
+        const lifecycle = runtime.lifecycle;
+        if (this.handedRuntime && isLoggingEmissionClosed(runtime))
+            throw new CapabilityError('The logger Runtime no longer accepts entries.', 'CANCELLED', {
+                reason: 'logger-runtime-disposed', cause: lifecycle.signal.reason
+            });
+        const id = this.source.idFor(runtime);
+        const state = existingState(runtime);
+        const prepared = state?.prepared;
+        if (!state || !prepared)
+            throw new CapabilityError('Logging has not been prepared on this Runtime.', 'UNAVAILABLE', {
+                reason: 'logger-not-initialized', retryable: false, details: { id }
+            });
+        const registered = state.registered.get(id);
+        if (registered)
+            return registered;
+        const resolved = prepared.resolved.get(id);
+        if (resolved)
+            return resolved;
+        let fallback = prepared.fallbacks.get(id);
+        if (!fallback) {
+            fallback = prepared.createFallback(id);
+            prepared.fallbacks.set(id, fallback);
+        }
+        return fallback;
+    }
+    resolveTarget() {
+        const base = this.resolveBase();
+        let derived = this.derivedByBase.get(base);
+        if (!derived) {
+            derived = this.derivations.reduce((logger, derive) => derive(logger), base);
+            this.derivedByBase.set(base, derived);
+        }
+        this.lastDerived = derived;
+        return derived;
+    }
+    debug = ForwardedLogCallSchema.implement((message, context, extraContext) => { this.resolveTarget().debug(message, context, extraContext); });
+    info = ForwardedLogCallSchema.implement((message, context, extraContext) => { this.resolveTarget().info(message, context, extraContext); });
+    warn = ForwardedLogCallSchema.implement((message, context, extraContext) => { this.resolveTarget().warn(message, context, extraContext); });
+    error = ForwardedLogCallSchema.implement((message, context, extraContext) => { this.resolveTarget().error(message, context, extraContext); });
+    derive(fullNamespace, derivation) {
+        return new LazyLoggerImplementation(this.source, this.unboundNamespace, fullNamespace, [...this.derivations, derivation], this.handedRuntime);
+    }
+    /**
+     * The options are read once, here, without throwing; the bound logger is
+     * handed the detached snapshot, never the caller's object, so no later log
+     * call reads it again. An unreadable one rides every entry as the
+     * `loggingError` and is reported once by the logger the snapshot binds to.
+     */
+    child(options) {
+        const config = deriveChildConfig(this.unboundFullNamespace, options);
+        const snapshot = childOptionsSnapshot(options, config);
+        return this.derive(config.nextNamespace, (logger) => logger.child(snapshot));
+    }
+    withContext(context) {
+        return this.derive(this.unboundFullNamespace, (logger) => logger.withContext(context));
+    }
+    withRequestContext(context) {
+        return this.derive(this.unboundFullNamespace, (logger) => logger.withRequestContext(context));
+    }
+    withJobContext(context) {
+        return this.derive(this.unboundFullNamespace, (logger) => logger.withJobContext(context));
+    }
+    performanceTracker(params) {
+        return this.resolveTarget().performanceTracker(params);
+    }
+}
+const defaultConfig = LoggerContextConfigSchema.parse({
     defaultNamespace: 'vibes',
     defaultRuntime: 'server'
-};
-let activeConfig = { ...defaultConfig };
-export function configureLoggerContext(config) {
-    activeConfig = { ...activeConfig, ...config };
-}
-export function getLoggerContextConfig() {
-    return { ...activeConfig };
-}
-const loggerCache = new Map();
-export function registerLogger(id, logger) {
-    loggerCache.set(id, logger);
-}
-export async function initializeLoggers() {
-    try {
-        const { getVibesRuntime } = await import('@vibesdotdev/runtime');
-        const runtime = getVibesRuntime();
-        const loggerIds = runtime.query('logging/logger').ids();
-        const errors = [];
-        for (const id of loggerIds) {
-            try {
-                const logger = (await runtime.query('logging/logger').withId(id).resolve());
-                loggerCache.set(id, logger);
-            }
-            catch (error) {
-                // Collect errors for reporting but continue initializing other loggers
-                errors.push({ id, error });
-            }
-        }
-        // Log summary of initialization results
-        if (errors.length > 0) {
-            const fallbackLogger = createFallbackLogger('logging');
-            fallbackLogger.warn(`Failed to initialize ${errors.length} logger(s):`, {
-                loggerIds: errors.map((e) => e.id),
-                errors: errors.map((e) => e.error instanceof Error ? e.error.message : String(e.error))
-            });
+});
+const stateByRoot = new WeakMap();
+/**
+ * In-flight `initializeLoggers` per lifecycle: one preparation reads one
+ * registry (a generation's may differ from its Root's), and its result is
+ * the Root's preparation.
+ */
+const pendingByLifecycle = new WeakMap();
+/** The provider bound to one handed runtime: its lazy loggers keep that runtime's emission window. */
+const boundLoggerContexts = new WeakMap();
+/** The state of this Runtime's Root, if any was recorded. */
+function existingState(runtime) {
+    return stateByRoot.get(loggingRootOf(runtime));
+}
+/** The state this Runtime's Root owns, created on first use. */
+function stateFor(runtime) {
+    const found = existingState(runtime);
+    if (found)
+        return found;
+    const state = { registered: new Map(), config: { ...defaultConfig }, provider: undefined, prepared: undefined };
+    stateByRoot.set(loggingRootOf(runtime), state);
+    return state;
+}
+/** The Runtime a call targets: the one handed, else the process's default binding (refuses when none is bootstrapped). */
+function targetRuntime(runtime) {
+    return runtime ?? getVibesRuntime();
+}
+/** Configure this Runtime's logger-context defaults; they never reach another Runtime. */
+export function configureLoggerContext(config, runtime) {
+    const state = stateFor(targetRuntime(runtime));
+    state.config = { ...state.config, ...LoggerContextConfigSchema.partial().parse(config) };
+}
+export function getLoggerContextConfig(runtime) {
+    return { ...(existingState(targetRuntime(runtime))?.config ?? defaultConfig) };
+}
+function withHostEnvironment(logger, runtime) {
+    const tier = runtime.scope.qualifiers.environmentTier;
+    return tier ? logger.withContext({ environment: tier }) : logger;
+}
+/** Register `logger` for `id` on this Runtime only; it takes precedence over the Runtime's resolved logger. */
+export function registerLogger(id, logger, runtime) {
+    stateFor(targetRuntime(runtime)).registered.set(id, logger);
+}
+/** Prepare only host diagnostics; registration must never read stored settings. */
+export async function prepareLoggerContext(runtime) {
+    const state = stateFor(runtime);
+    if (state.prepared)
+        return;
+    const createFallback = await prepareUndeclaredLoggerFactory(runtime);
+    state.prepared = { createFallback, resolved: new Map(), fallbacks: new Map() };
+}
+/** Explicit awaited host preparation; synchronous emits never start host work. */
+export function initializeLoggers(runtime) {
+    if (!runtime)
+        return Promise.reject(new CapabilityError('Logger initialization requires a handed Runtime.', 'INVALID_INPUT', {
+            reason: 'logger-runtime-missing', retryable: false
+        }));
+    const lifecycle = runtime.lifecycle;
+    const pending = pendingByLifecycle.get(lifecycle);
+    if (pending)
+        return pending;
+    const operation = prepareLoggers(runtime).finally(() => pendingByLifecycle.delete(lifecycle));
+    pendingByLifecycle.set(lifecycle, operation);
+    return operation;
+}
+async function prepareLoggers(runtime) {
+    const createFallback = await prepareUndeclaredLoggerFactory(runtime);
+    const resolved = new Map();
+    const errors = [];
+    if (runtime.hasKind('logging/logger')) {
+        for (const descriptor of runtime.query('logging/logger').descriptors()) {
+            if (descriptor.runtime === 'mcp' && runtime.scope.surface !== 'mcp' && runtime.scope.purpose !== 'mcp')
+                continue;
+            const loaded = await settle(runtime.query('logging/logger').withId(descriptor.id).resolve()
+                .then(logger => withHostEnvironment(logger, runtime)));
+            if (loaded.failed)
+                errors.push({ id: descriptor.id, error: LoggedErrorSchema.parse(loaded.cause) });
+            else
+                resolved.set(descriptor.id, loaded.value);
         }
     }
-    catch (error) {
-        // Runtime not available - this is expected in some contexts, use fallback
-        const fallbackLogger = createFallbackLogger('logging');
-        fallbackLogger.debug('Runtime not available for logger initialization, using fallback loggers', {
-            error: error instanceof Error ? error.message : String(error)
+    if (errors.length) {
+        (await prepareFallbackLoggerFactory(runtime))('logging').warn(`Failed to initialize ${errors.length} logger(s):`, {
+            loggerIds: errors.map(failure => failure.id), errors: errors.map(failure => failure.error)
         });
     }
+    stateFor(runtime).prepared = { createFallback, resolved, fallbacks: new Map() };
 }
-export function createLoggerContextProvider(config) {
-    const mergedConfig = { ...activeConfig, ...config };
+/** A provider's lazy loggers bind at emit to the Runtime handed here, else to the default binding. */
+export function createLoggerContextProvider(config, runtime) {
+    const overrides = LoggerContextConfigSchema.partial().parse(config ?? {});
+    const defaultNamespaceFor = (target) => overrides.defaultNamespace ?? getLoggerContextConfig(target).defaultNamespace;
+    // Memoize lazy loggers per provider so getLogger('x') returns the same instance
+    const lazyLoggerCache = new Map();
+    let lazyDefault;
     return {
         getLogger(id) {
-            let logger = loggerCache.get(id);
-            if (logger)
-                return logger;
-            logger = createFallbackLogger(id);
-            loggerCache.set(id, logger);
-            return logger;
+            // Return a lazy logger that defers resolution to first emit
+            let lazy = lazyLoggerCache.get(id);
+            if (!lazy) {
+                lazy = new LazyLoggerImplementation({ idFor: () => id }, id, id, [], runtime);
+                lazyLoggerCache.set(id, lazy);
+            }
+            return lazy;
         },
         getDefaultLogger() {
-            return this.getLogger(mergedConfig.defaultNamespace);
+            // The default namespace is the emitting Runtime's own configuration, read at emit.
+            lazyDefault ??= new LazyLoggerImplementation({ idFor: defaultNamespaceFor }, overrides.defaultNamespace ?? (runtime ? getLoggerContextConfig(runtime).defaultNamespace : defaultConfig.defaultNamespace), undefined, [], runtime);
+            return lazyDefault;
         }
     };
 }
-let globalLoggerContext = null;
-export function getLoggerContext() {
-    if (!globalLoggerContext) {
-        globalLoggerContext = createLoggerContextProvider();
+/** The provider this Runtime serves: the one substituted with `setLoggerContext`, else the one bound to it. */
+export function getLoggerContext(runtime) {
+    const target = targetRuntime(runtime);
+    const substituted = existingState(target)?.provider;
+    if (substituted)
+        return substituted;
+    let provider = boundLoggerContexts.get(target);
+    if (!provider) {
+        provider = createLoggerContextProvider(undefined, target);
+        boundLoggerContexts.set(target, provider);
     }
-    return globalLoggerContext;
+    return provider;
 }
-export function setLoggerContext(provider) {
-    globalLoggerContext = provider;
+/** Substitute the provider that `getLogger(id, runtime)` and `getDefaultLogger(runtime)` serve for this Runtime only. */
+export function setLoggerContext(provider, runtime) {
+    stateFor(targetRuntime(runtime)).provider = provider;
 }
-export function getLogger(id) {
-    return getLoggerContext().getLogger(id);
+/**
+ * A logger by id. With a Runtime it is that Runtime's logger through its
+ * provider; without one it is a lazy logger bound at emit to the default binding.
+ */
+export function getLogger(id, runtime) {
+    return (runtime ? getLoggerContext(runtime) : createLoggerContextProvider()).getLogger(id);
 }
-export function getDefaultLogger() {
-    return getLoggerContext().getDefaultLogger();
+export function getDefaultLogger(runtime) {
+    return (runtime ? getLoggerContext(runtime) : createLoggerContextProvider()).getDefaultLogger();
 }
 //# sourceMappingURL=logger.js.map

package/dist/contexts/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/contexts/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAS5D,MAAM,aAAa,GAAwB;IAC1C,gBAAgB,EAAE,OAAO;IACzB,cAAc,EAAE,QAAQ;CACxB,CAAC;AAEF,IAAI,YAAY,GAAG,EAAE,GAAG,aAAa,EAAE,CAAC;AAExC,MAAM,UAAU,sBAAsB,CAAC,MAAoC;IAC1E,YAAY,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,MAAM,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,sBAAsB;IACrC,OAAO,EAAE,GAAG,YAAY,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,WAAW,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE5D,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,MAA4B;IACtE,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACtC,IAAI,CAAC;QACJ,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,GAAG,EAAE,CAAC;QACxD,MAAM,MAAM,GAA0C,EAAE,CAAC;QAEzD,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAyB,CAAC;gBACpG,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,uEAAuE;gBACvE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;QAED,wCAAwC;QACxC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,cAAc,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;YACvD,cAAc,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,MAAM,aAAa,EAAE;gBACvE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACxB,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAC5D;aACD,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,0EAA0E;QAC1E,MAAM,cAAc,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;QACvD,cAAc,CAAC,KAAK,CAAC,yEAAyE,EAAE;YAC/F,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC7D,CAAC,CAAC;IACJ,CAAC;AACF,CAAC;AAOD,MAAM,UAAU,2BAA2B,CAC1C,MAAqC;IAErC,MAAM,YAAY,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,MAAM,EAAE,CAAC;IAEpD,OAAO;QACN,SAAS,CAAC,EAAU;YACnB,IAAI,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjC,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1B,MAAM,GAAG,oBAAoB,CAAC,EAAE,CAAC,CAAC;YAClC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,MAAM,CAAC;QACf,CAAC;QAED,gBAAgB;YACf,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;QACtD,CAAC;KACD,CAAC;AACH,CAAC;AAED,IAAI,mBAAmB,GAAiC,IAAI,CAAC;AAE7D,MAAM,UAAU,gBAAgB;IAC/B,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC1B,mBAAmB,GAAG,2BAA2B,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,mBAAmB,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAA+B;IAC/D,mBAAmB,GAAG,QAAQ,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,EAAU;IACnC,OAAO,gBAAgB,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC/B,OAAO,gBAAgB,EAAE,CAAC,gBAAgB,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/contexts/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AAWxF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,4BAA4B,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAKzD,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;CACrE,CAAC,CAAC;AAUH;;;;;;;;;;;;GAYG;AACH,MAAM,wBAAwB;IAQX;IAIA;IAXD,WAAW,CAAwB;IACnC,gBAAgB,CAAS;IACzB,oBAAoB,CAAS;IAC7B,aAAa,GAAG,IAAI,OAAO,EAA8C,CAAC;IACnF,WAAW,GAAgC,IAAI,CAAC;IAExD,YACkB,MAAsB,EACvC,SAAiB,EACjB,gBAAwB,SAAS,EACjC,cAAqC,EAAE,EACtB,aAA0B;QAJ1B,WAAM,GAAN,MAAM,CAAgB;QAItB,kBAAa,GAAb,aAAa,CAAa;QAE3C,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,oBAAoB,GAAG,aAAa,CAAC;QAC1C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAChC,CAAC;IAED,IAAI,SAAS;QACZ,OAAO,IAAI,CAAC,WAAW,EAAE,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC;IAC7D,CAAC;IAED,IAAI,aAAa;QAChB,OAAO,IAAI,CAAC,WAAW,EAAE,aAAa,IAAI,IAAI,CAAC,oBAAoB,CAAC;IACrE,CAAC;IAEO,WAAW;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,IAAI,eAAe,EAAE,CAAC;QACxD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,IAAI,IAAI,CAAC,aAAa,IAAI,uBAAuB,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,eAAe,CAAC,+CAA+C,EAAE,WAAW,EAAE;gBACnJ,MAAM,EAAE,yBAAyB,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM;aACjE,CAAC,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,KAAK,EAAE,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,eAAe,CAAC,gDAAgD,EAAE,aAAa,EAAE;gBACnH,MAAM,EAAE,wBAAwB,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE;aACnE,CAAC,CAAC;QACH,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5C,IAAI,UAAU;YAAE,OAAO,UAAU,CAAC;QAClC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,IAAI,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,QAAQ,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YACvC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,QAAQ,CAAC;IACjB,CAAC;IAEO,aAAa;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;YAClG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;QAC3B,OAAO,OAAO,CAAC;IAChB,CAAC;IAEQ,KAAK,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9I,IAAI,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5I,IAAI,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5I,KAAK,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/I,MAAM,CAAC,aAAqB,EAAE,UAAsB;QAC3D,OAAO,IAAI,wBAAwB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,aAAa,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IAC/I,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAA2B;QAChC,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;QACrE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,WAAW,CAAC,OAAmB;QAC9B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,kBAAkB,CAAC,OAA0B;QAC5C,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,cAAc,CAAC,OAAsB;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,kBAAkB,CAAC,MAAgC;QAClD,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACxD,CAAC;CACD;AAED,MAAM,aAAa,GAAwB,yBAAyB,CAAC,KAAK,CAAC;IAC1E,gBAAgB,EAAE,OAAO;IACzB,cAAc,EAAE,QAAQ;CACxB,CAAC,CAAC;AA4BH,MAAM,WAAW,GAAG,IAAI,OAAO,EAAwC,CAAC;AACxE;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAA0C,CAAC;AACjF,sGAAsG;AACtG,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAAqC,CAAC;AAE7E,6DAA6D;AAC7D,SAAS,aAAa,CAAC,OAAmB;IACzC,OAAO,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,gEAAgE;AAChE,SAAS,QAAQ,CAAC,OAAmB;IACpC,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,KAAK,GAAoB,EAAE,UAAU,EAAE,IAAI,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACjI,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC;AACd,CAAC;AAED,0HAA0H;AAC1H,SAAS,aAAa,CAAC,OAA+B;IACrD,OAAO,OAAO,IAAI,eAAe,EAAE,CAAC;AACrC,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,sBAAsB,CAAC,MAAoC,EAAE,OAAoB;IAChG,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,KAAK,CAAC,MAAM,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,yBAAyB,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAoB;IAC1D,OAAO,EAAE,GAAG,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,IAAI,aAAa,CAAC,EAAE,CAAC;AAChF,CAAC;AAED,SAAS,mBAAmB,CAAC,MAA4B,EAAE,OAAmB;IAC7E,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,eAAe,CAAC;IACtD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAClE,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,MAA4B,EAAE,OAAoB;IAC5F,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAmB;IAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO;IAC3B,MAAM,cAAc,GAAG,MAAM,8BAA8B,CAAC,OAAO,CAAC,CAAC;IACrE,KAAK,CAAC,QAAQ,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;AAChF,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACpD,IAAI,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,eAAe,CAAC,kDAAkD,EAAE,eAAe,EAAE;YAC5H,MAAM,EAAE,wBAAwB,EAAE,SAAS,EAAE,KAAK;SAClD,CAAC,CAAC,CAAC;IACJ,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9F,kBAAkB,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC7C,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAmB;IAChD,MAAM,cAAc,GAAG,MAAM,8BAA8B,CAAC,OAAO,CAAC,CAAC;IACrE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;IACzD,MAAM,MAAM,GAA8C,EAAE,CAAC;IAC7D,IAAI,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACvC,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,KAAK,CAAyC,gBAAgB,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YAChH,IAAI,UAAU,CAAC,OAAO,KAAK,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,KAAK,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,KAAK,KAAK;gBAAE,SAAS;YACjH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAyC,gBAAgB,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE;iBACjI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;YACxD,IAAI,MAAM,CAAC,MAAM;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;;gBAC/F,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAChD,CAAC;IACF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,CAAC,MAAM,4BAA4B,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,MAAM,aAAa,EAAE;YACjH,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;SAC1F,CAAC,CAAC;IACJ,CAAC;IACD,QAAQ,CAAC,OAAO,CAAC,CAAC,QAAQ,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;AACjF,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,2BAA2B,CAC1C,MAAqC,EACrC,OAAoB;IAEpB,MAAM,SAAS,GAAG,yBAAyB,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC1E,MAAM,mBAAmB,GAAG,CAAC,MAAkB,EAAU,EAAE,CAAC,SAAS,CAAC,gBAAgB,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC,gBAAgB,CAAC;IAC1I,gFAAgF;IAChF,MAAM,eAAe,GAAG,IAAI,GAAG,EAAoC,CAAC;IACpE,IAAI,WAAiD,CAAC;IAEtD,OAAO;QACN,SAAS,CAAC,EAAU;YACnB,4DAA4D;YAC5D,IAAI,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACnC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACX,IAAI,GAAG,IAAI,wBAAwB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;gBAC9E,eAAe,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,gBAAgB;YACf,mFAAmF;YACnF,WAAW,KAAK,IAAI,wBAAwB,CAC3C,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAC9B,SAAS,CAAC,gBAAgB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,aAAa,CAAC,gBAAgB,CAAC,EAC3H,SAAS,EACT,EAAE,EACF,OAAO,CACP,CAAC;YACF,OAAO,WAAW,CAAC;QACpB,CAAC;KACD,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACpD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IACpD,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,IAAI,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,QAAQ,GAAG,2BAA2B,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC1D,mBAAmB,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,yHAAyH;AACzH,MAAM,UAAU,gBAAgB,CAAC,QAA+B,EAAE,OAAoB;IACrF,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,OAAoB;IACzD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,2BAA2B,EAAE,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACpD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,2BAA2B,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC;AACjG,CAAC"}

package/dist/core/attempt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Keep a raised failure as a value so the caller decides what it means.
+ *
+ * A host call (filesystem, stdio, a handed callback) answers with a value or
+ * raises. These helpers turn the raise into a `Failure` that carries the
+ * failure exactly as raised plus the errno category it names, parsed once
+ * here. A caller then handles only the categories it owns (a missing path is
+ * `ENOENT`) and rethrows, records or reports every other failure with its
+ * cause intact.
+ */
+/** A failure an operation raised. */
+export interface Failure {
+    /** The errno category (`ENOENT`, `EACCES`, …), or null when the failure names none. */
+    readonly code: string | null;
+    /** The failure as it was raised; a caller that does not handle it rethrows this value unchanged. */
+    readonly cause: unknown;
+}
+/** What an operation answered: its value, or the failure it raised, never both. */
+export type Attempt<T> = {
+    readonly value: T;
+} | {
+    readonly failure: Failure;
+};
+/** Run a synchronous operation and keep its failure as a value. */
+export declare function attemptSync<T>(operation: () => T): Attempt<T>;
+/** Run an asynchronous operation and keep its failure (a throw or a rejection) as a value. */
+export declare function attempt<T>(operation: () => Promise<T>): Promise<Attempt<T>>;
+/** The one confirmed-absence category: the path is not there. */
+export declare function isMissingPath(failure: Failure): boolean;
+//# sourceMappingURL=attempt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.d.ts","sourceRoot":"","sources":["../../src/core/attempt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH,qCAAqC;AACrC,MAAM,WAAW,OAAO;IACvB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/E,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM7D;AAED,8FAA8F;AAC9F,wBAAsB,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAMjF;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEvD"}

package/dist/core/attempt.js

@@ -0,0 +1,44 @@
+/**
+ * Keep a raised failure as a value so the caller decides what it means.
+ *
+ * A host call (filesystem, stdio, a handed callback) answers with a value or
+ * raises. These helpers turn the raise into a `Failure` that carries the
+ * failure exactly as raised plus the errno category it names, parsed once
+ * here. A caller then handles only the categories it owns (a missing path is
+ * `ENOENT`) and rethrows, records or reports every other failure with its
+ * cause intact.
+ */
+import * as z from 'zod/v4';
+import { attempt as attemptOutcome } from "./outcome.js";
+const NativeCodeSchema = z.object({ code: z.string() });
+/**
+ * The errno category a raised value names, or null. Reading it never throws: a
+ * value whose `code` read throws (a getter or Proxy trap) names no category.
+ */
+const NativeCodeOfSchema = z.unknown().transform((cause) => {
+    const native = attemptOutcome(() => NativeCodeSchema.safeParse(cause));
+    return !native.failed && native.value.success ? native.value.data.code : null;
+});
+/** Run a synchronous operation and keep its failure as a value. */
+export function attemptSync(operation) {
+    try {
+        return { value: operation() };
+    }
+    catch (cause) {
+        return { failure: { code: NativeCodeOfSchema.parse(cause), cause } };
+    }
+}
+/** Run an asynchronous operation and keep its failure (a throw or a rejection) as a value. */
+export async function attempt(operation) {
+    try {
+        return { value: await operation() };
+    }
+    catch (cause) {
+        return { failure: { code: NativeCodeOfSchema.parse(cause), cause } };
+    }
+}
+/** The one confirmed-absence category: the path is not there. */
+export function isMissingPath(failure) {
+    return failure.code === 'ENOENT';
+}
+//# sourceMappingURL=attempt.js.map

package/dist/core/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../../src/core/attempt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAiB,EAAE;IACzE,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC,CAAC,CAAC;AAaH,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAI,SAAkB;IAChD,IAAI,CAAC;QACJ,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;IACtE,CAAC;AACF,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,SAA2B;IAC3D,IAAI,CAAC;QACJ,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,EAAE,EAAE,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;IACtE,CAAC;AACF,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC7C,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClC,CAAC"}

package/dist/core/emission-window.d.ts

@@ -0,0 +1,34 @@
+/**
+ * When a Runtime's loggers stop accepting entries.
+ *
+ * Disposal begins by aborting `lifecycle.signal`, then runs every plugin's
+ * `onDispose` in reverse dependency order, so a plugin that depends on Logging
+ * finalizes while Logging is still open and may log while it does. Emission
+ * therefore stays open through finalization and closes once Logging's own
+ * finalization ran on the Root (its plugin's or the host preparation plugin's
+ * `onDispose`), or once the handed runtime's own lifecycle phase is
+ * `disposed`.
+ *
+ * Two granularities, on purpose. The close Logging's finalization records is
+ * the Root's (`loggingRootOf(runtime)`): the Root, its views and every reload
+ * generation it still holds refuse from then on, because the services they
+ * borrow are being finalized. A runtime's own `disposed` phase is that
+ * lifecycle's: a retired generation refuses on its own, and its retirement
+ * never closes the Root or the generation now serving.
+ */
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+/**
+ * Logging's finalization on `runtime` ran: its Root's loggers refuse every
+ * later entry. It closes only a finalizing lifecycle. On a live Runtime
+ * (Logging retracted by `retractPlugin`, or a replaced Logging retiring with
+ * its reload generation, while the Root keeps running) it records nothing, so
+ * the Root's later disposal opens a full finalization window again.
+ */
+export declare function closeLoggingEmission(runtime: RuntimeRef): void;
+/**
+ * True once `runtime` no longer accepts log entries: once Logging finalized
+ * its Root, and always once the runtime's own lifecycle is `disposed`; never
+ * otherwise, so a live or finalizing runtime of an open Root still emits.
+ */
+export declare function isLoggingEmissionClosed(runtime: RuntimeRef): boolean;
+//# sourceMappingURL=emission-window.d.ts.map

package/dist/core/emission-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emission-window.d.ts","sourceRoot":"","sources":["../../src/core/emission-window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAGpE"}

package/dist/core/emission-window.js

@@ -0,0 +1,25 @@
+import { loggingRootOf } from "./root-identity.js";
+const closedRoots = new WeakSet();
+/**
+ * Logging's finalization on `runtime` ran: its Root's loggers refuse every
+ * later entry. It closes only a finalizing lifecycle. On a live Runtime
+ * (Logging retracted by `retractPlugin`, or a replaced Logging retiring with
+ * its reload generation, while the Root keeps running) it records nothing, so
+ * the Root's later disposal opens a full finalization window again.
+ */
+export function closeLoggingEmission(runtime) {
+    if (runtime.lifecycle.phase === 'live')
+        return;
+    closedRoots.add(loggingRootOf(runtime));
+}
+/**
+ * True once `runtime` no longer accepts log entries: once Logging finalized
+ * its Root, and always once the runtime's own lifecycle is `disposed`; never
+ * otherwise, so a live or finalizing runtime of an open Root still emits.
+ */
+export function isLoggingEmissionClosed(runtime) {
+    if (closedRoots.has(loggingRootOf(runtime)))
+        return true;
+    return runtime.lifecycle.phase === 'disposed';
+}
+//# sourceMappingURL=emission-window.js.map

package/dist/core/emission-window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emission-window.js","sourceRoot":"","sources":["../../src/core/emission-window.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,MAAM,WAAW,GAAG,IAAI,OAAO,EAAuB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAmB;IACvD,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO;IAC/C,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAmB;IAC1D,IAAI,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,KAAK,UAAU,CAAC;AAC/C,CAAC"}

package/dist/core/endpoint.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { type LoggedError } from './redact.ts';
+/** What an endpoint that is not a URL echoes as: its text could be anything, so none of it is shown. */
+export declare 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 declare const RedactedEndpointSchema: z.ZodPipe<z.ZodCustom<string, string>, z.ZodTransform<string, string>>;
+/**
+ * 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 declare const CREDENTIAL_QUERY_PARAMETER_NAMES: readonly ["token", "key", "apikey", "api_key", "access_token", "secret", "sig", "signature", "password", "pass", "pwd", "auth", "authorization", "code", "session", "sessionid", "sid", "jwt", "bearer", "credential"];
+/** Below this length a fragment is matched only as a whole token; at or above it, anywhere. */
+export declare const SUBSTRING_FRAGMENT_MIN_LENGTH = 4;
+/** 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 declare 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 declare function createEndpointTextSchema(endpoint: string, secrets?: readonly string[]): z.ZodType<string>;
+/** What a failure is described as when its description cannot be scrubbed: no value of it is shown. */
+export declare const UNSCRUBBABLE_FAILURE_MESSAGE = "The failure could not be described without its endpoint credentials, so none of its text is shown.";
+/**
+ * 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 declare function createEndpointFailureSchema(endpoint: string, secrets?: readonly string[]): z.ZodType<LoggedError>;
+//# sourceMappingURL=endpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/core/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,OAAO,EAAgE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7G,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D,iJAAiJ;AACjJ,eAAO,MAAM,sBAAsB,wEAUjC,CAAC;AAgCH;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,wNAGnC,CAAC;AAsDX,+FAA+F;AAC/F,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAkC/C,4IAA4I;AAC5I,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,MAAM,EAAO,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAO7G;AA2CD,uGAAuG;AACvG,eAAO,MAAM,4BAA4B,uGAAuG,CAAC;AAmBjJ;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,MAAM,EAAO,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAYrH"}