Policy Bridge

The Policy Bridge is SOMA's read-only query interface between the four-layer knowledge vault and agents. Agents submit queries with a semantic intent, and the bridge routes to the correct layer, returning results tagged with source layer and semantic weight.

Intent Routing

Intent-to-Layer Mapping

Intent	Target Layer	Semantic Weight	Description
enforce	L4 (canon)	mandatory	Ratified constraints agents must follow
advise	L3 (emerging)	advisory	Machine-proposed guidance with confidence
brief	L2 (working)	contextual	Team-scoped ephemeral context
route	L1 (archive)	historical	Raw traces and decayed entries
all	L1 + L2 + L3 + L4	Stratified	Results from all layers, tagged individually

Code Examples

Enforce: Get Mandatory Constraints

import { PolicyBridge } from '@soma/policy-bridge';

const bridge = new PolicyBridge(vault);

// Get all mandatory policies agents must follow
const constraints = await bridge.query({ intent: 'enforce' });

for (const entry of constraints) {
  console.log(`[${entry.source_layer}] ${entry.name}`);
  console.log(`  Weight: ${entry.semantic_weight}`);
  console.log(`  Content: ${entry.body}`);
}

[canon] max-retry-count
  Weight: mandatory
  Content: Agents must not retry more than 3 times per operation

[canon] api-backoff-required
  Weight: mandatory
  Content: All agents must implement exponential backoff on 429 responses

Advise: Get Soft Guidance

// Get machine-proposed guidance with confidence scores
const guidance = await bridge.query({ intent: 'advise' });

for (const entry of guidance) {
  console.log(`[${entry.source_layer}] ${entry.name} (${entry.confidence})`);
  console.log(`  Weight: ${entry.semantic_weight}`);
}

[emerging] retry-heavy-agents (0.82)
  Weight: advisory

[emerging] fetch-data-dominance (0.71)
  Weight: advisory

[emerging] payload-size-limit (0.55)
  Weight: advisory

Brief: Get Team Context

The brief intent requires a team_id because L2 is team-scoped:

// Get team-specific working memory
const context = await bridge.query({
  intent: 'brief',
  team_id: 'platform',
});

for (const entry of context) {
  console.log(`[${entry.source_layer}] ${entry.name}`);
  console.log(`  Team: ${entry.team_id}`);
  console.log(`  Expires: ${entry.decay_at}`);
}

[working] platform-deploy-freeze
  Team: platform
  Expires: 2026-03-28T00:00:00.000Z

[working] platform-oncall-rotation
  Team: platform
  Expires: 2026-04-01T00:00:00.000Z

Calling brief without team_id throws an error:

await bridge.query({ intent: 'brief' });
// Error: team_id is required for 'brief' intent

Route: Query Historical Data

// Get raw historical traces, optionally filtered by topic
const history = await bridge.query({
  intent: 'route',
  topic: 'agent-gamma',
});

for (const entry of history) {
  console.log(`[${entry.source_layer}] ${entry.id} (${entry.type}, ${entry.status})`);
}

[archive] exec-agent-gamma-20260320-001 (execution, failed)
[archive] exec-agent-gamma-20260319-003 (execution, completed)
[archive] decision-tool-choice-fetch-data-agent-gamma (decision, active)

All: Stratified Cross-Layer Query

// Get results from all layers, tagged with source and weight
const everything = await bridge.query({
  intent: 'all',
  topic: 'retry',
});

for (const entry of everything) {
  console.log(`[${entry.source_layer}/${entry.semantic_weight}] ${entry.name}`);
}

[canon/mandatory]    max-retry-count
[emerging/advisory]  retry-heavy-agents
[archive/historical] decision-retry-agent-alpha-exec-091
[archive/historical] decision-retry-agent-beta-exec-044

The all intent returns results grouped by layer, with L4 entries first (highest authority) down to L1 (lowest). Each result carries its own semantic_weight so agents can treat them appropriately.

Topic Filtering

All intents accept an optional topic parameter that filters results by matching against entity tags, names, and content:

const retryPolicies = await bridge.query({
  intent: 'enforce',
  topic: 'retry',
});

Legacy PolicySource Interface

The Policy Bridge implements the PolicySource interface from AgentFlow, making it a drop-in replacement for any existing policy provider:

interface PolicySource {
  getPolicies(context: PolicyContext): Promise<Policy[]>;
}

// SOMA's Policy Bridge implements this interface
const bridge = new PolicyBridge(vault);

// Pass it to AgentFlow as a policy source
const agent = new Agent({
  policySource: bridge,
  // ... other config
});

When used as a PolicySource, the bridge maps:

• L4 canon policies to severity: 'error' (blocks execution)
• L3 emerging policies to severity: 'warning' (logs but allows)
• L2/L1 entries are not served through the PolicySource interface (only enforce and advise intents)

Read-Only Guarantee

The Policy Bridge never writes to the vault. It has READ permissions on all four layers and WRITE permissions on none:

Worker	L1	L2	L3	L4
Policy Bridge	READ	READ	READ	READ

This is enforced at the layer permission level. Even if a bug in the bridge attempted a write, the vault would reject it with LayerPermissionError.

The bridge also never caches results beyond a single query. Every call reads fresh data from the vault index, ensuring agents always get the latest organizational knowledge.