cvx-kit 0.0.1

package/src/components/foundation/modules/command/command.ts

@@ -0,0 +1,154 @@
+export type Parseable<Output> = Readonly<{ parse: (value: unknown) => Output }>
+
+export type CommandRegistry = Readonly<Record<string, CommandDefinition>>
+
+export type CommandInput<
+	Registry extends CommandRegistry,
+	Key extends Operation<Registry>,
+> = Parsed<Registry[Key]['command']>
+
+export type CommandResult<
+	Registry extends CommandRegistry,
+	Key extends Operation<Registry>,
+> = Parsed<Registry[Key]['result']>
+
+export type CommandExecution<
+	Context,
+	Registry extends CommandRegistry,
+	Key extends Operation<Registry>,
+> = Readonly<{
+	context: Context
+	operation: Key
+	definition: Registry[Key]
+	command: CommandInput<Registry, Key>
+	parseResult: (value: unknown) => CommandResult<Registry, Key>
+	run: () => Promise<CommandResult<Registry, Key>>
+}>
+
+type CommandDefinition = Readonly<{
+	command: Parseable<unknown>
+	result: Parseable<unknown>
+}>
+
+type Operation<Registry extends CommandRegistry> = Extract<
+	keyof Registry,
+	string
+>
+type Parsed<Schema> = Schema extends Parseable<infer Output> ? Output : never
+type MaybePromise<Value> = Value | Promise<Value>
+type Execute<Context, Registry extends CommandRegistry> = <
+	Key extends Operation<Registry>,
+>(
+	execution: CommandExecution<Context, Registry, Key>,
+) => Promise<CommandResult<Registry, Key>>
+
+type FixedExecutor<
+	Context,
+	Registry extends CommandRegistry,
+	Key extends Operation<Registry>,
+> = Readonly<{
+	operation: Key
+	handler: (
+		context: Context,
+		command: CommandInput<Registry, Key>,
+	) => MaybePromise<CommandResult<Registry, Key>>
+}>
+
+type DynamicExecutor<
+	Context,
+	Registry extends CommandRegistry,
+	Dispatcher,
+	Key extends Operation<Registry>,
+> = Readonly<{
+	dispatcher: Parseable<Dispatcher>
+	select: (dispatcher: Dispatcher) => Key
+	handler: (
+		context: Context,
+		command: CommandInput<Registry, Key>,
+	) => MaybePromise<CommandResult<Registry, Key>>
+}>
+
+class CommandConfigurationError extends Error {
+	readonly code = 'COMMAND_OPERATION_NOT_CONFIGURED'
+	readonly name = 'CommandConfigurationError'
+
+	constructor() {
+		super('The selected command operation is not configured')
+	}
+}
+
+/** Generic command kernel. Host policy is injected by the owning domain. */
+export class Command<Context, const Registry extends CommandRegistry> {
+	readonly #operations: Registry
+	readonly #execute: Execute<Context, Registry>
+
+	constructor(configuration: {
+		readonly operations: Registry
+		readonly execute: Execute<Context, Registry>
+	}) {
+		this.#operations = configuration.operations
+		this.#execute = configuration.execute
+	}
+
+	exec<const Key extends Operation<Registry>>(
+		executor: FixedExecutor<Context, Registry, Key>,
+	): (
+		context: Context,
+		command: CommandInput<Registry, Key>,
+	) => Promise<CommandResult<Registry, Key>>
+	exec<Dispatcher, const Key extends Operation<Registry>>(
+		executor: DynamicExecutor<Context, Registry, Dispatcher, Key>,
+	): (
+		context: Context,
+		command: Dispatcher,
+	) => Promise<CommandResult<Registry, Key>>
+	exec(
+		executor:
+			| FixedExecutor<Context, Registry, Operation<Registry>>
+			| DynamicExecutor<Context, Registry, unknown, Operation<Registry>>,
+	) {
+		return async (context: Context, value: unknown) => {
+			const selected =
+				'operation' in executor
+					? { operation: executor.operation, value }
+					: (() => {
+							const dispatcher = executor.dispatcher.parse(value)
+							return {
+								operation: executor.select(dispatcher),
+								value: dispatcher,
+							}
+						})()
+			if (
+				!Object.prototype.hasOwnProperty.call(
+					this.#operations,
+					selected.operation,
+				)
+			) {
+				throw new CommandConfigurationError()
+			}
+			const operation = selected.operation as Operation<Registry>
+			const definition = this.#operations[operation]
+			const command = definition.command.parse(selected.value) as CommandInput<
+				Registry,
+				Operation<Registry>
+			>
+			const parseResult = (result: unknown) =>
+				definition.result.parse(result) as CommandResult<
+					Registry,
+					Operation<Registry>
+				>
+			const handler = executor.handler as (
+				context: Context,
+				command: CommandInput<Registry, Operation<Registry>>,
+			) => MaybePromise<CommandResult<Registry, Operation<Registry>>>
+			return this.#execute({
+				context,
+				operation,
+				definition,
+				command,
+				parseResult,
+				run: async () => parseResult(await handler(context, command)),
+			})
+		}
+	}
+}

