@db3.ai/app 0.1.0-beta.1 → 0.1.0-beta.4

package/README.md

@@ -2,19 +2,16 @@
 
 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:
 
+- `apps`: local feature apps, optional public services, owned migrations, lifecycle and inspectable navigation metadata. See [Apps](src/apps/README.md) for local folders and npm extraction.
+
 - `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.
+- `health`: extensible application and component checks with a Fastify `/health` adapter.
+- `websocket`: public/authenticated JSON endpoint actions, server-owned local channels, presence and a small browser client; see [WebSocket setup](./src/websocket/README.md).
 - `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.
@@ -26,8 +23,11 @@ This package owns reusable runtime services and data-layer mechanics:
 - `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.
+- `in-app`: durable recipient inboxes, scoped access, deduplication and independent read/dismiss/archive state.
+- `notifications`: recipient-aware `via()`, `toInApp()` and `toMail()` definitions coordinated through framework delivery services.
 - `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.
+- `network`: outbound request guards that keep user-supplied URLs, redirects and headless-browser traffic off private networks; see [Network](./src/network/README.md).
 - `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.
@@ -53,7 +53,7 @@ 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
+and upload. See `packages/app/RELEASING.md` for release checks and the manual
 bootstrap and trusted-publishing workflows.
 
 The [installation guide](https://db3.ai/docs/installation) distinguishes the
@@ -107,14 +107,57 @@ 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.
 
+## AI application guidance
+
+Generated DB3 applications include a root `AGENTS.md` that tells AI coding
+tools to resolve the installed framework instructions, use public package
+exports, preserve application/framework ownership, and follow the framework's
+file-naming conventions. In particular, class-owning TypeScript files and Vue
+components use PascalCase and match their primary concept.
+
+Existing applications can add the marked framework block without replacing
+their product-specific instructions:
+
+```sh
+npx db3-agents --target AGENTS.md
+```
+
+Refresh only that framework-owned block after upgrading `@db3.ai/app`:
+
+```sh
+npx db3-agents --target AGENTS.md --update
+```
+
+The scaffold directs AI tools to the installed
+`@db3.ai/app/agent-instructions` export. Those installed instructions are the
+consumer-facing source of truth for application layout, boundaries, naming,
+and verification.
+
 ## Testing
 
+In the source workspace, `npm test --workspace @db3.ai/app -- <optional test paths>`
+runs the selected behaviour tests, then source/example type checks and available
+workspace naming checks. All stages run after ordinary failures and a combined
+summary reports the final result and the convention findings path.
+The ordinary runner reuses Node's compiled dependencies, and Vitest persists
+source transformations under the workspace's ignored `node_modules` directory.
+Transformation directories are separate for each workspace and npm lockfile
+snapshot, so a dependency update cannot clear another active run's cache.
+Test files still run in separate runtimes and integration tests still own
+disposable databases. Source, test configuration and dependency changes invalidate
+the transformation cache. Coverage arguments disable the Node bytecode cache to
+preserve V8's source-position accuracy. Set `NODE_DISABLE_COMPILE_CACHE=1` to
+opt out; `--experimental.fsModuleCache=false` disables transformation caching.
+`npm run quality --workspace @db3.ai/app` runs the same quality stages without
+tests. The Platform naming gate is not included in the public source export;
+the runner explicitly reports its absence there. The specialised service and
+coverage commands below remain available for iteration and release workflows.
+
 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
 ```
 
