Skip to content

Policy & Governance

This document defines the policy model for Zakardo: how governance rules are authored, structured, evaluated, and enforced. Policies are the mechanism through which organizations control what plans can do, when execution must pause for human approval, and what constraints apply in different contexts.

Prerequisites: Glossary, System Architecture, Type System, Plan IR, Capability System


The Policy System must:

  1. Be declarative. Policies are data, not code. They are JSON documents that describe rules, not scripts that execute logic.
  2. Be composable. Multiple policies can apply simultaneously. The system must resolve overlaps and conflicts predictably.
  3. Be evaluable at three points. Pre-generation (Planner, lightweight), pre-execution (Validator, full plan), and per-step (Execution Engine, runtime). All evaluation points use the same policy engine.
  4. Be auditable. Every policy evaluation — its inputs, the matched rules, and the outcome — is recorded in the Trace.
  5. Be tenant-aware. Different organizations, teams, or users may have different policy sets. The system must support scoped policy application.
  6. Be understandable. A non-technical stakeholder should be able to read a policy and understand what it controls.
  7. Not be an authorization system. Policies govern what execution can do, not who is allowed to do it. User authentication and role-based access control are external to the policy model.
  8. Complement capability-level constraints. System-level policies defined here are cross-cutting governance rules. Capabilities may also declare their own constraints (role requirements, rate limits, preconditions) in their capability definition. The Planner reads both during plan generation. See the Capability System Specification, Section 16A.

A policy is a JSON document that declares a set of rules. Each rule specifies conditions under which a governance action is taken.

{
"policy_id": "550e8400-e29b-41d4-a716-446655440100",
"name": "production_safety",
"version": "1.0.0",
"description": "Safety policies for production execution environment",
"scope": {
"environment": "production",
"tenant": "*",
"user": "*"
},
"rules": [ ... ],
"metadata": {
"author": "platform-team",
"created_at": "2026-02-05T10:00:00Z",
"enabled": true,
"priority": 100
}
}
FieldTypeRequiredDescription
policy_idstring (UUID)YesUnique identifier for this policy.
namestringYesMachine-readable name. Must match ^[a-z][a-z0-9_-]*$.
versionstring (semver)YesPolicy version.
descriptionstringYesHuman-readable description of what this policy governs.
scopePolicyScopeYesWhen this policy applies. See Section 3.
rulesarray of RuleYesThe governance rules. See Section 4.
metadataobjectYesSee Section 2.3.
FieldTypeRequiredDescription
authorstringYesWho authored this policy.
created_atstring (ISO 8601)YesWhen this version was created.
enabledbooleanYesIf false, this policy is registered but not evaluated. Allows disabling without deleting.
priorityintegerYesEvaluation priority. Higher numbers are evaluated first. Used for conflict resolution (see Section 6).

A policy’s scope determines when it applies. Scopes are hierarchical and support wildcards.

FieldTypeDescription
environmentstringThe deployment environment: "production", "staging", "development", "*" (all).
tenantstringTenant identifier, or "*" for all tenants. For single-tenant deployments, this is always "*".
userstringUser identifier, or "*" for all users. Allows per-user policy overrides.
capability_tagsarray of stringIf present, this policy only applies to capabilities matching these tags.
plan_tagsarray of stringIf present, this policy only applies to plans matching these tags.

When the Policy Engine evaluates a step, it collects all applicable policies by matching scopes:

  1. Collect all enabled policies.
  2. Filter by environment (exact match or wildcard).
  3. Filter by tenant (exact match or wildcard).
  4. Filter by user (exact match or wildcard).
  5. Filter by capability_tags (if specified, capability must have at least one matching tag).
  6. Filter by plan_tags (if specified, plan must have at least one matching tag).
  7. Sort remaining policies by priority (descending).

All matching policies are evaluated. If they conflict, the conflict resolution rules in Section 6 apply.

// Applies to all users in production
{ "environment": "production", "tenant": "*", "user": "*" }
// Applies only to tenant "acme-corp" in any environment
{ "environment": "*", "tenant": "acme-corp", "user": "*" }
// Applies only to email-related capabilities in production
{ "environment": "production", "tenant": "*", "user": "*", "capability_tags": ["email"] }
// Applies only to a specific user (e.g., a high-risk user under review)
{ "environment": "*", "tenant": "acme-corp", "user": "user-789" }

Rules are the core of a policy. Each rule declares a condition and an action.

{
"rule_id": "rule-001",
"name": "require_approval_for_destructive",
"description": "All DESTRUCTIVE capabilities require human approval before execution",
"condition": {
"operator": "equals",
"field": "capability.effect_class",
"value": "DESTRUCTIVE"
},
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "This step will perform a destructive operation. Approval is required."
}
}
FieldTypeRequiredDescription
rule_idstringYesUnique identifier within the policy.
namestringYesHuman-readable rule name.
descriptionstringYesHuman-readable description of what this rule enforces.
conditionConditionYesWhen this rule triggers. See Section 5.
actionActionYesWhat happens when the condition is met. See Section 4.3.

