Skip to content

docs: stop claiming Provena blocks context before the LLM - #203

Open
yuee3 wants to merge 1 commit into
rajfirke:mainfrom
yuee3:docs/llm-gate-wording
Open

yuee3 wants to merge 1 commit into
rajfirke:mainfrom
yuee3:docs/llm-gate-wording

Conversation

@yuee3

@yuee3 yuee3 commented Sep 22, 2026

Copy link
Copy Markdown

What

Stop presenting Provena as an in-line gate that blocks bad context before it reaches the LLM. Documentation accuracy only — no runtime change.

  1. Rewrite the Architecture ASCII diagrams in README.md and docs/index.md so Provena is not drawn as ContextTrail ---> LLM Context Window. The replacement conveys: sources are observed/logged into the trail (passive by default); optional policies may WARN/BLOCK after persist; the LLM path is the application's, not Provena's.
  2. Replace the README example comment that claimed pre-LLM blocking (# Blocked: freshness_check failed — STALE context blocked before reaching LLM) with wording that says the PolicyViolation is raised after the record was written, and that with @track the wrapped call has already finished.
  3. Soften the Policy Enforcement table BLOCK row so it no longer implies call-site gating: raise PolicyViolation after persist; default trails with policies=None only observe/log.
  4. Keep the already-correct "blocked entries are always persisted" line — it now reads as the compliance story instead of competing with "before reaching the LLM".

Why

Closes #199. New users reading the hero README / docs landing page would believe Provena sits in front of the LLM. In src/provena/trail.py, _log_internal appends (or buffers) the record, then _enforce_policies; empty PolicyEngine always ALLOWs; @track calls func first and only then _track_result / _log_internal. The gate language created false security expectations.

Narrower than #56 and not a duplicate — this is specifically the false "blocked before the LLM" claim.

How checked

  • Read src/provena/trail.py (log / _log_internal, _enforce_policies, @track) and confirmed persist-then-policy order and that @track runs the wrapped body to completion before logging.
  • Matched every "What to do" item in README and docs/index overstate blocking context before the LLM #199 to a concrete edit.
  • Documentation-only. No code, config, or project-context/learning-guide.md touched.

Scope

  • README.md — Architecture diagram; E2E example comment; Policy Enforcement BLOCK row
  • docs/index.md — Architecture diagram

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README and docs/index overstate blocking context before the LLM

1 participant