Repository navigation
Diagram taint propagation and the scan pipeline #139
Description
Mermaid diagrams render on the docs site now, and there are five of them. The two concepts that most need one do not have one.
Taint propagation. Source.USER vs Source.RETRIEVED vs tool output, how taint attaches, how it survives across a turn, and what reset_session_taint() clears. This is the central idea in the SDK and it is currently explained only in prose across AGENT_FLOW_SECURITY.md and AGENT_ACTIONS.md.
The scan pipeline. What actually happens between guard.scan(text) and a ScanResult: normalization stages, the scanner fan-out, span merging, the policy decision that picks ALLOW / REDACT / REVIEW / BLOCK. ARCHITECTURE.md has the layering diagram but nothing showing a scan in motion.
This is labelled mentored, which means a maintainer works through it with you and questions on this thread are the point, not an interruption.
Where to start reading:
sdk/src/unplug/core/taint/for the first diagramsdk/src/unplug/pipelines/andsdk/src/unplug/core/policy/for the seconddocs/ARCHITECTURE.mdfor the mermaid style already in use
The diagram is the deliverable, but understanding the flow well enough to draw it is the actual goal. Expect to ask questions before you write any mermaid, and expect the first version to be wrong in an interesting way.
Acceptance:
- Both diagrams render on the site and match what the code does.
- Each sits in the page where a reader needs it, not in a diagrams appendix.
mkdocs build --strictpasses.
Comment here to claim it and a maintainer will assign it.
Activity
Kxrma47 commentedon Sep 12, 2026
Hi! I would like to claim this mentored documentation task. I will trace taint propagation and the scan pipeline from the referenced code, draft the two Mermaid diagrams in the pages where readers need them, and verify mkdocs build --strict. I would appreciate the intended paired workflow: I can post an initial flow outline here for maintainer correction before writing the diagrams, then incorporate GitHub review suggestions in the PR. Please assign me if it is still available.
chiruu12 commentedon Oct 6, 2026
Yours. Outline first is what I want here, so post the flow in this thread before drawing anything and I will correct it.
Two diagrams, taint propagation and the scan pipeline. Put each one on the page where a reader meets the concept rather than collecting them on a diagrams page.
Kxrma47 commentedon Oct 7, 2026
Thanks, @chiruu12. Here is a preliminary outline against
devat056c86f, before drawing anything.For taint propagation, I would separate per-text provenance from session state.
Source.USER,Source.RETRIEVED, andSource.TOOL_OUTPUTmap to distinctTrustLevelvalues; derived text keeps its parent's trust and origin. Non-isolated local scans of retrieved content or tool output mark the shared session tainted even when the content passes the scan. A later user scan records intent but does not automatically clear that taint. The next side-effect tool can require REVIEW.reset_session_taint()explicitly clears session taint, trigger labels, and degradation, but does not clear conversation, risk history, user intent, or past tool calls. I would put this diagram inAGENT_FLOW_SECURITY.md, with a link fromAGENT_ACTIONS.md.For the local scan pipeline, I would show input limits, request context and optional cache, boundary wrapping and trust tagging, encoding checks, shared normalization when configured, non-ML scanners, conditional ML, and the optional judge. Scanner iteration is sequential here, so I would not draw parallel execution.
BasePipelinethen incorporates trajectory and sensitive-context signals, calculates risk, and applies coverage/span policy before buildingScanResult. The policy can also emit ABSTAIN; overlapping spans are merged for coverage rather than replacing the findings. I would place this diagram beside the layering explanation inARCHITECTURE.md.Would you prefer the taint diagram in
AGENT_ACTIONS.mdinstead? I used Codex to assist this source analysis. Your mentored-contribution guide requires contributors to write their own patches, so I am checking that boundary before any diagram patch; any model-written patch would be disclosed as your policy requires.