# Trust boundaries and policies

A `Boundary` names the information-flow decision made during packing. It does not mutate item labels, and it does not send data anywhere.

```python
internal = cx.Boundary.internal("application")
external = cx.Boundary.external("openai")
```

## Core policy matrix

For optional and preferred items, a violation creates a manifest exclusion. For required items, the same violation raises `PolicyViolation` because silently dropping the item would break its retention contract.

| Item condition | Internal boundary | External boundary |
| --- | --- | --- |
| Expired | Excluded / required raises | Excluded / required raises |
| `quarantined` | Excluded / required raises | Excluded / required raises |
| No `sources` | Allowed | Excluded / required raises |
| `restricted` | Allowed | Excluded / required raises |
| Matches a built-in secret pattern | Allowed | Excluded / required raises |
| `untrusted` with provenance | Allowed | Allowed |
| `internal` or `confidential` sensitivity | Allowed | Allowed by the core policy |
| Binary | Not packable in the 0.1 series | Not packable in the 0.1 series |

The table describes the built-in core policy only. Applications often need stricter custom policies for confidential data, tenant separation, source allowlists, or untrusted content.

## Untrusted is a label, not a block

External records default to `untrusted`. Provenance-bearing untrusted content remains eligible until an application policy rejects or quarantines it.

```{testcode}
import cognoxium as cx

frame = cx.CognitionFrame.from_records([
    {"id": "web", "payload": "Public web result", "sources": ["https://example.com"],
     "created_at": "2026-01-01T00:00:00Z"}
])

allowed = frame.pack(budget=100, boundary=cx.Boundary.external("provider"))
blocked = frame.quarantine(lambda row: row["trust"] == cx.Trust.UNTRUSTED).pack(
    budget=100,
    boundary=cx.Boundary.external("provider"),
)

print([item.id for item in allowed.items])
print([(item["id"], item["reason"]) for item in blocked.manifest.excluded])
```

```{testoutput}
['web']
[('web', 'quarantined')]
```

## Required violations

```python
try:
    frame.pack(
        budget=100,
        boundary=cx.Boundary.external("provider"),
    )
except cx.PolicyViolation as error:
    print(error.code)         # CX_POLICY_001
    print(error.item_id)
    print(error.rule_id)
    print(error.boundary)
    print(error.reason_code)
```

Do not retry the same item through a weaker boundary without a separate application authorization decision.

## Custom policies

Pass one or more `Policy` objects to `pack(policies=[...])`. A policy returns `None` to allow an item or a stable reason code to reject it. See {doc}`plugins` for a complete implementation.