@db3.ai/app 0.1.0-beta.1

package/src/flows/models/FlowRun.ts

@@ -0,0 +1,164 @@
+import { ActiveRecord, type FieldBuilder } from '../../db';
+import type { EntityRef } from '../../db/fields/LinkField';
+import { FLOW_REPLAY_DEFINITION, FLOW_RUN_STATUS, type FlowReplayDefinition, type FlowRunStatus } from '../constants';
+import type { FlowErrorSnapshot, FlowExecutionDefinition, FlowValues } from '../contracts';
+
+/**
+ * Durable invocation of one immutable flow definition snapshot.
+ */
+export class FlowRun extends ActiveRecord {
+	static override table = 'flow_runs';
+	static override primaryKey = 'id';
+	static override labelFields = ['flowName', 'status'];
+	static override comment = 'Durable flow invocation and immutable definition snapshot used for observability and replay.';
+
+	/**
+	 * Defines persisted flow-run identity, snapshot, lifecycle, and result fields.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Flow run field definitions.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable flow run ULID.',
+			}),
+
+			flowId: field.string({
+				column: 'flow_id',
+				required: true,
+				length: 26,
+				maxLength: 26,
+				index: true,
+				comment: 'Stable ULID from the source flow definition.',
+			}),
+
+			flowName: field.string({
+				column: 'flow_name',
+				required: true,
+				length: 255,
+				maxLength: 255,
+				comment: 'Flow name captured when this run was created.',
+			}),
+
+			status: field.choice({
+				required: true,
+				choices: Object.values(FLOW_RUN_STATUS),
+				default: FLOW_RUN_STATUS.queued,
+				length: 20,
+				maxLength: 20,
+				index: true,
+				comment: 'Current durable lifecycle state for the flow invocation.',
+			}),
+
+			replayDefinition: field.choice({
+				column: 'replay_definition',
+				required: false,
+				choices: Object.values(FLOW_REPLAY_DEFINITION),
+				length: 20,
+				maxLength: 20,
+				comment: 'Definition source selected when this run replays an earlier invocation.',
+			}),
+
+			definitionRevision: field.string({
+				column: 'definition_revision',
+				required: true,
+				length: 64,
+				maxLength: 64,
+				index: true,
+				comment: 'SHA-256 revision of the source definition used for this run.',
+			}),
+
+			definitionSnapshot: field.jsonLongText<FlowExecutionDefinition>({
+				column: 'definition_snapshot',
+				required: true,
+				comment: 'Immutable normalized flow definition executed by this run.',
+			}),
+
+			input: field.jsonLongText<FlowValues>({
+				required: true,
+				comment: 'Validated public input supplied to the root block.',
+			}),
+
+			output: field.jsonLongText<FlowValues>({
+				required: false,
+				comment: 'Validated public output produced by the terminal block.',
+			}),
+
+			error: field.jsonLongText<FlowErrorSnapshot>({
+				required: false,
+				comment: 'Structured terminal error when the run fails.',
+			}),
+
+			replayOf: field.link(() => FlowRun, {
+				column: 'replay_of_run_id',
+				required: false,
+				onDelete: 'SET NULL',
+				index: true,
+				comment: 'Earlier flow run replayed by this invocation, when applicable.',
+			}),
+
+			parentRun: field.link(() => FlowRun, {
+				column: 'parent_run_id',
+				required: false,
+				onDelete: 'CASCADE',
+				index: true,
+				comment: 'Parent flow run waiting for this nested invocation.',
+			}),
+
+			parentBlockId: field.string({
+				column: 'parent_block_id',
+				required: false,
+				length: 26,
+				maxLength: 26,
+				index: true,
+				comment: 'Flow-backed block occurrence in the parent run.',
+			}),
+
+			startedAt: field.timestamp({
+				column: 'started_at',
+				precision: 3,
+				index: true,
+				comment: 'Time the first block began execution.',
+			}),
+
+			completedAt: field.timestamp({
+				column: 'completed_at',
+				precision: 3,
+				index: true,
+				comment: 'Time the run completed or failed.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				precision: 3,
+				auto: 'create',
+				index: true,
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				precision: 3,
+				auto: 'update',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare flowId: string | null;
+	declare flowName: string | null;
+	declare status: FlowRunStatus | null;
+	declare replayDefinition: FlowReplayDefinition | null;
+	declare definitionRevision: string | null;
+	declare definitionSnapshot: FlowExecutionDefinition | null;
+	declare input: FlowValues | null;
+	declare output: FlowValues | null;
+	declare error: FlowErrorSnapshot | null;
+	declare replayOf: EntityRef<FlowRun> | null;
+	declare parentRun: EntityRef<FlowRun> | null;
+	declare parentBlockId: string | null;
+	declare startedAt: Date | null;
+	declare completedAt: Date | null;
+	declare createdAt: Date | null;
+	declare updatedAt: Date | null;
+}

package/src/flows/models/FlowRunEvent.ts

@@ -0,0 +1,108 @@
+import { ActiveRecord, type FieldBuilder } from '../../db';
+import type { EntityRef } from '../../db/fields/LinkField';
+import { FLOW_RUN_EVENT_TYPE, type FlowRunEventType } from '../constants';
+import type { FlowLogLevel, FlowValue } from '../contracts';
+import { FlowRun } from './FlowRun';
+import { FlowStepRun } from './FlowStepRun';
+
+const FLOW_RUN_EVENTS_SEQUENCE_UNIQUE = 'flow_run_events_run_sequence_unique';
+
+/**
+ * Ordered durable lifecycle or log event emitted during a flow run.
+ */
+export class FlowRunEvent extends ActiveRecord {
+	static override table = 'flow_run_events';
+	static override primaryKey = 'id';
+	static override labelFields = ['type', 'message'];
+	static override comment = 'Ordered flow lifecycle and block log entries used by run timelines.';
+
+	/**
+	 * Defines ordered flow event fields and run-local sequence constraints.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Flow run event field definitions.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable flow run event ULID.',
+			}),
+
+			run: field.link(() => FlowRun, {
+				column: 'run_id',
+				required: true,
+				onDelete: 'CASCADE',
+				index: true,
+				indexes: [
+					{
+						name: FLOW_RUN_EVENTS_SEQUENCE_UNIQUE,
+						columns: ['run_id', 'sequence'],
+						unique: true,
+					},
+				],
+				comment: 'Flow run that owns this event.',
+			}),
+
+			stepRun: field.link(() => FlowStepRun, {
+				column: 'step_run_id',
+				required: false,
+				onDelete: 'CASCADE',
+				index: true,
+				comment: 'Block step associated with this event, when applicable.',
+			}),
+
+			sequence: field.integer({
+				required: true,
+				unsigned: true,
+				min: 0,
+				comment: 'Monotonic zero-based ordering within the flow run.',
+			}),
+
+			type: field.choice({
+				required: true,
+				choices: Object.values(FLOW_RUN_EVENT_TYPE),
+				length: 40,
+				maxLength: 40,
+				index: true,
+				comment: 'Lifecycle or log event type.',
+			}),
+
+			level: field.choice({
+				required: false,
+				choices: ['debug', 'info', 'warning', 'error'],
+				length: 20,
+				maxLength: 20,
+				comment: 'Optional block log severity.',
+			}),
+
+			message: field.string({
+				required: true,
+				length: 1024,
+				maxLength: 1024,
+				comment: 'Human-readable timeline or diagnostic message.',
+			}),
+
+			data: field.jsonLongText<FlowValue>({
+				required: false,
+				comment: 'Optional structured event or diagnostic data.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				precision: 3,
+				auto: 'create',
+				index: true,
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare run: EntityRef<FlowRun>;
+	declare stepRun: EntityRef<FlowStepRun> | null;
+	declare sequence: number | null;
+	declare type: FlowRunEventType | null;
+	declare level: FlowLogLevel | null;
+	declare message: string | null;
+	declare data: FlowValue | null;
+	declare createdAt: Date | null;
+}

package/src/flows/models/FlowStepRun.ts

@@ -0,0 +1,176 @@
+import { ActiveRecord, type FieldBuilder } from '../../db';
+import type { EntityRef } from '../../db/fields/LinkField';
+import { FLOW_STEP_STATUS, type FlowStepStatus } from '../constants';
+import type { FlowErrorSnapshot, FlowValues } from '../contracts';
+import { FlowRun } from './FlowRun';
+
+const FLOW_STEP_RUN_SEQUENCE_UNIQUE = 'flow_step_runs_run_sequence_unique';
+const FLOW_STEP_RUN_BLOCK_UNIQUE = 'flow_step_runs_run_block_unique';
+
+/**
+ * Durable execution state for one block occurrence within a flow run.
+ */
+export class FlowStepRun extends ActiveRecord {
+	static override table = 'flow_step_runs';
+	static override primaryKey = 'id';
+	static override labelFields = ['blockName', 'status'];
+	static override comment = 'Per-block flow execution input, output, error, queue identity, and timing.';
+
+	/**
+	 * Defines the durable per-block execution schema.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Flow step-run field definitions.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable flow step-run ULID.',
+			}),
+
+			run: field.link(() => FlowRun, {
+				column: 'run_id',
+				required: true,
+				onDelete: 'CASCADE',
+				index: true,
+				indexes: [
+					{
+						name: FLOW_STEP_RUN_SEQUENCE_UNIQUE,
+						columns: ['run_id', 'sequence'],
+						unique: true,
+					},
+					{
+						name: FLOW_STEP_RUN_BLOCK_UNIQUE,
+						columns: ['run_id', 'block_id'],
+						unique: true,
+					},
+				],
+				comment: 'Flow run that owns this block execution.',
+			}),
+
+			blockId: field.string({
+				column: 'block_id',
+				required: true,
+				length: 26,
+				maxLength: 26,
+				comment: 'Stable block occurrence ULID from the definition snapshot.',
+			}),
+
+			blockType: field.string({
+				column: 'block_type',
+				required: true,
+				length: 160,
+				maxLength: 160,
+				index: true,
+				comment: 'Registered executable block type used for this step.',
+			}),
+
+			blockName: field.string({
+				column: 'block_name',
+				required: true,
+				length: 255,
+				maxLength: 255,
+				comment: 'Block instance or type name captured for run history.',
+			}),
+
+			sequence: field.integer({
+				required: true,
+				unsigned: true,
+				min: 0,
+				comment: 'Zero-based position in the compiled sequential plan.',
+			}),
+
+			status: field.choice({
+				required: true,
+				choices: Object.values(FLOW_STEP_STATUS),
+				default: FLOW_STEP_STATUS.pending,
+				length: 20,
+				maxLength: 20,
+				index: true,
+				comment: 'Current durable lifecycle state for this block execution.',
+			}),
+
+			attempt: field.integer({
+				required: true,
+				unsigned: true,
+				min: 0,
+				default: 0,
+				comment: 'Most recent queue attempt observed for this step.',
+			}),
+
+			queueJobId: field.string({
+				column: 'queue_job_id',
+				required: false,
+				length: 255,
+				maxLength: 255,
+				index: true,
+				comment: 'Driver-owned queue job id for the current step dispatch.',
+			}),
+
+			nestedRun: field.link(() => FlowRun, {
+				column: 'nested_run_id',
+				required: false,
+				onDelete: 'SET NULL',
+				index: true,
+				comment: 'Child flow run delegated to by this flow-backed block.',
+			}),
+
+			input: field.jsonLongText<FlowValues>({
+				required: false,
+				comment: 'Validated values supplied to the block function.',
+			}),
+
+			output: field.jsonLongText<FlowValues>({
+				required: false,
+				comment: 'Validated values returned by the block function.',
+			}),
+
+			error: field.jsonLongText<FlowErrorSnapshot>({
+				required: false,
+				comment: 'Structured error from the most recent failed attempt.',
+			}),
+
+			startedAt: field.timestamp({
+				column: 'started_at',
+				precision: 3,
+				comment: 'Time the current or successful attempt began.',
+			}),
+
+			completedAt: field.timestamp({
+				column: 'completed_at',
+				precision: 3,
+				comment: 'Time the step completed or terminally failed.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				precision: 3,
+				auto: 'create',
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				precision: 3,
+				auto: 'update',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare run: EntityRef<FlowRun>;
+	declare blockId: string | null;
+	declare blockType: string | null;
+	declare blockName: string | null;
+	declare sequence: number | null;
+	declare status: FlowStepStatus | null;
+	declare attempt: number | null;
+	declare queueJobId: string | null;
+	declare nestedRun: EntityRef<FlowRun> | null;
+	declare input: FlowValues | null;
+	declare output: FlowValues | null;
+	declare error: FlowErrorSnapshot | null;
+	declare startedAt: Date | null;
+	declare completedAt: Date | null;
+	declare createdAt: Date | null;
+	declare updatedAt: Date | null;
+}

package/src/flows/models/index.ts

@@ -0,0 +1,16 @@
+export * from './FlowRun';
+export * from './FlowRunEvent';
+export * from './FlowStepRun';
+
+import { FlowRun } from './FlowRun';
+import { FlowRunEvent } from './FlowRunEvent';
+import { FlowStepRun } from './FlowStepRun';
+
+/**
+ * Framework models an application installs when enabling durable flow runs.
+ */
+export const FLOW_MODELS = [
+	FlowRun,
+	FlowStepRun,
+	FlowRunEvent,
+] as const;

package/src/index.ts

@@ -0,0 +1,40 @@
+export {
+	App,
+	type AppOptions,
+} from './server';
+export {
+	RequestContext,
+	type RequestContextValues,
+} from './server';
+export * from './cache';
+export * from './config';
+export * from './events';
+export * from './logging';
+export * from './media';
+export * from './security';
+export * from './serialization';
+export * from './url';
+export * from './validation';
+
+export interface AppManifest {
+	id: string;
+	name: string;
+	version: string;
+	description?: string;
+	icon?: string;
+	entry?: string;
+	adminPath?: string;
+	capabilities?: string[];
+}
+
+export interface AppDefinition<TManifest extends AppManifest = AppManifest> {
+	manifest: TManifest;
+}
+
+export function defineApp<TManifest extends AppManifest>(
+	manifest: TManifest,
+): AppDefinition<TManifest> {
+	return {
+		manifest,
+	};
+}

package/src/logging/Log.ts

@@ -0,0 +1,100 @@
+import type { ChildLoggerOptions } from 'pino';
+
+import { PinoLoggerDriver } from './drivers/PinoLoggerDriver';
+import type * as logging from './contracts';
+
+/**
+ * Application logging service exposed as `app().log`.
+ *
+ * Pino supplies the default driver while this service owns framework discovery
+ * and lifecycle. Applications may inject a compatible driver in tests.
+ *
+ * @example
+ * app().log.info({ websiteId }, 'Website crawl started');
+ */
+export class Log implements logging.Logger {
+	readonly #driver: logging.LoggerDriver;
+
+	/**
+	 * Creates the application logger from explicit options or the Pino driver.
+	 *
+	 * @param options - Logging level, destinations, context, and driver overrides.
+	 */
+	constructor(options: logging.LoggingOptions = {}) {
+		this.#driver = options.driver ?? new PinoLoggerDriver(options);
+	}
+
+	/** Returns the current trace function, respecting runtime level changes. */
+	get trace(): logging.Logger['trace'] { return this.#driver.logger.trace.bind(this.#driver.logger); }
+
+	/** Returns the current debug function, respecting runtime level changes. */
+	get debug(): logging.Logger['debug'] { return this.#driver.logger.debug.bind(this.#driver.logger); }
+
+	/** Returns the current info function, respecting runtime level changes. */
+	get info(): logging.Logger['info'] { return this.#driver.logger.info.bind(this.#driver.logger); }
+
+	/** Returns the current warning function, respecting runtime level changes. */
+	get warn(): logging.Logger['warn'] { return this.#driver.logger.warn.bind(this.#driver.logger); }
+
+	/** Returns the current error function, respecting runtime level changes. */
+	get error(): logging.Logger['error'] { return this.#driver.logger.error.bind(this.#driver.logger); }
+
+	/** Returns the current fatal function, respecting runtime level changes. */
+	get fatal(): logging.Logger['fatal'] { return this.#driver.logger.fatal.bind(this.#driver.logger); }
+
+	/** Returns the driver's non-emitting log function. */
+	get silent(): logging.Logger['silent'] { return this.#driver.logger.silent.bind(this.#driver.logger); }
+
+	/**
+	 * Returns the minimum severity currently emitted by the driver.
+	 */
+	get level(): string {
+		return this.#driver.logger.level;
+	}
+
+	/**
+	 * Changes the minimum emitted severity at runtime.
+	 *
+	 * @param level - Pino-compatible log level.
+	 */
+	set level(level: string) {
+		this.#driver.logger.level = level;
+	}
+
+	/**
+	 * Returns the underlying compatible logger for framework integrations.
+	 *
+	 * @returns Driver logger accepted by Fastify and worker adapters.
+	 */
+	get logger(): logging.Logger {
+		return this.#driver.logger;
+	}
+
+	/**
+	 * Creates a context-bearing child logger.
+	 *
+	 * @param bindings - Stable structured fields for subsequent records.
+	 * @param options - Optional Pino child logger overrides.
+	 * @returns Child logger sharing the configured destinations.
+	 */
+	child(
+		bindings: logging.LogBindings,
+		options?: ChildLoggerOptions,
+	): logging.Logger {
+		return this.#driver.logger.child(bindings, options);
+	}
+
+	/**
+	 * Waits for accepted records to reach their configured destination.
+	 */
+	async flush(): Promise<void> {
+		await this.#driver.flush();
+	}
+
+	/**
+	 * Flushes records and releases transport resources.
+	 */
+	async close(): Promise<void> {
+		await this.#driver.close();
+	}
+}