@lostgradient/weft 0.11.0 → 0.13.0

package/dist/mcp/http.d.ts

@@ -1,4 +1,4 @@
-import type { Engine } from '../core/engine.ts';
+import type { RegistryAgnosticEngine } from '../core/engine.ts';
 import { type Principal } from '../server/principal.ts';
 import { McpSessionManager } from './session.ts';
 /**
@@ -25,7 +25,12 @@ import { McpSessionManager } from './session.ts';
  */
 export type McpHttpRequestOptions = {
     readonly request: Request;
-    readonly engine: Engine;
+    /**
+     * Typed as {@link RegistryAgnosticEngine} (see its JSDoc) rather than the
+     * plain default `Engine`, so both `new Engine({ storage })` and
+     * `Engine.create({ workflows })` type-check here directly.
+     */
+    readonly engine: RegistryAgnosticEngine;
     readonly sessionManager: McpSessionManager;
     readonly principal?: Principal;
     readonly authRequired: boolean;

package/dist/mcp/session.d.ts

@@ -1,4 +1,4 @@
-import type { Engine } from '../core/engine.ts';
+import type { RegistryAgnosticEngine } from '../core/engine.ts';
 import { WeftError } from '../core/weft-error.ts';
 import type { Principal } from '../server/principal.ts';
 import { type McpResponse } from './protocol.ts';
@@ -123,7 +123,7 @@ export declare class McpSession {
  */
 export declare class McpSessionManager implements AsyncDisposable {
     #private;
-    constructor(engine: Engine, options?: McpSessionManagerOptions);
+    constructor(engine: RegistryAgnosticEngine, options?: McpSessionManagerOptions);
     /** Create and store a new session for a principal. */
     create(principal: Principal): McpSession;
     /** Store an externally-created session. Used by stdio. */
@@ -150,5 +150,5 @@ export declare class McpSessionManager implements AsyncDisposable {
  * void manager;
  * ```
  */
-export declare function createMcpSessionManager(engine: Engine, options?: McpSessionManagerOptions): McpSessionManager;
+export declare function createMcpSessionManager(engine: RegistryAgnosticEngine, options?: McpSessionManagerOptions): McpSessionManager;
 export {};

package/dist/mcp/session.js

@@ -127,11 +127,12 @@ export class McpSessionManager {
   #currentTimeMilliseconds;
   #toolListSignature;
   constructor(engine, options = {}) {
-    this.#engine = engine;
+    const erasedEngine = engine;
+    this.#engine = erasedEngine;
     this.#maximumSessions = options.maximumSessions ?? 1024;
     this.#sessionIdleTimeoutMilliseconds = options.sessionIdleTimeoutMilliseconds ?? 1800000;
     this.#currentTimeMilliseconds = options.currentTimeMilliseconds ?? Date.now;
-    this.#toolListSignature = toolListSignature(engine);
+    this.#toolListSignature = toolListSignature(erasedEngine);
     this.#resourceListener = (event) => {
       const workflowId = event.workflowId;
       if (typeof workflowId !== "string")

package/dist/mcp/stdio.d.ts

@@ -1,4 +1,4 @@
-import type { Engine } from '../core/engine.ts';
+import type { RegistryAgnosticEngine } from '../core/engine.ts';
 import { type McpSessionManagerOptions } from './session.ts';
 /**
  * Admission modes for local MCP stdio sessions.
@@ -46,7 +46,12 @@ export type McpStdioAdmission = {
 export type McpStdioSessionOptions = {
     readonly input: ReadableStream<Uint8Array>;
     readonly output: WritableStream<Uint8Array>;
-    readonly engine: Engine;
+    /**
+     * Typed as {@link RegistryAgnosticEngine} (see its JSDoc) rather than the
+     * plain default `Engine`, so both `new Engine({ storage })` and
+     * `Engine.create({ workflows })` type-check here directly.
+     */
+    readonly engine: RegistryAgnosticEngine;
     readonly admission: McpStdioAdmission;
     readonly maxFrameBytes?: number;
     readonly sessionManagerOptions?: McpSessionManagerOptions;

package/dist/observability/index.js

@@ -1,4 +1,4 @@
 // @bun
-var kS=Object.defineProperty;var zS=(S)=>S;function CS(S,W){this[S]=zS.bind(null,W)}var L0=(S,W)=>{for(var $ in W)kS(S,$,{get:W[$],enumerable:!0,configurable:!0,set:CS.bind(W,$)})};var L=(S,W)=>()=>(S&&(W=S(S=0)),W);var Q0=import.meta.require,j0=(S,W,$)=>{if(W!=null){if(typeof W!=="object"&&typeof W!=="function")throw TypeError('Object expected to be assigned to "using" declaration');let x;if($)x=W[Symbol.asyncDispose];if(x===void 0)x=W[Symbol.dispose];if(typeof x!=="function")throw TypeError("Object not disposable");S.push([$,x,W])}else if($)S.push([$]);return W},H0=(S,W,$)=>{let x=(K)=>W=$?new SuppressedError(K,W,"An error was suppressed during disposal"):($=!0,K),G=(K)=>{while(K=S.pop())try{var J=K[1]&&K[1].call(K[2]);if(K[0])return Promise.resolve(J).then(G,(H)=>(x(H),G()))}catch(H){x(H)}if($)throw W};return G()};var c,i,d,n,l;var o=L(()=>{c=class c extends Event{static type="activity:started";operationId;workflowId;activityName;attempt;constructor(S,W,$,x){super(c.type);this.operationId=S,this.workflowId=W,this.activityName=$,this.attempt=x}};i=class i extends Event{static type="activity:completed";operationId;workflowId;activityName;duration;constructor(S,W,$,x){super(i.type);this.operationId=S,this.workflowId=W,this.activityName=$,this.duration=x}};d=class d extends Event{static type="activity:async-pending";token;operationId;workflowId;activityName;attempt;constructor(S,W,$,x,G){super(d.type);this.token=S,this.operationId=W,this.workflowId=$,this.activityName=x,this.attempt=G}};n=class n extends Event{static type="activity:failed";operationId;workflowId;activityName;error;attempt;constructor(S,W,$,x,G){super(n.type);this.operationId=S,this.workflowId=W,this.activityName=$,this.error=x,this.attempt=G}};l=class l extends Event{static type="task:dead-lettered";operationId;workflowId;activityName;queue;workerId;reason;errorMessage;constructor({operationId:S,workflowId:W,activityName:$,queue:x,workerId:G,errorMessage:K}){super(l.type);this.operationId=S,this.workflowId=W,this.activityName=$,this.queue=x,this.workerId=G,this.reason="result-resolution-storage-exhausted",this.errorMessage=K}}});var r;var s=L(()=>{r=class r extends Event{static type="attributes:changed";workflowId;changes;constructor(S,W){super(r.type);this.workflowId=S,this.changes=W}}});var a,t;var e=L(()=>{a=class a extends Event{static type="schedule:fired";scheduleId;workflowId;firedAt;occurrence;constructor(S,W,$,x){super(a.type);this.scheduleId=S,this.workflowId=W,this.firedAt=$,this.occurrence=x}};t=class t extends Event{static type="schedule:missed-fire";scheduleId;missedCount;windowStart;windowEnd;constructor(S,W,$,x){super(t.type);this.scheduleId=S,this.missedCount=W,this.windowStart=$,this.windowEnd=x}}});var SS,WS;var $S=L(()=>{SS=class SS extends Event{static type="signal:received";workflowId;signalName;payload;constructor(S,W,$){super(SS.type);this.workflowId=S,this.signalName=W,this.payload=$}};WS=class WS extends Event{static type="signal:delivered";workflowId;signalName;constructor(S,W){super(WS.type);this.workflowId=S,this.signalName=W}}});var xS,GS,KS,XS,JS,LS,QS,jS,HS;var YS=L(()=>{xS=class xS extends Event{static type="checkpoint:size-warning";workflowId;sizeBytes;step;constructor(S,W,$){super(xS.type);this.workflowId=S,this.sizeBytes=W,this.step=$}};GS=class GS extends Event{static type="development:warning";workflowId;message;fieldPaths;constructor(S,W,$){super(GS.type);this.workflowId=S,this.message=W,this.fieldPaths=$}};KS=class KS extends Event{static type="cleanup:warning";source;error;workflowId;constructor(S,W,$){super(KS.type);this.source=S,this.error=W,this.workflowId=$}};XS=class XS extends Event{static type="storage:size-reported";sizeBytes;constructor(S){super(XS.type);this.sizeBytes=S}};JS=class JS extends Event{static type="worker:connected";workerId;queue;activities;concurrency;constructor(S,W,$,x){super(JS.type);this.workerId=S,this.queue=W,this.activities=$,this.concurrency=x}};LS=class LS extends Event{static type="worker:disconnected";workerId;inFlightTaskCount;constructor(S,W){super(LS.type);this.workerId=S,this.inFlightTaskCount=W}};QS=class QS extends Event{static type="alert:fired";metric;threshold;currentValue;window;constructor(S,W,$,x){super(QS.type);this.metric=S,this.threshold=W,this.currentValue=$,this.window=x}};jS=class jS extends Event{static type="alert:resolved";metric;threshold;currentValue;window;constructor(S,W,$,x){super(jS.type);this.metric=S,this.threshold=W,this.currentValue=$,this.window=x}};HS=class HS extends Event{static type="constraint:violated";workflowId;constraintName;scope;onViolation;constructor(S,W,$,x){super(HS.type);this.workflowId=S,this.constraintName=W,this.scope=$,this.onViolation=x}}});var ZS,OS;var BS=L(()=>{ZS=class ZS extends Event{static type="update:received";updateId;workflowId;name;payload;constructor(S,W,$,x){super(ZS.type);this.updateId=S,this.workflowId=W,this.name=$,this.payload=x}};OS=class OS extends Event{static type="update:completed";updateId;workflowId;name;result;error;constructor(S,W,$,x,G){super(OS.type);this.updateId=S,this.workflowId=W,this.name=$,this.result=x,this.error=G}}});var PS,qS,Y,Z,O,B,C0,TS,yS,US,_S;var bS=L(()=>{PS=class PS extends Event{static type="workflow:definition-registered";workflowType;constructor(S){super(PS.type);this.workflowType=S}};qS=class qS extends Event{static type="workflow:started";workflowId;workflowType;input;constructor(S,W,$){super(qS.type);this.workflowId=S,this.workflowType=W,this.input=$}};Y=class Y extends Event{static type="workflow:completed";workflowId;result;duration;constructor(S,W,$){super(Y.type);this.workflowId=S,this.result=W,this.duration=$}};Z=class Z extends Event{static type="workflow:failed";workflowId;error;constructor(S,W){super(Z.type);this.workflowId=S,this.error=W}};O=class O extends Event{static type="workflow:cancelled";workflowId;constructor(S){super(O.type);this.workflowId=S}};B=class B extends Event{static type="workflow:timed-out";workflowId;timeoutType;elapsed;reason;constructor(S,W,$,x){super(B.type);if(this.workflowId=S,this.timeoutType=W,this.elapsed=$,x!==void 0)this.reason=x}};C0=new Set([Y.type,Z.type,O.type,B.type]);TS=class TS extends Event{static type="workflow:resumed";workflowId;fromStep;constructor(S,W){super(TS.type);this.workflowId=S,this.fromStep=W}};yS=class yS extends Event{static type="workflow:suspended";workflowId;constructor(S){super(yS.type);this.workflowId=S}};US=class US extends Event{static type="workflow:recovery-skipped";workflowId;workflowType;reason;constructor(S,W,$){super(US.type);this.workflowId=S,this.workflowType=W,this.reason=$}};_S=class _S extends Event{static type="workflow:teardown";workflowId;workflowType;status;attempts;error;constructor(S,W,$,x,G){super(_S.type);this.workflowId=S,this.workflowType=W,this.status=$,this.attempts=x,this.error=G}}});var FS=L(()=>{o();s();e();$S();YS();BS();bS()});var MS=L(()=>{FS()});var wS={traceId:"0".repeat(32),spanId:"0".repeat(16),traceFlags:0},F={setAttribute(){},setStatus(){},recordException(){},end(){},spanContext(){return wS}},w={setAttribute:(...S)=>F.setAttribute(...S),setStatus:(...S)=>F.setStatus(...S),recordException:(...S)=>F.recordException(...S),end:(...S)=>F.end(...S)},pS={startSpan(){return F}},k={record(){},add(){}},IS={createHistogram(){return k},createCounter(){return k},createUpDownCounter(){return k}},NS=Symbol("ROOT_CONTEXT"),gS={trace:{getTracer(){return pS},setSpan(S){return S}},metrics:{getMeter(){return IS}},context:{ROOT_CONTEXT:NS,with(S,W){return W()}},SpanStatusCode:{OK:1,ERROR:2,UNSET:0}},q;function vS(){let S=globalThis.require;if(typeof S==="function")return(W)=>S(W);return()=>{return}}function ES(S){return S?.trace?.getTracer!=null&&S.SpanStatusCode!=null}function hS(S=vS()){try{let W=S("@opentelemetry/api");if(ES(W))return W}catch{}return}function T(S){if(q)return q;let W=hS(S);if(W)return q=W,q;return q=gS,q}function p(S){let W=new Uint8Array(S);return crypto.getRandomValues(W),Array.from(W,($)=>$.toString(16).padStart(2,"0")).join("")}var I="traceparent",uS=/^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/,mS="00000000000000000000000000000000",cS="0000000000000000";function N(S){let W=uS.exec(S);if(!W)return null;let[,$,x,G,K]=W;if(x===mS)return null;if(G===cS)return null;return{version:$,traceId:x,spanId:G,traceFlags:parseInt(K,16)}}function g(S){let W=S.traceFlags.toString(16).padStart(2,"0");return`${S.version}-${S.traceId}-${S.spanId}-${W}`}function M(S){let W=S.get(I);if(!W)return null;return N(W)}function z(S,W){S.set(I,g(W))}function iS(){return p(16)}function dS(){return p(8)}var v=1024;function y(S,W){let $;try{$=JSON.stringify(S)}catch{$=String(S)}if($.length>W)return $.slice(0,W)+"...";return $}function nS(S){return S instanceof Error?S.message:String(S)}function lS(S){return S instanceof Error?S:Error(String(S))}function R(S,W){let $=S.spanContext();z(W,{version:"00",traceId:$.traceId,spanId:$.spanId,traceFlags:$.traceFlags})}function U(S,W,$){let x=S.attributeExtractor;if(!x)return;let G=x($);for(let[K,J]of Object.entries(G))W.setAttribute(K,J)}function A(S,W){let $=S.workflowSpans.get(W);return $?S.trace.setSpan(S.api.context.ROOT_CONTEXT,$.span):S.api.context.ROOT_CONTEXT}function C(S,W,$){W.setStatus({code:S.SpanStatusCode.ERROR,message:nS($)}),W.recordException(lS($))}function E(S,W,$,x){try{let G=$();return W.setStatus({code:S.SpanStatusCode.OK}),x?.(G),G}catch(G){throw C(S,W,G),G}finally{W.end()}}async function f(S,W,$,x){try{let G=await $();return W.setStatus({code:S.SpanStatusCode.OK}),x?.(G),G}catch(G){throw C(S,W,G),G}finally{W.end()}}function*D(S,W,$,x){try{let G=yield*$();return W.setStatus({code:S.SpanStatusCode.OK}),x?.(G),G}catch(G){throw C(S,W,G),G}finally{W.end()}}function h(S){return{async execute(W,$){let x=M(W.headers),G=S.api.context.ROOT_CONTEXT;if(x){let J={...w,spanContext(){return{traceId:x.traceId,spanId:x.spanId,traceFlags:x.traceFlags}}};G=S.trace.setSpan(S.api.context.ROOT_CONTEXT,J)}let K=S.tracer.startSpan(`activity:execute:${W.activityName}`,{attributes:{"weft.activity.name":W.activityName,"weft.activity.attempt":W.attempt,...x?{"weft.parent.trace_id":x.traceId}:{}}},G);if(S.recordPayloads&&W.input!==void 0)K.setAttribute("weft.payload.input",y(W.input,S.maxPayloadSize));return f(S,K,()=>$(W))}}}var _={workflowDuration:{name:"weft.workflow.duration",description:"Duration of workflow execution in milliseconds",unit:"ms",type:"histogram"},activityDuration:{name:"weft.activity.duration",description:"Duration of activity execution in milliseconds",unit:"ms",type:"histogram"},activityAttempts:{name:"weft.activity.attempts",description:"Total activity execution attempts",unit:"attempts",type:"counter"},workflowActive:{name:"weft.workflow.active",description:"Number of currently active workflows",unit:"workflows",type:"gauge"},workflowStarted:{name:"weft.workflow.started",description:"Total workflows started",unit:"workflows",type:"counter"},workflowCompleted:{name:"weft.workflow.completed",description:"Total workflows completed",unit:"workflows",type:"counter"},workflowFailed:{name:"weft.workflow.failed",description:"Total workflows failed",unit:"workflows",type:"counter"},promptCacheHits:{name:"weft.prompt_cache.hits",description:"Total prompt prefix cache hits",unit:"hits",type:"counter"},promptCacheMisses:{name:"weft.prompt_cache.misses",description:"Total prompt prefix cache misses",unit:"misses",type:"counter"},dpmoDefects:{name:"weft.dpmo.defects",description:"Total failed workflows (DPMO numerator)",unit:"workflows",type:"counter"},dpmoOperations:{name:"weft.dpmo.operations",description:"Total started workflows (DPMO denominator)",unit:"workflows",type:"counter"},taskBacklog:{name:"weft.task.backlog",description:"Number of queued tasks waiting for workers",unit:"tasks",type:"gauge"},taskQueueLatency:{name:"weft.task.queue_latency",description:"Time tasks spend queued before dispatch in milliseconds",unit:"ms",type:"histogram"},taskExecutionLatency:{name:"weft.task.execution_latency",description:"Time tasks spend executing after worker start in milliseconds",unit:"ms",type:"histogram"},taskRetries:{name:"weft.task.retries",description:"Total task retry attempts after the first dispatch attempt",unit:"retries",type:"counter"},taskRequeues:{name:"weft.task.requeues",description:"Total visibility-timeout or disconnect task requeues",unit:"requeues",type:"counter"},taskStaleHeartbeats:{name:"weft.task.stale_heartbeats",description:"Number of in-flight tasks whose heartbeat age exceeds the diagnostic threshold",unit:"tasks",type:"gauge"},workerCapacitySaturation:{name:"weft.worker.capacity_saturation",description:"Ratio of in-flight worker slots to total worker concurrency",unit:"ratio",type:"gauge"}};var oS=1e4;class u{#S;#$=0;#W=0;constructor(S){this.#S=new Float64Array(S)}push(S){if(this.#S[this.#$]=S,this.#$=(this.#$+1)%this.#S.length,this.#W<this.#S.length)this.#W++}toArray(){if(this.#W<this.#S.length)return Array.from(this.#S.subarray(0,this.#W));let S=Array.from({length:this.#W});for(let W=0;W<this.#W;W++)S[W]=this.#S[(this.#$+W)%this.#S.length];return S}}class V{#S;#$;#W;constructor(){this.#S=new Map,this.#$=new Map,this.#W=new Map}increment(S,W=1){this.#S.set(S,(this.#S.get(S)??0)+W)}record(S,W){let $=this.#$.get(S);if(!$)$=new u(oS),this.#$.set(S,$);$.push(W)}gauge(S,W){this.#W.set(S,W)}snapshot(){let S={};for(let[W,$]of this.#S)S[W]={type:"counter",value:$};for(let[W,$]of this.#$){let x=$.toArray(),G=sS(x);S[W]={type:"histogram",count:x.length,sum:aS(x),p50:G[Math.floor(G.length*0.5)]??0,p99:G[Math.floor(G.length*0.99)]??0,min:G[0]??0,max:G[G.length-1]??0}}for(let[W,$]of this.#W)S[W]={type:"gauge",value:$};return S}reset(){this.#S.clear(),this.#$.clear(),this.#W.clear()}}function rS(S){let W;if(typeof S==="string")W=T().metrics.getMeter(S);else if(S)W=S;else W=T().metrics.getMeter("weft");return{workflowDuration:W.createHistogram("weft.workflow.duration",{unit:"ms"}),activityDuration:W.createHistogram("weft.activity.duration",{unit:"ms"}),activityAttempts:W.createCounter("weft.activity.attempts"),activeWorkflows:W.createUpDownCounter("weft.workflow.active")}}function sS(S){let W=[...S];return W.sort(($,x)=>$-x),W}function aS(S){let W=0;for(let $ of S)W+=$;return W}function tS(S,W){let $=W?.type==="histogram"?W.count:0,x=W?.type==="histogram"?W.sum:0;return[`# TYPE ${S} histogram`,`${S}_count ${$}`,`${S}_sum ${x}`]}function eS(S,W){let $=W?.type==="counter"?W.value:0;return[`# TYPE ${S} counter`,`${S}_total ${$}`]}function S0(S,W){let $=W?.type==="gauge"?W.value:0;return[`# TYPE ${S} gauge`,`${S} ${$}`]}var W0={histogram:tS,counter:eS,gauge:S0};function $0(S,W){let $=S.name.replace(/\./g,"_"),x=W[S.name];return[`# HELP ${$} ${S.description}`,...W0[S.type]($,x)]}function x0(S){let W=S[_.dpmoDefects.name],$=S[_.dpmoOperations.name],x=W?.type==="counter"?W.value:0,G=$?.type==="counter"?$.value:0,K=G===0?0:x*1e6/G,J="weft_dpmo";return["# HELP weft_dpmo Defects per million operations (failed workflows / started workflows * 1e6)","# TYPE weft_dpmo gauge",`weft_dpmo ${K}`]}function m(S){let W=[];for(let $ of Object.values(_))W.push(...$0($,S));return W.push(...x0(S)),W.join(`
+var Jn=import.meta.require,Qn=(n,w,i)=>{if(w!=null){if(typeof w!=="object"&&typeof w!=="function")throw TypeError('Object expected to be assigned to "using" declaration');let S;if(i)S=w[Symbol.asyncDispose];if(S===void 0)S=w[Symbol.dispose];if(typeof S!=="function")throw TypeError("Object not disposable");n.push([i,S,w])}else if(i)n.push([i]);return w},jn=(n,w,i)=>{let S=(f)=>w=i?new SuppressedError(f,w,"An error was suppressed during disposal"):(i=!0,f),k=(f)=>{while(f=n.pop())try{var y=f[1]&&f[1].call(f[2]);if(f[0])return Promise.resolve(y).then(k,(p)=>(S(p),k()))}catch(p){S(p)}if(i)throw w};return k()};var h={traceId:"0".repeat(32),spanId:"0".repeat(16),traceFlags:0},T={setAttribute(){},setStatus(){},recordException(){},end(){},spanContext(){return h}},q={setAttribute:(...n)=>T.setAttribute(...n),setStatus:(...n)=>T.setStatus(...n),recordException:(...n)=>T.recordException(...n),end:(...n)=>T.end(...n)},l={startSpan(){return T}},P={record(){},add(){}},t={createHistogram(){return P},createCounter(){return P},createUpDownCounter(){return P}},r=Symbol("ROOT_CONTEXT"),a={trace:{getTracer(){return l},setSpan(n){return n}},metrics:{getMeter(){return t}},context:{ROOT_CONTEXT:r,with(n,w){return w()}},SpanStatusCode:{OK:1,ERROR:2,UNSET:0}},o;function s(){let n=globalThis.require;if(typeof n==="function")return(w)=>n(w);return()=>{return}}function e(n){return n?.trace?.getTracer!=null&&n.SpanStatusCode!=null}function nn(n=s()){try{let w=n("@opentelemetry/api");if(e(w))return w}catch{}return}function K(n){if(o)return o;let w=nn(n);if(w)return o=w,o;return o=a,o}function H(n){let w=new Uint8Array(n);return crypto.getRandomValues(w),Array.from(w,(i)=>i.toString(16).padStart(2,"0")).join("")}var Y="traceparent",wn=/^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/,Sn="00000000000000000000000000000000",kn="0000000000000000";function Z(n){let w=wn.exec(n);if(!w)return null;let[,i,S,k,f]=w;if(S===Sn)return null;if(k===kn)return null;return{version:i,traceId:S,spanId:k,traceFlags:parseInt(f,16)}}function M(n){let w=n.traceFlags.toString(16).padStart(2,"0");return`${n.version}-${n.traceId}-${n.spanId}-${w}`}function J(n){let w=n.get(Y);if(!w)return null;return Z(w)}function U(n,w){n.set(Y,M(w))}function fn(){return H(16)}function vn(){return H(8)}var O=1024;function C(n,w){let i;try{i=JSON.stringify(n)}catch{i=String(n)}if(i.length>w)return i.slice(0,w)+"...";return i}function yn(n){return n instanceof Error?n.message:String(n)}function Wn(n){return n instanceof Error?n:Error(String(n))}function Q(n,w){let i=n.spanContext();U(w,{version:"00",traceId:i.traceId,spanId:i.spanId,traceFlags:i.traceFlags})}function A(n,w,i){let S=n.attributeExtractor;if(!S)return;let k=S(i);for(let[f,y]of Object.entries(k))w.setAttribute(f,y)}function j(n,w){let i=n.workflowSpans.get(w);return i?n.trace.setSpan(n.api.context.ROOT_CONTEXT,i.span):n.api.context.ROOT_CONTEXT}function V(n,w,i){w.setStatus({code:n.SpanStatusCode.ERROR,message:yn(i)}),w.recordException(Wn(i))}function _(n,w,i,S){try{let k=i();return w.setStatus({code:n.SpanStatusCode.OK}),S?.(k),k}catch(k){throw V(n,w,k),k}finally{w.end()}}async function x(n,w,i,S){try{let k=await i();return w.setStatus({code:n.SpanStatusCode.OK}),S?.(k),k}catch(k){throw V(n,w,k),k}finally{w.end()}}function*B(n,w,i,S){try{let k=yield*i();return w.setStatus({code:n.SpanStatusCode.OK}),S?.(k),k}catch(k){throw V(n,w,k),k}finally{w.end()}}function g(n){return{async execute(w,i){let S=J(w.headers),k=n.api.context.ROOT_CONTEXT;if(S){let y={...q,spanContext(){return{traceId:S.traceId,spanId:S.spanId,traceFlags:S.traceFlags}}};k=n.trace.setSpan(n.api.context.ROOT_CONTEXT,y)}let f=n.tracer.startSpan(`activity:execute:${w.activityName}`,{attributes:{"weft.activity.name":w.activityName,"weft.activity.attempt":w.attempt,...S?{"weft.parent.trace_id":S.traceId}:{}}},k);if(n.recordPayloads&&w.input!==void 0)f.setAttribute("weft.payload.input",C(w.input,n.maxPayloadSize));return x(n,f,()=>i(w))}}}var X={workflowDuration:{name:"weft.workflow.duration",description:"Duration of workflow execution in milliseconds",unit:"ms",type:"histogram"},activityDuration:{name:"weft.activity.duration",description:"Duration of activity execution in milliseconds",unit:"ms",type:"histogram"},activityAttempts:{name:"weft.activity.attempts",description:"Total activity execution attempts",unit:"attempts",type:"counter"},workflowActive:{name:"weft.workflow.active",description:"Number of currently active workflows",unit:"workflows",type:"gauge"},workflowStarted:{name:"weft.workflow.started",description:"Total workflows started",unit:"workflows",type:"counter"},workflowCompleted:{name:"weft.workflow.completed",description:"Total workflows completed",unit:"workflows",type:"counter"},workflowFailed:{name:"weft.workflow.failed",description:"Total workflows failed",unit:"workflows",type:"counter"},promptCacheHits:{name:"weft.prompt_cache.hits",description:"Total prompt prefix cache hits",unit:"hits",type:"counter"},promptCacheMisses:{name:"weft.prompt_cache.misses",description:"Total prompt prefix cache misses",unit:"misses",type:"counter"},dpmoDefects:{name:"weft.dpmo.defects",description:"Total failed workflows (DPMO numerator)",unit:"workflows",type:"counter"},dpmoOperations:{name:"weft.dpmo.operations",description:"Total started workflows (DPMO denominator)",unit:"workflows",type:"counter"},taskBacklog:{name:"weft.task.backlog",description:"Number of queued tasks waiting for workers",unit:"tasks",type:"gauge"},taskQueueLatency:{name:"weft.task.queue_latency",description:"Time tasks spend queued before dispatch in milliseconds",unit:"ms",type:"histogram"},taskExecutionLatency:{name:"weft.task.execution_latency",description:"Time tasks spend executing after worker start in milliseconds",unit:"ms",type:"histogram"},taskRetries:{name:"weft.task.retries",description:"Total task retry attempts after the first dispatch attempt",unit:"retries",type:"counter"},taskRequeues:{name:"weft.task.requeues",description:"Total visibility-timeout or disconnect task requeues",unit:"requeues",type:"counter"},taskStaleHeartbeats:{name:"weft.task.stale_heartbeats",description:"Number of in-flight tasks whose heartbeat age exceeds the diagnostic threshold",unit:"tasks",type:"gauge"},workerCapacitySaturation:{name:"weft.worker.capacity_saturation",description:"Ratio of in-flight worker slots to total worker concurrency",unit:"ratio",type:"gauge"}};var dn=1e4;class z{#n;#i=0;#w=0;constructor(n){this.#n=new Float64Array(n)}push(n){if(this.#n[this.#i]=n,this.#i=(this.#i+1)%this.#n.length,this.#w<this.#n.length)this.#w++}toArray(){if(this.#w<this.#n.length)return Array.from(this.#n.subarray(0,this.#w));let n=Array.from({length:this.#w});for(let w=0;w<this.#w;w++)n[w]=this.#n[(this.#i+w)%this.#n.length];return n}}class D{#n;#i;#w;constructor(){this.#n=new Map,this.#i=new Map,this.#w=new Map}increment(n,w=1){this.#n.set(n,(this.#n.get(n)??0)+w)}record(n,w){let i=this.#i.get(n);if(!i)i=new z(dn),this.#i.set(n,i);i.push(w)}gauge(n,w){this.#w.set(n,w)}snapshot(){let n={};for(let[w,i]of this.#n)n[w]={type:"counter",value:i};for(let[w,i]of this.#i){let S=i.toArray(),k=In(S);n[w]={type:"histogram",count:S.length,sum:Fn(S),p50:k[Math.floor(k.length*0.5)]??0,p99:k[Math.floor(k.length*0.99)]??0,min:k[0]??0,max:k[k.length-1]??0}}for(let[w,i]of this.#w)n[w]={type:"gauge",value:i};return n}reset(){this.#n.clear(),this.#i.clear(),this.#w.clear()}}function pn(n){let w;if(typeof n==="string")w=K().metrics.getMeter(n);else if(n)w=n;else w=K().metrics.getMeter("weft");return{workflowDuration:w.createHistogram("weft.workflow.duration",{unit:"ms"}),activityDuration:w.createHistogram("weft.activity.duration",{unit:"ms"}),activityAttempts:w.createCounter("weft.activity.attempts"),activeWorkflows:w.createUpDownCounter("weft.workflow.active")}}function In(n){let w=[...n];return w.sort((i,S)=>i-S),w}function Fn(n){let w=0;for(let i of n)w+=i;return w}function Ln(n,w){let i=w?.type==="histogram"?w.count:0,S=w?.type==="histogram"?w.sum:0;return[`# TYPE ${n} histogram`,`${n}_count ${i}`,`${n}_sum ${S}`]}function $n(n,w){let i=w?.type==="counter"?w.value:0;return[`# TYPE ${n} counter`,`${n}_total ${i}`]}function Gn(n,w){let i=w?.type==="gauge"?w.value:0;return[`# TYPE ${n} gauge`,`${n} ${i}`]}var on={histogram:Ln,counter:$n,gauge:Gn};function Kn(n,w){let i=n.name.replace(/\./g,"_"),S=w[n.name];return[`# HELP ${i} ${n.description}`,...on[n.type](i,S)]}function Cn(n){let w=n[X.dpmoDefects.name],i=n[X.dpmoOperations.name],S=w?.type==="counter"?w.value:0,k=i?.type==="counter"?i.value:0,f=k===0?0:S*1e6/k,y="weft_dpmo";return["# HELP weft_dpmo Defects per million operations (failed workflows / started workflows * 1e6)","# TYPE weft_dpmo gauge",`weft_dpmo ${f}`]}function b(n){let w=[];for(let i of Object.values(X))w.push(...Kn(i,n));return w.push(...Cn(n)),w.join(`
 `)+`
-`}function G0(S){return{serialize(){let W=S?.snapshot()??{};return m(W)}}}MS();var K0=3600000,RS=1e4,X0=3600000;function AS(S){let W=Date.now();for(let[$,x]of S.workflowSpans)if(W-x.createdAt>K0)x.span.end(),S.workflowSpans.delete($);if(S.workflowSpans.size>RS){let $=S.workflowSpans.size-RS,x=0;for(let[G,K]of S.workflowSpans){if(x>=$)break;K.span.end(),S.workflowSpans.delete(G),x++}}}function fS(S,W){let $=S.workflowSpans.get(W);if($)$.span.end(),S.workflowSpans.delete(W)}function DS(S){function W(X,P,Q){let j=S.workflowSpans.get(X);if(!j)return;if(P==="error")j.span.setStatus({code:S.SpanStatusCode.ERROR,...Q?{message:Q}:{}});else j.span.setStatus({code:S.SpanStatusCode.OK});j.span.end(),S.workflowSpans.delete(X)}let $=(X)=>{if(!(X instanceof Y))return;W(X.workflowId,"ok")},x=(X)=>{if(!(X instanceof Z))return;W(X.workflowId,"error",X.error.message),S.metrics.increment("weft.dpmo.defects")},G=(X)=>{if(!(X instanceof O))return;W(X.workflowId,"error","Workflow cancelled")},K=(X)=>{if(!(X instanceof B))return;W(X.workflowId,"error",`Workflow timed out (${X.timeoutType}) after ${X.elapsed}ms`),S.metrics.increment("weft.dpmo.defects")};if(S.eventTarget)S.eventTarget.addEventListener(Y.type,$),S.eventTarget.addEventListener(Z.type,x),S.eventTarget.addEventListener(O.type,G),S.eventTarget.addEventListener(B.type,K);function J(X=X0){let P=Date.now()-X,Q=0;for(let[j,b]of S.workflowSpans)if(b.createdAt<=P)b.span.setStatus({code:S.SpanStatusCode.ERROR,message:"span evicted (stale)"}),b.span.end(),S.workflowSpans.delete(j),Q++;return Q}function H(){if(S.eventTarget)S.eventTarget.removeEventListener(Y.type,$),S.eventTarget.removeEventListener(Z.type,x),S.eventTarget.removeEventListener(O.type,G),S.eventTarget.removeEventListener(B.type,K);for(let X of S.workflowSpans.values())X.span.setStatus({code:S.SpanStatusCode.ERROR,message:"Observability disposed"}),X.span.end();S.workflowSpans.clear()}return{endWorkflowSpan:W,evictStaleSpans:J,dispose:H}}function VS(S){return{workflowStart(W,$){AS(S);let x=S.workflowSpans.get(W.workflowId);if(x)x.span.setStatus({code:S.SpanStatusCode.OK}),fS(S,W.workflowId);let G=S.tracer.startSpan(`workflow:${W.workflowType}`,{attributes:{"weft.workflow.id":W.workflowId,"weft.workflow.type":W.workflowType}});if(S.workflowSpans.set(W.workflowId,{span:G,createdAt:Date.now()}),R(G,W.headers),S.recordPayloads&&W.input!==void 0)G.setAttribute("weft.payload.input",y(W.input,S.maxPayloadSize));U(S,G,W),S.metrics.increment("weft.workflow.started"),S.metrics.increment("weft.dpmo.operations"),$(W)},*activity(W,$){let x=S.tracer.startSpan(`activity:${W.activityName}`,{attributes:{"weft.activity.name":W.activityName,"weft.activity.attempt":W.attempt}},A(S,W.workflowId));if(R(x,W.headers),S.recordPayloads&&W.input!==void 0)x.setAttribute("weft.payload.input",y(W.input,S.maxPayloadSize));U(S,x,W);let G=Date.now();return yield*D(S,x,()=>$(W),()=>{S.metrics.record("weft.activity.duration",Date.now()-G),S.metrics.increment("weft.activity.attempts")})},*sleep(W,$){let x=S.tracer.startSpan("sleep",{attributes:{"weft.sleep.duration":W.duration}},A(S,W.workflowId));U(S,x,W),yield*D(S,x,()=>$(W))},*waitForSignal(W,$){let x=S.tracer.startSpan("waitForSignal",{attributes:{"weft.signal.name":W.signalName}},A(S,W.workflowId));return U(S,x,W),yield*D(S,x,()=>$(W))},async childWorkflow(W,$){let x=[],G=M(W.parentHeaders);if(G)x.push({context:{traceId:G.traceId,spanId:G.spanId,traceFlags:G.traceFlags}});let K=S.tracer.startSpan(`childWorkflow:${W.workflowType}`,{attributes:{"weft.child_workflow.type":W.workflowType,"weft.child_workflow.id":W.childWorkflowId,"weft.child_workflow.parent_id":W.workflowId},links:x},S.api.context.ROOT_CONTEXT);if(R(K,W.headers),S.recordPayloads&&W.input!==void 0)K.setAttribute("weft.payload.input",y(W.input,S.maxPayloadSize));return S.metrics.increment("weft.child_workflow.started"),f(S,K,()=>$(W))},signalReceived(W,$){let x=S.tracer.startSpan(`signal:received:${W.signalName}`,{attributes:{"weft.signal.name":W.signalName,"weft.signal.workflow_id":W.workflowId}});U(S,x,W),E(S,x,()=>$(W))}}}function J0(S){let{attributeExtractor:W,eventTarget:$,maxPayloadSize:x=v,metrics:G=new V,openTelemetryApi:K=T(),recordPayloads:J=!1,tracerName:H="weft",tracerVersion:X}=S??{},P=K,{trace:Q,SpanStatusCode:j}=P,b=Q.getTracer(H,X);return{api:P,trace:Q,SpanStatusCode:j,tracer:b,recordPayloads:J,maxPayloadSize:x,attributeExtractor:W,eventTarget:$,metrics:G,workflowSpans:new Map}}function xW(S){let W=J0(S),$=VS(W),x=h(W),G={...$,...x},K=DS(W);return{interceptor:G,metrics:W.metrics,...K}}export{m as serializeMetricsSnapshotForPrometheus,N as parseTraceParent,z as injectTraceParent,T as getOpenTelemetryApi,iS as generateTraceId,dS as generateSpanId,g as formatTraceParent,M as extractTraceParent,rS as createOpenTelemetryMetrics,xW as createObservabilityInterceptors,G0 as createMetricsCollectorExporter,V as MetricsCollector,_ as METRICS};
+`}function An(n){return{serialize(){let w=n?.snapshot()??{};return b(w)}}}class I extends Event{static type="workflow:completed";workflowId;result;duration;constructor(n,w,i){super(I.type);this.workflowId=n,this.result=w,this.duration=i}}class F extends Event{static type="workflow:failed";workflowId;error;constructor(n,w){super(F.type);this.workflowId=n,this.error=w}}class L extends Event{static type="workflow:cancelled";workflowId;constructor(n){super(L.type);this.workflowId=n}}class $ extends Event{static type="workflow:timed-out";workflowId;timeoutType;elapsed;reason;constructor(n,w,i,S){super($.type);if(this.workflowId=n,this.timeoutType=w,this.elapsed=i,S!==void 0)this.reason=S}}var zn=new Set([I.type,F.type,L.type,$.type]);var Xn=3600000,E=1e4,Rn=3600000;function c(n){let w=Date.now();for(let[i,S]of n.workflowSpans)if(w-S.createdAt>Xn)S.span.end(),n.workflowSpans.delete(i);if(n.workflowSpans.size>E){let i=n.workflowSpans.size-E,S=0;for(let[k,f]of n.workflowSpans){if(S>=i)break;f.span.end(),n.workflowSpans.delete(k),S++}}}function N(n,w){let i=n.workflowSpans.get(w);if(i)i.span.end(),n.workflowSpans.delete(w)}function u(n){function w(v,G,W){let d=n.workflowSpans.get(v);if(!d)return;if(G==="error")d.span.setStatus({code:n.SpanStatusCode.ERROR,...W?{message:W}:{}});else d.span.setStatus({code:n.SpanStatusCode.OK});d.span.end(),n.workflowSpans.delete(v)}let i=(v)=>{if(!(v instanceof I))return;w(v.workflowId,"ok")},S=(v)=>{if(!(v instanceof F))return;w(v.workflowId,"error",v.error.message),n.metrics.increment("weft.dpmo.defects")},k=(v)=>{if(!(v instanceof L))return;w(v.workflowId,"error","Workflow cancelled")},f=(v)=>{if(!(v instanceof $))return;w(v.workflowId,"error",`Workflow timed out (${v.timeoutType}) after ${v.elapsed}ms`),n.metrics.increment("weft.dpmo.defects")};if(n.eventTarget)n.eventTarget.addEventListener(I.type,i),n.eventTarget.addEventListener(F.type,S),n.eventTarget.addEventListener(L.type,k),n.eventTarget.addEventListener($.type,f);function y(v=Rn){let G=Date.now()-v,W=0;for(let[d,R]of n.workflowSpans)if(R.createdAt<=G)R.span.setStatus({code:n.SpanStatusCode.ERROR,message:"span evicted (stale)"}),R.span.end(),n.workflowSpans.delete(d),W++;return W}function p(){if(n.eventTarget)n.eventTarget.removeEventListener(I.type,i),n.eventTarget.removeEventListener(F.type,S),n.eventTarget.removeEventListener(L.type,k),n.eventTarget.removeEventListener($.type,f);for(let v of n.workflowSpans.values())v.span.setStatus({code:n.SpanStatusCode.ERROR,message:"Observability disposed"}),v.span.end();n.workflowSpans.clear()}return{endWorkflowSpan:w,evictStaleSpans:y,dispose:p}}function m(n){return{workflowStart(w,i){c(n);let S=n.workflowSpans.get(w.workflowId);if(S)S.span.setStatus({code:n.SpanStatusCode.OK}),N(n,w.workflowId);let k=n.tracer.startSpan(`workflow:${w.workflowType}`,{attributes:{"weft.workflow.id":w.workflowId,"weft.workflow.type":w.workflowType}});if(n.workflowSpans.set(w.workflowId,{span:k,createdAt:Date.now()}),Q(k,w.headers),n.recordPayloads&&w.input!==void 0)k.setAttribute("weft.payload.input",C(w.input,n.maxPayloadSize));A(n,k,w),n.metrics.increment("weft.workflow.started"),n.metrics.increment("weft.dpmo.operations"),i(w)},*activity(w,i){let S=n.tracer.startSpan(`activity:${w.activityName}`,{attributes:{"weft.activity.name":w.activityName,"weft.activity.attempt":w.attempt}},j(n,w.workflowId));if(Q(S,w.headers),n.recordPayloads&&w.input!==void 0)S.setAttribute("weft.payload.input",C(w.input,n.maxPayloadSize));A(n,S,w);let k=Date.now();return yield*B(n,S,()=>i(w),()=>{n.metrics.record("weft.activity.duration",Date.now()-k),n.metrics.increment("weft.activity.attempts")})},*sleep(w,i){let S=n.tracer.startSpan("sleep",{attributes:{"weft.sleep.duration":w.duration}},j(n,w.workflowId));A(n,S,w),yield*B(n,S,()=>i(w))},*waitForSignal(w,i){let S=n.tracer.startSpan("waitForSignal",{attributes:{"weft.signal.name":w.signalName}},j(n,w.workflowId));return A(n,S,w),yield*B(n,S,()=>i(w))},async childWorkflow(w,i){let S=[],k=J(w.parentHeaders);if(k)S.push({context:{traceId:k.traceId,spanId:k.spanId,traceFlags:k.traceFlags}});let f=n.tracer.startSpan(`childWorkflow:${w.workflowType}`,{attributes:{"weft.child_workflow.type":w.workflowType,"weft.child_workflow.id":w.childWorkflowId,"weft.child_workflow.parent_id":w.workflowId},links:S},n.api.context.ROOT_CONTEXT);if(Q(f,w.headers),n.recordPayloads&&w.input!==void 0)f.setAttribute("weft.payload.input",C(w.input,n.maxPayloadSize));return n.metrics.increment("weft.child_workflow.started"),x(n,f,()=>i(w))},signalReceived(w,i){let S=n.tracer.startSpan(`signal:received:${w.signalName}`,{attributes:{"weft.signal.name":w.signalName,"weft.signal.workflow_id":w.workflowId}});A(n,S,w),_(n,S,()=>i(w))}}}function Tn(n){let{attributeExtractor:w,eventTarget:i,maxPayloadSize:S=O,metrics:k=new D,openTelemetryApi:f=K(),recordPayloads:y=!1,tracerName:p="weft",tracerVersion:v}=n??{},G=f,{trace:W,SpanStatusCode:d}=G,R=W.getTracer(p,v);return{api:G,trace:W,SpanStatusCode:d,tracer:R,recordPayloads:y,maxPayloadSize:S,attributeExtractor:w,eventTarget:i,metrics:k,workflowSpans:new Map}}function nw(n){let w=Tn(n),i=m(w),S=g(w),k={...i,...S},f=u(w);return{interceptor:k,metrics:w.metrics,...f}}export{b as serializeMetricsSnapshotForPrometheus,Z as parseTraceParent,U as injectTraceParent,K as getOpenTelemetryApi,fn as generateTraceId,vn as generateSpanId,M as formatTraceParent,J as extractTraceParent,pn as createOpenTelemetryMetrics,nw as createObservabilityInterceptors,An as createMetricsCollectorExporter,D as MetricsCollector,X as METRICS};

package/dist/runtime/portable.d.ts

@@ -15,6 +15,15 @@ type PortableRuntimeTestOverrides = {
     document?: typeof globalThis.document | undefined;
 };
 export declare function setPortableRuntimeTestOverridesForTesting(overrides?: PortableRuntimeTestOverrides): void;
+/**
+ * Whether the current runtime is Bun. Honors
+ * {@link setPortableRuntimeTestOverridesForTesting}, unlike a bare
+ * `typeof Bun !== 'undefined'` check, so callers that need to simulate a
+ * non-Bun runtime in tests (e.g. to exercise a Node or browser fallback
+ * branch) can do so without a real environment change.
+ * @internal
+ */
+export declare function isBunRuntime(): boolean;
 /**
  * Detect the current JavaScript runtime.
  * Detection precedence is bun → node → browser → edge: a Bun process running
@@ -31,6 +40,16 @@ export declare function setPortableRuntimeTestOverridesForTesting(overrides?: Po
  * ```
  */
 export declare function detectRuntime(): RuntimeKind;
+/**
+ * Read an environment variable without assuming a runtime.
+ *
+ * Prefers `Bun.env` under Bun, falls back to `process.env` under Node, and
+ * returns `undefined` anywhere else (browsers, edge runtimes) — where
+ * neither global exists and a bare `Bun.env[...]` or `process.env[...]`
+ * reference would throw a `ReferenceError`.
+ * @internal
+ */
+export declare function readEnvironmentVariable(name: string): string | undefined;
 /**
  * Pause execution for the given number of milliseconds.
  *
@@ -85,6 +104,20 @@ export declare function hashBytes(data: Uint8Array): string;
  * ```
  */
 export declare function hashString(data: string): string;
+/**
+ * Load a Node.js built-in module without a static `node:*` import.
+ *
+ * This package is ESM (`"type": "module"` in package.json), so `require`
+ * is not defined in Node runtime. `process.getBuiltinModule` (Node 22.5+,
+ * also implemented by Bun) is the correct way to load Node built-ins from
+ * ESM code without needing `createRequire` — and, crucially, without a
+ * static `import ... from 'node:*'` specifier that a browser bundler would
+ * try to resolve or stub. Returns `undefined` in the browser or any runtime
+ * lacking `process.getBuiltinModule`, so callers on a browser-reachable path
+ * must treat the result as optional rather than throwing at import time.
+ * @internal
+ */
+export declare function tryLoadNodeBuiltin<T>(id: string): T | undefined;
 /**
  * Return the byte size of a file at the given path.
  *

package/dist/runtime/portable.js

@@ -2,8 +2,13 @@ let portableRuntimeTestOverrides;
 export function setPortableRuntimeTestOverridesForTesting(overrides) {
   portableRuntimeTestOverrides = overrides;
 }
-function isBunRuntime() {
-  return typeof (portableRuntimeTestOverrides && "bun" in portableRuntimeTestOverrides ? portableRuntimeTestOverrides.bun : globalThis.Bun) < "u";
+function getBunGlobal() {
+  if (portableRuntimeTestOverrides && "bun" in portableRuntimeTestOverrides)
+    return portableRuntimeTestOverrides.bun;
+  return globalThis.Bun;
+}
+export function isBunRuntime() {
+  return typeof getBunGlobal() < "u";
 }
 function getProcess() {
   if (portableRuntimeTestOverrides && "process" in portableRuntimeTestOverrides)
@@ -28,6 +33,12 @@ export function detectRuntime() {
       return detector.kind;
   return "edge";
 }
+export function readEnvironmentVariable(name) {
+  const bun = getBunGlobal();
+  if (bun !== void 0)
+    return bun.env[name];
+  return getProcess()?.env?.[name];
+}
 export function sleep(ms) {
   if (isBunRuntime())
     return Bun.sleep(ms);
@@ -49,7 +60,7 @@ export function hashBytes(data) {
 export function hashString(data) {
   return fnv1a64(textEncoder.encode(data));
 }
-function loadNodeBuiltin(id) {
+export function tryLoadNodeBuiltin(id) {
   const getBuiltinModule = getProcess()?.getBuiltinModule;
   if (typeof getBuiltinModule !== "function")
     return;
@@ -58,7 +69,7 @@ function loadNodeBuiltin(id) {
 export function fileSize(path) {
   if (isBunRuntime())
     return Bun.file(path).size;
-  const fs = loadNodeBuiltin("node:fs");
+  const fs = tryLoadNodeBuiltin("node:fs");
   if (!fs)
     throw Error("fileSize() requires Bun or Node 22.5+ (process.getBuiltinModule). Not available in browser or edge runtimes.");
   try {
@@ -70,7 +81,7 @@ export function fileSize(path) {
   }
 }
 function loadNodeZlib() {
-  const zlib = loadNodeBuiltin("node:zlib");
+  const zlib = tryLoadNodeBuiltin("node:zlib");
   if (!zlib)
     throw Error("gzip/gunzip require Bun or Node 22.5+ (process.getBuiltinModule). " + "Not available in browser or edge runtimes \u2014 use CompressionStream directly.");
   return zlib;
@@ -86,5 +97,5 @@ export function gunzipSync(data) {
   return new Uint8Array(loadNodeZlib().gunzipSync(data));
 }
 export function tryLoadNodeZlib() {
-  return loadNodeBuiltin("node:zlib");
+  return tryLoadNodeBuiltin("node:zlib");
 }

package/dist/server/access-policy-metadata.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Canonical discovery-document metadata for operation access policies.
+ *
+ * @module server/access-policy-metadata
+ */
+import { z } from 'zod';
+import type { AccessPolicy } from './authorization.ts';
+import type { ParameterizedAccessHint } from './operation-catalog/types.ts';
+export declare const ScopeRequirementMetadataSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        anyOf: "anyOf";
+        allOf: "allOf";
+    }>;
+    scopes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const AccessPolicyMetadataSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"public">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"authenticated">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"scoped">;
+    scopes: z.ZodObject<{
+        kind: z.ZodEnum<{
+            anyOf: "anyOf";
+            allOf: "allOf";
+        }>;
+        scopes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"optionalAuth">;
+    authenticatedScopes: z.ZodObject<{
+        kind: z.ZodEnum<{
+            anyOf: "anyOf";
+            allOf: "allOf";
+        }>;
+        scopes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"scopedAlternatives">;
+    alternatives: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            anyOf: "anyOf";
+            allOf: "allOf";
+        }>;
+        scopes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "kind">;
+export declare const ParameterizedAccessMetadataSchema: z.ZodObject<{
+    discriminator: z.ZodString;
+    defaultValue: z.ZodOptional<z.ZodString>;
+    variants: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        access: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"public">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"authenticated">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"scoped">;
+            scopes: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    anyOf: "anyOf";
+                    allOf: "allOf";
+                }>;
+                scopes: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"optionalAuth">;
+            authenticatedScopes: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    anyOf: "anyOf";
+                    allOf: "allOf";
+                }>;
+                scopes: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"scopedAlternatives">;
+            alternatives: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    anyOf: "anyOf";
+                    allOf: "allOf";
+                }>;
+                scopes: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AccessPolicyMetadata = z.infer<typeof AccessPolicyMetadataSchema>;
+export type ParameterizedAccessMetadata = z.infer<typeof ParameterizedAccessMetadataSchema>;
+/** Serialize an operation's static access policy for discovery documents. */
+export declare function serializeAccessPolicy(policy: AccessPolicy): AccessPolicyMetadata;
+/** Serialize discriminator-specific access overrides for discovery documents. */
+export declare function serializeParameterizedAccess(hint: ParameterizedAccessHint): ParameterizedAccessMetadata;

package/dist/server/access-policy-metadata.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { compareStrings } from "./json-schema-utilities.js";
+export const ScopeRequirementMetadataSchema = z.strictObject({
+  kind: z.enum(["anyOf", "allOf"]),
+  scopes: z.array(z.string()).min(1)
+}), AccessPolicyMetadataSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("public") }),
+  z.strictObject({ kind: z.literal("authenticated") }),
+  z.strictObject({
+    kind: z.literal("scoped"),
+    scopes: ScopeRequirementMetadataSchema
+  }),
+  z.strictObject({
+    kind: z.literal("optionalAuth"),
+    authenticatedScopes: ScopeRequirementMetadataSchema
+  }),
+  z.strictObject({
+    kind: z.literal("scopedAlternatives"),
+    alternatives: z.array(ScopeRequirementMetadataSchema).min(1)
+  })
+]), ParameterizedAccessMetadataSchema = z.strictObject({
+  discriminator: z.string(),
+  defaultValue: z.string().optional(),
+  variants: z.array(z.strictObject({
+    value: z.string(),
+    access: AccessPolicyMetadataSchema
+  }))
+});
+export function serializeAccessPolicy(policy) {
+  switch (policy.kind) {
+    case "public":
+      return { kind: "public" };
+    case "authenticated":
+      return { kind: "authenticated" };
+    case "scoped":
+      return { kind: "scoped", scopes: serializeScopeRequirement(policy.scopes) };
+    case "optionalAuth":
+      return {
+        kind: "optionalAuth",
+        authenticatedScopes: serializeScopeRequirement(policy.authenticatedScopes)
+      };
+    case "scopedAlternatives":
+      return {
+        kind: "scopedAlternatives",
+        alternatives: policy.alternatives.map(serializeScopeRequirement)
+      };
+    default:
+      return unsupportedAccessPolicy(policy);
+  }
+}
+export function serializeParameterizedAccess(hint) {
+  return {
+    discriminator: hint.discriminator,
+    ...hint.defaultValue === void 0 ? {} : { defaultValue: hint.defaultValue },
+    variants: hint.variants.map((variant) => ({
+      value: variant.value,
+      access: serializeAccessPolicy(variant.access)
+    }))
+  };
+}
+function serializeScopeRequirement(requirement) {
+  switch (requirement.kind) {
+    case "anyOf":
+    case "allOf":
+      return {
+        kind: requirement.kind,
+        scopes: [...requirement.scopes].toSorted(compareStrings)
+      };
+    default:
+      return unsupportedScopeRequirement(requirement);
+  }
+}
+function unsupportedAccessPolicy(policy) {
+  throw Error(`cannot serialize unsupported access policy: ${String(policy)}`);
+}
+function unsupportedScopeRequirement(requirement) {
+  throw Error(`cannot serialize unsupported scope requirement: ${String(requirement)}`);
+}

