@zeyolabs/kit 0.0.0-stage → 2026.11.6

package/cloudflare/workers/ticking-do.ts

@@ -0,0 +1,104 @@
+import { DurableObject } from 'cloudflare:workers';
+
+import type { ScheduledHandler } from './index';
+
+import { EnvStore } from '../../utils/env';
+
+/** Storage key marking a tick currently in flight — see `ensureAlarm()`'s doc comment for why. */
+const TICK_IN_PROGRESS_KEY = 'tickInProgress';
+
+/**
+ * Base class for a Durable Object whose whole job is a self-rescheduling alarm loop. Resolves
+ * `EnvStore` and always re-arms even if `tick()` throws, then calls `onTick(outcome)` — no
+ * default, implement it directly or wrap with `withTicking(...)`.
+ *
+ * ```ts
+ * export class MyThingDO extends TickingDurableObject<Env> {
+ *   protected readonly tickIntervalMs = 60_000;
+ *   protected readonly service = 'my-worker';
+ *   protected readonly secretNames = SECRET_STORE_BINDING_NAMES; // the app's secret-store binding names
+ *   protected async tick(): Promise<void> { ... }
+ *   protected async onTick(outcome: 'error' | 'ok'): Promise<void> {
+ *     Metrics.TickingDO(this.service, envStore()).onTick(outcome);
+ *   }
+ * }
+ * ```
+ *
+ * Wire a cron backstop with `.cron(expr, ensureTickingDO<Env>(env => env.MY_DO_NAMESPACE))` below.
+ */
+export abstract class TickingDurableObject<Env> extends DurableObject<Env> {
+	/** the app's secret-store binding names. */
+	protected abstract readonly secretNames: ReadonlySet<string>;
+	protected abstract readonly service: string;
+	protected abstract readonly tickIntervalMs: number;
+
+	async alarm(): Promise<void> {
+		await EnvStore.resolve(this.env, this.secretNames);
+		await this.ctx.storage.put(TICK_IN_PROGRESS_KEY, true);
+		try {
+			await this.tick();
+			await this.onTick('ok');
+		} catch (e) {
+			await this.onTick('error');
+			throw e;
+		} finally {
+			await this.ctx.storage.delete(TICK_IN_PROGRESS_KEY);
+			await this.ctx.storage.setAlarm(Date.now() + this.tickIntervalMs);
+		}
+	}
+
+	/** No-op if an alarm is already scheduled or a tick is running — `getAlarm() === null` alone
+	 *  can't tell a healthy in-progress tick from a genuinely broken chain, since the slot is
+	 *  empty for a normal tick's whole duration too. */
+	async ensureAlarm(): Promise<void> {
+		const [current, tickInProgress] = await Promise.all([
+			this.ctx.storage.getAlarm(),
+			this.ctx.storage.get<boolean>(TICK_IN_PROGRESS_KEY),
+		]);
+		if (current === null && !tickInProgress) {
+			await this.ctx.storage.setAlarm(Date.now() + this.tickIntervalMs);
+		}
+	}
+
+	protected abstract onTick(outcome: 'error' | 'ok'): Promise<void>;
+
+	protected abstract tick(): Promise<void>;
+}
+
+/** Plug `onTick` in at the binding site instead of overriding it in a subclass — same spot
+ *  `WorkerDOBinding.withSentry(...)` already wraps the class:
+ *
+ * ```ts
+ * export const MyThing = WorkerDOBinding.withSentry(
+ *   withTicking(MyThingDO, (outcome, instance) => sendToSlack(`${instance.service}: ${outcome}`))
+ * );
+ * ```
+ */
+export function withTicking<Env, T extends TickingDurableObject<Env>>(
+	DOClass: new (state: DurableObjectState, env: Env) => T,
+	onTick: (outcome: 'error' | 'ok', instance: T) => Promise<void> | void
+): new (state: DurableObjectState, env: Env) => T {
+	// Extending T directly leaves its abstract members "unimplemented" as far as TS is concerned.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	class Ticking extends (DOClass as unknown as new (state: DurableObjectState, env: Env) => any) {
+		protected async onTick(outcome: 'error' | 'ok'): Promise<void> {
+			await onTick(outcome, this as unknown as T);
+		}
+	}
+	return Ticking as unknown as new (state: DurableObjectState, env: Env) => T;
+}
+
+/** For `.cron(expr, ensureTickingDO<Env>(env => env.MY_DO_NAMESPACE))` — no per-worker handler
+ *  needed when the DO's own `ensureAlarm()` is the whole job. */
+export function ensureTickingDO<Env, Id = unknown>(
+	getNamespace: (env: Env) => {
+		get(id: Id): { ensureAlarm(): Promise<void> };
+		idFromName(name: string): Id;
+	},
+	name = 'global'
+): ScheduledHandler<Env> {
+	return async (_controller, env) => {
+		const namespace = getNamespace(env);
+		await namespace.get(namespace.idFromName(name)).ensureAlarm();
+	};
+}

