apps 0.0.1-beta.0

package/types/apps/src/implementation/workflow-context.d.ts

@@ -0,0 +1,8 @@
+/** Author-facing step methods delegate persistence to the host's durable engine. */
+import { Effect } from "effect";
+import type { AppDefinition } from "../contracts/app.js";
+import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type WorkflowStepContext } from "../contracts/workflows.js";
+/** Preserve typed failures and cancellation; authored exception text never leaves the app. */
+export declare const workflowSafe: <A>(work: Effect.Effect<A, unknown>) => Effect.Effect<A, WorkflowFailure>;
+/** Construct one replay's Promise context. Step callbacks acquire fresh capabilities per actual attempt. */
+export declare const makeWorkflowContext: (execution: WorkflowExecution, definition: Pick<AppDefinition<never>, "queries" | "mutations">, fresh: (stepId: string, signal: AbortSignal) => Effect.Effect<WorkflowStepContext, WorkflowFailure>, signal: AbortSignal) => Effect.Effect<WorkflowContext>;

package/types/apps/src/implementation/workflow-rpc.d.ts

@@ -0,0 +1,5 @@
+import { type WorkflowExecution, type WorkflowRpc, type WorkflowHostControls } from "../contracts/workflows.js";
+/** Bind a private host callback to this invocation; no workflow capability survives cancellation. */
+export declare const isolatedWorkflowExecution: (run: string, deliver: WorkflowRpc, signal: AbortSignal) => WorkflowExecution;
+/** Reconstruct app-scoped controls from one invocation-owned RPC function. */
+export declare const isolatedWorkflowControls: (deliver: (input: unknown) => Promise<unknown>) => WorkflowHostControls;

package/types/apps/src/implementation/workflows.d.ts

@@ -0,0 +1,27 @@
+/** Ordinary async workflow declarations, adapted once into native Effect handlers. */
+import { type Schema as EffectSchema } from "effect";
+import type { AppWorkflow, WorkflowContext } from "../contracts/workflows.js";
+import { type Schema } from "./schema.js";
+declare const NativeWorkflow: unique symbol;
+declare const HandlerContext: unique symbol;
+/** A workflow declaration retains input/output inference and required context compatibility. */
+export interface Workflow<Input, Output, Context extends WorkflowContext = WorkflowContext> {
+    readonly [HandlerContext]?: (context: Context) => void;
+    readonly [NativeWorkflow]: AppWorkflow<Input, Output>;
+}
+/** Composition view erases input only after retaining its runtime decoder. */
+export interface WorkflowDeclaration<Context extends WorkflowContext> {
+    readonly [HandlerContext]?: (context: Context) => void;
+    readonly [NativeWorkflow]: Omit<AppWorkflow<never>, "input"> & {
+        readonly input: EffectSchema.Decoder<unknown>;
+    };
+}
+/** Declare durable orchestration without starting a run or performing I/O. */
+export declare const workflow: <Input, Output, Context extends WorkflowContext = WorkflowContext>(options: {
+    readonly input: Schema<Input, boolean>;
+    readonly output?: Schema<Output, boolean>;
+    readonly description?: string;
+}, run: (context: Context, input: Input) => Promise<Output>) => Workflow<Input, Output, Context>;
+/** Only this module creates the private declaration symbol; input is decoded before invocation. */
+export declare const nativeWorkflow: (value: unknown) => AppWorkflow | undefined;
+export {};

