@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/sentry.js

@@ -0,0 +1,284 @@
+/**
+ * Error reporting (OBS-02). One place that decides what leaves this service.
+ *
+ * The boundary is the SAME one the engine's signed receipts hold: **codes, scores and identifiers may
+ * leave; answer values, trace contents and credentials may not.** That is deliberately not "send
+ * nothing" — an issue you cannot debug is worse than no issue, so claim ids, collection ids, step
+ * names and error codes all ride along, and the log trail comes with them. What gets redacted is
+ * the short list in `SENSITIVE_KEYS` (lib/redact.ts, shared with the logger) plus auth headers.
+ *
+ * Two things this file exists to enforce:
+ *
+ * 1. **`withSentry` alone would report almost nothing.** This codebase catches by design — Hono's
+ *    `onError` converts every throw into the `AppError` envelope, and each side-effect lane
+ *    (chain-write, Matrix, cron) swallows its own failure so it can never fail a
+ *    workflow. An unhandled exception is the exception here, so the fail-soft catches call
+ *    `reportError` explicitly. Installing the SDK without those calls buys a green dashboard and
+ *    silent failures.
+ * 2. **Redaction is ours now.** Cloudflare's old dashboard integration scrubbed headers for you via
+ *    `BLOCKED_HEADERS`; that flow was removed in 2025, so the hooks below are the only thing
+ *    standing between a UCAN bearer token and Sentry.
+ *
+ * Unset `SENTRY_DSN` ⇒ every function here is a no-op (`captureException` with no client is safe),
+ * which is what keeps local dev and CI from shipping events.
+ */
+import * as Sentry from "@sentry/cloudflare";
+import { maskIds } from "./api-lane/ids.js";
+import { redact } from "./redact.js";
+/** Header names that must never reach Sentry. `authorization` is a live UCAN invocation. */
+const BLOCKED_HEADERS = ["authorization", "cookie", "x-auth-type", "x-source-id"];
+const DEFAULT_TRACES_SAMPLE_RATE = 0.1;
+/**
+ * The raw var, read before `config.ts` has validated anything (the SDK wraps the handler that
+ * loads the config): a bad value is the default, never a crash in the error reporter itself.
+ */
+function sampleRate(raw) {
+    const n = raw?.trim() ? Number(raw) : Number.NaN;
+    return Number.isFinite(n) && n >= 0 && n <= 1 ? n : DEFAULT_TRACES_SAMPLE_RATE;
+}
+/**
+ * A URL as it may leave: origin + the id-masked path, never the query or fragment. A signed link's
+ * query IS its credential (`/v1/api/files`, an upload link's `src/exp/sig`) and a `/v1/api` path
+ * can name a pending source (D10). A bare path (`http.target`) stays a path; anything else unparsable
+ * is dropped.
+ */
+function scrubUrl(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    if (raw.startsWith("/"))
+        return maskIds(raw.split(/[?#]/, 1)[0] ?? "");
+    try {
+        const u = new URL(raw);
+        return u.origin + maskIds(u.pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A span/transaction name (`GET /v1/api/uploads/upl_…?sig=…`, `GET https://…`): no query, ids masked. */
+const scrubName = (name) => maskIds(name.replace(/[?#]\S*/g, ""));
+/** Span attributes that hold a URL (reduced by `scrubUrl`) or only its query/fragment (dropped). */
+const URL_ATTRS = ["url.full", "http.url", "http.target", "url.path"];
+const QUERY_ATTRS = ["url.query", "http.query", "url.fragment", "http.fragment"];
+function scrubAttrs(data) {
+    const out = { ...data };
+    for (const k of URL_ATTRS)
+        if (k in out)
+            out[k] = scrubUrl(out[k]);
+    for (const k of QUERY_ATTRS)
+        delete out[k];
+    for (const k of Object.keys(out)) {
+        // `http.request.header.<name>` / `http.response.header.<name>` — the header rule, as attributes.
+        const header = /^http\.(?:request|response)\.header\.(.+)$/.exec(k)?.[1];
+        if (header && BLOCKED_HEADERS.includes(header.toLowerCase().replaceAll("_", "-"))) {
+            out[k] = "[redacted]";
+        }
+    }
+    return out;
+}
+function scrubSpan(span) {
+    if (span.description)
+        span.description = scrubName(span.description);
+    if (span.data)
+        span.data = scrubAttrs(span.data);
+    return span;
+}
+/** What an error event and a transaction share: its name, `request`, and the root span's data. */
+function scrubEvent(event) {
+    if (event.transaction)
+        event.transaction = scrubName(event.transaction);
+    if (event.request) {
+        if (event.request.url)
+            event.request.url = scrubUrl(event.request.url);
+        delete event.request.query_string;
+        const headers = event.request.headers;
+        if (headers) {
+            for (const name of Object.keys(headers)) {
+                if (BLOCKED_HEADERS.includes(name.toLowerCase()))
+                    headers[name] = "[redacted]";
+            }
+        }
+    }
+    const trace = event.contexts?.trace;
+    if (trace?.data)
+        trace.data = scrubAttrs(trace.data);
+}
+/**
+ * The init options, shared by the fetch/scheduled wrapper and by every instrumented Workflow so a
+ * workflow event can never be less redacted than a request event.
+ */
+export function sentryOptions(env) {
+    return {
+        dsn: env.SENTRY_DSN,
+        // `ENVIRONMENT` is already the deploy's name (development | staging | production) — reused
+        // unless `SENTRY_ENVIRONMENT` tells two deploys of one ENVIRONMENT apart (config.ts).
+        environment: env.SENTRY_ENVIRONMENT || env.ENVIRONMENT || "development",
+        // Stamped by the provider's deploy, so a stack trace resolves against the right source map.
+        // Unset (the common case, and every local run) is Sentry's own default — no release tag.
+        release: env.SENTRY_RELEASE,
+        tracesSampleRate: sampleRate(env.SENTRY_TRACES_SAMPLE_RATE),
+        // We propagate W3C `traceparent` ourselves (lib/tracing.ts); the SDK adding `sentry-trace` /
+        // `baggage` to every outbound fetch would hand them to external sources and webhook receivers.
+        tracePropagationTargets: [],
+        // ON: the whole point is that an issue carries its own log trail, so you are not cross-
+        // referencing Workers Logs by timestamp to understand a failure. `beforeSendLog` redacts.
+        enableLogs: true,
+        dataCollection: {
+            // No user identity, and no HTTP bodies — a review POST body is the reviewer's answers, and a
+            // register body carries a delegation CAR. Ids travel as tags instead (see `reportError`).
+            userInfo: false,
+            httpBodies: [],
+        },
+        beforeSend(event) {
+            scrubEvent(event);
+            if (event.contexts) {
+                // `contexts.trace` is Sentry's own trace/span ids, not ours to redact — without it an
+                // event loses its trace_id. Every other context is.
+                const { trace, ...rest } = event.contexts;
+                event.contexts = { ...redact(rest), ...(trace ? { trace } : {}) };
+            }
+            if (event.extra)
+                event.extra = redact(event.extra);
+            return event;
+        },
+        // Tracing is the other way out (`tracesSampleRate`): the SDK names the server span from the RAW
+        // path and stamps `url.full` / `http.query` on it, and an outbound fetch span carries the full
+        // URL it called (the engine's company read names a sourceId). Same scrub as an error event.
+        beforeSendTransaction(event) {
+            scrubEvent(event);
+            if (event.spans)
+                event.spans = event.spans.map(scrubSpan);
+            return event;
+        },
+        beforeSendSpan: scrubSpan,
+        beforeBreadcrumb(crumb) {
+            // Console crumbs are our log lines again (already in Workers Logs, and in `enableLogs`).
+            if (crumb.category === "console")
+                return null;
+            // A fetch URL can carry a credential (the ops-alert webhook, a signed query): origin only.
+            if ((crumb.category === "fetch" || crumb.category === "xhr") && crumb.data?.url) {
+                try {
+                    crumb.data.url = new URL(String(crumb.data.url)).origin;
+                }
+                catch {
+                    crumb.data.url = "[redacted]";
+                }
+            }
+            if (crumb.data)
+                crumb.data = redact(crumb.data);
+            return crumb;
+        },
+        beforeSendLog(log) {
+            if (log.attributes) {
+                // `sentry.*` attributes are the SDK's own (`sentry.trace.parent_span_id`, …) — kept.
+                const own = Object.entries(log.attributes).filter(([k]) => k.startsWith("sentry."));
+                log.attributes = {
+                    ...redact(log.attributes),
+                    ...Object.fromEntries(own),
+                };
+            }
+            return log;
+        },
+    };
+}
+/** True when the lane is configured at all — lets callers skip building context for nothing. */
+export const sentryEnabled = (config) => !!config.SENTRY_DSN;
+/**
+ * Report a failure the code deliberately swallowed.
+ *
+ * `fingerprint` groups retries of the same durable step into ONE issue instead of one per attempt;
+ * Workflow steps retry by design, and without this a single stuck claim would page repeatedly.
+ * (The SDK already disables its own dedupe integration inside Workflows.) It is deliberately NOT
+ * keyed on claimId — one broken lane should be one issue with many events, not one issue per claim.
+ */
+export function reportError(err, scope) {
+    Sentry.withScope((s) => {
+        s.setTag("lane", scope.lane);
+        if (scope.step)
+            s.setTag("step", scope.step);
+        if (scope.claimId)
+            s.setTag("claimId", scope.claimId);
+        if (scope.collectionId)
+            s.setTag("collectionId", scope.collectionId);
+        if (scope.instanceId)
+            s.setTag("instanceId", scope.instanceId);
+        s.setFingerprint(["{{ default }}", scope.lane, scope.step ?? ""]);
+        if (scope.context)
+            s.setContext("detail", scope.context);
+        Sentry.captureException(err);
+    });
+}
+/** One page per condition per window: a flapping lane pages once, not every tick. */
+const ALERT_DEDUPE_SEC = 30 * 60;
+const ALERT_TIMEOUT_MS = 5_000;
+/**
+ * Page someone (observability spec §5.2): a condition a runbook says wakes a person, as opposed to
+ * a failure `reportError` records. The same contract in every IXO service:
+ *
+ * 1. Dedupe FIRST, on KV `ops-alert:<dedupeKey ?? event>` for 30 minutes — so both sinks see one
+ *    page per condition per window, not one per occurrence. That is why event names carry the
+ *    reason (`collection.paused.rubric-unusable`): the dedupe must never hide a different condition.
+ *    A KV that throws is no reason to stay silent: send anyway.
+ * 2. Sentry: one `captureMessage` at `error`, fingerprinted on `event`, so one condition is one
+ *    issue — the issue alert routes it to Slack. A no-op without `SENTRY_DSN`.
+ * 3. `OPS_ALERT_WEBHOOK_URL`, only when set: a Slack-compatible `{ text }` POST, under
+ *    `suppressTracing` so no span or breadcrumb records the URL (it is the credential). A POST that
+ *    fails frees the dedupe key, so the next occurrence tries again.
+ *
+ * Never throws — it sits beside the log line of a lane that is already failing, and must not be
+ * the thing that fails it. A webhook failure is one `ops-alert.failed` warn (no URL in it).
+ */
+export async function reportAlert(deps, event, fields = {}, dedupeKey) {
+    const key = `ops-alert:${dedupeKey ?? event}`;
+    try {
+        if (deps.cache) {
+            const seen = await deps.cache.get(key).catch(() => null);
+            if (seen !== null)
+                return;
+            await deps.cache.put(key, "1", { expirationTtl: ALERT_DEDUPE_SEC }).catch(() => { });
+        }
+        const safe = redact(fields);
+        Sentry.withScope((s) => {
+            s.setLevel("error");
+            s.setFingerprint([event]);
+            s.setTag("alert", event);
+            s.setExtras(safe);
+            Sentry.captureMessage(event);
+        });
+        const url = deps.config.OPS_ALERT_WEBHOOK_URL;
+        if (!url)
+            return;
+        const where = `${deps.config.SERVICE_NAME ?? "eval-oracle"} ${deps.config.IXO_NETWORK ?? ""}`;
+        const pairs = Object.entries(safe)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `${k}=${v}`);
+        const text = [`[${where.trim()}] ${event}`, ...pairs].join(" ");
+        const failed = await Sentry.suppressTracing(async () => {
+            try {
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ text }),
+                    signal: AbortSignal.timeout(ALERT_TIMEOUT_MS),
+                });
+                await res.body?.cancel().catch(() => { });
+                return res.ok ? null : `HTTP ${res.status}`;
+            }
+            catch (err) {
+                // The error's NAME only: a fetch error's message can quote the URL.
+                return err instanceof Error ? err.name : "error";
+            }
+        });
+        if (failed) {
+            deps.logger.warn("ops-alert.failed", { event, reason: failed });
+            await deps.cache?.delete(key).catch(() => { });
+        }
+    }
+    catch (err) {
+        deps.logger.warn("ops-alert.failed", {
+            event,
+            reason: err instanceof Error ? err.name : "error",
+        });
+    }
+}
+//# sourceMappingURL=sentry.js.map

package/dist/lib/sentry.js.map

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

package/dist/lib/spans.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Workers Traces custom spans (observability spec §4) — apart from `tracing.ts` because this one
+ * imports `cloudflare:workers`, and the CLI (a bun/node program) imports `tracing.ts`. The facts
+ * lane never imports this: it is handed `inSpan` through its deps (`ProducerDeps.span`), the same
+ * way it is handed `metrics`, so it stays node-safe.
+ */
+/**
+ * Run `fn` inside a custom span (`tracing.enterSpan`, which ends it when `fn`'s promise settles).
+ * An unsampled request still runs `fn`, just records nothing; a runtime without the API runs `fn`
+ * bare. Attributes are the metrics' low-cardinality labels only, never payloads. `setAttribute`
+ * one by one: `setAttributes` is newer than the local workerd the tests run on (it throws there).
+ */
+export declare function inSpan<T>(name: string, attrs: Record<string, string | number | undefined>, fn: () => T): T;
+//# sourceMappingURL=spans.d.ts.map

package/dist/lib/spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.d.ts","sourceRoot":"","sources":["../../src/lib/spans.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,EAClD,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAWH"}

package/dist/lib/spans.js

@@ -0,0 +1,28 @@
+/**
+ * Workers Traces custom spans (observability spec §4) — apart from `tracing.ts` because this one
+ * imports `cloudflare:workers`, and the CLI (a bun/node program) imports `tracing.ts`. The facts
+ * lane never imports this: it is handed `inSpan` through its deps (`ProducerDeps.span`), the same
+ * way it is handed `metrics`, so it stays node-safe.
+ */
+import * as workers from "cloudflare:workers";
+/**
+ * Run `fn` inside a custom span (`tracing.enterSpan`, which ends it when `fn`'s promise settles).
+ * An unsampled request still runs `fn`, just records nothing; a runtime without the API runs `fn`
+ * bare. Attributes are the metrics' low-cardinality labels only, never payloads. `setAttribute`
+ * one by one: `setAttributes` is newer than the local workerd the tests run on (it throws there).
+ */
+export function inSpan(name, attrs, fn) {
+    const tracing = workers.tracing;
+    if (typeof tracing?.enterSpan !== "function")
+        return fn();
+    return tracing.enterSpan(name, (span) => {
+        if (span.isTraced) {
+            for (const [key, value] of Object.entries(attrs)) {
+                if (value !== undefined)
+                    span.setAttribute(key, value);
+            }
+        }
+        return fn();
+    });
+}
+//# sourceMappingURL=spans.js.map

package/dist/lib/spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.js","sourceRoot":"","sources":["../../src/lib/spans.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CACpB,IAAY,EACZ,KAAkD,EAClD,EAAW;IAEX,MAAM,OAAO,GAAG,OAAO,CAAC,OAA8B,CAAC;IACvD,IAAI,OAAO,OAAO,EAAE,SAAS,KAAK,UAAU;QAAE,OAAO,EAAE,EAAE,CAAC;IAC1D,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;QACtC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,IAAI,KAAK,KAAK,SAAS;oBAAE,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QACD,OAAO,EAAE,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/tracing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lightweight, dependency-free distributed tracing.
+ *
+ * Implements W3C Trace Context (`traceparent`) parsing/generation so traces
+ * correlate across services and show up alongside logs in Workers Logs (every
+ * log line carries `traceId`). Outbound requests can propagate the context via
+ * `tracedFetch`. This deliberately avoids pulling in the full OpenTelemetry SDK
+ * to stay within the Cloudflare-native, zero-extra-vendor observability model —
+ * swap in `@microlabs/otel-cf-workers` later if you need OTLP export.
+ */
+export interface TraceContext {
+    /** 32 hex chars. */
+    traceId: string;
+    /** 16 hex chars — the current span. */
+    spanId: string;
+    /** Incoming parent span, if this request was called by another service. */
+    parentSpanId?: string;
+    sampled: boolean;
+}
+export declare function generateTraceContext(): TraceContext;
+/** Parse an incoming `traceparent` header, or return null if absent/invalid. */
+export declare function parseTraceparent(header: string | null | undefined): TraceContext | null;
+/** Continue an incoming trace if present, otherwise start a new root trace. */
+export declare function traceContextFromRequest(req: Request): TraceContext;
+export declare function toTraceparent(ctx: TraceContext): string;
+/**
+ * `fetch` that propagates the current trace context downstream so calls to
+ * other services / your own APIs join the same trace.
+ */
+export declare function tracedFetch(ctx: TraceContext, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/lib/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAcD,wBAAgB,oBAAoB,IAAI,YAAY,CAMnD;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CAiBvF;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAElE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAGvD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,QAAQ,CAAC,CAInB"}

package/dist/lib/tracing.js

@@ -0,0 +1,66 @@
+/**
+ * Lightweight, dependency-free distributed tracing.
+ *
+ * Implements W3C Trace Context (`traceparent`) parsing/generation so traces
+ * correlate across services and show up alongside logs in Workers Logs (every
+ * log line carries `traceId`). Outbound requests can propagate the context via
+ * `tracedFetch`. This deliberately avoids pulling in the full OpenTelemetry SDK
+ * to stay within the Cloudflare-native, zero-extra-vendor observability model —
+ * swap in `@microlabs/otel-cf-workers` later if you need OTLP export.
+ */
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+function randomHex(bytes) {
+    const buf = new Uint8Array(bytes);
+    crypto.getRandomValues(buf);
+    let out = "";
+    for (const byte of buf) {
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+export function generateTraceContext() {
+    return {
+        traceId: randomHex(16),
+        spanId: randomHex(8),
+        sampled: true,
+    };
+}
+/** Parse an incoming `traceparent` header, or return null if absent/invalid. */
+export function parseTraceparent(header) {
+    if (!header)
+        return null;
+    const match = TRACEPARENT_RE.exec(header.trim());
+    if (!match)
+        return null;
+    const [, , traceId, parentSpanId, flags] = match;
+    if (!traceId || !parentSpanId || !flags)
+        return null;
+    // All-zero trace/span ids are invalid per spec.
+    if (traceId === "0".repeat(32) || parentSpanId === "0".repeat(16))
+        return null;
+    return {
+        traceId,
+        // Continue the trace, but start a fresh span for this hop.
+        spanId: randomHex(8),
+        parentSpanId,
+        sampled: (Number.parseInt(flags, 16) & 0x01) === 0x01,
+    };
+}
+/** Continue an incoming trace if present, otherwise start a new root trace. */
+export function traceContextFromRequest(req) {
+    return parseTraceparent(req.headers.get("traceparent")) ?? generateTraceContext();
+}
+export function toTraceparent(ctx) {
+    const flags = ctx.sampled ? "01" : "00";
+    return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+/**
+ * `fetch` that propagates the current trace context downstream so calls to
+ * other services / your own APIs join the same trace.
+ */
+export function tracedFetch(ctx, input, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("traceparent", toTraceparent(ctx));
+    return fetch(input, { ...init, headers });
+}
+//# sourceMappingURL=tracing.js.map

package/dist/lib/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,MAAM,cAAc,GAAG,6DAA6D,CAAC;AAErF,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QACpB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAChE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,CAAC,EAAE,AAAD,EAAG,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IACjD,IAAI,CAAC,OAAO,IAAI,CAAC,YAAY,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACrD,gDAAgD;IAChD,IAAI,OAAO,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,YAAY,KAAK,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/E,OAAO;QACL,OAAO;QACP,2DAA2D;QAC3D,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QACpB,YAAY;QACZ,OAAO,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI;KACtD,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,OAAO,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,oBAAoB,EAAE,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAiB;IAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,OAAO,MAAM,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,GAAiB,EACjB,KAAwB,EACxB,IAAkB;IAElB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC5C,CAAC"}

package/dist/lib/ttl-cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A small in-isolate cache with an expiry per entry AND a hard cap on how many it holds.
+ *
+ * The module-level `Map`s this replaces only ever dropped an entry when the SAME key was read
+ * again after it expired — so a key that is never asked for twice stayed for the isolate's life.
+ * That is harmless for a handful of service DIDs and a real problem for the UCAN token cache,
+ * whose key is a hash of whatever bearer an unauthenticated caller chose to send: every distinct
+ * garbage token added an entry (the 30 s negative cache), and nothing ever removed it.
+ *
+ * `now` and `exp` are the caller's clock, in the caller's unit — this file never reads the time,
+ * so it stays pure and trivially testable. Eviction is two passes, both only when the cap is hit:
+ * expired entries first, then the oldest inserted (a `Map` iterates in insertion order), so a
+ * flood can at worst push out entries that would have been re-validated anyway.
+ */
+export declare class TtlCache<V> {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries: number);
+    get size(): number;
+    /** The live value, or undefined — an expired entry is removed on the way out. */
+    get(key: string, now: number): V | undefined;
+    set(key: string, value: V, exp: number, now: number): void;
+    delete(key: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=ttl-cache.d.ts.map

package/dist/lib/ttl-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.d.ts","sourceRoot":"","sources":["../../src/lib/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAGT,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IAExE,YAA6B,UAAU,EAAE,MAAM,EAI9C;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,iFAAiF;IACjF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAQ3C;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAazD;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAExB;IAED,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/lib/ttl-cache.js

@@ -0,0 +1,61 @@
+/**
+ * A small in-isolate cache with an expiry per entry AND a hard cap on how many it holds.
+ *
+ * The module-level `Map`s this replaces only ever dropped an entry when the SAME key was read
+ * again after it expired — so a key that is never asked for twice stayed for the isolate's life.
+ * That is harmless for a handful of service DIDs and a real problem for the UCAN token cache,
+ * whose key is a hash of whatever bearer an unauthenticated caller chose to send: every distinct
+ * garbage token added an entry (the 30 s negative cache), and nothing ever removed it.
+ *
+ * `now` and `exp` are the caller's clock, in the caller's unit — this file never reads the time,
+ * so it stays pure and trivially testable. Eviction is two passes, both only when the cap is hit:
+ * expired entries first, then the oldest inserted (a `Map` iterates in insertion order), so a
+ * flood can at worst push out entries that would have been re-validated anyway.
+ */
+export class TtlCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+        if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+            throw new Error("TtlCache: maxEntries must be a positive integer");
+        }
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /** The live value, or undefined — an expired entry is removed on the way out. */
+    get(key, now) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.exp <= now) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, exp, now) {
+        // Re-inserting moves the key to the back of the eviction order: a refreshed entry is "new".
+        this.entries.delete(key);
+        if (this.entries.size >= this.maxEntries) {
+            for (const [k, entry] of this.entries) {
+                if (entry.exp <= now)
+                    this.entries.delete(k);
+            }
+            for (const k of this.entries.keys()) {
+                if (this.entries.size < this.maxEntries)
+                    break;
+                this.entries.delete(k);
+            }
+        }
+        this.entries.set(key, { value, exp });
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=ttl-cache.js.map

package/dist/lib/ttl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl-cache.js","sourceRoot":"","sources":["../../src/lib/ttl-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,QAAQ;IAGU,UAAU;IAFtB,OAAO,GAAG,IAAI,GAAG,EAAqC,CAAC;IAExE,YAA6B,UAAkB;0BAAlB,UAAU;QACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,iFAAiF;IACjF,GAAG,CAAC,GAAW,EAAE,GAAW;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAE,GAAW,EAAE,GAAW;QACjD,4FAA4F;QAC5F,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACtC,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG;oBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC/C,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU;oBAAE,MAAM;gBAC/C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/lib/validator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Zod-backed request validation that funnels failures through the global error
+ * handler, so validation errors return the SAME `{ error: { code, message,
+ * requestId, details } }` envelope as everything else — instead of
+ * `@hono/zod-validator`'s raw default response.
+ *
+ * Usage (fully type-safe — `c.req.valid("json")` is inferred from the schema):
+ *
+ *   v1.post("/echo", validate("json", EchoBody), (c) => {
+ *     const body = c.req.valid("json");
+ *   });
+ */
+import type { ValidationTargets } from "hono";
+import type { ZodType } from "zod";
+export declare function validate<T extends ZodType, Target extends keyof ValidationTargets>(target: Target, schema: T): import("hono").MiddlewareHandler<import("hono").Env, string, {
+    in: (undefined extends (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) ? true : false) extends true ? { [K in Target]?: ([T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never] extends [ValidationTargets[K]] ? ValidationTargets[K] & (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [never] ? {} : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [object] ? undefined extends (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) ? (((Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined> extends infer T_3 ? { [K_1 in keyof T_3]: ([Exclude<T_3[K_1], undefined>] extends [string] ? [string & Exclude<T_3[K_1], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_3[K_1], undefined>>] ? false : true : false) extends true ? T_3[K_1] : ([unknown] extends [T_3[K_1]] ? false : undefined extends T_3[K_1] ? true : false) extends true ? T_3[K_1] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_2 ? { [K_1 in keyof T_2]: T_2[K_1]; } : never) extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never) | ((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined) : (((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) extends infer T_6 ? { [K_1 in keyof T_6]: ([Exclude<T_6[K_1], undefined>] extends [string] ? [string & Exclude<T_6[K_1], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_6[K_1], undefined>>] ? false : true : false) extends true ? T_6[K_1] : ([unknown] extends [T_6[K_1]] ? false : undefined extends T_6[K_1] ? true : false) extends true ? T_6[K_1] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_5 ? { [K_1 in keyof T_5]: T_5[K_1]; } : never) extends infer T_4 ? { [K_1 in keyof T_4]: T_4[K_1]; } : never : {}) | undefined; } : { [K in Target]: [T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never] extends [ValidationTargets[K]] ? ValidationTargets[K] & (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [never] ? {} : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [object] ? undefined extends (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) ? (((Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined> extends infer T_3 ? { [K_1 in keyof T_3]: ([Exclude<T_3[K_1], undefined>] extends [string] ? [string & Exclude<T_3[K_1], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_3[K_1], undefined>>] ? false : true : false) extends true ? T_3[K_1] : ([unknown] extends [T_3[K_1]] ? false : undefined extends T_3[K_1] ? true : false) extends true ? T_3[K_1] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_2 ? { [K_1 in keyof T_2]: T_2[K_1]; } : never) extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never) | ((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined) : (((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) extends infer T_6 ? { [K_1 in keyof T_6]: ([Exclude<T_6[K_1], undefined>] extends [string] ? [string & Exclude<T_6[K_1], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_6[K_1], undefined>>] ? false : true : false) extends true ? T_6[K_1] : ([unknown] extends [T_6[K_1]] ? false : undefined extends T_6[K_1] ? true : false) extends true ? T_6[K_1] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_5 ? { [K_1 in keyof T_5]: T_5[K_1]; } : never) extends infer T_4 ? { [K_1 in keyof T_4]: T_4[K_1]; } : never : {}; };
+    out: { [K in Target]: T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").output<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").output<T> : never; };
+}, never>;
+//# sourceMappingURL=validator.d.ts.map

package/dist/lib/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/lib/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAGnC,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,SAAS,MAAM,iBAAiB,EAChF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC;;;UAiBV"}

package/dist/lib/validator.js

@@ -0,0 +1,32 @@
+/**
+ * Zod-backed request validation that funnels failures through the global error
+ * handler, so validation errors return the SAME `{ error: { code, message,
+ * requestId, details } }` envelope as everything else — instead of
+ * `@hono/zod-validator`'s raw default response.
+ *
+ * Usage (fully type-safe — `c.req.valid("json")` is inferred from the schema):
+ *
+ *   v1.post("/echo", validate("json", EchoBody), (c) => {
+ *     const body = c.req.valid("json");
+ *   });
+ */
+import { zValidator } from "@hono/zod-validator";
+import { AppError, VALIDATION_FAILED } from "./errors.js";
+export function validate(target, schema) {
+    return zValidator(target, schema, (result) => {
+        if (!result.success) {
+            throw new AppError(VALIDATION_FAILED, {
+                code: "VALIDATION",
+                details: {
+                    target,
+                    issues: result.error.issues.map((issue) => ({
+                        path: issue.path.join("."),
+                        message: issue.message,
+                        code: issue.code,
+                    })),
+                },
+            });
+        }
+    });
+}
+//# sourceMappingURL=validator.js.map