@kontourai/flow-agents 3.12.1 → 4.1.0

package/schemas/workflow-waves.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/workflow-waves.schema.json",
+  "title": "Flow Agents Workflow Waves",
+  "description": "Fan-out wave manifest for a workflow session. Each wave declares its expected workers (M) before dispatch; every worker lands exactly one terminal status record; the orchestrator reconciles worker_results against expected_workers at wave close and records an explicit 'N of M reported' reconciliation. A worker that never reported is recorded as not_reported — visible data, never silently absorbed. This sidecar is additive: a session without waves.json declares no fan-out and is unaffected.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_slug",
+    "waves"
+  ],
+  "$defs": {
+    "evidence_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "source",
+            "command",
+            "artifact",
+            "provider",
+            "external"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "excerpt": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "source"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "file",
+              "line_start",
+              "line_end",
+              "excerpt"
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "artifact"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "allOf": [
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "file"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "url"
+                    ]
+                  }
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "summary"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "excerpt"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "command"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "excerpt"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "summary"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "url"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "enum": [
+                  "provider",
+                  "external"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "url"
+            ]
+          }
+        }
+      ]
+    },
+    "expected_worker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "task"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owned_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "worker_result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "status",
+        "summary",
+        "recorded_at"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "completed",
+            "failed",
+            "blocked",
+            "not_reported"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "recorded_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidence_ref"
+          }
+        }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "expected_count",
+        "reported_count",
+        "summary",
+        "reconciled_at"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "complete",
+            "incomplete"
+          ]
+        },
+        "expected_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reported_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reconciled_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "wave": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "wave_id",
+        "step",
+        "declared_at",
+        "expected_workers"
+      ],
+      "properties": {
+        "wave_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "step": {
+          "type": "string",
+          "minLength": 1
+        },
+        "declared_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expected_workers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/expected_worker"
+          }
+        },
+        "worker_results": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/worker_result"
+          }
+        },
+        "reconciliation": {
+          "$ref": "#/$defs/reconciliation"
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "task_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/wave"
+      }
+    }
+  }
+}