When a rule’s condition evaluates to true, its action is applied.

Action TypeBehaviorBlocks Execution?
GATETriggers a gate — pauses execution and presents a view to the user.Yes (until user responds).
DENYBlocks execution entirely. The step (or plan) cannot proceed.Yes (permanently).
WARNRecords a warning in the trace but allows execution to continue.No.
LOGRecords the policy match in the trace. No visible effect to the user.No.
REQUIRE_MODEForces a minimum execution mode (e.g., “this plan must run in DRY_RUN before LIVE”).Depends on current mode.
MODIFY_CONSTRAINTAdjusts an execution constraint (e.g., lower the timeout, reduce max steps).No (modifies parameters).

When the action type is GATE, additional fields are required:

{
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "This operation will send emails to external recipients. Approve to continue.",
"approvers": ["role:admin", "role:manager"],
"timeout_ms": 3600000,
"on_timeout": "DENY",
"view_hint": {
"preferred_blocks": ["ConfirmationCard"],
"show_context": ["capability.name", "capability.effect_class", "step.input_bindings"]
}
}
}
FieldTypeRequiredDescription
gate_typeGateType enumYesThe kind of gate. See Section 4.5.
messagestringYesMessage displayed to the user explaining why approval is needed.
approversarray of stringNoWho can approve. Format: "role:<role>" or "user:<user_id>". If omitted, the executing user can self-approve.
timeout_msintegerNoHow long to wait for approval. Default: 3,600,000 ms (1 hour).
on_timeoutstringNoWhat happens if the gate times out: "DENY" (block) or "APPROVE" (auto-approve). Default: "DENY".
view_hintobjectNoHints to A2UI Composition for rendering the gate UI.
Gate TypePurposeUser Action
APPROVALThe user must explicitly approve the step or plan before it proceeds.Approve or Deny.
INPUTThe user must provide additional data before the step proceeds.Fill in required fields.
REVIEWThe user must review information before proceeding. May approve/reject or just acknowledge.Acknowledge, Approve, or Reject.
LOG_ONLYThe gate is recorded in the trace but does not pause execution. Useful for audit trails.None (automatic).
{
"action": {
"type": "DENY",
"reason": "DESTRUCTIVE operations are not permitted in the staging environment",
"error_code": "POLICY_DENIED_DESTRUCTIVE_IN_STAGING"
}
}
FieldTypeRequiredDescription
reasonstringYesHuman-readable explanation of why the step/plan is denied.
error_codestringNoMachine-readable error code for programmatic handling.
{
"action": {
"type": "REQUIRE_MODE",
"minimum_mode": "DRY_RUN",
"message": "CANDIDATE plans must run in DRY_RUN mode before LIVE execution"
}
}
FieldTypeRequiredDescription
minimum_modeExecutionMode enumYesThe minimum mode required. If the requested mode is lower severity, execution is denied. Mode severity: SIMULATED < DRY_RUN < LIVE.
messagestringYesExplanation of the mode requirement.

Conditions are the predicate logic that determines when a rule triggers.

Conditions evaluate against the evaluation context — a structured data object assembled from the current plan, step, capability, execution mode, and user context.

FieldTypeRequiredDescription
operatorstringYesThe comparison or logical operator. See Section 5.3.
fieldstringDependsPath into the evaluation context. Required for comparison operators.
valueanyDependsThe value to compare against. Required for comparison operators.
conditionsarray of ConditionDependsSub-conditions for logical operators (and, or).
conditionConditionDependsSub-condition for not operator.

The evaluation context is the data available to conditions. It is NOT the Execution Context (which holds step outputs). The evaluation context is assembled from static plan and capability metadata.

evaluation_context = {
capability: {
name: string,
version: string,
effect_class: EffectClass,
boundary: Boundary,
tags: string[],
has_interaction_spec: boolean
},
plan: {
name: string,
version: string,
lifecycle_state: LifecycleState,
aggregate_effect_class: EffectClass,
tags: string[],
step_count: integer,
author: string
},
step: {
step_index: integer,
name: string,
has_condition: boolean,
input_binding_count: integer
},
execution: {
mode: ExecutionMode,
environment: string
},
user: {
user_id: string,
tenant_id: string,
roles: string[]
}
}
OperatorTypeDescriptionRequired Fields
equalsComparisonStrict equalityfield, value
not_equalsComparisonStrict inequalityfield, value
greater_thanComparisonNumeric/string comparisonfield, value
less_thanComparisonNumeric/string comparisonfield, value
inComparisonValue is in a listfield, value (array)
not_inComparisonValue is not in a listfield, value (array)
containsComparisonArray field contains valuefield, value
matchesComparisonRegex match on string fieldfield, value (regex string)
existsComparisonField is present and non-nullfield
andLogicalAll sub-conditions must be trueconditions (array)
orLogicalAt least one sub-condition is trueconditions (array)
notLogicalSub-condition must be falsecondition (single)

