yaml-flow 7.1.0 → 8.0.1

package/cli/board-live-cards-lib-tjYsPt5U.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Event Graph — Core Types
+ *
+ * Type definitions for the stateless event-graph engine.
+ * Pure: f(state, event) → newState
+ */
+interface GraphConfig {
+    id?: string;
+    settings: GraphSettings;
+    tasks: Record<string, TaskConfig>;
+}
+interface GraphSettings {
+    /** Completion strategy */
+    completion: CompletionStrategy;
+    /** Conflict resolution strategy */
+    conflict_strategy?: ConflictStrategy;
+    /** Execution mode */
+    execution_mode?: ExecutionMode;
+    /** Default refresh strategy for all tasks (default: 'data-changed') */
+    refreshStrategy?: RefreshStrategy;
+    /** Goal outputs — used with 'goal-reached' completion */
+    goal?: string[];
+    /** Max total scheduler iterations (safety limit, default: 1000) */
+    max_iterations?: number;
+    /** Timeout in ms (declared for drivers, not enforced by pure engine) */
+    timeout_ms?: number;
+}
+interface TaskConfig {
+    /** What this task needs to become eligible */
+    requires?: string[];
+    /** What this task produces on successful completion */
+    provides: string[];
+    /** Conditional provides based on handler result */
+    on?: Record<string, string[]>;
+    /** Tokens to inject into available outputs on failure */
+    on_failure?: string[];
+    /** Task execution method (informational — driver concern) */
+    method?: string;
+    /** Named task handler references — looked up in the handler registry at dispatch time */
+    taskHandlers?: string[];
+    /** Arbitrary task configuration (driver concern) */
+    config?: Record<string, unknown>;
+    /** Task priority (higher = preferred in conflict resolution) */
+    priority?: number;
+    /** Estimated duration in ms (used by duration-first strategy) */
+    estimatedDuration?: number;
+    /** Estimated cost (used by cost-optimized strategy) */
+    estimatedCost?: number;
+    /** Resource requirements (used by resource-aware strategy) */
+    estimatedResources?: Record<string, number>;
+    /** Retry configuration */
+    retry?: TaskRetryConfig;
+    /** Refresh strategy — controls when a completed task re-runs (default: 'data-changed') */
+    refreshStrategy?: RefreshStrategy;
+    /** Refresh interval in seconds — only used with 'time-based' strategy */
+    refreshInterval?: number;
+    /** Max executions cap (safety limit, optional) */
+    maxExecutions?: number;
+    /** Circuit breaker: max executions before breaking */
+    circuit_breaker?: TaskCircuitBreakerConfig;
+    /** Description */
+    description?: string;
+    /** LLM inference hints — opt-in metadata for AI-assisted completion detection */
+    inference?: {
+        /** Human-readable completion criteria */
+        criteria?: string;
+        /** Keywords to help the LLM understand the domain */
+        keywords?: string[];
+        /** Suggested checks for verification */
+        suggestedChecks?: string[];
+        /** Whether the LLM should attempt to auto-detect completion (default: false) */
+        autoDetectable?: boolean;
+    };
+}
+interface TaskRetryConfig {
+    max_attempts: number;
+    delay_ms?: number;
+    backoff_multiplier?: number;
+}
+interface TaskCircuitBreakerConfig {
+    /** Max executions before injecting break tokens */
+    max_executions: number;
+    /** Tokens to inject when breaker trips */
+    on_break: string[];
+}
+interface ExecutionConfig {
+    executionMode: ExecutionMode;
+    conflictStrategy: ConflictStrategy;
+    completionStrategy: CompletionStrategy;
+}
+type GraphEvent = TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | TaskProgressEvent | TaskRestartEvent | InjectTokensEvent | AgentActionEvent | TaskUpsertEvent | TaskRemovalEvent | NodeRequiresAddEvent | NodeRequiresRemoveEvent | NodeProvidesAddEvent | NodeProvidesRemoveEvent;
+interface TaskStartedEvent {
+    type: 'task-started';
+    taskName: string;
+    timestamp: string;
+    executionId?: string;
+}
+interface TaskCompletedEvent {
+    type: 'task-completed';
+    taskName: string;
+    /** Handler result key — used for conditional routing via `on` */
+    result?: string;
+    /** Data payload from task execution */
+    data?: Record<string, unknown>;
+    /** Content hash of the output — used by 'data-changed' refresh strategy */
+    dataHash?: string;
+    timestamp: string;
+    executionId?: string;
+}
+interface TaskFailedEvent {
+    type: 'task-failed';
+    taskName: string;
+    error: string;
+    timestamp: string;
+    executionId?: string;
+}
+interface TaskProgressEvent {
+    type: 'task-progress';
+    taskName: string;
+    message?: string;
+    progress?: number;
+    /**
+     * Arbitrary update payload — used by source delivery to carry
+     * { bindTo, fetchedAt, dest } or { bindTo, failure, reason }.
+     * card-handler receives this via TaskHandlerInput.update.
+     */
+    update?: Record<string, unknown>;
+    timestamp: string;
+    executionId?: string;
+}
+interface TaskRestartEvent {
+    type: 'task-restart';
+    taskName: string;
+    timestamp: string;
+    executionId?: string;
+}
+interface InjectTokensEvent {
+    type: 'inject-tokens';
+    tokens: string[];
+    timestamp: string;
+}
+interface AgentActionEvent {
+    type: 'agent-action';
+    action: 'start' | 'stop' | 'pause' | 'resume';
+    timestamp: string;
+    config?: Partial<ExecutionConfig>;
+}
+interface TaskUpsertEvent {
+    type: 'task-upsert';
+    taskName: string;
+    taskConfig: TaskConfig;
+    timestamp: string;
+}
+interface TaskRemovalEvent {
+    type: 'task-removal';
+    taskName: string;
+    timestamp: string;
+}
+interface NodeRequiresAddEvent {
+    type: 'node-requires-add';
+    nodeName: string;
+    tokens: string[];
+    timestamp: string;
+}
+interface NodeRequiresRemoveEvent {
+    type: 'node-requires-remove';
+    nodeName: string;
+    tokens: string[];
+    timestamp: string;
+}
+interface NodeProvidesAddEvent {
+    type: 'node-provides-add';
+    nodeName: string;
+    tokens: string[];
+    timestamp: string;
+}
+interface NodeProvidesRemoveEvent {
+    type: 'node-provides-remove';
+    nodeName: string;
+    tokens: string[];
+    timestamp: string;
+}
+type CompletionStrategy = 'all-tasks-done' | 'all-outputs-done' | 'only-resolved' | 'goal-reached' | 'manual';
+type ExecutionMode = 'dependency-mode' | 'eligibility-mode';
+type ConflictStrategy = 'alphabetical' | 'priority-first' | 'duration-first' | 'cost-optimized' | 'resource-aware' | 'random-select' | 'user-choice' | 'parallel-all' | 'skip-conflicts' | 'round-robin';
+type RefreshStrategy = 'data-changed' | 'epoch-changed' | 'time-based' | 'manual' | 'once';
+
+/**
+ * board-live-cards-lib — Pure logic library for the board-live-cards CLI.
+ *
+ * Merged from:
+ *   board-live-cards-all-stores.ts
+ *   board-live-cards-lib-types.ts
+ *   board-live-cards-lib-board-status.ts
+ *   board-live-cards-lib-card-handler.ts
+ *   board-live-cards-cli-board-commands.ts
+ *   board-live-cards-cli-card-commands.ts
+ *   board-live-cards-cli-callbacks.ts
+ *
+ * Zero platform imports. All storage is injected via adapter interfaces.
+ * Safe for Node, browser, and neutral (V8/PyMiniRacer) bundles.
+ */
+
+interface LiveCard {
+    id: string;
+    [key: string]: unknown;
+}
+interface CardIndexEntry {
+    /** Storage-specific address (file path, Cosmos doc id, localStorage key). */
+    key: string;
+    /** Checksum of card content — computed by the adapter at write time. */
+    checksum: string;
+    updatedAt: string;
+}
+type CardIndex = Record<string, CardIndexEntry>;
+type CardChecksumIndex = Record<string, string>;
+interface CardStorageAdapter {
+    readIndex(): CardIndex | null;
+    writeIndex(index: CardIndex): void;
+    readCard(key: string): LiveCard | null;
+    /** Write card content; returns checksum of what was written. */
+    writeCard(key: string, card: LiveCard): string;
+    cardExists(key: string): boolean;
+    defaultCardKey(cardId: string): string;
+}
+interface CardStore {
+    readCard(id: string): LiveCard | null;
+    readCardKey(id: string): string | null;
+    readAllCards(): LiveCard[];
+    readChecksumIndex(): CardChecksumIndex;
+    changedSince(snapshotChecksumIndex: CardChecksumIndex): string[];
+}
+interface CardUpsertValidation {
+    ok: boolean;
+    error?: string;
+}
+interface CardAdminStore extends CardStore {
+    validateUpsert(id: string, cardKey: string): CardUpsertValidation;
+    writeCard(id: string, card: LiveCard, cardKey?: string): void;
+    patchCard(id: string, jsonPath: string, value: unknown): void;
+    removeCard(id: string): void;
+    readIndex(): CardIndex;
+}
+declare function createCardStore(adapter: CardStorageAdapter, onWarn?: (msg: string) => void): CardAdminStore;
+interface JournalEntry {
+    id: string;
+    event: GraphEvent;
+}
+interface JournalStorageAdapter {
+    readAllEntries(): JournalEntry[];
+    appendEntry(entry: JournalEntry): void;
+    generateId(): string;
+}
+declare const SNAPSHOT_SCHEMA_VERSION_V1 = "v1";
+declare const BOARD_GRAPH_KEY = "board/graph";
+type OutputStoreEvent = {
+    kind: 'computed_values';
+    cardId: string;
+    values: Record<string, unknown>;
+} | {
+    kind: 'data_object';
+    key: string;
+    payload: unknown;
+} | {
+    kind: 'status';
+    status: unknown;
+};
+interface BoardStatusCard {
+    name: string;
+    status: string;
+    error?: {
+        message: string;
+        code?: string;
+        at?: string;
+        source?: 'task-runtime' | 'source-fetch' | 'timeout' | 'unknown';
+    };
+    requires: string[];
+    requires_satisfied: string[];
+    requires_missing: string[];
+    provides_declared: string[];
+    provides_runtime: string[];
+    blocked_by: string[];
+    unblocks: string[];
+    runtime: {
+        attempt_count: number;
+        restart_count: number;
+        in_progress_since: string | null;
+        last_transition_at: string | null;
+        last_completed_at: string | null;
+        last_restarted_at: string | null;
+        status_age_ms: number | null;
+    };
+}
+interface BoardStatusObject {
+    schema_version: 'v1';
+    meta: {
+        board: {
+            path: string;
+        };
+    };
+    summary: {
+        card_count: number;
+        completed: number;
+        eligible: number;
+        pending: number;
+        blocked: number;
+        unresolved: number;
+        failed?: number;
+        in_progress?: number;
+        orphan_cards?: number;
+        topology?: {
+            edge_count: number;
+            max_fan_out_card: string | null;
+            max_fan_out: number;
+        };
+    };
+    cards: BoardStatusCard[];
+}
+declare const EMPTY_CONFIG: GraphConfig;
+
+export { type BoardStatusObject as B, type CardAdminStore as C, EMPTY_CONFIG as E, type JournalStorageAdapter as J, type LiveCard as L, type OutputStoreEvent as O, SNAPSHOT_SCHEMA_VERSION_V1 as S, BOARD_GRAPH_KEY as a, createCardStore as c };

