@dwk/log 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# `@dwk/log`
+
+Minimal, injectable structured-logging seam shared across the `@dwk` packages.
+
+A **cross-standard reusable lib** (like [`@dwk/dpop`](../dpop) and
+[`@dwk/rdf`](../rdf)): protocol-agnostic, stateless, and unit-testable without a
+Workers runtime. It defines _where_ the `@dwk` packages send signal, not _how_
+that signal is stored — the composed Worker wires a concrete logger to Workers
+structured logs / Logpush / Analytics Engine.
+
+See [`spec/observability.md`](../../spec/observability.md) for the cross-cutting
+requirement and the event-taxonomy conventions.
+
+## Why
+
+The `@dwk` packages handle untrusted, attacker-supplied input. Without a logging
+seam, security-relevant events — a blocked SSRF attempt, an auth rejection, a
+poison queue message — are silently swallowed and indistinguishable from a dead
+link or a timeout. This package is the seam those events flow through.
+
+## The seam
+
+```ts
+import type { Logger } from "@dwk/log";
+
+export interface Logger {
+  debug(event: string, fields?: Record<string, unknown>): void;
+  info(event: string, fields?: Record<string, unknown>): void;
+  warn(event: string, fields?: Record<string, unknown>): void;
+  error(event: string, fields?: Record<string, unknown>): void;
+}
+```
+
+Each call names a **stable, dotted event** (e.g. `webmention.ssrf.blocked`) plus
+a flat bag of structured fields, so operators query by event and field instead
+of grepping prose. Event-name taxonomies are owned by each consuming package.
+
+## Usage
+
+A package accepts an **optional** `logger` in its config and defaults to
+`noopLogger`, so logging is strictly opt-in:
+
+```ts
+import { noopLogger, type Logger } from "@dwk/log";
+
+function createThing(config: { logger?: Logger }) {
+  const logger = config.logger ?? noopLogger;
+  logger.warn("thing.blocked", { reason: "policy" });
+}
+```
+
+The composed Worker wires a real logger once:
+
+```ts
+import { consoleLogger } from "@dwk/log";
+
+const logger = consoleLogger({ minLevel: "info", base: { service: "wm" } });
+const handler = createWebmention({ baseUrl, logger });
+```
+
+### Exports
+
+| Export                       | Purpose                                                         |
+| ---------------------------- | -------------------------------------------------------------- |
+| `Logger`, `LogLevel`, `LogFields` | The logging seam types.                                  |
+| `noopLogger`                 | Discards everything; the default when no logger is configured. |
+| `consoleLogger(options?)`    | Emits one JSON record per call to `console` (Workers logs).    |
+| `withContext(logger, ctx)`   | Binds request/pod-scoped fields onto every record.             |
+| `hostFromUrl(raw)`           | Redaction helper: a URL's host only, never its path/query.     |
+| `Metrics`                    | The metrics seam type (`count` / `observe`).                   |
+| `noopMetrics`                | Discards everything; the default when no metrics sink is set.  |
+| `analyticsEngineMetrics(dataset, options?)` | Adapter to Cloudflare Workers Analytics Engine. |
+
+## Metrics
+
+The companion **metrics** seam answers "how often / how much?" for the same
+events the logger names, so an operator can chart "SSRF blocks/min" or
+"verification success rate" instead of scraping log lines. It is injected the
+same way — an **optional** `metrics`, defaulting to `noopMetrics` — and reuses
+the same event names and field bags as logs, so logs and counters share one
+vocabulary:
+
+```ts
+import { noopMetrics, type Metrics } from "@dwk/log";
+
+function createThing(config: { metrics?: Metrics }) {
+  const metrics = config.metrics ?? noopMetrics;
+  metrics.count("thing.blocked", { reason: "policy" }); // a counter
+  metrics.observe("thing.latency", 42, { host: "a.example" }); // an observation
+}
+```
+
+The composed Worker wires the real adapter once, from a bound
+`AnalyticsEngineDataset`:
+
+```ts
+import { analyticsEngineMetrics } from "@dwk/log";
+
+// env.WM_METRICS is an AnalyticsEngineDataset binding declared in wrangler.toml.
+const metrics = analyticsEngineMetrics(env.WM_METRICS, {
+  base: { service: "wm" },
+});
+const handler = createWebmention({ baseUrl, logger, metrics });
+```
+
+`analyticsEngineMetrics` maps each call onto `writeDataPoint` deterministically:
+the `event` becomes `indexes[0]` (the sampling key) and `blobs[0]`; string fields
+become further `blobs`, and numeric/boolean fields become `doubles` (with a lead
+`1` for `count` or the observed value for `observe`) — all in sorted key order so
+positions are stable per event. Cloudflare's Analytics Engine limits (1 index ≤
+96 B, ≤ 20 blobs ≤ 16 KB total, ≤ 20 doubles) are enforced, and like `Logger` a
+`Metrics` implementation **never throws** into the operation it measures. The
+binding type is declared structurally (`AnalyticsEngineDatasetLike`), so this
+package keeps no `@cloudflare/workers-types` dependency. The same redaction rules
+apply — never pass tokens, bodies, or full URLs as fields.
+
+## Redaction
+
+Redaction is the caller's responsibility, but the seam helps. **Never** pass
+tokens, credentials, or full request/response bodies as fields. For URLs, prefer
+`hostFromUrl(raw)` so an attacker-supplied path or query string never lands in a
+log line.

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `@dwk/log` — a minimal, injectable structured-logging seam.
+ *
+ * The `@dwk` packages handle untrusted, attacker-supplied input, so failures and
+ * security-relevant events (a blocked SSRF attempt, an auth rejection) must
+ * produce a signal rather than being silently swallowed. This library defines
+ * the seam that signal flows through. It deliberately does **no I/O of its own
+ * by default**: a package takes an optional {@link Logger} in its config and
+ * calls it; the composed Worker decides where the records actually go (Workers
+ * structured logs, Logpush, Analytics Engine, …) by wiring in a concrete logger.
+ *
+ * It is a **cross-standard reusable**: like `@dwk/dpop` and `@dwk/rdf`, it MUST
+ * stay free of IndieWeb/Solid assumptions so future `@dwk` standards adopt it
+ * unchanged. It holds no state, performs no protocol logic, and unit-tests
+ * without a Workers runtime.
+ *
+ * Logs are **structured events**, not free text: every call names a stable,
+ * dotted `event` (e.g. `webmention.ssrf.blocked`) plus a flat bag of fields, so
+ * an operator can query by event and field rather than grep prose. Event-name
+ * taxonomies are owned by each consuming package, not by this library.
+ *
+ * **Redaction is the caller's responsibility, but the seam helps:** never pass
+ * tokens, credentials, or full request/response bodies as fields. For URLs,
+ * prefer {@link hostFromUrl} so an attacker-supplied path/query never lands in a
+ * log line.
+ *
+ * Logs answer "what happened?"; the companion {@link Metrics} seam (same file
+ * family, same injection discipline) answers "how often / how much?" for the
+ * same events. See {@link ./metrics}.
+ *
+ * @see spec/observability.md
+ * @see spec/packages/log.md
+ * @packageDocumentation
+ */
+export { type Metrics, noopMetrics, analyticsEngineMetrics, type AnalyticsEngineDatasetLike, type AnalyticsEngineDataPoint, type AnalyticsEngineMetricsOptions, } from "./metrics";
+/** Severity of a log record, in increasing order of importance. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A flat bag of structured fields attached to a log record. Keys SHOULD be
+ * stable and queryable; values MUST be safe to record (no secrets, no bodies).
+ */
+export type LogFields = Record<string, unknown>;
+/**
+ * The logging seam every `@dwk` package writes to.
+ *
+ * Each method takes a stable, dotted `event` name and an optional bag of
+ * structured `fields`. Implementations MUST NOT throw — a logging failure must
+ * never break the operation being logged.
+ */
+export interface Logger {
+    /** Verbose, developer-facing detail; off in production by default. */
+    debug(event: string, fields?: LogFields): void;
+    /** A normal, noteworthy outcome (e.g. a verification completed). */
+    info(event: string, fields?: LogFields): void;
+    /** A handled-but-notable event (e.g. a blocked SSRF attempt, a retry). */
+    warn(event: string, fields?: LogFields): void;
+    /** A failure that needs attention. */
+    error(event: string, fields?: LogFields): void;
+}
+/**
+ * A logger that discards everything. This is the default a package uses when
+ * its config supplies none, so logging is strictly opt-in and pure libs stay
+ * silent and side-effect-free in tests.
+ */
+export declare const noopLogger: Logger;
+/**
+ * The slice of the global `console` (or any compatible sink) that
+ * {@link consoleLogger} writes to. Declared structurally so a test can pass a
+ * spy and the composed Worker can pass `console`.
+ */
+export interface ConsoleLike {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** Tunables for {@link consoleLogger}. */
+export interface ConsoleLoggerOptions {
+    /** Sink to write to; defaults to the global `console`. */
+    readonly console?: ConsoleLike;
+    /** Drop records below this level (default `"debug"`, i.e. emit everything). */
+    readonly minLevel?: LogLevel;
+    /** Fields merged into every record (e.g. a deployment or request id). */
+    readonly base?: LogFields;
+    /** Timestamp source, for deterministic tests (default `Date.now` as ISO). */
+    readonly now?: () => string;
+}
+/**
+ * A {@link Logger} that emits one JSON object per record to `console`, suitable
+ * for Cloudflare Workers structured logs / Logpush.
+ *
+ * Each record is `{ level, event, time, ...base, ...fields }`, serialized with
+ * `JSON.stringify` (which drops `undefined`-valued fields, so optional context
+ * can be passed unconditionally). Records below `minLevel` are dropped. The
+ * matching `console` method is used per level so a platform's level routing
+ * still applies.
+ *
+ * Honors the {@link Logger} non-throwing contract: if a field is not
+ * JSON-serializable (a circular reference, a `BigInt`, …) the record is replaced
+ * by a minimal `log.serialization_failed` record rather than throwing into the
+ * operation being logged.
+ */
+export declare function consoleLogger(options?: ConsoleLoggerOptions): Logger;
+/**
+ * Wrap `logger` so that `context` is merged into the fields of every record.
+ *
+ * Use this to bind request- or pod-scoped context (a request id, a pod id) once
+ * at the composition boundary instead of repeating it at every call site. The
+ * per-call `fields` win on key collisions.
+ */
+export declare function withContext(logger: Logger, context: LogFields): Logger;
+/**
+ * Extract just the host from a URL string, for safe logging.
+ *
+ * Returns the `host` (name plus any non-default port) and nothing else — no
+ * scheme, path, query, or userinfo — so an attacker-supplied `source`/`target`
+ * URL never lands in a log line in full. Returns `undefined` when `raw` is not a
+ * parseable URL.
+ */
+export declare function hostFromUrl(raw: string): string | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,KAAK,OAAO,EACZ,WAAW,EACX,sBAAsB,EACtB,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,GACnC,MAAM,WAAW,CAAC;AAEnB,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,sEAAsE;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/C,oEAAoE;IACpE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9C,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9C,sCAAsC;IACtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,MAKxB,CAAC;AAUF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjC;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CA4CxE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,MAAM,CAQtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM3D"}

package/dist/index.js

@@ -0,0 +1,141 @@
+/**
+ * `@dwk/log` — a minimal, injectable structured-logging seam.
+ *
+ * The `@dwk` packages handle untrusted, attacker-supplied input, so failures and
+ * security-relevant events (a blocked SSRF attempt, an auth rejection) must
+ * produce a signal rather than being silently swallowed. This library defines
+ * the seam that signal flows through. It deliberately does **no I/O of its own
+ * by default**: a package takes an optional {@link Logger} in its config and
+ * calls it; the composed Worker decides where the records actually go (Workers
+ * structured logs, Logpush, Analytics Engine, …) by wiring in a concrete logger.
+ *
+ * It is a **cross-standard reusable**: like `@dwk/dpop` and `@dwk/rdf`, it MUST
+ * stay free of IndieWeb/Solid assumptions so future `@dwk` standards adopt it
+ * unchanged. It holds no state, performs no protocol logic, and unit-tests
+ * without a Workers runtime.
+ *
+ * Logs are **structured events**, not free text: every call names a stable,
+ * dotted `event` (e.g. `webmention.ssrf.blocked`) plus a flat bag of fields, so
+ * an operator can query by event and field rather than grep prose. Event-name
+ * taxonomies are owned by each consuming package, not by this library.
+ *
+ * **Redaction is the caller's responsibility, but the seam helps:** never pass
+ * tokens, credentials, or full request/response bodies as fields. For URLs,
+ * prefer {@link hostFromUrl} so an attacker-supplied path/query never lands in a
+ * log line.
+ *
+ * Logs answer "what happened?"; the companion {@link Metrics} seam (same file
+ * family, same injection discipline) answers "how often / how much?" for the
+ * same events. See {@link ./metrics}.
+ *
+ * @see spec/observability.md
+ * @see spec/packages/log.md
+ * @packageDocumentation
+ */
+export { noopMetrics, analyticsEngineMetrics, } from "./metrics";
+/**
+ * A logger that discards everything. This is the default a package uses when
+ * its config supplies none, so logging is strictly opt-in and pure libs stay
+ * silent and side-effect-free in tests.
+ */
+export const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/** Numeric ordering of {@link LogLevel} used for threshold filtering. */
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+/**
+ * A {@link Logger} that emits one JSON object per record to `console`, suitable
+ * for Cloudflare Workers structured logs / Logpush.
+ *
+ * Each record is `{ level, event, time, ...base, ...fields }`, serialized with
+ * `JSON.stringify` (which drops `undefined`-valued fields, so optional context
+ * can be passed unconditionally). Records below `minLevel` are dropped. The
+ * matching `console` method is used per level so a platform's level routing
+ * still applies.
+ *
+ * Honors the {@link Logger} non-throwing contract: if a field is not
+ * JSON-serializable (a circular reference, a `BigInt`, …) the record is replaced
+ * by a minimal `log.serialization_failed` record rather than throwing into the
+ * operation being logged.
+ */
+export function consoleLogger(options = {}) {
+    const sink = options.console ?? console;
+    const threshold = LEVEL_ORDER[options.minLevel ?? "debug"];
+    const now = options.now ?? (() => new Date().toISOString());
+    const base = options.base;
+    const emit = (level) => (event, fields) => {
+        if (LEVEL_ORDER[level] < threshold) {
+            return;
+        }
+        const record = {
+            level,
+            event,
+            time: now(),
+            ...base,
+            ...fields,
+        };
+        try {
+            sink[level](JSON.stringify(record));
+        }
+        catch (err) {
+            // Honor the Logger "MUST NOT throw" contract: a non-serializable field
+            // (circular reference, BigInt, …) must never break the operation being
+            // logged. Fall back to a minimal, guaranteed-serializable record. The
+            // serializer's own error message is safe to log — it is not caller data.
+            sink.error(JSON.stringify({
+                level: "error",
+                event: "log.serialization_failed",
+                time: record.time,
+                failedEvent: event,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        }
+    };
+    return {
+        debug: emit("debug"),
+        info: emit("info"),
+        warn: emit("warn"),
+        error: emit("error"),
+    };
+}
+/**
+ * Wrap `logger` so that `context` is merged into the fields of every record.
+ *
+ * Use this to bind request- or pod-scoped context (a request id, a pod id) once
+ * at the composition boundary instead of repeating it at every call site. The
+ * per-call `fields` win on key collisions.
+ */
+export function withContext(logger, context) {
+    const merge = (fields) => ({ ...context, ...fields });
+    return {
+        debug: (event, fields) => logger.debug(event, merge(fields)),
+        info: (event, fields) => logger.info(event, merge(fields)),
+        warn: (event, fields) => logger.warn(event, merge(fields)),
+        error: (event, fields) => logger.error(event, merge(fields)),
+    };
+}
+/**
+ * Extract just the host from a URL string, for safe logging.
+ *
+ * Returns the `host` (name plus any non-default port) and nothing else — no
+ * scheme, path, query, or userinfo — so an attacker-supplied `source`/`target`
+ * URL never lands in a log line in full. Returns `undefined` when `raw` is not a
+ * parseable URL.
+ */
+export function hostFromUrl(raw) {
+    try {
+        return new URL(raw).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `@dwk/log` — a minimal, injectable **metrics** seam, companion to {@link Logger}.
+ *
+ * Where the {@link Logger} answers "what happened?" with one structured record
+ * per event, this seam answers "how often / how much?" — emitting queryable
+ * counters and observations so an operator can chart "SSRF blocks/min",
+ * "verification success rate", or "queue retries by reason" rather than scraping
+ * log lines. It mirrors the logging seam exactly: a package takes an **optional**
+ * {@link Metrics} in its config, defaulting to {@link noopMetrics}, and the
+ * composed Worker wires a concrete adapter **once** at the composition boundary.
+ * It does **no I/O of its own by default**.
+ *
+ * Like the rest of `@dwk/log` it is a **cross-standard reusable**: protocol-
+ * agnostic, holding no IndieWeb/Solid assumptions, with no Workers-runtime
+ * dependency. The {@link analyticsEngineMetrics} adapter targets Cloudflare
+ * Workers Analytics Engine through a **structural** binding type
+ * ({@link AnalyticsEngineDatasetLike}) — the same trick {@link ConsoleLike} uses
+ * for `console` — so this library never imports `@cloudflare/workers-types` and
+ * still unit-tests under plain Node.
+ *
+ * Metrics reuse the same **event taxonomy** and the same {@link LogFields} bags
+ * as logs, so logs and metrics share one vocabulary: pass the same
+ * `(event, fields)` to both seams. The **redaction policy is identical** — only
+ * hosts, ports, status, machine-readable reason/result codes, booleans, and
+ * counts; never tokens, bodies, or full URLs (use {@link hostFromUrl}).
+ *
+ * @see spec/observability.md
+ * @packageDocumentation
+ */
+import type { LogFields } from "./index";
+/**
+ * The metrics seam every `@dwk` package writes to, alongside {@link Logger}.
+ *
+ * Both methods name the same stable, dotted `event` as the logger and an
+ * optional bag of structured {@link LogFields} — the adapter turns string fields
+ * into queryable dimensions and numeric/boolean fields into measurements.
+ * Implementations MUST NOT throw — a metrics failure must never break the
+ * operation being measured.
+ */
+export interface Metrics {
+    /**
+     * Record one occurrence of `event` (a counter increment of 1). Use for
+     * tallies like "SSRF blocks", "mentions received", "retries".
+     */
+    count(event: string, fields?: LogFields): void;
+    /**
+     * Record a numeric observation of `value` for `event` (a gauge/histogram
+     * sample). Use for measurements like a fetch latency in milliseconds.
+     */
+    observe(event: string, value: number, fields?: LogFields): void;
+}
+/**
+ * A metrics sink that discards everything. This is the default a package uses
+ * when its config supplies none, so metrics are strictly opt-in and pure libs
+ * stay side-effect-free in tests.
+ */
+export declare const noopMetrics: Metrics;
+/**
+ * One Analytics Engine data point. A structural mirror of Cloudflare's
+ * `AnalyticsEngineDataPoint` so this library needs no `@cloudflare/workers-types`
+ * dependency; the real binding is assignable to it.
+ */
+export interface AnalyticsEngineDataPoint {
+    /** Up to one sampling key, each ≤ 96 bytes. */
+    indexes?: (ArrayBuffer | string | null)[];
+    /** Up to 20 string/blob dimensions; total size ≤ 16 KB. */
+    blobs?: (ArrayBuffer | string | null)[];
+    /** Up to 20 numeric measurements. */
+    doubles?: number[];
+}
+/**
+ * The slice of a Cloudflare `AnalyticsEngineDataset` binding that
+ * {@link analyticsEngineMetrics} writes to. Declared structurally (like
+ * {@link ConsoleLike}) so a test can pass a spy and the composed Worker can pass
+ * the real `env.<DATASET>` binding.
+ */
+export interface AnalyticsEngineDatasetLike {
+    writeDataPoint(point?: AnalyticsEngineDataPoint): void;
+}
+/** Tunables for {@link analyticsEngineMetrics}. */
+export interface AnalyticsEngineMetricsOptions {
+    /**
+     * Fields merged into every data point (e.g. a deployment id or service name),
+     * mapped to blobs/doubles like any other field. Per-call fields win on a key
+     * collision.
+     */
+    readonly base?: LogFields;
+}
+/**
+ * A {@link Metrics} adapter that writes each call to a Cloudflare Workers
+ * Analytics Engine dataset via `writeDataPoint`.
+ *
+ * **Field mapping (deterministic, so positions are stable per event):**
+ * - `indexes[0]` = the `event` name (the sampling key; truncated to 96 bytes).
+ * - `blobs` = `[event, …string-valued fields]`, fields in **sorted key order**.
+ * - `doubles` = `[lead, …number/boolean fields]` in sorted key order, where
+ *   `lead` is `1` for {@link Metrics.count} or the observed value for
+ *   {@link Metrics.observe}, and booleans map to `1`/`0`.
+ *
+ * Non-scalar fields (objects, arrays) and `undefined`/`null`/non-finite numbers
+ * are dropped — metric fields must be scalar and safe to record. Because field
+ * positions follow sorted key order, an event SHOULD carry a stable field shape
+ * so `blobN` / `doubleN` mean the same thing across data points.
+ *
+ * Honors the {@link Metrics} non-throwing contract: a failing `writeDataPoint`
+ * is swallowed rather than thrown into the operation being measured.
+ */
+export declare function analyticsEngineMetrics(dataset: AnalyticsEngineDatasetLike, options?: AnalyticsEngineMetricsOptions): Metrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjE;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,CAAC,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAC1C,2DAA2D;IAC3D,KAAK,CAAC,EAAE,CAAC,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IACxC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,cAAc,CAAC,KAAK,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACxD;AAED,mDAAmD;AACnD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAgED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,0BAA0B,EACnC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAoCT"}

package/dist/metrics.js

@@ -0,0 +1,152 @@
+/**
+ * `@dwk/log` — a minimal, injectable **metrics** seam, companion to {@link Logger}.
+ *
+ * Where the {@link Logger} answers "what happened?" with one structured record
+ * per event, this seam answers "how often / how much?" — emitting queryable
+ * counters and observations so an operator can chart "SSRF blocks/min",
+ * "verification success rate", or "queue retries by reason" rather than scraping
+ * log lines. It mirrors the logging seam exactly: a package takes an **optional**
+ * {@link Metrics} in its config, defaulting to {@link noopMetrics}, and the
+ * composed Worker wires a concrete adapter **once** at the composition boundary.
+ * It does **no I/O of its own by default**.
+ *
+ * Like the rest of `@dwk/log` it is a **cross-standard reusable**: protocol-
+ * agnostic, holding no IndieWeb/Solid assumptions, with no Workers-runtime
+ * dependency. The {@link analyticsEngineMetrics} adapter targets Cloudflare
+ * Workers Analytics Engine through a **structural** binding type
+ * ({@link AnalyticsEngineDatasetLike}) — the same trick {@link ConsoleLike} uses
+ * for `console` — so this library never imports `@cloudflare/workers-types` and
+ * still unit-tests under plain Node.
+ *
+ * Metrics reuse the same **event taxonomy** and the same {@link LogFields} bags
+ * as logs, so logs and metrics share one vocabulary: pass the same
+ * `(event, fields)` to both seams. The **redaction policy is identical** — only
+ * hosts, ports, status, machine-readable reason/result codes, booleans, and
+ * counts; never tokens, bodies, or full URLs (use {@link hostFromUrl}).
+ *
+ * @see spec/observability.md
+ * @packageDocumentation
+ */
+/**
+ * A metrics sink that discards everything. This is the default a package uses
+ * when its config supplies none, so metrics are strictly opt-in and pure libs
+ * stay side-effect-free in tests.
+ */
+export const noopMetrics = {
+    count: () => { },
+    observe: () => { },
+};
+/** Analytics Engine limits (see the Workers Analytics Engine docs). */
+const MAX_INDEX_BYTES = 96;
+const MAX_BLOBS = 20;
+const MAX_DOUBLES = 20;
+const MAX_BLOB_BYTES_TOTAL = 16_384;
+const utf8 = new TextEncoder();
+function utf8ByteLength(value) {
+    return utf8.encode(value).length;
+}
+/** Truncate `value` to at most `maxBytes` UTF-8 bytes, on a char boundary. */
+function truncateUtf8(value, maxBytes) {
+    const bytes = utf8.encode(value);
+    if (bytes.length <= maxBytes) {
+        return value;
+    }
+    // Find the boundary by inspecting the bytes rather than decoding a partial
+    // slice: that way we never emit U+FFFD for a split char (and never mistake a
+    // genuine trailing U+FFFD in the input for one). First back off any
+    // continuation bytes (0b10xxxxxx) sitting at the cut...
+    let len = maxBytes;
+    while (len > 0 && ((bytes[len - 1] ?? 0) & 0xc0) === 0x80) {
+        len--;
+    }
+    // ...then, if we're left just after a lead byte whose multibyte sequence the
+    // cut would split, drop that lead byte too; otherwise the whole sequence fit,
+    // so keep up to maxBytes.
+    const lead = bytes[len - 1] ?? 0;
+    if (len > 0 && lead >= 0xc0) {
+        const seqLen = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : 2;
+        len = len - 1 + seqLen > maxBytes ? len - 1 : maxBytes;
+    }
+    // subarray is a zero-copy view (unlike slice), and the bytes are now a whole
+    // number of UTF-8 sequences, so the decode is exact.
+    return new TextDecoder().decode(bytes.subarray(0, len));
+}
+/** Cap a blob list to AE's count and total-byte limits, truncating the last. */
+function capBlobs(blobs) {
+    const out = [];
+    let total = 0;
+    for (const blob of blobs) {
+        if (out.length >= MAX_BLOBS) {
+            break;
+        }
+        const bytes = utf8ByteLength(blob);
+        if (total + bytes <= MAX_BLOB_BYTES_TOTAL) {
+            out.push(blob);
+            total += bytes;
+            continue;
+        }
+        const remaining = MAX_BLOB_BYTES_TOTAL - total;
+        if (remaining > 0) {
+            out.push(truncateUtf8(blob, remaining));
+        }
+        break;
+    }
+    return out;
+}
+/**
+ * A {@link Metrics} adapter that writes each call to a Cloudflare Workers
+ * Analytics Engine dataset via `writeDataPoint`.
+ *
+ * **Field mapping (deterministic, so positions are stable per event):**
+ * - `indexes[0]` = the `event` name (the sampling key; truncated to 96 bytes).
+ * - `blobs` = `[event, …string-valued fields]`, fields in **sorted key order**.
+ * - `doubles` = `[lead, …number/boolean fields]` in sorted key order, where
+ *   `lead` is `1` for {@link Metrics.count} or the observed value for
+ *   {@link Metrics.observe}, and booleans map to `1`/`0`.
+ *
+ * Non-scalar fields (objects, arrays) and `undefined`/`null`/non-finite numbers
+ * are dropped — metric fields must be scalar and safe to record. Because field
+ * positions follow sorted key order, an event SHOULD carry a stable field shape
+ * so `blobN` / `doubleN` mean the same thing across data points.
+ *
+ * Honors the {@link Metrics} non-throwing contract: a failing `writeDataPoint`
+ * is swallowed rather than thrown into the operation being measured.
+ */
+export function analyticsEngineMetrics(dataset, options = {}) {
+    const base = options.base;
+    const write = (event, lead, fields) => {
+        const merged = { ...base, ...fields };
+        const blobs = [event];
+        const doubles = [lead];
+        for (const key of Object.keys(merged).sort()) {
+            const value = merged[key];
+            if (typeof value === "string") {
+                blobs.push(value);
+            }
+            else if (typeof value === "boolean") {
+                doubles.push(value ? 1 : 0);
+            }
+            else if (typeof value === "number" && Number.isFinite(value)) {
+                doubles.push(value);
+            }
+            // Anything else (undefined, null, objects, NaN, …) is intentionally
+            // dropped: metric fields must be scalar and safe to record.
+        }
+        try {
+            dataset.writeDataPoint({
+                indexes: [truncateUtf8(event, MAX_INDEX_BYTES)],
+                blobs: capBlobs(blobs),
+                doubles: doubles.slice(0, MAX_DOUBLES),
+            });
+        }
+        catch {
+            // Metrics MUST NOT throw: a failed write must never break the operation
+            // being measured. There is no fallback sink, so swallow it.
+        }
+    };
+    return {
+        count: (event, fields) => write(event, 1, fields),
+        observe: (event, value, fields) => write(event, Number.isFinite(value) ? value : 0, fields),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA0BH;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC;CAClB,CAAC;AAoCF,uEAAuE;AACvE,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AACnC,CAAC;AAED,8EAA8E;AAC9E,SAAS,YAAY,CAAC,KAAa,EAAE,QAAgB;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,2EAA2E;IAC3E,6EAA6E;IAC7E,oEAAoE;IACpE,wDAAwD;IACxD,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1D,GAAG,EAAE,CAAC;IACR,CAAC;IACD,6EAA6E;IAC7E,8EAA8E;IAC9E,0BAA0B;IAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzD,CAAC;IACD,6EAA6E;IAC7E,qDAAqD;IACrD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,gFAAgF;AAChF,SAAS,QAAQ,CAAC,KAAe;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAC5B,MAAM;QACR,CAAC;QACD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,GAAG,KAAK,IAAI,oBAAoB,EAAE,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,KAAK,IAAI,KAAK,CAAC;YACf,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,oBAAoB,GAAG,KAAK,CAAC;QAC/C,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM;IACR,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAmC,EACnC,UAAyC,EAAE;IAE3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1B,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,IAAY,EAAE,MAAkB,EAAQ,EAAE;QACtE,MAAM,MAAM,GAAc,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;QACjD,MAAM,KAAK,GAAa,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,OAAO,GAAa,CAAC,IAAI,CAAC,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;iBAAM,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,CAAC;iBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,oEAAoE;YACpE,4DAA4D;QAC9D,CAAC;QACD,IAAI,CAAC;YACH,OAAO,CAAC,cAAc,CAAC;gBACrB,OAAO,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;gBAC/C,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC;gBACtB,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;YACxE,4DAA4D;QAC9D,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC;QACjD,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAChC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;KAC3D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dwk/log",
+  "version": "0.1.0-beta.0",
+  "description": "Minimal injectable structured-logging and metrics seam. Cross-standard reusable; protocol-agnostic, no Workers runtime dependency.",
+  "keywords": [
+    "logging",
+    "structured-logging",
+    "observability",
+    "metrics",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/log#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/log"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,208 @@
+/**
+ * `@dwk/log` — a minimal, injectable structured-logging seam.
+ *
+ * The `@dwk` packages handle untrusted, attacker-supplied input, so failures and
+ * security-relevant events (a blocked SSRF attempt, an auth rejection) must
+ * produce a signal rather than being silently swallowed. This library defines
+ * the seam that signal flows through. It deliberately does **no I/O of its own
+ * by default**: a package takes an optional {@link Logger} in its config and
+ * calls it; the composed Worker decides where the records actually go (Workers
+ * structured logs, Logpush, Analytics Engine, …) by wiring in a concrete logger.
+ *
+ * It is a **cross-standard reusable**: like `@dwk/dpop` and `@dwk/rdf`, it MUST
+ * stay free of IndieWeb/Solid assumptions so future `@dwk` standards adopt it
+ * unchanged. It holds no state, performs no protocol logic, and unit-tests
+ * without a Workers runtime.
+ *
+ * Logs are **structured events**, not free text: every call names a stable,
+ * dotted `event` (e.g. `webmention.ssrf.blocked`) plus a flat bag of fields, so
+ * an operator can query by event and field rather than grep prose. Event-name
+ * taxonomies are owned by each consuming package, not by this library.
+ *
+ * **Redaction is the caller's responsibility, but the seam helps:** never pass
+ * tokens, credentials, or full request/response bodies as fields. For URLs,
+ * prefer {@link hostFromUrl} so an attacker-supplied path/query never lands in a
+ * log line.
+ *
+ * Logs answer "what happened?"; the companion {@link Metrics} seam (same file
+ * family, same injection discipline) answers "how often / how much?" for the
+ * same events. See {@link ./metrics}.
+ *
+ * @see spec/observability.md
+ * @see spec/packages/log.md
+ * @packageDocumentation
+ */
+
+export {
+  type Metrics,
+  noopMetrics,
+  analyticsEngineMetrics,
+  type AnalyticsEngineDatasetLike,
+  type AnalyticsEngineDataPoint,
+  type AnalyticsEngineMetricsOptions,
+} from "./metrics";
+
+/** Severity of a log record, in increasing order of importance. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/**
+ * A flat bag of structured fields attached to a log record. Keys SHOULD be
+ * stable and queryable; values MUST be safe to record (no secrets, no bodies).
+ */
+export type LogFields = Record<string, unknown>;
+
+/**
+ * The logging seam every `@dwk` package writes to.
+ *
+ * Each method takes a stable, dotted `event` name and an optional bag of
+ * structured `fields`. Implementations MUST NOT throw — a logging failure must
+ * never break the operation being logged.
+ */
+export interface Logger {
+  /** Verbose, developer-facing detail; off in production by default. */
+  debug(event: string, fields?: LogFields): void;
+  /** A normal, noteworthy outcome (e.g. a verification completed). */
+  info(event: string, fields?: LogFields): void;
+  /** A handled-but-notable event (e.g. a blocked SSRF attempt, a retry). */
+  warn(event: string, fields?: LogFields): void;
+  /** A failure that needs attention. */
+  error(event: string, fields?: LogFields): void;
+}
+
+/**
+ * A logger that discards everything. This is the default a package uses when
+ * its config supplies none, so logging is strictly opt-in and pure libs stay
+ * silent and side-effect-free in tests.
+ */
+export const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+/** Numeric ordering of {@link LogLevel} used for threshold filtering. */
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+/**
+ * The slice of the global `console` (or any compatible sink) that
+ * {@link consoleLogger} writes to. Declared structurally so a test can pass a
+ * spy and the composed Worker can pass `console`.
+ */
+export interface ConsoleLike {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+
+/** Tunables for {@link consoleLogger}. */
+export interface ConsoleLoggerOptions {
+  /** Sink to write to; defaults to the global `console`. */
+  readonly console?: ConsoleLike;
+  /** Drop records below this level (default `"debug"`, i.e. emit everything). */
+  readonly minLevel?: LogLevel;
+  /** Fields merged into every record (e.g. a deployment or request id). */
+  readonly base?: LogFields;
+  /** Timestamp source, for deterministic tests (default `Date.now` as ISO). */
+  readonly now?: () => string;
+}
+
+/**
+ * A {@link Logger} that emits one JSON object per record to `console`, suitable
+ * for Cloudflare Workers structured logs / Logpush.
+ *
+ * Each record is `{ level, event, time, ...base, ...fields }`, serialized with
+ * `JSON.stringify` (which drops `undefined`-valued fields, so optional context
+ * can be passed unconditionally). Records below `minLevel` are dropped. The
+ * matching `console` method is used per level so a platform's level routing
+ * still applies.
+ *
+ * Honors the {@link Logger} non-throwing contract: if a field is not
+ * JSON-serializable (a circular reference, a `BigInt`, …) the record is replaced
+ * by a minimal `log.serialization_failed` record rather than throwing into the
+ * operation being logged.
+ */
+export function consoleLogger(options: ConsoleLoggerOptions = {}): Logger {
+  const sink = options.console ?? console;
+  const threshold = LEVEL_ORDER[options.minLevel ?? "debug"];
+  const now = options.now ?? (() => new Date().toISOString());
+  const base = options.base;
+
+  const emit =
+    (level: LogLevel) =>
+    (event: string, fields?: LogFields): void => {
+      if (LEVEL_ORDER[level] < threshold) {
+        return;
+      }
+      const record: LogFields = {
+        level,
+        event,
+        time: now(),
+        ...base,
+        ...fields,
+      };
+      try {
+        sink[level](JSON.stringify(record));
+      } catch (err) {
+        // Honor the Logger "MUST NOT throw" contract: a non-serializable field
+        // (circular reference, BigInt, …) must never break the operation being
+        // logged. Fall back to a minimal, guaranteed-serializable record. The
+        // serializer's own error message is safe to log — it is not caller data.
+        sink.error(
+          JSON.stringify({
+            level: "error",
+            event: "log.serialization_failed",
+            time: record.time,
+            failedEvent: event,
+            error: err instanceof Error ? err.message : String(err),
+          }),
+        );
+      }
+    };
+
+  return {
+    debug: emit("debug"),
+    info: emit("info"),
+    warn: emit("warn"),
+    error: emit("error"),
+  };
+}
+
+/**
+ * Wrap `logger` so that `context` is merged into the fields of every record.
+ *
+ * Use this to bind request- or pod-scoped context (a request id, a pod id) once
+ * at the composition boundary instead of repeating it at every call site. The
+ * per-call `fields` win on key collisions.
+ */
+export function withContext(logger: Logger, context: LogFields): Logger {
+  const merge = (fields?: LogFields): LogFields => ({ ...context, ...fields });
+  return {
+    debug: (event, fields) => logger.debug(event, merge(fields)),
+    info: (event, fields) => logger.info(event, merge(fields)),
+    warn: (event, fields) => logger.warn(event, merge(fields)),
+    error: (event, fields) => logger.error(event, merge(fields)),
+  };
+}
+
+/**
+ * Extract just the host from a URL string, for safe logging.
+ *
+ * Returns the `host` (name plus any non-default port) and nothing else — no
+ * scheme, path, query, or userinfo — so an attacker-supplied `source`/`target`
+ * URL never lands in a log line in full. Returns `undefined` when `raw` is not a
+ * parseable URL.
+ */
+export function hostFromUrl(raw: string): string | undefined {
+  try {
+    return new URL(raw).host;
+  } catch {
+    return undefined;
+  }
+}

package/src/metrics.ts

@@ -0,0 +1,219 @@
+/**
+ * `@dwk/log` — a minimal, injectable **metrics** seam, companion to {@link Logger}.
+ *
+ * Where the {@link Logger} answers "what happened?" with one structured record
+ * per event, this seam answers "how often / how much?" — emitting queryable
+ * counters and observations so an operator can chart "SSRF blocks/min",
+ * "verification success rate", or "queue retries by reason" rather than scraping
+ * log lines. It mirrors the logging seam exactly: a package takes an **optional**
+ * {@link Metrics} in its config, defaulting to {@link noopMetrics}, and the
+ * composed Worker wires a concrete adapter **once** at the composition boundary.
+ * It does **no I/O of its own by default**.
+ *
+ * Like the rest of `@dwk/log` it is a **cross-standard reusable**: protocol-
+ * agnostic, holding no IndieWeb/Solid assumptions, with no Workers-runtime
+ * dependency. The {@link analyticsEngineMetrics} adapter targets Cloudflare
+ * Workers Analytics Engine through a **structural** binding type
+ * ({@link AnalyticsEngineDatasetLike}) — the same trick {@link ConsoleLike} uses
+ * for `console` — so this library never imports `@cloudflare/workers-types` and
+ * still unit-tests under plain Node.
+ *
+ * Metrics reuse the same **event taxonomy** and the same {@link LogFields} bags
+ * as logs, so logs and metrics share one vocabulary: pass the same
+ * `(event, fields)` to both seams. The **redaction policy is identical** — only
+ * hosts, ports, status, machine-readable reason/result codes, booleans, and
+ * counts; never tokens, bodies, or full URLs (use {@link hostFromUrl}).
+ *
+ * @see spec/observability.md
+ * @packageDocumentation
+ */
+
+import type { LogFields } from "./index";
+
+/**
+ * The metrics seam every `@dwk` package writes to, alongside {@link Logger}.
+ *
+ * Both methods name the same stable, dotted `event` as the logger and an
+ * optional bag of structured {@link LogFields} — the adapter turns string fields
+ * into queryable dimensions and numeric/boolean fields into measurements.
+ * Implementations MUST NOT throw — a metrics failure must never break the
+ * operation being measured.
+ */
+export interface Metrics {
+  /**
+   * Record one occurrence of `event` (a counter increment of 1). Use for
+   * tallies like "SSRF blocks", "mentions received", "retries".
+   */
+  count(event: string, fields?: LogFields): void;
+  /**
+   * Record a numeric observation of `value` for `event` (a gauge/histogram
+   * sample). Use for measurements like a fetch latency in milliseconds.
+   */
+  observe(event: string, value: number, fields?: LogFields): void;
+}
+
+/**
+ * A metrics sink that discards everything. This is the default a package uses
+ * when its config supplies none, so metrics are strictly opt-in and pure libs
+ * stay side-effect-free in tests.
+ */
+export const noopMetrics: Metrics = {
+  count: () => {},
+  observe: () => {},
+};
+
+/**
+ * One Analytics Engine data point. A structural mirror of Cloudflare's
+ * `AnalyticsEngineDataPoint` so this library needs no `@cloudflare/workers-types`
+ * dependency; the real binding is assignable to it.
+ */
+export interface AnalyticsEngineDataPoint {
+  /** Up to one sampling key, each ≤ 96 bytes. */
+  indexes?: (ArrayBuffer | string | null)[];
+  /** Up to 20 string/blob dimensions; total size ≤ 16 KB. */
+  blobs?: (ArrayBuffer | string | null)[];
+  /** Up to 20 numeric measurements. */
+  doubles?: number[];
+}
+
+/**
+ * The slice of a Cloudflare `AnalyticsEngineDataset` binding that
+ * {@link analyticsEngineMetrics} writes to. Declared structurally (like
+ * {@link ConsoleLike}) so a test can pass a spy and the composed Worker can pass
+ * the real `env.<DATASET>` binding.
+ */
+export interface AnalyticsEngineDatasetLike {
+  writeDataPoint(point?: AnalyticsEngineDataPoint): void;
+}
+
+/** Tunables for {@link analyticsEngineMetrics}. */
+export interface AnalyticsEngineMetricsOptions {
+  /**
+   * Fields merged into every data point (e.g. a deployment id or service name),
+   * mapped to blobs/doubles like any other field. Per-call fields win on a key
+   * collision.
+   */
+  readonly base?: LogFields;
+}
+
+/** Analytics Engine limits (see the Workers Analytics Engine docs). */
+const MAX_INDEX_BYTES = 96;
+const MAX_BLOBS = 20;
+const MAX_DOUBLES = 20;
+const MAX_BLOB_BYTES_TOTAL = 16_384;
+
+const utf8 = new TextEncoder();
+
+function utf8ByteLength(value: string): number {
+  return utf8.encode(value).length;
+}
+
+/** Truncate `value` to at most `maxBytes` UTF-8 bytes, on a char boundary. */
+function truncateUtf8(value: string, maxBytes: number): string {
+  const bytes = utf8.encode(value);
+  if (bytes.length <= maxBytes) {
+    return value;
+  }
+  // Find the boundary by inspecting the bytes rather than decoding a partial
+  // slice: that way we never emit U+FFFD for a split char (and never mistake a
+  // genuine trailing U+FFFD in the input for one). First back off any
+  // continuation bytes (0b10xxxxxx) sitting at the cut...
+  let len = maxBytes;
+  while (len > 0 && ((bytes[len - 1] ?? 0) & 0xc0) === 0x80) {
+    len--;
+  }
+  // ...then, if we're left just after a lead byte whose multibyte sequence the
+  // cut would split, drop that lead byte too; otherwise the whole sequence fit,
+  // so keep up to maxBytes.
+  const lead = bytes[len - 1] ?? 0;
+  if (len > 0 && lead >= 0xc0) {
+    const seqLen = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : 2;
+    len = len - 1 + seqLen > maxBytes ? len - 1 : maxBytes;
+  }
+  // subarray is a zero-copy view (unlike slice), and the bytes are now a whole
+  // number of UTF-8 sequences, so the decode is exact.
+  return new TextDecoder().decode(bytes.subarray(0, len));
+}
+
+/** Cap a blob list to AE's count and total-byte limits, truncating the last. */
+function capBlobs(blobs: string[]): string[] {
+  const out: string[] = [];
+  let total = 0;
+  for (const blob of blobs) {
+    if (out.length >= MAX_BLOBS) {
+      break;
+    }
+    const bytes = utf8ByteLength(blob);
+    if (total + bytes <= MAX_BLOB_BYTES_TOTAL) {
+      out.push(blob);
+      total += bytes;
+      continue;
+    }
+    const remaining = MAX_BLOB_BYTES_TOTAL - total;
+    if (remaining > 0) {
+      out.push(truncateUtf8(blob, remaining));
+    }
+    break;
+  }
+  return out;
+}
+
+/**
+ * A {@link Metrics} adapter that writes each call to a Cloudflare Workers
+ * Analytics Engine dataset via `writeDataPoint`.
+ *
+ * **Field mapping (deterministic, so positions are stable per event):**
+ * - `indexes[0]` = the `event` name (the sampling key; truncated to 96 bytes).
+ * - `blobs` = `[event, …string-valued fields]`, fields in **sorted key order**.
+ * - `doubles` = `[lead, …number/boolean fields]` in sorted key order, where
+ *   `lead` is `1` for {@link Metrics.count} or the observed value for
+ *   {@link Metrics.observe}, and booleans map to `1`/`0`.
+ *
+ * Non-scalar fields (objects, arrays) and `undefined`/`null`/non-finite numbers
+ * are dropped — metric fields must be scalar and safe to record. Because field
+ * positions follow sorted key order, an event SHOULD carry a stable field shape
+ * so `blobN` / `doubleN` mean the same thing across data points.
+ *
+ * Honors the {@link Metrics} non-throwing contract: a failing `writeDataPoint`
+ * is swallowed rather than thrown into the operation being measured.
+ */
+export function analyticsEngineMetrics(
+  dataset: AnalyticsEngineDatasetLike,
+  options: AnalyticsEngineMetricsOptions = {},
+): Metrics {
+  const base = options.base;
+
+  const write = (event: string, lead: number, fields?: LogFields): void => {
+    const merged: LogFields = { ...base, ...fields };
+    const blobs: string[] = [event];
+    const doubles: number[] = [lead];
+    for (const key of Object.keys(merged).sort()) {
+      const value = merged[key];
+      if (typeof value === "string") {
+        blobs.push(value);
+      } else if (typeof value === "boolean") {
+        doubles.push(value ? 1 : 0);
+      } else if (typeof value === "number" && Number.isFinite(value)) {
+        doubles.push(value);
+      }
+      // Anything else (undefined, null, objects, NaN, …) is intentionally
+      // dropped: metric fields must be scalar and safe to record.
+    }
+    try {
+      dataset.writeDataPoint({
+        indexes: [truncateUtf8(event, MAX_INDEX_BYTES)],
+        blobs: capBlobs(blobs),
+        doubles: doubles.slice(0, MAX_DOUBLES),
+      });
+    } catch {
+      // Metrics MUST NOT throw: a failed write must never break the operation
+      // being measured. There is no fallback sink, so swallow it.
+    }
+  };
+
+  return {
+    count: (event, fields) => write(event, 1, fields),
+    observe: (event, value, fields) =>
+      write(event, Number.isFinite(value) ? value : 0, fields),
+  };
+}