yaml-flow 8.3.0 → 8.4.1

package/lib/step-machine-public/index.js

@@ -1,5 +1,5 @@
-import'ajv-formats';import {createRequire}from'module';import {fileURLToPath}from'url';import {dirname,resolve}from'path';import {existsSync}from'fs';function b(r,t,e,n){let s=r.steps[e];if(!s)throw new Error(`Step "${e}" not found in flow configuration`);if(n.result==="failure"&&s.retry){let a=t.retryCounts[e]??0;if(a<s.retry.max_attempts)return {newState:{...t,retryCounts:{...t.retryCounts,[e]:a+1},updatedAt:Date.now()},nextStep:e,isTerminal:false,isCircuitBroken:false,shouldRetry:true}}let o=s.failure_transitions?.[n.result]??s.transitions[n.result];if(!o)throw new Error(`No transition defined for result "${n.result}" in step "${e}"`);let i=!!r.terminal_states[o];return {newState:{...t,currentStep:o,stepHistory:[...t.stepHistory,e],retryCounts:{...t.retryCounts,[e]:0},updatedAt:Date.now()},nextStep:o,isTerminal:i,isCircuitBroken:false,shouldRetry:false}}function j(r,t,e){let n=r.steps[e];if(!n?.circuit_breaker)return {broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:(t.iterationCounts[e]??0)+1},updatedAt:Date.now()}};let s=t.iterationCounts[e]??0;return s>=n.circuit_breaker.max_iterations?{broken:true,redirectStep:n.circuit_breaker.on_open,newState:{...t,currentStep:n.circuit_breaker.on_open,updatedAt:Date.now()}}:{broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:s+1},updatedAt:Date.now()}}}function F(r,t,e){let n=r.steps[t];if(!n)throw new Error(`Step "${t}" not found`);if(n.expects_data){let s={};for(let o of n.expects_data)s[o]=e[o];return s}return {...e}}function C(r,t){if(r===false||r===void 0)return {};if(typeof r=="string")return {[r]:t[r]};if(Array.isArray(r)){let e={};for(let n of r)e[n]=t[n];return e}return {}}function E(r,t){let e=Date.now();return {runId:t,flowId:r.id??"unnamed",currentStep:r.settings.start_step,status:"running",stepHistory:[],iterationCounts:{},retryCounts:{},startedAt:e,updatedAt:e}}var h=class{runs=new Map;data=new Map;async saveRunState(t,e){this.runs.set(t,{...e});}async loadRunState(t){let e=this.runs.get(t);return e?{...e}:null}async deleteRunState(t){this.runs.delete(t),this.data.delete(t);}async setData(t,e,n){this.data.has(t)||this.data.set(t,{});let s=this.data.get(t);s[e]=n;}async getData(t,e){return this.data.get(t)?.[e]}async getAllData(t){return {...this.data.get(t)??{}}}async clearData(t){this.data.delete(t);}async listRuns(){return Array.from(this.runs.keys())}clear(){this.runs.clear(),this.data.clear();}};function et(){return typeof crypto<"u"&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,r=>{let t=Math.random()*16|0;return (r==="x"?t:t&3|8).toString(16)})}var k=class{flow;handlers;store;components;options;listeners=new Map;aborted=false;constructor(t,e,n={}){this.flow=t,this.handlers=new Map(Object.entries(e)),this.store=n.store??new h,this.components=n.components??{},this.options=n,n.signal&&n.signal.addEventListener("abort",()=>{this.aborted=true;}),this.validateFlow();}validateFlow(){let{settings:t,steps:e,terminal_states:n}=this.flow;if(!t?.start_step)throw new Error("Flow must have settings.start_step defined");if(!e||Object.keys(e).length===0)throw new Error("Flow must have at least one step defined");if(!n||Object.keys(n).length===0)throw new Error("Flow must have at least one terminal_state defined");if(!e[t.start_step]&&!n[t.start_step])throw new Error(`Start step "${t.start_step}" not found`);for(let[s,o]of Object.entries(e)){for(let[i,a]of Object.entries(o.transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" transition "${i}" points to unknown step "${a}"`);if(o.failure_transitions){for(let[i,a]of Object.entries(o.failure_transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" failure_transition "${i}" points to unknown step "${a}"`)}}}on(t,e){this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(e);}off(t,e){this.listeners.get(t)?.delete(e);}emit(t){let e=this.listeners.get(t.type);if(e)for(let n of e)try{n(t);}catch{}}sleep(t){return new Promise(e=>setTimeout(e,t))}async run(t){let e=et(),n=E(this.flow,e);if(await this.store.saveRunState(e,n),t)for(let[s,o]of Object.entries(t))await this.store.setData(e,s,o);this.emit({type:"flow:start",runId:e,timestamp:n.startedAt,data:{initialData:t??{}}});try{return await this.executeLoop(e,n)}catch(s){let o=s instanceof Error?s:new Error(String(s));return this.emit({type:"flow:error",runId:e,timestamp:Date.now(),data:{error:o.message}}),this.options.onError?.(o),n={...n,status:"failed",updatedAt:Date.now()},await this.store.saveRunState(e,n),{runId:e,status:"failed",data:await this.store.getAllData(e),finalStep:n.currentStep,stepHistory:n.stepHistory,durationMs:Date.now()-n.startedAt,error:o}}}async resume(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);if(e.status==="completed"||e.status==="failed")throw new Error(`Cannot resume a ${e.status} run`);let n={...e,status:"running",pausedAt:void 0,updatedAt:Date.now()};return await this.store.saveRunState(t,n),this.emit({type:"flow:resumed",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}}),this.executeLoop(t,n)}async pause(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);let n={...e,status:"paused",pausedAt:Date.now(),updatedAt:Date.now()};await this.store.saveRunState(t,n),this.emit({type:"flow:paused",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}});}async executeLoop(t,e){let n=this.flow.settings.max_total_steps??100,s=this.flow.settings.timeout_ms,o=e,i=0;for(;i<n;){if(this.aborted)return o={...o,status:"cancelled",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"cancelled",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};if(s&&Date.now()-o.startedAt>s)return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"timeout",intent:"timeout",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};let a=o.currentStep,c=this.flow.terminal_states[a];if(c){o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o);let p=await this.store.getAllData(t),l={runId:t,status:"completed",intent:c.return_intent,data:C(c.return_artifacts,p),finalStep:a,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};return this.emit({type:"flow:complete",runId:t,timestamp:Date.now(),data:{...l}}),this.options.onComplete?.(l),l}let d=j(this.flow,o,a);if(d.broken){o=d.newState,await this.store.saveRunState(t,o),i++;continue}o=d.newState;let f=await this.store.getAllData(t),u=F(this.flow,a,f),m={runId:t,stepName:a,components:this.components,store:this.store,signal:this.options.signal,emit:(p,l)=>{this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{event:p,payload:l}});}};this.emit({type:"step:start",runId:t,timestamp:Date.now(),data:{step:a,input:u}});let g;try{let p=this.handlers.get(a);if(!p)throw new Error(`No handler registered for step "${a}"`);g=await p(u,m);}catch(p){let l=p instanceof Error?p:new Error(String(p));this.emit({type:"step:error",runId:t,timestamp:Date.now(),data:{step:a,error:l.message}}),g={result:"failure",data:{error:l.message}};}if(g.data)for(let[p,l]of Object.entries(g.data))await this.store.setData(t,p,l);this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{step:a,result:g.result}}),this.options.onStep?.(a,g);let w=b(this.flow,o,a,g);if(o=w.newState,w.shouldRetry){await this.store.saveRunState(t,o);let p=this.flow.steps[a];if(p.retry?.delay_ms){let l=o.retryCounts[a]??0,S=p.retry.backoff_multiplier?p.retry.delay_ms*Math.pow(p.retry.backoff_multiplier,l-1):p.retry.delay_ms;await this.sleep(S);}i++;continue}await this.store.saveRunState(t,o),this.emit({type:"transition",runId:t,timestamp:Date.now(),data:{from:a,to:o.currentStep,result:g.result}}),this.options.onTransition?.(a,o.currentStep),i++;}return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"max_iterations",intent:"max_iterations",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt}}};function v(r,t,e){return new k(r,t,e)}async function $(r){return (await import('yaml')).parse(r)}async function rt(r){let t=await fetch(r);if(!t.ok)throw new Error(`Failed to load flow from ${r}: ${t.statusText}`);let e=t.headers.get("content-type")??"",n=await t.text();return e.includes("json")||r.endsWith(".json")?JSON.parse(n):$(n)}async function nt(r){let e=await(await import('fs/promises')).readFile(r,"utf-8");return r.endsWith(".json")?JSON.parse(e):$(e)}function D(r){let t=[];if(!r||typeof r!="object")return ["Flow must be an object"];let e=r;if(!e.settings||typeof e.settings!="object"?t.push('Flow must have a "settings" object'):typeof e.settings.start_step!="string"&&t.push("settings.start_step must be a string"),!e.steps||typeof e.steps!="object")t.push('Flow must have a "steps" object');else {let n=e.steps;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Step "${s}" must be an object`);continue}let i=o;(!i.transitions||typeof i.transitions!="object")&&t.push(`Step "${s}" must have a "transitions" object`),i.failure_transitions!==void 0&&typeof i.failure_transitions!="object"&&t.push(`Step "${s}" failure_transitions must be an object when provided`);}}if(!e.terminal_states||typeof e.terminal_states!="object")t.push('Flow must have a "terminal_states" object');else {let n=e.terminal_states;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Terminal state "${s}" must be an object`);continue}typeof o.return_intent!="string"&&t.push(`Terminal state "${s}" must have a "return_intent" string`);}}return t}async function P(r){let t;typeof r=="string"?r.startsWith("http://")||r.startsWith("https://")?t=await rt(r):r.includes("{")?t=JSON.parse(r):t=await nt(r):t=r;let e=D(t);if(e.length>0)throw new Error(`Invalid step flow configuration:
+import'ajv-formats';import {createRequire}from'module';import {fileURLToPath}from'url';import {dirname,resolve}from'path';import {existsSync}from'fs';function b(r,t,e,n){let s=r.steps[e];if(!s)throw new Error(`Step "${e}" not found in flow configuration`);if(n.result==="failure"&&s.retry){let a=t.retryCounts[e]??0;if(a<s.retry.max_attempts)return {newState:{...t,retryCounts:{...t.retryCounts,[e]:a+1},updatedAt:Date.now()},nextStep:e,isTerminal:false,isCircuitBroken:false,shouldRetry:true}}let o=s.failure_transitions?.[n.result]??s.transitions[n.result];if(!o)throw new Error(`No transition defined for result "${n.result}" in step "${e}"`);let i=!!r.terminal_states[o];return {newState:{...t,currentStep:o,stepHistory:[...t.stepHistory,e],retryCounts:{...t.retryCounts,[e]:0},updatedAt:Date.now()},nextStep:o,isTerminal:i,isCircuitBroken:false,shouldRetry:false}}function j(r,t,e){let n=r.steps[e];if(!n?.circuit_breaker)return {broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:(t.iterationCounts[e]??0)+1},updatedAt:Date.now()}};let s=t.iterationCounts[e]??0;return s>=n.circuit_breaker.max_iterations?{broken:true,redirectStep:n.circuit_breaker.on_open,newState:{...t,currentStep:n.circuit_breaker.on_open,updatedAt:Date.now()}}:{broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:s+1},updatedAt:Date.now()}}}function F(r,t,e){let n=r.steps[t];if(!n)throw new Error(`Step "${t}" not found`);if(n.expects_data){let s={};for(let o of n.expects_data)s[o]=e[o];return s}return {...e}}function C(r,t){if(r===false||r===void 0)return {};if(typeof r=="string")return {[r]:t[r]};if(Array.isArray(r)){let e={};for(let n of r)e[n]=t[n];return e}return {}}function E(r,t){let e=Date.now();return {runId:t,flowId:r.id??"unnamed",currentStep:r.settings.start_step,status:"running",stepHistory:[],iterationCounts:{},retryCounts:{},startedAt:e,updatedAt:e}}var h=class{runs=new Map;data=new Map;async saveRunState(t,e){this.runs.set(t,{...e});}async loadRunState(t){let e=this.runs.get(t);return e?{...e}:null}async deleteRunState(t){this.runs.delete(t),this.data.delete(t);}async setData(t,e,n){this.data.has(t)||this.data.set(t,{});let s=this.data.get(t);s[e]=n;}async getData(t,e){return this.data.get(t)?.[e]}async getAllData(t){return {...this.data.get(t)??{}}}async clearData(t){this.data.delete(t);}async listRuns(){return Array.from(this.runs.keys())}clear(){this.runs.clear(),this.data.clear();}};function et(){return typeof crypto<"u"&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,r=>{let t=Math.random()*16|0;return (r==="x"?t:t&3|8).toString(16)})}var x=class{flow;handlers;store;components;options;listeners=new Map;aborted=false;constructor(t,e,n={}){this.flow=t,this.handlers=new Map(Object.entries(e)),this.store=n.store??new h,this.components=n.components??{},this.options=n,n.signal&&n.signal.addEventListener("abort",()=>{this.aborted=true;}),this.validateFlow();}validateFlow(){let{settings:t,steps:e,terminal_states:n}=this.flow;if(!t?.start_step)throw new Error("Flow must have settings.start_step defined");if(!e||Object.keys(e).length===0)throw new Error("Flow must have at least one step defined");if(!n||Object.keys(n).length===0)throw new Error("Flow must have at least one terminal_state defined");if(!e[t.start_step]&&!n[t.start_step])throw new Error(`Start step "${t.start_step}" not found`);for(let[s,o]of Object.entries(e)){for(let[i,a]of Object.entries(o.transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" transition "${i}" points to unknown step "${a}"`);if(o.failure_transitions){for(let[i,a]of Object.entries(o.failure_transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" failure_transition "${i}" points to unknown step "${a}"`)}}}on(t,e){this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(e);}off(t,e){this.listeners.get(t)?.delete(e);}emit(t){let e=this.listeners.get(t.type);if(e)for(let n of e)try{n(t);}catch{}}sleep(t){return new Promise(e=>setTimeout(e,t))}async run(t){let e=et(),n=E(this.flow,e);if(await this.store.saveRunState(e,n),t)for(let[s,o]of Object.entries(t))await this.store.setData(e,s,o);this.emit({type:"flow:start",runId:e,timestamp:n.startedAt,data:{initialData:t??{}}});try{return await this.executeLoop(e,n)}catch(s){let o=s instanceof Error?s:new Error(String(s));return this.emit({type:"flow:error",runId:e,timestamp:Date.now(),data:{error:o.message}}),this.options.onError?.(o),n={...n,status:"failed",updatedAt:Date.now()},await this.store.saveRunState(e,n),{runId:e,status:"failed",data:await this.store.getAllData(e),finalStep:n.currentStep,stepHistory:n.stepHistory,durationMs:Date.now()-n.startedAt,error:o}}}async resume(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);if(e.status==="completed"||e.status==="failed")throw new Error(`Cannot resume a ${e.status} run`);let n={...e,status:"running",pausedAt:void 0,updatedAt:Date.now()};return await this.store.saveRunState(t,n),this.emit({type:"flow:resumed",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}}),this.executeLoop(t,n)}async pause(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);let n={...e,status:"paused",pausedAt:Date.now(),updatedAt:Date.now()};await this.store.saveRunState(t,n),this.emit({type:"flow:paused",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}});}async executeLoop(t,e){let n=this.flow.settings.max_total_steps??100,s=this.flow.settings.timeout_ms,o=e,i=0;for(;i<n;){if(this.aborted)return o={...o,status:"cancelled",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"cancelled",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};if(s&&Date.now()-o.startedAt>s)return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"timeout",intent:"timeout",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};let a=o.currentStep,c=this.flow.terminal_states[a];if(c){o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o);let p=await this.store.getAllData(t),l={runId:t,status:"completed",intent:c.return_intent,data:C(c.return_artifacts,p),finalStep:a,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};return this.emit({type:"flow:complete",runId:t,timestamp:Date.now(),data:{...l}}),this.options.onComplete?.(l),l}let d=j(this.flow,o,a);if(d.broken){o=d.newState,await this.store.saveRunState(t,o),i++;continue}o=d.newState;let f=await this.store.getAllData(t),u=F(this.flow,a,f),m={runId:t,stepName:a,components:this.components,store:this.store,signal:this.options.signal,emit:(p,l)=>{this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{event:p,payload:l}});}};this.emit({type:"step:start",runId:t,timestamp:Date.now(),data:{step:a,input:u}});let g;try{let p=this.handlers.get(a);if(!p)throw new Error(`No handler registered for step "${a}"`);g=await p(u,m);}catch(p){let l=p instanceof Error?p:new Error(String(p));this.emit({type:"step:error",runId:t,timestamp:Date.now(),data:{step:a,error:l.message}}),g={result:"failure",data:{error:l.message}};}if(g.data)for(let[p,l]of Object.entries(g.data))await this.store.setData(t,p,l);this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{step:a,result:g.result}}),this.options.onStep?.(a,g);let w=b(this.flow,o,a,g);if(o=w.newState,w.shouldRetry){await this.store.saveRunState(t,o);let p=this.flow.steps[a];if(p.retry?.delay_ms){let l=o.retryCounts[a]??0,S=p.retry.backoff_multiplier?p.retry.delay_ms*Math.pow(p.retry.backoff_multiplier,l-1):p.retry.delay_ms;await this.sleep(S);}i++;continue}await this.store.saveRunState(t,o),this.emit({type:"transition",runId:t,timestamp:Date.now(),data:{from:a,to:o.currentStep,result:g.result}}),this.options.onTransition?.(a,o.currentStep),i++;}return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"max_iterations",intent:"max_iterations",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt}}};function v(r,t,e){return new x(r,t,e)}async function $(r){return (await import('yaml')).parse(r)}async function rt(r){let t=await fetch(r);if(!t.ok)throw new Error(`Failed to load flow from ${r}: ${t.statusText}`);let e=t.headers.get("content-type")??"",n=await t.text();return e.includes("json")||r.endsWith(".json")?JSON.parse(n):$(n)}async function nt(r){let e=await(await import('fs/promises')).readFile(r,"utf-8");return r.endsWith(".json")?JSON.parse(e):$(e)}function D(r){let t=[];if(!r||typeof r!="object")return ["Flow must be an object"];let e=r;if(!e.settings||typeof e.settings!="object"?t.push('Flow must have a "settings" object'):typeof e.settings.start_step!="string"&&t.push("settings.start_step must be a string"),!e.steps||typeof e.steps!="object")t.push('Flow must have a "steps" object');else {let n=e.steps;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Step "${s}" must be an object`);continue}let i=o;(!i.transitions||typeof i.transitions!="object")&&t.push(`Step "${s}" must have a "transitions" object`),i.failure_transitions!==void 0&&typeof i.failure_transitions!="object"&&t.push(`Step "${s}" failure_transitions must be an object when provided`);}}if(!e.terminal_states||typeof e.terminal_states!="object")t.push('Flow must have a "terminal_states" object');else {let n=e.terminal_states;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Terminal state "${s}" must be an object`);continue}typeof o.return_intent!="string"&&t.push(`Terminal state "${s}" must have a "return_intent" string`);}}return t}async function P(r){let t;typeof r=="string"?r.startsWith("http://")||r.startsWith("https://")?t=await rt(r):r.includes("{")?t=JSON.parse(r):t=await nt(r):t=r;let e=D(t);if(e.length>0)throw new Error(`Invalid step flow configuration:
 - ${e.join(`
-- `)}`);return t}function M(r){return btoa(r).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}function O(r){return atob(r.replace(/-/g,"+").replace(/_/g,"/"))}var A=class{constructor(t){this.kv=t;}kv;stateKey(t){return `state_${M(t)}`}dataPrefix(t){return `data_${M(t)}_`}dataKey(t,e){return `${this.dataPrefix(t)}${M(e)}`}async saveRunState(t,e){this.kv.write(this.stateKey(t),e);}async loadRunState(t){let e=this.kv.read(this.stateKey(t));return e!=null&&typeof e=="object"?e:null}async deleteRunState(t){this.kv.delete(this.stateKey(t));for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async setData(t,e,n){this.kv.write(this.dataKey(t,e),n);}async getData(t,e){return this.kv.read(this.dataKey(t,e))}async getAllData(t){let e=this.dataPrefix(t),n={};for(let s of this.kv.listKeys(e))n[O(s.slice(e.length))]=this.kv.read(s);return n}async clearData(t){for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async listRuns(){return this.kv.listKeys("state_").map(t=>O(t.slice(6)))}};var K=dirname(fileURLToPath(import.meta.url)),pt=createRequire(import.meta.url);function ut(){let r=resolve(K,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(K,"../card-compute/jsonata-sync.cjs")}var R=pt(ut());function B(r,t){if(!r||typeof r!="object")throw new Error(`[step-machine-public] Step "${t}" returned a non-object result.`);let e=r,n=e.result??e.status;if(typeof n=="string"&&n.trim().length>0){let s=e.data&&typeof e.data=="object"&&!Array.isArray(e.data)?{...e.data}:{},o=typeof e.error=="string"?e.error:void 0;return o&&!("error"in s)&&(s.error=o),{result:n,data:s,...o?{error:o}:{}}}return {result:"success",data:{...e}}}function z(r,t){if(!t||t.length===0)return r;let e={};for(let n of t)Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n]);return e}function _(r,t){return async(e,n)=>{let s=await r(e,n),o=B(s,n?.stepName??"unknown");return {result:o.result,data:z(o.data,t),...o.error?{error:o.error}:{}}}}function V(r,t,e){if(!t||t.length===0)return null;for(let n of t)try{if(!R(n).evaluate(r))return {result:"failure",data:{error:`[${e}] input validation failed: ${n}`}}}catch(s){let o=s instanceof Error?s.message:String(s);return {result:"failure",data:{error:`[${e}] input validation error on "${n}": ${o}`}}}return null}function T(r,t,e){return !t||t.length===0?r:async(n,s)=>{let o=V(n,t,e);return o||r(n,s)}}var N=dirname(fileURLToPath(import.meta.url)),gt=createRequire(import.meta.url);function mt(){let r=resolve(N,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(N,"../../card-compute/jsonata-sync.cjs")}var x=gt(mt());function U(r,t,e){if(!r||typeof r!="object")return t;let n={output:t},s=t.result,o=t.data,i=t.error;if(typeof r.resultExpr=="string")try{let a=x(r.resultExpr).evaluate(n);if(typeof a!="string"||!a.trim())throw new Error(`resultExpr did not produce a non-empty string (got ${JSON.stringify(a)})`);s=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.resultExpr failed: ${c}`)}if(typeof r.dataTemplate=="string")try{let a=x(r.dataTemplate).evaluate(n);if(!a||typeof a!="object"||Array.isArray(a))throw new Error(`dataTemplate did not produce an object (got ${JSON.stringify(a)})`);o=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.dataTemplate failed: ${c}`)}if(typeof r.errorExpr=="string")try{let a=x(r.errorExpr).evaluate(n);i=a!=null?String(a):void 0;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.errorExpr failed: ${c}`)}return i!==void 0?{result:s,data:o,error:i}:{result:s,data:o}}var ht="b64:";function wt(r){let t=new TextEncoder().encode(r),e=globalThis.Buffer,n;if(e)n=e.from(t).toString("base64");else if(typeof btoa=="function"){let s="";for(let o of t)s+=String.fromCharCode(o);n=btoa(s);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function W(r){return `${ht}${wt(JSON.stringify(r))}`}function q(r){return !!r&&typeof r=="object"&&r.type==="compute-jsonata"&&Array.isArray(r.expr)&&r.expr.length>0}function I(r){if(!r||typeof r!="object")return  false;let t=r;if(t.type!=="ref"||typeof t.howToRun!="string")return  false;if(typeof t.whatToRun=="string")return  true;if(t.whatToRun&&typeof t.whatToRun=="object"){let e=t.whatToRun;return typeof e.kind=="string"&&typeof e.value=="string"}return  false}function St(r){if(typeof r=="string"){let t=r.indexOf("=");if(t<1)throw new Error(`[step-machine-public] Invalid compute expression (missing "="): "${r}"`);return {bindTo:r.slice(0,t).trim(),expr:r.slice(t+1).trim()}}if(r&&typeof r=="object"&&typeof r.bindTo=="string"&&typeof r.expr=="string")return r;throw new Error(`[step-machine-public] Invalid compute step: ${JSON.stringify(r)}`)}function yt(r,t,e){let n=t.split("."),s=r;for(let o=0;o<n.length-1;o++){let i=n[o];(s[i]==null||typeof s[i]!="object")&&(s[i]={}),s=s[i];}s[n[n.length-1]]=e;}function Y(r,t,e){let n=r.expr.map(St);return async s=>{let o=s&&typeof s=="object"&&!Array.isArray(s)?{...s}:{},i={},a={expects_data:o,data:i,...e?{config:e}:{}},c,d;for(let f of n)try{let u=R(f.expr).evaluate(a);if(f.bindTo==="result")c=u!=null?String(u):"success";else if(f.bindTo==="error")d=u!=null?String(u):void 0;else if(f.bindTo.startsWith("data."))yt(i,f.bindTo.slice(5),u);else return {result:"failure",data:{},error:`[${t}] invalid bindTo "${f.bindTo}": must be "result", "error", or start with "data."`}}catch(u){let m=u instanceof Error?u.message:String(u);return {result:"failure",data:{},error:`[${t}] compute "${f.bindTo}" failed: ${m}`}}return c===void 0?{result:"failure",data:{},error:`[${t}] compute-jsonata: no "result" binding declared \u2014 add '- result = "success"' to expr`}:d?{result:c,data:i,error:d}:{result:c,data:i}}}function X(r,t,e,n){let{type:s,...o}=r,i={...o,whatToRun:typeof o.whatToRun=="object"?W(o.whatToRun):o.whatToRun};return async a=>{let c=a&&typeof a=="object"&&!Array.isArray(a)?{...a}:{};n&&(c.config=n);try{let d=await e(i,c);if(!r.outputTransforms)return d;try{return U(r.outputTransforms,d,t)}catch(f){let u=f instanceof Error?f.message:String(f);return {result:"failure",data:{},error:u}}}catch(d){let f=d instanceof Error?d.message:String(d);return {result:"failure",data:{error:`[step-machine-public] step "${t}" invoke threw: ${f}`}}}}}function G(){return async r=>({result:"success",data:r&&typeof r=="object"&&!Array.isArray(r)?r:{}})}function Rt(r,t,e){return async(n,s)=>{let o=n?.[t.items];if(!Array.isArray(o))return {result:"failure",data:{},error:`[${e}] forEach: "${t.items}" is not an array (got ${typeof o})`};let i=o,a=t.collectAs??`${t.items}_results`;if(i.length===0)return {result:"success",data:{[a]:[]}};let{[t.items]:c,...d}=n,f=Math.max(1,t.concurrency??1),u=new Array(i.length),m=0,g=0,w=0;return await new Promise(p=>{function l(){for(;m<f&&g<i.length;){let S=g++;m++;let Z={...d,[t.as]:i[S]};r(Z,s).then(y=>{u[S]=y;}).catch(y=>{let tt=y instanceof Error?y.message:String(y);u[S]={result:"failure",data:{},error:tt};}).finally(()=>{m--,u[S]?.result==="failure"&&w++,g>=i.length&&m===0?p():l();});}m===0&&g>=i.length&&p();}l();}),w>0?{result:"failure",data:{errors:u.filter(l=>l.result==="failure").map(l=>l.error)},error:`[${e}] forEach: ${w}/${i.length} items failed`}:{result:"success",data:{[a]:u.map(p=>p.data)}}}}function Q(r,t,e){let n=Array.isArray(t?.produces_data)?t?.produces_data:void 0,s=Array.isArray(t?.input_validations)?t?.input_validations:void 0,o=t?.config??void 0,i=t?.handler,a;return q(i)?a=Y(i,r,o):I(i)?a=X(i,r,e.invoke,o):a=G(),t?.forEach&&(a=Rt(a,t.forEach,r)),T(_(a,n),s,r)}function H(r,t){let e={};for(let[n,s]of Object.entries(r.steps??{}))e[n]=Q(n,s,t);return e}function kt(r){let t=r.storeFactory||(()=>new h);return {async run(e,n){try{let s=H(e,{invoke:r.invokeRef}),i=await v(e,s,{store:t()}).run(n);return i.status!=="completed"?{dispatched:!1,error:i.error?.message||i.status}:{dispatched:!0}}catch(s){return {dispatched:false,error:s instanceof Error?s.message:String(s)}}}}}
-export{A as KVStorageStore,h as MemoryStore,H as buildStepHandlersForFlow,Y as createComputeJsonataHandler,G as createPassthroughHandler,X as createRefStepHandler,v as createStepMachine,kt as createStepMachineChatFlowRunner,z as filterProducedData,q as isComputeJsonataSpec,I as isRefSpec,R as jsonata,P as loadStepFlow,B as normalizeHandlerResult,Q as resolveStepHandler,V as runInputValidations,T as wrapWithInputValidations,_ as wrapWithOutputFiltering};//# sourceMappingURL=index.js.map
+- `)}`);return t}function A(r){return btoa(r).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}function O(r){return atob(r.replace(/-/g,"+").replace(/_/g,"/"))}var M=class{constructor(t){this.kv=t;}kv;stateKey(t){return `state_${A(t)}`}dataPrefix(t){return `data_${A(t)}_`}dataKey(t,e){return `${this.dataPrefix(t)}${A(e)}`}async saveRunState(t,e){this.kv.write(this.stateKey(t),e);}async loadRunState(t){let e=this.kv.read(this.stateKey(t));return e!=null&&typeof e=="object"?e:null}async deleteRunState(t){this.kv.delete(this.stateKey(t));for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async setData(t,e,n){this.kv.write(this.dataKey(t,e),n);}async getData(t,e){return this.kv.read(this.dataKey(t,e))}async getAllData(t){let e=this.dataPrefix(t),n={};for(let s of this.kv.listKeys(e))n[O(s.slice(e.length))]=this.kv.read(s);return n}async clearData(t){for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async listRuns(){return this.kv.listKeys("state_").map(t=>O(t.slice(6)))}};var B=dirname(fileURLToPath(import.meta.url)),pt=createRequire(import.meta.url);function ut(){let r=resolve(B,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(B,"../card-compute/jsonata-sync.cjs")}var k=pt(ut());function K(r,t){if(!r||typeof r!="object")throw new Error(`[step-machine-public] Step "${t}" returned a non-object result.`);let e=r,n=e.result??e.status;if(typeof n=="string"&&n.trim().length>0){let s=e.data&&typeof e.data=="object"&&!Array.isArray(e.data)?{...e.data}:{},o=typeof e.error=="string"?e.error:void 0;return o&&!("error"in s)&&(s.error=o),{result:n,data:s,...o?{error:o}:{}}}return {result:"success",data:{...e}}}function V(r,t){if(!t||t.length===0)return r;let e={};for(let n of t)Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n]);return e}function _(r,t){return async(e,n)=>{let s=await r(e,n),o=K(s,n?.stepName??"unknown");return {result:o.result,data:V(o.data,t),...o.error?{error:o.error}:{}}}}function z(r,t,e){if(!t||t.length===0)return null;for(let n of t)try{if(!k(n).evaluate(r))return {result:"failure",data:{error:`[${e}] input validation failed: ${n}`}}}catch(s){let o=s instanceof Error?s.message:String(s);return {result:"failure",data:{error:`[${e}] input validation error on "${n}": ${o}`}}}return null}function T(r,t,e){return !t||t.length===0?r:async(n,s)=>{let o=z(n,t,e);return o||r(n,s)}}var N=dirname(fileURLToPath(import.meta.url)),gt=createRequire(import.meta.url);function mt(){let r=resolve(N,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(N,"../../card-compute/jsonata-sync.cjs")}var R=gt(mt());function U(r,t,e){if(!r||typeof r!="object")return t;let n={output:t},s=t.result,o=t.data,i=t.error;if(typeof r.resultExpr=="string")try{let a=R(r.resultExpr).evaluate(n);if(typeof a!="string"||!a.trim())throw new Error(`resultExpr did not produce a non-empty string (got ${JSON.stringify(a)})`);s=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.resultExpr failed: ${c}`)}if(typeof r.dataTemplate=="string")try{let a=R(r.dataTemplate).evaluate(n);if(!a||typeof a!="object"||Array.isArray(a))throw new Error(`dataTemplate did not produce an object (got ${JSON.stringify(a)})`);o=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.dataTemplate failed: ${c}`)}if(typeof r.errorExpr=="string")try{let a=R(r.errorExpr).evaluate(n);i=a!=null?String(a):void 0;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.errorExpr failed: ${c}`)}return i!==void 0?{result:s,data:o,error:i}:{result:s,data:o}}var ht="b64:";function wt(r){let t=new TextEncoder().encode(r),e=globalThis.Buffer,n;if(e)n=e.from(t).toString("base64");else if(typeof btoa=="function"){let s="";for(let o of t)s+=String.fromCharCode(o);n=btoa(s);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function W(r){return `${ht}${wt(JSON.stringify(r))}`}function q(r){return !!r&&typeof r=="object"&&r.type==="compute-jsonata"&&Array.isArray(r.expr)&&r.expr.length>0}function I(r){if(!r||typeof r!="object")return  false;let t=r;if(t.type!=="ref"||typeof t.howToRun!="string")return  false;if(typeof t.whatToRun=="string")return  true;if(t.whatToRun&&typeof t.whatToRun=="object"){let e=t.whatToRun;return typeof e.kind=="string"&&typeof e.value=="string"}return  false}function St(r){if(typeof r=="string"){let t=r.indexOf("=");if(t<1)throw new Error(`[step-machine-public] Invalid compute expression (missing "="): "${r}"`);return {bindTo:r.slice(0,t).trim(),expr:r.slice(t+1).trim()}}if(r&&typeof r=="object"&&typeof r.bindTo=="string"&&typeof r.expr=="string")return r;throw new Error(`[step-machine-public] Invalid compute step: ${JSON.stringify(r)}`)}function yt(r,t,e){let n=t.split("."),s=r;for(let o=0;o<n.length-1;o++){let i=n[o];(s[i]==null||typeof s[i]!="object")&&(s[i]={}),s=s[i];}s[n[n.length-1]]=e;}function Y(r,t,e){let n=r.expr.map(St);return async s=>{let o=s&&typeof s=="object"&&!Array.isArray(s)?{...s}:{},i={},a={expects_data:o,data:i,...e?{config:e}:{}},c,d;for(let f of n)try{let u=k(f.expr).evaluate(a);if(f.bindTo==="result")c=u!=null?String(u):"success";else if(f.bindTo==="error")d=u!=null?String(u):void 0;else if(f.bindTo.startsWith("data."))yt(i,f.bindTo.slice(5),u);else return {result:"failure",data:{},error:`[${t}] invalid bindTo "${f.bindTo}": must be "result", "error", or start with "data."`}}catch(u){let m=u instanceof Error?u.message:String(u);return {result:"failure",data:{},error:`[${t}] compute "${f.bindTo}" failed: ${m}`}}return c===void 0?{result:"failure",data:{},error:`[${t}] compute-jsonata: no "result" binding declared \u2014 add '- result = "success"' to expr`}:d?{result:c,data:i,error:d}:{result:c,data:i}}}function X(r,t,e,n){let{type:s,...o}=r,i={...o,whatToRun:typeof o.whatToRun=="object"?W(o.whatToRun):o.whatToRun};return async a=>{let c=a&&typeof a=="object"&&!Array.isArray(a)?{...a}:{};n&&(c.config=n);try{let d=await e(i,c);if(!r.outputTransforms)return d;try{return U(r.outputTransforms,d,t)}catch(f){let u=f instanceof Error?f.message:String(f);return {result:"failure",data:{},error:u}}}catch(d){let f=d instanceof Error?d.message:String(d);return {result:"failure",data:{error:`[step-machine-public] step "${t}" invoke threw: ${f}`}}}}}function G(){return async r=>({result:"success",data:r&&typeof r=="object"&&!Array.isArray(r)?r:{}})}function kt(r,t,e){return async(n,s)=>{let o=n?.[t.items];if(!Array.isArray(o))return {result:"failure",data:{},error:`[${e}] forEach: "${t.items}" is not an array (got ${typeof o})`};let i=o,a=t.collectAs??`${t.items}_results`;if(i.length===0)return {result:"success",data:{[a]:[]}};let{[t.items]:c,...d}=n,f=Math.max(1,t.concurrency??1),u=new Array(i.length),m=0,g=0,w=0;return await new Promise(p=>{function l(){for(;m<f&&g<i.length;){let S=g++;m++;let Z={...d,[t.as]:i[S]};r(Z,s).then(y=>{u[S]=y;}).catch(y=>{let tt=y instanceof Error?y.message:String(y);u[S]={result:"failure",data:{},error:tt};}).finally(()=>{m--,u[S]?.result==="failure"&&w++,g>=i.length&&m===0?p():l();});}m===0&&g>=i.length&&p();}l();}),w>0?{result:"failure",data:{errors:u.filter(l=>l.result==="failure").map(l=>l.error)},error:`[${e}] forEach: ${w}/${i.length} items failed`}:{result:"success",data:{[a]:u.map(p=>p.data)}}}}function Q(r,t,e){let n=Array.isArray(t?.produces_data)?t?.produces_data:void 0,s=Array.isArray(t?.input_validations)?t?.input_validations:void 0,o=t?.config??void 0,i=t?.handler,a;return q(i)?a=Y(i,r,o):I(i)?a=X(i,r,e.invoke,o):a=G(),t?.forEach&&(a=kt(a,t.forEach,r)),T(_(a,n),s,r)}function H(r,t){let e={};for(let[n,s]of Object.entries(r.steps??{}))e[n]=Q(n,s,t);return e}function xt(r){let t=r.storeFactory||(()=>new h);return {async run(e,n){try{let s=H(e,{invoke:r.invokeRef}),i=await v(e,s,{store:t()}).run(n);return i.status!=="completed"?{dispatched:!1,error:i.error?.message||i.status}:{dispatched:!0}}catch(s){return {dispatched:false,error:s instanceof Error?s.message:String(s)}}}}}
+export{M as KVStorageStore,h as MemoryStore,H as buildStepHandlersForFlow,Y as createComputeJsonataHandler,G as createPassthroughHandler,X as createRefStepHandler,v as createStepMachine,xt as createStepMachineChatFlowRunner,V as filterProducedData,q as isComputeJsonataSpec,I as isRefSpec,k as jsonata,P as loadStepFlow,K as normalizeHandlerResult,Q as resolveStepHandler,z as runInputValidations,T as wrapWithInputValidations,_ as wrapWithOutputFiltering};//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/lib/{storage-interface-B6ecOulj.d.cts → storage-interface-B-7pDHwD.d.cts}

@@ -94,6 +94,41 @@ interface KVStorage {
      */
     listKeys(prefix?: string): string[];
 }
+interface ScratchStorage extends BlobStorage {
+    /**
+     * Allocate a new unique key. Does NOT create any underlying object — caller
+     * must write to it (e.g. via a spawned child) before it has content.
+     * prefix and suffix are sanitized; both are optional.
+     */
+    getUniqueKey(prefix?: string, suffix?: string): string;
+    /**
+     * Allocate a new unique key AND write data at it atomically. Returns the
+     * new key. Counts as a write for sweep-trigger purposes.
+     */
+    create(data: string, prefix?: string, suffix?: string): string;
+    /** Resolve a key to a transport-neutral ref (e.g. for child-process handoff). */
+    keyRef(key: string): KindValueRef;
+    /** Backend-agnostic config bag (used for retention policy and similar knobs). */
+    config: {
+        get(k: string): unknown;
+        set(k: string, v: unknown): void;
+    };
+}
+interface ArchiveFactory {
+    /** Open (or create) a named append-only stream rooted inside the archive. */
+    stream(name: string): JournalStorage;
+    /** Open (or create) a named blob namespace rooted inside the archive. */
+    blob(name: string): BlobStorage;
+    /** List all stream names present in the archive. */
+    listStreams(prefix?: string): string[];
+    /** List all blob namespace names present in the archive. */
+    listBlobs(prefix?: string): string[];
+    /** Backend-agnostic config bag (retention knobs and similar). */
+    config: {
+        get(k: string): unknown;
+        set(k: string, v: unknown): void;
+    };
+}
 interface AtomicRelayLock {
     /**
      * Attempt to acquire the lock without blocking.
@@ -103,4 +138,4 @@ interface AtomicRelayLock {
     tryAcquire(): (() => void) | null;
 }
 
-export { type AtomicRelayLock as A, type BlobStorage as B, type JournalStorage as J, type KVStorage as K, type KindValueRef as a, parseRef as p, serializeRef as s };
+export { type ArchiveFactory as A, type BlobStorage as B, type JournalStorage as J, type KVStorage as K, type ScratchStorage as S, type KindValueRef as a, type AtomicRelayLock as b, parseRef as p, serializeRef as s };

package/lib/{storage-interface-B6ecOulj.d.ts → storage-interface-B-7pDHwD.d.ts}

@@ -94,6 +94,41 @@ interface KVStorage {
      */
     listKeys(prefix?: string): string[];
 }
+interface ScratchStorage extends BlobStorage {
+    /**
+     * Allocate a new unique key. Does NOT create any underlying object — caller
+     * must write to it (e.g. via a spawned child) before it has content.
+     * prefix and suffix are sanitized; both are optional.
+     */
+    getUniqueKey(prefix?: string, suffix?: string): string;
+    /**
+     * Allocate a new unique key AND write data at it atomically. Returns the
+     * new key. Counts as a write for sweep-trigger purposes.
+     */
+    create(data: string, prefix?: string, suffix?: string): string;
+    /** Resolve a key to a transport-neutral ref (e.g. for child-process handoff). */
+    keyRef(key: string): KindValueRef;
+    /** Backend-agnostic config bag (used for retention policy and similar knobs). */
+    config: {
+        get(k: string): unknown;
+        set(k: string, v: unknown): void;
+    };
+}
+interface ArchiveFactory {
+    /** Open (or create) a named append-only stream rooted inside the archive. */
+    stream(name: string): JournalStorage;
+    /** Open (or create) a named blob namespace rooted inside the archive. */
+    blob(name: string): BlobStorage;
+    /** List all stream names present in the archive. */
+    listStreams(prefix?: string): string[];
+    /** List all blob namespace names present in the archive. */
+    listBlobs(prefix?: string): string[];
+    /** Backend-agnostic config bag (retention knobs and similar). */
+    config: {
+        get(k: string): unknown;
+        set(k: string, v: unknown): void;
+    };
+}
 interface AtomicRelayLock {
     /**
      * Attempt to acquire the lock without blocking.
@@ -103,4 +138,4 @@ interface AtomicRelayLock {
     tryAcquire(): (() => void) | null;
 }
 
-export { type AtomicRelayLock as A, type BlobStorage as B, type JournalStorage as J, type KVStorage as K, type KindValueRef as a, parseRef as p, serializeRef as s };
+export { type ArchiveFactory as A, type BlobStorage as B, type JournalStorage as J, type KVStorage as K, type ScratchStorage as S, type KindValueRef as a, type AtomicRelayLock as b, parseRef as p, serializeRef as s };

package/lib/stores/index.d.cts

@@ -1,4 +1,4 @@
 export { MemoryStore } from './memory.cjs';
 export { KVStorageStore } from './kv.cjs';
 import '../types-DQ1bKuB1.cjs';
-import '../storage-interface-B6ecOulj.cjs';
+import '../storage-interface-B-7pDHwD.cjs';

package/lib/stores/index.d.ts

@@ -1,4 +1,4 @@
 export { MemoryStore } from './memory.js';
 export { KVStorageStore } from './kv.js';
 import '../types-DQ1bKuB1.js';
-import '../storage-interface-B6ecOulj.js';
+import '../storage-interface-B-7pDHwD.js';

package/lib/stores/kv.d.cts

@@ -1,5 +1,5 @@
 import { l as StepMachineStore, k as StepMachineState } from '../types-DQ1bKuB1.cjs';
-import { K as KVStorage } from '../storage-interface-B6ecOulj.cjs';
+import { K as KVStorage } from '../storage-interface-B-7pDHwD.cjs';
 
 /**
  * yaml-flow - KVStorageStore

package/lib/stores/kv.d.ts

@@ -1,5 +1,5 @@
 import { l as StepMachineStore, k as StepMachineState } from '../types-DQ1bKuB1.js';
-import { K as KVStorage } from '../storage-interface-B6ecOulj.js';
+import { K as KVStorage } from '../storage-interface-B-7pDHwD.js';
 
 /**
  * yaml-flow - KVStorageStore

package/lib/{types-DNYhCFNJ.d.ts → types-Cn0b8G-i.d.ts}

@@ -1,19 +1,8 @@
-import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-DWpZVDXN.js';
+import { a as ArtifactsStore } from './artifacts-store-lib-454TAuov.js';
+import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-Bz07XKRK.js';
 import { ExecutionRef } from './execution-refs.js';
-import { a as KindValueRef } from './storage-interface-B6ecOulj.js';
-import { c as ChatStorage } from './chat-storage-lib-BK5Njslc.js';
-
-/**
- * server-runtime/types.ts
- *
- * Platform-free adapter interfaces for the board server runtime.
- *
- * The runtime (index.ts) imports ONLY this file and board-live-cards-public
- * for its dependencies — no node:fs, node:net, node:child_process, etc.
- *
- * Hosts (demo-server, Azure Function, Firebase Function) provide implementations
- * of these interfaces when constructing the runtime.
- */
+import { a as KindValueRef } from './storage-interface-B-7pDHwD.js';
+import { c as ChatStorage } from './chat-storage-lib-DGaKrjVe.js';
 
 interface InvocationAdapter {
     /**
@@ -77,9 +66,20 @@ interface BoardContextConfig {
     boardAdapter: BoardPlatformAdapter;
     /** Optional separate adapter for file/chat blob storage (defaults to boardAdapter) */
     artifactsAdapter?: BoardPlatformAdapter;
+    /**
+     * Optional caller-supplied file artifacts store. When provided, this is used
+     * verbatim and the runtime does NOT consult artifactsAdapter.blobStorage('files').
+     * Use this to give the embedder full control over the on-disk layout (e.g.
+     * via createFsBoardFileArtifactsStore(baseDir, { filesSubdir: '' })).
+     */
+    filesArtifactsStore?: ArtifactsStore;
     baseRef: KindValueRef;
     cardStoreRef: string;
     outputsStoreRef: string;
+    /** Optional ref pointing scratch storage at a different backend than the board runtime. */
+    scratchStoreRef?: string;
+    /** Optional ref pointing archive storage at a different backend than the board runtime. */
+    archiveStoreRef?: string;
     /** Notification endpoint ref — e.g. ::named-pipe::<path> or ::firestore-watch::<path> */
     notifyRef?: KindValueRef;
     taskExecutorRef?: ExecutionRef;

package/lib/{types-D9B0Vrwg.d.cts → types-Dszjwfud.d.cts}

@@ -1,19 +1,8 @@
-import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-BwZYGAsF.cjs';
+import { a as ArtifactsStore } from './artifacts-store-lib-zsGFbBV8.cjs';
+import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-BM6jCEIa.cjs';
 import { ExecutionRef } from './execution-refs.cjs';
-import { a as KindValueRef } from './storage-interface-B6ecOulj.cjs';
-import { c as ChatStorage } from './chat-storage-lib-C5bQ7bGe.cjs';
-
-/**
- * server-runtime/types.ts
- *
- * Platform-free adapter interfaces for the board server runtime.
- *
- * The runtime (index.ts) imports ONLY this file and board-live-cards-public
- * for its dependencies — no node:fs, node:net, node:child_process, etc.
- *
- * Hosts (demo-server, Azure Function, Firebase Function) provide implementations
- * of these interfaces when constructing the runtime.
- */
+import { a as KindValueRef } from './storage-interface-B-7pDHwD.cjs';
+import { c as ChatStorage } from './chat-storage-lib-OX0Q_Ttf.cjs';
 
 interface InvocationAdapter {
     /**
@@ -77,9 +66,20 @@ interface BoardContextConfig {
     boardAdapter: BoardPlatformAdapter;
     /** Optional separate adapter for file/chat blob storage (defaults to boardAdapter) */
     artifactsAdapter?: BoardPlatformAdapter;
+    /**
+     * Optional caller-supplied file artifacts store. When provided, this is used
+     * verbatim and the runtime does NOT consult artifactsAdapter.blobStorage('files').
+     * Use this to give the embedder full control over the on-disk layout (e.g.
+     * via createFsBoardFileArtifactsStore(baseDir, { filesSubdir: '' })).
+     */
+    filesArtifactsStore?: ArtifactsStore;
     baseRef: KindValueRef;
     cardStoreRef: string;
     outputsStoreRef: string;
+    /** Optional ref pointing scratch storage at a different backend than the board runtime. */
+    scratchStoreRef?: string;
+    /** Optional ref pointing archive storage at a different backend than the board runtime. */
+    archiveStoreRef?: string;
     /** Notification endpoint ref — e.g. ::named-pipe::<path> or ::firestore-watch::<path> */
     notifyRef?: KindValueRef;
     taskExecutorRef?: ExecutionRef;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "8.3.0",
+  "version": "8.4.1",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",