# orientation

Orientation is instruction that persists and that the session actually selected: staged as
an immutable candidate, then adopted with an operation id and an application boundary. It is
how "do it this way from now on" becomes testimony someone can point at later, instead of a
sentence in a turn.

## the trail

Stage first. Staging selects nothing.

```python
from klbr import orientation

staged = await orientation.stage(
    "clean-room-first",
    "Verify from a clean room before calling a gate green.",
    "standing responsibility",
    mode="form",
)
```

`current()` is what is actually in force for a scope - the answer to "what am I running
under right now", not what you last staged.

```python
selected = await orientation.current()
```

Adopt by naming the candidate and the parent revision you read. A parent that moved is
refused rather than force-applied: re-read `current()`, re-stage against the new parent, and
adopt again.

```python
receipt = await orientation.adopt(
    "clean-room-first",
    expected_parent=selected["revision_id"] if selected else None,
    apply_at="next_provider_boundary",
)
```

`apply_at="stored_only"` records the selection without applying it. The default boundary
applies at the next provider request, which is the only honest place it can apply: a request
already in flight cannot be rewritten.

Modes - `form`, `situate`, `elaborate`, `repair_return` - choose a steering template, and
`carrier_placement` says which part of the request carries the text (`header`,
`leading_system`, `prefix`, `tail`, `scoped_directive`). Scope controls what the revision
covers: global, one project, one work item, one session.

## receipts

An adoption returns a receipt and lands in the durable events with its operation id. Staging
leaves a candidate you can abandon without consequence.

## refusals

A stale parent conflict is a refusal, not a merge. Adoption never rewrites history: it
selects a revision that a later read will find.