package/dist/server/engine-event-feed-backend.d.ts

@@ -20,11 +20,30 @@
  *
  * @module server/engine-event-feed-backend
  */
-import type { Engine } from '../core/engine.ts';
+import type { RegistryAgnosticEngine } from '../core/engine.ts';
 import { type WorkflowEventFeedBackend } from './workflow-event-feed.ts';
 /**
  * Build the production `WorkflowEventFeedBackend`. Call once per
  * engine instance and share the returned backend across every
- * transport that needs a feed.
+ * transport that needs a feed. Pass the result to `createWorkflowEventFeed()`
+ * to build a `WorkflowEventFeed` for `HandlerOptions.workflowEventFeed`.
+ *
+ * Accepts `RegistryAgnosticEngine` — the same registry-erased engine type
+ * `handleRequest()` and `ServeOptions.engine` accept — so a concretely
+ * narrowed engine from `Engine.create({ workflows })` works here without a
+ * call-site cast.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import {
+ *   createEngineEventFeedBackend,
+ *   createWorkflowEventFeed,
+ * } from '@lostgradient/weft/server/handler';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const workflowEventFeed = createWorkflowEventFeed(createEngineEventFeedBackend(engine));
+ * void workflowEventFeed;
+ * ```
  */
-export declare function createEngineEventFeedBackend(engine: Engine): WorkflowEventFeedBackend;
+export declare function createEngineEventFeedBackend(engine: RegistryAgnosticEngine): WorkflowEventFeedBackend;

