@vibesdotdev/logging 0.0.2 → 1.0.0-rc.4

package/dist/core/root-identity.js

@@ -0,0 +1,23 @@
+/**
+ * The Root a runtime belongs to, as the kernel knows it. Logging keys every
+ * per-Root state (registrations, settings, namespace selection, emission
+ * window, resources, stdout capture, error tracking, telemetry) by it.
+ *
+ * It is `rootIdentityOf(runtime)`, never the runtime's own `rootIdentity`
+ * property: a Proxy or derived object can answer another Root's readable
+ * identity, and must not reach that Root's Logging state. A runtime the kernel
+ * neither constructed nor viewed names no Root and is refused typed.
+ */
+import { CapabilityError, rootIdentityOf } from '@vibesdotdev/kernel';
+export function loggingRootOf(runtime) {
+    const identity = rootIdentityOf(runtime);
+    if (!identity) {
+        throw new CapabilityError('Logging state is root-scoped; this runtime is not one the kernel constructed or viewed, so it names no root.', 'INVALID_INPUT', {
+            reason: 'logging-runtime-unidentified',
+            retryable: false,
+            recoveryHint: 'Hand the booted root, a plugin view, a reload generation or the generation dispatcher; a runtime double or Proxy cannot stand in.'
+        });
+    }
+    return identity;
+}
+//# sourceMappingURL=root-identity.js.map

package/dist/core/root-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-identity.js","sourceRoot":"","sources":["../../src/core/root-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,cAAc,EAA6C,MAAM,qBAAqB,CAAC;AAEjH,MAAM,UAAU,aAAa,CAAC,OAAmB;IAChD,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CAAC,8GAA8G,EAAE,eAAe,EAAE;YAC1J,MAAM,EAAE,8BAA8B;YACtC,SAAS,EAAE,KAAK;YAChB,YAAY,EAAE,mIAAmI;SACjJ,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/core/types.d.ts

@@ -4,15 +4,16 @@
  * Interfaces for logger instances and factories.
  */
 import type { LogLevel, LogContext, LoggerChildOptions, RequestLogContext, JobLogContext, PerformanceTracker, PerformanceTrackerParams } from '../schemas/entry.ts';
