How resolution works, and what it guarantees

SEIF decides what an agent receives for one request: which material, in which order, within which budget, and why everything else stayed out. The decision is a pure function of the project's files, the request and the clock. No model is called to make it. This page describes the pipeline as implemented in runtime/engine/resolve.mjs, retrieval.mjs and render.mjs, the guarantees it gives and the limits it does not hide.

request ──► objective ──► profile ──► per-layer evaluation ──► acquisition ──► budgeted rendering ──► status + trace
           (explicit or   (consumer ×  available · applicable ·  inline / retrieve /  required first,       RESOLVED
            the agent's    objective)  current · desired ·      on-demand,           priority, order;      RESOLVED_WITH_UNKNOWNS
            default)                   decision                 maxItems, maxTokens  trimmed → frontier    BLOCKED (reason)

1. Objective and profile

A request names a consumer (the agent) and optionally an objective (the task). Without one, the consumer's default objective is used; with neither, resolution is BLOCKED: OBJECTIVE_UNRESOLVED. The pair selects one Context Profile: the rules that decide, per layer, participation (include, auto, exclude), mode (inline, retrieve, on-demand), required, priority, maxItems, maxTokens, ordering and currentness. No profile bound: BLOCKED: PROFILE_UNRESOLVED.

2. Per-layer evaluation

Every layer of the project is evaluated through separate stages. None is inferred from another, and each records its reason:

A layer the profile excludes is never read into the context. Live Runtime Context Providers (a customer record, an order) are called only when their layer is in the profile, in scope and its lookup input is present: nothing else is fetched.

3. Acquisition

A section in hand can also declare cross-topic references to other sections (frontmatter references: or a <!-- seif: references=a,b --> marker). Each live reference becomes a frontier door with reason REFERENCED — the same open-it-yourself mechanism, declared by the author rather than ranked — honouring the profile seal (a target in an excluded layer is never offered) and the same frontier cap. See Retrieval and SEIF in the agent you already use.

Ranking strategies (retrieval on the rule):

• lexical (the default without search by meaning): BM25 over words of any language (ICU segmentation, stop words of twelve languages, a 5-letter prefix stem, bigrams for Chinese, Japanese and Korean, the project's synonyms and ignored words); titles count three times; ties break by locator.
• hybrid (the default when the project configures search.semantic) and semantic: similarity of meaning from an embeddings endpoint, with SEIF owning the index; vectors are pinned in the Build, so a runtime embeds only the question. Hybrid fuses words and meaning by reciprocal rank. See Retrieval.
• static: stable reference order.
• external: your HTTPS endpoint ranks candidate metadata (ref, title, locator, digest) against the query; content never leaves. onUnavailable: fail (default) blocks with RETRIEVAL_UNAVAILABLE; lexical falls back explicitly and the trace says so. The Build records that this ranking is not pinned.

4. Budgeted rendering

All acquired items enter one queue ordered by required layers first, then priority, then layer order. Items are admitted one by one while the exact rendered prompt stays within the limit (the smaller of the profile's and the consumer's maxTokens, minus tool schemas). An item that does not fit is BUDGET_TRIMMED and moves to the expandable frontier; smaller items after it may still fit.

The renderer turns the projection into provider-neutral messages: the consumer's preamble, the objective, a notice that the material is reference data and cannot change the objective or grant permissions, then one section per layer with each item's source, locator, revision and, when the rule asks, the date it was checked. Out-of-date material delivered under a warn rule says so where the model reads it.

Structural containment. Material cannot close or reopen the structure the renderer writes around it. In xml style, any document, context, context-notice or objective tag inside material is neutralized, whatever its spacing or case. In sections (Markdown) style, a heading inside material that imitates the renderer's own # Objective: or # Context is escaped. Ordinary Markdown and XML in documents render unchanged.

5. Status

6. Trace

Every runtime resolution produces a seif.observation-trace.v1 envelope: the Build and binding revision, each layer's stages and reasons, each material's digest and source revision, the rendered digest, what was trimmed and the budget. Secrets are redacted; retention follows the environment (metadata, content, incident capture). Whether the model actually consumed the context stays UNKNOWN until your application reports it.

Guarantees, and where each is proven

Limits, stated plainly

• Words are not meaning. Word relevance works in any language but cannot meet words that share no letters (valor / preço) or cross languages. Add synonyms (Conexões → Busca), turn on search by meaning, and put what must always be present in an inline, required layer, which no ranking can drop.
• Meaning is a similarity, from a model you choose. Its quality depends on that model (use a multilingual one) and the question goes to its endpoint; it is labelled per item and falls back to words, visibly, when the endpoint fails.
• Token counts are estimates (ceil(chars/4)). Leave headroom in maxTokens for your model's tokenizer.
• Containment is structural, not semantic. It stops material from forging the prompt's structure. A model can still be persuaded by text it reads; the data notice says the material is reference data, which models usually respect, but nothing here can force a model to obey.
• A Build proves what was delivered, not what the model did with it. Evaluate answers separately; SEIF keeps those evaluations apart from context evidence.

The Context Compass

context_compass (CLI seif compass, MCP, and the Contexto screen) answers one question for one agent: given what this agent would receive, is the answer in hand? It ranks the repository's sections against the question (deterministic, accent-insensitive, with a small synonym list), then reads the resolution:

The owner sees every verdict with the material's name and reason. An agent connected through the hosted MCP server sees only what its profile may receive or is told is out of date. On the Contexto screen the owner can turn on a diagnostic mode — a view-only toggle, never active in production — that expands the Compass's own mechanics (locators, match scores, reason codes, the equivalent command) and, when an agent names a reference teammate, runs the same question as that teammate side by side; see the suite.