@@ -239,3 +282,19 @@ 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.
+
+See [src/in-app/README.md](./src/in-app/README.md) for `app().inApp`, storage setup, authenticated inbox operations and the current delivery boundary.
+
+See [src/notifications/README.md](./src/notifications/README.md) for notification classes, multi-channel sends and durable-job retry responsibilities.
+
+## Canonical provider admission source dependency
+
+This legacy workspace consumes the reviewed provider admission integration from
+[`db3ai/framework@0bb30f3`](https://github.com/db3ai/framework/commit/0bb30f30ddffb5f78ae91f398ec5a9835d9fe49e).
+`package.json.db3FrameworkSource` pins that source dependency. The integration
+updates AI transport/admission, its option contract and terminal queue handling
+in place; other deployed framework code and app policy remain owned by this
+workspace until its consumer packaging migration. No sibling checkout imports
+or npm publication are used. The canonical commit separately preserves deployed
+bookkeeping/diagnostic fixes #77/#85 before adding admission. See the AI README
+for policy, recovery and result retention.

package/agent-instructions.md

@@ -30,6 +30,36 @@ 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.
 
+## Frontend development
+
+Read these rules before creating or changing frontend behaviour. Existing large
+components and starter examples are not exceptions or architectural precedent.
+
+- Keep Vue components focused on templates, interaction wiring, accessibility and
+	styles. Keep trivial presentation state local, such as an open disclosure.
+- Put substantial reactive state, form workflows, async orchestration and
+	lifecycle management in feature-owned `useSomething` composables, even when
+	only one component uses them. Keep composables beside the feature they own.
+- Put calculations, normalization, validation and business decisions that do not
+	need Vue in plain TypeScript functions. Keep shared state in its owning store;
+	do not duplicate it in a composable. The server remains authoritative for
+	authorization, billing and persisted business rules.
+- Expose a small, explicit set of reactive state and actions. Split by cohesive
+	responsibility, not an arbitrary line limit. Do not move a whole component
+	script into one oversized composable or create pass-through wrappers.
+- Make logic independently exercisable without rendering the full page. Keep
+	network and browser side effects at explicit boundaries, preserve reactive
+	inputs, handle failures and stale responses, and clean up requests, watchers,
+	timers and subscriptions with their owning scope.
+- Prioritize direct behavioural tests of functions, stores and composables for
+	important decisions and state transitions. Cover relevant failure, concurrency
+	and cleanup cases. Use a minimal lifecycle harness when required; retain
+	focused component tests for bindings, interactions and accessibility. Source
+	text assertions and screenshots do not establish logical correctness.
+- For new work, identify the state and behaviour owner before building the UI.
+	For existing components, extract only the responsibilities involved in the
+	current task. Preserve behaviour and avoid unrelated refactoring.
+
 ## Application boundaries
 
 - For new applications, use `client/` for browser code and `server/` for backend
@@ -43,12 +73,58 @@ the installed package version.
 - 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.
+- Define new models with `class ModelName extends ActiveRecord.define({ table,
+  fields: field => ({ id: field.ulid(), ... }) }) {}` imported from
+  `@db3.ai/app/db`. Put schema options in the definition and methods in the class
+  body. Do not repeat inferred fields with `declare` properties or widen the
+  factory return type. Use `field.json<Shape>()` for structured values and handle
+  inferred nullability; `required: true` is runtime validation. `create()` makes
+  an unsaved record; persist it with `save()`. Register models in the owning
+  migration registry and generate committed migrations when the schema changes.
 - 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.
 
+## Feature apps
+
+For cohesive features start with apps/{id}/manifest.json and App.ts. The root
+service extends AppService; shared/ is optional. Read src/apps/README.md before
+changing discovery, install/uninstall, owned migrations or npm extraction. Use
+app().social for an optional generated service type. Do not add per-app host
+registration or mix feature models into the host snapshot. Marked npm dependencies
+are discovered using their exported package.json. Migrations and down functions
+belong to the app; npm lifecycle hooks must never mutate SQL. Starter ships
+administrator controls for single-process hosts; multi-process maintenance
+requires stopping all consumers before CLI actions.
+
+## Application source naming
+
+Name each file for the main concept it owns. Follow these conventions for new
+files and files moved as part of an implementation:
+
+- A file whose primary export is a class uses PascalCase and matches the class name exactly, for example `QueueWorker.ts`, `SendInvoiceJob.ts`, or `User.ts`.
+- Vue component files use PascalCase, for example `AccountSettings.vue`.
+- A file whose primary purpose is one exported public contract, interface, or type uses PascalCase and matches that concept, for example `PaymentResult.ts`.
+- Function modules use camelCase on both server and client. When a file owns one exported function, match its name exactly: `invoiceDeliver.ts` exports `invoiceDeliver`, and `useInvoice.ts` exports `useInvoice`.
+- Cohesive helper/utility modules and stores use camelCase names describing their purpose. Composables start with `use`.
+- Feature directories use kebab-case. Framework-owned route parameters, route method suffixes, migrations, generated files, and required `index.ts` entry points keep the naming required by their owning system.
+- Test filenames mirror the source concept or route they verify and end in `.test.ts`.
+
+Keep one main concept per file. Do not copy an inconsistent neighbouring name
+as precedent. When a task already changes or moves an inconsistent file, rename
+it and update imports, tests, documentation, package exports, and dynamic
+registries. Do not turn a focused task into an unrelated repository-wide rename.
+
+Prefer behaviour on the service, model, or other domain object that owns it,
+especially when it uses state, dependencies, or side effects. Pure functions
+may be grouped into cohesive, purpose-named helper modules within the owning
+service. Keep helpers local when only one implementation needs them. Avoid
+unrelated utility buckets and one-off service classes created only to wrap a
+function. Required route and command adapters delegate to the owning behaviour.
+When migrating flat server/service files, establish ownership before renaming.
+
 ## AI workflows
 
 For AI work, read `src/ai/README.md` and its examples first. Use `app().ai` and

package/dist/ai/AIErrors.d.ts

@@ -1,3 +1,4 @@
+import type { AIRequestErrorDiagnostics } from './contracts/AIRequestErrorDiagnostics.js';
 /**
  * Raised when an AI operation needs provider credentials but none are configured.
  */
@@ -10,13 +11,18 @@ export declare class AIConfigurationError extends Error {
  */
 export declare class AIRequestError extends Error {
     readonly code: string | null;
+    /** HTTP response status; null when no provider response was received. */
+    readonly status: number | null;
+    /** Provider request identifier for support correlation, when supplied. */
+    readonly requestId: string | null;
     /**
      * Creates a provider request failure.
      *
      * @param message - Human-readable provider failure message.
      * @param code - Stable provider error code, when supplied.
+     * @param diagnostics - Response status and support identifier without the payload.
      */
-    constructor(message?: string, code?: string | null);
+    constructor(message?: string, code?: string | null, diagnostics?: AIRequestErrorDiagnostics);
 }
 /**
  * Raised when the application allowance hook rejects an AI request.

package/dist/ai/AIErrors.js

@@ -13,16 +13,23 @@ export class AIConfigurationError extends Error {
  */
 export class AIRequestError extends Error {
     code;
+    /** HTTP response status; null when no provider response was received. */
+    status;
+    /** Provider request identifier for support correlation, when supplied. */
+    requestId;
     /**
      * Creates a provider request failure.
      *
      * @param message - Human-readable provider failure message.
      * @param code - Stable provider error code, when supplied.
+     * @param diagnostics - Response status and support identifier without the payload.
      */
-    constructor(message = 'The AI provider did not return a valid response.', code = null) {
+    constructor(message = 'The AI provider did not return a valid response.', code = null, diagnostics = {}) {
         super(message);
         this.code = code;
         this.name = 'AIRequestError';
+        this.status = diagnostics.status ?? null;
+        this.requestId = diagnostics.requestId ?? null;
     }
 }
 /**

package/dist/ai/AIFailover.d.ts

@@ -23,3 +23,13 @@ export declare function isFailoverableResponse(status: number, payload: unknown)
  * @returns True when the next provider in the chain should be attempted.
  */
 export declare function isFailoverableFailure(error: unknown): boolean;
+/**
+ * Detects network, DNS, and timeout failures from fetch and SDK clients.
+ *
+ * Undici wraps socket errors inside `TypeError: fetch failed` with the real
+ * failure on `cause`, so the check walks the cause chain.
+ *
+ * @param error - Unknown thrown value.
+ * @returns True when the failure happened before a provider response arrived.
+ */
+export declare function isNetworkFailure(error: unknown, depth?: number): boolean;

package/dist/ai/AIFailover.js

@@ -1,3 +1,4 @@
+import { AIProviderDeferredError, AIProviderStoppedError } from './AIProviderAdmission.js';
 import { AIRateLimitDeferredError } from './AIRateLimiter.js';
 import { openAIProviderError, isOpenAIQuotaError } from './OpenAIProviderError.js';
 const FAILOVERABLE_STATUS_CODES = new Set([408, 409, 429]);
@@ -62,7 +63,7 @@ export function isFailoverableResponse(status, payload) {
  * @returns True when the next provider in the chain should be attempted.
  */
 export function isFailoverableFailure(error) {
-    if (error instanceof AIRateLimitDeferredError)
+    if (error instanceof AIRateLimitDeferredError || error instanceof AIProviderDeferredError || error instanceof AIProviderStoppedError)
         return true;
     if (isNetworkFailure(error))
         return true;
@@ -82,7 +83,7 @@ export function isFailoverableFailure(error) {
  * @param error - Unknown thrown value.
  * @returns True when the failure happened before a provider response arrived.
  */
-function isNetworkFailure(error, depth = 0) {
+export function isNetworkFailure(error, depth = 0) {
     if ((!(error instanceof Error) && !(error instanceof DOMException)) || depth > 4)
         return false;
     if (NETWORK_ERROR_NAMES.has(error.name))

package/dist/ai/AIProviderAdmission.d.ts

@@ -0,0 +1,101 @@
+import { QueueTerminalError, QueueRetryLaterError } from '@db3.ai/app/queue';
+import type { AIProviderAttempt } from './contracts/Providers.js';
+/** Account outage policy, independent of model capacity and application billing. */
+export interface AIProviderAdmissionOptions {
+    /** First transient cooldown; defaults to 30 seconds. */
+    initialSeconds?: number;
+    /** Maximum transient cooldown; defaults to five minutes. */
+    maxSeconds?: number;
+    /** Continuous failure episode deadline; defaults to fifteen minutes. */
+    failureWindowSeconds?: number;
+    /** Recovery ownership lifetime; must exceed the request timeout. Defaults to 90 seconds. */
+    recoveryLeaseSeconds?: number;
+}
+/** Token fences a recovery completion against newer failures and expired leases. */
+export interface AIProviderAdmissionLease {
+    bucketKey: string;
+    generation: string | null;
+    probe: string | null;
+}
+/** Queue backpressure that releases the job's reservation without spending a try. */
+export declare class AIProviderDeferredError extends QueueRetryLaterError {
+    readonly retryAt: Date;
+    readonly retryUntil: Date;
+    /** True only for the request that observed the provider failure. */
+    providerStarted: boolean;
+    /** Recognized rejection diagnostics for the observing request; absent for blocked work. */
+    readonly providerCode: string | null;
+    readonly diagnostics: {
+        status: number | null;
+        requestId: string | null;
+    };
+    /** Creates an account cooldown without retaining provider payloads. */
+    constructor(retryAt: Date, retryUntil: Date, providerCode?: string | null, diagnostics?: {
+        status?: number | null;
+        requestId?: string | null;
+    });
+}
+/** Terminal admission failure; exhausted accounts require explicit operator recovery. */
+export declare class AIProviderStoppedError extends QueueTerminalError {
+    readonly reason: 'quota' | 'outage';
+    /** Stable admission code; original provider code stays separate. */
+    readonly code = "ai_provider_stopped";
+    /** Recognized original rejection code; never an arbitrary provider message. */
+    readonly providerCode: string | null;
+    /** Actual rejection status and provider support identifier; absent for blocked work. */
+    readonly status: number | null;
+    readonly requestId: string | null;
+    /** Distinguishes account admission expiry from an individual run stopped to prevent replay. */
+    readonly stopStage: 'quota' | 'deadline' | 'stream-output';
+    /** True only for the request that observed the provider failure. */
+    providerStarted: boolean;
+    /** Creates a terminal failure without provider credentials or raw error messages. */
+    constructor(reason: 'quota' | 'outage', providerCode?: string | null, diagnostics?: {
+        status?: number | null;
+        requestId?: string | null;
+        stopStage?: 'stream-output';
+    });
+}
+/**
+ * Coordinates account-wide outages using existing SQL bucket metadata.
+ * Closed accounts admit normally. Failed accounts admit one leased real request
+ * after cooldown. Exhaustion and expired episodes remain stopped across restarts;
+ * reset() is an explicit operator action and never executes or replays work.
+ */
+export declare class AIProviderAdmission {
+    #private;
+    /** Validates bounded outage policy; invalid values fail at boot. */
+    constructor(options?: AIProviderAdmissionOptions);
+    /**
+     * Admits normal work or exclusively leases a recovery request under a SQL lock.
+     * Account identity includes provider, origin and a one-way credential digest,
+     * never endpoint/model or website. Other accounts remain independent.
+     */
+    acquire(attempt: AIProviderAttempt, now?: number, requestTimeoutMs?: number): Promise<AIProviderAdmissionLease>;
+    /**
+     * Records an actual provider failure before releasing external admission.
+     * Ordinary 429 capacity never trips an account outage. Late failures extend
+     * the same deadline; they cannot reopen quota or start a fresh episode.
+     */
+    failure(attempt: AIProviderAttempt, lease: AIProviderAdmissionLease, error: unknown, now?: number): Promise<Error | null>;
+    /** Clears an episode only for its still-owned recovery request before deadline. */
+    success(attempt: AIProviderAttempt, lease: AIProviderAdmissionLease, now?: number): Promise<void>;
+    /** Explicit operator reset after repair; does not dispatch, probe or replay jobs. */
+    reset(attempt: AIProviderAttempt): Promise<void>;
+    /**
+     * Wraps each real HTTP request, including SDK model turns and nested tools.
+     * JSON failures and streaming failures trip the same account state. Recovery
+     * is cleared only after body consumption, so header arrival is not recovery.
+     */
+    transport(attempt: AIProviderAttempt, fetcher: typeof fetch, requestTimeoutMs?: number): typeof fetch;
+    /**
+     * Returns the shared cooldown for a safe SDK retry of the current model request.
+     * The SDK vetoes emitted output and cancellation before consulting its policy.
+     * Retains the typed failure until transport actually starts the next attempt,
+     * because its stateful-request veto runs after policy evaluation. Every new
+     * attempt reacquires admission; terminal and cancellation decisions take priority.
+     */
+    requestRetryDelay(attempt: AIProviderAttempt, fallback: unknown, now?: number): number | null;
+    /** Restores a typed HTTP/SSE admission failure after the SDK consumes its original event. */
+    requestFailure(attempt: AIProviderAttempt, fallback: unknown): unknown;
+}