package/cloudflare/workers-ai/client.ts

@@ -0,0 +1,30 @@
+import type { Ai } from '@cloudflare/workers-types';
+
+import { envStore, type EnvStore } from '../../utils/env';
+
+export interface IWorkersAiClient {
+	run(...args: Parameters<Ai['run']>): ReturnType<Ai['run']>;
+}
+
+/**
+ * Thin wrapper over the Workers AI binding (`env.AI` — Cloudflare's own hosted models). No
+ * business logic of its own — a feature builds its own prompt and parses its own output; this
+ * just forwards to the binding.
+ */
+export class WorkersAiClient implements IWorkersAiClient {
+	private readonly binding: Ai;
+
+	constructor(env: EnvStore) {
+		this.binding = env.binding<Ai>('AI');
+	}
+
+	run(...args: Parameters<Ai['run']>): ReturnType<Ai['run']> {
+		return this.binding.run(...args);
+	}
+}
+
+/** Built fresh per call, same as `gates()` — the binding itself is cheap to wrap, nothing to
+ *  isolate-cache. */
+export function workersAi(): WorkersAiClient {
+	return new WorkersAiClient(envStore());
+}

package/cloudflare/workers-ai/testing.ts

@@ -0,0 +1,17 @@
+import type { Ai } from '@cloudflare/workers-types';
+
+import type { IWorkersAiClient } from './client';
+
+export class FakeWorkersAiClient implements IWorkersAiClient {
+	readonly calls: Parameters<Ai['run']>[] = [];
+	private readonly responses: unknown[] = [];
+
+	respondWith(response: unknown): void {
+		this.responses.push(response);
+	}
+
+	run(...args: Parameters<Ai['run']>): ReturnType<Ai['run']> {
+		this.calls.push(args);
+		return Promise.resolve(this.responses.shift()) as ReturnType<Ai['run']>;
+	}
+}

package/cloudflare/workers-env.ts

@@ -0,0 +1,12 @@
+/** The Workers bindings (`cloudflare:workers`'s `env`), or `{}` where there are none. The module
+ *  only resolves inside the Workers runtime — not in the Node process that analyses routes during
+ *  `vite build`, and the adapter throws on access while prerendering — so it's imported
+ *  dynamically and any failure means "no bindings". */
+export async function workersEnv(): Promise<Record<string, unknown>> {
+	try {
+		const { env } = await import('cloudflare:workers');
+		return { ...env };
+	} catch {
+		return {};
+	}
+}

package/eslint-config.js

