apps 0.0.1-beta.1 → 0.0.1-beta.2

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/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;