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.

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.

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.

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.