package/types/apps/src/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Public author API. Native contracts live in contracts/; this boundary
+ * exposes ordinary declarations, schema helpers and Promise operations.
+ */
+import { type Schema as EffectSchema } from "effect";
+import type { WebhookContext } from "./contracts/context.js";
+import { type JsonResponse as NativeResponse } from "./contracts/http.js";
+import { type OAuth2Config, type OAuth2Method as NativeOAuth2Method, type SecretsMethod as NativeSecretsMethod } from "./contracts/provider.js";
+import type { Webhook as NativeWebhook } from "./contracts/webhooks.js";
+import { type PromiseMethods } from "./implementation/authoring.js";
+import { type Fields, type Infer, type ObjectSchema, type Schema } from "./implementation/schema.js";
+export { type JsonObject, type JsonValue, ValidationError } from "./contracts/schema.js";
+export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Schema, array, boolean, json, jsonSchema, literal, number, object, record, string, } from "./implementation/schema.js";
+export { type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type OAuth2Config, type Provider, } from "./contracts/provider.js";
+export { defineProvider } from "./implementation/provider.js";
+export { accountOperations } from "./implementation/account-operations.js";
+/** A secrets declaration inferred from an author schema. */
+export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<Infer<Shape>>>;
+/** An OAuth declaration inferred from its author-facing response schema. */
+export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<Infer<Response>>>;
+/** Default OAuth fields visible to app code. Host-only grants and clients stay private. */
+export declare const OAuth2AccessToken: Schema<{
+    readonly access_token: string;
+}, false>;
+/** Declare a secrets method without requiring an Effect schema from the author. */
+export declare const secrets: <const F extends Fields>(options: {
+    readonly label: string;
+    readonly fields: ObjectSchema<F>;
+}) => SecretsMethod<ObjectSchema<F>>;
+/** Declare OAuth discovery/endpoints and an optional app-visible response projection. */
+export declare function oauth2(options: OAuth2Config): OAuth2Method<typeof OAuth2AccessToken>;
+export declare function oauth2<Response extends Schema<unknown, boolean>>(options: OAuth2Config & {
+    readonly response: Response;
+}): OAuth2Method<Response>;
+export type { AccountSlots } from "./contracts/app.js";
+export type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext, } from "./contracts/context.js";
+export { type App, type AppDefinition, defineApp } from "./implementation/app.js";
+export type { Approval, ApprovalContext, ApprovalDecision } from "./approval.js";
+type AuthorWebhook<Member, Config, State> = Member extends object ? Omit<PromiseMethods<Member>, "config" | "state"> & {
+    readonly config: Config;
+    readonly state: State;
+} : never;
+/** Author lifecycle methods use async functions and share native decoded context/state types. */
+export type Webhook<Context extends WebhookContext, Config extends Schema<unknown, boolean>, State extends Schema<unknown, boolean>> = AuthorWebhook<NativeWebhook<Context, EffectSchema.Decoder<Infer<Config>>, EffectSchema.Decoder<Infer<State>>>, Config, State>;
+export { ResponseDecodeError, ResponseStatusError } from "./contracts/http.js";
+/** Native fetch-compatible response accepted at the author boundary. */
+export type JsonResponse = PromiseMethods<NativeResponse>;
+/** Decode a fetch response with safe status/body errors. Unexpected reader failures propagate unchanged. */
+export declare const decodeJson: <T>(response: JsonResponse, schema: Schema<T, boolean>) => Promise<T>;
+export { NotImplemented } from "./contracts/app.js";
+export { ElicitationFailed, type FormElicitation, type ElicitationResponse, type Elicit, } from "./contracts/elicitation.js";
+export { table, defineDatabase, type Table, type DatabaseReader, type Database, type DatabaseDefinition, } from "./implementation/storage.js";
+export { id, userId } from "./implementation/schema.js";
+export { query, mutation, withApproval, type Operation, type OperationOptions, } from "./implementation/operations.js";
+export type { OperationContext } from "./contracts/operations.js";
+export { workflow, type Workflow, type WorkflowDeclaration } from "./implementation/workflows.js";
+export { NonRetryableError, WorkflowFailure, type WorkflowContext, type WorkflowStepContext, type WorkflowStep, type WorkflowStepOptions, type WorkflowDuration, type WorkflowReads, type WorkflowControls, } from "./contracts/workflows.js";
+export { interval, cron, type ScheduleDeclaration } from "./implementation/schedules.js";

package/types/apps/src/mcp-stdio.d.ts

