# Bridge Module

> Neuro-symbolic action validation for game rule enforcement

# Bridge Module

`Brídge_Módule // Néuro_Symbólic`

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

The Bridge module ensures AI-generated actions are **always valid** within game rules. It acts as a neuro-symbolic barrier between AI creativity and game physics.

> *T̷h̵e̴ ̷l̵a̸w̴s̵ ̶o̷f̸ ̷p̸h̵y̵s̶i̷c̴s̵ ̷c̴a̶n̸n̴o̷t̶ ̸b̴e̷ ̵b̶r̶o̵k̸e̴n̷.*

***

## Overview

The Bridge validates every action before it reaches the game engine:

* **Built-in Rules**: MOVE, ATTACK, INTERACT, SPEAK, Resources
* **Custom Rules**: Register game-specific validation logic
* **Strict Mode**: Reject unknown action types
* **Auto-Correction**: Provide fallback actions when validation fails

***

## Quick Start

```typescript
import { createBridge } from 'forbocai';

const bridge = createBridge({ strictMode: true });

// Validate an action
const result = await bridge.validate(
  { type: 'ATTACK', target: 'orc_1' },
  {
    agentState: { hp: 85, mana: 50 },
    worldState: { entities: ['orc_1', 'player_1'] }
  }
);

if (result.valid) {
  executeAction(result.correctedAction || action);
} else {
  console.log('Invalid:', result.reason);
}
```

***

## Configuration

| Option        | Type               | Default | Description                 |
| ------------- | ------------------ | ------- | --------------------------- |
| `strictMode`  | `boolean`          | `false` | Reject unknown action types |
| `apiUrl`      | `string`           | API URL | Optional remote validation  |
| `customRules` | `ValidationRule[]` | `[]`    | Additional validation rules |

***

## API Reference

### `createBridge(config)`

Factory function to create a Bridge instance.

```typescript
import { createBridge } from 'forbocai';

const bridge = createBridge({
  strictMode: true,
  customRules: [myCustomRule]
});
```

***

### `bridge.validate(action, context?)`

Validate an action against all applicable rules.

**Parameters:**

* `action` (AgentAction): The action to validate
* `context` (ValidationContext): Optional context for validation

**Returns:** `Promise<ValidationResult>`

```typescript
interface ValidationResult {
  valid: boolean;
  reason?: string;
  correctedAction?: AgentAction;
}
```

***

### `bridge.registerRule(rule)`

Register a custom validation rule.

```typescript
bridge.registerRule({
  id: 'game.fly',
  name: 'Flying Validation',
  actionTypes: ['FLY'],
  validate: (action, ctx) => {
    const hasWings = ctx.agentState?.hasWings;
    return hasWings 
      ? { valid: true }
      : { valid: false, reason: 'No wings' };
  }
});
```

***

### `bridge.listRules()`

List all registered validation rules.

**Returns:** `ValidationRule[]`

***

### `bridge.removeRule(ruleId)`

Remove a validation rule by ID.

**Returns:** `boolean` (true if removed)

***

## Built-in Rules

### Movement (`core.movement`)

Validates MOVE actions have valid coordinates.

**Checks:**

* Target has numeric x, y coordinates
* Coordinates are within world bounds (if provided)

```typescript
// Valid
{ type: 'MOVE', payload: { target: { x: 10, y: 20 } } }

// Invalid - no coordinates
{ type: 'MOVE', payload: {} }

// Corrected - clamped to bounds
{ type: 'MOVE', payload: { target: { x: 150, y: 50 } } }
// → { target: { x: 100, y: 50 } } if maxX=100
```

***

### Attack (`core.attack`)

Validates ATTACK actions have valid targets.

**Checks:**

* Target or targetId is specified
* Target exists in world (if entities provided)

```typescript
// Valid
{ type: 'ATTACK', target: 'orc_1' }

// Invalid - no target
{ type: 'ATTACK' }
```

***

### Interact (`core.interact`)

Validates INTERACT actions have valid objects.

**Checks:**

* Target or objectId is specified

***

### Speak (`core.speak`)

Validates SPEAK actions have non-empty text.

**Checks:**

* Text is not empty
* Text is within max length (truncates if needed)

```typescript
// Valid
{ type: 'SPEAK', payload: { text: 'Hello there!' } }

// Invalid - empty text
{ type: 'SPEAK', payload: { text: '' } }
```

***

### Resources (`core.resources`)

Validates agent has sufficient resources.

**Checks:**

* Agent is not dead (hp > 0)
* Sufficient mana for CAST actions

```typescript
// Context with low HP
context = { agentState: { hp: 0 } }

// Any action → Invalid: "Agent is dead"
```

***

## Custom Rules

Create game-specific validation rules:

```typescript
import { ValidationRule } from 'forbocai';

const flyingRule: ValidationRule = {
  id: 'game.fly',
  name: 'Flying Validation',
  description: 'Ensures agents can only fly if they have wings',
  actionTypes: ['FLY', 'GLIDE'],
  validate: (action, context) => {
    const hasWings = context.agentState?.hasWings;
    const altitude = context.worldState?.altitude;
    
    if (!hasWings) {
      return {
        valid: false,
        reason: 'Agent cannot fly without wings',
        correctedAction: { ...action, type: 'WALK' }
      };
    }
    
    if (altitude && altitude > 1000) {
      return {
        valid: false,
        reason: 'Altitude too high',
        correctedAction: { 
          ...action, 
          payload: { ...action.payload, maxAltitude: 1000 }
        }
      };
    }
    
    return { valid: true };
  }
};

bridge.registerRule(flyingRule);
```

***

## Validation Context

Provide context for more accurate validation:

```typescript
interface ValidationContext {
  agentState?: {
    hp?: number;
    mana?: number;
    inventory?: string[];
    hasWings?: boolean;
    // ... any game-specific state
  };
  worldState?: {
    entities?: string[];
    maxX?: number;
    maxY?: number;
    altitude?: number;
    // ... any game-specific world state
  };
  constraints?: {
    maxSpeechLength?: number;
    // ... any game-specific constraints
  };
}
```

***

## Strict Mode

When `strictMode: true`, unknown action types are rejected:

```typescript
const bridge = createBridge({ strictMode: true });

// Allowed in strict mode
bridge.validate({ type: 'IDLE' })    // ✅ Built-in safe type
bridge.validate({ type: 'ATTACK' })  // ✅ Has validation rule

// Rejected in strict mode
bridge.validate({ type: 'TELEPORT' }) // ❌ Unknown action type
// → { valid: false, reason: "Unknown action type 'TELEPORT'" }
```

***

## Pure Function

For functional programming without a class:

```typescript
import { validateAction, movementRule, attackRule } from 'forbocai';

const rules = [movementRule, attackRule];

const result = validateAction(
  { type: 'MOVE', payload: { target: { x: 10, y: 20 } } },
  rules,
  context
);
```

***

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

> *T̵h̷e̷ ̸B̷r̸i̵d̶g̷e̸ ̸s̷t̵a̸n̷d̴s̵ ̸b̵e̶t̴w̴e̵e̸n̶ ̷c̸h̷a̸o̸s̸ ̸a̶n̵d̵ ̴o̴r̷d̸e̸r̷.*