@db3.ai/app 0.1.0-beta.1

package/src/scheduler/contracts/SchedulerWorker.ts

@@ -0,0 +1,23 @@
+import type { SchedulerLogger } from './Scheduler';
+
+/**
+ * Abort-aware sleep function used by the long-running scheduler worker.
+ */
+export type SchedulerSleep = (
+	delayMs: number,
+	signal: AbortSignal,
+) => Promise<void>;
+
+/**
+ * Runtime dependencies and logging overrides for SchedulerWorker.
+ */
+export interface SchedulerWorkerOptions {
+	/** Clock used to align and evaluate scheduler ticks. */
+	now?: () => Date;
+	/** Abort-aware sleeper used between minute boundaries. */
+	sleep?: SchedulerSleep;
+	/** Scheduler progress and error logger. */
+	logger?: SchedulerLogger;
+	/** Duration that triggers a slow-tick warning. */
+	slowTickWarningMs?: number;
+}

package/src/scheduler/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './Scheduler';
+export * from './SchedulerConsole';
+export * from './SchedulerWorker';

package/src/scheduler/examples/RecoverableSummaryJob.ts

@@ -0,0 +1,18 @@
+import { QueueableJob } from '@db3.ai/app/queue';
+import { app } from '@db3.ai/app/server';
+
+/** A scheduled report whose missing local input can be repaired before replay. */
+export class RecoverableSummaryJob extends QueueableJob {
+	static readonly jobName = 'recoverable-summary';
+
+	/** Creates a durable empty payload; the app owns the source location. */
+	constructor() {
+		super({});
+	}
+
+	/** Reads the source before replacing output so failed reads cannot overwrite it. */
+	async handle(): Promise<void> {
+		const source = await app().storage.readToString('summary-source.txt');
+		await app().storage.write('reports/recovered.txt', `Summary: ${source.trim()}`);
+	}
+}

package/src/scheduler/examples/WriteDailySummaryJob.ts

@@ -0,0 +1,17 @@
+import { QueueableJob } from '@db3.ai/app/queue';
+import { app } from '@db3.ai/app/server';
+
+/** A small application job showing scheduled work performed by the queue. */
+export class WriteDailySummaryJob extends QueueableJob {
+	static readonly jobName = 'write-daily-summary';
+
+	/** Creates a zero-argument job with a serializable empty payload. */
+	constructor() {
+		super({});
+	}
+
+	/** Writes a replaceable summary; repeated attempts do not append duplicates. */
+	async handle(): Promise<void> {
+		await app().storage.write('reports/latest.txt', 'Daily summary ready');
+	}
+}

package/src/scheduler/examples/registerDailySummary.ts

@@ -0,0 +1,13 @@
+import { app } from '@db3.ai/app/server';
+import { WriteDailySummaryJob } from './WriteDailySummaryJob';
+
+/**
+ * Registers one daily report in each scheduler and queue-worker process.
+ *
+ * Call once at boot. Resolving scheduler also attaches the queue lifecycle
+ * recorder, so workers update occurrence history after processing the job.
+ */
+export function registerDailySummary(): void {
+	app().queue.registerJob(WriteDailySummaryJob);
+	app().scheduler.job(WriteDailySummaryJob).dailyAt('09:00').timezone('UTC');
+}

package/src/scheduler/examples/runDailySummary.ts

