feat: opt-in trace surface on /v1/verify (x-il-trace) - #113
Merged
jsam merged 2 commits intoAug 21, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
A request carrying x-il-trace: 1 gets a trace object inside the consistency block: the validated extraction (post quote-gate), the mapped IQL statements, the ephemeral KG name, the extraction model, and extract/engine wall times. The trace only ever contains data derived from the caller's own request. Untraced requests are byte-identical to before. This makes the text-to-facts translation observable per request - the enabler for il chat's inspection panel and the tutorial's next chapter (#84 plan). Verified live with a real model: traced request returned the two extracted claims, the claim/claim_num/claim_source statements, and timings (extraction 4.7s, engine 830ms); untraced request carries no trace key. Extended the env-gated live pipeline test with trace assertions. verify() refactored (ontology selection extracted into select_ontology) to stay under the line-count lint rather than suppressing it. Full gates green: 3290 workspace tests, fmt, clippy (Rust 1.98, -D warnings), doc.
- The ephemeral KG name embedded a readable server pid and gateway-wide request counter, newly exposed to callers via the trace - one tenant could measure another's traffic. Pid and sequence are still hashed in for per-request uniqueness but no longer readable. - Malformed x-il-trace values now 400 (matching the malformed-header principle x-il-ontology follows) instead of silently disabling tracing; 1/true and 0/false accepted case-insensitively. - The opt-out half of the trace contract (no header, no trace) is now asserted by the live pipeline test; engine_ms documented as including cleanup. Known gap, deliberate: the trace is dropped on verify_in_kg failure paths - consistent with fail-open returning only unverified + reason. Verified live: malformed header 400s, TRUE accepted, traced/untraced contract asserted against a running engine.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First PR of the M1 chain (#84 plan). A request carrying x-il-trace: 1 gets a trace object inside inputlayer.consistency:
(the values above are the literal output of the live verification run)
Why: makes the text-to-facts translation observable per request. This is the enabler for il chat's inspection panel and part two of the getting-started guide.
Tested: live with a real model (traced request returned the extracted claims, mapped IQL, and timings; untraced carries no trace key); the env-gated live pipeline test now asserts trace contents; 3290 workspace tests, fmt, clippy (Rust 1.98, -D warnings), doc all green.