apps 0.0.1-beta.4 → 0.0.1-beta.5

package/types/app-data/src/contracts/database.d.ts

@@ -157,6 +157,33 @@ export declare const DatabaseLimits: Schema.Struct<{
 export type DatabaseLimits = typeof DatabaseLimits.Type;
 /** Current per-invocation budgets, shared by every database adapter. */
 export declare const defaultDatabaseLimits: DatabaseLimits;
+/**
+ * The budget a query or mutation exhausted. `pageSize` bounds one take(n) or paginate call;
+ * `valueBytes` bounds one stored row; the rest accumulate across the whole invocation.
+ */
+export declare const DatabaseLimit: Schema.Literals<readonly ["scanCalls", "directGets", "rowsRead", "rowsReturned", "pageSize", "bytesRead", "writes", "valueBytes"]>;
+export type DatabaseLimit = typeof DatabaseLimit.Type;
+declare const DatabaseLimitExceeded_base: Schema.Class<DatabaseLimitExceeded, Schema.TaggedStruct<"DatabaseLimitExceeded", {
+    readonly limit: Schema.Literals<readonly ["scanCalls", "directGets", "rowsRead", "rowsReturned", "pageSize", "bytesRead", "writes", "valueBytes"]>;
+    readonly maximum: Schema.Int;
+    readonly requested: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** A query or mutation exceeded one of its database budgets. Nothing it wrote is committed. */
+export declare class DatabaseLimitExceeded extends DatabaseLimitExceeded_base {
+    get message(): string;
+}
+/** Host-owned row metadata that authored tables cannot declare. */
+export declare const reservedFieldNames: readonly ["id", "createdAt", "updatedAt"];
+declare const DatabaseFieldReserved_base: Schema.Class<DatabaseFieldReserved, Schema.TaggedStruct<"DatabaseFieldReserved", {
+    readonly table: Schema.String;
+    readonly field: Schema.Literals<readonly ["id", "createdAt", "updatedAt"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A table declared a field the host adds to every row. */
+export declare class DatabaseFieldReserved extends DatabaseFieldReserved_base {
+    get message(): string;
+}
+/** Failures a database session reports to authored code and its host. */
+export type DatabaseError = AppDatabaseError | DatabaseLimitExceeded;
 /** Host resource bounds outside an individual database transaction. Durations are milliseconds. */
 export declare const DatabaseRuntimeLimits: Schema.Struct<{
     readonly maxCursorChars: Schema.Int;
@@ -173,21 +200,21 @@ export declare const defaultDatabaseRuntimeLimits: {
 /** The host binds one database and read/write authority for the entire invocation. */
 export interface DatabaseSession {
     /** Host-only idempotency receipt, committed atomically with the mutation and validated result. */
-    readonly once: <E, R>(key: string, fingerprint: string, work: () => Effect.Effect<Schema.Json, E, R>) => Effect.Effect<Schema.Json, E | AppDatabaseError, R>;
+    readonly once: <E, R>(key: string, fingerprint: string, work: () => Effect.Effect<Schema.Json, E, R>) => Effect.Effect<Schema.Json, E | DatabaseError, R>;
     readonly readTables: ReadonlySet<string>;
     readonly changedTables: ReadonlySet<string>;
-    readonly execute: (operation: DatabaseOperation) => Effect.Effect<OperationResult, AppDatabaseError>;
+    readonly execute: (operation: DatabaseOperation) => Effect.Effect<OperationResult, DatabaseError>;
 }
 /** Native operation scope owns snapshot consistency, write rollback and commit notifications. */
 export interface AppDatabase {
     readonly schema: DatabaseSchema;
     readonly schemaHash: string;
-    readonly read: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | AppDatabaseError, R>;
-    readonly mutate: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | AppDatabaseError, R>;
+    readonly read: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | DatabaseError, R>;
+    readonly mutate: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | DatabaseError, R>;
 }
 /** Product-independent app partitions. A host supplies persistent storage; callers never choose filenames. */
 export interface AppDatabases {
-    readonly read: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError>;
-    readonly mutate: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError>;
+    readonly read: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError>;
+    readonly mutate: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError>;
 }
 export {};

package/types/app-data/src/implementation/schema.d.ts

@@ -1,6 +1,6 @@
 /** Validate declarations and write values before touching SQLite. */
 import { Effect } from "effect";
-import { AppDatabaseError, DatabaseSchema, RowMetadata, type Field, type Row, type Scalar, type Table } from "../contracts/database.js";
+import { AppDatabaseError, DatabaseFieldReserved, DatabaseSchema, RowMetadata, type Field, type Row, type Scalar, type Table } from "../contracts/database.js";
 /** Built-in creation ordering and stable tie-breakers apply to every index. */
 export declare const indexesFor: (table: Table) => {
     name: string;
@@ -11,22 +11,7 @@ export declare const fieldFor: (table: Table, name: string) => Field | undefined
 /** Finite numbers and well-formed strings keep JSON and index ordering consistent. */
 export declare const validScalar: (field: Field, value: unknown) => value is Scalar;
 /** Parse the whole schema, including references and composite-index definitions. */
-export declare const parseDatabaseSchema: (input: unknown) => Effect.Effect<{
-    readonly [x: string]: {
-        readonly fields: {
-            readonly [x: string]: {
-                readonly kind: "string" | "number" | "boolean" | "id" | "userId";
-                readonly optional?: boolean | undefined;
-                readonly default?: string | number | boolean | undefined;
-                readonly references?: string | undefined;
-            };
-        };
-        readonly indexes: readonly {
-            readonly name: string;
-            readonly fields: readonly [string, ...string[]];
-        }[];
-    };
-}, AppDatabaseError, never>;
+export declare const parseDatabaseSchema: (input: unknown) => Effect.Effect<DatabaseSchema, AppDatabaseError | DatabaseFieldReserved>;
 /** Canonical ordering for schema fingerprints and query-bound cursors. */
 export declare const canonicalSchema: (schema: DatabaseSchema) => string;
 /** Inserts apply declared defaults; updates reject unknown/metadata fields and clear optional values with null. */

package/types/apps/src/contracts/failure.d.ts

@@ -0,0 +1,25 @@
+/** Failure detail that crosses the runtime boundary to the app's own caller. */
+import { Schema } from "effect";
+/** Longest failure message carried across the runtime boundary. */
+export declare const maxFailureMessageLength = 2048;
+/**
+ * `app` for errors thrown by authored code, `storage` for app data failures the host raised, and
+ * `service` for an external API the app called through a framework helper.
+ */
+export declare const FailureSource: Schema.Literals<readonly ["app", "storage", "service"]>;
+/** The thrown error's name, such as `TypeError`, or the host error's tag. */
+export declare const FailureName: Schema.String;
+/** A stable host failure code, such as an app data reason. */
+export declare const FailureCode: Schema.String;
+/** Bounded, with the invocation's account secrets replaced. */
+export declare const FailureMessage: Schema.String;
+/**
+ * The error an app's own code raised, or the specific host failure it hit. Stacks and cause
+ * values stay private. Builds from before these fields existed send none.
+ */
+export declare const FailureDetail: {
+    source: Schema.optionalKey<Schema.Literals<readonly ["app", "storage", "service"]>>;
+    errorName: Schema.optionalKey<Schema.String>;
+    code: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+};

package/types/apps/src/contracts/host.d.ts

@@ -8,6 +8,9 @@ export { ProviderError } from "./provider-error.js";
 export { McpError } from "./mcp.js";
 import { WorkflowFailure, type WorkflowExecution, type WorkflowReplay, type WorkflowHostControls } from "./workflows.js";
 export * from "./workflows.js";
+export * from "./failure.js";
+import { DatabaseFieldReserved, DatabaseLimitExceeded } from "../../../app-data/src/contracts/database.js";
+export { DatabaseFieldReserved, DatabaseLimitExceeded } from "../../../app-data/src/contracts/database.js";
 /** Portable framework dispatch contracts. Requests never carry account bindings. */
 import { Context, Schema, type Effect, type Redacted } from "effect";
 import type { AppStorage } from "./storage.js";
@@ -26,8 +29,9 @@ export { OAuthClientAuth, OAuthSecretClientAuth } from "./provider.js";
 export { frameworkProtocol } from "./protocol-version.js";
 export { protocol1 } from "./protocols/1.js";
 export { protocol2 } from "./protocols/2.js";
-import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/2.js";
-export { DeclaredAuthMethod, DeclaredProvider, DeclaredRequirements, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, SkillSources, SkillCatalogResponse, HostRequest, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/2.js";
+export { protocol3 } from "./protocols/3.js";
+import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/3.js";
+export { DeclaredAuthMethod, DeclaredProvider, DeclaredRequirements, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, SkillSources, SkillCatalogResponse, HostRequest, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/3.js";
 /** Raw host inputs; the host boundary parses and redacts these immediately. */
 export type ResolvedAccountsInput = typeof ResolvedAccounts.Encoded;
 /** Trusted invocation context, supplied separately from the Request. */
@@ -80,14 +84,15 @@ export declare const indexCommand: {
 export declare const selectTools: (tools?: readonly string[]) => <A extends {
     readonly name: string;
 }>(all: readonly A[]) => readonly A[];
-/** Declaration reads do not bind accounts or evaluate the app factory. */
-export declare const HostRequirementsError: Schema.Union<readonly [typeof HostRequestInvalid, typeof HostDeclarationInvalid]>;
+/** Declaration reads do not bind accounts or evaluate the app factory. A named declaration
+ * problem, such as a reserved database field, is reported so the deploy can explain it. */
+export declare const HostRequirementsError: Schema.Union<readonly [typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof DatabaseFieldReserved]>;
 /** Inspection can fail while binding accounts or evaluating the live definition. */
 export declare const HostInspectError: Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>;
 /** Tool invocation adds lookup, input, execution and output failures to inspection. */
-export declare const HostCallError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+export declare const HostCallError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
 /** Queries, mutations and agent calls use the same operation failures. */
-export declare const HostDataError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+export declare const HostDataError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
 /** Invocation-owned outcome sink. Framework adapters report semantic failures
  * independently of successful JSON transport; customer output is never inspected. */
 export declare const ToolResultObservation: Context.Reference<{

package/types/apps/src/contracts/openapi.d.ts

@@ -227,5 +227,5 @@ export declare const isOpenapiFileSchema: (shape: Readonly<Record<string, unknow
 /** JSON-safe binary result, independent of the host's file storage. */
 export declare const openapiBinaryResultSchema: JsonObject;
 /** Classify request media for JSON-safe tool arguments; Swagger owns wire serialization. */
-export declare const openapiMediaKind: (type: string) => "form" | "text" | "binary" | "json" | "multipart";
+export declare const openapiMediaKind: (type: string) => "form" | "binary" | "json" | "multipart" | "text";
 export {};

package/types/apps/src/contracts/protocol-version.d.ts

@@ -1,6 +1,6 @@
 /**
  * The host protocol this framework speaks. It is written into `runtime.json` and every host
- * snapshot. Released protocols are frozen: see `protocols/1.ts` and notes/apps-publishing.md.
+ * snapshot. Released protocols are frozen: see `protocols/3.ts` and notes/apps-publishing.md.
  * This file has no imports so the package build script can read it directly.
  */
-export declare const frameworkProtocol = 2;
+export declare const frameworkProtocol = 3;

package/types/apps/src/contracts/protocols/1.d.ts

@@ -15,7 +15,21 @@ import { ElicitationFailed } from "../elicitation.js";
 import { McpError } from "../mcp.js";
 import { ProviderError } from "../provider-error.js";
 import { SkillLoadFailed } from "../skills.js";
-import { WorkflowFailure } from "../workflows.js";
+declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedStruct<"WorkflowFailure", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    readonly retryable: Schema.Boolean;
+}>, import("effect/Cause").YieldableError>;
+/** Protocol 1's workflow failure: a reason code only, as released. */
+export declare class WorkflowFailure extends WorkflowFailure_base {
+}
+/** Protocol 1's workflow step reply, carrying its own failure. */
+export declare const WorkflowRpcResult: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: typeof WorkflowFailure;
+}>]>;
 /** Serializable auth methods shared with SDK hosts; protocol configuration has one schema. */
 export declare const DeclaredAuthMethod: Schema.Union<readonly [Schema.Struct<{
     readonly type: Schema.Literal<"secrets">;

package/types/apps/src/contracts/protocols/2.d.ts

@@ -397,7 +397,7 @@ export declare const protocol2: {
             readonly toolError: Schema.optionalKey<Schema.Literal<true>>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: Schema.Union<readonly [typeof import("../api-response-error.js").OpenapiResponseError, typeof import("../provider-error.js").ProviderError, typeof import("../mcp.js").McpError, typeof import("../skills.js").SkillLoadFailed, typeof import("../workflows.js").WorkflowFailure, typeof import("./1.js").HostRequestInvalid, typeof import("./1.js").HostAccountsInvalid, typeof import("./1.js").HostDeclarationInvalid, typeof import("./1.js").HostEvaluationFailed, typeof import("./1.js").HostOperationNotFound, typeof import("./1.js").HostOperationFailed, typeof import("./1.js").HostToolNotFound, typeof import("./1.js").HostInputInvalid, typeof import("./1.js").HostOutputInvalid, typeof import("./1.js").HostToolBlocked, typeof import("./1.js").HostToolApprovalRequired, typeof import("./1.js").HostToolPolicyFailed, typeof import("../elicitation.js").ElicitationFailed]>;
+            readonly error: Schema.Union<readonly [typeof import("../api-response-error.js").OpenapiResponseError, typeof import("../provider-error.js").ProviderError, typeof import("../mcp.js").McpError, typeof import("../skills.js").SkillLoadFailed, typeof import("./1.js").WorkflowFailure, typeof import("./1.js").HostRequestInvalid, typeof import("./1.js").HostAccountsInvalid, typeof import("./1.js").HostDeclarationInvalid, typeof import("./1.js").HostEvaluationFailed, typeof import("./1.js").HostOperationNotFound, typeof import("./1.js").HostOperationFailed, typeof import("./1.js").HostToolNotFound, typeof import("./1.js").HostInputInvalid, typeof import("./1.js").HostOutputInvalid, typeof import("./1.js").HostToolBlocked, typeof import("./1.js").HostToolApprovalRequired, typeof import("./1.js").HostToolPolicyFailed, typeof import("../elicitation.js").ElicitationFailed]>;
         }>]>;
         readonly requirements: Schema.Struct<{
             readonly capabilities: Schema.optionalKey<Schema.Struct<{
@@ -593,7 +593,7 @@ export declare const protocol2: {
             readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
         }>, Schema.Struct<{
             readonly ok: Schema.Literal<false>;
-            readonly error: typeof import("../workflows.js").WorkflowFailure;
+            readonly error: typeof import("./1.js").WorkflowFailure;
         }>]>;
         readonly workflowControl: Schema.Union<readonly [Schema.Struct<{
             readonly operation: Schema.Literal<"start">;