Simple: trigger on destructive capabilities

{
"operator": "equals",
"field": "capability.effect_class",
"value": "DESTRUCTIVE"
}

Compound: trigger on external writes to remote boundaries by candidate plans

{
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "capability.effect_class", "value": "WRITE_EXTERNAL" },
{ "operator": "equals", "field": "capability.boundary", "value": "REMOTE" },
{ "operator": "equals", "field": "plan.lifecycle_state", "value": "CANDIDATE" }
]
}

Tag-based: trigger on capabilities tagged “financial”

{
"operator": "contains",
"field": "capability.tags",
"value": "financial"
}

Mode-based: trigger when running in LIVE mode

{
"operator": "equals",
"field": "execution.mode",
"value": "LIVE"
}

6. Policy Evaluation and Conflict Resolution

Section titled “6. Policy Evaluation and Conflict Resolution”

Policies are evaluated at three points in the lifecycle:

Evaluation PointWhenEvaluatorWhat Is CheckedPurpose
Pre-generationDuring backward chaining, before the Planner selects a capabilityPlanner (via Policy Engine)Can this user execute this specific capability? (effect class, boundary, tags vs. user roles)UX quality. Ensures the Planner only builds plans the user can execute. If blocked, the Planner searches for alternatives (request pattern).
Pre-executionAfter Plan Enrichment, during validationValidator (via Policy Engine)Plan-level policies: aggregate effect class, execution mode compatibility, plan lifecycle constraints. Evaluated once for the whole plan.Safety net. Catches edge cases the Planner missed (race conditions, registry changes).
Per-stepDuring plan execution, before each stepExecution Engine (via Policy Engine)Step-level policies: individual capability effect class, boundary, tags. May trigger gates.Runtime governance. Enforces gates and runtime constraints.

Pre-generation is the most important evaluation point. It ensures that plans always succeed by preventing the Planner from selecting capabilities the user cannot access. The other two points are defense-in-depth — they should rarely trigger denials for Planner-generated plans.

The Planner calls the Policy Engine during backward chaining, once for each candidate capability before committing to it:

Input:
- Capability metadata (name, version, effect_class, boundary, tags)
- User context (user_id, tenant_id, roles)
- Environment
Output:
- ALLOWED: Planner may use this capability in the plan
- DENIED: Planner must find an alternative
(with reason, so the Planner can explain if no alternative exists)

This is a lightweight evaluation. It checks only the capability’s static metadata against user roles and policies. It does not evaluate plan-level or step-level policies (those happen later). The purpose is not full policy enforcement — it is guidance to help the Planner build executable plans.

When a capability is DENIED:

  1. The Planner queries the Capability Registry for alternatives (checking alternatives field first, then tag-based search).
  2. For each alternative found, the Planner runs another pre-generation evaluation.
  3. If an alternative is ALLOWED, the Planner adjusts the goal and uses it.
  4. If no alternative is ALLOWED, the Planner switches to CONVERSE mode and explains why the intent cannot be fulfilled.

Example:

Intent: "Delete customer account ABC-123"
Pre-generation check: delete_customer_account (DESTRUCTIVE)
→ User role: "support_agent"
→ Policy: DENY (support agents cannot execute DESTRUCTIVE capabilities)
Alternative search: request_account_deletion (WRITE_INTERNAL)
→ Pre-generation check: ALLOWED
→ Planner adjusts goal: "submit deletion request"
→ Plan built with request_account_deletion
→ Plan always succeeds.

The Validator calls the Policy Engine with the full Plan IR and requests plan-level evaluation:

Input:
- Full Plan IR (plan name, tags, aggregate effect class, lifecycle state, step count)
- Requested execution mode
- User context (user_id, tenant_id, roles)
- Environment
Output:
- ALLOW: plan may proceed to execution
- DENY: plan is rejected (with reason)
- GATE: plan requires approval before execution starts (plan-level gate)
- REQUIRE_MODE: execution mode must change

Pre-execution evaluation checks:

  1. Is this execution mode permitted for this plan’s aggregate effect class?
  2. Are there plan-level policies that deny or gate this plan?
  3. Does the plan’s lifecycle state have constraints (e.g., “CANDIDATE plans must run in DRY_RUN first”)?

The Execution Engine calls the Policy Engine before executing each step:

Input:
- Step metadata (step_index, name, capability info)
- Capability metadata (name, version, effect_class, boundary, tags)
- Plan metadata (name, lifecycle_state, tags)
- Execution context (mode, environment)
- User context (user_id, tenant_id, roles)
Output:
- ALLOW: step may proceed
- DENY: step is blocked (plan aborts or handles per error policy)
- GATE: gate triggered (execution pauses, user sees gate UI)
- WARN: warning recorded, step proceeds
- LOG: logged silently, step proceeds
- MODIFY_CONSTRAINT: execution parameters adjusted (e.g., lower timeout)

For a given evaluation context:

1. Collect all enabled policies whose scope matches the context.
2. Sort by priority (descending).
3. For each policy, evaluate its rules in order:
a. Evaluate the rule's condition against the evaluation context.
b. If condition is true: record the rule match and its action.
c. Continue evaluating remaining rules (a single policy may have multiple matching rules).
4. Collect all matched actions across all policies.
5. Apply conflict resolution (see Section 6.5).
6. Return the final set of actions.

When multiple rules match and produce conflicting actions:

Priority rules (in order):

  1. DENY always wins. If any rule produces DENY, the result is DENY. No other action can override a denial.
  2. GATE trumps ALLOW. If any rule produces GATE and no rule produces DENY, the result includes the gate.
  3. REQUIRE_MODE is additive. If multiple rules require different modes, the highest mode wins (LIVE > DRY_RUN > SIMULATED).
  4. WARN and LOG are always additive. They never conflict with other actions. All warnings and logs are recorded regardless of other outcomes.
  5. MODIFY_CONSTRAINT is additive. Multiple modifications are merged. If they conflict (e.g., two different timeout values), the more restrictive value wins.
  6. Multiple GATE actions are combined. If rules from different policies both produce gates, the user sees all gates (in priority order). The user must resolve each one.

Same-priority conflict: If two policies have the same priority and produce conflicting GATE vs. ALLOW results, the GATE wins (default to more governance, not less).

The Policy Engine returns a structured result for tracing and auditing:

{
"outcome": "GATE",
"matched_rules": [
{
"policy_id": "550e8400-...",
"policy_name": "production_safety",
"rule_id": "rule-001",
"rule_name": "require_approval_for_destructive",
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "This step will perform a destructive operation."
}
},
{
"policy_id": "660e8400-...",
"policy_name": "audit_logging",
"rule_id": "rule-010",
"rule_name": "log_all_remote_calls",
"action": {
"type": "LOG"
}
}
],
"unmatched_policies": ["770e8400-..."],
"evaluation_context_snapshot": { ... }
}

This entire result is recorded in the Trace for auditability.


The Zakardo runtime ships with a set of default policies. These provide sensible governance out of the box. They can be overridden, extended, or disabled by the developer.

7.1 Default Policy: Execution Mode Constraints

Section titled “7.1 Default Policy: Execution Mode Constraints”
{
"policy_id": "default-mode-constraints",
"name": "default_execution_mode_constraints",
"version": "1.0.0",
"description": "Controls which effect classes are permitted in each execution mode",
"scope": { "environment": "*", "tenant": "*", "user": "*" },
"rules": [
{
"rule_id": "simulated-read-only",
"name": "simulated_mode_read_only",
"description": "SIMULATED mode only permits READ capabilities",
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "execution.mode", "value": "SIMULATED" },
{ "operator": "not_equals", "field": "capability.effect_class", "value": "READ" }
]
},
"action": {
"type": "DENY",
"reason": "SIMULATED mode does not permit capabilities with side effects",
"error_code": "POLICY_SIMULATED_MODE_NO_SIDE_EFFECTS"
}
},
{
"rule_id": "dryrun-no-external",
"name": "dryrun_no_external_writes",
"description": "DRY_RUN mode does not permit WRITE_EXTERNAL or DESTRUCTIVE capabilities",
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "execution.mode", "value": "DRY_RUN" },
{
"operator": "in",
"field": "capability.effect_class",
"value": ["WRITE_EXTERNAL", "DESTRUCTIVE"]
}
]
},
"action": {
"type": "DENY",
"reason": "DRY_RUN mode does not permit external writes or destructive operations",
"error_code": "POLICY_DRYRUN_NO_EXTERNAL_EFFECTS"
}
}
],
"metadata": {
"author": "zakardo-runtime",
"created_at": "2026-01-01T00:00:00Z",
"enabled": true,
"priority": 1000
}
}

7.2 Default Policy: Destructive Operations