@@ -0,0 +1,115 @@
+import { includeIgnoreFile } from '@eslint/compat';
+import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import drizzlePlugin from 'eslint-plugin-drizzle';
+import perfectionist from 'eslint-plugin-perfectionist';
+import svelte from 'eslint-plugin-svelte';
+import globals from 'globals';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import * as svelteParser from 'svelte-eslint-parser';
+import ts from 'typescript-eslint';
+
+// Re-export `config()` so each package's eslint.config.js can import everything from this one
+// package — no direct dependency on typescript-eslint required downstream.
+export { ts };
+export const config = ts.config;
+
+// The consumer's .gitignore: the nearest one upward from where ESLint runs, so a monorepo app
+// inherits the repo root's ignores and this package works the same installed from a registry.
+function nearestGitignore(dir = process.cwd()) {
+	for (let current = dir; ; current = dirname(current)) {
+		const candidate = join(current, '.gitignore');
+		if (existsSync(candidate)) return candidate;
+		if (dirname(current) === current) return null;
+	}
+}
+
+/**
+ * Shared base: js + ts + prettier + perfectionist, browser+node globals. Syntactic rules only
+ * (`ts.configs.recommended`), so no `projectService` is configured — type-aware linting is slow
+ * and none of the enabled rules need it.
+ */
+export function base() {
+	const gitignore = nearestGitignore();
+	return [
+		...(gitignore ? [includeIgnoreFile(gitignore)] : []),
+		{ ignores: ['**/worker-configuration.d.ts'] },
+		js.configs.recommended,
+		...ts.configs.recommended,
+		prettier,
+		perfectionist.configs['recommended-natural'],
+		{
+			languageOptions: {
+				globals: { ...globals.browser, ...globals.node },
+			},
+			rules: {
+				'@typescript-eslint/consistent-type-imports': 'error',
+				'@typescript-eslint/no-import-type-side-effects': 'error',
+				'@typescript-eslint/no-unused-vars': [
+					'error',
+					{ argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+				],
+				'perfectionist/sort-modules': ['error', { partitionByNewLine: true }],
+				// ClickHouse Native decode is positional: a row schema's field order must match its
+				// SELECT list, not get alphabetized. Exempt schemas passed straight to rawSelect() and
+				// ones assigned to a `*CHRow` const (the established naming convention for these).
+				'perfectionist/sort-objects': [
+					'error',
+					{
+						type: 'unsorted',
+						useConfigurationIf: {
+							callingFunctionNamePattern: { pattern: 'rawSelect', scope: 'deep' },
+						},
+					},
+					{
+						type: 'unsorted',
+						useConfigurationIf: {
+							declarationMatchesPattern: { pattern: 'CHRow$', scope: 'deep' },
+						},
+					},
+					{ partitionByNewLine: true },
+				],
+				'perfectionist/sort-switch-case': 'off',
+			},
+		},
+	];
+}
+
+/**
+ * Svelte parsing + recommended rules. `svelteConfig` is optional: apps pass their own
+ * svelte.config.js; source packages (ui) have none and call with no argument.
+ * @param {object} [svelteConfig]
+ */
+export function svelteRules(svelteConfig) {
+	return [
+		...svelte.configs.recommended,
+		...svelte.configs.prettier,
+		{
+			files: ['**/*.svelte', '**/*.svelte.ts'],
+			languageOptions: {
+				parser: svelteParser,
+				parserOptions: {
+					extraFileExtensions: ['.svelte'],
+					parser: ts.parser,
+					...(svelteConfig ? { svelteConfig } : {}),
+				},
+			},
+			rules: {
+				'svelte/sort-attributes': 'error',
+			},
+		},
+	];
+}
+
+// Drizzle safety rules: guard unfiltered delete/update. Scoped to the real drizzle handles
+// (`db`, `tx`) so Map/Set `.delete()` calls aren't flagged.
+const drizzleObjectName = ['db', 'tx'];
+export const drizzleRules = {
+	files: ['**/*.ts'],
+	plugins: { drizzle: drizzlePlugin },
+	rules: {
+		'drizzle/enforce-delete-with-where': ['error', { drizzleObjectName }],
+		'drizzle/enforce-update-with-where': ['error', { drizzleObjectName }],
+	},
+};

package/monitoring/alerts/client.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+import type { LoggerClient } from '../logger/client';
+import type { EventKey, EventRegistry } from './registry';
+
+/** Structural shape of the alerts queue binding — kept minimal so this doesn't pull in a
+ *  Cloudflare Workers type kit doesn't already depend on. */
+export type AlertsQueueBinding = { send(body: unknown): Promise<void> };
+
+/**
+ * Fires alert events onto a queue binding, generic over the caller's own event registry `R` —
+ * kit has no notion of what an alert type is called. `fire` warns and returns instead of throwing
+ * when the binding is absent — this is what lets the binding roll out app-by-app without every
+ * caller needing a feature-flag check first. Once the binding exists, a failed enqueue IS a real
+ * error (the caller believed the alert would fire and it silently wouldn't), so that case logs
+ * and rethrows instead of being swallowed.
+ */
+export class Alert<R extends EventRegistry> {
+	constructor(
+		private readonly queue: AlertsQueueBinding | undefined,
+		private readonly logger: LoggerClient,
+		private readonly registry: R
+	) {}
+
+	/** `accountId` is the envelope the consumer scopes by, not part of what happened — so it's its
+	 *  own argument rather than something every producer has to remember to put in the payload.
+	 *  The payload is encoded to its wire form here, so an invalid one throws instead of being
+	 *  dropped by the consumer. */
+	async fire<K extends EventKey<R>>(
+		accountId: number,
+		event: K,
+		payload: z.output<R[K]['payload']>
+	): Promise<void> {
+		if (!this.queue) {
+			this.logger.warn('alerts queue binding not configured — dropping alert event', { event });
+			return;
+		}
+
+		try {
+			const encoded = z.encode(this.registry[event].payload, payload);
+			// eslint-disable-next-line perfectionist/sort-objects -- key order is the serialized wire order
+			await this.queue.send({ event, payload: encoded, accountId });
+		} catch (err) {
+			this.logger.error(err, { accountId, event, op: 'alertFire' });
+			throw err;
+		}
+	}
+}

package/monitoring/alerts/event-config.ts

@@ -0,0 +1,33 @@
+import type { z } from 'zod';
+
+import type { Event, EventKey, EventRegistry } from './registry';
+
+/**
+ * Optional behavior for one event: a user-configurable filter deciding whether a fired payload
+ * actually trips an alert. An event with no entry in the map it belongs to always matches, with
+ * no config to collect — this is only for an event that needs a real parameter, like
+ * `credits_low`'s threshold.
+ *
+ * Distributed over `K` so the type is a union with one arm per event key. `matches` gets that
+ * event's own payload type rather than a union of all payloads. `config` isn't correlated with
+ * `matches`' second argument — a single object literal can't tie a schema to its own inferred
+ * type — so `matches` and `summary` receive it as `unknown` and parse.
+ */
+export type EventConfig<
+	R extends EventRegistry,
+	K extends EventKey<R> = EventKey<R>,
+> = K extends unknown
+	? {
+			config: z.ZodType;
+			defaults: unknown;
+			/** The entity this alert is about, for dedupe — absent means the whole payload is the entity. */
+			entity?(payload: Extract<Event<R>, { event: K }>['payload']): string;
+			matches(payload: Extract<Event<R>, { event: K }>['payload'], config: unknown): boolean;
+			/** One-line description of the config, for list views. */
+			summary(config: unknown): string;
+		}
+	: never;
+
+export type EventConfigMap<R extends EventRegistry> = Partial<{
+	[K in EventKey<R>]: EventConfig<R, K>;
+}>;

package/monitoring/alerts/policy.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+import { Schema } from '../../utils/schema';
+
+/** A policy's recipients are unverified addresses the account types in, so the count is bounded. */
+export const MAX_POLICY_RECIPIENTS = 10;
+
+/** Each webhook is an outbound request per fired event, so the count is bounded. */
+export const MAX_POLICY_WEBHOOKS = 5;
+
+/** Saved webhook destinations per account. */
+export const MAX_ACCOUNT_WEBHOOKS = 20;
+
+/** Scalars and string lists, so it fits a `<Form>`'s input type; the service validates it against the config schema of the policy's alert type. */
+export const PolicyConfig = z.record(
+	z.string(),
+	z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])
+);
+
+/** `description: null` clears it; omitted fields are left as they are, and `recipients`/`webhookIds` replace the destinations only when given. */
+export const UpdatePolicySchema = z.object({
+	config: PolicyConfig.optional(),
+	description: Schema.Text.max(280).nullable().optional(),
+	enabled: z.boolean().optional(),
+	id: Schema.UUID,
+	name: Schema.Text.max(80).optional(),
+	recipients: z.array(Schema.Email).max(MAX_POLICY_RECIPIENTS).optional(),
+	webhookIds: z.array(z.number().int()).max(MAX_POLICY_WEBHOOKS).optional(),
+});
+export type UpdatePolicySchema = z.infer<typeof UpdatePolicySchema>;
+
+export const PolicyIdSchema = z.object({ id: Schema.UUID });
+export type PolicyIdSchema = z.infer<typeof PolicyIdSchema>;
+
+export const HistoryPageQuerySchema = z.object({
+	limit: z.number().int().min(1).max(100).default(20),
+	offset: z.number().int().min(0).default(0),
+});
+export type HistoryPageQuerySchema = z.infer<typeof HistoryPageQuerySchema>;