@@ -0,0 +1,46 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
+import { FailedJob, QueuedJob } from '@db3.ai/app/queue';
+import { ScheduledOccurrence } from '@db3.ai/app/scheduler';
+import { App } from '@db3.ai/app/server';
+import { registerDailySummary } from './registerDailySummary';
+
+/**
+ * Evaluates a fixed minute, processes its SQL-backed job and checks deduplication.
+ *
+ * This isolated lab owns its schema and files. It does not run historical
+ * application schedules or wait for wall-clock time to pass.
+ *
+ * @returns Stable scheduling, processing and history observations.
+ */
+export async function runDailySummary() {
+	const root = await mkdtemp(join(tmpdir(), 'db3-scheduler-guide-'));
+	try {
+		const database = await createGeneratedTestDatabase('scheduler_guide');
+		const application = new App({ db: database.db, storage: { disks: { local: { driver: 'local', root } } } });
+		try {
+			await application.db.install(QueuedJob, FailedJob, ScheduledOccurrence);
+			registerDailySummary();
+			const minute = new Date('2026-01-01T09:00:00Z');
+			const first = await application.scheduler.runDue(minute);
+			const repeated = await application.scheduler.runDue(minute);
+			const processed = await application.queue.workNextJob();
+			if (!processed) throw new Error('The scheduled job was not available to the worker.');
+			const occurrence = await ScheduledOccurrence.where('name', 'write-daily-summary').firstOrFail();
+			const text = await application.storage.readToString('reports/latest.txt');
+			const notDue = await application.scheduler.runDue(new Date('2026-01-01T09:01:00Z'));
+			return { dispatched: first.dispatched, duplicateSkipped: repeated.skipped, processed: processed.status, occurrenceStatus: occurrence.status, text, nextMinuteDue: notDue.due };
+		} finally {
+			try { await application.close(); } finally { await database.destroy(); }
+		}
+	} finally {
+		await rm(root, { recursive: true, force: true });
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	console.log(JSON.stringify(await runDailySummary(), null, 2));
+}

package/src/scheduler/examples/runScheduledReplay.ts

@@ -0,0 +1,60 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createGeneratedTestDatabase } from '@db3.ai/app/db/test/db';
+import { FailedJob, QueuedJob } from '@db3.ai/app/queue';
+import { ScheduledOccurrence } from '@db3.ai/app/scheduler';
+import { App } from '@db3.ai/app/server';
+import { RecoverableSummaryJob } from './RecoverableSummaryJob';
+
+/**
+ * Recovers a terminal scheduled failure without rewriting its original audit row.
+ *
+ * The replacement job has a new identity and links to the retained failure.
+ * The lab uses immediate retries only to avoid waiting; production workers
+ * should use deliberate backoff. All SQL and files belong to this invocation.
+ *
+ * @returns Original audit state, replacement outcome, linkage and cleaned queue.
+ */
+export async function runScheduledReplay() {
+	const root = await mkdtemp(join(tmpdir(), 'db3-scheduled-replay-'));
+	try {
+		const database = await createGeneratedTestDatabase('scheduled_replay');
+		const application = new App({ db: database.db, queue: { retryDelaySeconds: 0, queueMonitor: false }, storage: { disks: { local: { driver: 'local', root } } } });
+		try {
+			await application.db.install(QueuedJob, FailedJob, ScheduledOccurrence);
+			application.queue.registerJob(RecoverableSummaryJob);
+			application.scheduler.job(RecoverableSummaryJob).dailyAt('09:00').timezone('UTC');
+			const minute = new Date('2026-01-01T09:00:00Z');
+			await application.scheduler.runDue(minute);
+			// Default maxTries is three. Bound the drain so a regression cannot hang.
+			for (let attempt = 0; attempt < 3; attempt++) await application.queue.workNextJob();
+			const original = await ScheduledOccurrence.where('name', RecoverableSummaryJob.jobName).firstOrFail();
+			const [failure] = await application.queue.failedJobs();
+			if (!failure || original.status !== 'failed') throw new Error('Expected the missing source to reach terminal failure.');
+			await application.storage.write('summary-source.txt', 'Recovered');
+			const replacementId = await application.queue.retryFailed(failure.id);
+			const replacement = await QueuedJob.findOrFail(replacementId);
+			const linked = replacement.payload?.retryOf?.failedJobId === failure.id;
+			const result = await application.queue.workNextJob();
+			const retained = await ScheduledOccurrence.findOrFail(original.id!);
+			return {
+				originalStatus: retained.status, replacementStatus: result?.status, linked,
+				newIdentity: replacement.payload?.uuid !== failure.payload.uuid,
+				text: await application.storage.readToString('reports/recovered.txt'),
+				duplicateSkipped: (await application.scheduler.runDue(minute)).skipped,
+				retainedFailures: (await application.queue.failedJobs()).length,
+				activeJobs: await QueuedJob.query().count(),
+			};
+		} finally {
+			try { await application.close(); } finally { await database.destroy(); }
+		}
+	} finally {
+		await rm(root, { recursive: true, force: true });
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	console.log(JSON.stringify(await runScheduledReplay(), null, 2));
+}

package/src/scheduler/index.ts

@@ -0,0 +1,9 @@
+export * from './contracts';
+export * from './console';
+export * from './Scheduler';
+export * from './ScheduledCall';
+export * from './ScheduledEvent';
+export * from './ScheduledJob';
+export * from './ScheduledOccurrence';
+export * from './ScheduledOccurrenceRecorder';
+export * from './SchedulerWorker';

package/src/scheduler/scheduleTime.ts

@@ -0,0 +1,78 @@
+const DAILY_TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
+/**
+ * Validates and normalizes one daily wall-clock time.
+ *
+ * @param value - Candidate time in 24-hour HH:mm form.
+ * @returns Validated time.
+ */
+export function normalizeDailyTime(value: string): string {
+	const normalized = value.trim();
+
+	if (!DAILY_TIME_PATTERN.test(normalized)) {
+		throw new Error(`Invalid daily schedule time "${value}". Use HH:mm in 24-hour time.`);
+	}
+
+	return normalized;
+}
+
+/**
+ * Validates one IANA timezone using the platform Intl implementation.
+ *
+ * @param value - Candidate IANA timezone.
+ * @returns Validated timezone.
+ */
+export function normalizeScheduleTimezone(value: string): string {
+	const normalized = value.trim();
+
+	try {
+		new Intl.DateTimeFormat('en-GB', {
+			timeZone: normalized,
+		}).format(new Date(0));
+	} catch {
+		throw new Error(`Invalid scheduler timezone "${value}". Use an IANA timezone name.`);
+	}
+
+	return normalized;
+}
+
+/**
+ * Returns whether a UTC instant matches one daily local schedule.
+ *
+ * @param instant - UTC instant being evaluated.
+ * @param time - Local HH:mm schedule time.
+ * @param timezone - IANA timezone used for local interpretation.
+ * @returns True when the local hour and minute match.
+ */
+export function dailyScheduleIsDue(
+	instant: Date,
+	time: string,
+	timezone: string,
+): boolean {
+	const parts = new Intl.DateTimeFormat('en-GB', {
+		timeZone: timezone,
+		hour: '2-digit',
+		minute: '2-digit',
+		hourCycle: 'h23',
+	}).formatToParts(instant);
+	const hour = parts.find(part => part.type === 'hour')?.value;
+	const minute = parts.find(part => part.type === 'minute')?.value;
+
+	return `${hour}:${minute}` === time;
+}
+
+/**
+ * Floors an instant to its canonical UTC minute.
+ *
+ * @param instant - Instant to normalize.
+ * @returns New Date at second and millisecond zero.
+ */
+export function utcMinute(instant: Date): Date {
+	const time = instant.getTime();
+
+	if (!Number.isFinite(time)) {
+		throw new Error('Scheduler requires a valid evaluation date.');
+	}
+
+	return new Date(Math.floor(time / 60_000) * 60_000);
+}

package/src/security/README.md

@@ -0,0 +1,130 @@
+# Security
+
+The security service centralizes reversible application encryption. It reads
+its key and cipher from the active app config, then owns the authenticated
+cipher, versioned payload format, and JSON serialization used by framework
+fields and application services.
+
+Password hashing is intentionally separate. Passwords are verified through a
+one-way hash and have no reusable encryption key; values such as webhook secrets
+and WordPress application passwords must be decrypted later and therefore use
+`app().security`.
+
+## Run a disposable secret round trip
+
+Complete [Installation](https://db3.ai/docs/installation), then run in your independent app:
+
+```sh
+mkdir -p examples
+cp -R node_modules/@db3.ai/app/src/security/examples/. examples/
+npx tsx examples/runSecretRoundTrip.ts
+```
+
+Expect `roundTrip`, `randomized`, `contextRejected`, `tamperingRejected` and `nonJsonRejected` all true. The example uses real encryption and a disposable App. It prints no key, plaintext or ciphertext, makes no database connection and does not read or write `.env`.
+
+The key is generated for the lab only. A persistent application must generate a key once during provisioning and retain it; copying the per-run lab key pattern into production would make stored secrets unreadable after restart.
+
+Copy the exact test from the [Security guide](https://db3.ai/docs/security#testing) into `tests/security/runSecretRoundTrip.test.ts` and run:
+
+```sh
+npx vitest run tests/security/runSecretRoundTrip.test.ts
+npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts
+```
+
+The tests check tampering, wrong-owner context and a different key, then prove the original service can still decrypt its value. Wrong-key failures must not silently overwrite ciphertext with an empty secret. These tests do not replace authorization or database backup/restore tests.
+
+## Configuration
+
+Applications should define a `security` config section:
+
+```ts
+import { defineConfig, env } from '@db3.ai/app/config';
+import { ensureAppKey, type SecurityOptions } from '@db3.ai/app/security';
+
+export default defineConfig({
+	key: env.string('APP_KEY') || ensureAppKey(),
+	cipher: 'aes-256-gcm',
+} satisfies SecurityOptions);
+```
+
+`ensureAppKey()` is a convention-based convenience for application config. It
+always uses `APP_KEY` and `.env`: an existing non-empty value is preserved, a
+missing value is generated and written to `.env`, and a persistence failure
+throws `SecurityError` so startup fails. The security service itself does not
+read environment variables or write files; `app().config` remains the boundary
+between environment configuration and framework services.
+
+The same key must be available to every API and worker process that reads or
+writes encrypted data. Back it up separately from the database: losing or
+changing the key makes existing ciphertext unreadable. Key rotation is not yet
+implemented, so replace the key only as part of a deliberate data re-encryption
+operation.
+
+Writable dotenv files are convenient for local and single-host environments.
+Production containers commonly use a read-only application filesystem and
+inject secrets through their deployment platform. Providing `APP_KEY`
+externally bypasses `ensureAppKey()` and no file write is attempted. Replicated
+processes must receive one shared key rather than generating separate keys into
+ephemeral files.
+
+Keys can also be generated explicitly when provisioning a deployment:
+
+```sh
+printf 'base64:%s\n' "$(openssl rand -base64 32)"
+```
+
+## Encryption
+
+New payloads use AES-256-GCM with a random 96-bit initialization vector and a
+128-bit authentication tag. The stored envelope includes a format version and
+cipher name so future readers can distinguish formats. Encryption authenticates
+both the ciphertext and optional caller-supplied context.
+
+```ts
+const payload = app().security.encryptJson({
+	token: 'provider-secret',
+}, {
+	additionalAuthenticatedData: 'websites:blog_integration',
+});
+
+const value = app().security.decryptJson<{ token: string }>(payload, {
+	additionalAuthenticatedData: 'websites:blog_integration',
+});
+```
+
+Never log plaintext, ciphertext, keys, or decrypted provider errors.
+
+Additional authenticated context is not stored in the envelope; reconstruct it identically when decrypting. It authenticates use but does not authorize the caller. `decrypt()` returns a Buffer; `decryptJson<T>()` parses JSON but does not validate the generic type at runtime. The key is pinned for the service lifetime, not reread on each operation.
+
+## Encrypted model fields
+
+Use `field.encryptedJson<T>()` for JSON-compatible secrets stored on an
+ActiveRecord model:
+
+```ts
+blogIntegration: field.encryptedJson<BlogIntegration>({
+	column: 'blog_integration',
+	selectedByDefault: false,
+})
+```
+
+The field stores versioned ciphertext in a long text column. It is always hidden
+from `toJSON()`, cannot be populated through request helpers when request
+guarded, and cannot be used in equality queries because encryption is
+randomized. It also authenticates the model table and database column name so a
+payload copied to a different encrypted field will not decrypt.
+
+That automatic field context is table/column identity, not row-level ownership. Keep authorization and any row/tenant binding policy explicit.
+
+For fields with `selectedByDefault: false`, integration-specific server code
+must opt in explicitly:
+
+```ts
+const website = await Website
+	.query()
+	.withField('blogIntegration')
+	.wherePk(websiteId)
+	.firstOrFail();
+```
+
+See [all current Security contracts](https://db3.ai/docs/security-api) for key, cipher, payload and error options. Automatic key rotation, KMS integration and searchable encryption are not implemented. Keep a re-encryption/backup plan separate from this local happy path.