Skip to main content

​
Migrating to v1.1.x

This guide covers migrating from TealTiger v1.0.x to v1.1.x with Enterprise Adoption Features.

​
Overview

v1.1.x adds five P0 enterprise features:
  1. Policy Rollout Modes - ENFORCE, MONITOR, REPORT_ONLY
  2. Deterministic Decision Contract - Stable typed Decision object
  3. Correlation IDs + Traceability - ExecutionContext for distributed systems
  4. Audit Schema + Redaction - Versioned audit events with security-by-default
  5. Policy Test Harness - CLI/library test runner for CI/CD

​
Backwards Compatibility

v1.1.x is 100% backwards compatible with v1.0.x.
  • All v1.0.x code continues to work
  • New features are opt-in
  • No breaking changes
  • Gradual adoption supported

​
Installation

​
TypeScript

npm install @tealtiger/sdk@^1.1.0

​
Python

pip install tealtiger>=1.1.0

​
Migration Steps

​
Step 1: Update Dependencies

Update your package.json or requirements.txt: 
{
  "dependencies": {
    "@tealtiger/sdk": "^1.1.0"
  }
}

tealtiger>=1.1.0
Before (v1.0.x): 
const decision = await engine.evaluate(request);
After (v1.1.x): 
import { ExecutionContext } from '@tealtiger/sdk';

const context = ExecutionContext.create({
  actor: { id: 'user-123', type: 'user' }
});

const decision = await engine.evaluate(request, context);
Benefits:
  • Correlation IDs for distributed tracing
  • Audit log correlation
  • Request attribution

​
Step 3: Configure Policy Modes (Optional)

Before (v1.0.x): 
const engine = new TealEngine({
  policies: [...]
});
After (v1.1.x): 
import { TealEngine, PolicyMode } from '@tealtiger/sdk';

const engine = new TealEngine({
  policies: [...],
  mode: {
    default: PolicyMode.ENFORCE,
    overrides: {
      'new-policy': PolicyMode.MONITOR // Safe rollout
    }
  }
});
Benefits:
  • Safe policy rollout
  • Production testing without risk
  • Gradual enforcement
Before (v1.0.x): 
const audit = new TealAudit({
  enabled: true
});
After (v1.1.x): 
import { TealAudit, RedactionLevel } from '@tealtiger/sdk';

const audit = new TealAudit({
  enabled: true,
  input_redaction: RedactionLevel.HASH, // Security by default
  output_redaction: RedactionLevel.HASH,
  detect_pii: true
});
Benefits:
  • Security-by-default (no raw prompts in logs)
  • PII detection and redaction
  • Compliance-ready audit logs
New in v1.1.x: 
import { PolicyTester, TestCorpora } from '@tealtiger/sdk/testing';

const tester = new PolicyTester(engine);

const report = await tester.runSuite({
  name: 'Security Policies',
  policy: 'security-policies',
  mode: PolicyMode.ENFORCE,
  tests: TestCorpora.promptInjection()
});

if (report.failed > 0) {
  throw new Error(`${report.failed} tests failed`);
}
Benefits:
  • Regression testing
  • CI/CD integration
  • Policy validation before deployment

​
Feature Adoption Guide

​
Gradual Adoption Path

  1. Week 1: Add ExecutionContext (no behavior change)
  2. Week 2: Enable audit redaction (security improvement)
  3. Week 3: Add policy tests (quality assurance)
  4. Week 4: Configure policy modes for new policies (safe rollout)
  5. Week 5+: Full adoption of all features

​
Minimal Migration (v1.0.x compatibility)

// No changes required - v1.0.x code works as-is
const engine = new TealEngine({ policies: [...] });
const decision = await engine.evaluate(request);

if (decision.action === 'DENY') {
  throw new Error('Denied');
}

import {
  TealEngine,
  TealAudit,
  ExecutionContext,
  PolicyMode,
  RedactionLevel
} from '@tealtiger/sdk';

// Configure engine with modes
const engine = new TealEngine({
  policies: [...],
  mode: {
    default: PolicyMode.ENFORCE,
    environment_overrides: {
      'development': PolicyMode.REPORT_ONLY,
      'staging': PolicyMode.MONITOR
    }
  }
});

// Configure audit with redaction
const audit = new TealAudit({
  enabled: true,
  input_redaction: RedactionLevel.HASH,
  output_redaction: RedactionLevel.HASH,
  detect_pii: true
});

// Create context for traceability
const context = ExecutionContext.create({
  actor: { id: 'user-123', type: 'user' },
  environment: process.env.NODE_ENV
});

// Evaluate with context
const decision = await engine.evaluate(request, context);

// Handle decision
switch (decision.action) {
  case DecisionAction.ALLOW:
    return await makeRequest(request);
  case DecisionAction.DENY:
    throw new PolicyViolationError(decision);
  case DecisionAction.REQUIRE_APPROVAL:
    return await requestApproval(request, decision);
}

// Log with context
await audit.log('policy_evaluation', { decision, context });

​
API Changes

​
New Exports

// Policy Modes
import { PolicyMode, ModeConfig } from '@tealtiger/sdk';

