agent-contracts 0.11.7 → 0.12.0

package/dist/index.d.ts

@@ -346,6 +346,9 @@ declare const DslSchema: z.ZodObject<{
             mechanical: "mechanical";
             semantic: "semantic";
             approval: "approval";
+            provenance: "provenance";
+            traceability: "traceability";
+            fidelity: "fidelity";
         }>;
         executor_type: z.ZodEnum<{
             tool: "tool";
@@ -731,6 +734,9 @@ declare const ValidationSchema: z.ZodObject<{
         mechanical: "mechanical";
         semantic: "semantic";
         approval: "approval";
+        provenance: "provenance";
+        traceability: "traceability";
+        fidelity: "fidelity";
     }>;
     executor_type: z.ZodEnum<{
         tool: "tool";
@@ -1028,8 +1034,18 @@ interface ResolvedConfig {
     paths?: Record<string, string>;
 }
 
-declare function renderFromConfig(dsl: Dsl, renderTargets: ResolvedRenderTarget[]): Promise<string[]>;
-declare function checkDriftFromConfig(dsl: Dsl, renderTargets: ResolvedRenderTarget[]): Promise<{
+interface LoadedBinding {
+    filePath: string;
+    binding: SoftwareBinding;
+}
+declare function loadBindings(bindingPaths: string[]): Promise<LoadedBinding[]>;
+
+interface RenderOptions {
+    loadedBindings?: LoadedBinding[];
+    activeGuardrailPolicy?: string;
+}
+declare function renderFromConfig(dsl: Dsl, renderTargets: ResolvedRenderTarget[], options?: RenderOptions): Promise<string[]>;
+declare function checkDriftFromConfig(dsl: Dsl, renderTargets: ResolvedRenderTarget[], options?: RenderOptions): Promise<{
     hasDrift: boolean;
     diffs: string[];
 }>;
@@ -1048,9 +1064,29 @@ interface GlobalContext {
     guardrail_policies: Dsl["guardrail_policies"];
     [key: string]: unknown;
 }
+interface GuardrailEnforcementEntry {
+    guardrail_id: string;
+    description: string;
+    severity: string;
+    action: string;
+    scoped_agents: string[];
+    scoped_tasks: string[];
+    scoped_workflows: string[];
+    scoped_tools: string[];
+    scoped_artifacts: string[];
+    allow_override: boolean;
+    override_requires: string[];
+    trigger: string | null;
+    escalation: {
+        target: string;
+        condition?: string;
+    } | null;
+}
 interface SystemContext {
     system: System;
     dsl: Dsl;
+    guardrailEnforcement?: GuardrailEnforcementEntry[];
+    bindings?: SoftwareBinding[];
     [key: string]: unknown;
 }
 interface PerTaskContext {
@@ -1177,7 +1213,10 @@ interface PerAgentContext {
     [key: string]: unknown;
 }
 declare function buildGlobalContext(dsl: Dsl): GlobalContext;
-declare function buildSystemContext(dsl: Dsl): SystemContext;
+declare function buildSystemContext(dsl: Dsl, options?: {
+    loadedBindings?: LoadedBinding[];
+    activeGuardrailPolicy?: string;
+}): SystemContext;
 declare function buildTaskContext(dsl: Dsl, taskId: string): PerTaskContext;
 declare function buildArtifactContext(dsl: Dsl, artifactId: string): PerArtifactContext;
 declare function buildToolContext(dsl: Dsl, toolId: string): PerToolContext;
@@ -1191,12 +1230,6 @@ declare function buildPerAgentContext(dsl: Dsl, agent: Agent & {
     id: string;
 }): PerAgentContext;
 
-interface LoadedBinding {
-    filePath: string;
-    binding: SoftwareBinding;
-}
-declare function loadBindings(bindingPaths: string[]): Promise<LoadedBinding[]>;
-
 declare class ConfigLoadError extends Error {
     readonly filePath?: string | undefined;
     constructor(message: string, filePath?: string | undefined);

package/dist/index.js

@@ -50660,7 +50660,7 @@ var ToolSchema = z9.object({
 import { z as z10 } from "zod";
 var ValidationSchema = z10.object({
   target_artifact: z10.string(),
-  kind: z10.enum(["schema", "mechanical", "semantic", "approval"]),
+  kind: z10.enum(["schema", "mechanical", "semantic", "approval", "provenance", "traceability", "fidelity"]),
   executor_type: z10.enum(["tool", "agent"]),
   executor: z10.string(),
   blocking: z10.boolean(),
@@ -52388,6 +52388,68 @@ var taskOutputValidationCompletenessRule = {
   }
 };
 
+// src/linter/rules/semantic-validation-phase-coverage.ts
+var SEMANTIC_KINDS = /* @__PURE__ */ new Set(["semantic", "fidelity"]);
+var semanticValidationPhaseCoverageRule = {
+  id: "semantic-validation-phase-coverage",
+  description: "Semantic and fidelity validations should appear in early workflow phases, not only in late phases.",
+  run(dsl) {
+    const diagnostics = [];
+    const semanticValIds = /* @__PURE__ */ new Set();
+    for (const [valId, val] of Object.entries(dsl.validations)) {
+      if (SEMANTIC_KINDS.has(val.kind)) {
+        semanticValIds.add(valId);
+      }
+    }
+    if (semanticValIds.size === 0) {
+      return diagnostics;
+    }
+    const phaseOrder = dsl.system.default_workflow_order;
+    if (phaseOrder.length < 2) {
+      return diagnostics;
+    }
+    const phaseValidations = /* @__PURE__ */ new Map();
+    for (const phase of phaseOrder) {
+      phaseValidations.set(phase, /* @__PURE__ */ new Set());
+    }
+    for (const [phase, wf] of Object.entries(dsl.workflow)) {
+      if (!phaseValidations.has(phase)) continue;
+      for (const step of wf.steps) {
+        if (step.type === "validation" && semanticValIds.has(step.validation)) {
+          phaseValidations.get(phase).add(step.validation);
+        }
+      }
+    }
+    for (const task of Object.values(dsl.tasks)) {
+      const phase = task.workflow;
+      if (!phaseValidations.has(phase)) continue;
+      for (const valId of task.validations) {
+        if (semanticValIds.has(valId)) {
+          phaseValidations.get(phase).add(valId);
+        }
+      }
+    }
+    const earlyBoundary = Math.ceil(phaseOrder.length / 2);
+    const earlyPhases = phaseOrder.slice(0, earlyBoundary);
+    const latePhases = phaseOrder.slice(earlyBoundary);
+    const earlyHasAny = earlyPhases.some(
+      (p2) => (phaseValidations.get(p2)?.size ?? 0) > 0
+    );
+    const lateWithSemantic = latePhases.filter(
+      (p2) => (phaseValidations.get(p2)?.size ?? 0) > 0
+    );
+    if (!earlyHasAny && lateWithSemantic.length > 0) {
+      diagnostics.push({
+        ruleId: "semantic-validation-phase-coverage",
+        severity: "warning",
+        path: "validations",
+        message: `Semantic validations are only referenced in workflow phases [${lateWithSemantic.join(", ")}]. Consider adding semantic review to earlier phases [${earlyPhases.join(", ")}] to catch issues before implementation.`
+      });
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
@@ -52399,7 +52461,8 @@ var builtinRules = [
   guardrailPolicyCoverageRule,
   yamlReservedKeySafetyRule,
   artifactRequiredValidationWiringRule,
-  taskOutputValidationCompletenessRule
+  taskOutputValidationCompletenessRule,
+  semanticValidationPhaseCoverageRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -53066,8 +53129,52 @@ function buildGlobalContext(dsl) {
     guardrail_policies: dsl.guardrail_policies
   };
 }
-function buildSystemContext(dsl) {
-  return { system: dsl.system, dsl };
+function buildSystemContext(dsl, options) {
+  const ctx = { system: dsl.system, dsl };
+  if (options?.loadedBindings && options.loadedBindings.length > 0) {
+    ctx.bindings = options.loadedBindings.map((lb) => lb.binding);
+    const policyName = options.activeGuardrailPolicy;
+    const policy = policyName ? dsl.guardrail_policies[policyName] : void 0;
+    if (policy) {
+      ctx.guardrailEnforcement = buildGuardrailEnforcement(dsl, policy, options.loadedBindings);
+    }
+  }
+  return ctx;
+}
+function buildGuardrailEnforcement(dsl, policy, loadedBindings) {
+  const entries = [];
+  const bindingTriggers = /* @__PURE__ */ new Map();
+  for (const lb of loadedBindings) {
+    const impl = lb.binding.guardrail_impl ?? {};
+    for (const [guardrailId, gi] of Object.entries(impl)) {
+      for (const check of gi.checks) {
+        if (check.matcher) {
+          bindingTriggers.set(guardrailId, check.matcher.type);
+        }
+      }
+    }
+  }
+  for (const rule of policy.rules) {
+    const guardrail = dsl.guardrails[rule.guardrail];
+    if (!guardrail) continue;
+    const scope = guardrail.scope ?? {};
+    entries.push({
+      guardrail_id: rule.guardrail,
+      description: guardrail.description,
+      severity: rule.severity,
+      action: rule.action,
+      scoped_agents: scope.agents ?? [],
+      scoped_tasks: scope.tasks ?? [],
+      scoped_workflows: scope.workflows ?? [],
+      scoped_tools: scope.tools ?? [],
+      scoped_artifacts: scope.artifacts ?? [],
+      allow_override: rule.allow_override,
+      override_requires: rule.override_requires ?? [],
+      trigger: bindingTriggers.get(rule.guardrail) ?? null,
+      escalation: rule.escalation ? { target: rule.escalation.target, condition: rule.escalation.condition } : null
+    });
+  }
+  return entries;
 }
 function buildTaskContext(dsl, taskId) {
   const taskDef = dsl.tasks[taskId];
@@ -54122,6 +54229,50 @@ Handlebars.registerHelper(
     return generateOverviewFlowchart(dsl);
   }
 );
+Handlebars.registerHelper(
+  "guardrailCoverageMatrix",
+  function() {
+    const enforcement = this["guardrailEnforcement"];
+    if (!enforcement || enforcement.length === 0) return "";
+    const header = "| Guardrail | Severity | Action | Agents | Tasks | Workflows | Tools | Artifacts | Trigger | Override | Escalation |";
+    const divider = "|-----------|----------|--------|--------|-------|-----------|-------|-----------|---------|----------|------------|";
+    const rows = enforcement.map((e3) => {
+      const agents = e3["scoped_agents"]?.join(", ") || "\u2014";
+      const tasks = e3["scoped_tasks"]?.join(", ") || "\u2014";
+      const workflows = e3["scoped_workflows"]?.join(", ") || "\u2014";
+      const tools = e3["scoped_tools"]?.join(", ") || "\u2014";
+      const artifacts = e3["scoped_artifacts"]?.join(", ") || "\u2014";
+      const trigger = e3["trigger"] || "\u2014";
+      const override = e3["allow_override"] ? "yes" : "no";
+      const esc = e3["escalation"];
+      const escalation = esc ? esc["target"] : "\u2014";
+      return `| ${e3["guardrail_id"]} | ${e3["severity"]} | ${e3["action"]} | ${agents} | ${tasks} | ${workflows} | ${tools} | ${artifacts} | ${trigger} | ${override} | ${escalation} |`;
+    });
+    return [header, divider, ...rows].join("\n");
+  }
+);
+Handlebars.registerHelper(
+  "taskGuardrailMatrix",
+  function() {
+    const dsl = this["dsl"];
+    const enforcement = this["guardrailEnforcement"];
+    if (!dsl || !enforcement || enforcement.length === 0) return "";
+    const taskIds = Object.keys(dsl.tasks);
+    if (taskIds.length === 0) return "";
+    const guardrailIds = enforcement.map((e3) => e3["guardrail_id"]);
+    const header = `| Task | ${guardrailIds.join(" | ")} |`;
+    const divider = `|------|${guardrailIds.map(() => "------").join("|")}|`;
+    const rows = taskIds.map((taskId) => {
+      const cells = enforcement.map((e3) => {
+        const scopedTasks = e3["scoped_tasks"];
+        if (scopedTasks.length > 0 && !scopedTasks.includes(taskId)) return "n/a";
+        return e3["action"];
+      });
+      return `| ${taskId} | ${cells.join(" | ")} |`;
+    });
+    return [header, divider, ...rows].join("\n");
+  }
+);
 function getDslSection(dsl, context) {
   const sectionMap = {
     agent: dsl.agents,
@@ -54186,13 +54337,13 @@ async function removeIfExists(filePath) {
   } catch {
   }
 }
-async function renderFromConfig(dsl, renderTargets) {
+async function renderFromConfig(dsl, renderTargets, options) {
   const outputFiles = [];
   for (const target of renderTargets) {
     const templateContent = await loadTemplate(target.template);
     const compiled = Handlebars.compile(templateContent, { noEscape: false });
     if (target.context === "system") {
-      const ctx = buildSystemContext(dsl);
+      const ctx = buildSystemContext(dsl, options);
       const output = compiled(ctx);
       if (target.skip_empty && isEffectivelyEmpty(output)) {
         await removeIfExists(target.output);
@@ -54241,13 +54392,13 @@ function checkExpectedVsExisting(expected, outputPath, skipEmpty, diffs) {
     diffs.push(outputPath);
   });
 }
-async function checkDriftFromConfig(dsl, renderTargets) {
+async function checkDriftFromConfig(dsl, renderTargets, options) {
   const diffs = [];
   for (const target of renderTargets) {
     const templateContent = await loadTemplate(target.template);
     const compiled = Handlebars.compile(templateContent, { noEscape: false });
     if (target.context === "system") {
-      const ctx = buildSystemContext(dsl);
+      const ctx = buildSystemContext(dsl, options);
       const expected = compiled(ctx);
       await checkExpectedVsExisting(expected, target.output, target.skip_empty, diffs);
     } else {