@sensigo/realm 0.39.0 → 0.41.0

package/dist/workflow/source-positions.d.ts

@@ -0,0 +1,39 @@
+import type { State } from 'js-yaml';
+/**
+ * Where a key sits in the source. 1-based. `endColumn` is exclusive — one past the last character
+ * (the editor convention); all other bounds inclusive.
+ */
+export interface SourcePosition {
+    line: number;
+    column: number;
+    endLine: number;
+    endColumn: number;
+}
+/**
+ * Resolves a semantic path to its position in the source, or `undefined` if it cannot.
+ *
+ * The path is a SEQUENCE OF SEGMENTS — `['steps', 'my_step', 'execution']` — never a joined
+ * string, and that is a correctness requirement rather than a style preference. A dotted path
+ * aliases: a step literally named `a.b` and a field `b` on a step named `a` both flatten to
+ * `steps.a.b`, and last-write-wins hands one of them the OTHER's line. That is lawful YAML
+ * producing a confidently wrong position — the one outcome this module exists to make impossible.
+ *
+ * No separator fixes it. NUL does not: js-yaml parses `"a\0b"` into a key that CONTAINS a literal
+ * NUL, so a NUL-join aliases exactly as the dot did. There is no character a YAML key cannot hold,
+ * so only structure can carry the distinction.
+ */
+export interface SourcePositionMap {
+    posOf(segments: readonly string[]): SourcePosition | undefined;
+}
+/** A map that resolves nothing — for callers with no source text to map against. */
+export declare function emptySourcePositionMap(): SourcePositionMap;
+/**
+ * Collects positions during a parse. Create one, hand `listener` to `yaml.load`, then call
+ * `finish()`. One instance per parse — there is no module state, so concurrent loads cannot see
+ * each other's positions.
+ */
+export declare function createSourcePositionCollector(): {
+    listener: (event: 'open' | 'close', state: State) => void;
+    finish: () => SourcePositionMap;
+};
+//# sourceMappingURL=source-positions.d.ts.map

package/dist/workflow/source-positions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-positions.d.ts","sourceRoot":"","sources":["../../src/workflow/source-positions.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,GAAG,SAAS,CAAC;CAChE;AAgCD,oFAAoF;AACpF,wBAAgB,sBAAsB,IAAI,iBAAiB,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,IAAI;IAC/C,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1D,MAAM,EAAE,MAAM,iBAAiB,CAAC;CACjC,CA0CA"}

package/dist/workflow/source-positions.js

@@ -0,0 +1,107 @@
+const EMPTY_MAP = { posOf: () => undefined };
+/**
+ * The map's internal key. `JSON.stringify` of a string array is injective — the escaping is
+ * deterministic and the array brackets/commas are part of the encoding — so two different segment
+ * sequences can never produce the same key. `['a.b']` encodes as `["a.b"]` and `['a','b']` as
+ * `["a","b"]`; there is no input that collapses them.
+ */
+function keyOf(segments) {
+    return JSON.stringify(segments);
+}
+/** A map that resolves nothing — for callers with no source text to map against. */
+export function emptySourcePositionMap() {
+    return EMPTY_MAP;
+}
+/**
+ * Collects positions during a parse. Create one, hand `listener` to `yaml.load`, then call
+ * `finish()`. One instance per parse — there is no module state, so concurrent loads cannot see
+ * each other's positions.
+ */
+export function createSourcePositionCollector() {
+    // The root frame is a container for whatever closes at the top level; the document's own node
+    // lands in its children.
+    const stack = [{ startLine: 0, startColumn: 0, children: [] }];
+    return {
+        listener(event, state) {
+            if (event === 'open') {
+                stack.push({
+                    startLine: state.line,
+                    startColumn: state.position - state.lineStart,
+                    children: [],
+                });
+                return;
+            }
+            // A close with nothing open would mean the stream is not balanced. It is, on every input
+            // this parser accepts — but if it ever were not, dropping the event is the behaviour that
+            // preserves the invariant.
+            if (stack.length <= 1)
+                return;
+            const frame = stack.pop();
+            const parent = stack[stack.length - 1];
+            parent.children.push({
+                kind: state.kind,
+                result: state.result,
+                startLine: frame.startLine,
+                startColumn: frame.startColumn,
+                endLine: state.line,
+                endColumn: state.position - state.lineStart,
+                children: frame.children,
+            });
+        },
+        finish() {
+            const positions = new Map();
+            // The document node is the last thing to close at the top level.
+            const root = stack[0]?.children[stack[0].children.length - 1];
+            if (root !== undefined)
+                collect(root, [], positions);
+            return {
+                posOf: (segments) => positions.get(keyOf(segments)),
+            };
+        },
+    };
+}
+/**
+ * Walks a mapping and records one position per key, then descends.
+ *
+ * THE STRICT PAIRING RULE. A block mapping's immediate children arrive as key, value, key, value
+ * — so `children.length` must be exactly twice the key count, and each even child must BE the
+ * corresponding key. Anything else means this node's children do not line up with its keys the
+ * way they normally do: a flow mapping with a valueless key, a merge key that expanded, an anchor
+ * replayed from elsewhere in the document. In every one of those the positions would be off by
+ * some amount that is not knowable from here.
+ *
+ * So on any mismatch this records NOTHING for the whole mapping — not a best guess for the keys
+ * that happened to line up. That is the absent-never-wrong invariant, and it is deliberately
+ * blunt: the cost is a missing line number on an exotic shape, and the alternative is a confident
+ * wrong one on the same shape.
+ */
+function collect(node, path, into) {
+    // Only structural nodes are walked. Anchor replays surface as events nested inside scalars,
+    // which have no keys to map and are never descended into.
+    if (node.kind !== 'mapping')
+        return;
+    if (typeof node.result !== 'object' || node.result === null || Array.isArray(node.result))
+        return;
+    const keys = Object.keys(node.result);
+    if (node.children.length !== 2 * keys.length)
+        return;
+    for (let i = 0; i < keys.length; i++) {
+        if (node.children[2 * i].result !== keys[i])
+            return;
+    }
+    for (let i = 0; i < keys.length; i++) {
+        const keyNode = node.children[2 * i];
+        const valueNode = node.children[2 * i + 1];
+        const childPath = [...path, keys[i]];
+        // +1 on every coordinate: this is the ONE place 0-based parser state becomes 1-based
+        // human/agent coordinates.
+        into.set(keyOf(childPath), {
+            line: keyNode.startLine + 1,
+            column: keyNode.startColumn + 1,
+            endLine: keyNode.endLine + 1,
+            endColumn: keyNode.endColumn + 1,
+        });
+        collect(valueNode, childPath, into);
+    }
+}
+//# sourceMappingURL=source-positions.js.map

