@mhingston5/lasso 0.1.0

package/src/failures/generator.ts

@@ -0,0 +1,421 @@
+import type { FailureClass } from "./ontology.js";
+import type { EnvironmentModel } from "../environment/types.js";
+import type { HarnessSpec } from "../spec/types.js";
+
+export interface FailureMode {
+  id: string;
+  description: string;
+  failureClass: FailureClass;
+  probability: "low" | "medium" | "high";
+  triggers: string[];
+  mitigations: string[];
+  recoveryActions: string[];
+}
+
+export interface FailureModeGeneration {
+  taskDescription: string;
+  failureModes: FailureMode[];
+  generatedAt: number;
+  riskSummary: string;
+}
+
+interface PatternRule {
+  keywords: RegExp[];
+  failureClass: FailureClass;
+  description: string;
+  probability: "low" | "medium" | "high";
+  triggers: string[];
+  mitigations: string[];
+  recoveryActions: string[];
+}
+
+const PATTERN_RULES: PatternRule[] = [
+  {
+    keywords: [/deploy/i, /release/i, /publish/i],
+    failureClass: "auth",
+    description: "Authentication failure during deployment",
+    probability: "medium",
+    triggers: ["Expired deployment credentials", "Missing API token", "Insufficient permissions for target environment"],
+    mitigations: ["Verify credentials before deployment", "Use short-lived tokens with refresh"],
+    recoveryActions: ["Refresh deployment credentials", "Check token scopes and permissions"],
+  },
+  {
+    keywords: [/deploy/i, /release/i, /publish/i],
+    failureClass: "network",
+    description: "Network timeout during deployment",
+    probability: "medium",
+    triggers: ["Target service unreachable", "DNS resolution failure", "Firewall blocking outbound traffic"],
+    mitigations: ["Check connectivity before deployment", "Use retry with exponential backoff"],
+    recoveryActions: ["Retry deployment with backoff", "Verify target service health"],
+  },
+  {
+    keywords: [/deploy/i, /release/i, /publish/i],
+    failureClass: "environment-drift",
+    description: "Configuration drift in target environment",
+    probability: "medium",
+    triggers: ["Environment variables changed", "Infrastructure config differs from expected", "Secrets rotated"],
+    mitigations: ["Validate config before deployment", "Use infrastructure-as-code"],
+    recoveryActions: ["Sync configuration to expected state", "Verify environment variables"],
+  },
+  {
+    keywords: [/test/i, /spec/i, /check/i],
+    failureClass: "resource",
+    description: "Test timeout due to resource constraints",
+    probability: "medium",
+    triggers: ["Test exceeds time limit", "Insufficient memory for test runner", "CPU throttling"],
+    mitigations: ["Set appropriate test timeouts", "Allocate sufficient resources"],
+    recoveryActions: ["Increase timeout threshold", "Retry flaky tests with isolation"],
+  },
+  {
+    keywords: [/test/i, /spec/i, /check/i],
+    failureClass: "semantic",
+    description: "Flaky test due to non-deterministic behavior",
+    probability: "medium",
+    triggers: ["Race conditions in test setup", "Shared mutable state", "Order-dependent test failures"],
+    mitigations: ["Isolate test state", "Use deterministic fixtures"],
+    recoveryActions: ["Retry with test isolation", "Review test setup and teardown"],
+  },
+  {
+    keywords: [/test/i, /spec/i, /check/i],
+    failureClass: "environment-drift",
+    description: "Environment mismatch causing test failures",
+    probability: "low",
+    triggers: ["Missing test dependencies", "Different Node.js version", "OS-specific behavior"],
+    mitigations: ["Pin dependency versions", "Use containerized test environment"],
+    recoveryActions: ["Install missing dependencies", "Verify runtime version matches expected"],
+  },
+  {
+    keywords: [/build/i, /compile/i, /bundle/i],
+    failureClass: "environment-drift",
+    description: "Dependency resolution failure during build",
+    probability: "medium",
+    triggers: ["Package registry unavailable", "Version conflict in dependency tree", "Lockfile out of date"],
+    mitigations: ["Use lockfile for reproducible builds", "Cache dependencies locally"],
+    recoveryActions: ["Run dependency install with fresh cache", "Verify package registry availability"],
+  },
+  {
+    keywords: [/build/i, /compile/i, /bundle/i],
+    failureClass: "resource",
+    description: "Disk space exhausted during build",
+    probability: "low",
+    triggers: ["Build artifacts exceed available disk", "Cache directory grows unbounded", "Temporary files not cleaned"],
+    mitigations: ["Monitor disk usage", "Clean build artifacts regularly"],
+    recoveryActions: ["Free disk space and retry build", "Clear build cache"],
+  },
+  {
+    keywords: [/build/i, /compile/i, /bundle/i],
+    failureClass: "resource",
+    description: "Out of memory during build",
+    probability: "low",
+    triggers: ["Build process exceeds memory limit", "Large bundle size", "Memory leak in build tooling"],
+    mitigations: ["Increase Node.js heap size", "Optimize bundle splitting"],
+    recoveryActions: ["Increase memory limit (--max-old-space-size)", "Split build into smaller chunks"],
+  },
+  {
+    keywords: [/merge/i, /rebase/i, /integrate/i],
+    failureClass: "semantic",
+    description: "Merge conflict in source files",
+    probability: "high",
+    triggers: ["Concurrent changes to same files", "Divergent branch history", "Structural refactoring on both branches"],
+    mitigations: ["Rebase frequently", "Communicate changes to shared files"],
+    recoveryActions: ["Resolve conflicts manually", "Use merge tool for complex conflicts"],
+  },
+  {
+    keywords: [/merge/i, /rebase/i, /integrate/i],
+    failureClass: "semantic",
+    description: "Post-merge verification failure",
+    probability: "medium",
+    triggers: ["Combined changes break tests", "Integration incompatibility", "Semantic conflict"],
+    mitigations: ["Run full test suite before merge", "Use CI gates on PR"],
+    recoveryActions: ["Revert merge and investigate", "Fix integration issues"],
+  },
+  {
+    keywords: [/database/i, /migrat/i, /schema/i],
+    failureClass: "network",
+    description: "Database connection timeout",
+    probability: "medium",
+    triggers: ["Database server unreachable", "Connection pool exhausted", "DNS resolution failure for DB host"],
+    mitigations: ["Verify database connectivity", "Use connection pooling with timeouts"],
+    recoveryActions: ["Retry with exponential backoff", "Check database server health"],
+  },
+  {
+    keywords: [/database/i, /migrat/i, /schema/i],
+    failureClass: "semantic",
+    description: "Migration failure due to schema conflict",
+    probability: "medium",
+    triggers: ["Migration script has syntax error", "Existing data violates new constraints", "Migration already partially applied"],
+    mitigations: ["Test migrations on staging first", "Use idempotent migration scripts"],
+    recoveryActions: ["Review migration logs", "Rollback to previous schema version"],
+  },
+  {
+    keywords: [/database/i, /migrat/i, /schema/i],
+    failureClass: "resource",
+    description: "Data corruption risk during migration",
+    probability: "low",
+    triggers: ["Migration interrupted mid-way", "Insufficient disk for migration", "Concurrent writes during migration"],
+    mitigations: ["Take backup before migration", "Schedule maintenance window"],
+    recoveryActions: ["Restore from backup", "Run data integrity checks"],
+  },
+  {
+    keywords: [/api/i, /endpoint/i, /request/i, /fetch/i, /call/i],
+    failureClass: "resource",
+    description: "API rate limit exceeded",
+    probability: "medium",
+    triggers: ["Too many requests in time window", "Shared rate limit across instances", "Burst traffic pattern"],
+    mitigations: ["Implement rate limiting client-side", "Use exponential backoff"],
+    recoveryActions: ["Wait and retry with backoff", "Request rate limit increase"],
+  },
+  {
+    keywords: [/api/i, /endpoint/i, /request/i, /fetch/i, /call/i],
+    failureClass: "auth",
+    description: "API authentication token expired",
+    probability: "medium",
+    triggers: ["Token TTL exceeded", "Clock skew between client and server", "Token not refreshed before expiry"],
+    mitigations: ["Implement token refresh logic", "Use tokens with appropriate TTL"],
+    recoveryActions: ["Refresh authentication token", "Re-authenticate with API"],
+  },
+  {
+    keywords: [/api/i, /endpoint/i, /request/i, /fetch/i, /call/i],
+    failureClass: "semantic",
+    description: "API schema mismatch",
+    probability: "low",
+    triggers: ["API version changed", "Response format differs from expected", "Breaking change in API contract"],
+    mitigations: ["Pin API version", "Validate responses against schema"],
+    recoveryActions: ["Check API changelog for breaking changes", "Update client to match new schema"],
+  },
+  {
+    keywords: [/file/i, /copy/i, /write/i, /read/i, /path/i, /directory/i],
+    failureClass: "tool",
+    description: "File permission denied",
+    probability: "medium",
+    triggers: ["Insufficient file permissions", "File locked by another process", "Read-only filesystem"],
+    mitigations: ["Verify file permissions before operation", "Use appropriate user context"],
+    recoveryActions: ["Fix file permissions", "Run with elevated privileges if appropriate"],
+  },
+  {
+    keywords: [/file/i, /copy/i, /write/i, /read/i, /path/i, /directory/i],
+    failureClass: "resource",
+    description: "Disk full during file operation",
+    probability: "low",
+    triggers: ["No space left on device", "Large file exceeds available space", "Disk quota exceeded"],
+    mitigations: ["Check available disk space", "Clean up temporary files"],
+    recoveryActions: ["Free disk space and retry", "Use external storage if available"],
+  },
+  {
+    keywords: [/file/i, /copy/i, /write/i, /read/i, /path/i, /directory/i],
+    failureClass: "tool",
+    description: "File or path not found",
+    probability: "medium",
+    triggers: ["Path does not exist", "File was deleted or moved", "Incorrect relative path"],
+    mitigations: ["Verify paths before operations", "Use absolute paths when possible"],
+    recoveryActions: ["Check path exists", "Correct the file path"],
+  },
+];
+
+let idCounter = 0;
+
+function generateId(cls: FailureClass, index: number): string {
+  return `gen-${cls}-${index}-${Date.now().toString(36)}`;
+}
+
+function matchesKeywords(description: string, keywords: RegExp[]): boolean {
+  return keywords.some(kw => kw.test(description));
+}
+
+function deduplicate(modes: FailureMode[]): FailureMode[] {
+  const seen = new Map<string, FailureMode>();
+  for (const mode of modes) {
+    const key = `${mode.failureClass}:${mode.description}`;
+    if (!seen.has(key)) {
+      seen.set(key, mode);
+    }
+  }
+  return [...seen.values()];
+}
+
+function applyEnvironmentConstraints(
+  modes: FailureMode[],
+  env: EnvironmentModel,
+): FailureMode[] {
+  const enhanced = [...modes];
+  const constraintClasses = new Set<string>();
+
+  for (const constraint of env.constraints) {
+    if (constraint.type === "auth") {
+      constraintClasses.add("auth");
+      if (!enhanced.some(m => m.failureClass === "auth")) {
+        enhanced.push({
+          id: generateId("auth", enhanced.length),
+          description: `Auth constraint detected: ${constraint.description}`,
+          failureClass: "auth",
+          probability: constraint.severity === "high" ? "high" : "medium",
+          triggers: [constraint.description],
+          mitigations: ["Address auth constraint before execution"],
+          recoveryActions: ["Resolve authentication issue", "Verify credentials"],
+        });
+      }
+    }
+
+    if (constraint.type === "network") {
+      constraintClasses.add("network");
+      if (!enhanced.some(m => m.failureClass === "network")) {
+        enhanced.push({
+          id: generateId("network", enhanced.length),
+          description: `Network constraint detected: ${constraint.description}`,
+          failureClass: "network",
+          probability: constraint.severity === "high" ? "high" : "medium",
+          triggers: [constraint.description],
+          mitigations: ["Verify network connectivity before execution"],
+          recoveryActions: ["Check network access", "Retry with backoff"],
+        });
+      }
+    }
+
+    if (constraint.type === "rate-limit") {
+      if (!enhanced.some(m => m.description.toLowerCase().includes("rate"))) {
+        enhanced.push({
+          id: generateId("resource", enhanced.length),
+          description: `Rate limit constraint detected: ${constraint.description}`,
+          failureClass: "resource",
+          probability: constraint.severity === "high" ? "high" : "medium",
+          triggers: [constraint.description],
+          mitigations: ["Implement client-side rate limiting"],
+          recoveryActions: ["Wait and retry with backoff"],
+        });
+      }
+    }
+  }
+
+  for (const resource of env.resources) {
+    if (!resource.available) {
+      if (!enhanced.some(m => m.failureClass === "resource" && m.description.toLowerCase().includes(resource.type))) {
+        enhanced.push({
+          id: generateId("resource", enhanced.length),
+          description: `Resource unavailable: ${resource.name} (${resource.type})`,
+          failureClass: "resource",
+          probability: "high",
+          triggers: [`${resource.type} resource is not available`],
+          mitigations: [`Provision ${resource.name} before execution`],
+          recoveryActions: [`Free up ${resource.type} resource`, "Retry after resource cleanup"],
+        });
+      }
+    }
+  }
+
+  for (const auth of env.authState) {
+    if (!auth.authenticated) {
+      if (!enhanced.some(m => m.failureClass === "auth" && m.description.toLowerCase().includes(auth.system.toLowerCase()))) {
+        enhanced.push({
+          id: generateId("auth", enhanced.length),
+          description: `Not authenticated with ${auth.system}`,
+          failureClass: "auth",
+          probability: "high",
+          triggers: [`${auth.system} authentication missing or expired`],
+          mitigations: [`Authenticate with ${auth.system} before execution`],
+          recoveryActions: [`Authenticate with ${auth.system}`, "Check credentials"],
+        });
+      }
+    }
+  }
+
+  // Boost probability when env constraints match existing modes
+  for (const mode of enhanced) {
+    if (mode.probability !== "high") {
+      if (mode.failureClass === "auth" && (env.constraints.some(c => c.type === "auth") || env.authState.some(a => !a.authenticated))) {
+        mode.probability = "high";
+      }
+      if (mode.failureClass === "network" && env.constraints.some(c => c.type === "network")) {
+        mode.probability = "high";
+      }
+      if (mode.failureClass === "resource" && env.resources.some(r => !r.available)) {
+        mode.probability = "high";
+      }
+    }
+  }
+
+  return enhanced;
+}
+
+function buildRiskSummary(modes: FailureMode[]): string {
+  if (modes.length === 0) {
+    return "No significant risks identified.";
+  }
+
+  const high = modes.filter(m => m.probability === "high");
+  const medium = modes.filter(m => m.probability === "medium");
+  const low = modes.filter(m => m.probability === "low");
+
+  const parts: string[] = [];
+
+  if (high.length > 0) {
+    const classes = [...new Set(high.map(m => m.failureClass))];
+    parts.push(`${high.length} high-probability risk(s) in ${classes.join(", ")}`);
+  }
+  if (medium.length > 0) {
+    parts.push(`${medium.length} medium-probability risk(s)`);
+  }
+  if (low.length > 0) {
+    parts.push(`${low.length} low-probability risk(s)`);
+  }
+
+  const classCounts = new Map<FailureClass, number>();
+  for (const mode of modes) {
+    classCounts.set(mode.failureClass, (classCounts.get(mode.failureClass) ?? 0) + 1);
+  }
+  const topClasses = [...classCounts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([cls, count]) => `${cls}(${count})`);
+
+  return `${parts.join("; ")}. Top categories: ${topClasses.join(", ")}.`;
+}
+
+export function generateFailureModes(
+  taskDescription: string,
+  env?: EnvironmentModel,
+  spec?: HarnessSpec,
+): FailureModeGeneration {
+  const matchedModes: FailureMode[] = [];
+
+  for (const rule of PATTERN_RULES) {
+    if (matchesKeywords(taskDescription, rule.keywords)) {
+      matchedModes.push({
+        id: generateId(rule.failureClass, matchedModes.length),
+        description: rule.description,
+        failureClass: rule.failureClass,
+        probability: rule.probability,
+        triggers: [...rule.triggers],
+        mitigations: [...rule.mitigations],
+        recoveryActions: [...rule.recoveryActions],
+      });
+    }
+  }
+
+  // For empty/unknown descriptions, add a baseline unknown mode
+  if (matchedModes.length === 0) {
+    matchedModes.push({
+      id: generateId("unknown", 0),
+      description: "Unrecognized task pattern — general execution risk",
+      failureClass: "unknown",
+      probability: "low",
+      triggers: ["Task description does not match known patterns"],
+      mitigations: ["Review task requirements carefully"],
+      recoveryActions: ["Collect diagnostic information", "Escalate if unresolved"],
+    });
+  }
+
+  let failureModes = deduplicate(matchedModes);
+
+  if (env) {
+    failureModes = applyEnvironmentConstraints(failureModes, env);
+  }
+
+  const riskSummary = buildRiskSummary(failureModes);
+
+  return {
+    taskDescription,
+    failureModes,
+    generatedAt: Date.now(),
+    riskSummary,
+  };
+}

