Module System

TealEngine v1.2 introduces a module system that decomposes governance into independent, composable modules. Each module owns a single governance dimension (secrets, memory, reliability, registry) and runs in parallel with all other active modules.

How It Works

The v1.2 evaluation pipeline follows this sequence:

Resolve — Determine which modules the policy references
Validate — Confirm all required modules are registered
Lazy-init — Initialize modules that haven’t been initialized yet
Dispatch — Run all active modules in parallel (Promise.allSettled / asyncio.gather)
Handle failures — Apply fail-closed defaults for any module that throws
Merge — Combine results using “most restrictive action wins”
Validate — Check the merged Decision against the TEEC registry

Request → [Resolve] → [Validate] → [Lazy-init]
                                        ↓
                              ┌─────────┼─────────┐
                              ↓         ↓         ↓
                          Secrets   Registry  Memory  ...
                              ↓         ↓         ↓
                              └─────────┼─────────┘
                                        ↓
                                    [Merge]
                                        ↓
                                  [TEEC Validate]
                                        ↓
                                    Decision

ModuleRegistry

The ModuleRegistry manages module lifecycle:

Registration

Modules are registered eagerly at engine construction time. Registration does not call init().

import { TealEngineV12, TealSecrets, TealMemory } from 'tealtiger';

const engine = new TealEngineV12({
  policy: {
    secrets: { enabled: true },
    memory: { default_scope: 'session' }
  },
  modules: [
    new TealSecrets(),
    new TealMemory()
  ]
});

Lazy Initialization

Modules are initialized on the first evaluation that references them. If a policy doesn’t reference a module’s dimension, that module is never initialized — saving startup time and resources.

// TealSecrets.init() is called only when the first request
// arrives with a policy that includes a "secrets" key.

Dependency Resolution

The registry maps policy keys to module names using a well-known convention:

Policy Key	Module Name
`secrets`	`tealsecrets`
`memory`	`tealmemory`
`reliability`	`tealreliability`
`registry`	`tealregistry`
`guard`	`tealguard`
`audit`	`tealaudit`
`monitor`	`tealmonitor`

If a policy references a module that isn’t registered, the engine throws a TealConfigError before evaluation begins.

Module Status

Query the status of all registered modules at any time:

const status = engine.getModuleStatus();
// {
//   tealsecrets: { registered: true, initialized: true, version: '1.2.0' },
//   tealmemory:  { registered: true, initialized: false, version: '1.2.0' }
// }

“Most Restrictive Action Wins” Merge

When multiple modules return results, the engine merges them by selecting the most restrictive action. This ensures that if any module flags a concern, the overall decision reflects it.

Action Severity Ranking

Severity	Actions
100 (highest)	`DENY`, `DENY_WRITE`, `DENY_READ`
80	`REQUIRE_APPROVAL`
70	`REDACT`, `REDACT_AND_WRITE`
60	`DEGRADE`, `STORE_SUMMARY_ONLY`
50	`TRANSFORM`
0 (lowest)	`ALLOW`, `ALLOW_WRITE`

Merge Example

If three modules return:

Module	Action	Severity
TealSecrets	`REDACT`	70
TealRegistry	`ALLOW`	0
TealMemory	`DENY_WRITE`	100

The merged result is DENY_WRITE (severity 100). All reason codes from all modules are combined into the final decision.

The merge strategy is intentionally conservative. A single DENY from any module overrides ALLOW from all others. This is a security-first design choice.

Fail-Closed Defaults

If any module throws an exception during evaluation, the engine applies a fail-closed default:

The overall decision becomes DENY
The reason includes which module(s) failed
Failed module names appear in metadata.modules_failed

const engine = new TealEngineV12({
  policy: myPolicy,
  modules: [new TealSecrets(), new TealMemory()],
  failurePolicy: { default: 'FAIL_CLOSED' }  // default
});

You can override this to FAIL_OPEN for non-critical environments:

const engine = new TealEngineV12({
  policy: myPolicy,
  modules: [new TealSecrets()],
  failurePolicy: { default: 'FAIL_OPEN' }
});

FAIL_OPEN should only be used in development or monitoring environments. In production, always use FAIL_CLOSED.

Granular Failure Policies

You can configure failure behavior for specific scenarios:

