apps 0.0.1-beta.1 → 0.0.1-beta.11

package/types/app-cache/src/contracts/cache.d.ts

@@ -16,7 +16,17 @@ export declare const cacheLimits: {
     readonly totalEntries: 100000;
     readonly retentionMs: number;
     readonly loadTimeoutMs: 90000;
-    readonly leaseMs: 120000;
+    /**
+     * A loader's lease lapses this long after its host last renewed it. Hosts renew every
+     * `renewMs` while the invocation that claimed it runs, so a stalled or lost holder frees the
+     * key well inside an MCP execute budget.
+     */
+    readonly leaseMs: 15000;
+    readonly renewMs: 5000;
+    /** The longest a caller waits on another loader before loading for itself without publishing. */
+    readonly waitMs: 10000;
+    /** Bound for one command to a host store; a lost reply fails instead of holding its caller. */
+    readonly commandTimeoutMs: 10000;
 };
 /** Stored values carry a version independent of their freshness clock. */
 export declare const CacheEntry: Schema.Struct<{
@@ -27,10 +37,31 @@ export declare const CacheEntry: Schema.Struct<{
 }>;
 /** Decoded cache value envelope. */
 export type CacheEntry = typeof CacheEntry.Type;
-/** Publication requires the lease acquired against the previously observed version. */
+/** The current entry, and a lease when this caller now owns its load. */
+export declare const CacheAcquired: Schema.Struct<{
+    readonly entry: Schema.NullOr<Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly version: Schema.String;
+        readonly freshUntil: Schema.Finite;
+        readonly staleUntil: Schema.Finite;
+    }>>;
+    readonly lease: Schema.NullOr<Schema.String>;
+}>;
+/**
+ * Publication requires the lease acquired against the previously observed version.
+ * `acquire` reads one entry and claims its load in the same transaction, so a cache
+ * miss costs one round trip. `read` and `claim` remain for builds retained before it.
+ */
 export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
     readonly operation: Schema.Literal<"read">;
     readonly keys: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"acquire">;