package/src/failures/map-reference-failures.ts

@@ -0,0 +1,23 @@
+import type { FailureRecord } from "./types.js";
+
+const WORKFLOW_FAILURE_MAPPING: Record<string, FailureRecord["rootCause"]> = {
+  "apply-failed": "dependency_failure",
+  "candidate-failed": "invalid_output",
+  "reject-human": "human_block",
+};
+
+export function mapReferenceFailure(
+  domainType: string,
+  workflowFailureType: string,
+  nodeId: string,
+  message: string,
+): FailureRecord {
+  const rootCause = WORKFLOW_FAILURE_MAPPING[workflowFailureType] ?? "unknown";
+  
+  return {
+    domainType,
+    rootCause,
+    nodeId,
+    message,
+  };
+}

package/src/failures/ontology.ts

@@ -0,0 +1,210 @@
+import type { FailureRecord } from "./types.js";
+import {
+  classifyAuthFailure,
+  classifyToolFailure,
+  classifyResourceFailure,
+  classifySemanticFailure,
+  classifyHumanFailure,
+  classifyEnvironmentDriftFailure,
+  classifyNetworkFailure,
+} from "./classifiers.js";
+
+export interface FailureClassification {
+  category: "transient" | "permanent";
+  retryable: boolean;
+}
+
+export function classifyFailureRecord(failure: FailureRecord): FailureClassification {
+  switch (failure.rootCause) {
+    case "tool_timeout":
+    case "rate_limited":
+    case "unknown":
+      return { category: "transient", retryable: true };
+
+    case "auth_required":
+    case "invalid_output":
+    case "dependency_failure":
+    case "verification_failed":
+    case "human_block":
+      return { category: "permanent", retryable: false };
+
+    default:
+      return { category: "transient", retryable: true };
+  }
+}
+
+export function isRetryableFailure(failure: FailureRecord): boolean {
+  return classifyFailureRecord(failure).retryable;
+}
+
+export type FailureClass =
+  | "auth"
+  | "tool"
+  | "resource"
+  | "semantic"
+  | "human"
+  | "environment-drift"
+  | "network"
+  | "unknown";
+
+export interface FailureContext {
+  nodeId?: string;
+  attemptNumber?: number;
+  harnessName?: string;
+}
+
+export interface FailureSignature {
+  class: FailureClass;
+  confidence: number;
+  evidence: string[];
+  suggestedRecovery: string[];
+  retryable: boolean;
+  requiresHumanIntervention: boolean;
+}
+
+const CLASS_RECOVERY_MAP: Record<FailureClass, string[]> = {
+  auth: [
+    "Refresh or re-obtain authentication credentials",
+    "Check token expiry and renew if necessary",
+    "Verify API keys or secrets are correctly configured",
+  ],
+  tool: [
+    "Verify tool is installed and available in PATH",
+    "Check tool version compatibility",
+    "Review tool exit code and stderr for details",
+  ],
+  resource: [
+    "Check available disk space and clean up if necessary",
+    "Review memory usage and increase limits if needed",
+    "Implement rate limiting or backoff for API calls",
+  ],
+  semantic: [
+    "Review output format and validate against expected schema",
+    "Check input data for correctness",
+    "Add validation step before processing",
+  ],
+  human: [
+    "Escalate to human operator for review",
+    "Reconsider the proposed changes",
+    "Provide additional context for human decision",
+  ],
+  "environment-drift": [
+    "Sync environment dependencies to expected versions",
+    "Install missing dependencies",
+    "Verify configuration matches expected state",
+  ],
+  network: [
+    "Retry the operation with exponential backoff",
+    "Check network connectivity and DNS resolution",
+    "Verify target service is reachable",
+  ],
+  unknown: [
+    "Collect additional diagnostic information",
+    "Review logs for root cause analysis",
+    "Escalate to human operator if unresolved",
+  ],
+};
+
+const CLASS_RETRYABLE_MAP: Record<FailureClass, boolean> = {
+  auth: false,
+  tool: false,
+  resource: true,
+  semantic: false,
+  human: false,
+  "environment-drift": false,
+  network: true,
+  unknown: false,
+};
+
+const CLASS_REQUIRES_HUMAN_MAP: Record<FailureClass, boolean> = {
+  auth: true,
+  tool: false,
+  resource: false,
+  semantic: true,
+  human: true,
+  "environment-drift": true,
+  network: false,
+  unknown: true,
+};
+
+const CLASS_CONFIDENCE_BASE: Record<FailureClass, number> = {
+  auth: 0.9,
+  tool: 0.85,
+  resource: 0.9,
+  semantic: 0.85,
+  human: 0.85,
+  "environment-drift": 0.8,
+  network: 0.9,
+  unknown: 0.1,
+};
+
+export function classifyFailure(
+  error: unknown,
+  context?: FailureContext,
+): FailureSignature {
+  const authResult = classifyAuthFailure(error);
+  if (authResult.matched) {
+    return buildSignature("auth", authResult, context);
+  }
+
+  const toolResult = classifyToolFailure(error);
+  if (toolResult.matched) {
+    return buildSignature("tool", toolResult, context);
+  }
+
+  const resourceResult = classifyResourceFailure(error);
+  if (resourceResult.matched) {
+    return buildSignature("resource", resourceResult, context);
+  }
+
+  const semanticResult = classifySemanticFailure(error);
+  if (semanticResult.matched) {
+    return buildSignature("semantic", semanticResult, context);
+  }
+
+  const humanResult = classifyHumanFailure(error);
+  if (humanResult.matched) {
+    return buildSignature("human", humanResult, context);
+  }
+
+  const envDriftResult = classifyEnvironmentDriftFailure(error);
+  if (envDriftResult.matched) {
+    return buildSignature("environment-drift", envDriftResult, context);
+  }
+
+  const networkResult = classifyNetworkFailure(error);
+  if (networkResult.matched) {
+    return buildSignature("network", networkResult, context);
+  }
+
+  return buildSignature("unknown", { matched: false, evidence: [] }, context);
+}
+
+function buildSignature(
+  cls: FailureClass,
+  classifierResult: { matched: boolean; evidence: string[] },
+  context?: FailureContext,
+): FailureSignature {
+  const evidence = [...classifierResult.evidence];
+
+  if (context?.nodeId) {
+    evidence.push(`node: ${context.nodeId}`);
+  }
+
+  if (context?.attemptNumber !== undefined) {
+    evidence.push(`attempt: ${context.attemptNumber}`);
+  }
+
+  const confidence = classifierResult.matched
+    ? CLASS_CONFIDENCE_BASE[cls]
+    : CLASS_CONFIDENCE_BASE.unknown;
+
+  return {
+    class: cls,
+    confidence,
+    evidence,
+    suggestedRecovery: CLASS_RECOVERY_MAP[cls],
+    retryable: CLASS_RETRYABLE_MAP[cls],
+    requiresHumanIntervention: CLASS_REQUIRES_HUMAN_MAP[cls],
+  };
+}