package/src/components/foundation/modules/observability/__tests__/observability.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from 'vite-plus/test'
+
+import { Observability } from '../observability'
+
+describe('Foundation Observability', () => {
+	it('emits bounded semantic metadata without payloads', async () => {
+		const emit = vi.fn()
+		const observability = new Observability({
+			enabled: true,
+			clock: tickingClock(),
+			classifyError: () => ({
+				outcome: 'failed',
+				errorCode: 'UNEXPECTED_ERROR',
+			}),
+			emit,
+		})
+
+		await expect(
+			observability.observe(
+				{ operation: 'assignments.claim', classification: 'writer' },
+				() => 'claimed',
+			),
+		).resolves.toBe('claimed')
+		expect(emit).toHaveBeenCalledWith({
+			operation: 'assignments.claim',
+			classification: 'writer',
+			outcome: 'completed',
+			durationMs: 5,
+		})
+	})
+
+	it('classifies denial and preserves the original failure', async () => {
+		const emit = vi.fn()
+		const original = new Error('sensitive reason')
+		const observability = new Observability({
+			enabled: true,
+			clock: tickingClock(),
+			classifyError: () => ({ outcome: 'denied', errorCode: 'FORBIDDEN' }),
+			emit,
+		})
+
+		await expect(
+			observability.observe(
+				{ operation: 'assignments.assign', classification: 'admin' },
+				() => {
+					throw original
+				},
+			),
+		).rejects.toBe(original)
+		expect(JSON.stringify(emit.mock.calls)).not.toContain('sensitive reason')
+	})
+
+	it('drops invalid semantic fields and contains emitter failures', async () => {
+		const emit = vi.fn(() => {
+			throw new Error('telemetry unavailable')
+		})
+		const observability = new Observability({
+			enabled: true,
+			classifyError: () => ({
+				outcome: 'failed',
+				errorCode: 'UNEXPECTED_ERROR',
+			}),
+			emit,
+		})
+
+		await expect(
+			observability.observe(
+				{ operation: 'contains secret whitespace', classification: 'writer' },
+				() => 'unchanged',
+			),
+		).resolves.toBe('unchanged')
+		expect(emit).not.toHaveBeenCalled()
+	})
+})
+
+function tickingClock(): () => number {
+	let now = 10
+	return () => (now += 5)
+}

package/src/components/foundation/modules/observability/observability.ts

@@ -0,0 +1,95 @@
+export type CommandObservation = Readonly<{
+	operation: string
+	classification: string
+	outcome: 'completed' | 'denied' | 'failed'
+	errorCode?: string
+	durationMs: number
+}>
+
+export type ObservabilityOptions = Readonly<{
+	enabled?: boolean | (() => boolean)
+	classifyError: (error: unknown) => Readonly<{
+		outcome: 'denied' | 'failed'
+		errorCode: string
+	}>
+	emit?: (observation: CommandObservation) => void
+	clock?: () => number
+}>
+
+const identifier = /^[A-Za-z][A-Za-z0-9_.-]{0,159}$/
+const errorCode = /^[A-Z][A-Z0-9_]{0,95}$/
+
+/** Payload-free command telemetry that cannot change command behavior. */
+export class Observability {
+	readonly #options: ObservabilityOptions
+
+	constructor(options: ObservabilityOptions) {
+		this.#options = options
+	}
+
+	async observe<Result>(
+		activation: Readonly<{ operation: string; classification: string }>,
+		execute: () => Result | Promise<Result>,
+	): Promise<Result> {
+		const started = this.#now()
+		try {
+			const result = await execute()
+			this.#emit({
+				...activation,
+				outcome: 'completed',
+				durationMs: this.#duration(started),
+			})
+			return result
+		} catch (error) {
+			try {
+				this.#emit({
+					...activation,
+					...this.#options.classifyError(error),
+					durationMs: this.#duration(started),
+				})
+			} catch {
+				// Preserve the original command failure when telemetry fails.
+			}
+			throw error
+		}
+	}
+
+	#emit(observation: CommandObservation): void {
+		try {
+			const enabled =
+				typeof this.#options.enabled === 'function'
+					? this.#options.enabled()
+					: this.#options.enabled
+			if (
+				enabled !== true ||
+				!identifier.test(observation.operation) ||
+				!identifier.test(observation.classification) ||
+				(observation.errorCode !== undefined &&
+					!errorCode.test(observation.errorCode))
+			) {
+				return
+			}
+			if (this.#options.emit) {
+				this.#options.emit(Object.freeze(observation))
+				return
+			}
+			console.info(
+				JSON.stringify({ event: 'command.execution', ...observation }),
+			)
+		} catch {
+			// Observability is intentionally behaviorally inert.
+		}
+	}
+
+	#now(): number {
+		try {
+			return this.#options.clock?.() ?? Date.now()
+		} catch {
+			return Date.now()
+		}
+	}
+
+	#duration(started: number): number {
+		return Math.max(0, Math.min(600_000, this.#now() - started))
+	}
+}