package/scripts/check-hachure-boundary.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * check-hachure-boundary — portfolio layer-doctrine ratchet.
+ *
+ * Doctrine (surface/docs/architecture/portfolio-layer-doctrine.md): only Surface
+ * may depend on the open trust format (hachure) directly. Products speak the
+ * format THROUGH Surface (Surface.validateTrustBundle / validateInquiryRecord /
+ * TrustBundleBuilder), so a hachure version can never drift across the suite.
+ *
+ * This check FAILS if a NEW direct-hachure usage appears in src/ or package.json.
+ * Today's known usages are allowlisted below and should be removed as each one
+ * migrates onto the Surface OTF read side. It is a ratchet: it does not force the
+ * existing migration, it prevents the problem from getting worse.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// ── Allowlist: current, pending-migration direct-hachure usage ───────────────
+// Remove an entry once its hachure usage is gone (routed through @kontourai/surface).
+const ALLOWLISTED_SOURCE_FILES = new Set([]);
+// package.json may still declare hachure while a source file above still needs it.
+const ALLOW_PACKAGE_JSON_HACHURE_DEP = false;
+
+// No `\b` before `require`: flow-agents calls `_require.resolve("hachure")`
+// (an aliased require), so a word-boundary anchor would miss it.
+const IMPORT_PATTERNS = [
+  /from\s+['"]hachure['"]/,
+  /require(\.resolve)?\(\s*['"]hachure['"]\s*\)/,
+  /import\(\s*['"]hachure['"]\s*\)/,
+];
+const SOURCE_EXT = /\.(ts|tsx|mjs|cjs|js|jsx)$/;
+
+function trackedSourceFiles() {
+  return execFileSync("git", ["ls-files", "src"], { encoding: "utf8" })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((f) => f && SOURCE_EXT.test(f));
+}
+
+const violations = [];
+
+for (const file of trackedSourceFiles()) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  text.split("\n").forEach((line, index) => {
+    if (IMPORT_PATTERNS.some((re) => re.test(line)) && !ALLOWLISTED_SOURCE_FILES.has(file)) {
+      violations.push(`${file}:${index + 1}  direct hachure usage — route through @kontourai/surface instead`);
+    }
+  });
+}
+
+const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+let pkgDeclaresHachure = false;
+for (const field of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
+  if (pkg[field] && Object.prototype.hasOwnProperty.call(pkg[field], "hachure")) {
+    pkgDeclaresHachure = true;
+    if (!ALLOW_PACKAGE_JSON_HACHURE_DEP) {
+      violations.push(`package.json ${field}.hachure — depend on @kontourai/surface, not hachure directly`);
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("[check-hachure-boundary] FAILED — new direct-hachure usage (products speak the open format through Surface):");
+  for (const v of violations) console.error(`  ${v}`);
+  console.error(
+    "\nSee the Portfolio Layer Doctrine (surface/docs/architecture/portfolio-layer-doctrine.md).\n" +
+      "Use @kontourai/surface (validateTrustBundle / validateInquiryRecord / TrustBundleBuilder).\n" +
+      "If this is a deliberate, reviewed exception, add it to the allowlist in this script with a migration note.",
+  );
+  process.exitCode = 1;
+} else {
+  const notes = [];
+  if (ALLOWLISTED_SOURCE_FILES.size) notes.push(`${ALLOWLISTED_SOURCE_FILES.size} allowlisted source file(s) pending migration`);
+  if (pkgDeclaresHachure && ALLOW_PACKAGE_JSON_HACHURE_DEP) notes.push("package.json hachure dep allowlisted pending migration");
+  console.log(`[check-hachure-boundary] OK — no new direct-hachure usage${notes.length ? ` (${notes.join("; ")})` : ""}.`);
+}

package/scripts/check-layer-boundary.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * check-layer-boundary — kit/engine layer-doctrine ratchet.
+ *
+ * Doctrine (veritas docs/architecture/engine-surface-seam.md, Invariant 3; ADR 0008/0016):
+ * kits distribute by copy/activate/CLI and consume a product engine via CLI + artifacts, NEVER
+ * as an npm library import. A kit that `import`s the veritas evaluation engine would fork the
+ * layer boundary — the kit must wrap the engine's CLI, not link its code. This is the executable
+ * enforcement of that invariant (flow-agents#651).
+ *
+ * FAILS if any tracked file under kits/ imports `@kontourai/veritas` (or its `/engine` subpath),
+ * or if any kit.json declares it as a dependency. The kit's trust-bundle adapter may import
+ * `@kontourai/surface` (the open trust format, Layer 3) — that is the sanctioned channel and is
+ * NOT matched here. No allowlist: the count is zero today and must stay zero.
+ *
+ * Not a violation (and not matched — import-syntax-scoped): the many descriptive strings naming
+ * "@kontourai/veritas" in kit.json descriptions, docs, and recorded CLI-output fixtures are prose
+ * and data, not code imports.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// Match import/require/dynamic-import of the veritas package (root or /engine subpath) only, so
+// prose/fixture mentions of the package name can never trip it — only an actual code link does.
+const PKG = String.raw`@kontourai/veritas(?:/[A-Za-z0-9_./-]+)?`;
+const IMPORT_PATTERNS = [
+  new RegExp(String.raw`from\s+['"](?:${PKG})['"]`),
+  new RegExp(String.raw`require(?:\.resolve)?\(\s*['"](?:${PKG})['"]\s*\)`),
+  new RegExp(String.raw`import\(\s*['"](?:${PKG})['"]\s*\)`),
+];
+const SOURCE_EXT = /\.(ts|tsx|mjs|cjs|js|jsx)$/;
+
+// Strip comments so an import-SHAPED example inside a doc comment (e.g. a JSDoc `* import ...`
+// line) is not a false positive. A real import statement never starts a line with `//` or `*`,
+// so this only removes prose, never a genuine dependency edge. (Line-scoped — not a full parser;
+// a package name inside a string literal remains matchable, which is intentional.)
+function codeOnly(line) {
+  const trimmed = line.trimStart();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) return "";
+  return line.replace(/\/\*.*?\*\//g, "").replace(/\/\/.*$/, "");
+}
+
+function trackedFiles(dir) {
+  return execFileSync("git", ["ls-files", dir], { encoding: "utf8" })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+const violations = [];
+
+// 1. Source imports under kits/.
+for (const file of trackedFiles("kits").filter((f) => SOURCE_EXT.test(f))) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  text.split("\n").forEach((line, index) => {
+    if (IMPORT_PATTERNS.some((re) => re.test(codeOnly(line)))) {
+      violations.push(`${file}:${index + 1}  imports @kontourai/veritas — kits wrap the engine via CLI, not as a library`);
+    }
+  });
+}
+
+// 2. kit.json dependency declarations.
+for (const file of trackedFiles("kits").filter((f) => f.endsWith("kit.json"))) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    continue;
+  }
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    const decl = manifest[field];
+    if (decl && typeof decl === "object" && !Array.isArray(decl)) {
+      for (const name of ["@kontourai/veritas"]) {
+        if (Object.prototype.hasOwnProperty.call(decl, name)) {
+          violations.push(`${file} ${field}.${name} — a kit must not declare the engine as an npm dependency`);
+        }
+      }
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("[check-layer-boundary] FAILED — a kit imports/depends on the veritas engine as a library (engine/surface seam, Invariant 3):");
+  for (const v of violations) console.error(`  ${v}`);
+  console.error(
+    "\nKits distribute by copy/activate/CLI and consume the engine via its CLI + recorded artifacts,\n" +
+      "never as an npm library import. The trust-bundle adapter may import @kontourai/surface (the open\n" +
+      "trust format); it must not import @kontourai/veritas. See veritas docs/architecture/engine-surface-seam.md.",
+  );
+  process.exitCode = 1;
+} else {
+  console.log("[check-layer-boundary] OK — no kit imports or declares the veritas engine as a library.");
+}