@vaudience/aigentflow-flow-validator 0.15.3 → 0.18.0

package/dist/index.cjs

@@ -432,7 +432,7 @@ function validateBasicStructure(flow, issues) {
 
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
-  specVersion: "2.802.0",
+  specVersion: "2.819.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -463,7 +463,6 @@ var aigentflow_spec_default = {
     "messenger",
     "mock",
     "mqtt",
-    "nexus",
     "opencorporates",
     "openmeteo",
     "overpass",
@@ -754,12 +753,6 @@ var aigentflow_spec_default = {
     fields: ["api_key", "base_url", "organization"],
     extraKey: "extra",
     scopes: {
-      aigentchat: [
-        "AIGENTFLOW_AIGENTCHAT_API_KEY",
-        "AIGENTFLOW_AIGENTCHAT_BASE_URL",
-        "AIGENTFLOW_NEXUS_API_KEY",
-        "AIGENTFLOW_NEXUS_BASE_URL"
-      ],
       anthropic: [
         "AIGENTFLOW_ANTHROPIC_API_KEY",
         "AIGENTFLOW_ANTHROPIC_BASE_URL"
@@ -867,12 +860,6 @@ var aigentflow_spec_default = {
         "AIGENTFLOW_MQTT_PASSWORD",
         "AIGENTFLOW_MQTT_USERNAME"
       ],
-      nexus: [
-        "AIGENTFLOW_AIGENTCHAT_API_KEY",
-        "AIGENTFLOW_AIGENTCHAT_BASE_URL",
-        "AIGENTFLOW_NEXUS_API_KEY",
-        "AIGENTFLOW_NEXUS_BASE_URL"
-      ],
       ollama: [
         "AIGENTFLOW_OLLAMA_API_KEY",
         "AIGENTFLOW_OLLAMA_BASE_URL"
@@ -992,9 +979,6 @@ var aigentflow_spec_default = {
       ]
     },
     familyKeySeparator: "/",
-    protocolAliases: {
-      aigentchat: "nexus"
-    },
     families: {
       db: {
         protocol: "db",
@@ -1153,40 +1137,6 @@ var aigentflow_spec_default = {
           "AIGENTFLOW_MQTT_PASSWORD"
         ]
       },
-      nexus: {
-        protocol: "nexus",
-        configKeys: [
-          "nexus",
-          "aigentchat"
-        ],
-        secretParams: [
-          "aigentchat_api_key",
-          "api_key"
-        ],
-        endpointParams: [
-          "aigentchat_base_url",
-          "base_url"
-        ],
-        defaultEndpoints: [],
-        configApiKeyParam: "",
-        configBaseUrlParam: "",
-        implicitServerCredential: false,
-        expandsServerEnvReferences: false,
-        serverEnv: [
-          "AIGENTFLOW_NEXUS_BASE_URL",
-          "AIGENTFLOW_NEXUS_API_KEY",
-          "AIGENTFLOW_AIGENTCHAT_API_KEY",
-          "AIGENTFLOW_AIGENTCHAT_BASE_URL"
-        ],
-        storedKeyShape: {
-          ownKeyParams: [
-            "aigentchat_api_key",
-            "api_key"
-          ],
-          ownCredentialsMapParam: "credentials",
-          provider: "aigentchat"
-        }
-      },
       opencorporates: {
         protocol: "opencorporates",
         configKeys: [
@@ -1307,6 +1257,97 @@ var aigentflow_spec_default = {
       }
     }
   },
+  examples: {
+    limits: {
+      maxPerFlow: 50,
+      maxBlockBytes: 262144,
+      maxInlineInputBytes: 32768,
+      maxReferenceTextBytes: 32768,
+      maxVariants: 10,
+      maxTags: 8,
+      maxMustNot: 12,
+      maxMustNotContain: 20,
+      maxRubricRunes: 4e3,
+      maxGuidanceRunes: 2e3,
+      maxNotesRunes: 2e3,
+      titleMaxRunes: 80,
+      maxMustNotRunes: 300,
+      maxMustNotContainLength: 200,
+      maxProvenanceRunes: 200,
+      maxNoteRunes: 300,
+      maxUrlBytes: 2048,
+      maxPatternLength: 512,
+      weightMax: 10,
+      minScoreMin: 0,
+      minScoreMax: 1
+    },
+    idPattern: "^[a-z][a-z0-9_]{1,47}$",
+    tagPattern: "^[a-z][a-z0-9_-]{0,31}$",
+    sha256Pattern: "^[0-9a-f]{64}$",
+    mediaTypePattern: "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$",
+    signedUrlQueryKeyPattern: "^(x-amz-signature|signature|sig|token|access_token|key|x-goog-signature|se|sp)$",
+    origins: [
+      "author",
+      "synthetic"
+    ],
+    sideEffects: [
+      "refuse",
+      "allow"
+    ],
+    statuses: [
+      "completed",
+      "failed",
+      "paused_for_human"
+    ],
+    reservedRefSchemes: [
+      "artifact",
+      "trove",
+      "aiv",
+      "s3",
+      "gs"
+    ],
+    secretPatterns: [
+      {
+        name: "an API key",
+        expr: "\\bsk-[A-Za-z0-9_-]{20,}",
+        flags: ""
+      },
+      {
+        name: "a platform API key",
+        expr: "\\bcrn_[A-Za-z0-9]{16,}",
+        flags: ""
+      },
+      {
+        name: "an AWS access key",
+        expr: "\\bAKIA[0-9A-Z]{16}\\b",
+        flags: ""
+      },
+      {
+        name: "a private key",
+        expr: "-----BEGIN [A-Z ]*PRIVATE KEY-----",
+        flags: ""
+      },
+      {
+        name: "a bearer token",
+        expr: "\\bbearer\\s+[A-Za-z0-9._~+/-]{20,}",
+        flags: "i"
+      },
+      {
+        name: "a Slack token",
+        expr: "\\bxox[abprs]-[A-Za-z0-9-]{10,}",
+        flags: ""
+      },
+      {
+        name: "a GitHub token",
+        expr: "\\bgh[pousr]_[A-Za-z0-9]{30,}",
+        flags: ""
+      },
+      {
+        name: "a retired registry key",
+        expr: "\\baivk_[A-Za-z0-9]{20,}",
+        flags: ""
+      }
+    ]},
   knownKeys: {
     root: "Flow",
     types: {
@@ -1327,6 +1368,17 @@ var aigentflow_spec_default = {
         on_children_complete: "scalar",
         shared_memory: "scalar"
       },
+      Checkpoint: {
+        exact: "map<any>",
+        fields: "map<FieldMatcher>",
+        min_score: "scalar",
+        must_not: "list<scalar>",
+        must_not_contain: "list<scalar>",
+        optional: "scalar",
+        reference: "ExampleReference",
+        rubric: "scalar",
+        status: "scalar"
+      },
       CheckpointConfig: {
         enabled: "scalar",
         interval_steps: "scalar",
@@ -1349,6 +1401,37 @@ var aigentflow_spec_default = {
         retry_delay: "scalar",
         retry_on: "list<scalar>"
       },
+      ExampleDefinition: {
+        checkpoints: "map<Checkpoint>",
+        expected: "Expectation",
+        guidance: "scalar",
+        hold_out: "scalar",
+        id: "scalar",
+        input: "map<any>",
+        input_ref: "FileRef",
+        min_score: "scalar",
+        notes: "scalar",
+        side_effects: "scalar",
+        tags: "list<scalar>",
+        title: "scalar",
+        variants: "list<ExampleVariant>",
+        weight: "scalar"
+      },
+      ExampleReference: {
+        ref: "FileRef",
+        text: "scalar"
+      },
+      ExampleVariant: {
+        expected: "Expectation",
+        guidance: "scalar",
+        id: "scalar",
+        input_patch: "map<any>",
+        input_ref: "FileRef",
+        origin: "scalar",
+        provenance: "scalar",
+        title: "scalar",
+        weight: "scalar"
+      },
       ExecutorDefaultsDefinition: {
         frequency_penalty: "scalar",
         max_tokens: "scalar",
@@ -1371,6 +1454,16 @@ var aigentflow_spec_default = {
         allowed_models: "list<scalar>",
         allowed_providers: "list<scalar>"
       },
+      Expectation: {
+        exact: "map<any>",
+        fields: "map<FieldMatcher>",
+        min_score: "scalar",
+        must_not: "list<scalar>",
+        must_not_contain: "list<scalar>",
+        reference: "ExampleReference",
+        rubric: "scalar",
+        status: "scalar"
+      },
       FailoverBreakerConfig: {
         failure_threshold: "scalar",
         open_duration: "scalar",
@@ -1389,6 +1482,22 @@ var aigentflow_spec_default = {
         type: "scalar",
         validation: "scalar"
       },
+      FieldMatcher: {
+        approx: "scalar",
+        contains: "scalar",
+        equals: "any",
+        matches: "scalar",
+        not_contains: "scalar",
+        one_of: "list<any>",
+        present: "scalar",
+        tolerance: "scalar"
+      },
+      FileRef: {
+        media_type: "scalar",
+        note: "scalar",
+        sha256: "scalar",
+        url: "scalar"
+      },
       Flow: {
         aigentflow_version: "scalar",
         billing: "BillingConfig",
@@ -1402,6 +1511,7 @@ var aigentflow_spec_default = {
         discoverable_tools: "list<scalar>",
         display_name: "scalar",
         error_strategy: "ErrorStrategyDefinition",
+        examples: "list<ExampleDefinition>",
         executor_config: "map<ExecutorInstanceDefinition>",
         exons_uploads: "ExonsUploadsFlowConfig",
         expression_functions: "list<map<scalar>>",
@@ -1479,6 +1589,7 @@ var aigentflow_spec_default = {
         pattern: "scalar",
         required: "scalar",
         type: "scalar",
+        untrusted: "scalar",
         visible_when: "VisibleWhenPredicate"
       },
       LoopDefinition: {
@@ -1488,6 +1599,7 @@ var aigentflow_spec_default = {
         while: "scalar"
       },
       LoopStepDefinition: {
+        allow_untrusted: "list<scalar>",
         condition: "scalar",
         credential: "scalar",
         credentials: "map<StepCredentialBinding>",
@@ -1500,7 +1612,8 @@ var aigentflow_spec_default = {
         post_processing: "list<any>",
         pre_processing: "list<any>",
         query: "map<any>",
-        response_evaluation: "scalar"
+        response_evaluation: "scalar",
+        trusted_output: "scalar"
       },
       MockBinaryAsset: {
         filename: "scalar",
@@ -1588,6 +1701,7 @@ var aigentflow_spec_default = {
         properties: "map<PropertyDefinition>",
         required: "scalar",
         type: "scalar",
+        untrusted: "scalar",
         validation: "scalar"
       },
       StepCredentialBinding: {
@@ -1595,6 +1709,7 @@ var aigentflow_spec_default = {
         source: "scalar"
       },
       StepDefinition: {
+        allow_untrusted: "list<scalar>",
         condition: "scalar",
         credential: "scalar",
         credentials: "map<StepCredentialBinding>",
@@ -1612,7 +1727,8 @@ var aigentflow_spec_default = {
         quality_gate: "QualityGateDefinition",
         query: "map<any>",
         response_evaluation: "scalar",
-        response_expectation: "map<FieldExpectationDefinition>"
+        response_expectation: "map<FieldExpectationDefinition>",
+        trusted_output: "scalar"
       },
       ThrottleDefinition: {
         batch_delay: "scalar",
@@ -1732,9 +1848,25 @@ var CREDENTIAL_ENDPOINT_PAIRING = {
     executorConfigProviders: aigentflow_spec_default.credentialEndpointPairing.ai.executorConfigProviders
   },
   familyKeySeparator: aigentflow_spec_default.credentialEndpointPairing.familyKeySeparator,
-  protocolAliases: aigentflow_spec_default.credentialEndpointPairing.protocolAliases,
   families: aigentflow_spec_default.credentialEndpointPairing.families
 };
+var EXAMPLES = {
+  limits: aigentflow_spec_default.examples.limits,
+  idPattern: new RegExp(aigentflow_spec_default.examples.idPattern),
+  tagPattern: new RegExp(aigentflow_spec_default.examples.tagPattern),
+  sha256Pattern: new RegExp(aigentflow_spec_default.examples.sha256Pattern),
+  mediaTypePattern: new RegExp(aigentflow_spec_default.examples.mediaTypePattern),
+  // The reference writes this pattern case-insensitively (`(?i)`); the spec
+  // carries the bare expression, so the flag is applied here.
+  signedUrlQueryKeyPattern: new RegExp(aigentflow_spec_default.examples.signedUrlQueryKeyPattern, "i"),
+  origins: new Set(aigentflow_spec_default.examples.origins),
+  sideEffects: new Set(aigentflow_spec_default.examples.sideEffects),
+  statuses: new Set(aigentflow_spec_default.examples.statuses),
+  reservedRefSchemes: new Set(aigentflow_spec_default.examples.reservedRefSchemes),
+  secretPatterns: aigentflow_spec_default.examples.secretPatterns.map((p) => ({
+    name: p.name,
+    re: new RegExp(p.expr, p.flags)
+  }))};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -3203,29 +3335,29 @@ function validateField(f, schemaPath, i, seen, issues) {
     });
   }
   const stringy = INPUT_SCHEMA.stringTypes.has(type);
-  const mismatch = (constraint) => issues.error({
+  const mismatch2 = (constraint) => issues.error({
     field: `${base}.${constraint}`,
     message: `constraint '${constraint}' is not meaningful for field '${shownName}' of type '${type}'`,
     code: "input_schema_constraint_type_mismatch"
   });
   if (!stringy) {
-    if (f.min_length !== void 0) mismatch("min_length");
-    if (f.max_length !== void 0) mismatch("max_length");
-    if (pattern !== null && pattern !== "") mismatch("pattern");
+    if (f.min_length !== void 0) mismatch2("min_length");
+    if (f.max_length !== void 0) mismatch2("max_length");
+    if (pattern !== null && pattern !== "") mismatch2("pattern");
   }
   if (type !== TYPE_NUMBER) {
-    if (f.min !== void 0) mismatch("min");
-    if (f.max !== void 0) mismatch("max");
+    if (f.min !== void 0) mismatch2("min");
+    if (f.max !== void 0) mismatch2("max");
   }
   if (type !== TYPE_ARRAY_OF_STRINGS) {
-    if (f.min_items !== void 0) mismatch("min_items");
-    if (f.max_items !== void 0) mismatch("max_items");
+    if (f.min_items !== void 0) mismatch2("min_items");
+    if (f.max_items !== void 0) mismatch2("max_items");
   }
   if (type !== TYPE_FILE) {
-    if (Array.isArray(f.accept) && f.accept.length > 0) mismatch("accept");
-    if (f.max_size !== void 0) mismatch("max_size");
+    if (Array.isArray(f.accept) && f.accept.length > 0) mismatch2("accept");
+    if (f.max_size !== void 0) mismatch2("max_size");
   }
-  if (type !== TYPE_ENUM && Array.isArray(f.enum) && f.enum.length > 0) mismatch("enum");
+  if (type !== TYPE_ENUM && Array.isArray(f.enum) && f.enum.length > 0) mismatch2("enum");
   const cap = (constraint, val) => issues.error({
     field: `${base}.${constraint}`,
     message: `constraint '${constraint}' (${val}) for field '${shownName}' exceeds the maximum of ${INPUT_SCHEMA.maxConstraintValue}`,
@@ -4505,7 +4637,8 @@ function parseHost(host) {
 function parseAuthority(authority) {
   const at = authority.lastIndexOf("@");
   const host = parseHost(at < 0 ? authority : authority.slice(at + 1));
-  if (host === null || at < 0) return host;
+  if (host === null) return null;
+  if (at < 0) return { host, hasUser: false };
   const userinfo = authority.slice(0, at);
   if (!validUserinfo(userinfo)) return null;
   const colon = userinfo.indexOf(":");
@@ -4513,7 +4646,7 @@ function parseAuthority(authority) {
   for (const part of parts) {
     if (unescapeText(part, Mode.UserPassword) === null) return null;
   }
-  return host;
+  return { host, hasUser: true };
 }
 function getScheme(raw) {
   for (let i = 0; i < raw.length; i++) {
@@ -4539,28 +4672,37 @@ function containsCTL(s) {
   return false;
 }
 function goParseSchemeHost(rawURL) {
+  const u = goParseURLParts(rawURL);
+  return u === null ? null : { scheme: u.scheme, host: u.host };
+}
+function goParseURLParts(rawURL) {
   const hash = rawURL.indexOf("#");
   const main = hash < 0 ? rawURL : rawURL.slice(0, hash);
   const frag = hash < 0 ? "" : rawURL.slice(hash + 1);
   if (containsCTL(main)) return null;
-  if (main === "*") return { scheme: "", host: "" };
+  if (main === "*") {
+    return { scheme: "", host: "", hasUser: false, rawQuery: "", fragment: frag };
+  }
   const split = getScheme(main);
   if (split === null) return null;
   const scheme = split.scheme.toLowerCase();
   let rest = split.rest;
   const questionMarks = rest.split("?").length - 1;
+  let rawQuery = "";
   if (rest.endsWith("?") && questionMarks === 1) {
     rest = rest.slice(0, -1);
   } else if (questionMarks > 0) {
+    rawQuery = rest.slice(rest.indexOf("?") + 1);
     rest = rest.slice(0, rest.indexOf("?"));
   }
   if (!rest.startsWith("/")) {
-    if (scheme !== "") return finish({ scheme, host: "" }, frag);
+    if (scheme !== "") return finish({ scheme, host: "", hasUser: false, rawQuery }, frag);
     const slash = rest.indexOf("/");
     const segment = slash < 0 ? rest : rest.slice(0, slash);
     if (segment.includes(":")) return null;
   }
   let host = "";
+  let hasUser = false;
   if ((scheme !== "" || !rest.startsWith("///")) && rest.startsWith("//")) {
     let authority = rest.slice(2);
     rest = "";
@@ -4571,14 +4713,26 @@ function goParseSchemeHost(rawURL) {
     }
     const parsed = parseAuthority(authority);
     if (parsed === null) return null;
-    host = parsed;
+    host = parsed.host;
+    hasUser = parsed.hasUser;
   }
   if (unescapeText(rest, Mode.Path) === null) return null;
-  return finish({ scheme, host }, frag);
+  return finish({ scheme, host, hasUser, rawQuery }, frag);
 }
 function finish(u, frag) {
   if (frag !== "" && unescapeText(frag, Mode.Fragment) === null) return null;
-  return u;
+  return { ...u, fragment: frag };
+}
+function goQueryKeys(rawQuery) {
+  const keys = [];
+  for (const pair of rawQuery.split("&")) {
+    if (pair === "" || pair.includes(";")) continue;
+    const eq = pair.indexOf("=");
+    const rawKey = eq < 0 ? pair : pair.slice(0, eq);
+    const key = unescapeText(rawKey.replace(/\+/g, " "), Mode.Path);
+    if (key !== null) keys.push(key);
+  }
+  return keys;
 }
 function goEndpointOrigin(raw, defaultPorts, protocolSeparator) {
   const trimmed = goTrimSpace(raw);
@@ -4715,12 +4869,10 @@ function warnStoredShape(issues, field, provider) {
 function familyOf(executor) {
   const sep = executor.indexOf(CREDENTIAL_ENDPOINT_PAIRING.protocolSeparator);
   if (sep <= 0) return null;
-  let protocol = executor.slice(0, sep);
+  const protocol = executor.slice(0, sep);
   const rest = executor.slice(sep + CREDENTIAL_ENDPOINT_PAIRING.protocolSeparator.length);
   const slash = rest.indexOf("/");
   const driver = slash < 0 ? rest : rest.slice(0, slash);
-  const alias = own(CREDENTIAL_ENDPOINT_PAIRING.protocolAliases, protocol);
-  if (typeof alias === "string") protocol = alias;
   const candidates = driver === "" ? [protocol] : [protocol + CREDENTIAL_ENDPOINT_PAIRING.familyKeySeparator + driver, protocol];
   for (const key of candidates) {
     const family = own(CREDENTIAL_ENDPOINT_PAIRING.families, key);
@@ -4800,24 +4952,11 @@ function familyAuthorEndpoint(flow, family, step, issues) {
   }
   return null;
 }
-function storedShapeHasOwnKey(family, query) {
-  const shape = family.storedKeyShape;
-  if (shape === void 0) return false;
-  if (shape.ownKeyParams.some((key) => nonEmptyString(query, key) !== null)) return true;
-  return isRecord(own(query, shape.ownCredentialsMapParam));
-}
 function validateFamilies(flow, steps, issues) {
   for (const step of steps) {
     const found = familyOf(step.executor);
     if (found === null || found.family.implicitServerCredential) continue;
     const { key: familyKey, family } = found;
-    if (family.storedKeyShape !== void 0) {
-      if (storedShapeHasOwnKey(family, step.query)) continue;
-      const key = family.endpointParams.find((k) => nonEmptyEndpoint(step.query, k) !== null);
-      if (key !== void 0)
-        warnStoredShape(issues, step.field(key), family.storedKeyShape.provider);
-      continue;
-    }
     const secret = familySecret(flow, family, step, issues);
     if (secret === null || secret.envName === null) continue;
     const endpointField = familyAuthorEndpoint(flow, family, step, issues);
@@ -5052,6 +5191,1291 @@ function warnOrchestratorToolWithheld(flow, orch, report, issues) {
   }
 }
 
+// src/validators/examples.ts
+var KEY_EXAMPLES = "examples";
+var VISIBILITY_PUBLIC = "public";
+var STATUS_COMPLETED = "completed";
+var STATUS_FAILED = "failed";
+var STATUS_PAUSED_FOR_HUMAN = "paused_for_human";
+var ORIGIN_NONE = "";
+var SIDE_EFFECTS_NONE = "";
+var SCHEME_HTTPS = "https";
+var FILE_REF_KEYS = /* @__PURE__ */ new Set(["url", "sha256", "media_type", "note"]);
+var FILE_REF_KEY = "ref";
+var TYPE_SECRET = "secret";
+var TYPE_FILE2 = "file";
+var TYPE_STRING = "string";
+var TYPE_MULTILINE = "multiline";
+var TYPE_NUMBER2 = "number";
+var TYPE_BOOL = "bool";
+var TYPE_ENUM2 = "enum";
+var TYPE_ARRAY_OF_STRINGS2 = "array_of_strings";
+var TYPE_DATE = "date";
+var MAX_RECURSION_DEPTH = 32;
+var TEXTUAL_MEDIA_BASES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/xml",
+  "application/yaml",
+  "application/x-yaml",
+  "application/markdown"
+]);
+var SUGGESTION_ID = "Pick a short stable name such as standard_invoice; it is the key results are filed under, so it never changes once saved";
+var SUGGESTION_CHECKPOINT = "Did you rename the step? Update the checkpoint to the new name";
+var SUGGESTION_SECRET_VALUE = "Remove the value; you are asked for it when you run the check";
+var SUGGESTION_EXPECTED = "Add at least a rubric: one or two sentences on what a good result looks like";
+var utf8Encoder2 = new TextEncoder();
+function byteLen(s) {
+  return utf8Encoder2.encode(s).length;
+}
+function runeCount(s) {
+  let n = 0;
+  for (const _ of s) n++;
+  return n;
+}
+function q(s) {
+  let out = '"';
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    if (ch === '"') out += '\\"';
+    else if (ch === "\\") out += "\\\\";
+    else if (c === 7) out += "\\a";
+    else if (c === 8) out += "\\b";
+    else if (c === 12) out += "\\f";
+    else if (c === 10) out += "\\n";
+    else if (c === 13) out += "\\r";
+    else if (c === 9) out += "\\t";
+    else if (c === 11) out += "\\v";
+    else if (c < 32 || c === 127) out += `\\x${c.toString(16).padStart(2, "0")}`;
+    else if (c >= 128 && /[\p{C}\p{Z}]/u.test(ch)) {
+      out += c > 65535 ? `\\U${c.toString(16).padStart(8, "0")}` : `\\u${c.toString(16).padStart(4, "0")}`;
+    } else out += ch;
+  }
+  return `${out}"`;
+}
+function num(n) {
+  if (Number.isNaN(n)) return "NaN";
+  if (n === Infinity) return "+Inf";
+  if (n === -Infinity) return "-Inf";
+  if (n === 0) return Object.is(n, -0) ? "-0" : "0";
+  const [mantissa = "", exponent = "0"] = n.toExponential().split("e");
+  const exp = Number(exponent);
+  if (exp < -4 || exp >= 6) {
+    const sign = exp < 0 ? "-" : "+";
+    return `${mantissa}e${sign}${String(Math.abs(exp)).padStart(2, "0")}`;
+  }
+  return String(n);
+}
+function has(o, key) {
+  return Object.prototype.hasOwnProperty.call(o, key) && o[key] !== null && o[key] !== void 0;
+}
+function own2(o, key) {
+  return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : void 0;
+}
+function setOwn(o, key, value) {
+  Object.defineProperty(o, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true
+  });
+}
+function sortedKeys(o) {
+  return Object.keys(o).sort();
+}
+function numberOf(v) {
+  return typeof v === "number" ? v : void 0;
+}
+function normalize(v, depth) {
+  if (depth > MAX_RECURSION_DEPTH) return null;
+  if (v instanceof Date) {
+    if (Number.isNaN(v.getTime())) return null;
+    const iso = v.toISOString();
+    if (/T00:00:00\.000Z$/.test(iso)) return iso.slice(0, 10);
+    return iso.replace(/\.000Z$/, "Z");
+  }
+  if (Array.isArray(v)) return v.map((x) => normalize(x, depth + 1));
+  if (isRecord(v)) {
+    const out = {};
+    for (const k of Object.keys(v)) setOwn(out, k, normalize(v[k], depth + 1));
+    return out;
+  }
+  return v;
+}
+function deepCopy(v, depth) {
+  if (depth > MAX_RECURSION_DEPTH) return v;
+  if (Array.isArray(v)) return v.map((x) => deepCopy(x, depth + 1));
+  if (isRecord(v)) {
+    const out = {};
+    for (const k of Object.keys(v)) setOwn(out, k, deepCopy(v[k], depth + 1));
+    return out;
+  }
+  return v;
+}
+function mergePatch(target, patch, depth) {
+  if (depth > MAX_RECURSION_DEPTH) return;
+  for (const k of Object.keys(patch)) {
+    const pv = patch[k];
+    if (pv === null || pv === void 0) {
+      delete target[k];
+      continue;
+    }
+    if (isRecord(pv)) {
+      const current = own2(target, k);
+      const existing = isRecord(current) ? deepCopy(current, 0) : {};
+      mergePatch(existing, pv, depth + 1);
+      setOwn(target, k, existing);
+      continue;
+    }
+    setOwn(target, k, deepCopy(pv, 0));
+  }
+}
+function applyExamplePatch(base, patch) {
+  const out = deepCopy(base, 0);
+  mergePatch(out, patch, 0);
+  return out;
+}
+function asFileRef(v) {
+  if (!isRecord(v)) return null;
+  const keys = Object.keys(v);
+  if (keys.length === 0) return null;
+  for (const k of keys) if (!FILE_REF_KEYS.has(k)) return null;
+  const str = (k) => {
+    const x = own2(v, k);
+    return typeof x === "string" ? x : "";
+  };
+  return {
+    url: str("url"),
+    sha256: str("sha256"),
+    mediaType: str("media_type"),
+    note: str("note")
+  };
+}
+function isTextualMediaType(mediaType) {
+  const base = goToLower(goTrimSpace((mediaType.split(";")[0] ?? "").toString()));
+  if (base.startsWith("text/")) return true;
+  if (base.endsWith("+json") || base.endsWith("+xml")) return true;
+  return TEXTUAL_MEDIA_BASES.has(base);
+}
+var Walker = class _Walker {
+  constructor(flow, issues) {
+    this.flow = flow;
+    this.issues = issues;
+    this.findings = [];
+  }
+  // -- emit -------------------------------------------------------------
+  add(severity, code, field, message, suggestion) {
+    this.findings.push({
+      code,
+      severity,
+      field,
+      message,
+      ...suggestion !== void 0 ? { suggestion } : {}
+    });
+  }
+  err(code, field, message, suggestion) {
+    this.add("error", code, field, message, suggestion);
+  }
+  warn(code, field, message) {
+    this.add("warning", code, field, message);
+  }
+  /** A Go `string` field read by its source text; absent is "". */
+  s(o, key, parentPath) {
+    return this.issues.stringOf(o, key, parentPath) ?? "";
+  }
+  // -- the set ----------------------------------------------------------
+  run(examples) {
+    this.validateSet(examples);
+    const seen = /* @__PURE__ */ new Map();
+    examples.forEach((ex, i) => {
+      if (isRecord(ex)) this.validateExample(i, ex, seen);
+    });
+  }
+  validateSet(examples) {
+    const n = examples.length;
+    const L = EXAMPLES.limits;
+    if (n > L.maxPerFlow) {
+      this.err(
+        "examples_too_many",
+        KEY_EXAMPLES,
+        `flow declares ${n} examples; the limit is ${L.maxPerFlow}`
+      );
+    }
+    const size = blockBytes(examples);
+    if (size !== null && size > L.maxBlockBytes) {
+      this.err(
+        "examples_block_too_large",
+        KEY_EXAMPLES,
+        `the examples block is ${size} bytes; the limit is ${L.maxBlockBytes}. Move large inputs or target outputs to a file reference (https URL).`
+      );
+    }
+    const allHeld = examples.every((e) => isRecord(e) && own2(e, "hold_out") === true);
+    if (allHeld) {
+      this.warn(
+        "examples_all_held_out",
+        KEY_EXAMPLES,
+        "every example is held out, so nothing is left to tune on"
+      );
+    }
+    if (this.isPublic()) {
+      this.warn(
+        "examples_published_with_public_flow",
+        KEY_EXAMPLES,
+        "this flow is public, so everyone who can see it can read its examples, including their expected results. Only publish examples you are happy to show."
+      );
+    }
+  }
+  isPublic() {
+    return this.s(this.flow, "visibility", "") === VISIBILITY_PUBLIC;
+  }
+  // -- one example ------------------------------------------------------
+  validateExample(i, ex, seen) {
+    const L = EXAMPLES.limits;
+    const path = `examples[${i}]`;
+    const id = this.s(ex, "id", path);
+    const label = id === "" ? `#${i + 1}` : id;
+    if (id === "") {
+      this.err("example_id_missing", `${path}.id`, `example #${i + 1} has no id`, SUGGESTION_ID);
+    } else if (!EXAMPLES.idPattern.test(id)) {
+      this.err(
+        "example_id_invalid",
+        `${path}.id`,
+        `example id ${q(id)} is not valid: use lower-case letters, digits and underscores, starting with a letter (2 to 48 characters)`,
+        SUGGESTION_ID
+      );
+    } else {
+      const first = seen.get(id);
+      if (first !== void 0) {
+        this.err(
+          "example_id_duplicate",
+          `${path}.id`,
+          `example id ${q(id)} is used by examples #${first + 1} and #${i + 1}`
+        );
+      } else {
+        seen.set(id, i);
+      }
+    }
+    const title = this.s(ex, "title", path);
+    if (goTrimSpace(title) === "") {
+      this.err(
+        "example_title_missing",
+        `${path}.title`,
+        `example ${q(label)} has no title; the title is what a person sees in the list of examples`
+      );
+    } else {
+      const n = runeCount(title);
+      if (n > L.titleMaxRunes) {
+        this.err(
+          "example_title_too_long",
+          `${path}.title`,
+          `example ${q(label)} title is ${n} characters; the limit is ${L.titleMaxRunes}`
+        );
+      }
+    }
+    const guidance = this.s(ex, "guidance", path);
+    if (goTrimSpace(guidance) === "") {
+      this.warn(
+        "example_guidance_missing",
+        `${path}.guidance`,
+        `example ${q(label)} has no guidance. One sentence on why this case matters helps the judge and the next author.`
+      );
+    } else {
+      const n = runeCount(guidance);
+      if (n > L.maxGuidanceRunes) {
+        this.err(
+          "example_guidance_too_long",
+          `${path}.guidance`,
+          `example ${q(label)} guidance is ${n} characters; the limit is ${L.maxGuidanceRunes}`
+        );
+      }
+    }
+    const notesN = runeCount(this.s(ex, "notes", path));
+    if (notesN > L.maxNotesRunes) {
+      this.err(
+        "example_notes_too_long",
+        `${path}.notes`,
+        `example ${q(label)} notes are ${notesN} characters; the limit is ${L.maxNotesRunes}`
+      );
+    }
+    this.validateTags(path, label, own2(ex, "tags"));
+    this.validateWeight(`${path}.weight`, label, numberOf(own2(ex, "weight")));
+    const minScore = numberOf(own2(ex, "min_score"));
+    if (minScore !== void 0 && !scoreInRange(minScore)) {
+      this.err(
+        "example_min_score_range",
+        `${path}.min_score`,
+        `example ${q(label)} has min_score ${num(minScore)}; use a number from 0 to 1 (0.7 is 7.3 out of 10)`
+      );
+    }
+    const sideEffects = this.s(ex, "side_effects", path);
+    if (sideEffects !== SIDE_EFFECTS_NONE && !EXAMPLES.sideEffects.has(sideEffects)) {
+      this.err(
+        "example_side_effects_invalid",
+        `${path}.side_effects`,
+        `example ${q(label)} has side_effects ${q(sideEffects)}; use refuse or allow`
+      );
+    }
+    const holdOut = own2(ex, "hold_out") === true;
+    if (holdOut && this.isPublic()) {
+      this.err(
+        "example_holdout_in_public_flow",
+        `${path}.hold_out`,
+        `example ${q(label)} is held out but this flow is public: a held-out example must stay private, and a public flow's definition is readable by everyone. Make the flow private or remove hold_out.`
+      );
+    }
+    const hasInput = has(ex, "input");
+    const hasInputRef = has(ex, "input_ref");
+    if (hasInput && hasInputRef) {
+      this.err(
+        "example_input_conflict",
+        path,
+        `example ${q(label)} sets both input and input_ref; use exactly one`
+      );
+    } else if (!hasInput && !hasInputRef) {
+      this.err(
+        "example_input_missing",
+        path,
+        `example ${q(label)} has neither input nor input_ref; use input: {} for a flow that takes no input`
+      );
+    }
+    const rawInput = own2(ex, "input");
+    const baseInput = isRecord(rawInput) ? rawInput : null;
+    if (baseInput !== null) {
+      this.checkInput(`${path}.input`, label, baseInput, "example_input_invalid");
+    }
+    const rawInputRef = own2(ex, "input_ref");
+    if (isRecord(rawInputRef)) {
+      this.validateFileRef(`${path}.input_ref`, this.fileRefOf(rawInputRef, `${path}.input_ref`));
+    }
+    let binaryOnly = false;
+    const expected = own2(ex, "expected");
+    if (!has(ex, "expected")) {
+      this.err(
+        "example_expected_missing",
+        `${path}.expected`,
+        `example ${q(label)} does not say what a good result is: add a rubric, fields, exact or reference`,
+        SUGGESTION_EXPECTED
+      );
+    } else if (isRecord(expected)) {
+      this.validateExpectation(`${path}.expected`, label, expected, "final", "");
+      binaryOnly = this.expectationIsBinaryReferenceOnly(expected, `${path}.expected`);
+    }
+    if (binaryOnly) {
+      this.warn(
+        "examples_unreadable_by_judge",
+        `${path}.expected`,
+        "this example can be run but not scored"
+      );
+    }
+    this.validateCheckpoints(path, label, own2(ex, "checkpoints"));
+    this.validateVariants(i, path, label, ex, hasInput, baseInput);
+    this.scanSecretLike(i, path, ex);
+  }
+  validateTags(path, label, tags) {
+    if (!Array.isArray(tags)) return;
+    if (tags.length > EXAMPLES.limits.maxTags) {
+      this.err(
+        "example_tag_invalid",
+        `${path}.tags`,
+        `example ${q(label)} has ${tags.length} tags; the limit is ${EXAMPLES.limits.maxTags}`
+      );
+    }
+    const seen = /* @__PURE__ */ new Set();
+    tags.forEach((item, j) => {
+      const field = `${path}.tags[${j}]`;
+      const tag = item === null ? "" : this.issues.stringAt(item, field) ?? null;
+      if (tag === null) return;
+      if (!EXAMPLES.tagPattern.test(tag)) {
+        this.err("example_tag_invalid", field, `example ${q(label)} has an invalid tag ${q(tag)}`);
+      } else if (seen.has(tag)) {
+        this.err(
+          "example_tag_invalid",
+          field,
+          `example ${q(label)} lists the tag ${q(tag)} more than once`
+        );
+      }
+      seen.add(tag);
+    });
+  }
+  validateWeight(field, label, weight) {
+    if (weight === void 0) return;
+    if (Number.isNaN(weight) || weight <= 0 || weight > EXAMPLES.limits.weightMax) {
+      this.err(
+        "example_weight_range",
+        field,
+        `example ${q(label)} has weight ${num(weight)}; use a number above 0 and at most 10`
+      );
+    }
+  }
+  // -- input ------------------------------------------------------------
+  /**
+   * Judge one inline input map (an example's `input`, or a variant's patched
+   * input). NARROWED relative to the reference, which runs its full value
+   * validator: here an unknown field, a missing required field, a value of the
+   * wrong KIND and an enum value outside its list are judged; length, range,
+   * pattern and date-format constraints are not (PARITY.md).
+   */
+  checkInput(field, label, raw, code) {
+    const input = normalize(raw, 0) ?? {};
+    const L = EXAMPLES.limits;
+    const size = jsonBytes(input);
+    if (size !== null && size > L.maxInlineInputBytes) {
+      this.err(
+        "example_input_too_large",
+        field,
+        `example ${q(label)} input is ${size} bytes; the limit is ${L.maxInlineInputBytes}. Put the large part behind an https file reference.`
+      );
+      return;
+    }
+    const schema = own2(this.flow, "input_schema");
+    const query = own2(this.flow, "query");
+    if (isRecord(schema)) {
+      this.checkInputAgainstSchema(field, label, input, schema, code);
+    } else if (isRecord(query) && Object.keys(query).length > 0) {
+      const declared = sortedKeys(query);
+      for (const k of sortedKeys(input)) {
+        if (!Object.prototype.hasOwnProperty.call(query, k)) {
+          this.err(
+            code,
+            `${field}.${k}`,
+            `example ${q(label)}: ${q(k)} is not a declared input of this flow (declared: ${declared.join(", ")})`
+          );
+        }
+      }
+    } else {
+      this.warn(
+        "example_input_unvalidated",
+        field,
+        `example ${q(label)} cannot be checked: the flow declares no input_schema and no query parameters.`
+      );
+    }
+  }
+  checkInputAgainstSchema(field, label, input, schema, code) {
+    const fields = this.schemaFields(schema);
+    const byName = /* @__PURE__ */ new Map();
+    for (const f of fields) byName.set(f.name, f);
+    const runInput = {};
+    for (const name of sortedKeys(input)) {
+      const val = input[name];
+      const f = byName.get(name);
+      const present = val !== null && val !== void 0;
+      if (f !== void 0 && f.type === TYPE_SECRET) {
+        if (present) {
+          this.err(
+            "example_secret_value",
+            `${field}.${name}`,
+            `example ${q(label)} gives a value for ${q(name)}, which is a secret field. Examples are saved inside the flow and are never allowed to hold secrets; remove it. The person running the evaluation is asked for it at run time.`,
+            SUGGESTION_SECRET_VALUE
+          );
+        }
+        continue;
+      }
+      if (f !== void 0 && f.type === TYPE_FILE2 && present) {
+        const ref = asFileRef(val);
+        if (ref === null) {
+          this.err(
+            "example_file_input_needs_ref",
+            `${field}.${name}`,
+            `example ${q(label)}: field ${q(name)} is a file; give it as {url: "https://\u2026"}. A pasted upload id would stop working as soon as the session ends.`
+          );
+          continue;
+        }
+        this.validateFileRef(`${field}.${name}`, ref);
+        setOwn(runInput, name, { [FILE_REF_KEY]: ref.url });
+        continue;
+      }
+      setOwn(runInput, name, val);
+    }
+    for (const failure of this.judgeRun(fields, byName, runInput)) {
+      if (failure.required) {
+        const f = byName.get(failure.field);
+        if (f !== void 0 && f.type === TYPE_SECRET) continue;
+      }
+      const at = failure.field !== "" ? `${field}.${failure.field}` : field;
+      this.err(code, at, `example ${q(label)}: ${failure.message}`);
+    }
+  }
+  schemaFields(schema) {
+    const raw = own2(schema, "fields");
+    if (!Array.isArray(raw)) return [];
+    const out = [];
+    raw.forEach((f, i) => {
+      if (!isRecord(f)) return;
+      const base = `input_schema.fields[${i}]`;
+      const enumRaw = own2(f, "enum");
+      const enumValues = [];
+      if (Array.isArray(enumRaw)) {
+        enumRaw.forEach((e, j) => {
+          enumValues.push(e === null ? "" : this.issues.stringAt(e, `${base}.enum[${j}]`) ?? "");
+        });
+      }
+      const vw = own2(f, "visible_when");
+      out.push({
+        name: this.s(f, "name", base),
+        type: this.s(f, "type", base),
+        required: own2(f, "required") === true,
+        enumValues,
+        visibleWhen: isRecord(vw) ? {
+          field: this.s(vw, "field", `${base}.visible_when`),
+          equals: own2(vw, "equals"),
+          in: Array.isArray(own2(vw, "in")) ? own2(vw, "in") : []
+        } : null
+      });
+    });
+    return out;
+  }
+  /** The narrowed run-time judgement: required, kind, enum, unknown field. */
+  judgeRun(fields, byName, runInput) {
+    const failures = [];
+    for (const f of fields) {
+      if (!isVisible(f, runInput)) continue;
+      const raw = own2(runInput, f.name);
+      if (raw === void 0 || raw === null) {
+        if (f.required) {
+          failures.push({
+            field: f.name,
+            message: `input field ${q(f.name)} is required`,
+            required: true
+          });
+        }
+        continue;
+      }
+      failures.push(...inputValueFailures(f, raw));
+    }
+    for (const k of sortedKeys(runInput)) {
+      if (!byName.has(k)) {
+        failures.push({
+          field: k,
+          message: `input field ${q(k)} is not declared in input_schema`,
+          required: false
+        });
+      }
+    }
+    return failures;
+  }
+  // -- file reference ---------------------------------------------------
+  fileRefOf(rec, path) {
+    return {
+      url: this.s(rec, "url", path),
+      sha256: this.s(rec, "sha256", path),
+      mediaType: this.s(rec, "media_type", path),
+      note: this.s(rec, "note", path)
+    };
+  }
+  validateFileRef(field, ref) {
+    const L = EXAMPLES.limits;
+    const raw = ref.url;
+    const invalid = "the file reference needs a url of at most 2048 characters";
+    if (raw === "" || byteLen(raw) > L.maxUrlBytes) {
+      this.err("example_ref_invalid", field, invalid);
+      return;
+    }
+    const u = goParseURLParts(raw);
+    if (u === null) {
+      this.err("example_ref_invalid", field, invalid);
+      return;
+    }
+    const scheme = u.scheme.toLowerCase();
+    if (EXAMPLES.reservedRefSchemes.has(scheme)) {
+      this.err(
+        "example_ref_scheme_reserved",
+        field,
+        `${scheme}: references are not available yet. Use an https URL, or paste the text into the example.`
+      );
+      return;
+    }
+    if (scheme !== SCHEME_HTTPS) {
+      this.err(
+        "example_ref_scheme",
+        field,
+        `only https:// references are allowed (got ${q(scheme)})`
+      );
+      return;
+    }
+    if (u.hasUser || u.fragment !== "" || raw.includes("#") || u.host === "") {
+      this.err("example_ref_invalid", field, "a reference must not carry a login or a fragment");
+      return;
+    }
+    if (ref.sha256 !== "" && !EXAMPLES.sha256Pattern.test(ref.sha256)) {
+      this.err(
+        "example_ref_sha256_invalid",
+        field,
+        "sha256 must be 64 lowercase hexadecimal characters"
+      );
+    }
+    if (ref.mediaType !== "" && !EXAMPLES.mediaTypePattern.test(ref.mediaType)) {
+      this.err(
+        "example_ref_media_type_invalid",
+        field,
+        `media_type ${q(ref.mediaType)} must look like type/subtype`
+      );
+    }
+    const noteN = runeCount(ref.note);
+    if (noteN > L.maxNoteRunes) {
+      this.err(
+        "example_ref_invalid",
+        field,
+        `the note is ${noteN} characters; the limit is ${L.maxNoteRunes}`
+      );
+    }
+    if (ref.sha256 === "") {
+      this.warn(
+        "example_ref_unpinned",
+        field,
+        "this reference is not pinned. If the file at that address changes, your scores change with it. Add sha256 to freeze it."
+      );
+    }
+    for (const key of goQueryKeys(u.rawQuery)) {
+      if (EXAMPLES.signedUrlQueryKeyPattern.test(key)) {
+        this.warn(
+          "example_ref_signed_url",
+          field,
+          "this address looks like a signed link. Anyone who can read the flow can use it until it expires, and it will stop working. Prefer a stable public address."
+        );
+        break;
+      }
+    }
+  }
+  // -- expectation ------------------------------------------------------
+  /** The names `fields` / `exact` may use, and whether such a list is declared at all. */
+  outputNamesFor(kind, stepId) {
+    if (kind === "final") {
+      const out = own2(this.flow, "output");
+      const names2 = [];
+      if (Array.isArray(out)) {
+        out.forEach((item, i) => {
+          names2.push(item === null ? "" : this.issues.stringAt(item, `output[${i}]`) ?? "");
+        });
+      }
+      return { names: names2, declared: names2.length > 0 };
+    }
+    const steps = own2(this.flow, "steps");
+    const step = isRecord(steps) ? own2(steps, stepId) : void 0;
+    const schema = isRecord(step) ? own2(step, "output_schema") : void 0;
+    const fields = isRecord(schema) ? own2(schema, "fields") : void 0;
+    if (!Array.isArray(fields) || fields.length === 0) return { names: [], declared: false };
+    const names = [];
+    fields.forEach((f, i) => {
+      if (isRecord(f)) names.push(this.s(f, "name", `steps.${stepId}.output_schema.fields[${i}]`));
+    });
+    return { names, declared: true };
+  }
+  validateExpectation(path, label, e, kind, stepId) {
+    const L = EXAMPLES.limits;
+    const status = this.s(e, "status", path);
+    if (status !== "" && !EXAMPLES.statuses.has(status)) {
+      this.err(
+        "example_status_invalid",
+        `${path}.status`,
+        "status must be completed, failed or paused_for_human"
+      );
+    }
+    const noOutput = status === STATUS_FAILED || status === STATUS_PAUSED_FOR_HUMAN;
+    const fieldsRec = own2(e, "fields");
+    const exactRec = own2(e, "exact");
+    const fieldKeys = isRecord(fieldsRec) ? sortedKeys(fieldsRec) : [];
+    const exactKeys = isRecord(exactRec) ? sortedKeys(exactRec) : [];
+    const hasFields = fieldKeys.length > 0;
+    const hasExact = exactKeys.length > 0;
+    if (hasFields && hasExact) {
+      this.err(
+        "example_expected_conflict",
+        path,
+        "use fields (some fields) or exact (the whole result), not both"
+      );
+    } else if (noOutput && (hasFields || hasExact)) {
+      this.err(
+        "example_expected_conflict",
+        path,
+        `a case that ends in ${status} has no output to match; remove fields and exact, or expect status completed`
+      );
+    }
+    const minScore = numberOf(own2(e, "min_score"));
+    if (minScore !== void 0 && !scoreInRange(minScore)) {
+      this.err(
+        "example_min_score_range",
+        `${path}.min_score`,
+        `min_score ${num(minScore)} is out of range; use a number from 0 to 1`
+      );
+    }
+    const rubric = this.s(e, "rubric", path);
+    if (rubric !== "") {
+      if (goTrimSpace(rubric) === "") {
+        this.err(
+          "example_rubric_empty",
+          `${path}.rubric`,
+          "the rubric is empty; write what a good result looks like, or remove it"
+        );
+      } else {
+        const n = runeCount(rubric);
+        if (n > L.maxRubricRunes) {
+          this.err(
+            "example_rubric_too_long",
+            `${path}.rubric`,
+            `the rubric is ${n} characters; the limit is ${L.maxRubricRunes}`
+          );
+        }
+      }
+    }
+    const reference = own2(e, "reference");
+    if (isRecord(reference)) this.validateReference(`${path}.reference`, reference);
+    const { names, declared } = this.outputNamesFor(kind, stepId);
+    const checkKey = (field, key) => {
+      if (!declared && kind === "final") {
+        this.warn(
+          "example_expected_field_unchecked",
+          field,
+          `this flow declares no output list, so ${q(key)} cannot be checked against it`
+        );
+      } else if (!declared) {
+        this.warn(
+          "example_expected_field_unchecked",
+          field,
+          `this step declares no output_schema, so ${q(key)} cannot be checked against it`
+        );
+      } else if (!names.includes(key)) {
+        this.err(
+          "example_expected_field_unknown",
+          field,
+          kind === "checkpoint" ? `${q(key)} is not a field this step declares in its output_schema (declared: ${names.join(", ")})` : `${q(key)} is not an output of this flow (outputs: ${names.join(", ")})`
+        );
+      }
+    };
+    for (const key of fieldKeys) {
+      const fpath = `${path}.fields.${key}`;
+      checkKey(fpath, key);
+      const matcher = own2(fieldsRec, key);
+      if (isRecord(matcher)) this.validateFieldMatcher(fpath, matcher);
+    }
+    for (const key of exactKeys) checkKey(`${path}.exact.${key}`, key);
+    const mustNot = this.stringList(own2(e, "must_not"), `${path}.must_not`);
+    const mustNotContain = this.stringList(own2(e, "must_not_contain"), `${path}.must_not_contain`);
+    const mustNotMsg = `must_not takes up to ${L.maxMustNot} statements of at most ${L.maxMustNotRunes} characters each, none empty`;
+    if (mustNot.length > L.maxMustNot) {
+      this.err("example_must_not_invalid", `${path}.must_not`, mustNotMsg);
+    }
+    mustNot.forEach((item, j) => {
+      if (goTrimSpace(item) === "" || runeCount(item) > L.maxMustNotRunes) {
+        this.err("example_must_not_invalid", `${path}.must_not[${j}]`, mustNotMsg);
+      }
+    });
+    const mncMsg = `must_not_contain takes up to ${L.maxMustNotContain} literals of 1 to ${L.maxMustNotContainLength} characters each`;
+    if (mustNotContain.length > L.maxMustNotContain) {
+      this.err("example_must_not_contain_invalid", `${path}.must_not_contain`, mncMsg);
+    }
+    mustNotContain.forEach((item, j) => {
+      const n = runeCount(item);
+      if (n === 0 || n > L.maxMustNotContainLength) {
+        this.err("example_must_not_contain_invalid", `${path}.must_not_contain[${j}]`, mncMsg);
+      }
+    });
+    for (const key of fieldKeys) {
+      const matcher = own2(fieldsRec, key);
+      if (!isRecord(matcher)) continue;
+      const eq = own2(matcher, "equals");
+      if (typeof eq !== "string" || eq === "") continue;
+      for (const banned of mustNotContain) {
+        if (banned !== "" && equalFold(banned, eq)) {
+          this.warn(
+            "example_expectation_contradiction",
+            `${path}.fields.${key}`,
+            `${q(banned)} is required by ${q(key)} and forbidden by must_not_contain`
+          );
+        }
+      }
+    }
+    if (kind === "checkpoint" && status !== "") {
+      this.err(
+        "example_checkpoint_status",
+        `${path}.status`,
+        `example ${q(label)}: a checkpoint cannot set status; status describes how the whole run ends`
+      );
+    }
+    if (rubric === "" && !has(e, "reference") && !hasFields && !hasExact && mustNot.length === 0 && mustNotContain.length === 0 && (status === "" || status === STATUS_COMPLETED)) {
+      this.err(
+        "example_expected_empty",
+        path,
+        "this expectation checks nothing; add a rubric, fields, exact, reference, must_not or must_not_contain",
+        SUGGESTION_EXPECTED
+      );
+    }
+  }
+  /** A Go `[]string` read: scalars by their text, null as "", anything else dropped. */
+  stringList(v, path) {
+    if (!Array.isArray(v)) return [];
+    const out = [];
+    v.forEach((item, j) => {
+      if (item === null) out.push("");
+      else {
+        const t = this.issues.stringAt(item, `${path}[${j}]`);
+        if (t !== null) out.push(t);
+      }
+    });
+    return out;
+  }
+  validateReference(path, r) {
+    const text = this.s(r, "text", path);
+    const hasText = text !== "";
+    const hasRef = has(r, "ref");
+    if (hasText === hasRef) {
+      this.err("example_reference_invalid", path, "a reference needs exactly one of text or ref");
+      return;
+    }
+    if (hasText) {
+      const n = byteLen(text);
+      if (n > EXAMPLES.limits.maxReferenceTextBytes) {
+        this.err(
+          "example_reference_invalid",
+          path,
+          `the reference text is ${n} bytes; the limit is ${EXAMPLES.limits.maxReferenceTextBytes}. Put it behind an https file reference.`
+        );
+      }
+      return;
+    }
+    const refRec = own2(r, "ref");
+    if (!isRecord(refRec)) return;
+    const ref = this.fileRefOf(refRec, `${path}.ref`);
+    this.validateFileRef(`${path}.ref`, ref);
+    if (ref.mediaType !== "" && !isTextualMediaType(ref.mediaType)) {
+      this.warn(
+        "example_reference_binary",
+        path,
+        "this reference is not text, so it cannot be compared in this version; the example will be skipped, not failed."
+      );
+    }
+  }
+  expectationIsBinaryReferenceOnly(e, path) {
+    const reference = own2(e, "reference");
+    const refRec = isRecord(reference) ? own2(reference, "ref") : void 0;
+    if (!isRecord(refRec)) return false;
+    const mediaType = this.s(refRec, "media_type", `${path}.reference.ref`);
+    if (mediaType === "" || isTextualMediaType(mediaType)) return false;
+    const status = this.s(e, "status", path);
+    const fields = own2(e, "fields");
+    const exact = own2(e, "exact");
+    return this.s(e, "rubric", path) === "" && !(isRecord(fields) && Object.keys(fields).length > 0) && !(isRecord(exact) && Object.keys(exact).length > 0) && this.stringList(own2(e, "must_not"), `${path}.must_not`).length === 0 && this.stringList(own2(e, "must_not_contain"), `${path}.must_not_contain`).length === 0 && (status === "" || status === STATUS_COMPLETED);
+  }
+  validateFieldMatcher(path, m) {
+    const L = EXAMPLES.limits;
+    const matches = this.s(m, "matches", path);
+    const oneOf = own2(m, "one_of");
+    const approx = numberOf(own2(m, "approx"));
+    const tolerance = numberOf(own2(m, "tolerance"));
+    let operators = 0;
+    if (has(m, "equals")) operators++;
+    if (this.s(m, "contains", path) !== "") operators++;
+    if (this.s(m, "not_contains", path) !== "") operators++;
+    if (matches !== "") operators++;
+    if (Array.isArray(oneOf) && oneOf.length > 0) operators++;
+    if (approx !== void 0) operators++;
+    if (typeof own2(m, "present") === "boolean") operators++;
+    if (operators !== 1) {
+      this.err(
+        "example_field_matcher_invalid",
+        path,
+        "write exactly one of equals, contains, not_contains, matches, one_of, approx, present"
+      );
+      return;
+    }
+    if (matches !== "" && byteLen(matches) > L.maxPatternLength) {
+      this.err(
+        "example_field_matcher_invalid",
+        path,
+        `the pattern in matches must be a valid regular expression of at most ${L.maxPatternLength} characters`
+      );
+    }
+    if (approx !== void 0 !== (tolerance !== void 0) || tolerance !== void 0 && (Number.isNaN(tolerance) || tolerance < 0)) {
+      this.err(
+        "example_field_matcher_invalid",
+        path,
+        "approx needs a tolerance (a number, zero or more) beside it, and tolerance is only for approx"
+      );
+    }
+  }
+  // -- checkpoints ------------------------------------------------------
+  validateCheckpoints(path, label, cps) {
+    if (!isRecord(cps) || Object.keys(cps).length === 0) return;
+    const stepsRaw = own2(this.flow, "steps");
+    const steps = isRecord(stepsRaw) ? stepsRaw : {};
+    const stepIds = sortedKeys(steps);
+    for (const id of sortedKeys(cps)) {
+      const cpath = `${path}.checkpoints.${id}`;
+      const step = own2(steps, id);
+      if (!isRecord(step)) {
+        this.err(
+          "example_checkpoint_step_unknown",
+          cpath,
+          `example ${q(label)}: checkpoint ${q(id)} is not a step of this flow (steps: ${stepIds.join(", ")})`,
+          SUGGESTION_CHECKPOINT
+        );
+        continue;
+      }
+      const next = own2(step, "next");
+      if (has(step, "for_each") || has(step, "loop") || isRecord(next) && has(next, "parallel")) {
+        this.err(
+          "example_checkpoint_step_composite",
+          cpath,
+          `example ${q(label)}: step ${q(id)} repeats or branches, so there is no single result to check; put the checkpoint on a plain step or check the final output`
+        );
+        continue;
+      }
+      const cp = own2(cps, id);
+      if (cp === null || cp === void 0) {
+        this.validateExpectation(cpath, label, {}, "checkpoint", id);
+      } else if (isRecord(cp)) {
+        this.validateExpectation(cpath, label, cp, "checkpoint", id);
+      }
+    }
+  }
+  // -- variants ---------------------------------------------------------
+  validateVariants(i, path, label, ex, hasInput, baseInput) {
+    const L = EXAMPLES.limits;
+    const variants = own2(ex, "variants");
+    if (!Array.isArray(variants) || variants.length === 0) return;
+    if (variants.length > L.maxVariants) {
+      this.err(
+        "example_variants_too_many",
+        `${path}.variants`,
+        `example ${q(label)} has ${variants.length} variants; the limit is ${L.maxVariants}`
+      );
+    }
+    const seen = /* @__PURE__ */ new Set();
+    variants.forEach((v, j) => {
+      if (!isRecord(v)) return;
+      const vpath = `examples[${i}].variants[${j}]`;
+      const vid = this.s(v, "id", vpath);
+      const vlabel = vid === "" ? `#${j + 1}` : vid;
+      const both = `${label}/${vlabel}`;
+      if (!EXAMPLES.idPattern.test(vid)) {
+        this.err(
+          "example_variant_id_invalid",
+          `${vpath}.id`,
+          `variant id ${q(vid)} of example ${q(label)} is not valid: use lower-case letters, digits and underscores, starting with a letter (2 to 48 characters)`,
+          SUGGESTION_ID
+        );
+      } else if (seen.has(vid)) {
+        this.err(
+          "example_variant_id_duplicate",
+          `${vpath}.id`,
+          `variant id ${q(vid)} is used twice in example ${q(label)}`
+        );
+      }
+      seen.add(vid);
+      const origin = this.s(v, "origin", vpath);
+      if (origin === ORIGIN_NONE || !EXAMPLES.origins.has(origin)) {
+        this.err(
+          "example_variant_origin_invalid",
+          `${vpath}.origin`,
+          `variant ${q(vlabel)} of example ${q(label)} has origin ${q(origin)}; use author (a person wrote or approved it) or synthetic (generated)`
+        );
+      }
+      const vtitleN = runeCount(this.s(v, "title", vpath));
+      if (vtitleN > L.titleMaxRunes) {
+        this.err(
+          "example_title_too_long",
+          `${vpath}.title`,
+          `example ${q(both)} title is ${vtitleN} characters; the limit is ${L.titleMaxRunes}`
+        );
+      }
+      const vguidanceN = runeCount(this.s(v, "guidance", vpath));
+      if (vguidanceN > L.maxGuidanceRunes) {
+        this.err(
+          "example_guidance_too_long",
+          `${vpath}.guidance`,
+          `example ${q(both)} guidance is ${vguidanceN} characters; the limit is ${L.maxGuidanceRunes}`
+        );
+      }
+      const provN = runeCount(this.s(v, "provenance", vpath));
+      if (provN > L.maxProvenanceRunes) {
+        this.err(
+          "example_notes_too_long",
+          `${vpath}.provenance`,
+          `example ${q(both)} notes are ${provN} characters; the limit is ${L.maxProvenanceRunes}`
+        );
+      }
+      this.validateWeight(`${vpath}.weight`, both, numberOf(own2(v, "weight")));
+      const patch = own2(v, "input_patch");
+      const patchRec = isRecord(patch) ? patch : null;
+      const hasPatch = patchRec !== null && Object.keys(patchRec).length > 0;
+      const hasRef = has(v, "input_ref");
+      if (hasPatch && hasRef) {
+        this.err(
+          "example_variant_input_conflict",
+          vpath,
+          `variant ${q(vlabel)} of example ${q(label)} sets both input_patch and input_ref; use one`
+        );
+      } else if (!hasPatch && !hasRef && !has(v, "expected")) {
+        this.err(
+          "example_variant_empty",
+          vpath,
+          `variant ${q(vlabel)} of example ${q(label)} changes neither the input nor the expectation`
+        );
+      }
+      const refRec = own2(v, "input_ref");
+      if (isRecord(refRec)) {
+        this.validateFileRef(`${vpath}.input_ref`, this.fileRefOf(refRec, `${vpath}.input_ref`));
+      }
+      if (hasPatch && patchRec !== null) {
+        if (!hasInput) {
+          this.warn(
+            "example_variant_unchecked",
+            `${vpath}.input_patch`,
+            `variant ${q(vlabel)} of example ${q(label)} cannot be checked: its parent takes its input from input_ref.`
+          );
+        } else if (baseInput !== null) {
+          this.checkVariantPatch(vpath, label, vlabel, baseInput, patchRec);
+        }
+      }
+      const expected = own2(v, "expected");
+      if (isRecord(expected)) {
+        this.validateExpectation(`${vpath}.expected`, both, expected, "final", "");
+      }
+    });
+  }
+  /**
+   * Judge the PATCHED input like a live run, and report a secret the patch
+   * itself supplies. A null patch value deleting a secret is fine.
+   */
+  checkVariantPatch(vpath, label, vlabel, base, patch) {
+    const schema = own2(this.flow, "input_schema");
+    if (isRecord(schema)) {
+      for (const f of this.schemaFields(schema)) {
+        if (f.type !== TYPE_SECRET) continue;
+        const val = own2(patch, f.name);
+        if (val !== void 0 && val !== null) {
+          this.err(
+            "example_secret_value",
+            `${vpath}.input_patch.${f.name}`,
+            `example ${q(`${label}/${vlabel}`)} gives a value for ${q(f.name)}, which is a secret field. Examples are saved inside the flow and are never allowed to hold secrets; remove it. The person running the evaluation is asked for it at run time.`,
+            SUGGESTION_SECRET_VALUE
+          );
+        }
+      }
+    }
+    const patched = applyExamplePatch(base, patch);
+    const scratch = new _Walker(this.flow, this.issues);
+    scratch.checkInput(
+      `${vpath}.input_patch`,
+      `${label}/${vlabel}`,
+      patched,
+      "example_variant_input_invalid"
+    );
+    for (const f of scratch.findings) {
+      if (f.code === "example_secret_value") continue;
+      this.findings.push(f);
+    }
+  }
+  // -- credential-shaped literals ----------------------------------------
+  scanSecretLike(i, path, ex) {
+    const emit = (field, s) => {
+      const name = secretMatch(s);
+      if (name !== "") {
+        this.err(
+          "example_secret_like_value",
+          field,
+          `${field} looks like a credential (${name}). Examples are saved in the flow definition and must never contain keys or tokens. Replace it with a made-up value.`,
+          SUGGESTION_SECRET_VALUE
+        );
+      }
+    };
+    emit(`${path}.title`, this.s(ex, "title", path));
+    emit(`${path}.guidance`, this.s(ex, "guidance", path));
+    emit(`${path}.notes`, this.s(ex, "notes", path));
+    const input = own2(ex, "input");
+    if (isRecord(input)) scanLeaves(`${path}.input`, input, 0, emit);
+    const expected = own2(ex, "expected");
+    if (isRecord(expected)) this.scanExpectationLeaves(`${path}.expected`, expected, emit);
+    const cps = own2(ex, "checkpoints");
+    if (isRecord(cps)) {
+      for (const id of sortedKeys(cps)) {
+        const cp = own2(cps, id);
+        if (isRecord(cp)) this.scanExpectationLeaves(`${path}.checkpoints.${id}`, cp, emit);
+      }
+    }
+    const variants = own2(ex, "variants");
+    if (Array.isArray(variants)) {
+      variants.forEach((v, j) => {
+        if (!isRecord(v)) return;
+        const vpath = `examples[${i}].variants[${j}]`;
+        emit(`${vpath}.title`, this.s(v, "title", vpath));
+        emit(`${vpath}.guidance`, this.s(v, "guidance", vpath));
+        emit(`${vpath}.provenance`, this.s(v, "provenance", vpath));
+        scanLeaves(`${vpath}.input_patch`, own2(v, "input_patch"), 0, emit);
+        const vexp = own2(v, "expected");
+        if (isRecord(vexp)) this.scanExpectationLeaves(`${vpath}.expected`, vexp, emit);
+      });
+    }
+  }
+  scanExpectationLeaves(path, e, emit) {
+    emit(`${path}.rubric`, this.s(e, "rubric", path));
+    const reference = own2(e, "reference");
+    if (isRecord(reference)) {
+      emit(`${path}.reference.text`, this.s(reference, "text", `${path}.reference`));
+    }
+    this.stringList(own2(e, "must_not"), `${path}.must_not`).forEach(
+      (s, j) => emit(`${path}.must_not[${j}]`, s)
+    );
+    this.stringList(own2(e, "must_not_contain"), `${path}.must_not_contain`).forEach(
+      (s, j) => emit(`${path}.must_not_contain[${j}]`, s)
+    );
+    const fields = own2(e, "fields");
+    if (isRecord(fields)) {
+      for (const key of sortedKeys(fields)) {
+        const m = own2(fields, key);
+        if (!isRecord(m)) continue;
+        const fpath = `${path}.fields.${key}`;
+        scanLeaves(`${fpath}.equals`, own2(m, "equals"), 0, emit);
+        emit(`${fpath}.contains`, this.s(m, "contains", fpath));
+        emit(`${fpath}.not_contains`, this.s(m, "not_contains", fpath));
+        const oneOf = own2(m, "one_of");
+        if (Array.isArray(oneOf)) {
+          oneOf.forEach(
+            (one, j) => scanLeaves(`${fpath}.one_of[${j}]`, one, 0, emit)
+          );
+        }
+      }
+    }
+    scanLeaves(`${path}.exact`, own2(e, "exact"), 0, emit);
+  }
+};
+function scoreInRange(v) {
+  return !Number.isNaN(v) && v >= EXAMPLES.limits.minScoreMin && v <= EXAMPLES.limits.minScoreMax;
+}
+function equalFold(a, b) {
+  const ca = [...a];
+  const cb = [...b];
+  if (ca.length !== cb.length) return false;
+  return ca.every((c, i) => {
+    const d = cb[i];
+    return c === d || c.toLowerCase() === d.toLowerCase() || c.toUpperCase() === d.toUpperCase();
+  });
+}
+function secretMatch(s) {
+  for (const p of EXAMPLES.secretPatterns) {
+    if (p.re.test(s)) return p.name;
+  }
+  return "";
+}
+function scanLeaves(path, v, depth, emit) {
+  if (depth > MAX_RECURSION_DEPTH) return;
+  if (isRecord(v)) {
+    for (const k of sortedKeys(v)) scanLeaves(`${path}.${k}`, v[k], depth + 1, emit);
+    return;
+  }
+  if (typeof v === "string") emit(path, v);
+  else if (Array.isArray(v)) {
+    v.forEach((item, i) => scanLeaves(`${path}[${i}]`, item, depth + 1, emit));
+  }
+}
+function jsonBytes(v) {
+  try {
+    const text = JSON.stringify(v);
+    return text === void 0 ? null : byteLen(text);
+  } catch {
+    return null;
+  }
+}
+function blockBytes(examples) {
+  try {
+    const text = JSON.stringify(normalize(examples, 0), function(_k, v) {
+      if (Array.isArray(this)) return v;
+      if (v === null || v === "" || v === false) return void 0;
+      if (Array.isArray(v) && v.length === 0) return void 0;
+      return v;
+    });
+    return text === void 0 ? null : byteLen(text);
+  } catch {
+    return null;
+  }
+}
+function isVisible(f, input) {
+  const vw = f.visibleWhen;
+  if (vw === null) return true;
+  if (!Object.prototype.hasOwnProperty.call(input, vw.field)) return false;
+  const dep = input[vw.field];
+  if (vw.equals !== void 0 && vw.equals !== null) return valuesEqual(dep, vw.equals);
+  return vw.in.some((candidate) => valuesEqual(dep, candidate));
+}
+function valuesEqual(a, b) {
+  const aNil = a === null || a === void 0;
+  const bNil = b === null || b === void 0;
+  if (aNil || bNil) return aNil && bNil;
+  if (typeof a === "number") return typeof b === "number" && a === b;
+  if (typeof a === "boolean") return typeof b === "boolean" && a === b;
+  if (typeof a === "string") return typeof b === "string" && a === b;
+  return false;
+}
+function mismatch(f, expected) {
+  return {
+    field: f.name,
+    message: `input field ${q(f.name)} is not a valid ${expected}`,
+    required: false
+  };
+}
+function inputValueFailures(f, raw) {
+  switch (f.type) {
+    case TYPE_STRING:
+    case TYPE_MULTILINE:
+    case TYPE_SECRET:
+      return typeof raw === "string" ? [] : [mismatch(f, TYPE_STRING)];
+    case TYPE_NUMBER2:
+      return typeof raw === "number" ? [] : [mismatch(f, TYPE_NUMBER2)];
+    case TYPE_BOOL:
+      return typeof raw === "boolean" ? [] : [mismatch(f, TYPE_BOOL)];
+    case TYPE_ENUM2:
+      if (typeof raw !== "string") return [mismatch(f, TYPE_ENUM2)];
+      if (f.enumValues.includes(raw)) return [];
+      return [
+        {
+          field: f.name,
+          message: `input field ${q(f.name)} value ${q(raw)} is not one of [${f.enumValues.join(",")}]`,
+          required: false
+        }
+      ];
+    case TYPE_ARRAY_OF_STRINGS2: {
+      if (!Array.isArray(raw)) return [mismatch(f, TYPE_ARRAY_OF_STRINGS2)];
+      const out = [];
+      raw.forEach((item, i) => {
+        if (typeof item !== "string") {
+          out.push({
+            field: f.name,
+            message: `input field ${q(f.name)} index ${i} is not a string`,
+            required: false
+          });
+        }
+      });
+      return out;
+    }
+    case TYPE_DATE:
+      return typeof raw === "string" ? [] : [mismatch(f, TYPE_DATE)];
+    case TYPE_FILE2: {
+      if (typeof raw === "string") return raw === "" ? [mismatch(f, TYPE_FILE2)] : [];
+      if (isRecord(raw)) {
+        const ref = own2(raw, FILE_REF_KEY);
+        return typeof ref === "string" && ref !== "" ? [] : [mismatch(f, TYPE_FILE2)];
+      }
+      return [mismatch(f, TYPE_FILE2)];
+    }
+    default:
+      return [];
+  }
+}
+function validateExamples(flow, issues) {
+  const examples = flow[KEY_EXAMPLES];
+  if (!Array.isArray(examples) || examples.length === 0) return;
+  const walker = new Walker(flow, issues);
+  walker.run(examples);
+  for (const f of walker.findings) {
+    const issue = {
+      field: f.field,
+      message: f.message,
+      code: f.code,
+      ...f.suggestion !== void 0 ? { suggestion: f.suggestion } : {}
+    };
+    if (f.severity === "error") issues.error(issue);
+    else issues.warn(issue);
+  }
+}
+
 // src/index.ts
 function countStepsWithErrors(errors) {
   const ids = /* @__PURE__ */ new Set();
@@ -5107,6 +6531,7 @@ function validateParsed(flow, opts, sources) {
   validateExecutorConfigEnvScopes(f, issues);
   validateServerOwnedQueryKeys(f, issues);
   validateCredentialEndpointPairing(f, issues);
+  validateExamples(f, issues);
   validateOrchestratorExons(f, issues);
   validateUnknownKeys(f, issues);
   const templateStats = validateTemplates(f, issues, opts);