Section titled “7.2 Default Policy: Destructive Operations”
{
"policy_id": "default-destructive-approval",
"name": "default_destructive_approval",
"version": "1.0.0",
"description": "All DESTRUCTIVE capabilities require human approval in LIVE mode",
"scope": { "environment": "*", "tenant": "*", "user": "*" },
"rules": [
{
"rule_id": "approve-destructive-live",
"name": "approve_destructive_in_live",
"description": "Require approval for destructive operations in LIVE mode",
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" },
{ "operator": "equals", "field": "execution.mode", "value": "LIVE" }
]
},
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "This step will perform a destructive operation. Approval is required to continue.",
"on_timeout": "DENY"
}
}
],
"metadata": {
"author": "zakardo-runtime",
"created_at": "2026-01-01T00:00:00Z",
"enabled": true,
"priority": 900
}
}
{
"policy_id": "default-candidate-safety",
"name": "default_candidate_plan_safety",
"version": "1.0.0",
"description": "CANDIDATE plans with external side effects must be reviewed before LIVE execution",
"scope": { "environment": "production", "tenant": "*", "user": "*" },
"rules": [
{
"rule_id": "candidate-external-review",
"name": "candidate_external_writes_require_review",
"description": "CANDIDATE plans with WRITE_EXTERNAL or DESTRUCTIVE aggregate effect must be approved",
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "plan.lifecycle_state", "value": "CANDIDATE" },
{
"operator": "in",
"field": "plan.aggregate_effect_class",
"value": ["WRITE_EXTERNAL", "DESTRUCTIVE"]
},
{ "operator": "equals", "field": "execution.mode", "value": "LIVE" }
]
},
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "This is a new (CANDIDATE) plan that has external side effects. Please review before approving.",
"on_timeout": "DENY"
}
},
{
"rule_id": "candidate-force-dryrun-first",
"name": "candidate_suggest_dryrun",
"description": "CANDIDATE plans should run in DRY_RUN first when they have write effects",
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "plan.lifecycle_state", "value": "CANDIDATE" },
{
"operator": "in",
"field": "plan.aggregate_effect_class",
"value": ["WRITE_INTERNAL", "WRITE_EXTERNAL", "DESTRUCTIVE"]
}
]
},
"action": {
"type": "WARN",
"reason": "This CANDIDATE plan has write effects. Consider running in DRY_RUN mode first."
}
}
],
"metadata": {
"author": "zakardo-runtime",
"created_at": "2026-01-01T00:00:00Z",
"enabled": true,
"priority": 800
}
}
{
"policy_id": "default-audit-logging",
"name": "default_audit_logging",
"version": "1.0.0",
"description": "Log all REMOTE and DESTRUCTIVE operations for audit",
"scope": { "environment": "*", "tenant": "*", "user": "*" },
"rules": [
{
"rule_id": "log-remote",
"name": "log_remote_operations",
"description": "Log all operations with REMOTE boundary",
"condition": {
"operator": "equals",
"field": "capability.boundary",
"value": "REMOTE"
},
"action": { "type": "LOG" }
},
{
"rule_id": "log-destructive",
"name": "log_destructive_operations",
"description": "Log all DESTRUCTIVE operations with warning level",
"condition": {
"operator": "equals",
"field": "capability.effect_class",
"value": "DESTRUCTIVE"
},
"action": { "type": "LOG" }
}
],
"metadata": {
"author": "zakardo-runtime",
"created_at": "2026-01-01T00:00:00Z",
"enabled": true,
"priority": 500
}
}
PolicyEffectCan Be Disabled?
Execution Mode ConstraintsSIMULATED=READ only, DRY_RUN=no external, LIVE=allYes, but strongly discouraged.
Destructive ApprovalDESTRUCTIVE + LIVE requires approval gateYes.
Candidate Plan SafetyCANDIDATE + external effects + production requires approvalYes.
Audit LoggingREMOTE and DESTRUCTIVE operations are loggedYes.

The governance matrix (defined conceptually in the Capability System Specification, Section 3.4) is implemented through default policies plus developer-authored policies.

Effect ClassBoundaryDefault Governance
READLOCALLOG_ONLY (via audit logging)
READREMOTELOG (via audit logging: remote boundary)
READUSER_ENVLOG
WRITE_INTERNALLOCALLOG. WARN for candidate plans.
WRITE_INTERNALUSER_ENVLOG.
WRITE_EXTERNALREMOTELOG. GATE (APPROVAL) for candidate plans in production. Outbox enforced (by Execution Engine, not policy).
DESTRUCTIVELOCALGATE (APPROVAL) in LIVE mode.
DESTRUCTIVEREMOTEGATE (APPROVAL) in LIVE mode. Outbox enforced.
DESTRUCTIVEUSER_ENVGATE (APPROVAL) in LIVE mode.

Developers add policies to tighten governance beyond defaults. Common patterns:

Require approval for all external writes (not just destructive):

{
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "capability.effect_class", "value": "WRITE_EXTERNAL" },
{ "operator": "equals", "field": "capability.boundary", "value": "REMOTE" },
{ "operator": "equals", "field": "execution.mode", "value": "LIVE" }
]
},
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "External write operation requires approval."
}
}