package/monitoring/alerts/registry.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/** One event's metadata: what it means, and the zod schema for its payload. */
+export type EventMeta<Payload extends z.ZodType = z.ZodType> = {
+	description: string;
+	payload: Payload;
+};
+
+/**
+ * A flat registry of every valid event, keyed by event name. Callers declare one with
+ * `as const satisfies EventRegistry` and derive everything else from it through the helpers below,
+ * so the key union, the keys array and the runtime schema can't drift from the event list.
+ */
+export type EventRegistry = Record<string, EventMeta>;
+
+export type EventKey<R extends EventRegistry> = Extract<keyof R, string>;
+
+/**
+ * One fired event: its key plus the payload that key requires, as a union discriminated on
+ * `event`. A union rather than a per-key map because consumers need to accept "any event" as a
+ * single type and narrow on `event`; a map pushes that narrowing onto every caller.
+ */
+export type Event<R extends EventRegistry> = {
+	[K in EventKey<R>]: { event: K; payload: z.infer<R[K]['payload']> };
+}[EventKey<R>];
+
+export const eventKeys = <R extends EventRegistry>(registry: R) =>
+	Object.keys(registry) as [EventKey<R>, ...EventKey<R>[]];
+
+/**
+ * A zod union over every event in `registry`, discriminated on `event`. `extra` adds fields to
+ * every arm — the queue wire format needs an envelope field kit has no notion of.
+ *
+ * `discriminatedUnion` wants a non-empty tuple and `.map()` only ever produces a plain array, so
+ * the cast is required rather than a shortcut: zod doesn't care about tuple-vs-array at runtime,
+ * and the returned type is pinned by the caller's own annotation.
+ */
+export const eventSchema = <R extends EventRegistry>(registry: R, extra?: z.ZodRawShape) =>
+	z.discriminatedUnion(
+		'event',
+		eventKeys(registry).map((key) =>
+			z.object({ ...extra, event: z.literal(key), payload: registry[key].payload })
+		) as never
+	);