package/src/components/foundation/modules/query/__tests__/query.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { Query } from '../query'
+
+describe('Foundation Query', () => {
+	it('runs injected policy before its handler', async () => {
+		const order: string[] = []
+		const query = new Query({
+			defaults: { classification: 'authenticated' as const },
+			execute: async (execution) => {
+				order.push(`policy:${execution.metadata.classification}`)
+				return execution.run()
+			},
+		})
+		const execute = query.exec({
+			handler: (_context: unknown, id: string) => {
+				order.push('handler')
+				return id
+			},
+		})
+
+		await expect(execute({}, 'assignment-1')).resolves.toBe('assignment-1')
+		expect(order).toEqual(['policy:authenticated', 'handler'])
+	})
+})

package/src/components/foundation/modules/query/query.ts

@@ -0,0 +1,47 @@
+export type QueryExecution<Context, Metadata, Result> = Readonly<{
+	context: Context
+	metadata: Metadata
+	run: () => Promise<Result>
+}>
+
+type MaybePromise<Value> = Value | Promise<Value>
+
+/** Generic query kernel. Authorization remains an injected host policy. */
+export class Query<Context, Defaults extends object> {
+	readonly #defaults: Defaults
+	readonly #execute: <Metadata extends object, Result>(
+		execution: QueryExecution<Context, Defaults & Metadata, Result>,
+	) => Promise<Result>
+
+	constructor(configuration: {
+		readonly defaults: Defaults
+		readonly execute: <Metadata extends object, Result>(
+			execution: QueryExecution<Context, Defaults & Metadata, Result>,
+		) => Promise<Result>
+	}) {
+		this.#defaults = configuration.defaults
+		this.#execute = configuration.execute
+	}
+
+	exec<
+		Arguments extends readonly unknown[],
+		Result,
+		Metadata extends object = object,
+	>(executor: {
+		readonly metadata?: Metadata
+		readonly handler: (
+			context: Context,
+			...args: Arguments
+		) => MaybePromise<Result>
+	}): (context: Context, ...args: Arguments) => Promise<Result> {
+		return (context, ...args) =>
+			this.#execute({
+				context,
+				metadata: {
+					...this.#defaults,
+					...(executor.metadata ?? ({} as Metadata)),
+				},
+				run: async () => executor.handler(context, ...args),
+			})
+	}
+}

package/src/components/foundation/result.ts

@@ -0,0 +1,77 @@
+import type { TransactionMetrics } from 'convex/server'
+
+export type TransactionMetricsContext = Readonly<{
+	meta: Readonly<{
+		getTransactionMetrics: () => Promise<TransactionMetrics>
+	}>
+}>
+
+export type Result<Value, Failure> =
+	| Readonly<{ ok: true; value: Value }>
+	| Readonly<{ ok: false; error: Failure }>
+
+export type ResultBoundary<Failure> = Readonly<{
+	ok: <Value>(value: Value) => Result<Value, Failure>
+	handledError: <Value = never>(failure: Failure) => Result<Value, Failure>
+	dataOf: (error: unknown) => Failure | undefined
+}>
+
+const metricNames = [
+	'bytesRead',
+	'bytesWritten',
+	'databaseQueries',
+	'documentsRead',
+	'documentsWritten',
+	'functionsScheduled',
+	'scheduledFunctionArgsBytes',
+] as const satisfies readonly (keyof TransactionMetrics)[]
+
+const effectMetricNames = [
+	'bytesWritten',
+	'documentsWritten',
+	'functionsScheduled',
+	'scheduledFunctionArgsBytes',
+] as const satisfies readonly (keyof TransactionMetrics)[]
+
+/** Return handled failures only before effects; otherwise rethrow for rollback. */
+export async function executeResultBoundary<Value, Failure>(
+	ctx: TransactionMetricsContext,
+	operation: () => Promise<Value>,
+	boundary: ResultBoundary<Failure>,
+): Promise<Result<Value, Failure>> {
+	try {
+		return boundary.ok(await operation())
+	} catch (error) {
+		const handled = boundary.dataOf(error)
+		if (handled === undefined) throw error
+		try {
+			if (hasEffects(await ctx.meta.getTransactionMetrics())) throw error
+		} catch {
+			throw error
+		}
+		return boundary.handledError(handled)
+	}
+}
+
+export function projectResult<Value, Failure>(
+	result: Result<Value, Failure>,
+	projectFailure: (failure: Failure) => never,
+): Value {
+	return result.ok ? result.value : projectFailure(result.error)
+}
+
+function hasEffects(metrics: TransactionMetrics): boolean {
+	for (const name of metricNames) {
+		const metric = metrics[name]
+		if (
+			!metric ||
+			!Number.isFinite(metric.used) ||
+			metric.used < 0 ||
+			!Number.isFinite(metric.remaining) ||
+			metric.remaining < 0
+		) {
+			throw new Error('Unreadable transaction metrics')
+		}
+	}
+	return effectMetricNames.some((name) => metrics[name].used > 0)
+}

