@oxygen-agent/cli 1.739.1 → 1.750.4

package/node_modules/@oxygen/workflows/dist/graph/mapping.js

@@ -0,0 +1,436 @@
+export const DEFAULT_WORKFLOW_MAPPING_FIELD_LIMITS = {
+    maxDepth: 6,
+    maxKeysPerObject: 40,
+    maxFields: 240,
+};
+const BLOCKED_SEGMENTS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+const SAFE_SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SOURCE_ORDER = [
+    "pinned_sample",
+    "observed",
+    "declared",
+];
+const TYPE_ORDER = [
+    "object",
+    "array",
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "null",
+    "unknown",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function appendMappingProperty(prefix, value) {
+    if (BLOCKED_SEGMENTS.has(value))
+        return null;
+    if (SAFE_SEGMENT.test(value))
+        return prefix ? `${prefix}.${value}` : value;
+    return `${prefix}[${JSON.stringify(value)}]`;
+}
+/** Join one relative mapping path to a rooted executable scope path. */
+export function workflowMappingScopePath(base, relative) {
+    if (!relative)
+        return base;
+    return relative.startsWith("[") ? `${base}${relative}` : `${base}.${relative}`;
+}
+/** Canonical relative mapping path from decoded property segments. */
+export function workflowMappingPathFromSegments(segments) {
+    let path = "";
+    for (const segment of segments) {
+        const next = appendMappingProperty(path, segment);
+        if (next === null)
+            return null;
+        path = next;
+    }
+    return path;
+}
+/** True only for the display grammar's unquoted `[]` array marker. */
+export function workflowMappingPathHasArrayBoundary(path) {
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index < path.length; index += 1) {
+        const character = path[index] ?? "";
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === "\"")
+                quoted = false;
+            continue;
+        }
+        if (character === "\"") {
+            quoted = true;
+            continue;
+        }
+        if (character === "[" && path[index + 1] === "]")
+            return true;
+    }
+    return false;
+}
+function orderedTypes(types) {
+    const values = new Set(types);
+    return TYPE_ORDER.filter((type) => values.has(type));
+}
+function orderedSources(sources) {
+    const values = new Set(sources);
+    return SOURCE_ORDER.filter((source) => values.has(source));
+}
+function normalizedTypeEvidence(field) {
+    if (field.typesBySource) {
+        return Object.fromEntries(Object.entries(field.typesBySource).map(([source, types]) => [
+            source,
+            orderedTypes(types ?? []),
+        ]));
+    }
+    return Object.fromEntries(field.sources.map((source) => [source, [...field.types]]));
+}
+function mergeTypeEvidence(left, right) {
+    const merged = {};
+    const leftEvidence = normalizedTypeEvidence(left);
+    const rightEvidence = normalizedTypeEvidence(right);
+    for (const source of SOURCE_ORDER) {
+        const types = orderedTypes([
+            ...(leftEvidence[source] ?? []),
+            ...(rightEvidence[source] ?? []),
+        ]);
+        if (types.length > 0)
+            merged[source] = types;
+    }
+    return merged;
+}
+export function workflowMappingValueType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (isRecord(value))
+        return "object";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    if (typeof value === "string")
+        return "string";
+    if (typeof value === "boolean")
+        return "boolean";
+    return "unknown";
+}
+/** Human-sized preview; never used to resolve a mapping or build a payload. */
+export function workflowMappingSample(value, maxLength = 72) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `[${value.length} ${value.length === 1 ? "item" : "items"}]`;
+    if (isRecord(value)) {
+        const count = Object.keys(value).length;
+        return `{${count} ${count === 1 ? "field" : "fields"}}`;
+    }
+    const raw = typeof value === "string" ? value : String(value);
+    const oneLine = raw.replace(/\s+/g, " ").trim();
+    return oneLine.length <= maxLength ? oneLine : `${oneLine.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+function schemaTypes(schema) {
+    if (!isRecord(schema))
+        return ["unknown"];
+    const types = new Set();
+    const declared = typeof schema.type === "string"
+        ? [schema.type]
+        : Array.isArray(schema.type)
+            ? schema.type
+            : [];
+    for (const type of declared) {
+        if (TYPE_ORDER.includes(type)) {
+            types.add(type);
+        }
+    }
+    if (isRecord(schema.properties) || Object.hasOwn(schema, "additionalProperties")) {
+        types.add("object");
+    }
+    if (isRecord(schema.items))
+        types.add("array");
+    if (Array.isArray(schema.anyOf)) {
+        for (const option of schema.anyOf) {
+            for (const type of schemaTypes(option))
+                types.add(type);
+        }
+    }
+    return orderedTypes(types.size > 0 ? types : ["unknown"]);
+}
+function addField(fields, next, maxFields) {
+    const existing = fields.get(next.path);
+    if (!existing && fields.size >= maxFields)
+        return;
+    fields.set(next.path, existing
+        ? {
+            path: next.path,
+            types: orderedTypes([...existing.types, ...next.types]),
+            typesBySource: mergeTypeEvidence(existing, next),
+            sources: orderedSources([...existing.sources, ...next.sources]),
+            ...(existing.sample !== undefined
+                ? {
+                    sample: existing.sample,
+                    ...(existing.sampleSource ? { sampleSource: existing.sampleSource } : {}),
+                }
+                : next.sample !== undefined
+                    ? {
+                        sample: next.sample,
+                        ...(next.sampleSource ? { sampleSource: next.sampleSource } : {}),
+                    }
+                    : {}),
+            ...(existing.observedAt
+                ? { observedAt: existing.observedAt }
+                : next.observedAt
+                    ? { observedAt: next.observedAt }
+                    : {}),
+        }
+        : next);
+}
+/** Flatten a JSON Schema while retaining types, array boundaries, and pinned examples. */
+export function workflowMappingFieldsFromSchema(schema, options = {}) {
+    const fields = new Map();
+    const limits = options.limits ?? DEFAULT_WORKFLOW_MAPPING_FIELD_LIMITS;
+    const source = options.source ?? "declared";
+    const explicitSample = options.sample !== undefined;
+    const schemaExample = isRecord(schema) && Array.isArray(schema.examples)
+        ? schema.examples[0]
+        : undefined;
+    const rootSample = explicitSample ? options.sample : schemaExample;
+    const rootSampleSource = rootSample === undefined
+        ? undefined
+        : explicitSample
+            ? options.sampleSource ?? "pinned_sample"
+            : "declared";
+    const walk = (node, prefix, sample, depth) => {
+        if (!isRecord(node) || depth > limits.maxDepth || fields.size >= limits.maxFields)
+            return;
+        if (Array.isArray(node.anyOf)) {
+            for (const option of node.anyOf)
+                walk(option, prefix, sample, depth + 1);
+        }
+        const types = schemaTypes(node);
+        if (types.includes("array")) {
+            walk(node.items, `${prefix}[]`, Array.isArray(sample) ? sample[0] : undefined, depth + 1);
+            return;
+        }
+        if (!isRecord(node.properties))
+            return;
+        let taken = 0;
+        for (const [name, child] of Object.entries(node.properties)) {
+            if (taken >= limits.maxKeysPerObject || fields.size >= limits.maxFields)
+                return;
+            const path = appendMappingProperty(prefix, name);
+            if (path === null)
+                continue;
+            if (!prefix && options.omitRootPaths?.has(name))
+                continue;
+            taken += 1;
+            const childSample = isRecord(sample) && Object.hasOwn(sample, name) ? sample[name] : undefined;
+            const samplePreview = childSample === undefined
+                ? undefined
+                : workflowMappingSample(childSample);
+            const declaredTypes = schemaTypes(child);
+            const sampleTypes = childSample === undefined
+                ? []
+                : [workflowMappingValueType(childSample)];
+            const typesBySource = {
+                [source]: declaredTypes,
+            };
+            if (rootSampleSource && sampleTypes.length > 0) {
+                typesBySource[rootSampleSource] = orderedTypes([
+                    ...(typesBySource[rootSampleSource] ?? []),
+                    ...sampleTypes,
+                ]);
+            }
+            addField(fields, {
+                path,
+                types: orderedTypes([...declaredTypes, ...sampleTypes]),
+                typesBySource,
+                sources: orderedSources([
+                    source,
+                    ...(childSample === undefined || !rootSampleSource ? [] : [rootSampleSource]),
+                ]),
+                ...(samplePreview === undefined
+                    ? {}
+                    : {
+                        sample: samplePreview,
+                        ...(rootSampleSource ? { sampleSource: rootSampleSource } : {}),
+                    }),
+            }, limits.maxFields);
+            walk(child, path, childSample, depth + 1);
+        }
+    };
+    walk(schema, "", rootSample, 0);
+    return [...fields.values()];
+}
+/** Describe actual JSON output without retaining more than a bounded display preview. */
+export function workflowMappingFieldsFromValue(value, options = {}) {
+    const fields = new Map();
+    const limits = options.limits ?? DEFAULT_WORKFLOW_MAPPING_FIELD_LIMITS;
+    const includeSamples = options.includeSamples ?? true;
+    const walk = (current, prefix, depth) => {
+        if (depth > limits.maxDepth || fields.size >= limits.maxFields)
+            return;
+        if (Array.isArray(current)) {
+            // One array can carry nullable or variant object rows. Inspecting only the
+            // first item made fields disappear whenever row zero happened to be null
+            // or a different variant. Twenty bounded samples are enough to learn the
+            // shape without turning a 50k-row provider response into editor work.
+            for (const item of current.slice(0, 20)) {
+                if (Array.isArray(item) || isRecord(item))
+                    walk(item, `${prefix}[]`, depth + 1);
+            }
+            return;
+        }
+        if (!isRecord(current))
+            return;
+        let taken = 0;
+        for (const key of Object.keys(current)) {
+            if (taken >= limits.maxKeysPerObject || fields.size >= limits.maxFields)
+                return;
+            const path = appendMappingProperty(prefix, key);
+            if (path === null)
+                continue;
+            taken += 1;
+            const child = current[key];
+            const sample = includeSamples ? workflowMappingSample(child) : undefined;
+            addField(fields, {
+                path,
+                types: [workflowMappingValueType(child)],
+                typesBySource: { observed: [workflowMappingValueType(child)] },
+                sources: ["observed"],
+                ...(sample === undefined ? {} : { sample, sampleSource: "observed" }),
+            }, limits.maxFields);
+            walk(child, path, depth + 1);
+        }
+    };
+    walk(value, "", 0);
+    return [...fields.values()];
+}
+export function mergeWorkflowMappingFields(...groups) {
+    const merged = new Map();
+    const maxFields = Math.max(DEFAULT_WORKFLOW_MAPPING_FIELD_LIMITS.maxFields, groups.reduce((total, group) => total + group.length, 0));
+    for (const group of groups) {
+        for (const field of group)
+            addField(merged, field, maxFields);
+    }
+    return [...merged.values()];
+}
+/** Compatibility adapter for older path-only observations and small fixtures. */
+export function workflowMappingFieldsFromPaths(paths, source = "observed") {
+    return [...new Set(paths)].map((path) => ({
+        path,
+        types: ["unknown"],
+        typesBySource: { [source]: ["unknown"] },
+        sources: [source],
+    }));
+}
+/** Attach immutable run lineage without changing the field's stable path/type contract. */
+export function withWorkflowMappingObservation(fields, observedAt) {
+    return fields.map((field) => field.sources.includes("observed")
+        ? { ...field, observedAt }
+        : field);
+}
+export function workflowMappingSourceLabel(source) {
+    switch (source) {
+        case "pinned_sample": return "Pinned sample";
+        case "observed": return "Observed";
+        case "declared": return "Declared";
+    }
+}
+export function workflowMappingObservationLabel(observation) {
+    return observation.scope === "workflow"
+        ? `Run v${observation.revisionVersion}${observation.stale ? " · older revision" : ""}`
+        : `Workspace run v${observation.revisionVersion}`;
+}
+function targetTypes(value) {
+    const values = typeof value === "string" ? [value] : value ?? [];
+    const types = values.filter((entry) => (TYPE_ORDER.includes(entry)));
+    return orderedTypes(types.length > 0 ? types : ["unknown"]);
+}
+function typeCompatible(source, target) {
+    if (source === target)
+        return true;
+    return source === "integer" && target === "number";
+}
+/** True when real run evidence contradicts the endpoint's declared type contract. */
+export function workflowMappingFieldHasTypeDrift(field) {
+    const evidence = normalizedTypeEvidence(field);
+    const declared = evidence.declared;
+    const observed = evidence.observed;
+    if (!declared?.length || !observed?.length)
+        return false;
+    return observed.some((actual) => !declared.some((expected) => typeCompatible(actual, expected)));
+}
+/** Compact, evidence-specific type copy for picker rows and diagnostics. */
+export function workflowMappingTypeEvidenceLabel(field) {
+    const evidence = normalizedTypeEvidence(field);
+    const labels = SOURCE_ORDER.flatMap((source) => {
+        const types = evidence[source];
+        return types?.length
+            ? [`${workflowMappingSourceLabel(source)} ${types.join(" | ")}`]
+            : [];
+    });
+    return labels.length > 0 ? labels.join(" · ") : field.types.join(" | ");
+}
+function coercionForTarget(types, target) {
+    if (!["string", "number", "integer", "boolean"].includes(target))
+        return [];
+    if (types.some((type) => type === "null" || type === "array" || type === "object" || type === "unknown")) {
+        return [];
+    }
+    const safe = types.every((type) => {
+        if (target === "string")
+            return type === "string" || type === "number" || type === "integer" || type === "boolean";
+        if (target === "number")
+            return type === "string" || type === "number" || type === "integer";
+        if (target === "integer")
+            return type === "string" || type === "integer";
+        return type === "string" || type === "boolean";
+    });
+    return safe ? [target] : [];
+}
+/** Compare one source field with one destination schema field. */
+export function workflowMappingCompatibility(sourceTypes, destinationType, coercion) {
+    const targets = targetTypes(destinationType);
+    const original = sourceTypes && sourceTypes.length > 0 ? [...sourceTypes] : ["unknown"];
+    const sourceLabel = original.join(" | ");
+    const targetLabel = targets.join(" | ");
+    if (targets.includes("unknown") || original.includes("unknown")) {
+        return { status: "unknown", sourceLabel, targetLabel, coercions: [] };
+    }
+    // A stored conversion still receives null and therefore fails. Without a
+    // conversion, nullable input is compatible only when the destination allows
+    // null too.
+    if (original.includes("null")
+        && (coercion !== undefined || !targets.includes("null"))
+        && !original.every((type) => type === "null")) {
+        return { status: "nullable", sourceLabel, targetLabel, coercions: [] };
+    }
+    const allowedCoercions = [...new Set(targets.flatMap((target) => coercionForTarget(original, target)))];
+    if (coercion !== undefined && !allowedCoercions.includes(coercion)) {
+        return {
+            status: "incompatible",
+            sourceLabel,
+            targetLabel,
+            coercions: allowedCoercions,
+        };
+    }
+    const effective = coercion ? [coercion] : original;
+    if (effective.every((type) => targets.some((target) => typeCompatible(type, target)))) {
+        return { status: "compatible", sourceLabel, targetLabel, coercions: [] };
+    }
+    return {
+        status: allowedCoercions.length > 0 ? "coercible" : "incompatible",
+        sourceLabel,
+        targetLabel,
+        coercions: allowedCoercions,
+    };
+}

package/node_modules/@oxygen/workflows/dist/graph/topology.d.ts

@@ -43,6 +43,15 @@ export declare function loopBodyNodeIds(graph: WorkflowGraphManifest, loopNodeId
  * runs and across machines.
  */
 export declare function topologicalOrder(graph: WorkflowGraphManifest): string[] | null;
+/**
+ * Nodes that execute on every forward path reaching `targetNodeId`.
+ *
+ * A structural ancestor is not necessarily available: after a switch rejoins,
+ * each branch is an ancestor but only one branch ran. Dominators are the exact
+ * graph concept the mapper needs. Legal loop back-edges are removed, matching
+ * execution order and the existing topological analysis.
+ */
+export declare function dominatingNodeIds(graph: WorkflowGraphManifest, targetNodeId: string): Set<string>;
 /**
  * Illegal cycles: one entry per strongly connected component that still contains
  * a cycle once legal loop back-edges are removed.

package/node_modules/@oxygen/workflows/dist/graph/topology.js

@@ -230,6 +230,58 @@ export function topologicalOrder(graph) {
     }
     return order.length === nodes.size ? order : null;
 }
+/**
+ * Nodes that execute on every forward path reaching `targetNodeId`.
+ *
+ * A structural ancestor is not necessarily available: after a switch rejoins,
+ * each branch is an ancestor but only one branch ran. Dominators are the exact
+ * graph concept the mapper needs. Legal loop back-edges are removed, matching
+ * execution order and the existing topological analysis.
+ */
+export function dominatingNodeIds(graph, targetNodeId) {
+    const forward = forwardOutgoing(graph);
+    const reachable = traverse(rootNodeIds(graph), forward);
+    if (!reachable.has(targetNodeId))
+        return new Set();
+    const order = topologicalOrder(graph);
+    if (!order)
+        return new Set();
+    const incoming = new Map();
+    for (const id of nodeIndex(graph).keys())
+        incoming.set(id, []);
+    for (const [source, edges] of forward) {
+        for (const edge of edges) {
+            if (!reachable.has(source) || !reachable.has(edge.target))
+                continue;
+            incoming.get(edge.target)?.push(source);
+        }
+    }
+    const roots = new Set(rootNodeIds(graph));
+    const dominators = new Map();
+    for (const id of order) {
+        if (!reachable.has(id))
+            continue;
+        if (roots.has(id)) {
+            dominators.set(id, new Set([id]));
+            continue;
+        }
+        const predecessors = (incoming.get(id) ?? [])
+            .map((predecessor) => dominators.get(predecessor))
+            .filter((entry) => entry !== undefined);
+        if (predecessors.length === 0) {
+            dominators.set(id, new Set([id]));
+            continue;
+        }
+        const intersection = new Set(predecessors[0]);
+        for (const candidate of [...intersection]) {
+            if (predecessors.some((set) => !set.has(candidate)))
+                intersection.delete(candidate);
+        }
+        intersection.add(id);
+        dominators.set(id, intersection);
+    }
+    return dominators.get(targetNodeId) ?? new Set();
+}
 /**
  * Illegal cycles: one entry per strongly connected component that still contains
  * a cycle once legal loop back-edges are removed.

package/node_modules/@oxygen/workflows/dist/graph/types.d.ts

@@ -70,6 +70,7 @@ export type WorkflowValueRef =
  | {
     type: "ref";
     path: string;
+    coerce?: WorkflowValueCoercion;
 }
 /** An OXYGEN formula-language expression (packages/formula). */
  | {
@@ -88,6 +89,16 @@ export type WorkflowValueRef =
     path?: string;
 };
 export type WorkflowValueRefType = WorkflowValueRef["type"];
+/**
+ * Explicit, fail-closed scalar conversions for a mapped value.
+ *
+ * A mapping never changes type merely because the destination field expects a
+ * different one. Authors may choose one of these conversions after the editor
+ * explains the mismatch; conversion failure stops the step instead of turning
+ * an invalid value into a provider request.
+ */
+export declare const WORKFLOW_VALUE_COERCIONS: readonly ["string", "number", "integer", "boolean"];
+export type WorkflowValueCoercion = typeof WORKFLOW_VALUE_COERCIONS[number];
 /** The only JSON value kinds the oxygen-js-v1 output validator enforces. */
 export type WorkflowCodeJsonType = "array" | "boolean" | "integer" | "null" | "number" | "object" | "string";
 /**

package/node_modules/@oxygen/workflows/dist/graph/types.js

@@ -69,6 +69,20 @@ export const BILLABLE_WORKFLOW_GRAPH_NODE_KINDS = new Set([
 export function workflowGraphNodeKindBills(kind) {
     return BILLABLE_WORKFLOW_GRAPH_NODE_KINDS.has(kind);
 }
+/**
+ * Explicit, fail-closed scalar conversions for a mapped value.
+ *
+ * A mapping never changes type merely because the destination field expects a
+ * different one. Authors may choose one of these conversions after the editor
+ * explains the mismatch; conversion failure stops the step instead of turning
+ * an invalid value into a provider request.
+ */
+export const WORKFLOW_VALUE_COERCIONS = [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+];
 export const WORKFLOW_CODE_V1_VERSION = 1;
 export const WORKFLOW_CODE_V1_LANGUAGE = "javascript";
 export const WORKFLOW_CODE_V1_RUNTIME = "oxygen-js-v1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.739.1",
+  "version": "1.750.4",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",