outcome-cli 1.0.0

package/src/outcomes/outcome.schema.property.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Property-based tests for Outcome Schema Validation
+ *
+ * **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+ * **Validates: Requirements 1.1, 1.2**
+ *
+ * Property 1: Outcome Schema Validation
+ * *For any* outcome object, validation SHALL accept the object if and only if
+ * it contains all required fields (name, payoutAmount, maxAttempts, timeLimitMs,
+ * successCriteria, failureReasons) with correct types.
+ */
+
+import { describe, test, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { validateOutcome, type Outcome, type SuccessCriterion } from './outcome.schema.js';
+
+/**
+ * Arbitrary for generating non-empty strings (not just whitespace)
+ * The validator requires strings that are non-empty after trimming
+ */
+const nonEmptyStringArb: fc.Arbitrary<string> = fc
+  .tuple(fc.string({ minLength: 1 }), fc.string())
+  .map(([prefix, suffix]) => {
+    // Ensure at least one non-whitespace character
+    const nonWhitespace = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-';
+    const char = nonWhitespace[Math.abs(prefix.charCodeAt(0) || 0) % nonWhitespace.length];
+    return prefix.replace(/^\s*/, '') + char + suffix;
+  })
+  .filter((s) => s.trim().length > 0);
+
+/**
+ * Arbitrary for generating valid SuccessCriterion objects
+ */
+const validSuccessCriterionArb: fc.Arbitrary<SuccessCriterion> = fc.record({
+  name: nonEmptyStringArb,
+  validator: nonEmptyStringArb,
+  params: fc.dictionary(fc.string(), fc.jsonValue()),
+});
+
+/**
+ * Arbitrary for generating valid Outcome objects
+ */
+const validOutcomeArb: fc.Arbitrary<Outcome> = fc.record({
+  name: nonEmptyStringArb,
+  description: fc.string(),
+  payoutAmount: fc.double({ min: 0.01, max: 1_000_000, noNaN: true }),
+  maxAttempts: fc.integer({ min: 1, max: 1000 }),
+  timeLimitMs: fc.integer({ min: 1, max: 86_400_000 }), // up to 24 hours
+  successCriteria: fc.array(validSuccessCriterionArb, { minLength: 1, maxLength: 10 }),
+  failureReasons: fc.array(fc.string(), { minLength: 0, maxLength: 10 }),
+});
+
+describe('Outcome Schema Validation - Property Tests', () => {
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('valid outcomes are accepted', () => {
+    fc.assert(
+      fc.property(validOutcomeArb, (outcome) => {
+        const result = validateOutcome(outcome);
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes missing required fields are rejected', () => {
+    const requiredFields = [
+      'name',
+      'description',
+      'payoutAmount',
+      'maxAttempts',
+      'timeLimitMs',
+      'successCriteria',
+      'failureReasons',
+    ] as const;
+
+    fc.assert(
+      fc.property(
+        validOutcomeArb,
+        fc.constantFrom(...requiredFields),
+        (outcome, fieldToRemove) => {
+          // Create a copy and remove one required field
+          const incompleteOutcome = { ...outcome };
+          delete (incompleteOutcome as Record<string, unknown>)[fieldToRemove];
+
+          const result = validateOutcome(incompleteOutcome);
+          expect(result.valid).toBe(false);
+          expect(result.errors.length).toBeGreaterThan(0);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes with wrong field types are rejected', () => {
+    const wrongTypeValues = [null, undefined, [], 'string', 123, true, {}];
+
+    fc.assert(
+      fc.property(
+        validOutcomeArb,
+        fc.constantFrom('name', 'description', 'payoutAmount', 'maxAttempts', 'timeLimitMs'),
+        fc.constantFrom(...wrongTypeValues),
+        (outcome, field, wrongValue) => {
+          // Skip if the wrong value happens to be the correct type
+          const expectedTypes: Record<string, string> = {
+            name: 'string',
+            description: 'string',
+            payoutAmount: 'number',
+            maxAttempts: 'number',
+            timeLimitMs: 'number',
+          };
+
+          if (typeof wrongValue === expectedTypes[field]) {
+            return; // Skip this case
+          }
+
+          const invalidOutcome = { ...outcome, [field]: wrongValue };
+          const result = validateOutcome(invalidOutcome);
+          expect(result.valid).toBe(false);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes with invalid payoutAmount are rejected', () => {
+    fc.assert(
+      fc.property(
+        validOutcomeArb,
+        fc.constantFrom(0, -1, -100, -0.01),
+        (outcome, invalidPayout) => {
+          const invalidOutcome = { ...outcome, payoutAmount: invalidPayout };
+          const result = validateOutcome(invalidOutcome);
+          expect(result.valid).toBe(false);
+          expect(result.errors.some((e) => e.includes('payoutAmount'))).toBe(true);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes with invalid maxAttempts are rejected', () => {
+    fc.assert(
+      fc.property(
+        validOutcomeArb,
+        fc.constantFrom(0, -1, -100, 1.5, 2.7),
+        (outcome, invalidAttempts) => {
+          const invalidOutcome = { ...outcome, maxAttempts: invalidAttempts };
+          const result = validateOutcome(invalidOutcome);
+          expect(result.valid).toBe(false);
+          expect(result.errors.some((e) => e.includes('maxAttempts'))).toBe(true);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes with invalid timeLimitMs are rejected', () => {
+    fc.assert(
+      fc.property(
+        validOutcomeArb,
+        fc.constantFrom(0, -1, -1000, 1.5, 2.7),
+        (outcome, invalidTimeLimit) => {
+          const invalidOutcome = { ...outcome, timeLimitMs: invalidTimeLimit };
+          const result = validateOutcome(invalidOutcome);
+          expect(result.valid).toBe(false);
+          expect(result.errors.some((e) => e.includes('timeLimitMs'))).toBe(true);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes with empty successCriteria are rejected', () => {
+    fc.assert(
+      fc.property(validOutcomeArb, (outcome) => {
+        const invalidOutcome = { ...outcome, successCriteria: [] };
+        const result = validateOutcome(invalidOutcome);
+        expect(result.valid).toBe(false);
+        expect(result.errors.some((e) => e.includes('successCriteria'))).toBe(true);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('outcomes with empty name are rejected', () => {
+    fc.assert(
+      fc.property(validOutcomeArb, fc.constantFrom('', '   ', '\t', '\n'), (outcome, emptyName) => {
+        const invalidOutcome = { ...outcome, name: emptyName };
+        const result = validateOutcome(invalidOutcome);
+        expect(result.valid).toBe(false);
+        expect(result.errors.some((e) => e.includes('name'))).toBe(true);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('non-object values are rejected', () => {
+    fc.assert(
+      fc.property(fc.constantFrom(null, undefined, 'string', 123, true, []), (invalidValue) => {
+        const result = validateOutcome(invalidValue);
+        expect(result.valid).toBe(false);
+        expect(result.errors.length).toBeGreaterThan(0);
+      }),
+      { numRuns: 100 }
+    );
+  });
+
+  // **Feature: earnd-bounty-engine, Property 1: Outcome Schema Validation**
+  test('validation is deterministic - same input produces same output', () => {
+    fc.assert(
+      fc.property(validOutcomeArb, (outcome) => {
+        const result1 = validateOutcome(outcome);
+        const result2 = validateOutcome(outcome);
+        expect(result1.valid).toBe(result2.valid);
+        expect(result1.errors).toEqual(result2.errors);
+      }),
+      { numRuns: 100 }
+    );
+  });
+});

package/src/outcomes/outcome.schema.ts

@@ -0,0 +1,187 @@
+/**
+ * Outcome Schema - Type definitions and validation for business outcomes
+ *
+ * An Outcome is a declarative, deterministic definition of a business goal
+ * including success criteria, payout amount, and constraints.
+ *
+ * @module outcomes/outcome.schema
+ */
+
+/**
+ * Represents a single success criterion that must be met for an outcome.
+ */
+export interface SuccessCriterion {
+  /** Unique name identifying this criterion */
+  name: string;
+  /** Reference to the validator function name */
+  validator: string;
+  /** Parameters passed to the validator function */
+  params: Record<string, unknown>;
+}
+
+/**
+ * Represents a complete business outcome definition.
+ * Outcomes are deterministic and verifiable.
+ */
+export interface Outcome {
+  /** Unique name identifying this outcome */
+  name: string;
+  /** Human-readable description of the outcome */
+  description: string;
+  /** Amount paid upon successful completion (in dollars) */
+  payoutAmount: number;
+  /** Maximum number of attempts allowed per agent */
+  maxAttempts: number;
+  /** Time limit for achieving the outcome (in milliseconds) */
+  timeLimitMs: number;
+  /** List of criteria that must all pass for success */
+  successCriteria: SuccessCriterion[];
+  /** Predefined failure reasons for structured error reporting */
+  failureReasons: string[];
+}
+
+/**
+ * Result of validating an outcome or its fields.
+ */
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** Error messages if validation failed */
+  errors: string[];
+}
+
+/**
+ * Validates a SuccessCriterion object.
+ *
+ * @param criterion - The criterion to validate
+ * @returns ValidationResult with any errors found
+ */
+function validateSuccessCriterion(criterion: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  if (typeof criterion !== 'object' || criterion === null) {
+    return { valid: false, errors: ['Success criterion must be an object'] };
+  }
+
+  const c = criterion as Record<string, unknown>;
+
+  if (typeof c.name !== 'string' || c.name.trim() === '') {
+    errors.push('Success criterion must have a non-empty string "name"');
+  }
+
+  if (typeof c.validator !== 'string' || c.validator.trim() === '') {
+    errors.push('Success criterion must have a non-empty string "validator"');
+  }
+
+  if (typeof c.params !== 'object' || c.params === null || Array.isArray(c.params)) {
+    errors.push('Success criterion must have an object "params"');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validates an Outcome object against the schema.
+ *
+ * Ensures all required fields are present with correct types:
+ * - name: non-empty string
+ * - description: string
+ * - payoutAmount: positive number
+ * - maxAttempts: positive integer
+ * - timeLimitMs: positive integer
+ * - successCriteria: non-empty array of valid SuccessCriterion
+ * - failureReasons: array of strings
+ *
+ * @param outcome - The outcome object to validate
+ * @returns ValidationResult indicating if the outcome is valid
+ *
+ * @example
+ * const result = validateOutcome(myOutcome);
+ * if (!result.valid) {
+ *   console.error('Invalid outcome:', result.errors);
+ * }
+ */
+export function validateOutcome(outcome: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  // Check if outcome is an object
+  if (typeof outcome !== 'object' || outcome === null) {
+    return { valid: false, errors: ['Outcome must be an object'] };
+  }
+
+  const o = outcome as Record<string, unknown>;
+
+  // Validate name
+  if (typeof o.name !== 'string') {
+    errors.push('Outcome must have a string "name"');
+  } else if (o.name.trim() === '') {
+    errors.push('Outcome "name" must not be empty');
+  }
+
+  // Validate description
+  if (typeof o.description !== 'string') {
+    errors.push('Outcome must have a string "description"');
+  }
+
+  // Validate payoutAmount
+  if (typeof o.payoutAmount !== 'number') {
+    errors.push('Outcome must have a number "payoutAmount"');
+  } else if (o.payoutAmount <= 0) {
+    errors.push('Outcome "payoutAmount" must be positive');
+  } else if (!Number.isFinite(o.payoutAmount)) {
+    errors.push('Outcome "payoutAmount" must be a finite number');
+  }
+
+  // Validate maxAttempts
+  if (typeof o.maxAttempts !== 'number') {
+    errors.push('Outcome must have a number "maxAttempts"');
+  } else if (!Number.isInteger(o.maxAttempts) || o.maxAttempts <= 0) {
+    errors.push('Outcome "maxAttempts" must be a positive integer');
+  }
+
+  // Validate timeLimitMs
+  if (typeof o.timeLimitMs !== 'number') {
+    errors.push('Outcome must have a number "timeLimitMs"');
+  } else if (!Number.isInteger(o.timeLimitMs) || o.timeLimitMs <= 0) {
+    errors.push('Outcome "timeLimitMs" must be a positive integer');
+  }
+
+  // Validate successCriteria
+  if (!Array.isArray(o.successCriteria)) {
+    errors.push('Outcome must have an array "successCriteria"');
+  } else if (o.successCriteria.length === 0) {
+    errors.push('Outcome "successCriteria" must not be empty');
+  } else {
+    o.successCriteria.forEach((criterion, index) => {
+      const criterionResult = validateSuccessCriterion(criterion);
+      if (!criterionResult.valid) {
+        criterionResult.errors.forEach((err) => {
+          errors.push(`successCriteria[${index}]: ${err}`);
+        });
+      }
+    });
+  }
+
+  // Validate failureReasons
+  if (!Array.isArray(o.failureReasons)) {
+    errors.push('Outcome must have an array "failureReasons"');
+  } else {
+    o.failureReasons.forEach((reason, index) => {
+      if (typeof reason !== 'string') {
+        errors.push(`failureReasons[${index}] must be a string`);
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Type guard to check if an unknown value is a valid Outcome.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid Outcome
+ */
+export function isOutcome(value: unknown): value is Outcome {
+  return validateOutcome(value).valid;
+}

package/src/outcomes/qualified_sales_interest.ts

@@ -0,0 +1,118 @@
+/**
+ * Qualified Sales Interest Outcome
+ *
+ * Demo outcome for demonstrating the Earnd Bounty Engine to investors.
+ * An agent achieves this outcome by generating a qualified sales lead
+ * that meets all 5 success criteria.
+ *
+ * @module outcomes/qualified_sales_interest
+ */
+
+import type { Outcome } from './outcome.schema.js';
+
+/**
+ * Payout amount for successfully qualifying a sales interest.
+ * Set to $250 as per Requirements 8.6.
+ */
+export const PAYOUT_AMOUNT = 250;
+
+/**
+ * Maximum number of attempts an agent can make to achieve this outcome.
+ */
+export const MAX_ATTEMPTS = 5;
+
+/**
+ * Time limit for achieving the outcome (5 minutes in milliseconds).
+ */
+export const TIME_LIMIT_MS = 300000;
+
+/**
+ * Keywords that indicate buying intent.
+ * Message must contain at least one of these keywords.
+ */
+export const BUYING_INTENT_KEYWORDS = ['pricing', 'demo', 'next steps'];
+
+/**
+ * Minimum company size required for qualification.
+ */
+export const MIN_COMPANY_SIZE = 50;
+
+/**
+ * Roles that are excluded from qualification.
+ */
+export const EXCLUDED_ROLES = ['intern', 'student'];
+
+/**
+ * Minimum number of words required in the message.
+ */
+export const MIN_MESSAGE_WORDS = 20;
+
+/**
+ * Qualified Sales Interest Outcome Definition
+ *
+ * Success requires meeting ALL 5 criteria:
+ * 1. Message contains buying intent keywords (pricing, demo, next steps)
+ * 2. Company size >= 50 employees
+ * 3. Role is not intern or student
+ * 4. Message length >= 20 words
+ * 5. Email is syntactically valid
+ *
+ * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6
+ */
+export const qualifiedSalesInterest: Outcome = {
+  name: 'qualified_sales_interest',
+  description:
+    'Generate a qualified sales lead by engaging with a prospect who demonstrates buying intent, works at a company of sufficient size, holds a decision-making role, and provides valid contact information.',
+  payoutAmount: PAYOUT_AMOUNT,
+  maxAttempts: MAX_ATTEMPTS,
+  timeLimitMs: TIME_LIMIT_MS,
+  successCriteria: [
+    {
+      // Requirement 8.1: Verify message contains buying intent keywords
+      name: 'buying_intent',
+      validator: 'validateBuyingIntent',
+      params: {
+        keywords: BUYING_INTENT_KEYWORDS,
+      },
+    },
+    {
+      // Requirement 8.2: Verify company size >= 50
+      name: 'company_size',
+      validator: 'validateCompanySize',
+      params: {
+        minimum: MIN_COMPANY_SIZE,
+      },
+    },
+    {
+      // Requirement 8.3: Verify role is not intern or student
+      name: 'valid_role',
+      validator: 'validateRole',
+      params: {
+        excludedRoles: EXCLUDED_ROLES,
+      },
+    },
+    {
+      // Requirement 8.4: Verify message length >= 20 words
+      name: 'message_length',
+      validator: 'validateMessageLength',
+      params: {
+        minWords: MIN_MESSAGE_WORDS,
+      },
+    },
+    {
+      // Requirement 8.5: Verify email is syntactically valid
+      name: 'valid_email',
+      validator: 'validateEmail',
+      params: {},
+    },
+  ],
+  failureReasons: [
+    'No buying intent detected - message must contain: pricing, demo, or next steps',
+    'Company too small - must have at least 50 employees',
+    'Invalid role - interns and students are not qualified leads',
+    'Message too short - must be at least 20 words',
+    'Invalid email format',
+  ],
+};
+
+export default qualifiedSalesInterest;