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

# Policy

> A policy is a lifecycle rule you attach to a stack: automatic cleanup after a duration, or automatic enforcement of declared state.

A policy is a configurable behavior you attach to a stack. Where a forma declares what resources should exist, a policy declares how formae should manage the stack's lifecycle over time, without you having to run another `apply`.

formae has two built-in policy types:

* **[TTL policy](/documentation/concepts/policies/ttl)**: destroys a stack and its resources after a set duration.
* **[Auto-reconcile policy](/documentation/concepts/policies/auto-reconcile)**: re-applies the stack's declared state at a fixed interval, undoing out-of-band and incremental changes.

## Inline vs. reusable policies

You can define a policy two ways.

**Inline policies** live directly inside a stack definition. They belong to that stack alone and are deleted along with it.

```pkl theme={"languages":{"custom":["/languages/pkl.json"]}}
new formae.Stack {
  label = "dev-environment"
  policies = new Listing {
    new formae.TTLPolicy {
      ttl = 4.h
      onDependents = "cascade"
    }
  }
}
```

**Reusable policies** are standalone objects, defined once and referenced from any number of stacks with `.res`. Changes to the policy propagate to every stack that references it.

```pkl theme={"languages":{"custom":["/languages/pkl.json"]}}
local ephemeralPolicy = new formae.TTLPolicy {
  label = "ephemeral-1h"
  ttl = 1.h
  onDependents = "abort"
}

forma {
  ephemeralPolicy

  new formae.Stack {
    label = "dev-stack-1"
    policies = new Listing { ephemeralPolicy.res }
  }

  new formae.Stack {
    label = "dev-stack-2"
    policies = new Listing { ephemeralPolicy.res }
  }
}
```

| Aspect    | Inline                                                  | Reusable                                |
| --------- | ------------------------------------------------------- | --------------------------------------- |
| Label     | None                                                    | Required                                |
| Lifecycle | Follows the stack's declaration; deleted with the stack | Independent, must be explicitly deleted |
| Sharing   | Single stack only                                       | Any number of stacks                    |
| Use case  | One-off behavior                                        | Consistent policy across stacks         |

<Tip>
  Reach for a reusable policy as soon as you find yourself copying the same `ttl` or `interval` value into more than one stack. A single source of truth means one edit updates every stack that uses it.
</Tip>

## Removing a policy

In reconcile mode, the applied forma is the source of truth for a stack's policies, the same way it is for the stack's resources:

* **Inline policy**: re-apply the stack without the policy in its `policies` listing, and the policy is deleted.
* **Reusable policy**: re-apply the stack without the `.res` reference, and the policy is detached from that stack. The standalone policy object itself lives on, attached to whatever other stacks still reference it, until it is destroyed.

This also means an inline policy added outside the forma (for example through an operator tool) does not survive the next reconcile of a stack the forma declares: declare it in the forma to keep it. Patch mode never touches policies you don't mention.

## Querying policies

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae inventory policies
```

Lists reusable policies only, since inline policies have no independent identity outside their stack. To see which policy, inline or reusable, is attached to a given stack, check the stack itself:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae inventory stacks
```

## See also

* [TTL policy](/documentation/concepts/policies/ttl): automatic cleanup after a duration.
* [Auto-reconcile policy](/documentation/concepts/policies/auto-reconcile): automatic enforcement of declared state.
* [Stack](/documentation/concepts/stack): the unit a policy attaches to.