package/{dist/cli → cli}/browser-api/board-live-cards-browser-adapter.d.ts

@@ -1,8 +1,6 @@
-import { N as NotificationTransport } from '../../types-HGDTWIun.js';
-import { B as BoardPlatformAdapter } from '../../board-live-cards-public-CK_J8uv0.js';
-import { ExecutionRef } from '../../execution-refs.js';
-import '../../board-live-cards-lib-jM2uYG1v.js';
-import '../../types-BBhqYGhE.js';
+import { B as BoardPlatformAdapter, N as NotificationTransport } from '../types-C2YQXFwo.js';
+import { E as ExecutionRef } from '../execution-interface-ftO1W7Po.js';
+import '../board-live-cards-lib-tjYsPt5U.js';
 
 interface InMemoryBus {
     publish(event: unknown): void;

package/{dist/cli → cli}/browser-api/card-store-browser-api.d.ts

@@ -1,5 +1,4 @@
-import { L as LiveCard } from '../../board-live-cards-lib-jM2uYG1v.js';
-import '../../types-BBhqYGhE.js';
+import { L as LiveCard } from '../board-live-cards-lib-tjYsPt5U.js';
 
 /**
  * card-store-browser-api.ts

package/{dist/cli → cli}/browser-api/card-store-browser-api.js

@@ -1,2 +1,2 @@
-import {createRequire}from'module';import'ajv-formats';var x=createRequire(import.meta.url);x("./jsonata-sync.cjs");var v=createRequire(import.meta.url);v("./jsonata-sync.cjs");function y(n,o){function e(){return n.readIndex()??{}}function r(t,s,i){let a=String(s||"").split(".").filter(Boolean);if(a.length===0)return i&&typeof i=="object"&&!Array.isArray(i)?i:{value:i};let u={...t},c=u;for(let d=0;d<a.length-1;d++){let l=a[d],f=c[l],m=f&&typeof f=="object"&&!Array.isArray(f)?{...f}:{};c[l]=m,c=m;}return c[a[a.length-1]]=i,u}return {readCard(t){let s=e()[t];return !s||!n.cardExists(s.key)?null:n.readCard(s.key)},readCardKey(t){return e()[t]?.key??null},readAllCards(){let t=[];for(let[s,i]of Object.entries(e())){if(!n.cardExists(i.key))continue;let a=n.readCard(i.key);a?t.push(a):o?.(`[card-store] could not read card "${s}" at key "${i.key}"`);}return t},readChecksumIndex(){let t={};for(let[s,i]of Object.entries(e()))t[s]=i.checksum;return t},changedSince(t){let s=e(),i=[];for(let[a,u]of Object.entries(s))t[a]!==u.checksum&&i.push(a);for(let a of Object.keys(t))s[a]||i.push(a);return i},validateUpsert(t,s){let i=e(),a=i[t],u=Object.entries(i).find(([,c])=>c.key===s);return a&&a.key!==s?{ok:false,error:`Card id "${t}" is already mapped to key "${a.key}", cannot remap to "${s}"`}:u&&u[0]!==t?{ok:false,error:`Key "${s}" is already mapped to card id "${u[0]}", cannot remap to "${t}"`}:{ok:true}},writeCard(t,s,i){let a=e(),u=i??a[t]?.key??n.defaultCardKey(t),c=n.writeCard(u,s);a[t]={key:u,checksum:c,updatedAt:new Date().toISOString()},n.writeIndex(a);},patchCard(t,s,i){let a=e(),u=a[t];if(!u||!n.cardExists(u.key))throw new Error(`card "${t}" not found`);let c=n.readCard(u.key);if(!c||typeof c!="object"||Array.isArray(c))throw new Error(`card "${t}" is not patchable`);let d=r(c,s,i),l=n.writeCard(u.key,d);a[t]={key:u.key,checksum:l,updatedAt:new Date().toISOString()},n.writeIndex(a);},removeCard(t){let s=e();s[t]&&(delete s[t],n.writeIndex(s));},readIndex(){return e()}}}function p(n){if(n==null||typeof n!="object")return JSON.stringify(n);if(Array.isArray(n))return `[${n.map(p).join(",")}]`;let o=n;return `{${Object.keys(o).sort().map(r=>`${JSON.stringify(r)}:${p(o[r])}`).join(",")}}`}function g(n,o){let e=o>>>0;for(let r=0;r<n.length;r++)e^=n.charCodeAt(r),e=Math.imul(e,16777619)>>>0;return e}function E(n){let o=p(n),e=g(o,2166136261),r=g(o,3735928559),t=g(o,19088743),s=g(o,4277009102);return [e,r,t,s].map(i=>i.toString(16).padStart(8,"0")).join("")}function A(n){function o(e){return `${n}:kv:${e}`}return {read(e){let r=globalThis.localStorage.getItem(o(e));if(r===null)return null;try{return JSON.parse(r)}catch{return null}},write(e,r){globalThis.localStorage.setItem(o(e),JSON.stringify(r));},delete(e){globalThis.localStorage.removeItem(o(e));},listKeys(e){let r=o(e??""),t=[];for(let s=0;s<globalThis.localStorage.length;s++){let i=globalThis.localStorage.key(s);i!==null&&i.startsWith(r)&&t.push(i.slice(o("").length));}return t}}}function h(n,o){let e={...n};for(let[r,t]of Object.entries(o))t!==null&&typeof t=="object"&&!Array.isArray(t)&&e[r]!==null&&typeof e[r]=="object"&&!Array.isArray(e[r])?e[r]=h(e[r],t):e[r]=t;return e}function S(n,o,e){if(o.length===0)return n;let[r,...t]=o;if(t.length===0)return {...n,[r]:e};let s=n[r]!==null&&typeof n[r]=="object"&&!Array.isArray(n[r])?n[r]:{};return {...n,[r]:S(s,t,e)}}function _(n){let o=A(n);return {read:e=>o.read(e),get(e,r){let t=o.read(e);if(t===null)return null;let s=t;for(let i of r.split(".").filter(Boolean)){if(s===null||typeof s!="object"||Array.isArray(s))return null;s=s[i]??null;}return s??null},write:(e,r)=>o.write(e,r),delete:e=>o.delete(e),listKeys:e=>o.listKeys(e),shallowMerge(e,r){let t=o.read(e)??{};o.write(e,{...t,...r});},deepMerge(e,r){let t=o.read(e)??{};o.write(e,h(t,r));},patch(e,r,t){let s=o.read(e)??{},i=r.split(".").filter(Boolean);o.write(e,S(s,i,t));}}}function k(n){let o=_(n);return {readIndex(){return o.read("_index")},writeIndex(e){o.write("_index",e);},readCard(e){return o.read(e)},writeCard(e,r){return o.write(e,r),E(r)},cardExists(e){return o.read(e)!==null},defaultCardKey(e){return e}}}function he(n){let o=k(n),e=y(o);return {getCard(r){return e.readCard(r)},getAllCards(){return e.readAllCards()},upsertCard(r){let t=o.defaultCardKey(r.id);e.writeCard(r.id,r,t);},removeCard(r){e.removeCard(r);}}}export{he as createBrowserCardStoreApi};//# sourceMappingURL=card-store-browser-api.js.map
+import {createRequire}from'module';import'ajv-formats';var C=createRequire(import.meta.url);C("./jsonata-sync.cjs");var v=createRequire(import.meta.url);v("./jsonata-sync.cjs");function y(n,o){function e(){return n.readIndex()??{}}function r(t,s,i){let a=String(s||"").split(".").filter(Boolean);if(a.length===0)return i&&typeof i=="object"&&!Array.isArray(i)?i:{value:i};let u={...t},c=u;for(let d=0;d<a.length-1;d++){let l=a[d],f=c[l],m=f&&typeof f=="object"&&!Array.isArray(f)?{...f}:{};c[l]=m,c=m;}return c[a[a.length-1]]=i,u}return {readCard(t){let s=e()[t];return !s||!n.cardExists(s.key)?null:n.readCard(s.key)},readCardKey(t){return e()[t]?.key??null},readAllCards(){let t=[];for(let[s,i]of Object.entries(e())){if(!n.cardExists(i.key))continue;let a=n.readCard(i.key);a?t.push(a):o?.(`[card-store] could not read card "${s}" at key "${i.key}"`);}return t},readChecksumIndex(){let t={};for(let[s,i]of Object.entries(e()))t[s]=i.checksum;return t},changedSince(t){let s=e(),i=[];for(let[a,u]of Object.entries(s))t[a]!==u.checksum&&i.push(a);for(let a of Object.keys(t))s[a]||i.push(a);return i},validateUpsert(t,s){let i=e(),a=i[t],u=Object.entries(i).find(([,c])=>c.key===s);return a&&a.key!==s?{ok:false,error:`Card id "${t}" is already mapped to key "${a.key}", cannot remap to "${s}"`}:u&&u[0]!==t?{ok:false,error:`Key "${s}" is already mapped to card id "${u[0]}", cannot remap to "${t}"`}:{ok:true}},writeCard(t,s,i){let a=e(),u=i??a[t]?.key??n.defaultCardKey(t),c=n.writeCard(u,s);a[t]={key:u,checksum:c,updatedAt:new Date().toISOString()},n.writeIndex(a);},patchCard(t,s,i){let a=e(),u=a[t];if(!u||!n.cardExists(u.key))throw new Error(`card "${t}" not found`);let c=n.readCard(u.key);if(!c||typeof c!="object"||Array.isArray(c))throw new Error(`card "${t}" is not patchable`);let d=r(c,s,i),l=n.writeCard(u.key,d);a[t]={key:u.key,checksum:l,updatedAt:new Date().toISOString()},n.writeIndex(a);},removeCard(t){let s=e();s[t]&&(delete s[t],n.writeIndex(s));},readIndex(){return e()}}}function p(n){if(n==null||typeof n!="object")return JSON.stringify(n);if(Array.isArray(n))return `[${n.map(p).join(",")}]`;let o=n;return `{${Object.keys(o).sort().map(r=>`${JSON.stringify(r)}:${p(o[r])}`).join(",")}}`}function g(n,o){let e=o>>>0;for(let r=0;r<n.length;r++)e^=n.charCodeAt(r),e=Math.imul(e,16777619)>>>0;return e}function E(n){let o=p(n),e=g(o,2166136261),r=g(o,3735928559),t=g(o,19088743),s=g(o,4277009102);return [e,r,t,s].map(i=>i.toString(16).padStart(8,"0")).join("")}function A(n){function o(e){return `${n}:kv:${e}`}return {read(e){let r=globalThis.localStorage.getItem(o(e));if(r===null)return null;try{return JSON.parse(r)}catch{return null}},write(e,r){globalThis.localStorage.setItem(o(e),JSON.stringify(r));},delete(e){globalThis.localStorage.removeItem(o(e));},listKeys(e){let r=o(e??""),t=[];for(let s=0;s<globalThis.localStorage.length;s++){let i=globalThis.localStorage.key(s);i!==null&&i.startsWith(r)&&t.push(i.slice(o("").length));}return t}}}function h(n,o){let e={...n};for(let[r,t]of Object.entries(o))t!==null&&typeof t=="object"&&!Array.isArray(t)&&e[r]!==null&&typeof e[r]=="object"&&!Array.isArray(e[r])?e[r]=h(e[r],t):e[r]=t;return e}function S(n,o,e){if(o.length===0)return n;let[r,...t]=o;if(t.length===0)return {...n,[r]:e};let s=n[r]!==null&&typeof n[r]=="object"&&!Array.isArray(n[r])?n[r]:{};return {...n,[r]:S(s,t,e)}}function _(n){let o=A(n);return {read:e=>o.read(e),get(e,r){let t=o.read(e);if(t===null)return null;let s=t;for(let i of r.split(".").filter(Boolean)){if(s===null||typeof s!="object"||Array.isArray(s))return null;s=s[i]??null;}return s??null},write:(e,r)=>o.write(e,r),delete:e=>o.delete(e),listKeys:e=>o.listKeys(e),shallowMerge(e,r){let t=o.read(e)??{};o.write(e,{...t,...r});},deepMerge(e,r){let t=o.read(e)??{};o.write(e,h(t,r));},patch(e,r,t){let s=o.read(e)??{},i=r.split(".").filter(Boolean);o.write(e,S(s,i,t));}}}function k(n){let o=_(n);return {readIndex(){return o.read("_index")},writeIndex(e){o.write("_index",e);},readCard(e){return o.read(e)},writeCard(e,r){return o.write(e,r),E(r)},cardExists(e){return o.read(e)!==null},defaultCardKey(e){return e}}}function he(n){let o=k(n),e=y(o);return {getCard(r){return e.readCard(r)},getAllCards(){return e.readAllCards()},upsertCard(r){let t=o.defaultCardKey(r.id);e.writeCard(r.id,r,t);},removeCard(r){e.removeCard(r);}}}export{he as createBrowserCardStoreApi};//# sourceMappingURL=card-store-browser-api.js.map
 //# sourceMappingURL=card-store-browser-api.js.map

package/cli/execution-interface-ftO1W7Po.d.ts

@@ -0,0 +1,286 @@
+/**
+ * execution-interface.ts
+ *
+ * Pure module — no Node/platform imports.  Safe for any runtime.
+ *
+ * Defines the portable descriptor types for invoking any executable target,
+ * regardless of transport (local process, HTTP endpoint, cloud function, etc.).
+ *
+ * Parallel to storage-interface.ts (which describes WHERE data lives), this
+ * module describes HOW to invoke a piece of logic.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * CORE CONCEPTS
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  ExecutionRef — self-contained, serializable JSON descriptor for one invocation target.
+ *    • howToRun    — transport / runtime kind (discriminator)
+ *    • whatToRun   — address of the artifact (KindValueRef wire form: b64:<base64url(json)>)
+ *    • argsMassaging — optional JSONata expressions that map logical args → physical call shape
+ *    • meta        — optional human-readable label (e.g. 'task-executor', 'chat-handler')
+ *
+ *  ExecutionResult — standardized envelope returned by any invocation.
+ *    • status: 'success' | 'fail' | 'error'
+ *    • data   — KindValueRef wire form pointing to output blob (on success)
+ *    • error  — human-readable message (on fail/error)
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * howToRun VALUES
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  'local-node'      node <whatToRun> [argv...]
+ *  'local-python'    python <whatToRun> [argv...]
+ *  'local-process'   execute <whatToRun> directly (shebang / pre-resolved binary)
+ *  'http:post'       HTTP POST to <whatToRun>
+ *  'http:get'        HTTP GET to <whatToRun>
+ *  'built-in'        resolved by the adapter to a well-known internal implementation
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * argsMassaging
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  Each field is a JSONata expression evaluated against the caller's logical args object.
+ *  If argsMassaging is omitted, the adapter uses its default mapping for the howToRun kind.
+ *
+ *  Local transports (local-node, local-python, local-process):
+ *    cmdTemplate   — array of JSONata exprs, each producing one argv string
+ *    stdinTemplate — JSONata expr producing the stdin payload object
+ *
+ *  HTTP transports (http:post, http:get, azure-function, firebase, etc.):
+ *    urlTemplate    — JSONata expr producing the final URL string
+ *    headerTemplate — JSONata expr producing the request headers object
+ *    bodyTemplate   — JSONata expr producing the request body object
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * SERIALIZATION
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  ExecutionRef is a plain JSON object — store it as-is on disk, in Cosmos, or any DB.
+ *  No special encoding needed.  parseExecutionRef / serializeExecutionRef are thin
+ *  JSON wrappers provided for symmetry with storage-interface.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * USAGE EXAMPLES
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ *  // Built-in source-cli task executor (resolved by adapter from cliDir):
+ *  const builtIn: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'built-in',
+ *    whatToRun: 'b64:<base64url({"kind":"built-in","value":"source-cli-task-executor"})>',
+ *  };
+ *
+ *  // External local-node task executor with default protocol args:
+ *  const local: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'local-node',
+ *    whatToRun: 'b64:<base64url({"kind":"fs-path","value":"/path/to/my-executor.js"})>',
+ *  };
+ *
+ *  // Azure Function task executor with custom arg mapping:
+ *  const azureFn: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'http:post',
+ *    whatToRun: 'b64:<base64url({"kind":"http-url","value":"https://myfn.azurewebsites.net/api/task-executor"})>',
+ *    argsMassaging: {
+ *      urlTemplate: "whatToRun & '?op=' & subcommand",
+ *      headerTemplate: "{ 'Authorization': 'Bearer ' & token }",
+ *      bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef }",
+ *    },
+ *  };
+ *
+ *  // Chat handler over HTTP with a different logical args shape:
+ *  const chatHandler: ExecutionRef = {
+ *    meta: 'chat-handler',
+ *    howToRun: 'http:post',
+ *    whatToRun: 'b64:<base64url({"kind":"http-url","value":"https://myfn.azurewebsites.net/api/chat"})>',
+ *    argsMassaging: {
+ *      bodyTemplate: "{ 'message': message, 'context': context, 'sessionId': sessionId }",
+ *    },
+ *  };
+ */
+/**
+ * Optional JSONata-based transforms applied to the raw invoke result.
+ * Context for all expressions: `{ output: { result, data, error? } }`.
+ * All fields are optional.
+ */
+interface OutputTransforms {
+    /**
+     * JSONata expression that produces the transition name string.
+     * @example "output.code = 200 ? 'success' : 'failure'"
+     */
+    resultExpr?: string;
+    /**
+     * JSONata expression that produces the data object.
+     * @example "{ 'value': output.body.value }"
+     */
+    dataTemplate?: string;
+    /**
+     * JSONata expression that produces the error string, or $undefined() to clear it.
+     * @example "output.code != 200 ? output.error_message : $undefined()"
+     */
+    errorExpr?: string;
+}
+/**
+ * Optional JSONata-based mapping from logical args → physical invocation shape.
+ *
+ * Each field is a JSONata expression string evaluated against the caller's
+ * logical args object (e.g. `{ inRef, outRef, errRef }` for a task-executor).
+ *
+ * If argsMassaging is omitted entirely, the execution adapter uses its default
+ * mapping for the given howToRun kind.
+ */
+interface ArgsMassaging {
+    /**
+     * Array of JSONata expressions — each evaluates to one argv string.
+     * The resolved strings are appended after the base command.
+     *
+     * @example
+     * cmdTemplate: [
+     *   "'run-source-fetch'",
+     *   "'--in-ref'",  "inRef",
+     *   "'--out-ref'", "outRef",
+     *   "'--err-ref'", "errRef",
+     * ]
+     */
+    cmdTemplate?: string[];
+    /**
+     * JSONata expression that produces the stdin payload object.
+     * Evaluated against the logical args.
+     * If omitted, `JSON.stringify(args)` is sent on stdin.
+     *
+     * @example
+     * stdinTemplate: "{ 'X': x, 'multiplier': 2 }"
+     */
+    stdinTemplate?: string;
+    /**
+     * JSONata expression that produces the final URL string.
+     * The input context includes 'whatToRun' (the base URL from the ref)
+     * plus all logical args.
+     *
+     * @example
+     * urlTemplate: "whatToRun & '?op=' & subcommand"
+     */
+    urlTemplate?: string;
+    /**
+     * JSONata expression that produces the request headers object.
+     * Merged on top of the default headers (`Content-Type: application/json`).
+     *
+     * @example
+     * headerTemplate: "{ 'Authorization': 'Bearer ' & token }"
+     */
+    headerTemplate?: string;
+    /**
+     * JSONata expression that produces the request body object.
+     * Evaluated against the logical args object.
+     *
+     * @example
+     * bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef }"
+     */
+    bodyTemplate?: string;
+}
+type KnownExecutionTransport = 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in' | 'in-browser';
+type ExecutionTransportKind = KnownExecutionTransport | (string & {});
+/**
+ * Self-contained, serializable descriptor for invoking a target.
+ *
+ * Stores everything needed to make the physical call — transport kind,
+ * artifact address, and optional arg-mapping expressions.
+ * Serialize as plain JSON; no special wire encoding required.
+ */
+interface ExecutionRef {
+    /**
+     * Optional human-readable label identifying the role of this invocation.
+     * Not used for dispatch — purely for logging and diagnostics.
+     * @example 'task-executor', 'chat-handler', 'board-live-cards'
+     */
+    meta?: string;
+    /**
+     * Transport and runtime kind — determines how whatToRun is invoked.
+     * @see module JSDoc for the full list of supported values.
+     */
+    howToRun: ExecutionTransportKind;
+    /**
+      * Address of the artifact to run. Two valid forms:
+      *   - string:  must be KindValueRef wire form `b64:<base64url(json)>` (programmatically generated via serializeRef)
+      *   - object:  `{ kind: string; value: string }` plain object (human-authored flow files — normalized by the handler factory)
+      * @example 'b64:<base64url({"kind":"fs-path","value":"/dist/cli/source-cli-task-executor.js"})>'
+      * @example { kind: 'http-url', value: '/api/workiq/ask' }
+      * @example { kind: 'fs-path', value: './my-handler.js' }
+     */
+    whatToRun: string | {
+        kind: string;
+        value: string;
+    };
+    /**
+     * Optional JSONata-based mapping from logical args → physical call shape.
+     * When omitted, the adapter applies its default protocol for the howToRun kind.
+     */
+    argsMassaging?: ArgsMassaging;
+    /**
+     * Optional JSONata-based transforms applied to the raw invoke result
+     * before it reaches the step-machine engine.
+     *
+     * Context for all expressions: `{ output: { result, data, error? } }`
+     * where `output` is the raw { result, data, error? } returned by invokeRefSync.
+     *
+     * All fields are optional — only defined ones override the raw value.
+     *
+     * @example
+     * outputTransforms:
+     *   resultExpr:   "output.code = 200 ? 'success' : 'failure'"
+     *   dataTemplate: "{ 'value': output.body.value }"
+     *   errorExpr:    "output.code != 200 ? output.error_message : $undefined()"
+     */
+    outputTransforms?: OutputTransforms;
+    /**
+     * Opaque executor-specific configuration.
+     * For local transports, base64-encoded and passed as --extra <base64-json> in the argv.
+     * For HTTP transports, available in argsMassaging templates as the `extra` binding.
+     * Stored with the ref so it travels as a single unit with the invocation descriptor.
+     */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Standardized result envelope returned by any execution.
+ *
+ * Replaces the implicit "file-exists = success, absent = failure" protocol
+ * with an explicit status field.  The data ref points to the output blob.
+ */
+interface ExecutionResult {
+    /** Outcome of the execution. */
+    status: 'success' | 'fail' | 'error';
+    /**
+     * KindValueRef wire form pointing to the output blob.
+     * Present only when status === 'success'.
+     */
+    data?: string;
+    /**
+     * Human-readable error or failure message.
+     * Present when status === 'fail' or 'error'.
+     */
+    error?: string;
+}
+/**
+ * Create an ExecutionRef from a script path string (e.g. from a --task-executor CLI arg).
+ * File extension determines howToRun:
+ *   .js / .mjs → 'local-node'
+ *   .py        → 'local-python'
+ *   other      → 'local-process'
+ *
+ * @param scriptPath  Absolute or relative path to the script / binary.
+ * @param extra       Optional opaque executor config stored on the ref.
+ */
+declare function executionRefFromScriptPath(scriptPath: string, extra?: Record<string, unknown>): ExecutionRef;
+/**
+ * Serialize an ExecutionRef to a JSON string for storage.
+ * Plain JSON.stringify — no special encoding.
+ */
+declare function serializeExecutionRef(ref: ExecutionRef): string;
+/**
+ * Parse a JSON string back into an ExecutionRef.
+ * Throws if the string is not valid JSON or is missing required fields.
+ */
+declare function parseExecutionRef(s: string): ExecutionRef;
+
+export { type ArgsMassaging as A, type ExecutionRef as E, type ExecutionResult as a, executionRefFromScriptPath as e, parseExecutionRef as p, serializeExecutionRef as s };