Rules - VisIQ

How Rules Work

Rules define what context your agents are permitted to see. Every document, tool result, or rendered prompt intercepted by the SDK is evaluated against your rule set. Rules are compiled into OPA/Rego policy, then into WASM bundles that SDKs download and cache locally — evaluation happens in-process with sub-millisecond latency. Each rule targets a specific trust tier, surface, or principal and produces one of four actions: allow the content, redact sensitive fields, deny it entirely, or escalate to a human.

Rule Structure

A rule has the following fields:

Field	Type	Description
`name`	`string`	Human-readable name for the rule
`description`	`string`	Optional longer description
`rego_source`	`string`	OPA/Rego policy source code
`natural_language`	`string`	Natural language description used for AI compilation
`priority`	`number`	Rules with higher priority are evaluated first. Default: `0`
`enabled`	`boolean`	Whether the rule is active. Disabled rules are excluded from the bundle
`trust_tier`	`string`	Trust tier this rule applies to (e.g. `tier1`, `tier2`, `tier3`)
`surface`	`string`	Communication surface this rule applies to (e.g. `slack`, `email`)
`principal_exclusions`	`string[]`	Agent IDs excluded from this rule’s scope

Example Rule (JSON)

{
  "name": "Deny tier3 from confidential data",
  "description": "Prevent tier3 agents from accessing internal, confidential, or restricted documents",
  "rego_source": "package recall.evaluate\n\nimport rego.v1\n\ndefault decision := {\"action\": \"deny\", \"reason_code\": \"DEFAULT_DENY\", \"reason\": \"no matching rule\"}\n\ndecision := result if {\n  input.trust_tier == \"tier3\"\n  input.resource_metadata.classification in {\"internal\", \"confidential\", \"restricted\"}\n  result := {\"action\": \"deny\", \"reason_code\": \"TIER_MISMATCH\", \"reason\": \"tier3 restricted to public data\"}\n}",
  "natural_language": "Deny tier3 agents from accessing internal, confidential, or restricted data",
  "priority": 50,
  "enabled": true,
  "trust_tier": "tier3",
  "surface": null,
  "principal_exclusions": null
}

Trust Tiers

Trust tiers are the primary mechanism for controlling agent access to data. Each agent is assigned a trust tier, and each document has a classification. The trust tier matrix determines the outcome.

Trust Tier	Access Level	Behavior
`tier1`	Full access	Allow all document classifications
`tier2`	Standard	Allow public and internal; redact confidential; deny restricted
`tier3`	Restricted	Allow public only; deny everything else
(unknown)	No access	Deny all (fail-closed, configurable via `unknown_agent_policy`)

Document Classifications

Classification	Description
`public`	Generally available information
`internal`	Company-internal, not sensitive
`confidential`	Sensitive business data (PII, financial, legal)
`restricted`	Highly sensitive (trade secrets, board materials, security keys)

Trust Tier Matrix

	public	internal	confidential	restricted
tier1	Allow	Allow	Allow	Allow
tier2	Allow	Allow	Redact	Deny
tier3	Allow	Deny	Deny	Deny
unknown	Deny	Deny	Deny	Deny

Unknown agents are denied all context by default (fail-closed). Configure unknown_agent_policy: 'lowest_tier' to apply tier3 rules instead, or 'audit' to allow all context while logging warnings. The deny default is the secure choice for production.

Surfaces

Surfaces represent the communication channel where the agent’s output will be delivered. Rules can restrict context based on the destination surface — a document might be allowed in a private group but denied in a public channel.

Surface	Description
`DIRECT_MESSAGE`	One-to-one private message
`PRIVATE_GROUP`	Private group or channel
`INTERNAL_CHANNEL`	Company-internal channel
`PUBLIC_CHANNEL`	Publicly visible channel
`EXTERNAL_CHANNEL`	Channel shared with external parties

A rule with surface: "PUBLIC_CHANNEL" will only match when the agent’s output surface is a public channel. Rules without a surface restriction match all surfaces.

OPA/Rego Policy Format

Every RECALL Rego policy must follow this structure:

package recall.evaluate

import rego.v1

# Default: deny (fail-closed, G001)
default decision := {
  "action": "deny",
  "reason_code": "DEFAULT_DENY",
  "reason": "no matching rule",
}

# Your rules produce a decision object
decision := result if {
  # conditions...
  result := {
    "action": "allow",           # allow | deny | redact | escalate
    "reason_code": "POLICY_ALLOW",
    "reason": "human-readable explanation",
  }
}

Input Document

The OPA input document has these fields, matching the evaluate request:

Field	Type	Description
`input.agent_id`	`string`	Agent identifier
`input.trust_tier`	`string`	`tier1`, `tier2`, or `tier3`
`input.operation`	`string`	`retrieve`, `tool_call`, or `prompt_render`
`input.resource_type`	`string`	`document`, `tool_result`, or `prompt`
`input.resource_metadata`	`object`	Contains `classification`, `min_trust_tier`, `restricted_surfaces`, `excluded_principals`, etc.
`input.surface`	`string`	Communication surface (e.g. `PUBLIC_CHANNEL`)
`input.query`	`string`	Retrieval query string (optional)

