yaml-flow 5.4.2 → 6.0.0

package/dist/execution-refs.cjs

@@ -0,0 +1,2 @@
+'use strict';function o(e,t){let n;return /\.m?js$/i.test(e)?n="local-node":/\.py$/i.test(e)?n="local-python":n="local-process",{meta:"task-executor",howToRun:n,whatToRun:`::fs-path::${e}`,...t?{extra:t}:{}}}function r(e){return JSON.stringify(e)}function i(e){let t;try{t=JSON.parse(e);}catch{throw new Error(`parseExecutionRef: invalid JSON \u2014 ${e}`)}if(typeof t!="object"||t===null||typeof t.howToRun!="string"||typeof t.whatToRun!="string")throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun \u2014 ${e}`);return t}exports.executionRefFromScriptPath=o;exports.parseExecutionRef=i;exports.serializeExecutionRef=r;//# sourceMappingURL=execution-refs.cjs.map
+//# sourceMappingURL=execution-refs.cjs.map

package/dist/execution-refs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/common/execution-interface.ts"],"names":["executionRefFromScriptPath","scriptPath","extra","howToRun","serializeExecutionRef","ref","parseExecutionRef","s","parsed"],"mappings":"aA6OO,SAASA,CAAAA,CACdC,EACAC,CAAAA,CACc,CACd,IAAIC,CAAAA,CACJ,OAAI,WAAW,IAAA,CAAKF,CAAU,EAAGE,CAAAA,CAAW,YAAA,CACnC,SAAS,IAAA,CAAKF,CAAU,EAAGE,CAAAA,CAAW,cAAA,CAC1CA,EAAW,eAAA,CACT,CACL,KAAM,eAAA,CACN,QAAA,CAAAA,EACA,SAAA,CAAW,CAAA,WAAA,EAAcF,CAAU,CAAA,CAAA,CACnC,GAAIC,EAAQ,CAAE,KAAA,CAAAA,CAAM,CAAA,CAAI,EAC1B,CACF,CAUO,SAASE,CAAAA,CAAsBC,CAAAA,CAA2B,CAC/D,OAAO,IAAA,CAAK,SAAA,CAAUA,CAAG,CAC3B,CAMO,SAASC,CAAAA,CAAkBC,CAAAA,CAAyB,CACzD,IAAIC,CAAAA,CACJ,GAAI,CACFA,CAAAA,CAAS,KAAK,KAAA,CAAMD,CAAC,EACvB,CAAA,KAAQ,CACN,MAAM,IAAI,KAAA,CAAM,CAAA,uCAAA,EAAqCA,CAAC,CAAA,CAAE,CAC1D,CACA,GACE,OAAOC,GAAW,QAAA,EAClBA,CAAAA,GAAW,MACX,OAAQA,CAAAA,CAAmC,UAAa,QAAA,EACxD,OAAQA,EAAmC,SAAA,EAAc,QAAA,CAEzD,MAAM,IAAI,KAAA,CAAM,wEAAmED,CAAC,CAAA,CAAE,CAAA,CAExF,OAAOC,CACT","file":"execution-refs.cjs","sourcesContent":["/**\n * execution-interface.ts\n *\n * Pure module — no Node/platform imports.  Safe for any runtime.\n *\n * Defines the portable descriptor types for invoking any executable target,\n * regardless of transport (local process, HTTP endpoint, cloud function, etc.).\n *\n * Parallel to storage-interface.ts (which describes WHERE data lives), this\n * module describes HOW to invoke a piece of logic.\n *\n * ────────────────────────────────────────────────────────────────────────────\n * CORE CONCEPTS\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  ExecutionRef — self-contained, serializable JSON descriptor for one invocation target.\n *    • howToRun    — transport / runtime kind (discriminator)\n *    • whatToRun   — address of the artifact (KindValueRef wire form: ::kind::value)\n *    • argsMassaging — optional JSONata expressions that map logical args → physical call shape\n *    • meta        — optional human-readable label (e.g. 'task-executor', 'chat-handler')\n *\n *  ExecutionResult — standardized envelope returned by any invocation.\n *    • status: 'success' | 'fail' | 'error'\n *    • data   — KindValueRef wire form pointing to output blob (on success)\n *    • error  — human-readable message (on fail/error)\n *\n * ────────────────────────────────────────────────────────────────────────────\n * howToRun VALUES\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  'local-node'      node <whatToRun> [argv...]\n *  'local-python'    python <whatToRun> [argv...]\n *  'local-process'   execute <whatToRun> directly (shebang / pre-resolved binary)\n *  'http:post'       HTTP POST to <whatToRun>\n *  'http:get'        HTTP GET to <whatToRun>\n *  'built-in'        resolved by the adapter to a well-known internal implementation\n *\n * ────────────────────────────────────────────────────────────────────────────\n * argsMassaging\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  Each field is a JSONata expression evaluated against the caller's logical args object.\n *  If argsMassaging is omitted, the adapter uses its default mapping for the howToRun kind.\n *\n *  cmdTemplate  — array of JSONata exprs, each producing one argv string (local transports)\n *  urlTemplate  — JSONata expr producing the final URL string (http transports)\n *  bodyTemplate — JSONata expr producing the request body object (http transports)\n *\n * ────────────────────────────────────────────────────────────────────────────\n * SERIALIZATION\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  ExecutionRef is a plain JSON object — store it as-is on disk, in Cosmos, or any DB.\n *  No special encoding needed.  parseExecutionRef / serializeExecutionRef are thin\n *  JSON wrappers provided for symmetry with storage-interface.\n *\n * ────────────────────────────────────────────────────────────────────────────\n * USAGE EXAMPLES\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  // Built-in source-cli task executor (resolved by adapter from cliDir):\n *  const builtIn: ExecutionRef = {\n *    meta: 'task-executor',\n *    howToRun: 'built-in',\n *    whatToRun: '::built-in::source-cli-task-executor',\n *  };\n *\n *  // External local-node task executor with default protocol args:\n *  const local: ExecutionRef = {\n *    meta: 'task-executor',\n *    howToRun: 'local-node',\n *    whatToRun: '::fs-path::/path/to/my-executor.js',\n *  };\n *\n *  // Azure Function task executor with custom arg mapping:\n *  const azureFn: ExecutionRef = {\n *    meta: 'task-executor',\n *    howToRun: 'http:post',\n *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/task-executor',\n *    argsMassaging: {\n *      urlTemplate: \"whatToRun & '?op=' & subcommand\",\n *      bodyTemplate: \"{ 'inRef': inRef, 'outRef': outRef, 'token': token }\",\n *    },\n *  };\n *\n *  // Chat handler over HTTP with a different logical args shape:\n *  const chatHandler: ExecutionRef = {\n *    meta: 'chat-handler',\n *    howToRun: 'http:post',\n *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/chat',\n *    argsMassaging: {\n *      bodyTemplate: \"{ 'message': message, 'context': context, 'sessionId': sessionId }\",\n *    },\n *  };\n */\n\n// ============================================================================\n// ArgsMassaging\n// ============================================================================\n\n/**\n * Optional JSONata-based mapping from logical args → physical invocation shape.\n *\n * Each field is a JSONata expression string evaluated against the caller's\n * logical args object (e.g. `{ inRef, outRef, errRef }` for a task-executor).\n *\n * If argsMassaging is omitted entirely, the execution adapter uses its default\n * mapping for the given howToRun kind.\n */\nexport interface ArgsMassaging {\n  /**\n   * For local transports ('local-node', 'local-python', 'local-process').\n   * Array of JSONata expressions — each evaluates to one argv string.\n   * The resolved strings are appended after the base command.\n   *\n   * @example\n   * // Standard task-executor protocol:\n   * cmdTemplate: [\n   *   \"'run-source-fetch'\",\n   *   \"'--in-ref'\",  \"inRef\",\n   *   \"'--out-ref'\", \"outRef\",\n   *   \"'--err-ref'\", \"errRef\",\n   * ]\n   */\n  cmdTemplate?: string[];\n\n  /**\n   * For http transports ('http:post', 'http:get').\n   * JSONata expression that produces the final URL string.\n   * The input context includes 'whatToRun' (the base URL from the ref)\n   * plus all logical args.\n   *\n   * @example\n   * urlTemplate: \"whatToRun & '?op=' & subcommand\"\n   */\n  urlTemplate?: string;\n\n  /**\n   * For http transports.\n   * JSONata expression that produces the request body object.\n   * Evaluated against the logical args object.\n   *\n   * @example\n   * bodyTemplate: \"{ 'inRef': inRef, 'outRef': outRef, 'token': token }\"\n   */\n  bodyTemplate?: string;\n}\n\n// ============================================================================\n// ExecutionRef\n// ============================================================================\n\n/**\n * Self-contained, serializable descriptor for invoking a target.\n *\n * Stores everything needed to make the physical call — transport kind,\n * artifact address, and optional arg-mapping expressions.\n * Serialize as plain JSON; no special wire encoding required.\n */\nexport interface ExecutionRef {\n  /**\n   * Optional human-readable label identifying the role of this invocation.\n   * Not used for dispatch — purely for logging and diagnostics.\n   * @example 'task-executor', 'chat-handler', 'board-live-cards'\n   */\n  meta?: string;\n\n  /**\n   * Transport and runtime kind — determines how whatToRun is invoked.\n   * @see module JSDoc for the full list of supported values.\n   */\n  howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';\n\n  /**\n   * Address of the artifact to run, in KindValueRef wire form (::kind::value).\n   * @example '::fs-path::/dist/cli/source-cli-task-executor.js'\n   * @example '::http-url::https://fn.example.com/api/executor'\n   * @example '::built-in::source-cli-task-executor'\n   */\n  whatToRun: string;\n\n  /**\n   * Optional JSONata-based mapping from logical args → physical call shape.\n   * When omitted, the adapter applies its default protocol for the howToRun kind.\n   */\n  argsMassaging?: ArgsMassaging;\n\n  /**\n   * Opaque executor-specific configuration.\n   * For local transports, base64-encoded and passed as --extra <base64-json> in the argv.\n   * For HTTP transports, available in argsMassaging.bodyTemplate as the `extra` binding.\n   * Stored with the ref so it travels as a single unit with the invocation descriptor.\n   */\n  extra?: Record<string, unknown>;\n}\n\n// ============================================================================\n// ExecutionResult\n// ============================================================================\n\n/**\n * Standardized result envelope returned by any execution.\n *\n * Replaces the implicit \"file-exists = success, absent = failure\" protocol\n * with an explicit status field.  The data ref points to the output blob.\n */\nexport interface ExecutionResult {\n  /** Outcome of the execution. */\n  status: 'success' | 'fail' | 'error';\n\n  /**\n   * KindValueRef wire form pointing to the output blob.\n   * Present only when status === 'success'.\n   */\n  data?: string;\n\n  /**\n   * Human-readable error or failure message.\n   * Present when status === 'fail' or 'error'.\n   */\n  error?: string;\n}\n\n// ============================================================================\n// ExecutionRef factory helpers\n// ============================================================================\n\n/**\n * Create an ExecutionRef from a script path string (e.g. from a --task-executor CLI arg).\n * File extension determines howToRun:\n *   .js / .mjs → 'local-node'\n *   .py        → 'local-python'\n *   other      → 'local-process'\n *\n * @param scriptPath  Absolute or relative path to the script / binary.\n * @param extra       Optional opaque executor config stored on the ref.\n */\nexport function executionRefFromScriptPath(\n  scriptPath: string,\n  extra?: Record<string, unknown>,\n): ExecutionRef {\n  let howToRun: ExecutionRef['howToRun'];\n  if (/\\.m?js$/i.test(scriptPath)) howToRun = 'local-node';\n  else if (/\\.py$/i.test(scriptPath)) howToRun = 'local-python';\n  else howToRun = 'local-process';\n  return {\n    meta: 'task-executor',\n    howToRun,\n    whatToRun: `::fs-path::${scriptPath}`,\n    ...(extra ? { extra } : {}),\n  };\n}\n\n// ============================================================================\n// Serialization helpers\n// ============================================================================\n\n/**\n * Serialize an ExecutionRef to a JSON string for storage.\n * Plain JSON.stringify — no special encoding.\n */\nexport function serializeExecutionRef(ref: ExecutionRef): string {\n  return JSON.stringify(ref);\n}\n\n/**\n * Parse a JSON string back into an ExecutionRef.\n * Throws if the string is not valid JSON or is missing required fields.\n */\nexport function parseExecutionRef(s: string): ExecutionRef {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(s);\n  } catch {\n    throw new Error(`parseExecutionRef: invalid JSON — ${s}`);\n  }\n  if (\n    typeof parsed !== 'object' ||\n    parsed === null ||\n    typeof (parsed as Record<string, unknown>).howToRun !== 'string' ||\n    typeof (parsed as Record<string, unknown>).whatToRun !== 'string'\n  ) {\n    throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun — ${s}`);\n  }\n  return parsed as ExecutionRef;\n}\n"]}