package/dist/server/fault-to-http.d.ts

@@ -2,13 +2,9 @@
  * `faultToHttpResponse` — pure mapper from a transport-neutral
  * `OperationFault` into a `Response` shaped for the REST surface.
  *
- * Body shape: `{ error: { code, message, data? } }`. The `code` matches the
- * fault discriminant verbatim so REST clients can switch on the same names
- * that JSON-RPC clients see in their `data.weftCode`.
- *
- * Pure: no engine, no I/O, no logging. Errors visible to clients are
- * exactly what the fault carries; internal `EngineFailure` detail belongs
- * in server logs, not the response body.
+ * This fallback uses the same flat, audited projection as every explicit REST
+ * binding. Keeping one mapper prevents a binding that omits `shapeFault` from
+ * accidentally exposing a broader nested payload or raw EngineFailure detail.
  */
 import { type OperationFault } from './operation-fault.ts';
 export declare function faultToHttpResponse(fault: OperationFault): Response;

package/dist/server/fault-to-http.js

@@ -1,36 +1,4 @@
-import { FAULT_CODE_TO_HTTP_STATUS } from "./operation-fault.js";
+import { shapeRestFaultAsJson } from "./operation-fault.js";
 export function faultToHttpResponse(fault) {
-  const status = FAULT_CODE_TO_HTTP_STATUS[fault.code], body = JSON.stringify({ error: shapeErrorBody(fault) }), headers = new Headers({ "content-type": "application/json; charset=utf-8" });
-  return new Response(body, { status, headers });
-}
-function shapeErrorBody(fault) {
-  const base = { code: fault.code, message: fault.message };
-  if (fault.code === "EngineFailure" || fault.code === "NotImplemented")
-    return base;
-  if (fault.code === "Timeout")
-    return shapeTimeoutBody(base, fault.data);
-  if (fault.code === "NotFound")
-    return shapeNotFoundBody(base, fault.data);
-  return { ...base, data: fault.data };
-}
-function shapeTimeoutBody(base, data) {
-  const defined = filterDefined(data);
-  return Object.keys(defined).length === 0 ? base : { ...base, data: defined };
-}
-function shapeNotFoundBody(base, data) {
-  const shaped = {
-    resource: data.resource
-  };
-  if (data.identifier !== void 0)
-    shaped.identifier = data.identifier;
-  if (data.weftCode !== void 0)
-    shaped.weftCode = data.weftCode;
-  return { ...base, data: shaped };
-}
-function filterDefined(input) {
-  const output = {};
-  for (const [key, value] of Object.entries(input))
-    if (value !== void 0)
-      output[key] = value;
-  return output;
+  return shapeRestFaultAsJson(fault);
 }

