docs(grammar): a typed capture is interpolated, not evaluated - #327
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Documents the existing capture-substitution behavior for typed values (interpolation of ${captured.*} with surrounding literal text, without evaluation), and adds regression coverage to keep the documentation and behavior pinned.
Changes:
- Expanded
docs/authoring.mdto explicitly state typed-capture interpolation semantics and the non-evaluation (“12 + 30”, not “42”) behavior. - Added a focused unit test in
flowproof-tracepinning multi-reference + literal-surround interpolation and non-evaluation. - Wired the new documented examples into the grammar “documented examples parse” test, and recorded the doc fix in the changelog.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/authoring.md | Adds a dedicated section describing typed capture interpolation vs. evaluation semantics. |
| crates/flowproof-trace/src/captures.rs | Adds a regression test asserting interpolation behavior and guarding against accidental evaluation. |
| crates/flowproof-agent/src/rules.rs | Adds the new doc examples to the “documented grammar examples parse” coverage. |
| CHANGELOG.md | Notes the doc clarification and the pinning regression test in Unreleased/Fixed. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| enough to an answer that a flow could go green on it while asserting | ||
| nothing anybody meant. | ||
|
|
||
| Arithmetic is refused deliberately, not merely absent. A capture is *text |
authoring.md showed one form — `Type ${captured.oid} into the …` — and said
the value is read fresh on every replay. It did not say that several
references resolve in one step, that literal text between them is typed as
written, or that none of it is evaluated.
So `Type ${captured.a} + ${captured.b} into the "Sum" field` types
`12 + 30`. That is interpolation working as designed, and it is also close
enough to an answer that a flow can go green on it while asserting nothing
anybody meant — on the page that reads like the complete account of captures.
No behaviour change. The non-arithmetic is now stated outright, with the
reason: a capture is text the app displayed and handing it back is data
entry, while deriving a value from two of them is a computation, and a trace
carrying a computation has stopped being a recording. Pinned by a test that
asserts `12 + 30`, so arithmetic can only ever arrive as a spelling that
cannot be mistaken for this one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
AminChirazi
force-pushed
the
relanded/1-capture-interpolation
branch
from
August 1, 2026 09:59
c30a790 to
3985e33
Compare
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
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.
So
Type ${captured.a} + ${captured.b} into the "Sum" fieldtypes12 + 30— interpolation working as designed, and close enough to an answer that a flow can go green while asserting nothing anybody meant.No behaviour change. Pinned by
a_typed_capture_is_interpolated_and_never_evaluated, so arithmetic can only ever arrive as a spelling that cannot be mistaken for this one.The one question: still a recording — this changes no behaviour at all.
🤖 Generated with Claude Code