agent-contracts 0.11.6 → 0.11.8

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";
@@ -1204,6 +1210,22 @@ declare class ConfigLoadError extends Error {
 declare function loadConfig(configPath?: string): Promise<ResolvedConfig | null>;
 declare function resolveDslPath(dirArg: string | undefined, dirArgDefault: string, config: ResolvedConfig | null): string;
 
+interface DimensionResult {
+    id: string;
+    label: string;
+    score: number;
+    total: number;
+    percent: number;
+    weight: number;
+    recommendations: string[];
+}
+interface ScoreResult {
+    overall: number;
+    dimensions: DimensionResult[];
+}
+
+declare function score(dsl: Dsl): ScoreResult;
+
 interface ResolvedCheck {
     guardrail_id: string;
     guardrail: Guardrail;
@@ -1259,4 +1281,4 @@ interface PathResolveResult {
 }
 declare function resolveBindingTargetPath(target: string, paths: Record<string, string>, bindingSoftware: string): PathResolveResult;
 
-export { type Agent, type AgentContractsConfig, AgentContractsConfigSchema, AgentSchema, type AppendOperator, AppendOperatorSchema, type Artifact, ArtifactSchema, BaseResolveError, type BindingOutput, BindingOutputSchema, CONTEXT_TYPES, type Check, CheckSchema, type Command, CommandSchema, type Components, ComponentsSchema, ConfigLoadError, type ContextType, ContextTypeSchema, type DelegatableTaskView, type DiagnosticMessage, type Dsl, DslLoadError, DslSchema, type EscalationCriterion, EscalationCriterionSchema, type ExecutionStep, ExecutionStepSchema, type Extends, ExtendsSchema, type ExternalParticipant, type GenerateDiagnostic, type GenerateGuardrailsOptions, type GenerateResult, type GlobalContext, type Guardrail, type GuardrailGenerationContext, type GuardrailPolicy, type GuardrailPolicyRule, type GuardrailPolicyRuleEscalation, GuardrailPolicyRuleEscalationSchema, GuardrailPolicyRuleSchema, GuardrailPolicySchema, GuardrailSchema, type GuardrailScope, GuardrailScopeSchema, type HandoffType, HandoffTypeSchema, type InsertAfterOperator, InsertAfterOperatorSchema, type LintDiagnostic, type LintRule, type LoadResult, type LoadedBinding, type Matcher, MatcherSchema, MergeError, type MergeableRecord, type MergedBehavioralSpec, type PathResolveResult, type PerAgentContext, type PerArtifactContext, type PerGuardrailContext, type PerGuardrailPolicyContext, type PerHandoffTypeContext, type PerPolicyContext, type PerTaskContext, type PerToolContext, type PerValidationContext, type PerWorkflowContext, type Policy, PolicySchema, type PolicyWhen, PolicyWhenSchema, type PrependOperator, PrependOperatorSchema, type Prerequisite, PrerequisiteSchema, type ReferenceDiagnostic, type RemoveOperator, RemoveOperatorSchema, type RenderTarget, RenderTargetSchema, type ReplaceOperator, ReplaceOperatorSchema, type Reporting, ReportingSchema, type ResolveChecksResult, type ResolveResult, type ResolvedCheck, type ResolvedConfig, type ResolvedRenderTarget, type Retry, type Rule, RuleSchema, type SchemaValidationResult, type Severity, type SoftwareBinding, SoftwareBindingSchema, type System, type SystemContext, SystemSchema, type Task, TaskSchema, type Tool, ToolSchema, type Validation, ValidationSchema, type VersionLiteral, VersionLiteralSchema, type Workflow, WorkflowSchema, type WorkflowStep, WorkflowStepSchema, type XExtensionDecl, XExtensionDeclSchema, buildArtifactContext, buildGlobalContext, buildGuardrailContext, buildGuardrailPolicyContext, buildHandoffTypeContext, buildPerAgentContext, buildPolicyContext, buildSystemContext, buildTaskContext, buildToolContext, buildValidationContext, buildWorkflowContext, builtinRules, checkDriftFromConfig, checkReferences, expandDefaults, generateGuardrails, lint, loadBindings, loadConfig, loadDsl, mergeDsl, renderFromConfig, resolve, resolveAllOf, resolveBase, resolveBindingTargetPath, resolveChecks, resolveDslPath, spectralLint, validateHandoffSchemas, validateSchema, yamlReservedKeySafetyRule };
+export { type Agent, type AgentContractsConfig, AgentContractsConfigSchema, AgentSchema, type AppendOperator, AppendOperatorSchema, type Artifact, ArtifactSchema, BaseResolveError, type BindingOutput, BindingOutputSchema, CONTEXT_TYPES, type Check, CheckSchema, type Command, CommandSchema, type Components, ComponentsSchema, ConfigLoadError, type ContextType, ContextTypeSchema, type DelegatableTaskView, type DiagnosticMessage, type DimensionResult, type Dsl, DslLoadError, DslSchema, type EscalationCriterion, EscalationCriterionSchema, type ExecutionStep, ExecutionStepSchema, type Extends, ExtendsSchema, type ExternalParticipant, type GenerateDiagnostic, type GenerateGuardrailsOptions, type GenerateResult, type GlobalContext, type Guardrail, type GuardrailGenerationContext, type GuardrailPolicy, type GuardrailPolicyRule, type GuardrailPolicyRuleEscalation, GuardrailPolicyRuleEscalationSchema, GuardrailPolicyRuleSchema, GuardrailPolicySchema, GuardrailSchema, type GuardrailScope, GuardrailScopeSchema, type HandoffType, HandoffTypeSchema, type InsertAfterOperator, InsertAfterOperatorSchema, type LintDiagnostic, type LintRule, type LoadResult, type LoadedBinding, type Matcher, MatcherSchema, MergeError, type MergeableRecord, type MergedBehavioralSpec, type PathResolveResult, type PerAgentContext, type PerArtifactContext, type PerGuardrailContext, type PerGuardrailPolicyContext, type PerHandoffTypeContext, type PerPolicyContext, type PerTaskContext, type PerToolContext, type PerValidationContext, type PerWorkflowContext, type Policy, PolicySchema, type PolicyWhen, PolicyWhenSchema, type PrependOperator, PrependOperatorSchema, type Prerequisite, PrerequisiteSchema, type ReferenceDiagnostic, type RemoveOperator, RemoveOperatorSchema, type RenderTarget, RenderTargetSchema, type ReplaceOperator, ReplaceOperatorSchema, type Reporting, ReportingSchema, type ResolveChecksResult, type ResolveResult, type ResolvedCheck, type ResolvedConfig, type ResolvedRenderTarget, type Retry, type Rule, RuleSchema, type SchemaValidationResult, type ScoreResult, type Severity, type SoftwareBinding, SoftwareBindingSchema, type System, type SystemContext, SystemSchema, type Task, TaskSchema, type Tool, ToolSchema, type Validation, ValidationSchema, type VersionLiteral, VersionLiteralSchema, type Workflow, WorkflowSchema, type WorkflowStep, WorkflowStepSchema, type XExtensionDecl, XExtensionDeclSchema, buildArtifactContext, buildGlobalContext, buildGuardrailContext, buildGuardrailPolicyContext, buildHandoffTypeContext, buildPerAgentContext, buildPolicyContext, buildSystemContext, buildTaskContext, buildToolContext, buildValidationContext, buildWorkflowContext, builtinRules, checkDriftFromConfig, checkReferences, expandDefaults, generateGuardrails, lint, loadBindings, loadConfig, loadDsl, mergeDsl, renderFromConfig, resolve, resolveAllOf, resolveBase, resolveBindingTargetPath, resolveChecks, resolveDslPath, score, spectralLint, validateHandoffSchemas, validateSchema, yamlReservedKeySafetyRule };

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 = [];
@@ -54544,6 +54607,271 @@ ${issues}`,
   return results;
 }
 
+// src/scorer/scorer.ts
+function pct(n3, d2) {
+  return d2 === 0 ? 100 : Math.round(n3 / d2 * 100);
+}
+function artifactValidationCoverage(dsl) {
+  const entries = Object.entries(dsl.artifacts);
+  const total = entries.length;
+  const covered = entries.filter(
+    ([, a3]) => a3.required_validations.length > 0
+  ).length;
+  const missing = entries.filter(([, a3]) => a3.required_validations.length === 0).map(([id]) => id);
+  return {
+    id: "artifact-validation-coverage",
+    label: "Artifact validation coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 3,
+    recommendations: missing.length > 0 ? [`${missing.length} artifacts missing required_validations: ${missing.join(", ")}`] : []
+  };
+}
+function taskValidationCoverage(dsl) {
+  const entries = Object.entries(dsl.tasks);
+  const total = entries.length;
+  const covered = entries.filter(([, t3]) => t3.validations.length > 0).length;
+  const missing = entries.filter(([, t3]) => t3.validations.length === 0).map(([id]) => id);
+  return {
+    id: "task-validation-coverage",
+    label: "Task validation coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 3,
+    recommendations: missing.length > 0 ? [`${missing.length} tasks missing validations: ${missing.join(", ")}`] : []
+  };
+}
+function guardrailPolicyCoverage(dsl) {
+  const guardrailIds = Object.keys(dsl.guardrails);
+  const total = guardrailIds.length;
+  const referenced = /* @__PURE__ */ new Set();
+  for (const policy of Object.values(dsl.guardrail_policies)) {
+    for (const rule of policy.rules) {
+      referenced.add(rule.guardrail);
+    }
+  }
+  const covered = guardrailIds.filter((id) => referenced.has(id)).length;
+  const missing = guardrailIds.filter((id) => !referenced.has(id));
+  return {
+    id: "guardrail-policy-coverage",
+    label: "Guardrail policy coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 2,
+    recommendations: missing.length > 0 ? [`${missing.length} guardrails not in any policy: ${missing.join(", ")}`] : []
+  };
+}
+function workflowValidationIntegration(dsl) {
+  const blockingValidations = Object.entries(dsl.validations).filter(
+    ([, v2]) => v2.blocking
+  );
+  const total = blockingValidations.length;
+  const referenced = /* @__PURE__ */ new Set();
+  for (const wf of Object.values(dsl.workflow)) {
+    for (const step of wf.steps) {
+      if (step.type === "validation") {
+        referenced.add(step.validation);
+      }
+    }
+  }
+  for (const task of Object.values(dsl.tasks)) {
+    for (const valId of task.validations) {
+      referenced.add(valId);
+    }
+  }
+  const covered = blockingValidations.filter(
+    ([id]) => referenced.has(id)
+  ).length;
+  const missing = blockingValidations.filter(([id]) => !referenced.has(id)).map(([id]) => id);
+  return {
+    id: "workflow-validation-integration",
+    label: "Workflow validation integration",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 3,
+    recommendations: missing.length > 0 ? [`${missing.length} blocking validations not wired: ${missing.join(", ")}`] : []
+  };
+}
+var OPTIONAL_ENTITY_FIELDS = {
+  agents: {
+    section: "agents",
+    fields: ["responsibilities", "constraints", "rules"]
+  },
+  tasks: {
+    section: "tasks",
+    fields: ["description", "responsibilities", "execution_steps", "completion_criteria"]
+  },
+  artifacts: {
+    section: "artifacts",
+    fields: ["description", "visibility"]
+  },
+  tools: {
+    section: "tools",
+    fields: ["description", "commands"]
+  },
+  workflow: {
+    section: "workflow",
+    fields: ["description", "trigger", "entry_conditions"]
+  },
+  guardrails: {
+    section: "guardrails",
+    fields: ["rationale", "tags"]
+  }
+};
+function hasNonEmpty(obj, field) {
+  const val = obj[field];
+  if (val === void 0 || val === null) return false;
+  if (typeof val === "string") return val.length > 0;
+  if (Array.isArray(val)) return val.length > 0;
+  return true;
+}
+function schemaCompleteness(dsl) {
+  let totalSlots = 0;
+  let filledSlots = 0;
+  const lowSections = [];
+  for (const [sectionKey, meta] of Object.entries(OPTIONAL_ENTITY_FIELDS)) {
+    const entities = dsl[meta.section];
+    if (!entities) continue;
+    let sectionTotal = 0;
+    let sectionFilled = 0;
+    for (const entity of Object.values(entities)) {
+      for (const field of meta.fields) {
+        sectionTotal++;
+        totalSlots++;
+        if (hasNonEmpty(entity, field)) {
+          sectionFilled++;
+          filledSlots++;
+        }
+      }
+    }
+    if (sectionTotal > 0 && pct(sectionFilled, sectionTotal) < 50) {
+      lowSections.push(sectionKey);
+    }
+  }
+  return {
+    id: "schema-completeness",
+    label: "Schema completeness",
+    score: filledSlots,
+    total: totalSlots,
+    percent: pct(filledSlots, totalSlots),
+    weight: 1,
+    recommendations: lowSections.length > 0 ? [`Low optional field coverage in: ${lowSections.join(", ")}`] : []
+  };
+}
+function crossReferenceBidirectionality(dsl) {
+  let totalChecks = 0;
+  let passedChecks = 0;
+  const issues = [];
+  for (const [agentId, agent] of Object.entries(dsl.agents)) {
+    for (const toolId of agent.can_execute_tools) {
+      totalChecks++;
+      const tool = dsl.tools[toolId];
+      if (tool && tool.invokable_by.includes(agentId)) {
+        passedChecks++;
+      } else {
+        issues.push(`agent ${agentId} \u2192 tool ${toolId}`);
+      }
+    }
+    for (const artId of agent.can_write_artifacts) {
+      totalChecks++;
+      const art = dsl.artifacts[artId];
+      if (art && (art.producers.includes(agentId) || art.editors.includes(agentId))) {
+        passedChecks++;
+      } else {
+        issues.push(`agent ${agentId} \u2192 artifact ${artId} (write)`);
+      }
+    }
+    for (const artId of agent.can_read_artifacts) {
+      totalChecks++;
+      const art = dsl.artifacts[artId];
+      if (art && (art.consumers.includes(agentId) || art.producers.includes(agentId) || art.editors.includes(agentId))) {
+        passedChecks++;
+      } else {
+        issues.push(`agent ${agentId} \u2192 artifact ${artId} (read)`);
+      }
+    }
+  }
+  for (const [toolId, tool] of Object.entries(dsl.tools)) {
+    for (const agentId of tool.invokable_by) {
+      totalChecks++;
+      const agent = dsl.agents[agentId];
+      if (agent && agent.can_execute_tools.includes(toolId)) {
+        passedChecks++;
+      } else {
+        issues.push(`tool ${toolId} \u2192 agent ${agentId}`);
+      }
+    }
+  }
+  return {
+    id: "cross-reference-bidirectionality",
+    label: "Cross-reference bidirectionality",
+    score: passedChecks,
+    total: totalChecks,
+    percent: pct(passedChecks, totalChecks),
+    weight: 2,
+    recommendations: issues.length > 0 ? [`${issues.length} unreciprocated cross-references: ${issues.slice(0, 5).join(", ")}${issues.length > 5 ? `, ... (${issues.length - 5} more)` : ""}`] : []
+  };
+}
+function guardrailScopeResolution(dsl) {
+  let totalRefs = 0;
+  let resolvedRefs = 0;
+  const unresolved = [];
+  const sectionMap = {
+    agents: dsl.agents,
+    tasks: dsl.tasks,
+    tools: dsl.tools,
+    artifacts: dsl.artifacts,
+    workflows: dsl.workflow
+  };
+  for (const [guardrailId, guardrail] of Object.entries(dsl.guardrails)) {
+    const scope = guardrail.scope;
+    for (const [scopeKey, entityIds] of Object.entries(scope)) {
+      if (!Array.isArray(entityIds)) continue;
+      const section = sectionMap[scopeKey];
+      if (!section) continue;
+      for (const entityId of entityIds) {
+        totalRefs++;
+        if (section[entityId]) {
+          resolvedRefs++;
+        } else {
+          unresolved.push(`${guardrailId}.scope.${scopeKey}: ${entityId}`);
+        }
+      }
+    }
+  }
+  return {
+    id: "guardrail-scope-resolution",
+    label: "Guardrail scope resolution",
+    score: resolvedRefs,
+    total: totalRefs,
+    percent: pct(resolvedRefs, totalRefs),
+    weight: 2,
+    recommendations: unresolved.length > 0 ? [`${unresolved.length} unresolved scope refs: ${unresolved.join(", ")}`] : []
+  };
+}
+function score(dsl) {
+  const dimensions = [
+    artifactValidationCoverage(dsl),
+    taskValidationCoverage(dsl),
+    guardrailPolicyCoverage(dsl),
+    workflowValidationIntegration(dsl),
+    schemaCompleteness(dsl),
+    crossReferenceBidirectionality(dsl),
+    guardrailScopeResolution(dsl)
+  ];
+  const totalWeight = dimensions.reduce((s2, d2) => s2 + d2.weight, 0);
+  const weightedSum = dimensions.reduce(
+    (s2, d2) => s2 + d2.percent * d2.weight,
+    0
+  );
+  const overall = totalWeight === 0 ? 100 : Math.round(weightedSum / totalWeight);
+  return { overall, dimensions };
+}
+
 // src/guardrail-generator/generator.ts
 import { readFile as readFile5, writeFile as writeFile2, mkdir as mkdir2, chmod, unlink as unlink2 } from "fs/promises";
 import { resolve as resolve6, dirname as dirname6 } from "path";
@@ -54856,6 +55184,7 @@ export {
   resolveBindingTargetPath,
   resolveChecks,
   resolveDslPath,
+  score,
   spectralLint,
   validateHandoffSchemas,
   validateSchema,