Deny all DESTRUCTIVE operations for non-admin users:

{
"condition": {
"operator": "and",
"conditions": [
{ "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" },
{
"operator": "not",
"condition": { "operator": "contains", "field": "user.roles", "value": "admin" }
}
]
},
"action": {
"type": "DENY",
"reason": "Only administrators can execute destructive operations"
}
}

Require review for plans with more than 10 steps:

{
"condition": {
"operator": "greater_than",
"field": "plan.step_count",
"value": 10
},
"action": {
"type": "GATE",
"gate_type": "REVIEW",
"message": "This plan has more than 10 steps. Please review before execution."
}
}

Gates are the user-facing enforcement mechanism. When a policy triggers a GATE action, the Execution Engine pauses and the frontend presents a gate UI.

1. Policy Engine returns GATE action for a step (or plan).
2. Execution Engine pauses execution.
3. Execution Engine records gate trigger in Trace.
4. A2UI Composition produces Gate A2UI messages:
- Uses gate_type to select appropriate A2UI components (GatePrompt, etc.)
- Includes the gate message and context data
- Includes approval/rejection options
5. Gate A2UI messages streamed to frontend via SSE.
6. A2UI Renderer renders the gate surface.
7. User responds:
a. APPROVE: Execution resumes. Gate resolution recorded in Trace.
b. DENY/REJECT: Execution aborts. Gate rejection recorded in Trace.
c. TIMEOUT: on_timeout action applied (DENY or auto-APPROVE).
8. If approved: step proceeds.
9. If denied/rejected: Execution Engine handles per plan's error policy (abort, compensate, etc.)

9.2 Gate vs. Interaction Point (Clarification)

Section titled “9.2 Gate vs. Interaction Point (Clarification)”

Both Gates and Interaction Points pause execution and show UI. The distinction matters:

AspectGateInteraction Point
Triggered byPolicy Engine (governance rules)Capability (Interaction Spec)
PurposeProtection — “should this happen?”Enablement — “what should happen?”
WhenBefore the capability executesAfter the capability executes (it has already produced data)
User actionApprove/Deny/AcknowledgeSelect/Compare/Review/Input/Confirm
SkippableDepends on policy (usually no)Depends on Interaction Spec constraints
Recorded asGate resolution in TraceInteraction response in Trace

A single step can trigger both: first a gate (policy says “approve this external write”), then an interaction point (capability says “user must select which item to send”). They happen in sequence: gate first, then interaction.

9.3 v1 Gate Model: Synchronous, Same-Session

Section titled “9.3 v1 Gate Model: Synchronous, Same-Session”

In v1, gates are synchronous and same-session only:

  • The approvers field on a gate means “the current user must have one of these roles to approve.”
  • If the current user matches an approver role: they see the gate UI and can approve/deny.
  • If the current user does not match any approver role: the gate resolves as DENY automatically. The user sees a message explaining what role is required.
  • There is no async gate suspension. No notification to external approvers.
  • There is no execution state persistence across sessions for gate resolution.

This is acceptable because the Planner is policy-aware (see Section 6.2). If a plan step would require approval from a role the current user doesn’t have, the Planner should have already found an alternative capability path (e.g., the request pattern). Gate DENY due to role mismatch is a safety net, not the primary user experience.

Example of same-session gate:

User role: "admin"
Step: delete_customer_account (DESTRUCTIVE)
Policy triggers: APPROVAL gate, approvers: ["admin", "super_admin"]
→ User is "admin" → gate UI shown → user approves → step executes.

Example of auto-DENY gate:

User role: "support_agent"
Step: delete_customer_account (DESTRUCTIVE)
Policy triggers: APPROVAL gate, approvers: ["admin"]
→ User is "support_agent" → no matching role → auto-DENY.
→ But this should rarely happen because the Planner's policy pre-check
would have redirected to request_account_deletion.

9.4 v2 Gate Model (Future): Async, Cross-Role

Section titled “9.4 v2 Gate Model (Future): Async, Cross-Role”

v2 will introduce async gate resolution for cross-role approvals:

  • When a gate requires a role the current user doesn’t have, execution suspends instead of denying.
  • A notification is sent to eligible approvers (via the host app’s notification system).
  • The approver reviews the gate asynchronously and responds.
  • The Execution Engine resumes (or aborts) based on the approver’s response.
  • This requires persistent execution state and long-lived suspended plan contexts.

v2 is documented here for planning purposes but is not part of the v1 design.

If multiple policies trigger gates for the same step, the user sees all of them in priority order. Each gate must be resolved before the next is presented. If any gate is denied, execution aborts.


Policies are versioned using semver:

ChangeVersion Bump
Fix a description or messagePATCH
Change a rule’s message textPATCH
Add a new ruleMINOR
Add a new policy scope fieldMINOR
Remove a ruleMAJOR
Change a rule’s conditionMAJOR
Change a rule’s action type (e.g., GATE to DENY)MAJOR
Change the scope to be more or less restrictiveMAJOR
StateMeaning
enabled: truePolicy is active and evaluated.
enabled: falsePolicy is registered but skipped during evaluation.
DeletedPolicy is removed from the registry.

There is no “deprecated” state for policies. Policies are either enabled or disabled. If a policy is no longer needed, disable it first (to verify nothing breaks), then delete it.

Policies can be authored through:

MethodDescription
JSON filesPolicies defined as JSON in the project repository. Loaded at runtime startup.
Runtime APIPolicies created/updated via the API. Allows dynamic policy management.
Zakardo CloudPolicies managed centrally in the Zakardo Cloud dashboard and synced to runtimes.
CLIzakardo policy create, zakardo policy list, zakardo policy enable/disable.

Plan Enrichment interacts with the Policy Engine in two ways:

During enrichment, when building the Full Plan IR from a Plan Draft:

  • Enrichment computes execution_constraints.aggregate_effect_class from the capabilities.
  • Enrichment sets execution_constraints.require_plan_approval based on whether any default policy would trigger a plan-level gate for this effect class.
  • Enrichment sets default execution_constraints.allowed_modes based on the aggregate effect class (e.g., if all capabilities are READ, all modes are allowed).

These are hints in the Plan IR. The actual policy evaluation happens at validation and execution time.

In a future version, enrichment could query the Policy Engine to pre-compute which steps will trigger gates and annotate the Plan IR accordingly. This would allow the Plan Preview to show the user where gates will appear before execution starts.


Every policy evaluation is recorded in the Trace.

EventRecorded Data
Pre-execution evaluationMatched rules, outcome (ALLOW/DENY/GATE), evaluation context snapshot
Per-step evaluationMatched rules, outcome, evaluation context for that step
Gate triggerGate type, message, approvers, timeout
Gate resolutionUser response (approved/denied), response timestamp, responder identity
Gate timeoutTimeout action applied (DENY/auto-APPROVE)
Policy WARNWarning message, matched rule
Policy DENYDenial reason, error code, matched rule

The combination of policy evaluation records and gate resolutions in the Trace provides a complete audit trail:

  • Who approved what, when, and why.
  • Which policies matched and which didn’t.
  • How the evaluation context looked at decision time.
  • Whether any gates timed out and what happened.

This audit trail is immutable (per the Trace system’s append-only design) and supports compliance requirements.


13. Complete Example: Financial Transaction Policies

Section titled “13. Complete Example: Financial Transaction Policies”

A company building a financial application with Zakardo might define these policies:

{
"policy_id": "fin-001",
"name": "high_value_transaction_approval",
"version": "1.0.0",
"description": "Transactions above $10,000 require manager approval",
"scope": {
"environment": "production",
"tenant": "*",
"user": "*",
"capability_tags": ["financial", "payment", "transfer"]
},
"rules": [
{
"rule_id": "high-value-gate",
"name": "high_value_approval",
"description": "Require manager approval for high-value financial operations",
"condition": {
"operator": "and",
"conditions": [
{
"operator": "in",
"field": "capability.effect_class",
"value": ["WRITE_EXTERNAL", "DESTRUCTIVE"]
},
{ "operator": "equals", "field": "execution.mode", "value": "LIVE" }
]
},
"action": {
"type": "GATE",
"gate_type": "APPROVAL",
"message": "This financial operation requires manager approval for amounts above $10,000.",
"approvers": ["role:finance_manager", "role:admin"],
"timeout_ms": 86400000,
"on_timeout": "DENY"
}
}
],
"metadata": {
"author": "finance-team",
"created_at": "2026-02-05T12:00:00Z",
"enabled": true,
"priority": 700
}
}
{
"policy_id": "fin-002",
"name": "financial_compliance_logging",
"version": "1.0.0",
"description": "All financial operations must be logged for compliance",
"scope": {
"environment": "*",
"tenant": "*",
"user": "*",
"capability_tags": ["financial"]
},
"rules": [
{
"rule_id": "log-all-financial",
"name": "log_financial_operations",
"description": "Log all financial capability invocations",
"condition": {
"operator": "exists",
"field": "capability.name"
},
"action": { "type": "LOG" }
}
],
"metadata": {
"author": "compliance-team",
"created_at": "2026-02-05T12:00:00Z",
"enabled": true,
"priority": 600
}
}
{
"policy_id": "fin-003",
"name": "no_destructive_in_staging",
"version": "1.0.0",
"description": "DESTRUCTIVE operations are denied in the staging environment for financial capabilities",
"scope": {
"environment": "staging",
"tenant": "*",
"user": "*",
"capability_tags": ["financial"]
},
"rules": [
{
"rule_id": "deny-destructive-staging",
"name": "deny_destructive_staging",
"description": "Block all destructive financial operations in staging",
"condition": {
"operator": "equals",
"field": "capability.effect_class",
"value": "DESTRUCTIVE"
},
"action": {
"type": "DENY",
"reason": "DESTRUCTIVE financial operations are not permitted in staging",
"error_code": "POLICY_FIN_NO_DESTRUCTIVE_STAGING"
}
}
],
"metadata": {
"author": "finance-team",
"created_at": "2026-02-05T12:00:00Z",
"enabled": true,
"priority": 700
}
}

