apps 0.0.1-beta.76 → 0.0.1-beta.79

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

@@ -21,7 +21,12 @@ export interface CacheGet<A> {
 /** Create a scoped cache client; a background runner must retain all task resources until completion. */
 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) => {
+deadline?: number, 
+/**
+ * Wraps the time this caller waits on another caller's load of the same entry, polls included,
+ * so the host can trace it and count it as waiting rather than as its own work.
+ */
+leaseWait?: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>) => {
     /** 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;

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

@@ -730,6 +730,13 @@ export declare const InvocationTiming: Schema.Struct<{
     readonly upstreamMs: Schema.Finite;
     readonly elicitationMs: Schema.Finite;
     readonly authoredMs: Schema.Finite;
+    /** Waiting on another call that holds the lease to load a cache entry this call needs. */
+    readonly leaseMs: Schema.optionalKey<Schema.Finite>;
+    /**
+     * How long background work, such as a stale cache entry's refresh, ran within the invocation.
+     * It runs beside the invocation, so it is not part of the division above.
+     */
+    readonly backgroundMs: Schema.optionalKey<Schema.Finite>;
 }>;
 export type InvocationTiming = typeof InvocationTiming.Type;
 /** Receives the invocation's timing once it is over; hosts that do not return it ignore it. */

package/types/apps/src/implementation/invocation-timing.d.ts

@@ -1,6 +1,8 @@
 /**
  * Divide a tool invocation's time, on its own isolate's clock, by who the work belonged to:
- * Executor, the app's authored code, upstream providers, or a person answering an elicitation.
+ * Executor, the app's authored code, upstream providers, a person answering an elicitation, or
+ * another call loading a cache entry this one waits for. Background work no caller waits on runs
+ * beside the division and is reported apart.
  * Each boundary declares its owner where the work starts (see `owned`); the invocation's own span is
  * Executor's. The host adds the other isolates' parts.
  */

package/types/telemetry/src/ownership.d.ts

@@ -3,7 +3,9 @@
  * starts work for someone other than its caller declares the owner with `ownedBy`; any other span
  * works for whoever its parent works for. Each instant then belongs to the innermost boundary in
  * progress, so Executor's work inside an upstream session stays Executor's, and an app's callback
- * inside Executor's cache stays the app's.
+ * inside Executor's cache stays the app's. Background work is the exception: everything inside it
+ * is background, and it runs beside its caller rather than inside it. It takes no instant from the
+ * caller's window; how long it ran within the window is reported beside the division.
  *
  * Workers clocks advance only on I/O, so durations are comparable within one isolate and not across
  * isolates: each isolate measures its own part, and the spans that already bracket the work define
@@ -11,10 +13,11 @@
  */
 import { Context, Effect, Tracer } from "effect";
 /**
- * Executor's own work; the app's authored code; waiting on an upstream provider; or waiting on a
- * person's answer.
+ * Executor's own work; the app's authored code; waiting on an upstream provider; waiting on a
+ * person's answer; waiting on another call that holds the lease to load a cache entry; or work
+ * handed to the background, such as refreshing a stale cache entry, that no caller waits on.
  */
-export type Owner = "executor" | "app" | "upstream" | "person";
+export type Owner = "executor" | "app" | "upstream" | "person" | "lease" | "background";
 /** The attribute that shows a boundary's owner in the trace; the telemetry tracer sets it. */
 export declare const ownerAttribute = "executor.owner";
 /** The owner a span declared when it started, if it is an ownership boundary. */
@@ -44,6 +47,7 @@ export declare const measuredSpan: (name: string, options: Tracer.SpanOptionsNoT
  * instant, the work in progress is the innermost span of each branch: a span with no child still
  * open. Its owner takes the instant. With nothing open inside the window, `owner` takes it. Spans
  * are counted as they open and end, in constant time each, and only spans still open are kept.
+ * `background` is not part of the division: it is how long background work was in progress.
  */
 export declare const makeOwnershipAccounting: (origin: bigint, owner: Owner) => {
     /** Run `effect` with the spans it opens observed, including spans it hands to later work. */