@@ -0,0 +1,8 @@
+import type { ProcessConfig } from "./contracts/mcp.js";
+import { type OperationKinds } from "./implementation/protocol-operations.js";
+export { McpError, type McpToolContext, type ProcessConfig } from "./contracts/mcp.js";
+/** Discover an account's tools; each discovery and call owns and closes its subprocess. */
+export declare const stdioOperations: (config: ProcessConfig, signal?: AbortSignal, kinds?: OperationKinds) => Promise<{
+    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
+    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
+}>;

package/types/apps/src/mcp.d.ts

@@ -0,0 +1,10 @@
+/** HTTP MCP helpers. Requires the optional @modelcontextprotocol/sdk peer. */
+import { type OperationKinds } from "./implementation/protocol-operations.js";
+import type { McpToolsOptions } from "./contracts/mcp.js";
+export { McpError, type McpToolContext, type McpToolsOptions, type McpToolResult, } from "./contracts/mcp.js";
+/** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
+export declare const mcpOperations: (options: McpToolsOptions, kinds?: OperationKinds) => Promise<{
+    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
+    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
+}>;
+export type { OperationKinds } from "./implementation/protocol-operations.js";

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

@@ -0,0 +1,10 @@
+/** OpenAPI helpers over normalized operation metadata; no optional dependency is needed. */
+import { type OperationKinds } from "./implementation/protocol-operations.js";
+import type { OpenapiToolsOptions } from "./contracts/openapi.js";
+export { OpenapiError, type OpenapiToolsOptions, type OpenapiOperation, type CredentialBinding, type RequestParameter, } from "./contracts/openapi.js";
+/** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
+export declare const openapiOperations: (options: OpenapiToolsOptions, kinds?: OperationKinds) => Promise<{
+    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
+    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
+}>;
+export type { OperationKinds } from "./implementation/protocol-operations.js";

package/types/apps/src/react.d.ts

@@ -0,0 +1,7 @@
+import { AsyncResult, type Atom } from "effect/unstable/reactivity";
+/** Subscribe for the component lifetime. Each mount owns and disposes its registry, including StrictMode remounts. */
+export declare const useAppQuery: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => {
+    data: A | undefined;
+    pending: boolean;
+    error: string | undefined;
+};

package/types/apps/src/ui-auth.d.ts

@@ -0,0 +1,3 @@
+/** Host-only app authentication protocol and bootstrap; products supply identity and session lifecycle. */
+export * from "./contracts/ui-auth.js";
+export { appPrivateHeaders, appSignInPage, appSignInScript } from "./implementation/ui-auth.js";

package/types/apps/src/ui-serving.d.ts

@@ -0,0 +1,3 @@
+/** Host-only rendering utilities; the host supplies authorized retained assets. */
+export { appDocument, appAsset } from "./implementation/ui-serving.js";
+export { appWatchScript } from "./implementation/ui-watch.js";

package/types/telemetry/src/browser-operations.d.ts

@@ -0,0 +1,16 @@
+/** Correlate transport and decoded outcomes without exporting response bodies or errors. */
+import { Effect, Schema, Tracer } from "effect";
+import { HttpClient, HttpClientError } from "effect/unstable/http";
+/** A random document identity. It is never an authentication or user identifier. */
+export declare const browserPageId: () => string;
+/** Safe event shared with the host's error reporter and product analytics. */
+export declare const BrowserOperationFailure: Schema.Struct<{
+    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
+    readonly trace_id: Schema.String;
+    readonly span_id: Schema.String;
+    readonly page_id: Schema.String;
+}>;
+/** Observe transport failure and retain only its trace identity for the subsequent decoder. */
+export declare const observeBrowserTransport: (client: HttpClient.HttpClient) => HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;
+/** AtomHttpApi invokes this after status/body decoding, including handled schema failures. */
+export declare const observeBrowserResponse: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>;

package/types/telemetry/src/browser-performance.d.ts

