Policy Authoring

Policy vs config

Policy and config are separate namespaces by design.

• Policy is control-plane-governed, versioned, and audited.
• Config is local operator preference and is not a policy authority surface.

Policy changes affect permit issuance, approval behavior, checkpoint behavior, trust-tier mapping, and audit-chain interpretation. Config changes affect local UX defaults such as output formatting and local preferences.

This separation is mandatory and must not be merged (per PC-004, CLI-004).

v1 deployment note This page describes the v1 local-embedded deployment. Team and enterprise deployments use syndicate-server and can differ in policy distribution and activation workflow, while policy authority and audit requirements remain the same.

Policy bundle

The policy bundle is the activation unit for policy lifecycle operations.

The bundle wire format is implementation-defined. Use validation first:

syndicate policy validate <bundle-path>

A new policy version is required when any governed rule semantics change, including capability rules, provider routing rules, network rules, secret rules, delegation rules, trust-tier mapping rules, approval-friction rules, checkpoint rules, retention/redaction rules, emergency overlays, or canonicalization-version references (per policy_versioning_and_upgrade_spec.md §3.2).

Five policy principles

• PC-001: Policy is authoritative.
• PC-002: Capabilities are explicit.
• PC-003: Least privilege by default.
• PC-004: Separation of concerns.
• PC-005: Policy must be explainable.

Source: policy_and_capability_model.md §2.

Applying policy

# Validate before applying
syndicate policy validate ./policy-bundle.toml

# Apply a new policy bundle
syndicate policy apply ./policy-bundle.toml

# Dry run validation/diff with no activation
syndicate policy apply --dry-run ./policy-bundle.toml

Activation must be atomic: no proposal may observe partial policy state (per PV-003). If a policy cannot be loaded or validated, control plane policy evaluation and permit issuance must not proceed; no degraded policy mode is permitted (per PV-009).

Policy version identity

Policy version format is:

policy_version: "<counter>:<sha256-of-canonical-bundle>"

Example:

policy_version: "7:a3f8c2d1..."

The counter provides strict ordering and the hash provides verifiable content identity. This is not semantic-version labeling. Given a policy version identifier, the exact active policy is reconstructable (per PV-002, policy_versioning_and_upgrade_spec.md §3.1).

Rollback

syndicate policy rollback <version-identifier>

Rollback is a first-class governed operation (per PV-007). Rollback activation increments the counter; it does not reuse historical counter values (per policy_versioning_and_upgrade_spec.md §14.2).

Historical evidence remains valid after rollback. Prior executions stay readable and replayable under their recorded policy version (per PV-004).

syndicate policy command surface