# Authority, conflicts, and resolution The rule this whole area serves: **the resolver never quietly guesses.** When two canonical objects contradict each other, both survive into the bundle's warnings and a strict run fails. The alternative — silently picking one — produces an agent confidently acting on a policy that half the organization believes was replaced, with nothing in the output suggesting anything was wrong. ## Authority is declared, not inferred ```txt canonical the organization's own source of truth approved reviewed and sanctioned reference useful, not binding observed seen in the wild, unverified inferred derived by a model or heuristic historical retained for the record only ``` Authority is set by whoever owns the context. It is never derived from: - **retrieval rank** — the top embedding hit is not thereby the truth; - **recency** — a note written this morning does not outrank a reviewed policy; - **the content itself** — an object saying "THIS IS CANONICAL" stays whatever its metadata says. That last one matters most once context flows in from tickets and chats. See [security](./security.md). ### Reordering precedence ```yaml authority: precedence: [canonical, approved, reference, observed, inferred, historical] ``` The list may be reordered but must remain a permutation of all six. Omitting a level would leave objects at it unrankable; adding one would let a repository define something that outranks canonical. An unknown authority sorts *last*, never first. ## Resolution order ```txt 1. authorization 2. temporal validity 3. explicit scope 4. authority 5. supersession and version 6. recency 7. configured tie breakers ``` Authorization is first, always. An object the consumer may not read is removed before freshness, ranking, or compilation ever sees it — so it cannot reach a ranker, a prompt, or even an explanation. ## Tie breakers ```yaml authority: tie_breakers: [version, updated, confidence, id] ``` Applied in order when authority does not settle it. `id` is always appended, so ordering is **total** and two runs over the same sources produce the same bundle. Without a total order, resolution would depend on filesystem enumeration and digests would drift. `confidence` breaks ties *within* a level. It never promotes across levels. ## Supersession Supersession is **declared**, never inferred: ```yaml # the replacement id: pricing.enterprise version: 2 supersedes: - pricing.enterprise@1 ``` ```yaml # or on the replaced object id: decisions.2026-02-01-postgres authority: historical superseded_by: decisions.2026-08-01-postgres-ha ``` Both directions work. A reference to something that does not exist is an error, because a broken chain silently resurrects retired policy. ### Why version numbers are not enough A higher `version` on disk does **not** imply supersession. It would be convenient, and it would be the resolver guessing. Two active canonical versions of one policy is a real governance failure — a rewrite landed and nobody declared what it replaced. Inferring the link hides exactly that, and makes `multiple-active-versions` and `duplicate-canonical` impossible to detect. So instead: resolution still returns one winner (the `version` tie breaker), the loser is reported as `outranked`, and validation raises the missing link. ```txt ✗ duplicate-canonical: 2 active canonical objects share the id "policies.refunds" → Supersede the older one, or lower its authority to reference. ⚠ multiple-active-versions: 2 active versions of "policies.refunds" (versions 1, 2) → Add supersedes: [policies.refunds@1] to the newer object. ``` ### Versions and history Superseded objects stay on disk. That is the point — it preserves the ability to answer "what did we believe in March", which deletion destroys. ```bash opencontext resolve --role sales # current only opencontext resolve --role sales --include-historical # every version opencontext history pricing.enterprise ``` ## Conflicts Declare a known contradiction: ```yaml id: policies.refunds authority: canonical conflicts_with: [policies.refunds-observed] ``` Three outcomes: | Situation | Code | Severity | | --- | --- | --- | | Conflict between equal-authority objects | `conflict-ambiguous` | error | | Conflict authority settles | `conflict-declared` | warning | | Two active canonical objects for one id | `duplicate-canonical` | error | A settled conflict is *still reported*. The higher authority wins, and the losing side is named, so nothing disappears without a trace. A conflict declared on only one side is still detected. Pairs are deduplicated by the unordered pair, not by id ordering — otherwise a conflict would vanish depending on alphabetical luck. ## What `--explain` shows ```bash opencontext resolve --role support --task "refund" --explain ``` ```txt Included: ✓ mission canonical ✓ policies.refunds canonical ✓ procedures.refund approved Excluded: - decisions.2026-08-09-adopt-opencontext not-in-scope (no include pattern matches) - policies.internal.margins scope-exclusion (excluded by "policies.internal.*") - pricing.enterprise superseded by pricing.enterprise - policies.old outranked by policies.refunds Warnings: ! stale policies.legacy: has not been updated inside its freshness window. Digest: sha256:81b41a91… ``` Exclusion reasons are a closed set: `permission-denied`, `classification-denied`, `scope-exclusion`, `not-in-scope`, `superseded`, `expired`, `not-yet-valid`, `outranked`, `unapproved`, `not-relevant`, `conflict`, `source-unavailable`. ## Relevance ranking Ranking decides **order**, and — only when you ask — what gets trimmed. It never decides access. The scorer is lexical on purpose. Semantic search is a legitimate adapter concern, but requiring an embedding model to resolve context would make resolution non-deterministic and put a model vendor in the path of a specification whose entire point is that vendors are replaceable. Signals, strongest first: `applies_to`, `tags`, `title`, `id`, `summary`, `type`, then content (weighted lowest and capped, so a long document cannot outrank a precisely-titled one by containing more words). L0 mission and L1 identity carry a floor score, so they stay in the bundle even when a ticket does not mention them. Dropping them because the task was narrow is how a replacement agent loses the organization's voice. ### Trimming By default resolution returns **everything authorized**, ranked. Trimming silently would be worse than a large bundle. ```bash opencontext resolve --role support --task "refund" --limit 10 opencontext resolve --role support --task "refund" --min-relevance 4 ``` Trimmed objects are reported as `not-relevant` exclusions — visible, not silent. ## Determinism Two resolutions with the same inputs over the same source state produce the same bundle and the same digest. The digest covers the resolved objects, their computed lifecycle states, the exclusions, and the warnings. It excludes `generated_at`, `bundle_id`, `digest` itself, and `as_of`. `as_of` is excluded deliberately, and it is worth being precise about why, because it looks like a resolution input. Resolving at two different instants only matters if it *changes what was selected* — and any such change already shows up, because every object's `lifecycle` and the full object, exclusion, and warning lists are inside the digest. Two resolutions that select the same context at the same lifecycle states *are* the same context, and should digest identically whether they ran a second or a month apart. That is exactly the property a decision record needs when it cites the context it was made from.