@@ -0,0 +1,11 @@
+/** Native page measurements. Observers and reporting fibers belong to the browser Layer. */
+import { Effect } from "effect";
+/** Collect page measurements without making them parents of unrelated API calls. */
+export declare const observeBrowserPerformance: Effect.Effect<{
+    flush: Effect.Effect<void, never, never>;
+    pause: Effect.Effect<void, never, never>;
+    resume: Effect.Effect<void, never, never>;
+    hide: Effect.Effect<void, never, never>;
+    restore: Effect.Effect<void, never, never>;
+    navigation: (_path: string) => Effect.Effect<void, never, never>;
+}, never, import("effect/Scope").Scope>;

package/types/telemetry/src/browser-request-timing.d.ts

@@ -0,0 +1,2 @@
+/** Missing/restricted browser measurements stay absent instead of being labelled network or cold-start time. */
+export declare const browserRequestTiming: (entry: unknown, origin: string) => Readonly<Record<string, string | number>> | undefined;

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

@@ -0,0 +1,27 @@
+/** Browser-owned Effect telemetry, shared by Promise calls and Atom runtimes. */
+import { Context, Effect, Layer, ManagedRuntime } from "effect";
+import { OtlpExporter } from "effect/unstable/observability";
+import { Atom } from "effect/unstable/reactivity";
+import type { TelemetryConfig } from "./config.js";
+declare const BrowserTelemetry_base: Context.ServiceClass<BrowserTelemetry, "executor/BrowserTelemetry", {
+    readonly navigation: (event: {
+        readonly type: "start";
+        readonly path: string;
+    } | {
+        readonly type: "end";
+    }) => Effect.Effect<void>;
+    readonly flush: Effect.Effect<void>;
+}>;
+/** Page events use the same tracer and export scope as browser API operations. */
+export declare class BrowserTelemetry extends BrowserTelemetry_base {
+}
+/** Install listeners for this page lifetime. Closing the Layer removes them and drains exporters. */
+export declare const browserTelemetryLayer: (settings: Effect.Effect<TelemetryConfig>) => Layer.Layer<OtlpExporter.Flusher | BrowserTelemetry, never, never>;
+/** Share a memo map so the page and its Atom registries acquire one telemetry Layer. */
+export declare const makeBrowserTelemetry: (settings: Effect.Effect<TelemetryConfig>) => {
+    runtime: ManagedRuntime.ManagedRuntime<OtlpExporter.Flusher | BrowserTelemetry, never>;
+    atoms: Atom.SharedRuntimeFactory;
+};
+/** Read public build metadata and use only same-origin telemetry endpoints. */
+export declare const browserSettings: (basePath: string, service: string) => Effect.Effect<TelemetryConfig>;
+export { browserPageId, BrowserOperationFailure, observeBrowserTransport, observeBrowserResponse, } from "./browser-operations.js";

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

