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

package/dist/ai/chunkEmbeddingText.js

@@ -0,0 +1,147 @@
+import { Tiktoken } from 'js-tiktoken/lite';
+import cl100kBase from 'js-tiktoken/ranks/cl100k_base';
+let tokenizer;
+/** Counts ordinary text, including literal special-token spellings, with cl100k_base. */
+function tokens(text) {
+    tokenizer ??= new Tiktoken(cl100kBase);
+    return tokenizer.encode(text, [], []).length;
+}
+/**
+ * Keeps fitting documents whole and splits oversized Markdown at natural boundaries.
+ * Each passage retains source offsets, bounded shared context, its heading hierarchy
+ * and a small overlap. Uses cl100k_base, as used by text-embedding-3-small/large.
+ * No provider requests or generated summaries are involved.
+ *
+ * @param text - Extracted text or Markdown; HTML extraction belongs to the caller.
+ * @param options - Context and token budgets for the complete embedding input.
+ * @returns Ordered passages whose source ranges cover all of the original text.
+ * @example
+ * const chunks = chunkEmbeddingText(page.text, { context: `Title: ${page.title}` });
+ */
+export function chunkEmbeddingText(text, options = {}) {
+    const maximum = options.maxTokens ?? 8000;
+    const overlap = options.overlapTokens ?? Math.min(128, Math.floor(maximum / 8));
+    if (!Number.isInteger(maximum) || maximum < 64 || maximum > 8191)
+        throw new Error('Embedding chunks require maxTokens between 64 and 8191.');
+    if (!Number.isInteger(overlap) || overlap < 0 || overlap >= maximum / 2)
+        throw new Error('Embedding overlap must be non-negative and smaller than half the input budget.');
+    if (!text.trim())
+        return [];
+    const contextBudget = Math.min(512, Math.floor(maximum / 8));
+    const context = boundedPrefix(options.context?.trim() ?? '', contextBudget);
+    const headings = markdownHeadings(text);
+    const chunks = [];
+    const fullInput = embeddingInput(context, null, text);
+    if (tokens(fullInput) <= maximum)
+        return [{ index: 0, text, heading: null, input: fullInput, start: 0, end: text.length, tokens: tokens(fullInput) }];
+    let start = 0;
+    let contentStart = 0;
+    while (start < text.length) {
+        const activeHeading = headings.filter(heading => heading.start <= contentStart).at(-1)?.title ?? null;
+        const heading = activeHeading ? boundedPrefix(activeHeading, contextBudget) : null;
+        const prefix = embeddingInput(context, heading, '');
+        const available = maximum - tokens(prefix) - 8;
+        let end = start + fittingPrefixLength(text.slice(start), available);
+        if (end < text.length)
+            end = naturalBoundary(text, start, end, headings.map(item => item.start));
+        let input = embeddingInput(context, heading, text.slice(start, end));
+        // BPE merges across the prefix boundary are verified against the final input.
+        while (tokens(input) > maximum && end > start) {
+            end = previousCharacter(text, end);
+            input = embeddingInput(context, heading, text.slice(start, end));
+        }
+        if (end <= start)
+            throw new Error('Embedding context leaves no room for source text.');
+        chunks.push({ index: chunks.length, text: text.slice(start, end), heading, input, start, end, tokens: tokens(input) });
+        if (end === text.length)
+            break;
+        contentStart = end;
+        const previousText = text.slice(start, end);
+        const overlapStart = overlap ? fittingSuffixStart(previousText, overlap) + start : end;
+        // Prefer a whole final paragraph when it fits inside the overlap budget.
+        const paragraphStart = text.lastIndexOf('\n\n', end - 3) + 2;
+        start = paragraphStart >= overlapStart && paragraphStart < end && paragraphStart > start
+            ? paragraphStart : overlapStart > start ? overlapStart : end;
+    }
+    return chunks;
+}
+/** Builds a deterministic context prefix without rewriting source evidence. */
+function embeddingInput(context, heading, text) {
+    return `${context ? `${context}\n` : ''}${heading ? `section: ${heading}\n` : ''}content:\n${text}`;
+}
+/** Finds a token-bounded prefix without cutting a Unicode code point. */
+function fittingPrefixLength(text, maximum) {
+    if (tokens(text) <= maximum)
+        return text.length;
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (tokens(text.slice(0, middle)) <= maximum)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    if (low > 0 && /[\uD800-\uDBFF]/.test(text[low - 1]))
+        low -= 1;
+    return low;
+}
+/** Bounds repeated context so even unusually long metadata leaves room for source text. */
+function boundedPrefix(text, maximum) {
+    return text.slice(0, fittingPrefixLength(text, maximum)).trim();
+}
+/** Locates a bounded overlap suffix on Unicode code-point boundaries. */
+function fittingSuffixStart(text, maximum) {
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (tokens(text.slice(middle)) <= maximum)
+            high = middle;
+        else
+            low = middle + 1;
+    }
+    if (/[\uDC00-\uDFFF]/.test(text[low] ?? ''))
+        low += 1;
+    return low;
+}
+/** Moves backwards by one Unicode code point. */
+function previousCharacter(text, end) {
+    return end > 1 && /[\uDC00-\uDFFF]/.test(text[end - 1]) ? end - 2 : end - 1;
+}
+/** Prefers a heading or paragraph boundary, then sentences and whitespace, without emitting tiny fragments. */
+function naturalBoundary(text, start, end, headings) {
+    const minimum = start + Math.floor((end - start) / 2);
+    const heading = headings.filter(position => position >= minimum && position <= end).at(-1);
+    if (heading !== undefined)
+        return heading;
+    const candidate = text.slice(minimum, end);
+    for (const pattern of [/\n\s*\n/g, /[.!?。！？][\s]+/g, /\s+/g]) {
+        const match = [...candidate.matchAll(pattern)].at(-1);
+        if (match)
+            return minimum + match.index + match[0].length;
+    }
+    return end;
+}
+/** Reads Markdown heading ancestry while ignoring headings inside fenced code blocks. */
+function markdownHeadings(text) {
+    const headings = [];
+    const hierarchy = [];
+    let fence = null;
+    for (const line of text.matchAll(/^.*(?:\n|$)/gm)) {
+        const delimiter = line[0].match(/^\s*(`{3,}|~{3,})/)?.[1];
+        if (delimiter) {
+            fence = fence ? (delimiter[0] === fence[0] ? null : fence) : delimiter;
+            continue;
+        }
+        if (fence)
+            continue;
+        const heading = line[0].match(/^(#{1,6})\s+(.+?)(?:\s+#+)?\s*$/);
+        if (!heading)
+            continue;
+        hierarchy.length = heading[1].length;
+        hierarchy[heading[1].length - 1] = heading[2];
+        headings.push({ start: line.index, title: hierarchy.filter(Boolean).join(' > ') });
+    }
+    return headings;
+}

package/dist/ai/contracts/AI.d.ts

@@ -1,3 +1,4 @@
+import type { AIServiceTier } from './AIServiceTier.js';
 import type { TextResponsePayload } from '@db3.ai/pure';
 import type { ZodType } from 'zod';
 import type { AiConversation } from '../AiConversation.js';
@@ -125,6 +126,8 @@ export interface AIOptions {
     fetch?: typeof fetch;
     /** Rate limiter used before provider requests. Pass false only in isolated tests. */
     rateLimiter?: AIRateLimiter | false;
+    /** Durable account admission policy; capacity limiter disabling never bypasses it. */
+    providerAdmission?: import('../AIProviderAdmission.js').AIProviderAdmissionOptions;
     /** Optional customer allowance hook. Defaults to no-op until billing limits exist. */
     allowance?: AIAllowanceChecker | false;
 }
@@ -132,6 +135,10 @@ export interface AIOptions {
  * Plain text request sent to the Responses API.
  */
 export interface GenerateTextInput {
+    /** Keep transient failures local to optional work; account quota and existing admission stops still apply. */
+    transientFailureScope?: 'account' | 'request';
+    /** Explicit OpenAI processing tier; defaults to Standard. No automatic tier fallback. */
+    serviceTier?: AIServiceTier;
     /** Optional per-call model override for the OpenAI provider entry. */
     model?: string;
     /** Optional provider failover chain overriding the app default for this call. */
@@ -203,6 +210,10 @@ export interface AIResponseLogOptions extends Record<string, unknown> {
 }
 /** Untrusted provider text response, including optional token usage. */
 export interface TextResponsePayloadWithUsage extends TextResponsePayload {
+    /** Actual model reported by the provider for billing. */
+    model?: unknown;
+    /** Actual processing tier reported by OpenAI, not the requested tier. */
+    service_tier?: unknown;
     /** Provider completion status; omitted by some compatible endpoints. */
     status?: unknown;
     usage?: unknown;
@@ -345,3 +356,8 @@ export interface AIModels {
     request: typeof AiRequest;
     message: typeof import('../AiMessage.js').AiMessage;
 }
+/** Embedding persistence policy for workflows that must resume partial provider work. */
+export interface GenerateEmbeddingOptions extends RequestLogOptions {
+    /** Persist the completed vector in the existing request response for authorized resume. Defaults to false. */
+    retainResult?: boolean;
+}

package/dist/ai/contracts/AIRequestErrorDiagnostics.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider response identifiers retained on a direct AI request failure.
+ *
+ * These fields exclude response bodies, credentials and customer inputs. Missing
+ * fields stay unknown rather than inferring an HTTP status from an error message.
+ */
+export interface AIRequestErrorDiagnostics {
+    /** HTTP response status, when a provider response was received. */
+    status?: number | null;
+    /** Provider request identifier from response headers, for support correlation. */
+    requestId?: string | null;
+}

package/dist/ai/contracts/AIRequestErrorDiagnostics.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/contracts/AIServiceTier.d.ts

@@ -0,0 +1,2 @@
+/** OpenAI processing tier. Default preserves Standard pricing; Flex is opt-in. */
+export type AIServiceTier = 'default' | 'flex' | 'fast' | 'priority';

package/dist/ai/contracts/AIServiceTier.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/contracts/Agent.d.ts

@@ -3,6 +3,7 @@ import type { QueueJobId } from '@db3.ai/app/queue';
 import type { SerializedValueEnvelope } from '@db3.ai/app/serialization';
 import type { AiConversation } from '../AiConversation.js';
 import type { AiRequest, AiRequestRunCostSummary } from '../AiRequest.js';
+import type { AIServiceTier } from './AIServiceTier.js';
 import type { AgentCitation } from '@db3.ai/pure';
 export type { AgentCitation } from '@db3.ai/pure';
 /**
@@ -359,6 +360,8 @@ export interface BaseAgentContext {
  * Serializable payload stored on the queue for deferred agent execution.
  */
 export interface QueuedAgentRunPayload extends Record<string, unknown> {
+    /** Captured processing tier. Legacy payloads retain Standard processing. */
+    serviceTier?: AIServiceTier;
     /**
      * Registered agent name used for worker registration and queue observability.
      */

package/dist/ai/contracts/EmbeddingTextChunk.d.ts

@@ -0,0 +1,25 @@
+/** A source-backed passage prepared for the cl100k_base OpenAI embedding models. */
+export interface EmbeddingTextChunk {
+    /** Zero-based position within this source revision. */
+    index: number;
+    /** Exact source slice, including any overlap with the preceding chunk. */
+    text: string;
+    /** Heading hierarchy active at the new source text, excluding preceding overlap. */
+    heading: string | null;
+    /** Complete provider input, with bounded source context and heading prefix. */
+    input: string;
+    /** UTF-16 offsets into the original text; end is exclusive. */
+    start: number;
+    end: number;
+    /** Token count of the complete input, including context and overlap. */
+    tokens: number;
+}
+/** Controls deterministic text preparation; callers retain extraction, storage and authorization. */
+export interface EmbeddingTextChunkOptions {
+    /** Source title, description or other trusted context repeated on every passage. */
+    context?: string;
+    /** Complete input ceiling, including prefixes. Defaults to 8,000; cannot exceed 8,191. */
+    maxTokens?: number;
+    /** Maximum preceding text carried into the next passage. Defaults to 128 tokens. */
+    overlapTokens?: number;
+}

package/dist/ai/contracts/EmbeddingTextChunk.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/contracts/Pricing.d.ts

@@ -5,13 +5,15 @@
  * the rates. `outputUSDPer1M` is null for input-only models such as embeddings.
  */
 export interface AIModelPricing {
+    /** Verified tier multipliers for this model only; absent tiers remain unpriced. */
+    serviceTierMultipliers?: Partial<Record<'flex' | 'fast' | 'priority', number>>;
     inputUSDPer1M: number;
     cachedInputUSDPer1M: number | null;
     outputUSDPer1M: number | null;
     /**
      * Multiplier applied to input tokens written into the provider prompt cache.
      *
-     * GPT-5.6 and GPT-6 Astra report cache writes separately and bill them above
+     * GPT-5.6 and GPT-6 models report cache writes separately and bill them above
      * the ordinary uncached input rate. Models without that charge omit it.
      */
     cacheWriteInputMultiplier?: number;
@@ -45,6 +47,8 @@ export interface AIImageModelPricing {
  * Normalized token counts captured from a tracked AI provider response.
  */
 export interface AIRequestCostUsage {
+    /** Actual provider tier. Undefined retains legacy Standard; null means unknown. */
+    serviceTier?: string | null;
     inputTokens: number | null;
     outputTokens: number | null;
     cachedTokens?: number | null;
@@ -55,6 +59,8 @@ export interface AIRequestCostUsage {
  * Per-provider-request usage retained from an aggregate Agents SDK run.
  */
 export interface AIRequestCostUsageEntry extends AIRequestCostUsage {
+    /** Actual provider model, when supplied with this completed response. */
+    model?: string;
     /** Provider endpoint that reported this usage entry, when available. */
     endpoint?: string;
 }

package/dist/ai/contracts/Providers.d.ts

@@ -21,6 +21,8 @@ export interface AIProviderConfig {
  * One resolved, fully configured provider attempt in a failover chain.
  */
 export interface AIProviderAttempt {
+    /** Optional work isolates transient transport failures; quota and existing account stops remain shared. */
+    transientFailureScope?: 'account' | 'request';
     /** Stable provider id persisted on tracking rows and bucket keys. */
     provider: AIProvider;
     /** Model sent to this provider. */

package/dist/ai/contracts/index.d.ts

@@ -1,4 +1,5 @@
 export * from './AI.js';
+export * from './EmbeddingTextChunk.js';
 export * from './Agent.js';
 export * from './AiRequestRunCostSummary.js';
 export * from './Pricing.js';
@@ -6,3 +7,4 @@ export * from './Providers.js';
 export * from './RateLimits.js';
 export * from './ResponsesProviderCall.js';
 export * from './QuotaRetry.js';
+export type { AIRequestErrorDiagnostics } from './AIRequestErrorDiagnostics.js';

package/dist/ai/contracts/index.js

@@ -1,4 +1,5 @@
 export * from './AI.js';
+export * from './EmbeddingTextChunk.js';
 export * from './Agent.js';
 export * from './AiRequestRunCostSummary.js';
 export * from './Pricing.js';

package/dist/ai/index.d.ts

@@ -1,5 +1,9 @@
 export * from './Ai.js';
+export type { AIServiceTier } from './contracts/AIServiceTier.js';
+export { chunkEmbeddingText } from './chunkEmbeddingText.js';
+export type { EmbeddingTextChunk, EmbeddingTextChunkOptions } from './contracts/EmbeddingTextChunk.js';
 export * from './AIErrors.js';
+export * from './AIRequestTrackingError.js';
 export * from './contracts/AI.js';
 export * from './AiConversation.js';
 export * from './AiMessage.js';
@@ -11,7 +15,7 @@ export * from './AIProviders.js';
 export * from './AIQuotaDeferredError.js';
 export * from './AIRateLimiter.js';
 export * from './Estimates.js';
-export * from './Models.js';
+export * from './modelPricing.js';
 export * from './OpenAIProviderError.js';
 export * from './ProviderCosts.js';
 export * from './Agent.js';
@@ -23,5 +27,7 @@ export * from './agentCitations.js';
 export * from './OpenAIQuotaRetry.js';
 export * from './ResponsesProviderCall.js';
 export { agentConversationTimeline } from './AgentHistory.js';
-export { tool, webSearchTool, fileSearchTool, imageGenerationTool } from '@openai/agents';
+export { tool, computerTool, type Computer, webSearchTool, fileSearchTool, imageGenerationTool } from '@openai/agents';
 export { INTERRUPTED_TOOL_CALL_MESSAGE, unresolvedToolCallIds } from './toolCallRecovery.js';
+export type { AIRequestErrorDiagnostics } from './contracts/AIRequestErrorDiagnostics.js';
+export * from './AIProviderAdmission.js';

package/dist/ai/index.js

@@ -1,5 +1,7 @@
 export * from './Ai.js';
+export { chunkEmbeddingText } from './chunkEmbeddingText.js';
 export * from './AIErrors.js';
+export * from './AIRequestTrackingError.js';
 export * from './contracts/AI.js';
 export * from './AiConversation.js';
 export * from './AiMessage.js';
@@ -11,7 +13,7 @@ export * from './AIProviders.js';
 export * from './AIQuotaDeferredError.js';
 export * from './AIRateLimiter.js';
 export * from './Estimates.js';
-export * from './Models.js';
+export * from './modelPricing.js';
 export * from './OpenAIProviderError.js';
 export * from './ProviderCosts.js';
 export * from './Agent.js';
@@ -23,5 +25,6 @@ export * from './agentCitations.js';
 export * from './OpenAIQuotaRetry.js';
 export * from './ResponsesProviderCall.js';
 export { agentConversationTimeline } from './AgentHistory.js';
-export { tool, webSearchTool, fileSearchTool, imageGenerationTool } from '@openai/agents';
+export { tool, computerTool, webSearchTool, fileSearchTool, imageGenerationTool } from '@openai/agents';
 export { INTERRUPTED_TOOL_CALL_MESSAGE, unresolvedToolCallIds } from './toolCallRecovery.js';
+export * from './AIProviderAdmission.js';

package/dist/ai/{Models.d.ts → modelPricing.d.ts}

@@ -1,10 +1,10 @@
 import type { AIModelPricing, AIImageModelPricing, AIRequestCostUsage, AIRequestCostUsageEntry, AIImageRequestCostUsage, AIHostedToolUsage, AIHostedToolCost } from './contracts/Pricing.js';
 export type { AIModelPricing, AIImageModelPricing, AIRequestCostUsage, AIRequestCostUsageEntry, AIImageRequestCostUsage, AIHostedToolUsage, AIHostedToolCost } from './contracts/Pricing.js';
 /**
- * OpenAI Standard processing prices in USD, verified on 2026-09-11.
+ * OpenAI Standard processing prices in USD, verified on 2026-09-25.
  *
  * Used to estimate request cost at write time; stored historical costs are not
- * recalculated. Excludes regional processing surcharges and other service tiers.
+ * recalculated. Excludes regional processing surcharges. Tier multipliers were verified on 2026-10-08.
  *
  * @see https://developers.openai.com/api/docs/pricing
  */

package/dist/ai/{Models.js → modelPricing.js}

@@ -1,13 +1,20 @@
 /**
- * OpenAI Standard processing prices in USD, verified on 2026-09-11.
+ * OpenAI Standard processing prices in USD, verified on 2026-09-25.
  *
  * Used to estimate request cost at write time; stored historical costs are not
- * recalculated. Excludes regional processing surcharges and other service tiers.
+ * recalculated. Excludes regional processing surcharges. Tier multipliers were verified on 2026-10-08.
  *
  * @see https://developers.openai.com/api/docs/pricing
  */
 export const AI_MODEL_PRICING = {
+    // Default lightweight agent model; Standard rates verified on 2026-10-01.
+    'gpt-4.1-mini': {
+        inputUSDPer1M: 0.40,
+        cachedInputUSDPer1M: 0.10,
+        outputUSDPer1M: 1.60,
+    },
     'gpt-6-astra': {
+        serviceTierMultipliers: { flex: 0.5, fast: 2, priority: 2 },
         inputUSDPer1M: 10.00,
         cachedInputUSDPer1M: 1.00,
         outputUSDPer1M: 50.00,
@@ -16,8 +23,29 @@ export const AI_MODEL_PRICING = {
         longContextInputMultiplier: 2,
         longContextOutputMultiplier: 1.5,
     },
+    'gpt-6-sol': {
+        serviceTierMultipliers: { flex: 0.5, fast: 2, priority: 2 },
+        inputUSDPer1M: 2.00,
+        cachedInputUSDPer1M: 0.20,
+        outputUSDPer1M: 10.00,
+        cacheWriteInputMultiplier: 1.25,
+        longContextInputTokenThreshold: 272_000,
+        longContextInputMultiplier: 2,
+        longContextOutputMultiplier: 1.5,
+    },
+    'gpt-6-luna': {
+        serviceTierMultipliers: { flex: 0.5, fast: 2, priority: 2 },
+        inputUSDPer1M: 0.10,
+        cachedInputUSDPer1M: 0.01,
+        outputUSDPer1M: 0.50,
+        cacheWriteInputMultiplier: 1.25,
+        longContextInputTokenThreshold: 272_000,
+        longContextInputMultiplier: 2,
+        longContextOutputMultiplier: 1.5,
+    },
     // Promotional rates available at least through 2026-11-21; recheck before changing.
     'gpt-5.6-sol': {
+        serviceTierMultipliers: { flex: 0.5, fast: 2, priority: 2 },
         inputUSDPer1M: 4.00,
         cachedInputUSDPer1M: 0.40,
         outputUSDPer1M: 20.00,
@@ -27,6 +55,7 @@ export const AI_MODEL_PRICING = {
         longContextOutputMultiplier: 1.5,
     },
     'gpt-5.6-terra': {
+        serviceTierMultipliers: { flex: 0.5, fast: 2, priority: 2 },
         inputUSDPer1M: 2.00,
         cachedInputUSDPer1M: 0.20,
         outputUSDPer1M: 12.00,
@@ -36,6 +65,7 @@ export const AI_MODEL_PRICING = {
         longContextOutputMultiplier: 1.5,
     },
     'gpt-5.6-luna': {
+        serviceTierMultipliers: { flex: 0.5, fast: 2, priority: 2 },
         inputUSDPer1M: 0.20,
         cachedInputUSDPer1M: 0.02,
         outputUSDPer1M: 1.20,
@@ -149,6 +179,10 @@ export function calculateAIRequestCostUSD(model, usage) {
     const pricing = AI_MODEL_PRICING[canonicalModelName(model)];
     if (!pricing)
         return null;
+    const tier = usage.serviceTier === undefined ? 'default' : usage.serviceTier;
+    const tierMultiplier = tier === 'default' ? 1 : tier === 'flex' || tier === 'fast' || tier === 'priority' ? pricing.serviceTierMultipliers?.[tier] : undefined;
+    if (tierMultiplier === undefined)
+        return null;
     if (!validTokenCount(usage.inputTokens))
         return null;
     if (pricing.outputUSDPer1M !== null && !validTokenCount(usage.outputTokens))
@@ -173,7 +207,7 @@ export function calculateAIRequestCostUSD(model, usage) {
     const cost = ((uncachedInputTokens * inputRate)
         + (cachedTokens * cachedInputRate)
         + (cacheWriteTokens * cacheWriteInputRate)
-        + (outputTokens * outputRate)) / TOKENS_PER_PRICING_UNIT;
+        + (outputTokens * outputRate)) * tierMultiplier / TOKENS_PER_PRICING_UNIT;
     return Math.round(cost * COST_PRECISION) / COST_PRECISION;
 }
 /**
@@ -191,7 +225,7 @@ export function calculateAIRequestEntriesCostUSD(model, entries) {
         return null;
     let cost = 0;
     for (const entry of entries) {
-        const entryCost = calculateAIRequestCostUSD(model, entry);
+        const entryCost = calculateAIRequestCostUSD(entry.model ?? model, entry);
         if (entryCost === null)
             return null;
         cost += entryCost;

package/dist/apps/AppInstallation.d.ts

@@ -0,0 +1,21 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+import type { AppDescription, AppInstallationState } from './contracts/index.js';
+/** Framework-owned record retained after code removal; business tables and migration ledgers stay separate. */
+export declare class AppInstallation extends ActiveRecord {
+    static table: string;
+    /** Defines durable installation identity, desired state and retained ownership evidence. */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        appId: import("../db/index.js").StringField;
+        version: import("../db/index.js").StringField;
+        state: import("../db/index.js").StringField;
+        description: import("../db/index.js").JsonField<AppDescription | null>;
+        migrationHashes: import("../db/index.js").JsonField<Record<string, string> | null>;
+    };
+    id: string | null;
+    appId: string;
+    version: string;
+    state: AppInstallationState;
+    description: AppDescription;
+    migrationHashes: Record<string, string>;
+}

package/dist/apps/AppInstallation.js

@@ -0,0 +1,16 @@
+import { ActiveRecord } from '../db/index.js';
+/** Framework-owned record retained after code removal; business tables and migration ledgers stay separate. */
+export class AppInstallation extends ActiveRecord {
+    static table = 'db3_apps';
+    /** Defines durable installation identity, desired state and retained ownership evidence. */
+    static fields(field) {
+        return {
+            id: field.ulid(),
+            appId: field.string({ column: 'app_id', required: true, length: 48, unique: true }),
+            version: field.string({ required: true, length: 64 }),
+            state: field.string({ required: true, length: 24 }),
+            description: field.json({ required: true }),
+            migrationHashes: field.json({ column: 'migration_hashes', required: true }),
+        };
+    }
+}

package/dist/apps/AppRouteError.d.ts

@@ -0,0 +1,6 @@
+/** Deliberately public HTTP failure from an app route. Other errors remain private to server logs. */
+export declare class AppRouteError extends Error {
+    readonly statusCode: 400 | 401 | 403 | 404 | 409 | 503;
+    /** Creates a safe client-facing error; use only for expected validation and access failures. */
+    constructor(statusCode: 400 | 401 | 403 | 404 | 409 | 503, message: string);
+}

package/dist/apps/AppRouteError.js

@@ -0,0 +1,10 @@
+/** Deliberately public HTTP failure from an app route. Other errors remain private to server logs. */
+export class AppRouteError extends Error {
+    statusCode;
+    /** Creates a safe client-facing error; use only for expected validation and access failures. */
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'AppRouteError';
+    }
+}

package/dist/apps/AppService.d.ts

@@ -0,0 +1,24 @@
+import type { ActiveRecordClass } from '../db/index.js';
+import type { QueueableJobClass } from '../queue/index.js';
+import type { Schedule } from '../scheduler/index.js';
+import type { App as HostApp } from '../server/App.js';
+import type { AppNavigation, AppNavigationContext, AppRoute, AppStartContext } from './contracts/index.js';
+/** Base for a discovered app's root App.ts. The instance is exposed as app().social, for example. */
+export declare class AppService {
+    protected readonly host: HostApp;
+    static models: readonly ActiveRecordClass[];
+    static routes: readonly AppRoute<any>[];
+    static jobs: readonly QueueableJobClass[];
+    /** Receives the existing host; an installed app never creates a second framework runtime. */
+    constructor(host: HostApp);
+    /** Computes navigation for this viewer. Undefined uses manifest links; null hides the app. Keep viewer data off this shared instance. */
+    navigation(_context: AppNavigationContext): Promise<AppNavigation | null | undefined>;
+    /** Declares recurring work during boot. Delegate to the app's schedule.ts; declarations must be synchronous. */
+    schedule(_schedule: Schedule): void;
+    /** Starts resources after dependencies are ready. Register cleanup immediately using context.defer. */
+    start(_context: AppStartContext<this>): Promise<void>;
+    /** Runs after migrations on every install or upgrade. Implementations must tolerate retries. */
+    install(): Promise<void>;
+    /** Checks and releases durable app-specific registrations. Database tables are retained by default. */
+    uninstall(): Promise<void>;
+}

package/dist/apps/AppService.js

@@ -0,0 +1,21 @@
+/** Base for a discovered app's root App.ts. The instance is exposed as app().social, for example. */
+export class AppService {
+    host;
+    static models = [];
+    static routes = [];
+    static jobs = [];
+    /** Receives the existing host; an installed app never creates a second framework runtime. */
+    constructor(host) {
+        this.host = host;
+    }
+    /** Computes navigation for this viewer. Undefined uses manifest links; null hides the app. Keep viewer data off this shared instance. */
+    async navigation(_context) { return undefined; }
+    /** Declares recurring work during boot. Delegate to the app's schedule.ts; declarations must be synchronous. */
+    schedule(_schedule) { }
+    /** Starts resources after dependencies are ready. Register cleanup immediately using context.defer. */
+    async start(_context) { }
+    /** Runs after migrations on every install or upgrade. Implementations must tolerate retries. */
+    async install() { }
+    /** Checks and releases durable app-specific registrations. Database tables are retained by default. */
+    async uninstall() { }
+}