DecisionResolution
Policy formatDeclarative JSON documents. Not code.
Policy scopingHierarchical: environment > tenant > user, with optional tag filtering. Wildcards supported.
Rule conditionsStructured predicate logic over an evaluation context (capability, plan, step, execution, user metadata). Same operator set as Plan IR conditions.
Action typesGATE, DENY, WARN, LOG, REQUIRE_MODE, MODIFY_CONSTRAINT. Six types covering blocking, non-blocking, and informational actions.
Gate typesAPPROVAL, INPUT, REVIEW, LOG_ONLY. Four types matching governance needs.
Evaluation pointsThree: pre-generation (Planner, lightweight), pre-execution (Validator, full plan), per-step (Execution Engine). Same engine, same rules. Pre-generation is the most important for UX.
Plans always succeedThe Planner performs policy pre-checks during backward chaining. If a capability is blocked, the Planner finds alternatives (request pattern). Plans are built only from capabilities the user can execute.
v1 Gate modelSynchronous, same-session. If user lacks approver role, gate auto-DENYs. This is acceptable because the Planner should have already found an alternative.
v2 Gate model (future)Async cross-role approvals. Execution suspends, notification sent to eligible approvers. Requires persistent execution state.
Authorization modelFour layers: Identity (external), API Access (external), Execution Governance (Zakardo Policy Engine), Data Authorization (capability implementation).
Conflict resolutionDENY > GATE > ALLOW. Higher priority wins. Same-priority defaults to more governance. Warnings and logs are always additive.
Default policiesFour shipped policies: execution mode constraints, destructive approval, candidate plan safety, audit logging. All overridable.
Gate lifecycleTrigger -> pause -> send view to frontend -> wait for response -> resume or abort -> record in Trace.
Gate vs. Interaction PointGates are policy-driven (before execution). Interaction Points are capability-driven (after execution). Both pause and show UI.
Trace integrationEvery evaluation, gate trigger, and resolution recorded in the Trace for audit.
Policy versioningSemver. Enabled/disabled state. No “deprecated” — disable then delete.
Authoring methodsJSON files, Runtime API, Zakardo Cloud dashboard, CLI.

QuestionDeferred To
How are gate approvals routed to specific users or roles?Runtime API and SDK Specification (notification/routing mechanism)
Can policies trigger asynchronous workflows (e.g., email an approver)?Execution Engine Specification
How are policies synced between Zakardo Cloud and local runtimes?PRD — Zakardo Cloud
Can policies reference runtime data (e.g., “deny if transaction amount > $10,000”)?See Section 15.1
How do policies interact with sub-plan execution?Execution Engine Specification

15.1 Runtime Data in Conditions (v1: Static Only)

Section titled “15.1 Runtime Data in Conditions (v1: Static Only)”

v1 Decision: Policies evaluate static metadata only. Value-based governance (e.g., “require approval if amount > $10,000”) is the capability’s responsibility via Interaction Specs. The capability knows its data semantics and can trigger a CONFIRM interaction for high-value operations. The policy system does not inspect runtime values.

Rationale:

  • Keeps the policy engine simple and fast (no dependency on execution state).
  • Clean separation: policies govern structure (what kind of operation), capabilities govern value (what specific data).
  • A capability that processes financial transactions should declare a CONFIRM interaction for high-value operations regardless of policy — it’s domain logic, not governance.

Future Evolution Options (post-v1):

These are documented for future consideration but are NOT part of the v1 design:

  1. Runtime context extension. Extend the evaluation context to include step.input_values and step.output_values. Policies could then reference actual runtime data. Trade-off: adds power but policies become dependent on execution state, harder to reason about statically, and harder to preview in Plan Preview.
  2. Capability policy hooks. Capabilities declare specific output fields as “policy-observable.” The policy engine evaluates only those declared fields, not the full output. Trade-off: targeted power without full runtime context exposure, but adds coupling between capability definitions and policies.
  3. Post-execution policy evaluation. A third evaluation point (after step execution, before writing to Execution Context) that can inspect outputs and trigger gates retroactively. Trade-off: enables value-based governance without pre-execution complexity, but means the capability has already run (side effects may have occurred).