@@ -0,0 +1,83 @@
+/** Telemetry configuration is parsed at composition roots; headers remain redacted. */
+import { Config, Context, Effect, Schema } from "effect";
+/** One private exporter target. Endpoints are complete signal URLs. */
+export declare const TelemetryTarget: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly headers: Schema.optional<Schema.RedactedFromValue<Schema.$Record<Schema.String, Schema.String>>>;
+}>;
+/** Parsed target with redaction-safe headers. */
+export type TelemetryTarget = typeof TelemetryTarget.Type;
+/** Shared identity and independently selectable OTLP signals. */
+export declare const TelemetryConfig: Schema.Struct<{
+    readonly service: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
+    readonly environment: Schema.NonEmptyString;
+    readonly clock: Schema.optional<Schema.Literals<readonly ["system", "cloudflare-io"]>>;
+    readonly traces: Schema.optional<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly headers: Schema.optional<Schema.RedactedFromValue<Schema.$Record<Schema.String, Schema.String>>>;
+    }>>;
+    readonly logs: Schema.optional<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly headers: Schema.optional<Schema.RedactedFromValue<Schema.$Record<Schema.String, Schema.String>>>;
+    }>>;
+    readonly metrics: Schema.optional<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly headers: Schema.optional<Schema.RedactedFromValue<Schema.$Record<Schema.String, Schema.String>>>;
+    }>>;
+    readonly metricsProtocol: Schema.optional<Schema.Literals<readonly ["http/json", "http/protobuf"]>>;
+}>;
+/** Resolved telemetry configuration. */
+export type TelemetryConfig = typeof TelemetryConfig.Type;
+/** Host-only destinations; never copied into an app's invocation telemetry capability. */
+export declare const CurrentTelemetryConfig: Context.Reference<{
+    readonly version: string;
+    readonly service: string;
+    readonly environment: string;
+    readonly clock?: "system" | "cloudflare-io" | undefined;
+    readonly traces?: {
+        readonly url: string;
+        readonly headers?: import("effect/Redacted").Redacted<{
+            readonly [x: string]: string;
+        }> | undefined;
+    } | undefined;
+    readonly logs?: {
+        readonly url: string;
+        readonly headers?: import("effect/Redacted").Redacted<{
+            readonly [x: string]: string;
+        }> | undefined;
+    } | undefined;
+    readonly metrics?: {
+        readonly url: string;
+        readonly headers?: import("effect/Redacted").Redacted<{
+            readonly [x: string]: string;
+        }> | undefined;
+    } | undefined;
+    readonly metricsProtocol?: "http/json" | "http/protobuf" | undefined;
+} | undefined>;
+/** Read OTLP endpoints uniformly for all signals; development chooses which signals to configure. */
+export declare const telemetryConfig: (service: string) => Effect.Effect<{
+    readonly version: string;
+    readonly service: string;
+    readonly environment: string;
+    readonly clock?: "system" | "cloudflare-io" | undefined;
+    readonly traces?: {
+        readonly url: string;
+        readonly headers?: import("effect/Redacted").Redacted<{
+            readonly [x: string]: string;
+        }> | undefined;
+    } | undefined;
+    readonly logs?: {
+        readonly url: string;
+        readonly headers?: import("effect/Redacted").Redacted<{
+            readonly [x: string]: string;
+        }> | undefined;
+    } | undefined;
+    readonly metrics?: {
+        readonly url: string;
+        readonly headers?: import("effect/Redacted").Redacted<{
+            readonly [x: string]: string;
+        }> | undefined;
+    } | undefined;
+    readonly metricsProtocol?: "http/json" | "http/protobuf" | undefined;
+}, Schema.SchemaError | Config.ConfigError, never>;

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