+    readonly key: Schema.String;
+    /** Claim even a fresh entry, as an explicit refresh does. */
+    readonly refresh: Schema.Boolean;
+    /** Claim only while the entry still has this version. Absent accepts the current one. */
+    readonly version: Schema.optionalKey<Schema.NullOr<Schema.String>>;
 }>, Schema.Struct<{
     readonly operation: Schema.Literal<"claim">;
     readonly key: Schema.String;
@@ -49,6 +80,10 @@ export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
     readonly operation: Schema.Literal<"release">;
     readonly key: Schema.String;
     readonly lease: Schema.String;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"renew">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
 }>, Schema.Struct<{
     readonly operation: Schema.Literal<"write">;
     readonly entries: Schema.$Array<Schema.Struct<{
@@ -68,6 +103,11 @@ export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
 export type CacheCommand = typeof CacheCommand.Type;
 /** Replies remain JSON across Worker RPC and are decoded by each caller. */
 export type CacheTransport = (command: CacheCommand) => Effect.Effect<Schema.Json, CacheError>;
+/**
+ * Whether a command replaced or removed retained data: a published refresh, a direct write or an
+ * invalidation. Hosts report these so results evaluated from the earlier data are not reused.
+ */
+export declare const changesCache: (command: unknown) => boolean;
 /** Safe protocol envelope used at process boundaries. */
 export declare const CacheReply: Schema.Union<readonly [Schema.Struct<{
     readonly ok: Schema.Literal<true>;

package/types/app-cache/src/index.d.ts

@@ -13,7 +13,9 @@ export interface CacheGet<A> {
     readonly load: Effect.Effect<A, unknown>;
 }
 /** Create a scoped cache client; a background runner must retain all task resources until completion. */
-export declare const makeCache: (transport: CacheTransport, background: (task: Effect.Effect<void, unknown>) => Effect.Effect<void>, scope?: Schema.Json) => {
+export declare const makeCache: (host: CacheTransport, background: (task: Effect.Effect<void, unknown>) => Effect.Effect<void>, scope?: Schema.Json, 
+/** The caller's own deadline, when the host supplies one. Waiting never runs past it. */
+deadline?: number) => {
     /** Read arbitrary retained JSON entries without initiating a refresh. Missing and null are distinct. */
     read: (keys: readonly Schema.Json[]) => Effect.Effect<readonly ({
         readonly value: Schema.Json;
@@ -33,3 +35,59 @@ export declare const makeCache: (transport: CacheTransport, background: (task: E
     /** Force one awaited refresh without removing the retained value. Concurrent refreshes share a load. */
     revalidate: <A>(options: CacheGet<A>) => Effect.Effect<A, unknown, never>;
 };
+/**
+ * Host-side lease ownership for one app invocation. Leases the invocation claims are renewed while
+ * it runs, so a slow load keeps its key, and released when the host ends the invocation, including
+ * interrupted and cancelled ones and loads whose own release never arrived. A holder that stops
+ * running, or whose store channel stops answering, loses its lease within `leaseMs`.
+ */
+export declare const holdLeases: (transport: CacheTransport) => Effect.Effect<{
+    /** Use for every command of the invocation. Each command is bounded by `commandTimeoutMs`. */
+    transport: (input: {
+        readonly operation: "read";
+        readonly keys: readonly string[];
+    } | {
+        readonly operation: "acquire";
+        readonly key: string;
+        readonly refresh: boolean;
+        readonly version?: string | null;
+    } | {
+        readonly operation: "claim";
+        readonly key: string;
+        readonly version: string | null;
+    } | {
+        readonly operation: "publish";
+        readonly key: string;
+        readonly lease: string;
+        readonly entry: {
+            readonly value: Schema.Json;
+            readonly version: string;
+            readonly freshUntil: number;
+            readonly staleUntil: number;
+        };
+    } | {
+        readonly operation: "release";
+        readonly key: string;
+        readonly lease: string;
+    } | {
+        readonly operation: "renew";
+        readonly key: string;
+        readonly lease: string;
+    } | {
+        readonly operation: "write";
+        readonly entries: readonly {
+            readonly key: string;
+            readonly entry: {
+                readonly value: Schema.Json;
+                readonly version: string;
+                readonly freshUntil: number;
+                readonly staleUntil: number;
+            };
+        }[];
+    } | {
+        readonly operation: "invalidate";
+        readonly key: string;
+    }) => Effect.Effect<Schema.Json, CacheError, never>;
+    /** Stop renewing and release every lease the invocation still holds. */
+    close: Effect.Effect<void, never, never>;
+}, never, never>;

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/app.d.ts

@@ -3,7 +3,6 @@ import type { DatabaseDefinition } from "./storage.js";
 /** Native app contracts; factories and handlers compose in the host's Effect runtime. */
 import { type Effect, Schema } from "effect";
 import type { OperationSchedule } from "./schedules.js";
-import type { AppOperation } from "./operations.js";
 import type { AccountOf, AuthMethods, ManyAccounts, Provider } from "./provider.js";
 import type { AppWorkflow, WorkflowReads } from "./workflows.js";
 import type { Elicit } from "./elicitation.js";
@@ -11,8 +10,8 @@ import type { Elicit } from "./elicitation.js";
 type Handler<Context> = (context: Context, input: never) => Effect.Effect<unknown, unknown>;
 /** App capabilities share one account context. Package metadata belongs in package.json. */
 export interface AppDefinition<Context> {
-    /** Optional dynamic tools; resolution does not enumerate the catalog. */
-    readonly dynamicTools?: import("./dynamic-tools.js").DynamicTools;
+    /** The app's root router. Its keys form tool paths such as `issues.list`. */
+    readonly tools?: import("./router.js").AppRouter | import("./router.js").DynamicRouter;
     /** Omission reads packaged skills/. An explicit catalog replaces that default, including []. */
     readonly skills?: readonly AppSkillSource[];
     /** Optional lazy skills, added to the static catalog. Only skill reads call them. */
@@ -21,8 +20,6 @@ export interface AppDefinition<Context> {
     readonly schedules?: Readonly<Record<string, Omit<OperationSchedule, "name"> & {
         readonly tool: string;
     }>>;
-    readonly queries?: Readonly<Record<string, AppOperation>>;
-    readonly mutations?: Readonly<Record<string, AppOperation>>;
     readonly webhooks?: Readonly<Record<string, {
         readonly account: string;
         readonly config: Schema.Decoder<unknown>;
@@ -46,7 +43,11 @@ export interface BoundContext<Slots extends AccountSlots> {
     readonly workflows: WorkflowReads;
     /** Ask for user input during this tool call. Unavailable during discovery and after the invocation closes. */
     readonly elicit: Elicit;
-    /** Invocation-owned HTTP requests with trace propagation and host cancellation. */
+    /**
+     * Invocation-owned HTTP requests with trace propagation and host cancellation. It lasts until the
+     * invocation and every app cache refresh it started in the background have ended, so a catalog
+     * loader given this fetch can refresh after the reply.
+     */
     readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
     /** Host cancellation for this invocation. Pass it to fetch and other interruptible APIs. */
     readonly signal: AbortSignal;

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

@@ -29,7 +29,10 @@ export interface AppCache {
         readonly value: JsonValue;
     }[], retention: Duration.Input) => Promise<void>;
     readonly invalidate: (key: JsonValue) => Promise<void>;
-    /** Uses the current bound credentials' fingerprint, never just the saved account ID. */
+    /**
+     * Scope entries to a bound account and its credential generation. Token renewal keeps the
+     * entries; reconnecting or replacing the account's credentials starts an empty scope.
+     */
     readonly forAccount: (account: {
         readonly id: string;
     }) => AppCache;

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>;
+};