@db3.ai/app 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,31 @@
+Licence scope
+
+The MIT licence below applies to the DB3 framework packages (@db3.ai/app,
+@db3.ai/pure and @db3.ai/create), their framework documentation, the starter
+application in apps/starter, and the framework release tooling. Third-party dependencies retain
+their own licences.
+Applications and other packages in this development repository are excluded
+unless they carry their own licence granting rights. In particular, this file
+does not license private product code merely because it shares this repository.
+
+MIT License
+
+Copyright (c) 2026 DB3 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# @db3.ai/app
+
+Shared backend framework package for DB3 applications.
+
+The framework is intended to support both code-first and visual application
+development. Framework operations should expose reusable contracts so CLI,
+GUI, programmatic, and collaborative AI clients can share the same behavior
+rather than creating parallel implementations. Source-repository contributors
+can read the product direction in `docs/framework-goals.md`; that repository-only
+document is not part of the installed runtime package.
+
+This package owns reusable runtime services and data-layer mechanics:
+
+- `config`: explicit config repositories and environment parsing helpers.
+- `cli`: shared `db3` commands, interactive app REPL, service registration, help and app lifecycle.
+- `cache`: named cache stores and driver-backed value lifecycles.
+- `events`: synchronous and asynchronous in-process event dispatch.
+- `logging`: structured application logging and development-tool delivery.
+- `server`: `App`, service discovery, request context, and database wiring.
+- `db`: ActiveRecord, FieldType, projections, schema installation, and SQL error helpers.
+- `validation`: request-data validation for routes, services, and jobs.
+- `auth`: user identity, configurable auth providers, auth tokens, password reset tokens, and password hashing.
+- `ai`: agents with function calls, streaming, durable conversations, provider request tracking, images, embeddings, structured output and failover.
+- `queue`: database-backed dispatch, handlers, job classes, retry/failure records, and workers.
+- `serialization`: registered root-constructor serialization from ordinary JSON state, with ActiveRecord identity references as the only special nested value.
+- `scheduler`: code-owned daily schedules, durable occurrence claims, queue correlation, and a dedicated worker.
+- `flows`: code-backed graph definitions, queue orchestration, durable block observability, nested flows, and replay.
+- `mail`: file, Mailgun, and Resend mail transports.
+- `storage`: named local and S3-compatible disks, streams, transfers and scoped file operations.
+- `media`: scoped media libraries, managed file ULIDs, and browser-visible folder trees.
+- `security`: central key configuration and versioned authenticated encryption for application secrets.
+- `ssr`: optional render contracts, document assembly, safe hydration state, and Fastify adaptation for public HTML.
+- `url`: canonical base-URL configuration and standard URL resolution, without a named-route registry.
+
+Keep app-specific behavior in `apps/*`. Move code here only when it is reusable framework behavior.
+
+## Installation
+
+After the first public release, install the framework runtime with:
+
+```sh
+npm install @db3.ai/app
+```
+
+Install optional Fastify or Vite peer packages only when using their matching
+SSR adapters.
+
+## Publishing status
+
+The framework is MIT licensed; private applications sharing the development
+repository are excluded by the licence scope. Public framework source belongs
+in `github.com/db3ai/framework`. The published packages are `@db3.ai/app`,
+`@db3.ai/pure` and `@db3.ai/create`. Maintainers can publish a verified beta from
+the repository root with `npm run framework:publish -- --version 0.1.0-beta.1`;
+add `--dry-run` to inspect it without publishing. npm handles packaging, login
+and upload. See `docs/framework-release.md` for release checks and the manual
+bootstrap and trusted-publishing workflows.
+
+The [installation guide](https://db3.ai/docs/installation) distinguishes the
+unpublished preview tarballs from the future npm install command. The
+[first app](https://db3.ai/docs/create-app) uses the shipped
+`src/server/examples` files to run and test an independent Fastify application.
+Auth, Storage, Media and Scheduler also ship their service-owned examples.
+
+## Consumer package artifacts
+
+From the repository root, stage both compiled packages and run the clean
+consumer install gate with:
+
+```sh
+npm run framework:package
+npm run framework:package:test
+```
+
+The first command writes publish-shaped packages to
+`dist/framework-packages/pure` and `dist/framework-packages/app`. The second
+packs both directories, installs the tarballs in a temporary project, imports
+every public runtime subpath, type-checks representative declarations, verifies
+installed Markdown links, and exercises the `db3-agents` scaffold.
+
+The workspace manifests intentionally keep their source exports for monorepo
+development; only the staged manifests target compiled JavaScript and
+declarations. Workspace manifests, runtime imports, examples, documentation,
+and consumer artifacts all use the same `@db3.ai/*` package names.
+The ordinary staged manifest omits the private monorepo repository identity.
+Release-mode staging requires the exact dedicated public framework repository
+and rejects ambiguous or non-GitHub URLs. Candidate preparation also requires
+both checked-in versions and App's exact Pure dependency to match the requested
+tag; it does not rewrite versions. Always prepare Pure before App because App
+depends on the matching Pure version. These commands do not publish either
+package.
+
+npm provenance requires a public repository whose package `repository.url`
+matches the GitHub source exactly. Once that repository is established, publish
+from its trusted GitHub Actions workflow so npm can attach provenance without a
+long-lived publish token.
+
+The eventual public workflow must supply its exact canonical source URL through
+either the option or environment variable below:
+
+```sh
+npm run framework:package -- --repository-url git+https://github.com/OWNER/REPOSITORY.git
+DB3_FRAMEWORK_REPOSITORY_URL=git+https://github.com/OWNER/REPOSITORY.git npm run framework:package
+```
+
+Only canonical public GitHub URLs are accepted. In this explicit release mode,
+the staged manifests include package-directory repository metadata and enable
+`publishConfig.provenance`; neither command publishes a package.
+
+## Testing
+
+Framework tests live with the service they exercise under
+`src/{service}/tests`. Run the complete package suite before considering a
+framework change finished:
+
+```sh
+npm run check --workspace packages/app
+npm test --workspace packages/app
+```
+
+Run one service while developing a focused change by passing its directory
+name to the service runner:
+
+```sh
+npm run test:service --workspace packages/app -- queue
+```
+
+The service runner fails when the service does not have a test directory, so a
+misspelled or stale service name cannot produce an accidental green result.
+Coverage uses the same complete suite and enforces package-wide regression
+floors of 75% statements, 65% branches, 80% functions, and 77% lines:
+
+```sh
+npm run test:coverage --workspace packages/app
+```
+
+The test scripts optionally load connection credentials from the package-owned
+`packages/app/.env.test` file, then force `NODE_ENV=test`,
+`DB_DATABASE=db3_app_test`, and `DB_TEST_DATABASE_PREFIX=db3_app_test`.
+Start from the committed example when local credentials are needed:
+
+```sh
+cp packages/app/.env.test.example packages/app/.env.test
+```
+
+Framework integration suites create and remove unique disposable databases
+under that test-only namespace. They do not read application configuration or connect
+to an application's named database. A `DATABASE_URL` supplied by CI must itself
+target `db3_app_test` (or a disposable database with that prefix). The configured
+database server must be reachable for the complete suite and service suites that
+own database integration tests.
+
+Redis Queue integration tests use `QUEUE_REDIS_URL` or the separate
+`QUEUE_REDIS_HOST` and `QUEUE_REDIS_PORT` settings. They skip during an ordinary
+local run when Redis is unavailable. A release gate must prove the Redis driver
+against a real server and fail instead of skipping it:
+
+```sh
+npm run test:release --workspace packages/app
+```
+
+The release command runs the source and example type checks followed by the
+complete coverage suite. It sets `TEST_REDIS_REQUIRED=1`, so an unreachable
+Redis server is a failure rather than a conditional skip.
+
+Tests should exercise public typed contracts and observable behaviour with real
+framework components. Mock only external provider boundaries, and cover failure,
+retry, cleanup, and lifecycle behaviour when those outcomes are part of the
+service contract. Public API changes also require a consumer type check through
+the exported package subpath; importing a private source file is not sufficient.
+When a service supports multiple drivers, apply the same behavioural contract to
+each supported driver where practical, and require its external infrastructure
+in the release gate instead of accepting a skipped suite as proof.
+
+The richer guide at [db3.ai](https://db3.ai/) includes dedicated sections for
+Mail, Queue, creating jobs, and queue workers.
+
+See [src/cli/README.md](./src/cli/README.md) for the shared `db3` executable and
+service command registration. Generated apps configure it in `server/cli.config.ts`;
+database commands are owned by DB and job generation is owned by Queue.
+
+See [src/flows/README.md](./src/flows/README.md) for flow definitions, block contracts, file providers, durable run models, nested execution, and replay.
+
+See [src/scheduler/README.md](./src/scheduler/README.md) for scheduled jobs,
+inline calls, durable deduplication, occurrence history, and process commands.
+
+See [src/serialization/README.md](./src/serialization/README.md) for
+`app().serializer`, registry configuration, supported values, and ActiveRecord
+reference semantics.
+
+See [src/security/README.md](./src/security/README.md) for `app().security`,
+application-key configuration, authenticated encryption, and encrypted JSON
+model fields.
+
+See [src/ssr/README.md](./src/ssr/README.md) for the optional server-rendering
+boundary, document markers, request isolation, and Fastify adapter.
+
+## Auth Providers
+
+`packages/app/src/auth` treats the user row as the account and `auth_providers`
+rows as the ways that account can authenticate. Provider-specific code lives in
+`packages/app/src/auth/providers`: the built-in `password` provider stores
+password credentials in `auth_providers`, while the Google provider verifies
+Google ID tokens and stores only safe profile claims.
+
+Apps configure supported providers through the app config repository at
+`auth.providers`:
+
+```ts
+import {
+	GOOGLE_AUTH_PROVIDER,
+	PASSWORD_AUTH_PROVIDER,
+} from '@db3.ai/app/auth';
+
+const app = new App({
+	config: {
+		auth: {
+			providers: {
+				[PASSWORD_AUTH_PROVIDER]: {
+					driver: PASSWORD_AUTH_PROVIDER,
+				},
+				[GOOGLE_AUTH_PROVIDER]: {
+					driver: GOOGLE_AUTH_PROVIDER,
+					clientIds: ['google-client-id.apps.googleusercontent.com'],
+				},
+			},
+		},
+	},
+});
+```
+
+Tests and advanced apps may also pass concrete provider driver instances through
+`AppOptions.auth.providers`.
+
+Provider rows can be listed, linked, and unlinked through the auth service. The
+framework refuses to unlink the final provider for a user so every account keeps
+at least one usable login method.
+
+See [src/auth/README.md](./src/auth/README.md) for the account/provider mental
+model, route and session examples, provider management, custom drivers, security
+responsibilities, and complete password and Google setup instructions.

package/agent-instructions.md

@@ -0,0 +1,69 @@
+# @db3.ai/app Agent Instructions
+
+This file is the installed framework guide for AI tools working in a consuming
+application. The consuming repository's `AGENTS.md` should route framework work
+here; this file does not replace the application's own product instructions.
+
+## Resolve the installed framework
+
+Use Node's package resolver instead of assuming a particular `node_modules`
+layout:
+
+```sh
+node -p "require.resolve('@db3.ai/app/agent-instructions')"
+```
+
+The returned file is inside the installed `@db3.ai/app` package. Resolve the
+other paths below relative to its directory.
+
+## Read the smallest relevant surface
+
+- Read `package.json` for supported public entry points.
+- Read `README.md` for package ownership and application setup.
+- For one service, read `src/{service}/README.md` when it is shipped.
+- Use the declarations exposed by the relevant `@db3.ai/app/{service}` entry
+  point as the exact public API contract.
+- Use service-owned examples under `src/{service}/examples/` when present.
+
+Do not infer supported APIs from unexported files or copy implementation details
+from `node_modules` into the application. If the installed declarations,
+documentation and runtime disagree, treat that as a framework defect and record
+the installed package version.
+
+## Application boundaries
+
+- For new applications, use `client/` for browser code and `server/` for backend
+  code. Keep committed migrations and the schema snapshot in `server/database/`,
+  and behaviour tests in `tests/`. Browser database access goes through the server API.
+- Configure app migrations with `dbOptions: { migrations: { models } }`.
+  The framework fixes paths to `server/database/migrations/` and
+  `server/database/schema.snapshot.json` beneath `App.directory`; no separate
+  `migrations.ts` configuration is needed. The starter anchors the app root with
+  `directory: new URL('../', import.meta.url)` in `server/app.ts`.
+- Register service commands in `server/cli.config.ts` using the shared `db3` CLI.
+  Keep command implementations in their owning service and reuse its public operations.
+- Keep product models, routes, jobs and policy in the consuming application.
+- Use ActiveRecord logical field names and let fields own database mapping,
+  conversion, validation and JSON values.
+- Resolve normal application services through the active `App` rather than
+  threading optional Knex connections through app code.
+- Put reusable mechanics in the framework only when they are genuinely shared.
+
+## AI workflows
+
+For AI work, read `src/ai/README.md` and its examples first. Use `app().ai` and
+the exported `Agent` class for provider calls, tools, conversations, request
+tracking and queued runs. Keep application prompts, authorization, storage
+destinations and commercial policy in the app. Extend the shipped AI records
+through `ai.models` and committed migrations. Do not copy the SDK runner or
+tracking implementation into application helpers or assume fluent builders
+that are absent from the installed declarations.
+
+## Verification
+
+- Type-check application code against the installed package exports.
+- Add behavioural tests for application workflows using real framework services.
+- Use disposable databases for database-backed tests.
+- Mock external providers, not framework-owned behavior.
+- Run the consuming application's focused tests and type check after changing
+  framework usage.

package/bin/db3-agents.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const START_MARKER = '<!-- @db3.ai/app:start -->';
+const END_MARKER = '<!-- @db3.ai/app:end -->';
+
+const options = parseArguments(process.argv.slice(2));
+const targetPath = resolve(process.cwd(), options.target);
+const template = await readFile(
+	new URL('../templates/AGENTS.md', import.meta.url),
+	'utf8',
+);
+const existing = await readOptionalFile(targetPath);
+const hasStartMarker = existing?.includes(START_MARKER) ?? false;
+const hasEndMarker = existing?.includes(END_MARKER) ?? false;
+
+if (hasStartMarker !== hasEndMarker) {
+	throw new Error(
+		`Refusing to update ${targetPath} because its @db3.ai/app markers are incomplete.`,
+	);
+}
+
+if (options.check) {
+	if (!hasStartMarker) {
+		console.error(`${targetPath} does not contain the @db3.ai/app instruction scaffold.`);
+		process.exitCode = 1;
+	} else {
+		console.log(`${targetPath} contains the @db3.ai/app instruction scaffold.`);
+	}
+} else if (hasStartMarker) {
+	if (options.update) {
+		const updated = replaceScaffold(existing ?? '', template);
+
+		await writeFile(targetPath, updated, 'utf8');
+		console.log(`Updated the @db3.ai/app instructions in ${targetPath}.`);
+	} else {
+		console.log(`${targetPath} already contains the @db3.ai/app instruction scaffold.`);
+	}
+} else {
+	const updated = appendScaffold(existing, template);
+
+	await writeFile(targetPath, updated, 'utf8');
+	console.log(`Added the @db3.ai/app instruction scaffold to ${targetPath}.`);
+}
+
+/**
+ * Parses supported command-line options for the scaffold command.
+ *
+ * @param {string[]} args - Command-line arguments after the executable name.
+ * @returns {{ target: string, check: boolean, update: boolean }} Parsed options.
+ */
+function parseArguments(args) {
+	const parsed = {
+		target: 'AGENTS.md',
+		check: false,
+		update: false,
+	};
+
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+
+		if (argument === '--check') {
+			parsed.check = true;
+			continue;
+		}
+
+		if (argument === '--update') {
+			parsed.update = true;
+			continue;
+		}
+
+		if (argument === '--target') {
+			const target = args[index + 1];
+
+			if (!target) {
+				throw new Error('--target requires a file path.');
+			}
+
+			parsed.target = target;
+			index += 1;
+			continue;
+		}
+
+		throw new Error(`Unknown db3-agents option "${argument}".`);
+	}
+
+	if (parsed.check && parsed.update) {
+		throw new Error('--check and --update cannot be used together.');
+	}
+
+	return parsed;
+}
+
+/**
+ * Reads an existing instruction file without failing when it is absent.
+ *
+ * @param {string} path - Absolute instruction-file path.
+ * @returns {Promise<string | null>} Existing content or null when missing.
+ */
+async function readOptionalFile(path) {
+	try {
+		return await readFile(path, 'utf8');
+	} catch (error) {
+		if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+			return null;
+		}
+
+		throw error;
+	}
+}
+
+/**
+ * Appends the framework block without disturbing existing project guidance.
+ *
+ * @param {string | null} existing - Existing instruction content, when present.
+ * @param {string} template - Current framework scaffold.
+ * @returns {string} Complete instruction file content.
+ */
+function appendScaffold(existing, template) {
+	const prefix = existing?.trimEnd();
+
+	return prefix ? `${prefix}\n\n${template}` : template;
+}
+
+/**
+ * Replaces only the marked framework block in an existing instruction file.
+ *
+ * @param {string} existing - Existing instruction content containing both markers.
+ * @param {string} template - Current framework scaffold.
+ * @returns {string} Updated instruction file content.
+ */
+function replaceScaffold(existing, template) {
+	const start = existing.indexOf(START_MARKER);
+	const end = existing.indexOf(END_MARKER, start);
+	const suffixStart = end + END_MARKER.length;
+
+	return `${existing.slice(0, start)}${template.trimEnd()}${existing.slice(suffixStart)}`;
+}

package/bin/db3.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { register } from 'tsx/esm/api';
+
+// The workspace resolves public exports to TypeScript; installed packages resolve to JavaScript.
+const unregister = register();
+try {
+	const { runDb3 } = await import('@db3.ai/app/cli');
+	process.exitCode = await runDb3(process.argv.slice(2));
+} finally {
+	unregister();
+}

package/dist/ai/AIErrors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Raised when an AI operation needs provider credentials but none are configured.
+ */
+export declare class AIConfigurationError extends Error {
+    /** Creates a missing-provider-configuration error. */
+    constructor(message?: string);
+}
+/**
+ * Raised when the provider rejects a request or returns a payload without text.
+ */
+export declare class AIRequestError extends Error {
+    readonly code: string | null;
+    /**
+     * Creates a provider request failure.
+     *
+     * @param message - Human-readable provider failure message.
+     * @param code - Stable provider error code, when supplied.
+     */
+    constructor(message?: string, code?: string | null);
+}
+/**
+ * Raised when the application allowance hook rejects an AI request.
+ */
+export declare class AIAllowanceExceededError extends Error {
+    /** Stable public failure code; applications may specialize it for their own allowance UI. */
+    readonly publicCode: string;
+    /**
+     * Create an allowance failure.
+     *
+     * @param message - Public error message for the denied request.
+     */
+    constructor(message?: string);
+}

package/dist/ai/AIErrors.js

@@ -0,0 +1,43 @@
+/**
+ * Raised when an AI operation needs provider credentials but none are configured.
+ */
+export class AIConfigurationError extends Error {
+    /** Creates a missing-provider-configuration error. */
+    constructor(message = 'Set OPENAI_API_KEY before using AI features.') {
+        super(message);
+        this.name = 'AIConfigurationError';
+    }
+}
+/**
+ * Raised when the provider rejects a request or returns a payload without text.
+ */
+export class AIRequestError extends Error {
+    code;
+    /**
+     * Creates a provider request failure.
+     *
+     * @param message - Human-readable provider failure message.
+     * @param code - Stable provider error code, when supplied.
+     */
+    constructor(message = 'The AI provider did not return a valid response.', code = null) {
+        super(message);
+        this.code = code;
+        this.name = 'AIRequestError';
+    }
+}
+/**
+ * Raised when the application allowance hook rejects an AI request.
+ */
+export class AIAllowanceExceededError extends Error {
+    /** Stable public failure code; applications may specialize it for their own allowance UI. */
+    publicCode = 'ai_allowance_exceeded';
+    /**
+     * Create an allowance failure.
+     *
+     * @param message - Public error message for the denied request.
+     */
+    constructor(message = 'AI allowance has been reached for this period.') {
+        super(message);
+        this.name = 'AIAllowanceExceededError';
+    }
+}

package/dist/ai/AIFailover.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decides whether a provider HTTP response should fail over to the next provider.
+ *
+ * Failover is reserved for transient availability problems and exhausted
+ * account capacity: rate limits, overload, 5xx, timeouts, and quota. Request
+ * problems such as validation or authentication failures stay terminal because
+ * retrying them on another provider repeats the same failure at extra cost.
+ *
+ * @param status - HTTP response status.
+ * @param payload - Parsed provider response payload.
+ * @returns True when the next provider in the chain should be attempted.
+ */
+export declare function isFailoverableResponse(status: number, payload: unknown): boolean;
+/**
+ * Decides whether a thrown provider or SDK failure should fail over.
+ *
+ * Local rate-limit deferrals count as failoverable because a full local bucket
+ * for one provider says nothing about the capacity of the next provider.
+ * Streaming SDK failures may carry a provider code without an HTTP status, so
+ * classification never relies on status alone.
+ *
+ * @param error - Unknown thrown value from a provider call or SDK run.
+ * @returns True when the next provider in the chain should be attempted.
+ */
+export declare function isFailoverableFailure(error: unknown): boolean;