The Compliance Auditor Suite: Testing the Rules Engine

TestingComplianceTypeScriptEngineeringArchitecture
Series Context: NeuroHub Engineering chronicles our journey building the first AI-native operating system for neurodiversity care. This post is part of a deep-dive series exploring our technical challenges scaling an autonomous multi-agent orchestration framework (BotHuddle) to write and test production React code.

The Compliance Auditor Suite: Testing the Rules Engine

The Compliance Engine is the most critical piece of our infrastructure; a single miscalculation could result in severe legal and financial repercussions. Traditional testing wasn't enough to cover the massive matrix of federal, state, and regional rules. We developed the Compliance Auditor Suite to ruthlessly validate our business logic against unimaginable edge cases.

The true heart of the red-tape-ninja application lies deep beneath the surface: the ComplianceEngine. While our React UI is the face of the application, it is ultimately just a dumb terminal that renders the decisions made by the Compliance Engine. A single bug within this domain could mean the difference between a legally funded service for a disabled child and a rejected invoice that plunges a family into debt. To protect this core, we rely heavily on the compliance-auditor.spec.ts suite, an exhaustive gauntlet of tests that pushes our TypeScript engine to its absolute limits.

Architectural Overview of the Compliance Engine

We built the ComplianceEngine using a strict, multi-tiered inheritance model in pure TypeScript. This layered architecture expresses overarching federal laws at the root level, refines them at the state level (such as California's Lanterman Act), and applies pinpoint overrides for individual Regional Centers (like Golden Gate or Alta California).

As detailed in our deep dive on Building the Compliance Engine, we explicitly rejected off-the-shelf BRMS (Business Rule Management Systems) and JSON ASTs stored in DynamoDB in favor of 100% type safety. We don't evaluate strings; we evaluate compiled code. By leaning entirely on the TS compiler, we eliminate an entire class of runtime rule resolution errors. If an AI agent tries to modify a rule and breaks an inheritance chain, the build fails instantly.

Core Architecture: The Builder Pattern and Immutable State

The compliance-auditor.spec.ts suite interacts strictly with immutable Domain Entities constructed via the Builder.build() method. We heavily enforce strict domain builders to ensure no malformed data can even be passed into the rules engine for evaluation.

When writing tests for complex financial compliance, mutability is the enemy. If a test accidentally modifies an entity midway through an evaluation, the results are fundamentally untrustworthy.

const testInvoice = new InvoiceRecordEntityBuilder()
  .setId('inv-12345')
  .setAmount(500.00)
  .setServiceDate(new Date('2026-05-15'))
  .build(); // Validates internal consistency before returning an immutable object

By ensuring every entity is frozen upon construction, our Auditor suite can run thousands of evaluations in parallel without race conditions or state bleed.

Deep Dive into compliance-auditor.spec.ts

We needed specialized testing strategies to cover the vast state space of compliance rules. A standard unit test checking expect(result).toBe(true) is insufficient when Regional Center limits dynamically shift based on historical spending tracked in DynamoDB, the participant's age, and the specific diagnostic codes attached to their profile.

Simulating State Evaluations and Boundary Conditions

The test suite runs thousands of simulated state evaluations rapidly in memory. Since we are dealing with complex financial allocations spread across multiple AppSync requests and DynamoDB tables, precise decimal arithmetic testing is essential. JavaScript's native floating-point math (0.1 + 0.2 === 0.30000000000000004) is disastrous for financial compliance. The Auditor suite specifically tests boundary conditions around budget caps down to the exact penny, ensuring our custom Decimal classes never drop precision.

it('must strictly reject invoices that push the budget over by a single cent', () => {
  const overBudgetInvoice = new InvoiceBuilder().setAmount(100.01).build();
  const auditResult = engine.evaluate(overBudgetInvoice);
  
  expect(auditResult.isValid).toBe(false);
  expect(auditResult.rejectionReason).toBe('EXCEEDS_CAP');
  expect(auditResult.auditTrail).toContain('Failed federal waiver limit check');
});

Mastering Time: Mocking Temporal Realities

Financial compliance is inextricably bound to time. A service authorized in Q1 might be strictly forbidden in Q3 due to changing fiscal year budgets. A provider's credential might expire halfway through a billing cycle. Testing this requires deterministic control over the flow of time within the Node.js test runtime, simulating dates that trigger complex state transitions.

The Auditor suite heavily utilizes temporal mocking to fast-forward and rewind time, verifying that the Compliance Engine correctly applies the precise laws that were active at the exact moment the service was rendered, not when the invoice was submitted.

vi.setSystemTime(new Date('2026-06-30T23:59:59.999Z'));
const result = engine.evaluateRateLimits(service);
expect(result.appliedRateTable).toBe('FY26_RATES');

// Fast forward one millisecond into the new fiscal year
vi.setSystemTime(new Date('2026-07-01T00:00:00.000Z'));
const newResult = engine.evaluateRateLimits(service);
expect(newResult.appliedRateTable).toBe('FY27_RATES');

Uncovering the Unknown: Property-Based Testing

Even with exhaustive unit testing, we couldn't possibly anticipate every combination of edge cases. What if a user submits an invoice for $0.00? What if they submit a negative amount? What if the service date is in the year 1899?

To find unimaginable edge cases, compliance-auditor.spec.ts heavily employs Property-Based Testing using fast-check. Instead of manually coding specific dates or amounts, we define the properties of a valid entity, and the framework generates thousands of randomized, malformed, and extreme entities, feeding them into the engine. We assert that regardless of the input, the engine never crashes, never throws an unhandled exception, and never authorizes an invalid claim.

it('should NEVER authorize an inactive service regardless of amount or date', () => {
  fc.assert(
    fc.property(fc.integer(), fc.date(), (amount, date) => {
      const service = createInactiveService(amount, date);
      const evaluation = engine.evaluate(service);
      
      // The core invariant: Inactive services can never be valid
      expect(evaluation.isAuthorized).toBe(false);
      expect(evaluation.error).toBeUndefined(); // It should handle it gracefully, not crash
    }),
    { numRuns: 10000 } // Run 10,000 permutations
  );
});

The Impact of the Auditor Suite

Before the Auditor Suite, a single typo in a Regional Center rule could silently approve thousands of dollars in invalid claims, requiring massive manual clawbacks and creating legal nightmares. By exhaustively testing the ComplianceEngine in total isolation with property-based fuzzing and temporal manipulation, we ensure that our business rules are mathematically sound before the UI, the GraphQL API, or the AI Assistant ever interacts with them. This suite is our final line of defense against compliance drift, giving our engineering team the ultimate confidence to ship complex regulatory changes at lightning speed.