package/src/components/foundation/schema.ts

@@ -0,0 +1,4 @@
+import { defineSchema } from 'convex/server'
+
+/** Foundation is a capability-free in-process kernel and owns no business data. */
+export default defineSchema({})

package/src/components/foundation/telemetry.ts

@@ -0,0 +1,23 @@
+type SemanticValue = string | number | boolean
+
+const semanticToken = /^[A-Za-z][A-Za-z0-9_.-]{0,159}$/
+
+/** Emit bounded semantic fields only; free-form payloads and identifiers drop. */
+export function emitSemanticEvent(
+	event: string,
+	fields: Readonly<Record<string, SemanticValue | undefined>> = {},
+): void {
+	try {
+		if (!semanticToken.test(event)) return
+		const safe: Record<string, SemanticValue> = { event }
+		for (const [key, value] of Object.entries(fields)) {
+			if (!semanticToken.test(key) || value === undefined) continue
+			if (typeof value === 'string' && !semanticToken.test(value)) continue
+			if (typeof value === 'number' && !Number.isFinite(value)) continue
+			safe[key] = value
+		}
+		console.info(JSON.stringify(safe))
+	} catch {
+		// Telemetry must never change command behavior.
+	}
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+/** Structured application error carried across Convex function boundaries. */
+export class KitError extends Error {
+	readonly code: string
+
+	constructor(input: { code: string; message?: string }) {
+		super(input.message ?? input.code)
+		this.name = 'KitError'
+		this.code = input.code
+	}
+}
+
+/**
+ * Injection seam for host error policy. Hosts with their own error taxonomy
+ * (e.g. an App.errors singleton) adapt it to this shape; everyone else uses
+ * the default factory below.
+ */
+export type ErrorFactory = {
+	throw(input: { code: string; message?: string }): never
+}
+
+export const defaultErrors: ErrorFactory = {
+	throw(input) {
+		throw new KitError(input)
+	},
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+export {
+	defaultErrors,
+	KitError,
+	type ErrorFactory,
+} from './errors'
+export {
+	jsonSafeZid,
+	TIMESTAMP_FIELDS,
+	zodTable,
+	zodVariantTable,
+	type TableBoundaryOptions,
+} from './zod-table'
+export {
+	createAuthFunctions,
+	createInclude,
+	defaultRoleMap,
+	type Actor,
+	type AuthBundle,
+	type AuthFunctionsConfig,
+	type DefaultRole,
+	type Include,
+	type IncludedQuery,
+} from './auth'
+export {
+	appendOnly,
+	createTriggers,
+	noDelete,
+	timestamps,
+	Triggers,
+	type Change,
+	type Trigger,
+} from './triggers'
+export {
+	Foundation,
+	type ApplicationCommand,
+	type AuditedOperation,
+	type AuditedRegistry,
+	type AuditEntryInput,
+	type AuditWriter,
+	type FoundationOptions,
+} from './components/foundation/client'

package/src/test.ts

@@ -0,0 +1,36 @@
+/**
+ * Test helpers for consumers, following the official component template:
+ * register the kit's components on a convex-test instance so host-app tests
+ * run against them in-memory. Requires a vitest-compatible runner
+ * (import.meta.glob), which is why this export ships as source.
+ */
+import approvalsSchema from './components/approvals/schema'
+import foundationSchema from './components/foundation/schema'
+
+const foundationModules = import.meta.glob(
+	'./components/foundation/**/!(*.test).ts',
+)
+const approvalsModules = import.meta.glob(
+	'./components/approvals/**/!(*.test).ts',
+)
+
+type RegistersComponents = {
+	registerComponent: (
+		name: string,
+		schema: unknown,
+		modules: Record<string, () => Promise<unknown>>,
+	) => void
+}
+
+/** Registers the foundation component under its default install name. */
+export function registerFoundation(
+	t: RegistersComponents,
+	name = 'foundation',
+) {
+	t.registerComponent(name, foundationSchema, foundationModules)
+}
+
+/** Registers the approvals component under its default install name. */
+export function registerApprovals(t: RegistersComponents, name = 'approvals') {
+	t.registerComponent(name, approvalsSchema, approvalsModules)
+}