const engine = new TealEngineV12({
  policy: myPolicy,
  modules: [...],
  failurePolicy: {
    default: 'FAIL_CLOSED',
    memory_adapter_unavailable: { action: 'DENY_WRITE' },
    evidence_sink_unavailable: { action: 'ALLOW' },
    bundle_fetch_failed: { action: 'DENY', allow_cached_bundle: true },
    sarif_export_failed: { action: 'ALLOW', emit_evidence: true }
  }
});

Writing a Custom Module

Implement the TealModule interface to create your own governance module.

TealModule Interface

interface TealModule {
  readonly name: string;
  readonly version: string;

  evaluate(
    request: ModuleEvaluationRequest,
    ctx: ModuleContext,
    policy: unknown
  ): Promise<ModuleResult>;

  init?(config: unknown): Promise<void>;
  destroy?(): Promise<void>;
}

Example: Custom Rate Limiter

import type { TealModule, ModuleEvaluationRequest, ModuleContext, ModuleResult } from 'tealtiger';

class RateLimiterModule implements TealModule {
  readonly name = 'rate-limiter';
  readonly version = '1.0.0';

  private counters = new Map<string, number>();
  private maxRequests = 100;

  async init(config: unknown): Promise<void> {
    const cfg = config as { max_requests?: number };
    this.maxRequests = cfg.max_requests ?? 100;
  }

  async evaluate(
    request: ModuleEvaluationRequest,
    ctx: ModuleContext,
    policy: unknown
  ): Promise<ModuleResult> {
    const key = ctx.agent_id ?? ctx.user_id ?? 'global';
    const count = (this.counters.get(key) ?? 0) + 1;
    this.counters.set(key, count);

    if (count > this.maxRequests) {
      return {
        action: 'DENY',
        reason_codes: ['TOOL_RATE_LIMIT_EXCEEDED'],
        event_type: 'tool.evaluation',
        metadata: { current_count: count, limit: this.maxRequests }
      };
    }

    return {
      action: 'ALLOW',
      reason_codes: ['POLICY_COMPLIANT'],
      event_type: 'policy.evaluation'
    };
  }

  async destroy(): Promise<void> {
    this.counters.clear();
  }
}

Register Your Module

const engine = new TealEngineV12({
  policy: {
    'rate-limiter': { max_requests: 50 }
  },
  modules: [new RateLimiterModule()]
});

Custom modules participate in the same parallel dispatch and merge pipeline as built-in modules. They receive the same ModuleContext and must return a valid ModuleResult.

ModuleContext

Every module receives a ModuleContext with request metadata:

interface ModuleContext {
  correlation_id: string;   // Unique request ID
  tenant_id?: string;       // Multi-tenant isolation
  user_id?: string;         // End user
  session_id?: string;      // Session scope
  agent_id?: string;        // Agent identifier
  policy_version: string;   // Policy version (e.g., "1.2.0")
  teec_version: string;     // TEEC registry version (e.g., "0.1.0")
  timestamp: number;        // Unix ms
}

ModuleResult

Every module must return a ModuleResult:

interface ModuleResult {
  action: DecisionAction;           // The governance action
  reason_codes: string[];           // TEEC reason codes
  event_type: string;               // TEEC event type
  findings?: SecretFinding[];       // Optional (TealSecrets)
  metadata?: Record<string, unknown>; // Optional extra data
}

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

How It Works

ModuleRegistry

Registration

Lazy Initialization

Dependency Resolution

Module Status

“Most Restrictive Action Wins” Merge

Action Severity Ranking

Merge Example

Fail-Closed Defaults

Granular Failure Policies

Writing a Custom Module

TealModule Interface

Example: Custom Rate Limiter

Register Your Module

ModuleContext

ModuleResult

​How It Works

​ModuleRegistry

​Registration

​Lazy Initialization

​Dependency Resolution

​Module Status

​“Most Restrictive Action Wins” Merge

​Action Severity Ranking

​Merge Example

​Fail-Closed Defaults

​Granular Failure Policies

​Writing a Custom Module

​TealModule Interface

​Example: Custom Rate Limiter

​Register Your Module

​ModuleContext

​ModuleResult

​Related Documentation

How It Works

ModuleRegistry

Registration

Lazy Initialization

Dependency Resolution

Module Status

“Most Restrictive Action Wins” Merge

Action Severity Ranking

Merge Example

Fail-Closed Defaults

Granular Failure Policies

Writing a Custom Module

TealModule Interface

Example: Custom Rate Limiter

Register Your Module

ModuleContext

ModuleResult

Related Documentation