package/dist/workflow/source-positions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-positions.js","sourceRoot":"","sources":["../../src/workflow/source-positions.ts"],"names":[],"mappings":"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"}

package/dist/workflow/yaml-loader.d.ts

@@ -1,4 +1,5 @@
 import type { WorkflowDefinition } from '../types/workflow-definition.js';
+import { WorkflowError } from '../types/workflow-error.js';
 import { type LoaderWarning } from './diagnostics.js';
 import type { ExtensionRegistry } from '../extensions/registry.js';
 /** Bumped on every breaking change to WorkflowDefinition's serialized format. */
@@ -12,6 +13,22 @@ export declare const CURRENT_WORKFLOW_SCHEMA_VERSION = 1;
  * Pure `package.json`/`.git` walk — zero manifest knowledge.
  */
 export declare function findTrustRoot(dir: string): string;
+/**
+ * issue #424 — attaches the live loader warnings to an error on its way out.
+ *
+ * Two chokepoints call this (one in `parseWorkflowString`, one in `loadWorkflowFromFileCore`),
+ * which is why it exists rather than each throw site building its own error with a `warnings`
+ * option: there are eleven throw sites across this file plus four more in template-resolver.ts,
+ * the warnings array is out of scope at most of them, and a chokepoint covers every future one
+ * for free. The non-empty guard makes the classification automatic — a throw that happens before
+ * any warning could exist attaches nothing, by construction rather than by a rule someone has to
+ * remember.
+ *
+ * Attach-once: an inner chokepoint's attachment survives the outer one re-catching the same
+ * error, so a file-based load reports the warnings from the parse that produced it rather than
+ * an emptier outer set.
+ */
+export declare function attachLoaderWarnings(err: WorkflowError, warnings: readonly LoaderWarning[]): void;
 /**
  * Loads a WorkflowDefinition from a YAML file on disk. UNCHANGED signature/return type — the
  * non-breaking invariant (issue #169): every existing execution caller keeps compiling and

package/dist/workflow/yaml-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-loader.d.ts","sourceRoot":"","sources":["../../src/workflow/yaml-loader.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,iCAAiC,CAAC;AAQzC,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAyKnE,iFAAiF;AACjF,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAkFjD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUjD;AA4JD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,kBAAkB,CAIpB;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B;IAAE,UAAU,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,kBAAkB,CAMpB;AAED;;;GAGG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,iBAAiB,GAC3B;IAAE,UAAU,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAE/D"}
+{"version":3,"file":"yaml-loader.d.ts","sourceRoot":"","sources":["../../src/workflow/yaml-loader.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,iCAAiC,CAAC;AAOzC,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAsOnE,iFAAiF;AACjF,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAkFjD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAIjG;AA8KD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,kBAAkB,CAIpB;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B;IAAE,UAAU,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,kBAAkB,CAMpB;AAED;;;GAGG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,iBAAiB,GAC3B;IAAE,UAAU,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAE/D"}