package/dist/server/fleet-event-feed.d.ts

@@ -1,5 +1,20 @@
 import { type Storage } from '../storage/interface.ts';
 import { type Cursor, type FeedEventKind, type ReplayLiveSubscribeOptions, type WorkflowEventFeedOptions } from './workflow-event-feed.ts';
+/**
+ * A single committed record from the fleet-wide event feed — cross-workflow
+ * lifecycle and system events, optionally scoped to one `workflowId`.
+ * Returned by `FleetEventFeed.replay()` / `FleetEventFeed.subscribe()`, and
+ * consumed directly by the `/v1/events/sse` REST route.
+ *
+ * @example
+ * ```ts
+ * import type { FleetEventEnvelope } from '@lostgradient/weft/server/handler';
+ *
+ * declare const envelope: FleetEventEnvelope;
+ * console.log(envelope.kind); // e.g. 'workflow:completed'
+ * console.log(envelope.workflowId); // string | undefined
+ * ```
+ */
 export type FleetEventEnvelope = {
     readonly kind: FeedEventKind;
     readonly workflowId?: string | undefined;
@@ -17,6 +32,23 @@ export type FleetEventInput = {
 export type FleetWorkflowEventInput = FleetEventInput & {
     readonly workflowId: string;
 };
+/**
+ * The fleet-wide event feed: append cross-workflow events, replay committed
+ * history from a cursor, then subscribe for live delivery. This is the shape
+ * of `HandlerOptions.fleetEventFeed` — build a real one with
+ * `createFleetEventFeed()` to drive `/v1/events/sse` through `handleRequest()`
+ * without `serve()`.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import { createFleetEventFeed, type FleetEventFeed } from '@lostgradient/weft/server/handler';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const fleetEventFeed: FleetEventFeed = createFleetEventFeed(engine.storage);
+ * void fleetEventFeed;
+ * ```
+ */
 export type FleetEventFeed = {
     append(event: FleetEventInput): Promise<FleetEventEnvelope>;
     appendWorkflowEventIfPresent(event: FleetWorkflowEventInput): Promise<FleetEventEnvelope | null>;
@@ -28,4 +60,37 @@ export type FleetEventFeed = {
     snapshotTailSequence(): Promise<number>;
     dispose(): void;
 };
+/**
+ * Build a `FleetEventFeed` backed by the given `Storage` — typically
+ * `engine.storage`. Pass the result as `HandlerOptions.fleetEventFeed` to
+ * drive `/v1/events/sse` through `handleRequest()` directly, without
+ * `serve()`. Call once per storage instance and share the returned feed
+ * across every transport that needs it.
+ *
+ * **This feed does not subscribe to `Engine` events on its own.** `serve()`
+ * bridges engine lifecycle events into it via `wireEventBroadcasting()`; a
+ * direct `handleRequest()` host that skips `serve()` is responsible for
+ * calling `fleetEventFeed.append()` (or `appendWorkflowEventIfPresent()`)
+ * itself for whatever events it wants `/v1/events/sse` to carry — e.g. from
+ * `engine.addEventListener(...)` handlers wired up separately.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import {
+ *   createFleetEventFeed,
+ *   handleRequest,
+ *   type HandlerOptions,
+ * } from '@lostgradient/weft/server/handler';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const fleetEventFeed = createFleetEventFeed(engine.storage);
+ * const options: HandlerOptions = { fleetEventFeed };
+ *
+ * async function handleFleetEventsSse(request: Request): Promise<Response> {
+ *   return handleRequest(request, engine, options);
+ * }
+ * void handleFleetEventsSse;
+ * ```
+ */
 export declare function createFleetEventFeed(storage: Storage, feedOptions?: WorkflowEventFeedOptions): FleetEventFeed;