// Decision Contract
import { Decision, DecisionAction, ReasonCode } from '@tealtiger/sdk';

// Execution Context
import { ExecutionContext, ContextManager } from '@tealtiger/sdk';

// Audit & Redaction
import { RedactionLevel, AuditEventType } from '@tealtiger/sdk';

// Policy Testing
import { PolicyTester, TestCorpora } from '@tealtiger/sdk/testing';

​
Updated Interfaces

​
TealEngineConfig

interface TealEngineConfig {
  policies: Policy[];
  mode?: ModeConfig; // New in v1.1.x
}

​
AuditConfig

interface AuditConfig {
  enabled: boolean;
  input_redaction?: RedactionLevel; // New in v1.1.x
  output_redaction?: RedactionLevel; // New in v1.1.x
  detect_pii?: boolean; // New in v1.1.x
  debug_mode?: boolean; // New in v1.1.x
}

​
Decision (replaces PolicyEvaluationResult)

// v1.0.x
interface PolicyEvaluationResult {
  action: string;
  reason?: string;
}

// v1.1.x (backwards compatible)
interface Decision {
  action: DecisionAction;
  reason_codes: ReasonCode[];
  risk_score: number;
  mode: PolicyMode;
  correlation_id: string; // New
  component_versions: ComponentVersions; // New
  reason?: string;
  metadata?: Record<string, any>;
}

​
Method Signatures

​
TealEngine.evaluate()

// v1.0.x
evaluate(request: Request): Promise<PolicyEvaluationResult>

// v1.1.x (backwards compatible)
evaluate(request: Request, context?: ExecutionContext): Promise<Decision>

​
TealGuard.check()

// v1.0.x
check(content: string): Promise<PolicyEvaluationResult>

// v1.1.x (backwards compatible)
check(content: string, context?: ExecutionContext): Promise<Decision>

​
TealAudit.log()

// v1.0.x
log(event: string, data: any): Promise<void>

// v1.1.x (backwards compatible)
log(event: string, data: any, context?: ExecutionContext): Promise<void>

​
Breaking Changes

None. v1.1.x is fully backwards compatible with v1.0.x.

​
Deprecations

None. All v1.0.x APIs remain supported.

​
Performance Impact

v1.1.x features have minimal performance overhead:
  • Mode resolution: < 1ms
  • Context propagation: < 0.5ms
  • Decision evaluation: < 10ms (same as v1.0.x)
  • Audit redaction: < 5ms for 10KB content

​
Security Improvements

v1.1.x improves security by default:
  • No raw prompts in logs (HASH redaction by default)
  • PII detection enabled by default
  • Debug mode requires opt-in (explicit security trade-off)
  • Correlation IDs for security investigations

​
Testing Your Migration

​
Unit Tests

import { TealEngine, ExecutionContext, PolicyMode } from '@tealtiger/sdk';

describe('v1.1.x migration', () => {
  it('should work without context (v1.0.x compatibility)', async () => {
    const engine = new TealEngine({ policies: [...] });
    const decision = await engine.evaluate(request);
    expect(decision.action).toBeDefined();
  });

  it('should work with context (v1.1.x)', async () => {
    const engine = new TealEngine({ policies: [...] });
    const context = ExecutionContext.create({ actor });
    const decision = await engine.evaluate(request, context);
    expect(decision.correlation_id).toBeDefined();
  });

  it('should respect policy modes', async () => {
    const engine = new TealEngine({
      policies: [...],
      mode: { default: PolicyMode.MONITOR }
    });
    const decision = await engine.evaluate(violatingRequest, context);
    expect(decision.action).toBe(DecisionAction.ALLOW); // MONITOR allows
    expect(decision.mode).toBe(PolicyMode.MONITOR);
  });
});

​
Integration Tests

describe('v1.1.x integration', () => {
  it('should propagate context through components', async () => {
    const context = ExecutionContext.create({ actor });
    
    const engineDecision = await engine.evaluate(request, context);
    const guardDecision = await guard.check(content, context);
    
    expect(engineDecision.correlation_id).toBe(context.correlation_id);
    expect(guardDecision.correlation_id).toBe(context.correlation_id);
  });

  it('should redact PII in audit logs', async () => {
    const audit = new TealAudit({
      input_redaction: RedactionLevel.HASH,
      detect_pii: true
    });
    
    await audit.log('test', { prompt: 'SSN: 123-45-6789' }, context);
    
    const events = await audit.query({ correlation_id: context.correlation_id });
    expect(events[0].safe_inputs).not.toContain('123-45-6789');
  });
});

​
Rollback Plan

If you need to rollback to v1.0.x:
  1. Revert package.json/requirements.txt
  2. Remove v1.1.x-specific code (optional, it won’t break)
  3. Redeploy
# TypeScript
npm install @tealtiger/sdk@^1.0.0

# Python
pip install tealtiger==1.0.0

​
Support

​
Next Steps

  1. Review Best Practices
  2. Set up Policy Testing
  3. Configure Audit Redaction
  4. Implement Distributed Tracing