@sweny-ai/core 0.1.101 → 0.1.102

package/dist/claude.js

@@ -372,6 +372,7 @@ export function buildEvaluatePrompt(question, context, choices) {
         `1. Read each choice's condition literally and match against the structured fields in the context (e.g. status, counts, enum values, boolean flags).`,
         `2. Ignore prose narrative fields ("summary", free-form rationale, conversational commentary). They are not the contract.`,
         `3. When a field's value contradicts what a prose field claims, trust the field's value.`,
+        `4. A field whose value is explicitly null means the source node DECLARED that field but did NOT emit a value. Treat null as "unknown" and do NOT match it against any specific value (do not match "is 0", "is N", "is true", "is false", or "is undefined" against a null field). Prefer a default/fallback edge when the field needed for a decision is null.`,
         `\nRespond with ONLY the choice ID, nothing else.`,
     ].join("\n");
 }

package/dist/executor.js

@@ -174,6 +174,27 @@ export async function execute(workflow, input, options) {
             // Retry only triggers on eval failure. Bail on tool/API errors.
             if (result.status !== "success")
                 break;
+            // Required-field gate: if the source node's declared output schema
+            // marks fields as `required`, those fields are the routing contract.
+            // An agent that omits a required field has violated the contract; we
+            // fail the node loudly rather than letting routing guess against a
+            // half-built data view. See the offload release-notes field bug:
+            // an optional quality_retry_count was declared in the schema but
+            // omitted by the agent, the route view silently dropped the key,
+            // and an "is 0 OR is undefined" condition ghost-matched.
+            //
+            // We only check declared `required` fields, not full JSON Schema
+            // validation. Type mismatches, formats, additionalProperties, etc.
+            // stay the workflow author's problem and don't have the same
+            // routing-correctness blast radius.
+            const missingRequired = findMissingRequiredFields(result.data, node.output);
+            if (missingRequired.length > 0) {
+                const msg = `output schema violation: required field(s) missing from emitted data: ${missingRequired.join(", ")}`;
+                result.status = "failed";
+                result.data = { ...(result.data ?? {}), error: msg };
+                logger.warn(`  ${msg}`, { node: currentId });
+                break;
+            }
             const evalResults = await evaluateAll(node.eval, result, {
                 aliases: toolAliases,
                 claude,
@@ -344,16 +365,44 @@ function buildPriorNodeContext(result) {
 function buildRouteEvalEntry(result, sourceNode) {
     const fullData = (result.data ?? {});
     const declaredProps = getDeclaredOutputProperties(sourceNode?.output);
-    const dataView = declaredProps ? pickKeys(fullData, declaredProps) : fullData;
+    // When the source node declared an `output.properties` block, the routing
+    // view is contract-shaped: every declared property is present in the
+    // view, with an explicit `null` when the agent did not emit it. The
+    // alternative (silently dropping the key) lets the LLM evaluator
+    // ghost-match conditions like "is 0", "is N", or "is undefined" against
+    // a structurally-absent field. That was the offload release-notes field
+    // bug: an optional `quality_retry_count` declared in the schema but
+    // omitted by the agent, evaluated against a condition like
+    // `quality_retry_count is 0 OR is undefined`, took the wrong branch.
+    //
+    // Returning `missing` separately lets the caller emit a loud warning so
+    // operators see the contract violation in the log stream.
+    let dataView;
+    const missing = [];
+    if (declaredProps) {
+        dataView = {};
+        for (const k of declaredProps) {
+            if (k in fullData) {
+                dataView[k] = fullData[k];
+            }
+            else {
+                dataView[k] = null;
+                missing.push(k);
+            }
+        }
+    }
+    else {
+        dataView = fullData;
+    }
     const evals = result.evals ?? [];
     if (evals.length === 0)
-        return dataView;
+        return { view: dataView, missing };
     const evalsByName = {};
     for (const e of evals) {
         evalsByName[e.name] = e;
     }
     // Spread evals first so a data-side `evals` key shadows it (back-compat).
-    return { evals: evalsByName, ...dataView };
+    return { view: { evals: evalsByName, ...dataView }, missing };
 }
 /**
  * Return the declared output property names for a node, or null when the
@@ -375,13 +424,34 @@ function getDeclaredOutputProperties(output) {
         return null;
     return new Set(keys);
 }
-function pickKeys(obj, keys) {
-    const out = {};
-    for (const k of keys) {
-        if (k in obj)
-            out[k] = obj[k];
-    }
-    return out;
+/**
+ * Return the declared `required` field names for a node's output schema,
+ * or an empty array when no required block is declared. Tolerant of
+ * malformed schemas (mirrors getDeclaredOutputProperties).
+ */
+function getDeclaredRequiredFields(output) {
+    if (!output || typeof output !== "object")
+        return [];
+    const required = output.required;
+    if (!Array.isArray(required))
+        return [];
+    return required.filter((r) => typeof r === "string");
+}
+/**
+ * Validate a node's emitted data against the declared output schema's
+ * required fields. Returns the list of required-but-missing field names.
+ *
+ * This is intentionally narrow: we do NOT do full JSON Schema validation.
+ * The routing impact comes from required fields being absent, so that's
+ * what we check. Type mismatches, format violations, additionalProperties
+ * etc. stay the workflow author's problem.
+ */
+function findMissingRequiredFields(data, output) {
+    const required = getDeclaredRequiredFields(output);
+    if (required.length === 0)
+        return [];
+    const obj = (data ?? {});
+    return required.filter((k) => !(k in obj));
 }
 function nodeSourcesToArray(ns) {
     if (!ns)
@@ -587,10 +657,28 @@ async function resolveNext(workflow, current, results, input, claude, observer,
     // always-injected `summary` prose from the reference Claude client) can
     // sway the natural-language route evaluator and override the actual
     // structured result. See `buildRouteEvalEntry` for the full rationale.
-    const context = {
-        input,
-        ...Object.fromEntries([...results.entries()].map(([k, v]) => [k, buildRouteEvalEntry(v, workflow.nodes[k])])),
-    };
+    const context = { input };
+    for (const [k, v] of results.entries()) {
+        const { view, missing } = buildRouteEvalEntry(v, workflow.nodes[k]);
+        context[k] = view;
+        if (missing.length > 0) {
+            // Loud signal for the operator. The view itself already replaces the
+            // missing keys with explicit `null`, so the LLM evaluator cannot
+            // ghost-match "is N" or "is undefined" against a structurally-absent
+            // field. The warning surfaces the contract violation in the log
+            // stream and to observer-based telemetry.
+            logger?.warn(`  route eval: source node '${k}' declared properties not in emitted data: ${missing.join(", ")}`, {
+                node: k,
+                fields: missing,
+            });
+            safeObserve(observer, {
+                type: "node:warning",
+                node: k,
+                reason: `declared output properties missing from emitted data; routing view filled them with null`,
+                fields: missing,
+            }, logger);
+        }
+    }
     const choices = conditionalEdges.map((e) => ({
         id: e.to,
         description: e.when,

package/dist/types.d.ts

@@ -409,6 +409,23 @@ export type ExecutionEvent = {
     attempt: number;
     reason: string;
     preamble: string;
+}
+/**
+ * Non-fatal contract violation surfaced during node execution. Currently
+ * emitted when a source node declares output properties that the agent
+ * did not emit. The route eval view fills the missing keys with `null`
+ * so the LLM evaluator can't ghost-match conditions like "is undefined"
+ * or "is 0", but the operator still wants a loud signal in the log
+ * stream.
+ *
+ * `fields` lists the declared property names that were missing from the
+ * emitted data. `reason` is a short human-readable summary.
+ */
+ | {
+    type: "node:warning";
+    node: string;
+    reason: string;
+    fields: string[];
 } | {
     type: "route";
     from: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.101",
+  "version": "0.1.102",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"