Decision Object

The decision produced by the policy must include:

Field	Type	Required	Values
`action`	`string`	Yes	`allow`, `deny`, `redact`, `escalate`
`reason_code`	`string`	Yes	`TIER_MISMATCH`, `PRINCIPAL_EXCLUDED`, `POLICY_DENY`, `AUDIENCE_EXPANSION`, `SURFACE_RESTRICTION`, `POLICY_ALLOW`, `DEFAULT_DENY`, `EMERGENCY_BYPASS`
`reason`	`string`	Yes	Human-readable explanation

Example: Surface-Based Restriction

package recall.evaluate

import rego.v1

default decision := {
  "action": "deny",
  "reason_code": "DEFAULT_DENY",
  "reason": "no matching rule",
}

# Deny confidential content in public or external channels
decision := result if {
  input.resource_metadata.classification == "confidential"
  input.surface in {"PUBLIC_CHANNEL", "EXTERNAL_CHANNEL"}
  result := {
    "action": "deny",
    "reason_code": "AUDIENCE_EXPANSION",
    "reason": "confidential content cannot be shared in public or external channels",
  }
}

# Allow confidential content in private contexts
decision := result if {
  input.resource_metadata.classification == "confidential"
  input.surface in {"DIRECT_MESSAGE", "PRIVATE_GROUP", "INTERNAL_CHANNEL"}
  result := {
    "action": "allow",
    "reason_code": "POLICY_ALLOW",
    "reason": "confidential content allowed in private contexts",
  }
}

Natural Language Rules

You can describe rules in plain English. RECALL compiles them to OPA/Rego policy using AI (powered by the POST /recall/rules/compile endpoint). No Rego expertise required. Example prompt: “Deny tier3 agents from accessing any document classified as internal, confidential, or restricted. Allow tier1 and tier2 agents to access everything except restricted documents.” The compiler reads your existing rules for context before generating new ones, ensuring the new rule fits coherently into your policy set. It validates the Rego syntax and can optionally save the rule directly to the database.

The compile endpoint supports streaming via ?stream=true or Accept: text/event-stream for real-time feedback during rule compilation.

Rule Evaluation Flow

When the SDK intercepts a retrieved document:

The SDK extracts operation, resource_type, and resource_metadata from the retrieval context.
The SDK harness evaluates the input against the cached WASM policy bundle.
The policy produces a decision object with an action, reason_code, and reason.
The action is applied: allow passes the document through, redact scrubs sensitive fields, deny suppresses it, escalate holds it for review.
If no local bundle is loaded, the SDK falls back to server-side evaluation via POST /recall/evaluate.

No policy loaded defaults to deny in enforce mode. An empty policy bundle suppresses all retrieved context. Start with audit mode to observe your agent’s retrieval patterns before writing rules.

Principal Exclusions

Rules can exclude specific agent IDs from their scope. A rule with principal_exclusions: ["admin-bot", "debug-agent"] will not apply to those agents — they will fall through to lower-priority rules or the default decision. This is useful for granting specific agents elevated access without creating separate rules:

{
  "name": "Deny tier3 from confidential",
  "rego_source": "...",
  "trust_tier": "tier3",
  "principal_exclusions": ["admin-bot"],
  "priority": 50
}

In this example, admin-bot is excluded from the denial rule even if it is assigned tier3. It will be evaluated by other matching rules or receive the default decision.

Managing Rules

Rules can be created and managed via:

Dashboard: Navigate to Rules in the RECALL dashboard. Use the Create Rule button for manual entry or the Compile from description input for natural language.
REST API: Use the Rules endpoints documented in the API Reference. Useful for programmatic rule management, CI/CD pipelines, and bulk imports.

Rule Priority Guidelines

Priority range	Suggested use
`100+`	Override rules — emergency denials that should always win
`50–99`	Standard suppression rules for known patterns
`10–49`	Broad trust tier rules
`1–9`	Catch-all rules
`0`	Default / lowest precedence

Documentation Index

​How Rules Work

​Rule Structure

​Example Rule (JSON)

​Trust Tiers

​Document Classifications

​Trust Tier Matrix

​Surfaces

​OPA/Rego Policy Format

​Input Document

​Decision Object

​Example: Surface-Based Restriction

​Natural Language Rules

​Rule Evaluation Flow

​Principal Exclusions

​Managing Rules

​Rule Priority Guidelines

How Rules Work

Rule Structure

Example Rule (JSON)

Trust Tiers

Document Classifications

Trust Tier Matrix

Surfaces

OPA/Rego Policy Format

Input Document

Decision Object

Example: Surface-Based Restriction

Natural Language Rules

Rule Evaluation Flow

Principal Exclusions

Managing Rules

Rule Priority Guidelines