@@ -0,0 +1,14 @@
+/** Explicit telemetry-only context across Promise and HTTP boundaries. */
+import { Context, Effect, Tracer } from "effect";
+/** Trusted in-process capability containing no product authority, database or credentials. */
+export interface InvocationTelemetry {
+    readonly context: Context.Context<never>;
+}
+/** Capture the tracer, loggers, registry and parent for a host-owned callback. */
+export declare const captureTelemetry: Effect.Effect<InvocationTelemetry>;
+/** Encode the active span; absent tracing remains a valid no-header case. */
+export declare const traceHeaders: Effect.Effect<Readonly<Record<string, string>>>;
+/** Decode W3C context and start a server span in the recipient's own telemetry runtime. */
+export declare const withRemoteSpan: (request: Request, name: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Tracer.ParentSpan>>;
+/** Plain fetch for app authors, correlated with the invocation and cancelled by its owner. */
+export declare const invocationFetch: (signal: AbortSignal) => Effect.Effect<(input: string | URL | Request, init?: RequestInit) => Promise<Response>, never, never>;

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

@@ -0,0 +1,9 @@
+/** Effect-native observability shared by Executor hosts and framework operations. */
+export { CurrentTelemetryConfig, TelemetryConfig, TelemetryTarget, telemetryConfig, } from "./config.js";
+export { telemetryLayer, telemetryFromConfig } from "./layer.js";
+export { captureTelemetry, traceHeaders, withRemoteSpan, invocationFetch, type InvocationTelemetry, } from "./context.js";
+export { collectTelemetry, forwardTelemetry, makeTelemetryForwarder, TelemetryBatch, } from "./relay.js";
+export { TraceContext, currentTraceContext, externalTrace, traceLinks } from "./trace-context.js";
+export { pendingSpan } from "./pending-span.js";
+export { recordWorkerMeasurements } from "./measurements.js";
+export { allowlistedSpans, httpSpanAttributeAllowlist, spanAttributeAllowed, } from "./span-attributes.js";

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

@@ -0,0 +1,7 @@
+/** Portable Effect exporters. The host owns scope and export lifetime. */
+import { Layer, Logger } from "effect";
+import { type TelemetryConfig } from "./config.js";
+/** Build one tracer per runtime. Event mode defers export until Worker scope finalization. */
+export declare const telemetryLayer: (config: TelemetryConfig, lifetime?: "process" | "event", logger?: Logger.Logger<unknown, void>) => Layer.Layer<import("effect/unstable/observability/OtlpExporter").Flusher, never, never>;
+/** Node/local entry points resolve telemetry once and share it for their process lifetime. */
+export declare const telemetryFromConfig: (service: string) => Layer.Layer<import("effect/unstable/observability/OtlpExporter").Flusher, import("effect/Schema").SchemaError | import("effect/Config").ConfigError, never>;

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

@@ -0,0 +1,8 @@
+/** Low-cardinality transport measurements; these are wall/CPU totals with explicit units, not app data. */
+import { Effect } from "effect";
+/** Classify URLs into a fixed set before attaching attributes; raw paths and query strings are never labels. */
+export declare const recordResponseReady: (path: string | undefined, method: string, status: number, milliseconds: number) => Effect.Effect<void, never, never>;
+/** Fixed failure metadata goes to both local/native logs and the metric registry, even when the remote exporter is down. */
+export declare const recordExportFailure: (path: string, reason?: "transport" | "interrupted" | "partial-success" | "capacity" | "acknowledgement", records?: number) => Effect.Effect<void, never, never>;
+/** Record provider-owned invocation totals separately from response-ready timing. */
+export declare const recordWorkerMeasurements: (worker: string, outcome: string, cpu: number, wall: number) => Effect.Effect<void, never, never>;

package/types/telemetry/src/pending-span.d.ts

@@ -0,0 +1,7 @@
+/** A span ending at an asynchronous milestone, with cancellation owned by its enclosing scope. */
+import { Effect, Exit, type Tracer } from "effect";
+/** End exactly once at completion, failure, or scope release. It is not installed as a parent implicitly. */
+export declare const pendingSpan: (name: string, options?: Tracer.SpanOptionsNoTrace) => Effect.Effect<{
+    span: Tracer.Span;
+    finish: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, never>;
+}, never, import("effect/Scope").Scope>;

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

@@ -0,0 +1,28 @@
+/** Bounded OTLP return channel for credential-free app isolates. The parent owns export. */
+import { Effect, Schema } from "effect";
+/**
+ * Forward app telemetry in the host scope without delaying an app result.
+ * One export runs at a time, with at most sixteen pending batches. Overload and
+ * shutdown loss are reported through the normal safe export-failure signal.
+ * Scope release drains for the same three-second budget as the other exporters.
+ */
+export declare const makeTelemetryForwarder: Effect.Effect<(batch: TelemetryBatch, traceId: string, build?: string) => Effect.Effect<void, never, never>, never, import("effect/Scope").Scope>;
+/** Untrusted isolate batches are bounded before decoding; no endpoint or credential crosses back. */
+export declare const TelemetryBatch: Schema.Struct<{
+    readonly traces: Schema.$Array<Schema.String>;
+    readonly logs: Schema.$Array<Schema.String>;
+    readonly dropped: Schema.Int;
+}>;
+/** Parsed isolate telemetry envelope. */
+export type TelemetryBatch = typeof TelemetryBatch.Type;
+/** Collect one invocation into memory, flush before returning, and never contact a remote collector. */
+export declare const collectTelemetry: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<{
+    value: A;
+    telemetry: {
+        traces: string[];
+        logs: string[];
+        dropped: number;
+    };
+}, E, Exclude<Exclude<R, import("effect/unstable/observability/OtlpExporter").Flusher>, never>>;
+/** Validate isolated records and export only this call's trace, using parent-owned credentials/identity. */
+export declare const forwardTelemetry: (batch: TelemetryBatch, traceId: string | undefined, build: string | undefined, service?: "executor-app" | "executor-web") => Effect.Effect<void, Schema.SchemaError | import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Cause").TimeoutError, never>;

package/types/telemetry/src/span-attributes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP span attributes are allowlisted. Nothing else in an HTTP namespace is recorded.
+ *
+ * Effect's HTTP client and its server tracer write every request and response
+ * header, the full URL and the query string onto their spans. This product
+ * routes provider API keys through header and query names chosen by an imported
+ * OpenAPI spec, and carries bearer capabilities such as the one-click
+ * unsubscribe token in a query parameter and in a redirect `Location` header.
+ * No list of dangerous names can keep up with that, so HTTP spans record a
+ * fixed set of attributes and drop everything else.
+ *
+ * The allowlist runs on the tracer because that is the single point where the
+ * client tracer and the server tracer meet. Effect's
+ * `HttpClient.TracerHeaderFilter` controls outgoing headers only: nothing
+ * configures the URL attributes on either side, and the server tracer has no
+ * header hook at all. A second filter on the client would duplicate this one
+ * rather than complete it, so this is the only boundary.
+ *
+ * Attributes outside these namespaces are the product's own and pass through.
+ */
+import { Layer } from "effect";
+/** Every HTTP attribute an exported span may carry. */
+export declare const httpSpanAttributeAllowlist: ReadonlySet<string>;
+/** Record this attribute? HTTP names must be allowlisted; product names pass through. */
+export declare const spanAttributeAllowed: (key: string) => boolean;
+/** Wrap whichever tracer is already in scope; provide this above the exporter. */
+export declare const spanAttributes: (clock?: "system" | "cloudflare-io", recordAll?: boolean) => Layer.Layer<never>;
+/** Header and URL filtering without making an unsupported claim about the runtime clock. */
+export declare const allowlistedSpans: Layer.Layer<never, never, never>;

package/types/telemetry/src/trace-context.d.ts

@@ -0,0 +1,20 @@
+/** Safe W3C identifiers for correlation across transports that do not carry HTTP headers. */
+import { Effect, Option, Schema, Tracer } from "effect";
+/** Trace metadata conveys no authorization and must never contain app values or credentials. */
+export declare const TraceContext: Schema.Struct<{
+    readonly traceId: Schema.String;
+    readonly spanId: Schema.String;
+    readonly sampled: Schema.Boolean;
+}>;
+/** Decoded, non-authorizing trace identity. */
+export type TraceContext = typeof TraceContext.Type;
+/** Capture only the current span's transport-safe identity. */
+export declare const currentTraceContext: Effect.Effect<{
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly sampled: boolean;
+} | undefined, never, never>;
+/** Invalid or absent optional telemetry never prevents otherwise valid application data from rendering. */
+export declare const externalTrace: (input: unknown) => Option.Option<Tracer.ExternalSpan>;
+/** Link a measurement to the observed request without inventing a parent/child lifetime. */
+export declare const traceLinks: (input: unknown, relationship: string) => ReadonlyArray<Tracer.SpanLink>;

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

@@ -0,0 +1,6 @@
+import { Context, Layer } from "effect";
+import { HttpClient } from "effect/unstable/http";
+/** Local collector discovery can resolve its destination when an export runs. */
+export declare const CurrentTelemetryClient: Context.Reference<HttpClient.HttpClient | undefined>;
+/** Telemetry consumers inspect status and headers; release response I/O inside each export scope. */
+export declare const telemetryHttpClient: Layer.Layer<HttpClient.HttpClient, never, never>;