package/dist/execution-refs.d.cts

@@ -0,0 +1,222 @@
+/**
+ * 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: ::kind::value)
+ *    • 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.
+ *
+ *  cmdTemplate  — array of JSONata exprs, each producing one argv string (local transports)
+ *  urlTemplate  — JSONata expr producing the final URL string (http transports)
+ *  bodyTemplate — JSONata expr producing the request body object (http transports)
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * 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: '::built-in::source-cli-task-executor',
+ *  };
+ *
+ *  // External local-node task executor with default protocol args:
+ *  const local: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'local-node',
+ *    whatToRun: '::fs-path::/path/to/my-executor.js',
+ *  };
+ *
+ *  // Azure Function task executor with custom arg mapping:
+ *  const azureFn: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'http:post',
+ *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/task-executor',
+ *    argsMassaging: {
+ *      urlTemplate: "whatToRun & '?op=' & subcommand",
+ *      bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef, 'token': token }",
+ *    },
+ *  };
+ *
+ *  // Chat handler over HTTP with a different logical args shape:
+ *  const chatHandler: ExecutionRef = {
+ *    meta: 'chat-handler',
+ *    howToRun: 'http:post',
+ *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/chat',
+ *    argsMassaging: {
+ *      bodyTemplate: "{ 'message': message, 'context': context, 'sessionId': sessionId }",
+ *    },
+ *  };
+ */
+/**
+ * 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 {
+    /**
+     * For local transports ('local-node', 'local-python', 'local-process').
+     * Array of JSONata expressions — each evaluates to one argv string.
+     * The resolved strings are appended after the base command.
+     *
+     * @example
+     * // Standard task-executor protocol:
+     * cmdTemplate: [
+     *   "'run-source-fetch'",
+     *   "'--in-ref'",  "inRef",
+     *   "'--out-ref'", "outRef",
+     *   "'--err-ref'", "errRef",
+     * ]
+     */
+    cmdTemplate?: string[];
+    /**
+     * For http transports ('http:post', 'http:get').
+     * 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;
+    /**
+     * For http transports.
+     * JSONata expression that produces the request body object.
+     * Evaluated against the logical args object.
+     *
+     * @example
+     * bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef, 'token': token }"
+     */
+    bodyTemplate?: 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: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';
+    /**
+     * Address of the artifact to run, in KindValueRef wire form (::kind::value).
+     * @example '::fs-path::/dist/cli/source-cli-task-executor.js'
+     * @example '::http-url::https://fn.example.com/api/executor'
+     * @example '::built-in::source-cli-task-executor'
+     */
+    whatToRun: 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;
+    /**
+     * Opaque executor-specific configuration.
+     * For local transports, base64-encoded and passed as --extra <base64-json> in the argv.
+     * For HTTP transports, available in argsMassaging.bodyTemplate 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, type ExecutionRef, type ExecutionResult, executionRefFromScriptPath, parseExecutionRef, serializeExecutionRef };

package/dist/execution-refs.d.ts

@@ -0,0 +1,222 @@
+/**
+ * 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: ::kind::value)
+ *    • 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.
+ *
+ *  cmdTemplate  — array of JSONata exprs, each producing one argv string (local transports)
+ *  urlTemplate  — JSONata expr producing the final URL string (http transports)
+ *  bodyTemplate — JSONata expr producing the request body object (http transports)
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * 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: '::built-in::source-cli-task-executor',
+ *  };
+ *
+ *  // External local-node task executor with default protocol args:
+ *  const local: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'local-node',
+ *    whatToRun: '::fs-path::/path/to/my-executor.js',
+ *  };
+ *
+ *  // Azure Function task executor with custom arg mapping:
+ *  const azureFn: ExecutionRef = {
+ *    meta: 'task-executor',
+ *    howToRun: 'http:post',
+ *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/task-executor',
+ *    argsMassaging: {
+ *      urlTemplate: "whatToRun & '?op=' & subcommand",
+ *      bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef, 'token': token }",
+ *    },
+ *  };
+ *
+ *  // Chat handler over HTTP with a different logical args shape:
+ *  const chatHandler: ExecutionRef = {
+ *    meta: 'chat-handler',
+ *    howToRun: 'http:post',
+ *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/chat',
+ *    argsMassaging: {
+ *      bodyTemplate: "{ 'message': message, 'context': context, 'sessionId': sessionId }",
+ *    },
+ *  };
+ */
+/**
+ * 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 {
+    /**
+     * For local transports ('local-node', 'local-python', 'local-process').
+     * Array of JSONata expressions — each evaluates to one argv string.
+     * The resolved strings are appended after the base command.
+     *
+     * @example
+     * // Standard task-executor protocol:
+     * cmdTemplate: [
+     *   "'run-source-fetch'",
+     *   "'--in-ref'",  "inRef",
+     *   "'--out-ref'", "outRef",
+     *   "'--err-ref'", "errRef",
+     * ]
+     */
+    cmdTemplate?: string[];
+    /**
+     * For http transports ('http:post', 'http:get').
+     * 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;
+    /**
+     * For http transports.
+     * JSONata expression that produces the request body object.
+     * Evaluated against the logical args object.
+     *
+     * @example
+     * bodyTemplate: "{ 'inRef': inRef, 'outRef': outRef, 'token': token }"
+     */
+    bodyTemplate?: 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: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';
+    /**
+     * Address of the artifact to run, in KindValueRef wire form (::kind::value).
+     * @example '::fs-path::/dist/cli/source-cli-task-executor.js'
+     * @example '::http-url::https://fn.example.com/api/executor'
+     * @example '::built-in::source-cli-task-executor'
+     */
+    whatToRun: 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;
+    /**
+     * Opaque executor-specific configuration.
+     * For local transports, base64-encoded and passed as --extra <base64-json> in the argv.
+     * For HTTP transports, available in argsMassaging.bodyTemplate 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, type ExecutionRef, type ExecutionResult, executionRefFromScriptPath, parseExecutionRef, serializeExecutionRef };

package/dist/execution-refs.js

@@ -0,0 +1,2 @@
+function o(e,t){let n;return /\.m?js$/i.test(e)?n="local-node":/\.py$/i.test(e)?n="local-python":n="local-process",{meta:"task-executor",howToRun:n,whatToRun:`::fs-path::${e}`,...t?{extra:t}:{}}}function r(e){return JSON.stringify(e)}function i(e){let t;try{t=JSON.parse(e);}catch{throw new Error(`parseExecutionRef: invalid JSON \u2014 ${e}`)}if(typeof t!="object"||t===null||typeof t.howToRun!="string"||typeof t.whatToRun!="string")throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun \u2014 ${e}`);return t}export{o as executionRefFromScriptPath,i as parseExecutionRef,r as serializeExecutionRef};//# sourceMappingURL=execution-refs.js.map
+//# sourceMappingURL=execution-refs.js.map

package/dist/execution-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/common/execution-interface.ts"],"names":["executionRefFromScriptPath","scriptPath","extra","howToRun","serializeExecutionRef","ref","parseExecutionRef","s","parsed"],"mappings":"AA6OO,SAASA,CAAAA,CACdC,EACAC,CAAAA,CACc,CACd,IAAIC,CAAAA,CACJ,OAAI,WAAW,IAAA,CAAKF,CAAU,EAAGE,CAAAA,CAAW,YAAA,CACnC,SAAS,IAAA,CAAKF,CAAU,EAAGE,CAAAA,CAAW,cAAA,CAC1CA,EAAW,eAAA,CACT,CACL,KAAM,eAAA,CACN,QAAA,CAAAA,EACA,SAAA,CAAW,CAAA,WAAA,EAAcF,CAAU,CAAA,CAAA,CACnC,GAAIC,EAAQ,CAAE,KAAA,CAAAA,CAAM,CAAA,CAAI,EAC1B,CACF,CAUO,SAASE,CAAAA,CAAsBC,CAAAA,CAA2B,CAC/D,OAAO,IAAA,CAAK,SAAA,CAAUA,CAAG,CAC3B,CAMO,SAASC,CAAAA,CAAkBC,CAAAA,CAAyB,CACzD,IAAIC,CAAAA,CACJ,GAAI,CACFA,CAAAA,CAAS,KAAK,KAAA,CAAMD,CAAC,EACvB,CAAA,KAAQ,CACN,MAAM,IAAI,KAAA,CAAM,CAAA,uCAAA,EAAqCA,CAAC,CAAA,CAAE,CAC1D,CACA,GACE,OAAOC,GAAW,QAAA,EAClBA,CAAAA,GAAW,MACX,OAAQA,CAAAA,CAAmC,UAAa,QAAA,EACxD,OAAQA,EAAmC,SAAA,EAAc,QAAA,CAEzD,MAAM,IAAI,KAAA,CAAM,wEAAmED,CAAC,CAAA,CAAE,CAAA,CAExF,OAAOC,CACT","file":"execution-refs.js","sourcesContent":["/**\n * execution-interface.ts\n *\n * Pure module — no Node/platform imports.  Safe for any runtime.\n *\n * Defines the portable descriptor types for invoking any executable target,\n * regardless of transport (local process, HTTP endpoint, cloud function, etc.).\n *\n * Parallel to storage-interface.ts (which describes WHERE data lives), this\n * module describes HOW to invoke a piece of logic.\n *\n * ────────────────────────────────────────────────────────────────────────────\n * CORE CONCEPTS\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  ExecutionRef — self-contained, serializable JSON descriptor for one invocation target.\n *    • howToRun    — transport / runtime kind (discriminator)\n *    • whatToRun   — address of the artifact (KindValueRef wire form: ::kind::value)\n *    • argsMassaging — optional JSONata expressions that map logical args → physical call shape\n *    • meta        — optional human-readable label (e.g. 'task-executor', 'chat-handler')\n *\n *  ExecutionResult — standardized envelope returned by any invocation.\n *    • status: 'success' | 'fail' | 'error'\n *    • data   — KindValueRef wire form pointing to output blob (on success)\n *    • error  — human-readable message (on fail/error)\n *\n * ────────────────────────────────────────────────────────────────────────────\n * howToRun VALUES\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  'local-node'      node <whatToRun> [argv...]\n *  'local-python'    python <whatToRun> [argv...]\n *  'local-process'   execute <whatToRun> directly (shebang / pre-resolved binary)\n *  'http:post'       HTTP POST to <whatToRun>\n *  'http:get'        HTTP GET to <whatToRun>\n *  'built-in'        resolved by the adapter to a well-known internal implementation\n *\n * ────────────────────────────────────────────────────────────────────────────\n * argsMassaging\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  Each field is a JSONata expression evaluated against the caller's logical args object.\n *  If argsMassaging is omitted, the adapter uses its default mapping for the howToRun kind.\n *\n *  cmdTemplate  — array of JSONata exprs, each producing one argv string (local transports)\n *  urlTemplate  — JSONata expr producing the final URL string (http transports)\n *  bodyTemplate — JSONata expr producing the request body object (http transports)\n *\n * ────────────────────────────────────────────────────────────────────────────\n * SERIALIZATION\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  ExecutionRef is a plain JSON object — store it as-is on disk, in Cosmos, or any DB.\n *  No special encoding needed.  parseExecutionRef / serializeExecutionRef are thin\n *  JSON wrappers provided for symmetry with storage-interface.\n *\n * ────────────────────────────────────────────────────────────────────────────\n * USAGE EXAMPLES\n * ────────────────────────────────────────────────────────────────────────────\n *\n *  // Built-in source-cli task executor (resolved by adapter from cliDir):\n *  const builtIn: ExecutionRef = {\n *    meta: 'task-executor',\n *    howToRun: 'built-in',\n *    whatToRun: '::built-in::source-cli-task-executor',\n *  };\n *\n *  // External local-node task executor with default protocol args:\n *  const local: ExecutionRef = {\n *    meta: 'task-executor',\n *    howToRun: 'local-node',\n *    whatToRun: '::fs-path::/path/to/my-executor.js',\n *  };\n *\n *  // Azure Function task executor with custom arg mapping:\n *  const azureFn: ExecutionRef = {\n *    meta: 'task-executor',\n *    howToRun: 'http:post',\n *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/task-executor',\n *    argsMassaging: {\n *      urlTemplate: \"whatToRun & '?op=' & subcommand\",\n *      bodyTemplate: \"{ 'inRef': inRef, 'outRef': outRef, 'token': token }\",\n *    },\n *  };\n *\n *  // Chat handler over HTTP with a different logical args shape:\n *  const chatHandler: ExecutionRef = {\n *    meta: 'chat-handler',\n *    howToRun: 'http:post',\n *    whatToRun: '::http-url::https://myfn.azurewebsites.net/api/chat',\n *    argsMassaging: {\n *      bodyTemplate: \"{ 'message': message, 'context': context, 'sessionId': sessionId }\",\n *    },\n *  };\n */\n\n// ============================================================================\n// ArgsMassaging\n// ============================================================================\n\n/**\n * Optional JSONata-based mapping from logical args → physical invocation shape.\n *\n * Each field is a JSONata expression string evaluated against the caller's\n * logical args object (e.g. `{ inRef, outRef, errRef }` for a task-executor).\n *\n * If argsMassaging is omitted entirely, the execution adapter uses its default\n * mapping for the given howToRun kind.\n */\nexport interface ArgsMassaging {\n  /**\n   * For local transports ('local-node', 'local-python', 'local-process').\n   * Array of JSONata expressions — each evaluates to one argv string.\n   * The resolved strings are appended after the base command.\n   *\n   * @example\n   * // Standard task-executor protocol:\n   * cmdTemplate: [\n   *   \"'run-source-fetch'\",\n   *   \"'--in-ref'\",  \"inRef\",\n   *   \"'--out-ref'\", \"outRef\",\n   *   \"'--err-ref'\", \"errRef\",\n   * ]\n   */\n  cmdTemplate?: string[];\n\n  /**\n   * For http transports ('http:post', 'http:get').\n   * JSONata expression that produces the final URL string.\n   * The input context includes 'whatToRun' (the base URL from the ref)\n   * plus all logical args.\n   *\n   * @example\n   * urlTemplate: \"whatToRun & '?op=' & subcommand\"\n   */\n  urlTemplate?: string;\n\n  /**\n   * For http transports.\n   * JSONata expression that produces the request body object.\n   * Evaluated against the logical args object.\n   *\n   * @example\n   * bodyTemplate: \"{ 'inRef': inRef, 'outRef': outRef, 'token': token }\"\n   */\n  bodyTemplate?: string;\n}\n\n// ============================================================================\n// ExecutionRef\n// ============================================================================\n\n/**\n * Self-contained, serializable descriptor for invoking a target.\n *\n * Stores everything needed to make the physical call — transport kind,\n * artifact address, and optional arg-mapping expressions.\n * Serialize as plain JSON; no special wire encoding required.\n */\nexport interface ExecutionRef {\n  /**\n   * Optional human-readable label identifying the role of this invocation.\n   * Not used for dispatch — purely for logging and diagnostics.\n   * @example 'task-executor', 'chat-handler', 'board-live-cards'\n   */\n  meta?: string;\n\n  /**\n   * Transport and runtime kind — determines how whatToRun is invoked.\n   * @see module JSDoc for the full list of supported values.\n   */\n  howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';\n\n  /**\n   * Address of the artifact to run, in KindValueRef wire form (::kind::value).\n   * @example '::fs-path::/dist/cli/source-cli-task-executor.js'\n   * @example '::http-url::https://fn.example.com/api/executor'\n   * @example '::built-in::source-cli-task-executor'\n   */\n  whatToRun: string;\n\n  /**\n   * Optional JSONata-based mapping from logical args → physical call shape.\n   * When omitted, the adapter applies its default protocol for the howToRun kind.\n   */\n  argsMassaging?: ArgsMassaging;\n\n  /**\n   * Opaque executor-specific configuration.\n   * For local transports, base64-encoded and passed as --extra <base64-json> in the argv.\n   * For HTTP transports, available in argsMassaging.bodyTemplate as the `extra` binding.\n   * Stored with the ref so it travels as a single unit with the invocation descriptor.\n   */\n  extra?: Record<string, unknown>;\n}\n\n// ============================================================================\n// ExecutionResult\n// ============================================================================\n\n/**\n * Standardized result envelope returned by any execution.\n *\n * Replaces the implicit \"file-exists = success, absent = failure\" protocol\n * with an explicit status field.  The data ref points to the output blob.\n */\nexport interface ExecutionResult {\n  /** Outcome of the execution. */\n  status: 'success' | 'fail' | 'error';\n\n  /**\n   * KindValueRef wire form pointing to the output blob.\n   * Present only when status === 'success'.\n   */\n  data?: string;\n\n  /**\n   * Human-readable error or failure message.\n   * Present when status === 'fail' or 'error'.\n   */\n  error?: string;\n}\n\n// ============================================================================\n// ExecutionRef factory helpers\n// ============================================================================\n\n/**\n * Create an ExecutionRef from a script path string (e.g. from a --task-executor CLI arg).\n * File extension determines howToRun:\n *   .js / .mjs → 'local-node'\n *   .py        → 'local-python'\n *   other      → 'local-process'\n *\n * @param scriptPath  Absolute or relative path to the script / binary.\n * @param extra       Optional opaque executor config stored on the ref.\n */\nexport function executionRefFromScriptPath(\n  scriptPath: string,\n  extra?: Record<string, unknown>,\n): ExecutionRef {\n  let howToRun: ExecutionRef['howToRun'];\n  if (/\\.m?js$/i.test(scriptPath)) howToRun = 'local-node';\n  else if (/\\.py$/i.test(scriptPath)) howToRun = 'local-python';\n  else howToRun = 'local-process';\n  return {\n    meta: 'task-executor',\n    howToRun,\n    whatToRun: `::fs-path::${scriptPath}`,\n    ...(extra ? { extra } : {}),\n  };\n}\n\n// ============================================================================\n// Serialization helpers\n// ============================================================================\n\n/**\n * Serialize an ExecutionRef to a JSON string for storage.\n * Plain JSON.stringify — no special encoding.\n */\nexport function serializeExecutionRef(ref: ExecutionRef): string {\n  return JSON.stringify(ref);\n}\n\n/**\n * Parse a JSON string back into an ExecutionRef.\n * Throws if the string is not valid JSON or is missing required fields.\n */\nexport function parseExecutionRef(s: string): ExecutionRef {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(s);\n  } catch {\n    throw new Error(`parseExecutionRef: invalid JSON — ${s}`);\n  }\n  if (\n    typeof parsed !== 'object' ||\n    parsed === null ||\n    typeof (parsed as Record<string, unknown>).howToRun !== 'string' ||\n    typeof (parsed as Record<string, unknown>).whatToRun !== 'string'\n  ) {\n    throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun — ${s}`);\n  }\n  return parsed as ExecutionRef;\n}\n"]}