package/monitoring/gates/client.ts

@@ -0,0 +1,90 @@
+// Fleet-wide boolean flags over a GATES Workers VPC binding (see the separate `gates` repo). No
+// ambient context, no app-specific knowledge — the binding is passed in; the caller decides where
+// it comes from.
+
+export type Gate = { key: string; namespace: string; value: boolean };
+
+const FRESH_MS = 5_000; // skip a refetch within this long of the last successful read
+const STALE_MAX_MS = 60_000; // how long a failed fetch may still use the last successful read
+
+type FlagCacheEntry = { fetchedAt: number; value: boolean };
+const flagCache = new Map<string, FlagCacheEntry>(); // isolate-shared, not per-instance
+
+/** Just the shape callers depend on — a test can hand-write a fake object matching this, or use
+ *  `FakeGatesClient` from `./testing`, instead of constructing `GatesClient` with a fake binding. */
+export interface IGatesClient {
+	delete(namespace: string, key: string): Promise<void>;
+	get(namespace: string, key: string): Promise<Gate | null>;
+	getFlag(identifier: string, fallback: boolean): Promise<boolean>;
+	list(namespace: string): Promise<Gate[]>;
+	set(namespace: string, key: string, value: boolean): Promise<Gate>;
+}
+
+export class GatesClient implements IGatesClient {
+	constructor(private readonly binding: Fetcher) {}
+
+	async delete(namespace: string, key: string): Promise<void> {
+		const res = await this.binding.fetch(`http://gates${this.path(namespace, key)}`, {
+			method: 'DELETE',
+		});
+		if (!res.ok && res.status !== 404) {
+			throw new Error(`GatesClient.delete ${namespace}/${key}: ${res.status}`);
+		}
+	}
+
+	async get(namespace: string, key: string): Promise<Gate | null> {
+		const res = await this.binding.fetch(`http://gates${this.path(namespace, key)}`);
+		if (res.status === 404) return null;
+		if (!res.ok) throw new Error(`GatesClient.get ${namespace}/${key}: ${res.status}`);
+		return res.json();
+	}
+
+	/** `identifier` is `namespace/key`. Cached, never-throws boolean read: fresh cache within
+	 *  `FRESH_MS`, else refetch; on failure, reuse the last good value within `STALE_MAX_MS`, else
+	 *  `fallback`. */
+	async getFlag(identifier: string, fallback: boolean): Promise<boolean> {
+		const [namespace, key] = identifier.split('/');
+		const cached = flagCache.get(identifier);
+		const now = Date.now();
+		if (cached && now - cached.fetchedAt < FRESH_MS) return cached.value;
+
+		try {
+			const gate = await this.get(namespace, key);
+			const value = gate?.value ?? fallback;
+			flagCache.set(identifier, { fetchedAt: now, value });
+			return value;
+		} catch (e) {
+			const stillFresh = cached && now - cached.fetchedAt < STALE_MAX_MS;
+			console.warn(
+				`gates: ${identifier} unreachable, ${stillFresh ? 'using last known value' : 'no recent value, using fallback'}`,
+				{
+					error: e instanceof Error ? e.message : String(e),
+					fallback: stillFresh ? cached.value : fallback,
+				}
+			);
+			return stillFresh ? cached.value : fallback;
+		}
+	}
+
+	async list(namespace: string): Promise<Gate[]> {
+		const res = await this.binding.fetch(
+			`http://gates/v1/namespaces/${encodeURIComponent(namespace)}/gates`
+		);
+		if (!res.ok) throw new Error(`GatesClient.list ${namespace}: ${res.status}`);
+		return res.json();
+	}
+
+	async set(namespace: string, key: string, value: boolean): Promise<Gate> {
+		const res = await this.binding.fetch(`http://gates${this.path(namespace, key)}`, {
+			body: JSON.stringify({ value }),
+			headers: { 'content-type': 'application/json' },
+			method: 'PUT',
+		});
+		if (!res.ok) throw new Error(`GatesClient.set ${namespace}/${key}: ${res.status}`);
+		return res.json();
+	}
+
+	private path(namespace: string, key: string): string {
+		return `/v1/namespaces/${encodeURIComponent(namespace)}/gates/${encodeURIComponent(key)}`;
+	}
+}