+import type { LogMethod } from './normalize.ts';
 import type { SinkImplementation } from '../kinds/sink.ts';
 /**
  * Base logger interface.
  */
 export interface Logger {
-    debug(message: string, context?: unknown): void;
-    info(message: string, context?: unknown): void;
-    warn(message: string, context?: unknown): void;
-    error(message: string, context?: unknown): void;
+    debug: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+    error: LogMethod;
     child?(options: LoggerChildOptions): Logger;
     namespace?: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC5C,oDAAoD;IACpD,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAAC;IAClD,2CAA2C;IAC3C,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,aAAa,CAAC;IAChD,mCAAmC;IACnC,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAAC;IAC9D,+BAA+B;IAC/B,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC;IACtD,yDAAyD;IACzD,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,kBAAkB,CAAC;IACzE,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,UAAU,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC5C,oDAAoD;IACpD,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAAC;IAClD,2CAA2C;IAC3C,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,aAAa,CAAC;IAChD,mCAAmC;IACnC,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAAC;IAC9D,+BAA+B;IAC/B,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC;IACtD,yDAAyD;IACzD,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,kBAAkB,CAAC;IACzE,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,UAAU,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/docs/cli.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=cli.docs.descriptor.d.ts.map

package/dist/docs/cli.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/cli.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA8FjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/cli.docs.descriptor.js

@@ -0,0 +1,97 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'logging.cli',
+    title: 'vibes logs',
+    summary: 'List, view, tail, search and rotate log outputs, and inspect audit logs, from the CLI',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: vibes logs
+summary: List, view, tail, search and rotate log outputs, and inspect audit logs, from the CLI
+tags: [logging, cli, logs, tail, search, rotate, audit]
+parent: logging
+order: 4
+id: logging.cli
+surfaces: [cli]
+hardware: [consumer]
+---
+
+# vibes logs
+
+The \`logs\` command group reads the \`logging/output\` and \`logging/audit\`
+descriptors registered on the runtime. Commands never import a sink or output
+directly, so they show whatever the host registered: the host's
+\`nodeLoggingPlugin\` adds the \`file\` and \`mcp-stdout-capture\` outputs.
+The capture output is owned by its stdout-capture lease, which writes to the
+global log directory, so \`logs list\`, \`logs search\` and \`logs rotate --all\`
+skip it and naming it refuses \`output-lease-owned\`. A \`remote\` output ships
+its entries to its endpoint and keeps none locally, so the same commands skip it
+and naming it (\`view\`, \`tail\`, \`rotate\`, \`search --output\`) refuses
+\`output-not-readable\`: read its entries where they land.
+
+Register the commands by adding \`@vibesdotdev/logging/cli/plugin\` after the
+core \`@vibesdotdev/logging/plugin\` on a CLI surface.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| \`vibes logs list [--json]\` | List registered outputs with storage, format, path, size and last modified time |
+| \`vibes logs view [output]\` | Print recent entries. \`-n, --lines <count>\` (default 50), \`--offset <count>\`, \`-f, --filter <pattern>\`, \`-i, --ignore-case\`, \`--json\`, \`--raw\` |
+| \`vibes logs tail [output]\` | Follow an output live. \`-n, --lines <count>\` (default 10), \`-f, --filter <pattern>\`, \`-i\`, \`--level <level>\`. Runs until interrupted |
+| \`vibes logs search <pattern>\` | Search entries (regex by default). \`-o, --output <id>\`, \`-n, --max <count>\` (default 100), \`-i\`, \`--level\`, \`--since <time>\` (\`1h\`, \`30m\`, an ISO date), \`-C, --context <lines>\`, \`-F, --fixed\`, \`--json\` |
+| \`vibes logs rotate [output]\` | Rotate an output file. \`--all\` rotates every output; \`--cleanup\` also runs rotated-file and audit retention; \`--audit\` enforces audit retention only. With no output, pass \`--all\`, \`--audit\` or \`--cleanup\`. An output with nothing to rotate is reported as such |
+| \`vibes logs audit list <category>\` | Query audit entries for a category or audit logger id. \`--since <iso>\`, \`--limit <n>\` (default 100), \`--output json\\|table\` |
+| \`vibes logs audit cleanup\` | Enforce audit retention for every audit logger, or one with \`--id <auditId>\` |
+
+Every flag is checked before the command does anything: counts are digits only,
+\`--level\` is \`debug\`, \`info\`, \`warn\` or \`error\`, and \`--since\` is a
+relative age (\`30s\`, \`15m\`, \`1h\`, \`2d\`) or an ISO 8601 date or date-time
+(\`audit list --since\`: ISO only). Anything else is refused naming the flag
+(\`INVALID_INPUT logs-flag-invalid\`).
+
+## Examples
+
+\`\`\`bash
+vibes logs list
+vibes logs view file -n 200 --filter error -i
+vibes logs tail mcp-server --level warn
+vibes logs search 'ECONNREFUSED' --since 1h -C 2
+vibes logs rotate file --cleanup
+vibes logs audit list authentication --since 2026-01-01T00:00:00Z --output json
+\`\`\`
+
+## Behaviour
+
+- Every command writes through the runtime's host text output: results,
+  \`--json\` documents and tables on stdout, diagnostics (an invalid search
+  pattern, a skipped unreadable output) on stderr. A failure ends in a typed
+  refusal and the CLI sets the exit status.
+- \`search -n/--max\` takes a whole number above 0 and \`-C/--context\` a whole
+  number; other text is refused naming the flag. Naming an output that is not
+  registered refuses \`NOT_FOUND\`; an output that fails to load reports its own
+  failure.
+- \`search -C <lines>\` prints each match between its neighbouring lines, with
+  \`--\` between groups; with \`--json\` each match carries them as
+  \`contextBefore\` and \`contextAfter\`.
+- \`tail\` stops on the host's SIGINT or SIGTERM, or when its runtime is
+  disposed; it never force-exits the host.
+- Audit categories are \`authentication\`, \`authorization\`, \`security\`,
+  \`data_access\`, \`data_modification\`, \`configuration\` and \`system\`.
+
+:::card{title="See also"}
+- [\`logging\`](logging) — package overview and configuration keys
+- [\`logging.transports\`](logging.transports) — outputs and rotation
+:::
+`
+    },
+    parent: 'logging',
+    order: 4,
+    tags: ['logging', 'cli', 'logs', 'tail', 'search', 'rotate', 'audit'],
+    surfaces: ['cli'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=cli.docs.descriptor.js.map

package/dist/docs/cli.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/cli.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,uFAAuF;IAChG,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8ET;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC;IACrE,QAAQ,EAAE,CAAC,KAAK,CAAC;IACjB,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/index.d.ts

@@ -0,0 +1,7 @@
+export { default as loggingDocsDescriptor } from './logging.docs.descriptor.ts';
+export { default as levelsDocsDescriptor } from './levels.docs.descriptor.ts';
+export { default as structuredDocsDescriptor } from './structured.docs.descriptor.ts';
+export { default as transportsDocsDescriptor } from './transports.docs.descriptor.ts';
+export { default as cliDocsDescriptor } from './cli.docs.descriptor.ts';
+export { default as observabilityDocsDescriptor } from './observability.docs.descriptor.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/docs/index.js

@@ -0,0 +1,7 @@
+export { default as loggingDocsDescriptor } from "./logging.docs.descriptor.js";
+export { default as levelsDocsDescriptor } from "./levels.docs.descriptor.js";
+export { default as structuredDocsDescriptor } from "./structured.docs.descriptor.js";
+export { default as transportsDocsDescriptor } from "./transports.docs.descriptor.js";
+export { default as cliDocsDescriptor } from "./cli.docs.descriptor.js";
+export { default as observabilityDocsDescriptor } from "./observability.docs.descriptor.js";
+//# sourceMappingURL=index.js.map

package/dist/docs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/docs/levels.docs.descriptor.d.ts

@@ -1,4 +1,4 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
 declare const descriptor: DocsTopicDescriptor;
 export default descriptor;
 //# sourceMappingURL=levels.docs.descriptor.d.ts.map

package/dist/docs/levels.docs.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"levels.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/levels.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,QAAA,MAAM,UAAU,EAAE,mBAmVjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"levels.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/levels.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA6MjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/levels.docs.descriptor.js

@@ -12,322 +12,188 @@ summary: Log levels (debug, info, warn, error) and filtering
 tags: [logging, levels, debug, info, warn, error, filtering]
 parent: logging
 order: 1
+id: logging.levels
 surfaces: [cli, web, in-app]
 hardware: [consumer, cloud]
 ---
 
 # Log Levels
 
-Log levels categorize log entries by severity. The logging system provides five standard levels with automatic filtering based on configuration.
-
-## Level Hierarchy
-
-\`\`\`
-trace < debug < info < warn < error
-\`\`\`
-
-Each level includes all levels above it. Setting level to \`warn\` logs \`warn\` and \`error\` only.
-
-## Level Definitions
-
-### Trace (0)
-
-Fine-grained debugging information:
+Log levels categorize log entries by severity. The logging package defines four
+levels, exported as \`LogLevelSchema\` / \`LogLevel\`:
 
 \`\`\`ts
-logger.trace('Entering function', { fn: 'processUser', userId: '123' });
-\`\`\`
-
-**Use for:**
-- Function entry/exit
-- Variable values during debugging
-- Detailed execution flow
+import { LogLevelSchema, type LogLevel, LOG_LEVEL_ORDER } from '@vibesdotdev/logging';
 
-**Typical output:**
-\`\`\`
-[TRACE] [app:user] Entering function {"fn":"processUser","userId":"123"}
-\`\`\`
-
-### Debug (1)
-
-Debugging information for development:
-
-\`\`\`ts
-logger.debug('Database query executed', {
-  query: 'SELECT * FROM users',
-  duration: 45
-});
+// LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error'])
+// LOG_LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 }
 \`\`\`
 
-**Use for:**
-- SQL queries
-- API requests
-- Configuration values
-- Performance metrics
+## Level Hierarchy
 
-**Typical output:**
 \`\`\`
-[DEBUG] [app:db] Database query executed {"query":"SELECT * FROM users","duration":45}
+debug < info < warn < error
 \`\`\`
 
-### Info (2)
+A logger emits an entry when its level priority is at or above the active
+baseline level. With a baseline of \`warn\`, only \`warn\` and \`error\` entries are
+emitted (namespace selectors can re-include lower levels — see below).
 
-General informational messages:
+## Emitting Logs
 
-\`\`\`ts
-logger.info('Server started', {
-  port: 3000,
-  environment: 'development'
-});
-\`\`\`
-
-**Use for:**
-- Application lifecycle events
-- User actions (login, logout)
-- System state changes
-- Successful operations
-
-**Typical output:**
-\`\`\`
-[INFO] [app:server] Server started {"port":3000,"environment":"development"}
-\`\`\`
-
-### Warn (3)
-
-Warning conditions:
+Get a logger from the runtime and call one of the four level methods. Each
+takes a message and an optional context object.
 
 \`\`\`ts
-logger.warn('High memory usage detected', {
-  usage: '85%',
-  threshold: '80%'
-});
-\`\`\`
-
-**Use for:**
-- Resource warnings
-- Deprecated API usage
-- Recoverable errors
-- Performance degradation
+import { getLogger } from '@vibesdotdev/logging';
 
-**Typical output:**
-\`\`\`
-[WARN] [app:monitor] High memory usage detected {"usage":"85%","threshold":"80%"}
-\`\`\`
-
-### Error (4)
+// runtime is the runtime your host booted and handed to this code.
+const log = getLogger('myapp', runtime);
+log.info('Server started', { port: 3000, environment: 'development' });
 
-Error conditions:
-
-\`\`\`ts
-logger.error('Database connection failed', {
-  error: error.message,
-  host: config.db.host
-});
+// Named logger (resolved from a registered LoggerDescriptor by id)
+const db = getLogger('myapp:db', runtime);
+db.debug('Database query executed', { query: 'SELECT * FROM users', duration: 45 });
+db.warn('High memory usage detected', { usage: '85%', threshold: '80%' });
+db.error('Connection failed', { error: 'ECONNREFUSED', host: 'localhost' });
 \`\`\`
 
-**Use for:**
-- Unhandled exceptions
-- Failed operations
-- System errors
-- External service failures
+\`LoggerImplementation\` exposes exactly these emit methods — \`debug\`, \`info\`,
+\`warn\`, and \`error\`. There is no \`trace\` level and no \`log()\` catch-all.
 
-**Typical output:**
-\`\`\`
-[ERROR] [app:db] Database connection failed {"error":"ECONNREFUSED","host":"localhost"}
-\`\`\`
+The context argument is normalized: passing an \`Error\` expands to
+\`{ errorName, errorMessage, stack }\`; a plain object is merged as-is.
 
-## Setting Log Level
+### Level Definitions
 
-### Environment Variable
+- **debug** — development detail: SQL queries, request/response payloads, resolved config, timings.
+- **info** — lifecycle and successful operations: startup, user actions, state changes.
+- **warn** — recoverable problems: resource pressure, deprecated usage, retried failures.
+- **error** — failed operations and unhandled exceptions.
 
-\`\`\`bash
-# Set minimum level
-export LOG_LEVEL=debug
+## Setting the Level
 
-# Levels: trace, debug, info, warn, error
-\`\`\`
-
-### Programmatic Configuration
+The minimum level is configured **per logger** on its \`LoggerDescriptor\`, not
+via a runtime \`setLevel()\` call. Define a descriptor (kind \`logging/logger\`) and
+register it:
 
 \`\`\`ts
-import { logger } from '@vibesdotdev/logging';
+import type { LoggerDescriptor } from '@vibesdotdev/logging';
 
-logger.setLevel('debug');
+const descriptor: LoggerDescriptor = {
+  kind: 'logging/logger',
+  id: 'myapp',
+  namespace: 'myapp',
+  runtime: 'server',
+  sinks: ['console'],
+  level: 'info' // defaults to 'info'
+};
 
-// Only debug, info, warn, error will be logged
-// trace will be filtered out
+export default descriptor;
 \`\`\`
 
-### Config Manifest
+The active baseline level and namespace selectors also come from the host
+environment, parsed via \`parseNamespaceSettingsFromEnv\`:
 
 \`\`\`ts
-const loggingConfig = await runtime.query('config/manifest')
-  .filter(d => d.id === 'logging')
-  .resolve();
+import {
+  parseNamespaceSettingsFromEnv,
+  updateNamespaceSettings
+} from '@vibesdotdev/logging';
+import type { RuntimeRef } from '@vibesdotdev/kernel';
 
-const config = await loggingConfig.loadWithDefaults(context);
-
-console.log(config.level);  // 'info'
+// Configure the handed Runtime without changing another host's settings.
+function configureNamespaces(runtime: RuntimeRef) {
+  const settings = parseNamespaceSettingsFromEnv(runtime.getEnvSnapshot());
+  updateNamespaceSettings(runtime, settings);
+}
 \`\`\`
 
-## Level Filtering
-
-### Filter by Level
-
-\`\`\`ts
-logger.setLevel('warn');
+\`\`\`bash
+# Baseline level for all loggers
+export LOG_LEVEL=debug          # or VIBES_LOG_LEVEL
 
-logger.trace('Will NOT be logged');  // filtered
-logger.debug('Will NOT be logged');  // filtered
-logger.info('Will NOT be logged');   // filtered
-logger.warn('Will be logged');       // ✓
-logger.error('Will be logged');      // ✓
+# Namespace selectors: comma-separated, '-' prefix excludes
+export VIBES_LOG='app:*,-app:auth'
 \`\`\`
 
-### Filter by Namespace
-
-\`\`\`ts
-import { createLogger } from '@vibesdotdev/logging';
-
-// Create logger with namespace
-const dbLogger = createLogger('app:db');
-const authLogger = createLogger('app:auth');
+An unrecognized level string falls back to \`info\`.
 
-dbLogger.setLevel('debug');
-authLogger.setLevel('error');
+## Namespace Filtering
 
-dbLogger.debug('Query executed');    // logged
-authLogger.debug('Token validated');  // filtered
-\`\`\`
-
-### Filter by Context
+Namespace selectors decide which namespaces are emitted independently of the
+baseline level. The selector string format is
+\`"namespace1,namespace2,-excluded1"\`, where \`*\` is a wildcard and a leading
+\`-\` marks an exclusion.
 
 \`\`\`ts
-logger.debug('Debug message', {
-  context: {
-    userId: '123',
-    requestId: 'req-456'
-  }
+import { parseNamespaceSettings, shouldLog } from '@vibesdotdev/logging';
+
+const settings = parseNamespaceSettings({
+  input: 'app:*,-app:auth',
+  defaultLevel: 'warn'
 });
 
-// Output includes context
-// [DEBUG] [app] Debug message {"userId":"123","requestId":"req-456"}
+shouldLog({ namespace: 'app:db', level: 'error', settings });   // true
+shouldLog({ namespace: 'app:auth', level: 'error', settings }); // false (excluded)
+shouldLog({ namespace: 'app:db', level: 'debug', settings });   // true (re-included below baseline)
 \`\`\`
 
-## Namespace Patterns
+The semantics: a level **at or above** the baseline is emitted unless the
+namespace is excluded; a level **below** the baseline is only emitted if the
+namespace is explicitly included by a selector.
 
-### Namespace Hierarchy
+## Child Loggers and Context
 
-\`\`\`ts
-// Namespace structure
-app:server
-app:database
-app:auth
-app:api:users
-app:api:posts
-
-// Set level for namespace pattern
-logger.setLevel('app:api:*', 'debug');  // All API logs
-\`\`\`
-
-### Wildcard Patterns
+A logger is immutable — derive scoped loggers instead of mutating level state.
 
 \`\`\`ts
-// Wildcard matching
-logger.setLevel('app:*', 'info');       // All app logs
-logger.setLevel('app:api:*', 'debug');  // All API logs
-logger.setLevel('*', 'warn');           // All logs
-\`\`\`
+import { getLogger } from '@vibesdotdev/logging';
 
-## Level-Specific Methods
+const log = getLogger('myapp', runtime);
 
-### Convenience Methods
+// Extend the namespace (e.g. 'myapp:database')
+const dbLog = log.child('database');
+dbLog.debug('Connected');
 
-\`\`\`ts
-logger.trace('Trace message');
-logger.debug('Debug message');
-logger.info('Info message');
-logger.warn('Warning message');
-logger.error('Error message');
+// Bind static context onto every subsequent entry
+const reqLog = log.withRequestContext({ requestId: 'req-456', userId: '123' });
+reqLog.info('Handling request');
 \`\`\`
 
-### Structured Logging
+\`child(options)\` accepts a string namespace segment or an object
+(\`{ namespace?, context? }\` plus arbitrary context fields). \`withContext\`,
+\`withRequestContext\`, and \`withJobContext\` return a new logger with merged
+metadata.
 
-\`\`\`ts
-logger.info('User logged in', {
-  userId: '123',
-  email: 'user@example.com',
-  timestamp: new Date().toISOString()
-});
-
-logger.error('Payment failed', {
-  userId: '123',
-  amount: 99.99,
-  error: 'Insufficient funds',
-  code: 'PAYMENT_FAILED'
-});
-\`\`\`
+## Performance Tracking
 
-## Conditional Logging
-
-### Level Guards
+\`performanceTracker\` emits a \`debug\` start entry and an \`info\` success (or
+\`error\` failure) entry with a measured \`duration\`:
 
 \`\`\`ts
-if (logger.isLevelEnabled('debug')) {
-  // Expensive operation only if debug logging enabled
-  const debugData = computeExpensiveDebugData();
-  logger.debug('Debug info', debugData);
+const tracker = logger.performanceTracker({ operation: 'processUser' });
+tracker.start();
+try {
+  // ... work ...
+  tracker.end({ recordCount: 42 });
+} catch (err) {
+  tracker.fail(err);
 }
 \`\`\`
 
-### Dynamic Level Changes
-
-\`\`\`ts
-// Temporarily increase verbosity
-const previousLevel = logger.getLevel();
-logger.setLevel('trace');
-
-// ... debug-heavy operation ...
-
-logger.setLevel(previousLevel);  // restore
-\`\`\`
-
-## Audit Logging
-
-Audit logs use special level handling:
-
-\`\`\`ts
-import { auditLogger } from '@vibesdotdev/logging';
-
-// Audit logs always logged regardless of level
-auditLogger.authentication({
-  userId: '123',
-  action: 'login',
-  success: true,
-  ipAddress: '192.168.1.1'
-});
-
-auditLogger.authorization({
-  userId: '123',
-  resource: 'users/456',
-  action: 'delete',
-  allowed: false
-});
-\`\`\`
-
 ## Best Practices
 
-1. **Use appropriate levels** — Don't log everything as error
-2. **Include context** — Help debugging with relevant data
-3. **Avoid sensitive data** — Never log passwords, tokens, PII
-4. **Consistent namespaces** — Use hierarchical naming
-5. **Production level** — Typically 'info' or 'warn'
-6. **Development level** — Typically 'debug'
+1. **Use appropriate levels** — don't log everything as \`error\`.
+2. **Include context** — pass a structured object, not string concatenation.
+3. **Avoid sensitive data** — never log passwords, tokens, or PII.
+4. **Consistent namespaces** — use hierarchical, colon-delimited names.
+5. **Production baseline** — typically \`info\` or \`warn\`.
+6. **Development baseline** — typically \`debug\`.
 
 :::card{title="See also"}
-- [\`logging.transports\`](logging.transports) — Transport layers
-- [\`logging.structured\`](logging.structured) — Structured logging
-- [\`config.environment\`](config.environment) — Environment configuration
+- [\`logging.transports\`](logging.transports) — Sinks, formatters, and outputs
+- [\`logging.structured\`](logging.structured) — Structured logging and context
 :::
 `
     },

package/dist/docs/levels.docs.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"levels.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/levels.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,gBAAgB;IACpB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,qDAAqD;IAC9D,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmUT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC;IAC1E,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"levels.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/levels.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,gBAAgB;IACpB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,qDAAqD;IAC9D,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6LT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC;IAC1E,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}