Policy Builder

Policy Builder is the policy lifecycle workspace at /policy-studio. The main route and conversational builder require policy:read. Direct operations at /policy-studio/operations require policy:publish.

What it owns

• Policy catalog, scope, versions, rules, and reason codes.
• Guided and advanced rule authoring.
• Simulation against supplied Decision Request context.
• Review submission, approval, publication, compiled pack integrity, and rollback.
• Policy-to-Agent and policy-to-environment bindings.
• Evidence export for one exact policy version through the shared Evidence Factory. The returned manifest is checked for that policy snapshot before download.

Policy detail tabs are Overview, Scope, Rules, Diff, Simulate, Signature, and Versions.

Builder session lifecycle

Opening /policy-studio/builder is read-only. Policy Builder creates a session when an author sends the first message or selects Start draft. Concurrent first actions reuse the same open empty session for that tenant and author. Empty sessions contain no messages, policy state, selected profile, policy check result, token usage, or completed turn. The session list removes empty sessions after 24 hours. Listing sessions performs this cleanup, so repeated cleanup runs are safe.

Published policy packs are versioned and signed. Runtime decisions carry the policy identifier and version into Decision Desk, Lineage Explorer, Audit Trail, and Evidence Room.

Administrator handoffs

Policy Builder prepares a platform administrator handoff when a conversational session assigns connection, permission, configuration, or runtime-validation work to a tenant administrator. The originating session records the delivered handoff and links to its detail route at /policy-studio/admin-handoffs/[sessionId]/[handoffId]. The inbox at /policy-studio/admin-handoffs lists delivered handoffs for the tenant.

The detail view presents business-step mappings, operations, required permissions and credential field names, configuration fields, validation steps, unresolved decisions, and sources. An authorized tenant administrator can continue connection work in Tool Catalog on the Connections tab with the originating bundle revision, session, handoff, connector, and requirement context.

The inbox data requires tenant_admin or super_admin and policy_builder_session:read. Detail data requires policy_builder_session:read and allows the originating session owner, tenant_admin, or super_admin. Tenant scoping applies to both data APIs, and authorization failures disclose no handoff data.

Policy lifecycle

flowchart LR
  D["Draft"] --> S["Simulation"]
  S --> R["Review"]
  R --> P["Publish signed pack"]
  P --> E["Runtime evaluation"]
  E --> O["allow / warn / require approval / block"]
  P --> B["Rollback"]

Blocked drafts stay in the policy catalog, reachable through a blocked filter that shows each remediation blocker. Saved links to the retired policy remediation route permanently redirect into the catalog on the rules tab with that filter applied. A link carrying a policy identifier and version opens that draft.

Server-side validation and authorization remain authoritative for review, publication, and rollback.