package/monitoring/gates/dev.ts

@@ -0,0 +1,29 @@
+import type { Gate, IGatesClient } from './client';
+
+export class GatesDevClient implements IGatesClient {
+	private readonly store = new Map<string, Gate>();
+
+	async delete(namespace: string, key: string): Promise<void> {
+		this.store.delete(`${namespace}/${key}`);
+		console.log(`[gates:dev] delete ${namespace}/${key}`);
+	}
+
+	async get(namespace: string, key: string): Promise<Gate | null> {
+		return this.store.get(`${namespace}/${key}`) ?? null;
+	}
+
+	async getFlag(identifier: string, fallback: boolean): Promise<boolean> {
+		return this.store.get(identifier)?.value ?? fallback;
+	}
+
+	async list(namespace: string): Promise<Gate[]> {
+		return [...this.store.values()].filter((g) => g.namespace === namespace);
+	}
+
+	async set(namespace: string, key: string, value: boolean): Promise<Gate> {
+		const gate: Gate = { key, namespace, value };
+		this.store.set(`${namespace}/${key}`, gate);
+		console.log(`[gates:dev] set ${namespace}/${key} = ${value}`);
+		return gate;
+	}
+}

package/monitoring/gates/testing.ts

@@ -0,0 +1,30 @@
+import type { Gate, IGatesClient } from './client';
+
+/** In-memory `GatesClient` stand-in — real get/set/list/delete/getFlag semantics against a local
+ *  `Map` instead of a GATES Workers VPC binding, so a test can seed or read flags without a real
+ *  binding and without touching `client.ts`'s isolate-shared flag cache. */
+export class FakeGatesClient implements IGatesClient {
+	private readonly store = new Map<string, Gate>();
+
+	async delete(namespace: string, key: string): Promise<void> {
+		this.store.delete(`${namespace}/${key}`);
+	}
+
+	async get(namespace: string, key: string): Promise<Gate | null> {
+		return this.store.get(`${namespace}/${key}`) ?? null;
+	}
+
+	async getFlag(identifier: string, fallback: boolean): Promise<boolean> {
+		return this.store.get(identifier)?.value ?? fallback;
+	}
+
+	async list(namespace: string): Promise<Gate[]> {
+		return [...this.store.values()].filter((g) => g.namespace === namespace);
+	}
+
+	async set(namespace: string, key: string, value: boolean): Promise<Gate> {
+		const gate: Gate = { key, namespace, value };
+		this.store.set(`${namespace}/${key}`, gate);
+		return gate;
+	}
+}

