@kontourai/flow-agents 1.2.0 → 1.4.0

package/kits/knowledge/flows/synthesize.flow.json

@@ -14,12 +14,12 @@
       "expects": [
         {
           "id": "similar-sources-found",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "At least one compiled record similar to the target concept has been identified via the similarity detector. Similarity v1 uses category match + link-overlap heuristic. The result is a cluster of source record IDs to synthesize from.",
-          "claim": {
-            "type": "knowledge.synthesize.cluster",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.cluster",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -30,12 +30,12 @@
       "expects": [
         {
           "id": "proposal-recorded",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A proposal carrying source refs (proposer_id + source_ids in evidence) has been recorded via the store propose op. The concept body is NOT modified at this step — only a proposes link and mutation log entry are created.",
-          "claim": {
-            "type": "knowledge.synthesize.proposal",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.proposal",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -46,12 +46,12 @@
       "expects": [
         {
           "id": "proposal-carries-source-refs",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "The proposal evidence includes source_ids referencing every compiled record that contributed to the proposed summary. Gate rejects if source_ids is empty or any referenced record does not exist.",
-          "claim": {
-            "type": "knowledge.synthesize.evidence",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.evidence",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -62,12 +62,12 @@
       "expects": [
         {
           "id": "mutation-gate-decision",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A gate decision (apply or reject) has been recorded. If applied: concept body is updated via the store apply op with rationale and all contributing source_ids in provenance. If rejected: the store reject op is called, the concept body is byte-identical to its pre-proposal state, and only a rejection log entry is appended.",
-          "claim": {
-            "type": "knowledge.synthesize.gate-decision",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.gate-decision",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }

package/kits/release-evidence/flows/release-evidence.flow.json

@@ -13,12 +13,12 @@
       "expects": [
         {
           "id": "release-claim-present",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A trusted release.evidence claim must be attached before this gate can pass.",
           "explore_hint": "Attach a trust-report JSON file with claim type release.evidence and status trusted.",
-          "claim": {
-            "type": "release.evidence",
+          "bundle_claim": {
+            "claimType": "release.evidence",
             "accepted_statuses": [
               "trusted"
             ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -22,6 +22,15 @@
     "access": "public"
   },
   "type": "module",
+  "main": "build/src/index.js",
+  "types": "build/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/src/index.d.ts",
+      "import": "./build/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kontourai/flow-agents.git"
@@ -133,6 +142,9 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "^1.2.0"
+    "@kontourai/flow": "~1.3.0"
+  },
+  "optionalDependencies": {
+    "hachure": "^0.4.0"
   }
 }

package/schemas/workflow-evidence.schema.json

@@ -239,7 +239,8 @@
               "properties": {
                 "artifact_kind": {
                   "type": "string",
-                  "enum": ["TrustReport", "Trust Snapshot"]
+                  "description": "Hachure-aligned artifact kind. trust.bundle is the canonical value; TrustReport and Trust Snapshot are legacy aliases.",
+                  "enum": ["trust.bundle", "TrustReport", "Trust Snapshot"]
                 },
                 "artifact_ref": {
                   "type": "string",

package/scripts/hooks/stop-goal-fit.js

@@ -80,6 +80,15 @@ function hasSidecars(dir) {
   }
 }
 
+/**
+ * Returns true if a line of validator output looks like a validator-environment
+ * error (shell/npm error, tsc missing, spawn failure) rather than a real
+ * artifact validation message. Environment errors must never block goal-fit.
+ */
+function isEnvironmentError(line) {
+  return /tsc[:\s]|command not found|npm ERR!|npm error|ENOENT|EACCES|Cannot find module|node_modules\/.bin|TypeScript version|version conflict|error TS[0-9]/i.test(line);
+}
+
 function sidecarValidation(root, artifactDir) {
   const requireSidecars = String(process.env.FLOW_AGENTS_REQUIRE_SIDECARS || '').toLowerCase() === 'true';
   const requireCritique = String(process.env.FLOW_AGENTS_REQUIRE_CRITIQUE || '').toLowerCase() === 'true';
@@ -88,8 +97,6 @@ function sidecarValidation(root, artifactDir) {
   const packageRoot = fs.existsSync(path.join(root, 'package.json'))
     ? root
     : path.resolve(__dirname, '..', '..');
-  const packageJson = path.join(packageRoot, 'package.json');
-  if (!fs.existsSync(packageJson)) return [`${relative(root, artifactDir)} sidecar validation: package.json is missing; cannot run TypeScript workflow validator.`];
 
   let sidecarFiles = [];
   try {
@@ -112,26 +119,67 @@ function sidecarValidation(root, artifactDir) {
 
   if (sidecarFiles.length === 0) return [];
 
-  const args = ['run', 'workflow:validate-artifacts', '--silent', '--'];
-  args.push('--skip-markdown-validation');
-  if (requireSidecars) args.push('--require-sidecars');
-  if (requireCritique) args.push('--require-critique');
-  args.push(artifactDir);
+  // Part 1 fix: invoke the already-built validator directly via `node`, bypassing
+  // `npm run build` (tsc). npm-installed packages ship build/ in the package files,
+  // so the compiled JS is always available. Only fall back to npm run if build/ is
+  // absent (a raw dev checkout that hasn't been built yet).
+  const builtValidator = path.join(packageRoot, 'build', 'src', 'cli', 'validate-workflow-artifacts.js');
+  const hasBuild = fs.existsSync(builtValidator);
+
+  const validatorArgs = ['--skip-markdown-validation'];
+  if (requireSidecars) validatorArgs.push('--require-sidecars');
+  if (requireCritique) validatorArgs.push('--require-critique');
+  validatorArgs.push(artifactDir);
+
+  let result;
+  if (hasBuild) {
+    // Direct node invocation: no tsc, no npm build step, works from any npm install.
+    result = spawnSync(process.execPath, [builtValidator, ...validatorArgs], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  } else {
+    // Dev checkout without build/: fall back to npm run (may trigger tsc).
+    // If this also fails due to environment issues, Part 2 handles it below.
+    const npmArgs = ['run', 'workflow:validate-artifacts', '--silent', '--', ...validatorArgs];
+    result = spawnSync('npm', npmArgs, {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  }
 
-  const result = spawnSync('npm', args, {
-    cwd: packageRoot,
-    encoding: 'utf8',
-    timeout: 30000,
-  });
+  // Part 2 fix: treat validator-environment failures as SKIP, never as blocking.
+  // A spawn error (ENOENT, timeout) means the validator couldn't run at all.
+  if (result.error) {
+    // Validator couldn't be launched — environment issue, not a goal-fit failure.
+    return [`${relative(root, artifactDir)} sidecar validation skipped: validator could not run (${result.error.code || result.error.message})`];
+  }
 
   if (result.status === 0) return [];
-  const output = `${result.stdout || ''}\n${result.stderr || ''}`
+
+  // Validator ran and exited non-zero. Separate real validation errors from
+  // environment errors (tsc missing, npm ERR!, shell errors) so that a broken
+  // validator environment never blocks goal-fit.
+  const allLines = `${result.stdout || ''}\n${result.stderr || ''}`
     .split('\n')
     .map(line => line.trim())
-    .filter(Boolean)
-    .slice(0, 12);
-  if (output.length === 0) output.push(`validator exited with status ${result.status ?? 'unknown'}`);
-  return output.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
+    .filter(Boolean);
+
+  const envLines = allLines.filter(isEnvironmentError);
+  const validationLines = allLines.filter(line => !isEnvironmentError(line));
+
+  if (envLines.length > 0 && validationLines.length === 0) {
+    // Pure environment failure — skip, do not block.
+    return [`${relative(root, artifactDir)} sidecar validation skipped: validator environment error (${envLines[0].slice(0, 120)})`];
+  }
+
+  // Real validation errors (possibly mixed with a few env noise lines).
+  const output = validationLines.length > 0 ? validationLines : allLines;
+  const trimmed = output.slice(0, 12);
+  if (trimmed.length === 0) trimmed.push(`validator exited with status ${result.status ?? 'unknown'}`);
+  return trimmed.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
 }
 
 function isWorkflowArtifact(artifact) {
@@ -295,7 +343,7 @@ function analyze(root, now = Date.now()) {
   }
   warnings.push(...sidecarGuidance(root, path.dirname(latest.file)));
 
-  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
+  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
   return { warnings, blocking };
 }
 

package/src/cli/workflow-sidecar.ts

@@ -2,21 +2,23 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 
 type AnyObj = Record<string, any>;
 
-const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
-const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
-const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
-const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
-const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
+export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
+export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
+export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
+export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
+export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
 
 function now(): string { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file: string): string { return fs.readFileSync(file, "utf8"); }
-function writeJson(file: string, payload: AnyObj): void { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
+export function writeJson(file: string, payload: AnyObj): void { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
 function printJson(payload: AnyObj): void { console.log(JSON.stringify(payload).replace(/":/g, '": ').replace(/,"/g, ', "')); }
-function loadJson(file: string, fallback: AnyObj = {}): AnyObj { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
-function appendJsonl(file: string, payload: AnyObj): void {
+export function loadJson(file: string, fallback: AnyObj = {}): AnyObj { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
+export function appendJsonl(file: string, payload: AnyObj): void {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const line = JSON.stringify(payload, Object.keys(payload).sort()).replace(/":/g, '": ').replace(/,"/g, ', "');
   fs.appendFileSync(file, `${line}\n`);
@@ -24,6 +26,60 @@ function appendJsonl(file: string, payload: AnyObj): void {
 function die(message: string): never { throw new Error(message); }
 function slugify(value: string, fallback: string): string { return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || fallback; }
 
+// Optional Hachure trust-bundle validation. No-ops gracefully when hachure is not installed.
+// Install hachure (^0.4.0) as an optional dependency to enable schema validation.
+function tryLoadHachureValidator(): ((bundle: unknown) => { valid: boolean; errors: string[] }) | null {
+  try {
+    const _require = createRequire(import.meta.url);
+    const hachureDir = path.dirname(_require.resolve("hachure"));
+    const schemasDir = path.join(hachureDir, "schemas");
+    const Ajv = _require("ajv/dist/2020");
+    const schemas: Record<string, any> = {};
+    for (const file of fs.readdirSync(schemasDir)) {
+      if (!file.endsWith(".schema.json")) continue;
+      schemas[file] = JSON.parse(fs.readFileSync(path.join(schemasDir, file), "utf8"));
+    }
+    const ajv = new Ajv({ strict: false, allErrors: true });
+    for (const [filename, schema] of Object.entries(schemas)) {
+      if (filename === "trust-bundle.schema.json") continue;
+      ajv.addSchema(schema, filename);
+    }
+    const trustBundleSchema = schemas["trust-bundle.schema.json"];
+    if (!trustBundleSchema) return null;
+    const validate = ajv.compile(trustBundleSchema);
+    return (bundle: unknown) => {
+      const valid = validate(bundle);
+      if (valid) return { valid: true, errors: [] };
+      const errors = ((validate as any).errors ?? []).map((err: any) => {
+        const loc = err.instancePath || err.schemaPath || "";
+        return `${loc} ${err.message ?? "invalid"}`.trim();
+      });
+      return { valid: false, errors };
+    };
+  } catch {
+    return null;
+  }
+}
+let _hachureValidator: ReturnType<typeof tryLoadHachureValidator> | undefined;
+function getHachureValidator(): ReturnType<typeof tryLoadHachureValidator> {
+  if (_hachureValidator === undefined) _hachureValidator = tryLoadHachureValidator();
+  return _hachureValidator;
+}
+
+/**
+ * Validate a Hachure trust.bundle against the canonical trust-bundle schema.
+ * Returns `{ valid, errors, available }`. When the optional `hachure` dependency
+ * is not installed, validation is unavailable and this returns
+ * `{ valid: true, errors: [], available: false }` (fail-open) so callers can
+ * choose to treat unvalidated bundles as acceptable or gate on `available`.
+ * This is the same validator the sidecar writer uses for trust-backed evidence.
+ */
+export function validateTrustBundle(bundle: unknown): { valid: boolean; errors: string[]; available: boolean } {
+  const validate = getHachureValidator();
+  if (!validate) return { valid: true, errors: [], available: false };
+  return { ...validate(bundle), available: true };
+}
+
 function safeRepoIdentifier(value: string): string {
   const trimmed = value.trim().replace(/\.git$/, "");
   if (!trimmed || trimmed.length > 120) return "";
@@ -68,7 +124,7 @@ function repoIdentifier(): string {
   return safeRepoIdentifier(path.basename(process.cwd())) || "workspace";
 }
 
-function sidecarBase(slug: string): AnyObj {
+export function sidecarBase(slug: string): AnyObj {
   return { schema_version: "1.0", task_slug: slug, repo: repoIdentifier() };
 }
 
@@ -336,7 +392,7 @@ function hasNonEmptyString(value: unknown): boolean {
 function hasPositiveInteger(value: unknown): boolean {
   return Number.isInteger(value) && Number(value) >= 1;
 }
-function validateEvidenceRef(ref: AnyObj, label: string): AnyObj {
+export function validateEvidenceRef(ref: AnyObj, label: string): AnyObj {
   if (!["source", "command", "artifact", "provider", "external"].includes(ref.kind)) die(`${label} entry kind must be one of: source, command, artifact, provider, external`);
   for (const key of Object.keys(ref)) if (!["kind", "url", "file", "line_start", "line_end", "excerpt", "summary"].includes(key)) die(`${label} entries contain unsupported field: ${key}`);
   if (ref.url !== undefined && !hasNonEmptyString(ref.url)) die(`${label} entry url must be a non-empty string`);
@@ -352,7 +408,7 @@ function validateEvidenceRef(ref: AnyObj, label: string): AnyObj {
   if ((ref.kind === "provider" || ref.kind === "external") && !hasNonEmptyString(ref.url)) die(`${label} ${ref.kind} refs require url`);
   return ref;
 }
-function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
+export function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
   if (!Array.isArray(raw)) die(`${label} must be an array`);
   return raw.map((ref) => {
     if (typeof ref === "string") die(`${label} entries must be structured evidence reference objects; legacy string refs are not supported`);
@@ -360,7 +416,7 @@ function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
     return validateEvidenceRef({ ...ref as AnyObj }, label);
   });
 }
-function normalizeCheck(raw: AnyObj): AnyObj {
+export function normalizeCheck(raw: AnyObj): AnyObj {
   const check = { ...raw };
   if (!check.id || !check.kind || !check.status || !check.summary) die("check requires id, kind, status, and summary");
   if (!checkKinds.has(check.kind)) die("kind must be one of: build, types, lint, test, security, diff, browser, runtime, policy, external");
@@ -372,11 +428,27 @@ function normalizeCheck(raw: AnyObj): AnyObj {
 }
 function normalizeSurfaceRefs(refs: any): AnyObj[] {
   if (!Array.isArray(refs)) die("surface_trust_refs must be an array");
+  const hachureValidate = getHachureValidator();
   return refs.map((ref) => {
     const keys = JSON.stringify(ref).match(/"([^"]+)":/g) ?? [];
     for (const key of keys.map((k) => k.slice(1, -2))) if (key.toLowerCase().includes("veritas")) die(`unsupported field in Surface trust ref: ${key}`);
     const out = { ...ref };
-    if (!["TrustReport", "Trust Snapshot"].includes(out.artifact_kind)) die("artifact_kind must be one of");
+    // trust.bundle is the canonical Hachure-aligned artifact kind; TrustReport/Trust Snapshot are legacy aliases
+    if (!["trust.bundle", "TrustReport", "Trust Snapshot"].includes(out.artifact_kind)) die("artifact_kind must be one of: trust.bundle, TrustReport, Trust Snapshot");
+    // When hachure is installed, validate the referenced trust artifact if it is a local file
+    if (hachureValidate && out.artifact_ref && typeof out.artifact_ref === "string" && fs.existsSync(out.artifact_ref)) {
+      try {
+        const bundle = JSON.parse(fs.readFileSync(out.artifact_ref, "utf8"));
+        const result = hachureValidate(bundle);
+        if (!result.valid) {
+          const errorSummary = result.errors.slice(0, 3).join("; ");
+          die(`trust.bundle artifact at ${out.artifact_ref} failed Hachure schema validation: ${errorSummary}`);
+        }
+      } catch (err) {
+        if (err instanceof Error && err.message.includes("failed Hachure schema validation")) throw err;
+        // File read or parse errors are not re-thrown: the artifact_ref validation path is advisory
+      }
+    }
     const status = deriveSurfaceStatus(out);
     if (out.status === "pass" && status !== "pass") die("surface_trust_refs contradicts Surface trust facts");
     return out;
@@ -394,15 +466,16 @@ function surfaceCheckFromArtifact(file: string, index: number): AnyObj {
   const lower = JSON.stringify(raw).toLowerCase();
   let ref: AnyObj;
   if (lower.includes("provider") && lower.includes("absent")) {
-    ref = { artifact_kind: "TrustReport", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "surface.claim", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
   } else if (lower.includes("artifact") && lower.includes("absent")) {
-    ref = { artifact_kind: "TrustReport", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "surface.claim", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
   } else {
     const claimStatus = lower.includes("rejected") ? "rejected" : "accepted";
     const freshness = lower.includes("stale") ? "stale" : "fresh";
     const producer = lower.includes("missing-authority") ? "unknown" : "surface-local";
     const integrity = lower.includes("mismatch") ? "mismatch" : "matched";
-    ref = { artifact_kind: file.includes("snapshot") ? "Trust Snapshot" : "TrustReport", artifact_ref: file, gate_id: "builder.surface.claim", claim_type: "surface.claim", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
+    // Use trust.bundle as the canonical Hachure-aligned artifact_kind for all trust-backed evidence refs
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "builder.trust.bundle", claim_type: "builder.trust.bundle", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
     ref.status = deriveSurfaceStatus(ref);
     ref.summary = ref.status === "pass" ? "accepted" : ref.status === "not_verified" ? "not currently verifiable" : (claimStatus === "rejected" ? "rejected" : producer === "unknown" ? "missing authority" : "integrity mismatch");
   }
@@ -426,7 +499,7 @@ function validateAcceptanceEvidenceRefs(dir: string): void {
     if (criterion.evidence_refs !== undefined) normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
   });
 }
-function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next = "continue"): void {
+export function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next = "continue"): void {
   writeJson(path.join(dir, "state.json"), { ...loadJson(path.join(dir, "state.json")), ...sidecarBase(slug), status, phase, updated_at: timestamp, artifact_paths: relArtifacts(dir), next_action: { status: next, summary } });
 }
 function recordEvidence(p: ReturnType<typeof parseArgs>): number {
@@ -479,7 +552,7 @@ function advanceState(p: ReturnType<typeof parseArgs>): number {
   return 0;
 }
 
-function normalizeFinding(raw: AnyObj): AnyObj {
+export function normalizeFinding(raw: AnyObj): AnyObj {
   if (raw.file_refs !== undefined && !Array.isArray(raw.file_refs)) die("file_refs must be an array");
   return raw;
 }
@@ -536,7 +609,7 @@ function recordRelease(p: ReturnType<typeof parseArgs>): number {
   writeState(dir, slug, "delivered", "release", payload.updated_at, stateSummary);
   return 0;
 }
-function validateLearningCorrection(record: AnyObj): void {
+export function validateLearningCorrection(record: AnyObj): void {
   const correction = record.correction;
   if (correction === undefined) return;
   if (!correction || typeof correction !== "object" || Array.isArray(correction)) die("correction must be an object");
@@ -566,7 +639,7 @@ function validateLearningPrevention(prevention: unknown): void {
   if (typeof value.status !== "string" || value.status.length === 0) die("correction.prevention.status is required");
   if (!["open", "completed", "accepted", "deferred", "rejected"].includes(value.status)) die("correction.prevention.status must be one of: open, completed, accepted, deferred, rejected");
 }
-function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj {
+export function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj {
   if (!Array.isArray(raw.source_refs)) die("source_refs must be an array");
   if (!Array.isArray(raw.facts)) die("facts must be an array");
   if (!Array.isArray(raw.routing)) die("routing must be an array");
@@ -673,4 +746,11 @@ async function main(): Promise<number> {
   });
 }
 
-main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+// Run the CLI only when executed directly, not when imported as a library.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) {
+  main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+}

package/src/flow-kit/validate.ts

@@ -24,6 +24,47 @@ export interface KitConformanceLevel {
   k2: boolean;
 }
 
+/**
+ * Kit trust level — WHO vouches for a kit, orthogonal to the K-level capability axis.
+ *
+ * - "first-party": the kit is authored and published by Kontour (kontourai); its id is in the
+ *   FIRST_PARTY_KIT_IDS allowlist maintained in this repository. These kits are built, tested,
+ *   and distributed with the flow-agents package.
+ * - "verified": reserved for a future third-party verification process (e.g. self-certification
+ *   via the conformance kit + cryptographic attestation / Veritas claims). Not yet implemented.
+ * - "unverified": default for all kits not in the first-party allowlist. This says nothing about
+ *   the kit's quality — it only means Kontour has not vouched for it.
+ *
+ * The v2 path for "verified": cryptographic signing / attestation against the conformance kit
+ * and Veritas claims substrate is the natural next step and is intentionally deferred.
+ */
+export type KitTrustLevel = "first-party" | "verified" | "unverified";
+
+/**
+ * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
+ *
+ * Criteria for inclusion:
+ *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
+ *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
+ *   3. Kontour owns and maintains the kit's content and release lifecycle.
+ *
+ * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
+ * Third-party forks or community kits published elsewhere are NOT first-party, even if they
+ * share a similar id — first-party is tied to provenance in this specific repository.
+ */
+export const FIRST_PARTY_KIT_IDS: ReadonlySet<string> = new Set(["builder", "knowledge"]);
+
+/**
+ * Derive the trust level for a kit id.
+ *
+ * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
+ * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ */
+export function deriveKitTrust(kitId: string): KitTrustLevel {
+  if (FIRST_PARTY_KIT_IDS.has(kitId)) return "first-party";
+  return "unverified";
+}
+
 export interface KitTargetsResult {
   kit_id: string;
   kit_name: string;
@@ -32,6 +73,11 @@ export interface KitTargetsResult {
   targets: KitTargetConsumer[];
   /** Extension field namespaces that are not Flow or Flow Agents-owned. */
   third_party_extensions: string[];
+  /**
+   * Trust level: who vouches for this kit. Orthogonal to the K-level capability axis.
+   * "first-party" = Kontour-published; "verified" = reserved (future); "unverified" = default.
+   */
+  trust: KitTrustLevel;
 }
 
 // Lazy-loaded cache for validateKitContainer from @kontourai/flow.
@@ -83,7 +129,7 @@ async function delegateCoreContainerValidation(kitDir: string, manifest: Record<
 }
 
 /**
- * Derives the consumer-target level (K0/K1/K2) and target audience list from
+ * Derives the consumer-target level (K0/K1/K2), target audience list, and trust level from
  * observable asset classes in the kit manifest. Does not require file I/O.
  *
  * Derivation rules (from kontourai/flow-agents#52 and Brian's layering review):
@@ -94,6 +140,10 @@ async function delegateCoreContainerValidation(kitDir: string, manifest: Record<
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
  *
+ * Trust derivation (from kontourai/flow-agents#79):
+ *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
+ *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ *
  * @param manifest  The kit.json manifest object.
  * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
  *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
@@ -125,12 +175,16 @@ export async function deriveKitTargets(manifest: Record<string, unknown>, kitDir
   if (k1) targets.push("flow-agents");
   for (const ns of thirdPartyExtensions) targets.push(ns);
 
+  // Derive trust level orthogonally to the K-level capability axis.
+  const trust = deriveKitTrust(kitId);
+
   return {
     kit_id: kitId,
     kit_name: kitName,
     conformance: { k0, k1, k2 },
     targets,
     third_party_extensions: thirdPartyExtensions,
+    trust,
   };
 }
 

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Public library surface for `@kontourai/flow-agents`.
+ *
+ * Native orchestration hosts can import the canonical workflow-sidecar
+ * writer/validator here instead of shelling out to the
+ * `flow-agents-workflow-sidecar` CLI or reimplementing validated
+ * read / merge / write of workflow evidence. This is the same code the CLI
+ * runs — importing it does not execute the CLI.
+ *
+ * The sidecar JSON Schemas ship under `schemas/` and can be validated against
+ * directly; the helpers below are the canonical writer/validator that produce
+ * and check conforming artifacts.
+ *
+ * @module
+ */
+import * as path from "node:path";
+import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
+
+export {
+  // Trust-bundle (Hachure) validation — the same validator the writer uses.
+  validateTrustBundle,
+  // Evidence / check / learning validation + normalization. These throw on
+  // invalid input (with the same messages the CLI surfaces) and return the
+  // normalized object on success.
+  normalizeCheck,
+  normalizeFinding,
+  normalizeLearning,
+  normalizeEvidenceRefs,
+  validateEvidenceRef,
+  validateLearningCorrection,
+  // Sidecar read / merge / write primitives.
+  loadJson,
+  writeJson,
+  appendJsonl,
+  sidecarBase,
+  writeState,
+  // Schema vocabularies (the allowed status/phase/kind values).
+  statuses,
+  phases,
+  checkKinds,
+  checkStatuses,
+  verdicts,
+} from "./cli/workflow-sidecar.js";
+
+/** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */
+export function readSidecar(dir: string, name: string): Record<string, any> {
+  return _loadJson(path.join(dir, name));
+}
+
+/** Write a sidecar JSON file into a workflow artifact directory (pretty-printed, trailing newline). */
+export function writeSidecar(dir: string, name: string, payload: Record<string, any>): void {
+  _writeJson(path.join(dir, name), payload);
+}