@vaudience/aigentflow-flow-validator 0.19.0 → 0.21.0

package/dist/cli.js

@@ -307,6 +307,17 @@ function isValidGoDuration(input) {
 var RESERVED_STEP_ID_CHAR = ".";
 var RESERVED_STEP_ID_ORCHESTRATOR = "orchestrator";
 var DISPLAY_NAME_MAX_LEN = 80;
+var YAML11_BOOL_WORDS = new Set(
+  ["y", "yes", "on", "n", "no", "off"].flatMap((w) => [
+    w,
+    w.toUpperCase(),
+    w[0].toUpperCase() + w.slice(1)
+  ])
+);
+function isBoolLike(v) {
+  if (v === null || typeof v === "boolean") return true;
+  return typeof v === "string" && YAML11_BOOL_WORDS.has(v);
+}
 function validateBasicStructure(flow, issues) {
   if (!issues.nonEmptyStringOf(flow, "aigentflow_version", "")) {
     issues.error({
@@ -336,6 +347,14 @@ function validateBasicStructure(flow, issues) {
       });
     }
   }
+  if (flow.strict_templates !== void 0 && !isBoolLike(flow.strict_templates)) {
+    issues.error({
+      field: "strict_templates",
+      message: "strict_templates must be a boolean (true or false)",
+      code: "invalid_type",
+      suggestion: "Write 'strict_templates: true' or remove the key"
+    });
+  }
   const start = issues.stringOf(flow, "start", "");
   if (start === null || start === "") {
     issues.error({
@@ -436,7 +455,7 @@ function validateBasicStructure(flow, issues) {
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
   $comment: "Vendored enum surface mirrored from the AIgentFlow Go reference implementation. Regenerate / review on every flow-YAML schema change. See PARITY.md. Values here are public protocol/type names only.",
-  specVersion: "2.820.0",
+  specVersion: "2.827.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -460,6 +479,7 @@ var aigentflow_spec_default = {
     "geocoding",
     "geovisualize",
     "getmd",
+    "here",
     "homeassistant",
     "hosting",
     "http",
@@ -1275,6 +1295,42 @@ var aigentflow_spec_default = {
       }
     }
   },
+  templateDefaultPiped: {
+    $comment: "template_default_piped (ERROR at the top level, WARNING inside a loop body, like template_syntax_error). The template function `default` takes the value FIRST; a pipeline that passes a value into it as a non-first command hands the piped value as the LAST argument, so the fallback is always the result. Flagged: any pipeline (in any action, including if / else if / range / with / template / block conditions, parenthesised sub-pipelines and variable declarations) in which a command whose first word is the bare identifier `default` is not the FIRST command. Never flagged: a field, a variable, a string literal, a comment, `default` as the first command. The message fills %s with the pipeline.",
+    code: "template_default_piped",
+    function: "default",
+    messageFormat: "`default` takes the value FIRST, and a pipe passes the piped value LAST: `%s` is `default <fallback> <value>`, so the fallback is always the result",
+    suggestion: 'write the value first and the fallback second, as a call: `{{ default .x "fallback" }}`'
+  },
+  complianceResidency: {
+    $comment: "compliance_residency_unenforced (WARNING, never an error; needs no catalogue). When compliance.residency is non-empty and every code (trimmed, upper-cased) is in euResidencyCodes, each top-level step and loop sub-step whose executor starts with aiProtocol+protocolSeparator, then the orchestrator (provider = its exons execution.provider), warns when its provider (literal, lower-cased; skipped when empty or containing templateActionOpen) is in regionLaneProviders and the call is not pinned. Pinned = query region (orchestrator.region) a non-empty string after trimming; OR enforce_region true (query: bool true or the strings in enforceRegionTrueStrings; orchestrator: bool true); OR the author named the endpoint: query <provider>+baseUrlParamSuffix a non-empty string after trimming, or executor_config.<provider>.base_url non-empty after trimming. The provider segment of ai://<provider>/<operation> exists only when a slash follows it. regionLaneProviders is the set of providers whose adapter routes on `region`; a provider outside it has no region lane and is never warned. Message, suggestion and site formats fill %s and %q (a Go-quoted string) in order; the message's last placeholder is the residency list as written, printed [A B]. Reference: validateResidencyEnforcement (validation.residency.go).",
+    code: "compliance_residency_unenforced",
+    euResidencyCodes: ["EU", "DE", "FR", "IE", "NL", "IT", "ES"],
+    regionLaneProviders: [
+      "bedrock",
+      "google",
+      "azure",
+      "openai",
+      "assemblyai",
+      "speechmatics",
+      "deepgram",
+      "mistral"
+    ],
+    aiProtocol: "ai",
+    protocolSeparator: "://",
+    regionParam: "region",
+    enforceRegionParam: "enforce_region",
+    baseUrlParamSuffix: "_base_url",
+    enforceRegionTrueStrings: ["true", "1", "yes"],
+    stepFieldFormat: "steps.%s.executor",
+    loopStepFieldFormat: "steps.%s.loop.steps.%s.executor",
+    orchestratorField: "orchestrator.exons",
+    siteStepFormat: "step %q",
+    siteLoopStepFormat: "loop sub-step %q of step %q",
+    siteOrchestrator: "the orchestrator",
+    messageFormat: "%s calls provider %q, whose default endpoint commits to no jurisdiction, but sets neither region nor enforce_region, so nothing pins it to the declared residency %v. compliance.residency is a catalogue eligibility check, not endpoint evidence",
+    suggestion: "Add `region: eu` and `enforce_region: true` to the call (an orchestrator: the same two keys on the orchestrator block). Prove it afterwards: the step record's diagnostics.region is stamped from the host actually dialled."
+  },
   examples: {
     $comment: "The examples: block. Derived from the reference's constants, never hand-typed: limits, vocabularies, the credential-shaped-literal pattern set and each code's severity. example_ref_blocked_host is listed for completeness but is raised by the reference implementation only; the ports never raise it. See PARITY.md, 'The examples block'.",
     limits: {
@@ -1609,6 +1665,7 @@ var aigentflow_spec_default = {
         rate_limit: "FlowRateLimitConfig",
         start: "scalar",
         steps: "map<StepDefinition>",
+        strict_templates: "scalar",
         tags: "list<scalar>",
         template: "FlowTemplateMetadata",
         tool_discovery: "scalar",
@@ -1943,6 +2000,25 @@ var CREDENTIAL_ENDPOINT_PAIRING = {
   familyKeySeparator: aigentflow_spec_default.credentialEndpointPairing.familyKeySeparator,
   families: aigentflow_spec_default.credentialEndpointPairing.families
 };
+var COMPLIANCE_RESIDENCY = {
+  code: aigentflow_spec_default.complianceResidency.code,
+  euResidencyCodes: aigentflow_spec_default.complianceResidency.euResidencyCodes,
+  regionLaneProviders: aigentflow_spec_default.complianceResidency.regionLaneProviders,
+  aiProtocol: aigentflow_spec_default.complianceResidency.aiProtocol,
+  protocolSeparator: aigentflow_spec_default.complianceResidency.protocolSeparator,
+  regionParam: aigentflow_spec_default.complianceResidency.regionParam,
+  enforceRegionParam: aigentflow_spec_default.complianceResidency.enforceRegionParam,
+  baseUrlParamSuffix: aigentflow_spec_default.complianceResidency.baseUrlParamSuffix,
+  enforceRegionTrueStrings: aigentflow_spec_default.complianceResidency.enforceRegionTrueStrings,
+  stepFieldFormat: aigentflow_spec_default.complianceResidency.stepFieldFormat,
+  loopStepFieldFormat: aigentflow_spec_default.complianceResidency.loopStepFieldFormat,
+  orchestratorField: aigentflow_spec_default.complianceResidency.orchestratorField,
+  siteStepFormat: aigentflow_spec_default.complianceResidency.siteStepFormat,
+  siteLoopStepFormat: aigentflow_spec_default.complianceResidency.siteLoopStepFormat,
+  siteOrchestrator: aigentflow_spec_default.complianceResidency.siteOrchestrator,
+  messageFormat: aigentflow_spec_default.complianceResidency.messageFormat,
+  suggestion: aigentflow_spec_default.complianceResidency.suggestion
+};
 var EXAMPLES = {
   limits: aigentflow_spec_default.examples.limits,
   idPattern: new RegExp(aigentflow_spec_default.examples.idPattern),
@@ -1962,6 +2038,12 @@ var EXAMPLES = {
   })),
   codes: aigentflow_spec_default.examples.codes
 };
+var TEMPLATE_DEFAULT_PIPED = {
+  code: aigentflow_spec_default.templateDefaultPiped.code,
+  function: aigentflow_spec_default.templateDefaultPiped.function,
+  messageFormat: aigentflow_spec_default.templateDefaultPiped.messageFormat,
+  suggestion: aigentflow_spec_default.templateDefaultPiped.suggestion
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -3925,6 +4007,117 @@ function splitPipeline(body) {
   return stages;
 }
 
+// src/template/gotmpl-default.ts
+var FUNCTION_NAME = "default";
+var PIPE = "|";
+var OPEN_PAREN = "(";
+var CLOSE_PAREN = ")";
+var MAX_NESTING_DEPTH = 100;
+var PIPELINE_KEYWORDS = /^(?:else\s+if|else\s+with|if|range|with|template|block)(?![\w$.])/;
+var NO_PIPELINE = /^(?:define|else|end|break|continue)(?![\w$.])/;
+var DECLARATION = /^\$\w*(?:\s*,\s*\$\w*)*\s*:?=/;
+function pipedDefaultPipelines(src) {
+  const { actions, fatal } = lexActions(src);
+  if (fatal) return [];
+  const found = /* @__PURE__ */ new Set();
+  try {
+    for (const action of actions) {
+      if (action.isComment || action.body === "") continue;
+      scanAction(action.body, found);
+    }
+  } catch (err) {
+    if (!(err instanceof RangeError)) throw err;
+    return [];
+  }
+  return [...found].sort();
+}
+function scanAction(body, found) {
+  let rest = body;
+  const kw = PIPELINE_KEYWORDS.exec(rest);
+  if (!kw && NO_PIPELINE.test(rest)) return;
+  if (kw) {
+    rest = rest.slice(kw[0].length).trimStart();
+    const keyword = kw[0].replace(/\s+/g, " ");
+    if (keyword === "template" || keyword === "block") {
+      const q2 = rest[0];
+      if (q2 === '"' || q2 === "`") {
+        const end = scanString(rest, 0, q2);
+        if (end === -1) return;
+        rest = rest.slice(end + 1).trimStart();
+      }
+    }
+  }
+  if (rest === "") return;
+  parsePipeline(rest, 0, false, found, 0);
+}
+function parsePipeline(src, start, nested, found, depth) {
+  if (depth > MAX_NESTING_DEPTH) return { text: src.slice(start), end: src.length };
+  let i = start;
+  const n = src.length;
+  let decl = "";
+  const decMatch = DECLARATION.exec(src.slice(i));
+  if (decMatch) {
+    decl = decMatch[0].replace(/\s+/g, " ") + " ";
+    i += decMatch[0].length;
+  }
+  const commands = [];
+  let current = [];
+  let firstWords = [];
+  let pipedDefault = false;
+  const pushCommand = () => {
+    if (current.length > 0) {
+      commands.push(current);
+      firstWords.push(current[0]);
+    }
+    current = [];
+  };
+  while (i < n) {
+    const c = src[i];
+    if (c === " " || c === "	" || c === "\n" || c === "\r") {
+      i += 1;
+      continue;
+    }
+    if (c === '"' || c === "`" || c === "'") {
+      const end = scanString(src, i, c);
+      const stop = end === -1 ? n - 1 : end;
+      current.push(src.slice(i, stop + 1));
+      i = stop + 1;
+      continue;
+    }
+    if (c === OPEN_PAREN) {
+      const inner = parsePipeline(src, i + 1, true, found, depth + 1);
+      current.push(`(${inner.text})`);
+      i = inner.end;
+      continue;
+    }
+    if (c === CLOSE_PAREN) {
+      if (nested) {
+        i += 1;
+        break;
+      }
+      i += 1;
+      continue;
+    }
+    if (c === PIPE) {
+      pushCommand();
+      i += 1;
+      continue;
+    }
+    let j = i;
+    while (j < n && !/[\s|()"`']/.test(src[j])) j += 1;
+    if (j === i) j = i + 1;
+    current.push(src.slice(i, j));
+    i = j;
+  }
+  pushCommand();
+  firstWords.forEach((word, idx) => {
+    if (idx > 0 && word === FUNCTION_NAME) pipedDefault = true;
+  });
+  const text = decl + commands.map((cmd) => cmd.join(" ")).join(` ${PIPE} `);
+  if (pipedDefault) found.add(text);
+  return { text, end: i };
+}
+
 // src/validators/processingOperations.ts
 var PROCESSING_OP_GUARD_KEY = PROCESSING_OPERATIONS.guardKey;
 var PROCESSING_PHASES = ["pre_processing", "post_processing"];
@@ -4071,6 +4264,17 @@ function checkTemplateString(value, field, stepID, issues, stats, opts, demote =
       });
     }
   }
+  if (errors.length > 0) return;
+  for (const pipe of pipedDefaultPipelines(value)) {
+    report({
+      field,
+      message: TEMPLATE_DEFAULT_PIPED.messageFormat.replace("%s", () => pipe),
+      code: TEMPLATE_DEFAULT_PIPED.code,
+      stepId: stepID,
+      context: `Template: ${value}`,
+      suggestion: TEMPLATE_DEFAULT_PIPED.suggestion
+    });
+  }
 }
 function walkStrings2(basePath, value, stepID, issues, stats, opts, check, demote = false) {
   if (isString(value)) {
@@ -5302,6 +5506,141 @@ function warnOrchestratorToolWithheld(flow, orch, report, issues) {
   }
 }
 
+// src/validators/complianceResidency.ts
+function own2(m, key) {
+  if (!isRecord(m) || !Object.prototype.hasOwnProperty.call(m, key)) return void 0;
+  return m[key];
+}
+function sprintf(format, ...args) {
+  let i = 0;
+  return format.replace(/%[sqv]/g, (verb) => {
+    const arg = args[i++] ?? "";
+    return verb === "%q" ? JSON.stringify(arg) : arg;
+  });
+}
+function literalOrEmpty(s) {
+  const t = goTrimSpace2(s);
+  return t.includes(TEMPLATE_ACTION_OPEN) ? "" : t;
+}
+function euOnlyResidency(flow, issues) {
+  const raw = own2(own2(flow, "compliance"), "residency");
+  if (!isArray(raw)) return null;
+  const codes = [];
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] === null) continue;
+    const code = issues.stringAt(raw[i], `compliance.residency[${i}]`);
+    if (code === null) return null;
+    codes.push(code);
+  }
+  if (codes.length === 0) return null;
+  const eu = new Set(COMPLIANCE_RESIDENCY.euResidencyCodes);
+  return codes.every((c) => eu.has(goTrimSpace2(c).toUpperCase())) ? codes : null;
+}
+function aiProvider(executor) {
+  const prefix = COMPLIANCE_RESIDENCY.aiProtocol + COMPLIANCE_RESIDENCY.protocolSeparator;
+  if (!executor.startsWith(prefix)) return "";
+  const rest = executor.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  const provider = slash > 0 ? rest.slice(0, slash) : "";
+  return provider.includes(TEMPLATE_ACTION_OPEN) ? "" : provider;
+}
+function isRegionLane(provider) {
+  const literal = literalOrEmpty(provider);
+  return literal !== "" && COMPLIANCE_RESIDENCY.regionLaneProviders.includes(literal.toLowerCase());
+}
+function nonBlankString(m, key) {
+  const v = own2(m, key);
+  return typeof v === "string" && goTrimSpace2(v) !== "";
+}
+function queryEnforcesRegion(query) {
+  const v = own2(query, COMPLIANCE_RESIDENCY.enforceRegionParam);
+  if (typeof v === "boolean") return v;
+  return typeof v === "string" && COMPLIANCE_RESIDENCY.enforceRegionTrueStrings.includes(v);
+}
+function flowDirectsEndpoint(flow, provider, issues) {
+  const key = provider.toLowerCase();
+  const inst = own2(own2(flow, "executor_config"), key);
+  if (!isRecord(inst)) return false;
+  const baseUrl = issues.stringOf(inst, "base_url", `executor_config.${key}`);
+  return baseUrl !== null && goTrimSpace2(baseUrl) !== "";
+}
+function callPinsEndpoint(flow, provider, query, issues) {
+  if (nonBlankString(query, COMPLIANCE_RESIDENCY.regionParam)) return true;
+  if (queryEnforcesRegion(query)) return true;
+  if (nonBlankString(query, provider.toLowerCase() + COMPLIANCE_RESIDENCY.baseUrlParamSuffix)) return true;
+  return flowDirectsEndpoint(flow, provider, issues);
+}
+function validateResidencyEnforcement(flow, issues) {
+  const residency = euOnlyResidency(flow, issues);
+  if (residency === null) return;
+  const warn = (site, field, stepId, provider) => {
+    issues.warn({
+      field,
+      ...stepId === void 0 ? {} : { stepId },
+      code: COMPLIANCE_RESIDENCY.code,
+      message: sprintf(COMPLIANCE_RESIDENCY.messageFormat, site, provider, `[${residency.join(" ")}]`),
+      suggestion: COMPLIANCE_RESIDENCY.suggestion
+    });
+  };
+  const steps = flow.steps;
+  if (isRecord(steps)) {
+    for (const stepId of Object.keys(steps).sort()) {
+      const step = steps[stepId];
+      if (!isRecord(step)) continue;
+      const calls = [
+        {
+          executor: issues.stringOf(step, "executor", `steps.${stepId}`) ?? "",
+          query: own2(step, "query"),
+          subId: null
+        }
+      ];
+      for (const sub of loopSubStepsOfStep(stepId, step)) {
+        calls.push({
+          executor: issues.stringOf(sub.raw, "executor", sub.basePath) ?? "",
+          query: own2(sub.raw, "query"),
+          subId: issues.stringOf(sub.raw, "id", sub.basePath) ?? ""
+        });
+      }
+      for (const call of calls) {
+        const provider = aiProvider(call.executor);
+        if (!isRegionLane(provider)) continue;
+        if (callPinsEndpoint(flow, provider, call.query, issues)) continue;
+        if (call.subId === null) {
+          warn(
+            sprintf(COMPLIANCE_RESIDENCY.siteStepFormat, stepId),
+            sprintf(COMPLIANCE_RESIDENCY.stepFieldFormat, stepId),
+            stepId,
+            provider
+          );
+        } else {
+          warn(
+            sprintf(COMPLIANCE_RESIDENCY.siteLoopStepFormat, call.subId, stepId),
+            sprintf(COMPLIANCE_RESIDENCY.loopStepFieldFormat, stepId, call.subId),
+            stepId,
+            provider
+          );
+        }
+      }
+    }
+  }
+  warnOrchestrator(flow, issues, warn);
+}
+function warnOrchestrator(flow, issues, warn) {
+  const orch = flow.orchestrator;
+  if (!isRecord(orch)) return;
+  const source = issues.stringOf(orch, "exons", "orchestrator");
+  if (source === null || source === "") return;
+  const report = inspectExonsFrontmatter(source);
+  if (report.parseError !== null || !report.specRead || !report.hasSpec) return;
+  const provider = literalOrEmpty(report.provider);
+  if (!isRegionLane(provider)) return;
+  const region = issues.stringOf(orch, "region", "orchestrator");
+  if (region !== null && goTrimSpace2(region) !== "") return;
+  if (orch.enforce_region === true) return;
+  if (flowDirectsEndpoint(flow, provider, issues)) return;
+  warn(COMPLIANCE_RESIDENCY.siteOrchestrator, COMPLIANCE_RESIDENCY.orchestratorField, void 0, provider);
+}
+
 // src/validators/examples.ts
 var KEY_EXAMPLES = "examples";
 var VISIBILITY_PUBLIC = "public";
@@ -5379,7 +5718,7 @@ function num(n) {
 function has(o, key) {
   return Object.prototype.hasOwnProperty.call(o, key) && o[key] !== null && o[key] !== void 0;
 }
-function own2(o, key) {
+function own3(o, key) {
   return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : void 0;
 }
 function setOwn(o, key, value) {
@@ -5431,7 +5770,7 @@ function mergePatch(target, patch, depth) {
       continue;
     }
     if (isRecord(pv)) {
-      const current = own2(target, k);
+      const current = own3(target, k);
       const existing = isRecord(current) ? deepCopy(current, 0) : {};
       mergePatch(existing, pv, depth + 1);
       setOwn(target, k, existing);
@@ -5451,7 +5790,7 @@ function asFileRef(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);
+    const x = own3(v, k);
     return typeof x === "string" ? x : "";
   };
   return {
@@ -5519,7 +5858,7 @@ var Walker = class _Walker {
         `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);
+    const allHeld = examples.every((e) => isRecord(e) && own3(e, "hold_out") === true);
     if (allHeld) {
       this.warn(
         "examples_all_held_out",
@@ -5607,9 +5946,9 @@ var Walker = class _Walker {
         `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"));
+    this.validateTags(path, label, own3(ex, "tags"));
+    this.validateWeight(`${path}.weight`, label, numberOf(own3(ex, "weight")));
+    const minScore = numberOf(own3(ex, "min_score"));
     if (minScore !== void 0 && !scoreInRange(minScore)) {
       this.err(
         "example_min_score_range",
@@ -5625,7 +5964,7 @@ var Walker = class _Walker {
         `example ${q(label)} has side_effects ${q(sideEffects)}; use refuse or allow`
       );
     }
-    const holdOut = own2(ex, "hold_out") === true;
+    const holdOut = own3(ex, "hold_out") === true;
     if (holdOut && this.isPublic()) {
       this.err(
         "example_holdout_in_public_flow",
@@ -5648,17 +5987,17 @@ var Walker = class _Walker {
         `example ${q(label)} has neither input nor input_ref; use input: {} for a flow that takes no input`
       );
     }
-    const rawInput = own2(ex, "input");
+    const rawInput = own3(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");
+    const rawInputRef = own3(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");
+    const expected = own3(ex, "expected");
     if (!has(ex, "expected")) {
       this.err(
         "example_expected_missing",
@@ -5677,7 +6016,7 @@ var Walker = class _Walker {
         "this example can be run but not scored"
       );
     }
-    this.validateCheckpoints(path, label, own2(ex, "checkpoints"));
+    this.validateCheckpoints(path, label, own3(ex, "checkpoints"));
     this.validateVariants(i, path, label, ex, hasInput, baseInput);
     this.scanSecretLike(i, path, ex);
   }
@@ -5737,8 +6076,8 @@ var Walker = class _Walker {
       );
       return;
     }
-    const schema = own2(this.flow, "input_schema");
-    const query = own2(this.flow, "query");
+    const schema = own3(this.flow, "input_schema");
+    const query = own3(this.flow, "query");
     if (isRecord(schema)) {
       this.checkInputAgainstSchema(field, label, input, schema, code);
     } else if (isRecord(query) && Object.keys(query).length > 0) {
@@ -5806,29 +6145,29 @@ var Walker = class _Walker {
     }
   }
   schemaFields(schema) {
-    const raw = own2(schema, "fields");
+    const raw = own3(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 enumRaw = own3(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");
+      const vw = own3(f, "visible_when");
       out.push({
         name: this.s(f, "name", base),
         type: this.s(f, "type", base),
-        required: own2(f, "required") === true,
+        required: own3(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") : []
+          equals: own3(vw, "equals"),
+          in: Array.isArray(own3(vw, "in")) ? own3(vw, "in") : []
         } : null
       });
     });
@@ -5839,7 +6178,7 @@ var Walker = class _Walker {
     const failures = [];
     for (const f of fields) {
       if (!isVisible(f, runInput)) continue;
-      const raw = own2(runInput, f.name);
+      const raw = own3(runInput, f.name);
       if (raw === void 0 || raw === null) {
         if (f.required) {
           failures.push({
@@ -5950,7 +6289,7 @@ var Walker = class _Walker {
   /** 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 out = own3(this.flow, "output");
       const names2 = [];
       if (Array.isArray(out)) {
         out.forEach((item, i) => {
@@ -5959,10 +6298,10 @@ var Walker = class _Walker {
       }
       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;
+    const steps = own3(this.flow, "steps");
+    const step = isRecord(steps) ? own3(steps, stepId) : void 0;
+    const schema = isRecord(step) ? own3(step, "output_schema") : void 0;
+    const fields = isRecord(schema) ? own3(schema, "fields") : void 0;
     if (!Array.isArray(fields) || fields.length === 0) return { names: [], declared: false };
     const names = [];
     fields.forEach((f, i) => {
@@ -5981,8 +6320,8 @@ var Walker = class _Walker {
       );
     }
     const noOutput = status === STATUS_FAILED || status === STATUS_PAUSED_FOR_HUMAN;
-    const fieldsRec = own2(e, "fields");
-    const exactRec = own2(e, "exact");
+    const fieldsRec = own3(e, "fields");
+    const exactRec = own3(e, "exact");
     const fieldKeys = isRecord(fieldsRec) ? sortedKeys(fieldsRec) : [];
     const exactKeys = isRecord(exactRec) ? sortedKeys(exactRec) : [];
     const hasFields = fieldKeys.length > 0;
@@ -6000,7 +6339,7 @@ var Walker = class _Walker {
         `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"));
+    const minScore = numberOf(own3(e, "min_score"));
     if (minScore !== void 0 && !scoreInRange(minScore)) {
       this.err(
         "example_min_score_range",
@@ -6027,7 +6366,7 @@ var Walker = class _Walker {
         }
       }
     }
-    const reference = own2(e, "reference");
+    const reference = own3(e, "reference");
     if (isRecord(reference)) this.validateReference(`${path}.reference`, reference);
     const { names, declared } = this.outputNamesFor(kind, stepId);
     const checkKey = (field, key) => {
@@ -6054,12 +6393,12 @@ var Walker = class _Walker {
     for (const key of fieldKeys) {
       const fpath = `${path}.fields.${key}`;
       checkKey(fpath, key);
-      const matcher = own2(fieldsRec, key);
+      const matcher = own3(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 mustNot = this.stringList(own3(e, "must_not"), `${path}.must_not`);
+    const mustNotContain = this.stringList(own3(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);
@@ -6080,9 +6419,9 @@ var Walker = class _Walker {
       }
     });
     for (const key of fieldKeys) {
-      const matcher = own2(fieldsRec, key);
+      const matcher = own3(fieldsRec, key);
       if (!isRecord(matcher)) continue;
-      const eq = own2(matcher, "equals");
+      const eq = own3(matcher, "equals");
       if (typeof eq !== "string" || eq === "") continue;
       for (const banned of mustNotContain) {
         if (banned !== "" && equalFold(banned, eq)) {
@@ -6142,7 +6481,7 @@ var Walker = class _Walker {
       }
       return;
     }
-    const refRec = own2(r, "ref");
+    const refRec = own3(r, "ref");
     if (!isRecord(refRec)) return;
     const ref = this.fileRefOf(refRec, `${path}.ref`);
     this.validateFileRef(`${path}.ref`, ref);
@@ -6155,22 +6494,22 @@ var Walker = class _Walker {
     }
   }
   expectationIsBinaryReferenceOnly(e, path) {
-    const reference = own2(e, "reference");
-    const refRec = isRecord(reference) ? own2(reference, "ref") : void 0;
+    const reference = own3(e, "reference");
+    const refRec = isRecord(reference) ? own3(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);
+    const fields = own3(e, "fields");
+    const exact = own3(e, "exact");
+    return this.s(e, "rubric", path) === "" && !(isRecord(fields) && Object.keys(fields).length > 0) && !(isRecord(exact) && Object.keys(exact).length > 0) && this.stringList(own3(e, "must_not"), `${path}.must_not`).length === 0 && this.stringList(own3(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"));
+    const oneOf = own3(m, "one_of");
+    const approx = numberOf(own3(m, "approx"));
+    const tolerance = numberOf(own3(m, "tolerance"));
     let operators = 0;
     if (has(m, "equals")) operators++;
     if (this.s(m, "contains", path) !== "") operators++;
@@ -6178,7 +6517,7 @@ var Walker = class _Walker {
     if (matches !== "") operators++;
     if (Array.isArray(oneOf) && oneOf.length > 0) operators++;
     if (approx !== void 0) operators++;
-    if (typeof own2(m, "present") === "boolean") operators++;
+    if (typeof own3(m, "present") === "boolean") operators++;
     if (operators !== 1) {
       this.err(
         "example_field_matcher_invalid",
@@ -6205,12 +6544,12 @@ var Walker = class _Walker {
   // -- checkpoints ------------------------------------------------------
   validateCheckpoints(path, label, cps) {
     if (!isRecord(cps) || Object.keys(cps).length === 0) return;
-    const stepsRaw = own2(this.flow, "steps");
+    const stepsRaw = own3(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);
+      const step = own3(steps, id);
       if (!isRecord(step)) {
         this.err(
           "example_checkpoint_step_unknown",
@@ -6220,7 +6559,7 @@ var Walker = class _Walker {
         );
         continue;
       }
-      const next = own2(step, "next");
+      const next = own3(step, "next");
       if (has(step, "for_each") || has(step, "loop") || isRecord(next) && has(next, "parallel")) {
         this.err(
           "example_checkpoint_step_composite",
@@ -6229,7 +6568,7 @@ var Walker = class _Walker {
         );
         continue;
       }
-      const cp = own2(cps, id);
+      const cp = own3(cps, id);
       if (cp === null || cp === void 0) {
         this.validateExpectation(cpath, label, {}, "checkpoint", id);
       } else if (isRecord(cp)) {
@@ -6240,7 +6579,7 @@ var Walker = class _Walker {
   // -- variants ---------------------------------------------------------
   validateVariants(i, path, label, ex, hasInput, baseInput) {
     const L = EXAMPLES.limits;
-    const variants = own2(ex, "variants");
+    const variants = own3(ex, "variants");
     if (!Array.isArray(variants) || variants.length === 0) return;
     if (variants.length > L.maxVariants) {
       this.err(
@@ -6303,8 +6642,8 @@ var Walker = class _Walker {
           `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");
+      this.validateWeight(`${vpath}.weight`, both, numberOf(own3(v, "weight")));
+      const patch = own3(v, "input_patch");
       const patchRec = isRecord(patch) ? patch : null;
       const hasPatch = patchRec !== null && Object.keys(patchRec).length > 0;
       const hasRef = has(v, "input_ref");
@@ -6321,7 +6660,7 @@ var Walker = class _Walker {
           `variant ${q(vlabel)} of example ${q(label)} changes neither the input nor the expectation`
         );
       }
-      const refRec = own2(v, "input_ref");
+      const refRec = own3(v, "input_ref");
       if (isRecord(refRec)) {
         this.validateFileRef(`${vpath}.input_ref`, this.fileRefOf(refRec, `${vpath}.input_ref`));
       }
@@ -6336,7 +6675,7 @@ var Walker = class _Walker {
           this.checkVariantPatch(vpath, label, vlabel, baseInput, patchRec);
         }
       }
-      const expected = own2(v, "expected");
+      const expected = own3(v, "expected");
       if (isRecord(expected)) {
         this.validateExpectation(`${vpath}.expected`, both, expected, "final", "");
       }
@@ -6347,11 +6686,11 @@ var Walker = class _Walker {
    * itself supplies. A null patch value deleting a secret is fine.
    */
   checkVariantPatch(vpath, label, vlabel, base, patch) {
-    const schema = own2(this.flow, "input_schema");
+    const schema = own3(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);
+        const val = own3(patch, f.name);
         if (val !== void 0 && val !== null) {
           this.err(
             "example_secret_value",
@@ -6391,18 +6730,18 @@ var Walker = class _Walker {
     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");
+    const input = own3(ex, "input");
     if (isRecord(input)) scanLeaves(`${path}.input`, input, 0, emit);
-    const expected = own2(ex, "expected");
+    const expected = own3(ex, "expected");
     if (isRecord(expected)) this.scanExpectationLeaves(`${path}.expected`, expected, emit);
-    const cps = own2(ex, "checkpoints");
+    const cps = own3(ex, "checkpoints");
     if (isRecord(cps)) {
       for (const id of sortedKeys(cps)) {
-        const cp = own2(cps, id);
+        const cp = own3(cps, id);
         if (isRecord(cp)) this.scanExpectationLeaves(`${path}.checkpoints.${id}`, cp, emit);
       }
     }
-    const variants = own2(ex, "variants");
+    const variants = own3(ex, "variants");
     if (Array.isArray(variants)) {
       variants.forEach((v, j) => {
         if (!isRecord(v)) return;
@@ -6410,34 +6749,34 @@ var Walker = class _Walker {
         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");
+        scanLeaves(`${vpath}.input_patch`, own3(v, "input_patch"), 0, emit);
+        const vexp = own3(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");
+    const reference = own3(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(
+    this.stringList(own3(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(
+    this.stringList(own3(e, "must_not_contain"), `${path}.must_not_contain`).forEach(
       (s, j) => emit(`${path}.must_not_contain[${j}]`, s)
     );
-    const fields = own2(e, "fields");
+    const fields = own3(e, "fields");
     if (isRecord(fields)) {
       for (const key of sortedKeys(fields)) {
-        const m = own2(fields, key);
+        const m = own3(fields, key);
         if (!isRecord(m)) continue;
         const fpath = `${path}.fields.${key}`;
-        scanLeaves(`${fpath}.equals`, own2(m, "equals"), 0, emit);
+        scanLeaves(`${fpath}.equals`, own3(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");
+        const oneOf = own3(m, "one_of");
         if (Array.isArray(oneOf)) {
           oneOf.forEach(
             (one, j) => scanLeaves(`${fpath}.one_of[${j}]`, one, 0, emit)
@@ -6445,7 +6784,7 @@ var Walker = class _Walker {
         }
       }
     }
-    scanLeaves(`${path}.exact`, own2(e, "exact"), 0, emit);
+    scanLeaves(`${path}.exact`, own3(e, "exact"), 0, emit);
   }
 };
 function scoreInRange(v) {
@@ -6561,7 +6900,7 @@ function inputValueFailures(f, raw) {
     case TYPE_FILE2: {
       if (typeof raw === "string") return raw === "" ? [mismatch(f, TYPE_FILE2)] : [];
       if (isRecord(raw)) {
-        const ref = own2(raw, FILE_REF_KEY);
+        const ref = own3(raw, FILE_REF_KEY);
         return typeof ref === "string" && ref !== "" ? [] : [mismatch(f, TYPE_FILE2)];
       }
       return [mismatch(f, TYPE_FILE2)];
@@ -6641,6 +6980,7 @@ function validateParsed(flow, opts, sources) {
   validateCredentialEndpointPairing(f, issues);
   validateExamples(f, issues);
   validateOrchestratorExons(f, issues);
+  validateResidencyEnforcement(f, issues);
   validateUnknownKeys(f, issues);
   const templateStats = validateTemplates(f, issues, opts);
   const totalSteps = f.steps && typeof f.steps === "object" && !Array.isArray(f.steps) ? Object.keys(f.steps).length : 0;