package/monitoring/logger/client.ts

@@ -0,0 +1,66 @@
+import { captureException } from '@sentry/cloudflare';
+
+// Drizzle (and other wrappers) bury the real failure in `error.cause` — e.g. a pg error like
+// `[28P01] password authentication failed` or `[42501] permission denied`. Surface the whole
+// chain so logs show the actual cause, not just "Failed query".
+export function causeChain(error: unknown): string {
+	const parts: string[] = [];
+	let e: unknown = error;
+	for (let depth = 0; depth < 5 && e && typeof e === 'object' && 'cause' in e; depth++) {
+		e = (e as { cause: unknown }).cause;
+		if (!e || typeof e !== 'object') break;
+		const x = e as { code?: unknown; detail?: unknown; message?: unknown };
+		const code = x.code ? `[${String(x.code)}] ` : '';
+		const detail = x.detail ? ` | detail: ${String(x.detail)}` : '';
+		parts.push(`${code}${String(x.message ?? e)}${detail}`);
+	}
+	return parts.join(' <- ');
+}
+
+/** `console.error(error)`'s own serialization is lossy in Workers/CI log capture — pull
+ *  `message`/`name`/`code` (the last from node-postgres and similar driver errors) into the
+ *  logged context explicitly so they survive. `cause` walks wrapper errors (drizzle, etc) down
+ *  to the real underlying error, which otherwise never surfaces at all. */
+function errorDetails(error: unknown): Record<string, unknown> {
+	if (!(error instanceof Error)) return { message: String(error) };
+	const code = 'code' in error ? (error as { code: unknown }).code : undefined;
+	const cause = causeChain(error);
+	return {
+		message: error.message,
+		name: error.name,
+		...(code !== undefined && { code }),
+		...(cause && { cause }),
+	};
+}
+
+/** A `context.tags` key (if present) is Sentry tag data (grouping/filtering) — peeled off here so
+ *  every caller gets consistent tag/extra separation for free, rather than each host re-deriving
+ *  this split in its own wiring (see the old per-host `logger.configure` callbacks this replaced). */
+function reportToSentry(error: unknown, context?: Record<string, unknown>): void {
+	const { tags, ...extra } = context ?? {};
+	captureException(error, { extra, tags: tags as Record<string, string> | undefined });
+}
+
+/** `warn`/`error` always fire — both are reserved for genuinely abnormal conditions (not routine
+ *  per-request narration), so there's nothing to gate: volume stays near-zero in normal operation
+ *  and only rises during a real incident, which is exactly when more visibility is wanted, not
+ *  less. `debug` is for active, temporary investigation only — add a call while chasing a
+ *  specific bug, delete it once resolved; it's not a permanent narration/tracing tool, so it gets
+ *  no gate either. */
+export class LoggerClient {
+	debug(message: string, context?: Record<string, unknown>): void {
+		console.debug(`[DEBUG] ${message}`, ...(context ? [context] : []));
+	}
+
+	error(error: unknown, context?: Record<string, unknown>): void {
+		console.error('[ERROR]', error, { ...errorDetails(error), ...context });
+		reportToSentry(error, context);
+	}
+
+	warn(message: string, context?: Record<string, unknown>): void {
+		console.warn(`[WARN] ${message}`, ...(context ? [context] : []));
+	}
+}
+
+/** Process-wide logger singleton — Sentry reporting is self-contained, nothing to wire per host. */
+export const logger = new LoggerClient();