> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

> Policy revisions, ownership, restoration, backtests, deletion, and audit history.

Forge maintains one durable identity and an immutable revision history for each
policy.

## Revisions

Creating a policy starts its revision stream. Every successful update:

1. validates the complete family definition;
2. checks the caller's expected current revision;
3. writes a new immutable revision;
4. makes that revision current.

The expected-revision check prevents one writer from silently overwriting
another. Policy hits, violations, approval grants, and audit records retain the
policy ID and exact revision used for their decision.

Restoring an older definition does not make history mutable. Forge copies the
selected historical definition into a new forward revision.

```bash theme={"system"}
forge policies revisions content customer-export
forge policies restore \
  --expected 8 \
  content \
  customer-export \
  5
```

In this example, revision 5 becomes the definition for a new revision after
Forge confirms that revision 8 is still current.

## Enabled state

`enabled: false` excludes the current revision from new evaluations while
preserving:

* the policy identity;
* all prior revisions;
* historical hits and violations;
* approval and audit history;
* management ownership.

Disabling a policy is therefore different from deleting it.

## Ownership

| Ownership          | Writable through                         | Behavior                                         |
| ------------------ | ---------------------------------------- | ------------------------------------------------ |
| Forge-managed      | Console and ordinary API automation      | Both interfaces share one revision stream        |
| Terraform-managed  | The bound Terraform manager and instance | Console and ordinary API writes are read-only    |
| MCP Registry-owned | MCP Registry access settings             | Appears as a read-only Content policy projection |

Terraform ownership records `managementMode = "terraform"` with the bound
manager, instance, and principal. Importing an existing Forge-managed policy
requires an explicit revision-bound authority claim.

Emergency break-glass detachment creates a new Forge-managed revision and
records the required incident reason in the audit trail. The previous
Terraform manager immediately loses write authority.

MCP Registry access rules are stored and evaluated as Content policies but must
be edited from Registry. An organization-authored Content policy may also
target the same MCP server or tool; normal action precedence applies when both
match.

## Backtests

Backtests evaluate an authored Content or Access policy against compatible
historical evidence without changing the deployed policy.

| Mode    | Meaning                                                      |
| ------- | ------------------------------------------------------------ |
| `auto`  | Forge selects an appropriate execution mode                  |
| `quick` | Bounded lower-cost evaluation                                |
| `full`  | Full eligible historical evaluation for the selected filters |

A backtest captures:

* the authored definition;
* the compiled policy snapshot;
* policy source and version;
* requested and effective mode;
* filters and historical target;
* estimated and scanned event counts;
* decisions, hits, diagnostics, and completion status.

Content backtests can filter by time, user, group-expanded user, device,
session, tool, model, integration, and observation kind. Access backtests
support time, user, group-expanded user, device, and observation-kind filters.

A candidate event is compatible historical evidence Forge could replay. It is
not a partial match. The policy still must satisfy its scope and complete
condition tree, and its exception must not match. A completed backtest can
therefore contain candidate events and zero hits.

## Deletion

Deletion tombstones the policy instead of erasing it. The policy stops
participating in new evaluation, but its revisions and historical references
remain available for audit.

Tombstoned policy IDs cannot be reused. Terraform destroy follows the same
history-preserving model for a Terraform-owned policy.

## Audit history

Lifecycle operations record the actor, policy ID, revision, management mode,
and operation context. This includes creation, update, restoration, ownership
changes, break-glass detachment, enablement changes, and deletion.