From cca57170c131540444a7cf20bdf1768d13e09ebe Mon Sep 17 00:00:00 2001
From: Tim <code@tim.life>
Date: Tue, 1 Sep 2026 22:51:37 -0700
Subject: [PATCH 1/3] fix: two rules that ignored they were writing expression
 source (#340, #341)

`inside_dollar_string` says the text being produced is part of an
expression rather than a value for the caller. `StringRule` checks it
and keeps its quotes, because `upper("x")` becoming `upper(x)` asks for
a variable nobody declared. Two rules did not.

A heredoc argument was spliced in bare: `upper(<<E\nx\nE\n)` came back
as `${upper(x)}`, and a multi-line body put raw newlines into source
that no longer parsed. Both heredoc rules check the flag now, in the
flattened and the trimmed paths.

With `preserve_heredocs` on, the heredoc is left as itself rather than
wrapped in quotes. That was quoting raw newlines, which OpenTofu rejects
with "Invalid multi-line string"; as a heredoc it is a legal argument
and `trimspace(<<EOF\n  hi  \nEOF\n)` evaluates to "hi". One existing
test pinned the quoted form and now states this.

`TemplateStringRule` dropped its delimiters in the value form, turning
`%{ if x == "y" }` into `%{ if x == y }` -- a comparison against a
variable rather than a string. It only ever appears inside a directive,
which is always expression source.
---
 CHANGELOG.md                              |  5 +-
 hcl2/rules/strings.py                     | 28 ++++++-
 test/unit/rules/test_expression_source.py | 92 +++++++++++++++++++++++
 test/unit/test_api.py                     |  6 +-
 4 files changed, 126 insertions(+), 5 deletions(-)
 create mode 100644 test/unit/rules/test_expression_source.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61dc143a..1fe62afc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## \[Unreleased\]
 
-- Nothing yet.
+### Fixed
+
+- A heredoc inside an expression is written as a string rather than spliced in bare. `SerializationContext.inside_dollar_string` says the text being produced is expression source, and `StringRule` checks it for exactly this reason; the heredoc rules did not, so `upper(<<E\nx\nE\n)` came back as `${upper(x)}` -- a reference to a variable nobody declared -- and a multi-line body put raw newlines into source that then did not parse. With `preserve_heredocs` on, the heredoc is now left as itself rather than wrapped in quotes: it is a legal argument that way, and OpenTofu rejects the quoted form with "Invalid multi-line string". ([#340](https://github.com/amplify-education/python-hcl2/issues/340))
+- A string literal inside a template directive keeps its delimiters in the value form. `TemplateStringRule` only ever appears inside `%{ ... }`, where the text is expression source and the quotes belong to a literal written in it, so dropping them turned `%{ if x == "y" }` into `%{ if x == y }`: a comparison against a variable rather than against a string. ([#341](https://github.com/amplify-education/python-hcl2/issues/341))
 
 ## \[8.1.3\] - 2026-08-26
 
diff --git a/hcl2/rules/strings.py b/hcl2/rules/strings.py
index 76ce0660..becbbc09 100644
--- a/hcl2/rules/strings.py
+++ b/hcl2/rules/strings.py
@@ -170,15 +170,28 @@ def serialize(self, options=SerializationOptions(), context=SerializationContext
             if not match:
                 raise RuntimeError(f"Invalid Heredoc token: {heredoc}")
             heredoc = _strip_closing_marker_line(match.group(2))
-            if options.strip_string_quotes:
+            if options.strip_string_quotes and not context.inside_dollar_string:
                 # The caller asked for the value, so hand back the body as-is:
                 # real newlines, no escaping. The escaping below exists only to
                 # build the quoted-string *source* form returned otherwise.
+                #
+                # Not inside an expression, though. There the heredoc is an
+                # argument, and its text is part of that expression's source:
+                # `upper(<<E\nx\nE\n)` has to come back as `upper("x")` and not
+                # as `upper(x)`, which asks for a variable nobody declared. A
+                # multi-line body made it worse, splicing raw newlines into
+                # source that then did not parse. `StringRule` checks the same
+                # flag one class away, for the same reason.
                 return heredoc
             heredoc = heredoc.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
             return f'"{heredoc}"'
 
         result = heredoc.rstrip(self._trim_chars)
+        if context.inside_dollar_string:
+            # A heredoc is a legal argument, and it is already source: quoting
+            # it here would put its raw newlines inside a quoted string, which
+            # is not valid HCL.
+            return result
         if options.strip_string_quotes:
             return result
         return f'"{result}"'
@@ -232,9 +245,12 @@ def serialize(self, options=SerializationOptions(), context=SerializationContext
         if not options.preserve_heredocs:
             lines = [line.replace("\\", "\\\\").replace('"', '\\"') for line in lines]
 
-        if options.strip_string_quotes:
+        if options.strip_string_quotes and not context.inside_dollar_string:
             # Value, not source: join with real newlines regardless of
             # preserve_heredocs, and skip the escaping done for the quoted form.
+            # Inside an expression the text is that expression's source, so the
+            # quoted form below is what belongs there -- see the note in
+            # `HeredocTemplateRule.serialize`.
             return "\n".join(lines)
 
         sep = "\\n" if not options.preserve_heredocs else "\n"
@@ -272,8 +288,14 @@ def serialize(self, options=SerializationOptions(), context=SerializationContext
         Inside template directive expressions, strings are delimited by \\"
         rather than plain ". We preserve these as \\" in serialized form so
         the deserializer can reconstruct them correctly.
+
+        `strip_string_quotes` asks for a value, and this rule only ever appears
+        inside a directive -- where the text is expression source and the
+        delimiters belong to a string literal written in it. Dropping them
+        there turned `%{ if x == "y" }` into `%{ if x == y }`: a comparison
+        against a variable rather than against a string.
         """
         raw = self.raw_value
-        if options.strip_string_quotes:
+        if options.strip_string_quotes and not context.inside_dollar_string:
             return self.inner_value
         return raw
diff --git a/test/unit/rules/test_expression_source.py b/test/unit/rules/test_expression_source.py
new file mode 100644
index 00000000..f1a56588
--- /dev/null
+++ b/test/unit/rules/test_expression_source.py
@@ -0,0 +1,92 @@
+# pylint: disable=C0103,C0114,C0115,C0116
+r"""Rules that are serialized into expression source (GH #340, #341).
+
+`SerializationContext.inside_dollar_string` tells a rule it is being written
+into an expression rather than handed to a caller as a value. `StringRule`
+checks it and keeps its quotes, because `upper("x")` becoming `upper(x)` asks
+for a variable nobody declared. Two rules did not check it.
+
+Checked against OpenTofu v1.12.5: `upper(<<EOT\nx\nEOT\n)` evaluates to
+`"X\n"`, so the argument is a string; and a string literal inside a directive
+is written with plain quotes, `"%{ if local.x == "y" }t%{ endif }"`, which
+evaluates to `"t"`.
+"""
+
+from unittest import TestCase
+
+from hcl2.api import loads
+from hcl2.utils import SerializationOptions
+
+VALUE = SerializationOptions(preserve_heredocs=False, strip_string_quotes=True)
+QUOTED = SerializationOptions(strip_string_quotes=True)
+SOURCE = SerializationOptions(preserve_heredocs=False)
+
+
+class TestAHeredocInsideAnExpression(TestCase):
+    """#340: the body was spliced in bare, so it read as a reference."""
+
+    def test_it_stays_a_string(self):
+        self.assertEqual(loads("a = upper(<<E\nx\nE\n)\n", serialization_options=VALUE)["a"], '${upper("x")}')
+
+    def test_it_matches_the_quoted_equivalent(self):
+        self.assertEqual(
+            loads("a = upper(<<E\nx\nE\n)\n", serialization_options=VALUE)["a"],
+            loads('a = upper("x")\n', serialization_options=VALUE)["a"],
+        )
+
+    def test_a_multi_line_body_does_not_splice_raw_newlines(self):
+        result = loads("a = upper(<<E\nx\ny\nE\n)\n", serialization_options=VALUE)["a"]
+        self.assertEqual(result, '${upper("x\\ny")}')
+        self.assertNotIn("\n", result)
+
+    def test_the_trim_form_too(self):
+        self.assertEqual(
+            loads("a = upper(<<-E\n  x\n  E\n)\n", serialization_options=VALUE)["a"], '${upper("x")}'
+        )
+
+    def test_a_heredoc_that_is_not_in_an_expression_is_unaffected(self):
+        self.assertEqual(loads("a = <<E\nx\nE\n", serialization_options=VALUE)["a"], "x")
+
+
+class TestAStringLiteralInsideADirective(TestCase):
+    """#341: the delimiters were dropped, turning a literal into a reference."""
+
+    ESCAPED = 'a = "%{ if x == \\"y\\" }t%{ endif }"\n'
+    PLAIN = 'a = "%{ if x == "y" }t%{ endif }"\n'
+
+    def test_the_escaped_delimiters_survive_the_value_form(self):
+        self.assertEqual(
+            loads(self.ESCAPED, serialization_options=QUOTED)["a"], '%{ if x == \\"y\\" }t%{ endif }'
+        )
+
+    def test_the_plain_delimiters_survive_too(self):
+        # The spelling Terraform accepts; unchanged by this fix, asserted so it
+        # stays that way.
+        self.assertEqual(loads(self.PLAIN, serialization_options=QUOTED)["a"], '%{ if x == "y" }t%{ endif }')
+
+    def test_the_source_form_is_unchanged(self):
+        self.assertEqual(loads(self.ESCAPED)["a"], '"%{ if x == \\"y\\" }t%{ endif }"')
+
+    def test_a_directive_without_a_literal_is_unaffected(self):
+        self.assertEqual(
+            loads('a = "%{ if x }t%{ endif }"\n', serialization_options=QUOTED)["a"],
+            "%{ if x }t%{ endif }",
+        )
+
+
+class TestTheSourceFormIsUntouched(TestCase):
+    """Neither fix changes what the non-value modes emit."""
+
+    def test_a_heredoc_argument_keeps_its_quoted_source(self):
+        self.assertEqual(
+            loads("a = upper(<<E\nx\nE\n)\n", serialization_options=SOURCE)["a"], '${upper("x")}'
+        )
+
+    def test_default_options_keep_the_heredoc_unquoted(self):
+        """A heredoc is a legal argument; quoting it is not.
+
+        The quoted form put raw newlines inside a quoted string, which OpenTofu
+        rejects with "Invalid multi-line string". As a heredoc it evaluates:
+        `trimspace(<<EOF\n  hi  \nEOF\n)` gives "hi".
+        """
+        self.assertEqual(loads("a = upper(<<E\nx\nE\n)\n")["a"], "${upper(<<E\nx\nE)}")
diff --git a/test/unit/test_api.py b/test/unit/test_api.py
index d6599fec..99cbb3d2 100644
--- a/test/unit/test_api.py
+++ b/test/unit/test_api.py
@@ -358,7 +358,11 @@ def test_empty_heredoc_as_an_object_value(self):
         self.assertEqual(loads("a = {\n  k = <<EOF\nEOF\n}\n"), {"a": {"k": '"<<EOF\nEOF"'}})
 
     def test_empty_heredoc_as_a_function_argument(self):
-        self.assertEqual(loads("a = trimspace(<<EOF\nEOF\n)\n"), {"a": '${trimspace("<<EOF\nEOF")}'})
+        # The heredoc stays a heredoc rather than being quoted. Quoting it put
+        # raw newlines inside a quoted string, which OpenTofu rejects with
+        # "Invalid multi-line string"; as a heredoc it is a legal argument, and
+        # `trimspace(<<EOF\n  hi  \nEOF\n)` evaluates to "hi".
+        self.assertEqual(loads("a = trimspace(<<EOF\nEOF\n)\n"), {"a": "${trimspace(<<EOF\nEOF)}"})
 
 
 class TestNegativeIntegerLiterals(TestCase):

From 486ea95f0356fbbc3074c9e41fc8c06302e90475 Mon Sep 17 00:00:00 2001
From: Kamil Kozik <kkozik@amplify.com>
Date: Mon, 7 Sep 2026 14:31:55 +0200
Subject: [PATCH 2/3] fix: keep the value-form fixes, drop the default-path
 change (#340, #341)

The branch also stopped quoting a heredoc that sits inside an expression on
the default path, which neither #340 nor #341 asks for -- both are scoped to
`strip_string_quotes`. It regressed the round trip: `dumps(loads(...))` of a
heredoc argument raised `UnexpectedToken`, because the emitted
`trimspace(<<EOF\nhi\nEOF)` puts the closing marker on the same line as the
`)`, which this grammar does not accept. On main that round trip works.

The change is right in the end -- Terraform v1.11.4 rejects the quoted form
with "Invalid multi-line string" and evaluates the heredoc argument to "hi" --
but it needs the writer to give a heredoc its own line first, which is #338.
Landing it here breaks `dumps` for anyone whose document has a heredoc in a
call. Reverted, with `test_api.py` back to the expectation it had and a note
saying which fix supersedes it, so #338 makes the change deliberately.

The two fixes the issues do ask for are untouched, and are now covered per
rule: reverting `HeredocTemplateRule`'s check fails twelve assertions,
`HeredocTrimTemplateRule`'s one, `TemplateStringRule`'s two.

Also widens #340's coverage past the reported function argument to every rule
that marks its children as expression source -- nested call, later argument,
binary operand, conditional branch, indexed tuple, interpolation -- and adds
round-trip assertions for both the default and value dicts, which is the half
that a change here can break without any of the value assertions noticing.

Verified against Terraform v1.11.4: `upper(<<EOT\nx\nEOT\n)` is "X\n", and
`"%{ if local.x == "y" }t%{ endif }"` is "t".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                              |   4 +-
 hcl2/rules/strings.py                     |   5 -
 test/unit/rules/test_expression_source.py | 132 ++++++++++++++++++----
 test/unit/test_api.py                     |  10 +-
 4 files changed, 118 insertions(+), 33 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fe62afc..4eae4695 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,8 +9,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Fixed
 
-- A heredoc inside an expression is written as a string rather than spliced in bare. `SerializationContext.inside_dollar_string` says the text being produced is expression source, and `StringRule` checks it for exactly this reason; the heredoc rules did not, so `upper(<<E\nx\nE\n)` came back as `${upper(x)}` -- a reference to a variable nobody declared -- and a multi-line body put raw newlines into source that then did not parse. With `preserve_heredocs` on, the heredoc is now left as itself rather than wrapped in quotes: it is a legal argument that way, and OpenTofu rejects the quoted form with "Invalid multi-line string". ([#340](https://github.com/amplify-education/python-hcl2/issues/340))
-- A string literal inside a template directive keeps its delimiters in the value form. `TemplateStringRule` only ever appears inside `%{ ... }`, where the text is expression source and the quotes belong to a literal written in it, so dropping them turned `%{ if x == "y" }` into `%{ if x == y }`: a comparison against a variable rather than against a string. ([#341](https://github.com/amplify-education/python-hcl2/issues/341))
+- `strip_string_quotes` now writes a heredoc inside an expression as a string instead of splicing its body in bare. `StringRule` checks `inside_dollar_string` to keep its quotes for exactly this reason; the heredoc rules did not, so `upper(<<E\nx\nE\n)` came back as `${upper(x)}` — a reference to a variable nobody declared — and a multi-line body put raw newlines into source that would not parse. Both `<<` and `<<-` are fixed, in every expression context. Thanks, @livingstaccato ([#350](https://github.com/amplify-education/python-hcl2/pull/350))
+- `strip_string_quotes` now keeps the delimiters of a string literal inside a template directive. `TemplateStringRule` only ever appears inside `%{ ... }`, where the text is expression source and the quotes belong to a literal written in it, so dropping them turned `%{ if x == "y" }` into `%{ if x == y }`: a comparison against a variable rather than against a string. Thanks, @livingstaccato ([#350](https://github.com/amplify-education/python-hcl2/pull/350))
 
 ## \[8.1.3\] - 2026-08-26
 
diff --git a/hcl2/rules/strings.py b/hcl2/rules/strings.py
index becbbc09..482a2fb6 100644
--- a/hcl2/rules/strings.py
+++ b/hcl2/rules/strings.py
@@ -187,11 +187,6 @@ def serialize(self, options=SerializationOptions(), context=SerializationContext
             return f'"{heredoc}"'
 
         result = heredoc.rstrip(self._trim_chars)
-        if context.inside_dollar_string:
-            # A heredoc is a legal argument, and it is already source: quoting
-            # it here would put its raw newlines inside a quoted string, which
-            # is not valid HCL.
-            return result
         if options.strip_string_quotes:
             return result
         return f'"{result}"'
diff --git a/test/unit/rules/test_expression_source.py b/test/unit/rules/test_expression_source.py
index f1a56588..d6a31122 100644
--- a/test/unit/rules/test_expression_source.py
+++ b/test/unit/rules/test_expression_source.py
@@ -6,46 +6,105 @@
 checks it and keeps its quotes, because `upper("x")` becoming `upper(x)` asks
 for a variable nobody declared. Two rules did not check it.
 
-Checked against OpenTofu v1.12.5: `upper(<<EOT\nx\nEOT\n)` evaluates to
-`"X\n"`, so the argument is a string; and a string literal inside a directive
-is written with plain quotes, `"%{ if local.x == "y" }t%{ endif }"`, which
-evaluates to `"t"`.
+Both defects are in the value form only -- `strip_string_quotes=True`. What
+the other modes emit is unchanged; `TestTheOtherModesAreUntouched` states so,
+including the round trip, because that is the half a change here can break
+without any of the assertions above noticing.
+
+Checked against Terraform v1.11.4:
+
+    upper(<<EOT\nx\nEOT\n)              -> "X\n", so the argument is a string
+    "%{ if local.x == "y" }t%{ endif }" -> "t", with plain quotes
+
+The escaped spelling this grammar also accepts, `\"y\"` inside a directive,
+Terraform rejects outright with "Invalid character". That divergence is filed
+as #341's sibling, #353; the tests below only pin that the value form stops
+mangling it into a reference, which is what #341 asks for.
 """
 
 from unittest import TestCase
 
-from hcl2.api import loads
+from hcl2.api import dumps, loads
 from hcl2.utils import SerializationOptions
 
 VALUE = SerializationOptions(preserve_heredocs=False, strip_string_quotes=True)
 QUOTED = SerializationOptions(strip_string_quotes=True)
 SOURCE = SerializationOptions(preserve_heredocs=False)
+DEFAULT = SerializationOptions()
 
 
 class TestAHeredocInsideAnExpression(TestCase):
     """#340: the body was spliced in bare, so it read as a reference."""
 
+    def value(self, source: str) -> str:
+        return loads(source, serialization_options=VALUE)["a"]
+
     def test_it_stays_a_string(self):
-        self.assertEqual(loads("a = upper(<<E\nx\nE\n)\n", serialization_options=VALUE)["a"], '${upper("x")}')
+        self.assertEqual(self.value("a = upper(<<E\nx\nE\n)\n"), '${upper("x")}')
 
     def test_it_matches_the_quoted_equivalent(self):
         self.assertEqual(
-            loads("a = upper(<<E\nx\nE\n)\n", serialization_options=VALUE)["a"],
-            loads('a = upper("x")\n', serialization_options=VALUE)["a"],
+            self.value("a = upper(<<E\nx\nE\n)\n"),
+            self.value('a = upper("x")\n'),
         )
 
     def test_a_multi_line_body_does_not_splice_raw_newlines(self):
-        result = loads("a = upper(<<E\nx\ny\nE\n)\n", serialization_options=VALUE)["a"]
+        result = self.value("a = upper(<<E\nx\ny\nE\n)\n")
         self.assertEqual(result, '${upper("x\\ny")}')
         self.assertNotIn("\n", result)
 
     def test_the_trim_form_too(self):
-        self.assertEqual(
-            loads("a = upper(<<-E\n  x\n  E\n)\n", serialization_options=VALUE)["a"], '${upper("x")}'
-        )
+        self.assertEqual(self.value("a = upper(<<-E\n  x\n  E\n)\n"), '${upper("x")}')
 
     def test_a_heredoc_that_is_not_in_an_expression_is_unaffected(self):
-        self.assertEqual(loads("a = <<E\nx\nE\n", serialization_options=VALUE)["a"], "x")
+        # Nothing wraps this one, so the caller does get the bare body.
+        self.assertEqual(self.value("a = <<E\nx\nE\n"), "x")
+
+    def test_a_heredoc_in_a_container_is_unaffected(self):
+        # A tuple element and an object value are values, not expression
+        # source, so they keep handing back the body.
+        self.assertEqual(self.value("a = [<<E\nx\nE\n]\n"), ["x"])
+        self.assertEqual(self.value("a = {k = <<E\nx\nE\n}\n"), {"k": "x"})
+
+
+class TestEveryExpressionContextQuotesIt(TestCase):
+    """`inside_dollar_string` is set by more rules than the function call.
+
+    #340 was reported against an argument, but every rule that marks its
+    children as expression source had the same hole. One case each, so a rule
+    that stops threading the context is caught here rather than in whichever
+    document happens to use it.
+    """
+
+    def value(self, source: str) -> str:
+        return loads(source, serialization_options=VALUE)["a"]
+
+    def test_a_nested_call(self):
+        self.assertEqual(self.value("a = upper(lower(<<E\nx\nE\n))\n"), '${upper(lower("x"))}')
+
+    def test_a_later_argument(self):
+        self.assertEqual(self.value('a = join(",", <<E\nx\nE\n)\n'), '${join(",", "x")}')
+
+    def test_a_binary_operand(self):
+        self.assertEqual(self.value("a = b + <<E\nx\nE\n"), '${b + "x"}')
+
+    def test_a_conditional_branch(self):
+        self.assertEqual(self.value('a = c ? <<E\nx\nE\n : "z"\n'), '${c ? "x" : "z"}')
+
+    def test_an_indexed_tuple_inside_a_call(self):
+        self.assertEqual(self.value("a = upper([<<E\nx\nE\n][0])\n"), '${upper(["x"][0])}')
+
+    def test_an_interpolation_in_a_quoted_string(self):
+        self.assertEqual(self.value('a = "${upper(<<E\nx\nE\n)}"\n'), '${upper("x")}')
+
+    def test_none_of_them_leak_a_raw_newline(self):
+        for source in (
+            "a = upper(<<E\nx\ny\nE\n)\n",
+            "a = b + <<E\nx\ny\nE\n",
+            'a = c ? <<E\nx\ny\nE\n : "z"\n',
+        ):
+            with self.subTest(source=source):
+                self.assertNotIn("\n", self.value(source))
 
 
 class TestAStringLiteralInsideADirective(TestCase):
@@ -64,6 +123,12 @@ def test_the_plain_delimiters_survive_too(self):
         # stays that way.
         self.assertEqual(loads(self.PLAIN, serialization_options=QUOTED)["a"], '%{ if x == "y" }t%{ endif }')
 
+    def test_the_literal_is_not_reduced_to_a_reference(self):
+        # The point of the fix: `== y` would compare against a variable.
+        for source in (self.ESCAPED, self.PLAIN):
+            with self.subTest(source=source):
+                self.assertNotIn("== y ", loads(source, serialization_options=QUOTED)["a"])
+
     def test_the_source_form_is_unchanged(self):
         self.assertEqual(loads(self.ESCAPED)["a"], '"%{ if x == \\"y\\" }t%{ endif }"')
 
@@ -74,19 +139,44 @@ def test_a_directive_without_a_literal_is_unaffected(self):
         )
 
 
-class TestTheSourceFormIsUntouched(TestCase):
-    """Neither fix changes what the non-value modes emit."""
+class TestTheOtherModesAreUntouched(TestCase):
+    """Neither fix changes what the non-value modes emit, or the round trip."""
+
+    HEREDOC_IN_EXPRESSION = (
+        "a = upper(<<E\nx\nE\n)\n",
+        "a = trimspace(<<EOF\nhi\nEOF\n)\n",
+        "a = trimspace(<<EOF\nEOF\n)\n",
+        "a = b + <<E\nx\nE\n",
+    )
 
     def test_a_heredoc_argument_keeps_its_quoted_source(self):
         self.assertEqual(
             loads("a = upper(<<E\nx\nE\n)\n", serialization_options=SOURCE)["a"], '${upper("x")}'
         )
 
-    def test_default_options_keep_the_heredoc_unquoted(self):
-        """A heredoc is a legal argument; quoting it is not.
+    def test_default_options_keep_the_heredoc_as_quoted_source(self):
+        r"""The default still quotes the heredoc's own text, markers and all.
 
-        The quoted form put raw newlines inside a quoted string, which OpenTofu
-        rejects with "Invalid multi-line string". As a heredoc it evaluates:
-        `trimspace(<<EOF\n  hi  \nEOF\n)` gives "hi".
+        That form is not valid HCL -- Terraform rejects a quoted string split
+        over lines with "Invalid multi-line string", and a heredoc is a legal
+        argument as itself. Changing it needs the emitting side to give a
+        heredoc its own line first, which is #338; until then this asserts what
+        the default does rather than what it should, so the two fixes here stay
+        confined to the value form.
         """
-        self.assertEqual(loads("a = upper(<<E\nx\nE\n)\n")["a"], "${upper(<<E\nx\nE)}")
+        self.assertEqual(loads("a = upper(<<E\nx\nE\n)\n")["a"], '${upper("<<E\nx\nE")}')
+
+    def test_the_default_dict_still_round_trips(self):
+        # `dumps` has to read back whatever `loads` produced. Emitting the
+        # heredoc unquoted here breaks this, which is why that belongs with
+        # #338 rather than in this change.
+        for source in self.HEREDOC_IN_EXPRESSION:
+            with self.subTest(source=source):
+                written = dumps(loads(source, serialization_options=DEFAULT))
+                self.assertEqual(dumps(loads(written)), written)
+
+    def test_the_value_dict_still_round_trips(self):
+        for source in self.HEREDOC_IN_EXPRESSION:
+            with self.subTest(source=source):
+                written = dumps(loads(source, serialization_options=VALUE))
+                self.assertEqual(dumps(loads(written)), written)
diff --git a/test/unit/test_api.py b/test/unit/test_api.py
index 99cbb3d2..9885402e 100644
--- a/test/unit/test_api.py
+++ b/test/unit/test_api.py
@@ -358,11 +358,11 @@ def test_empty_heredoc_as_an_object_value(self):
         self.assertEqual(loads("a = {\n  k = <<EOF\nEOF\n}\n"), {"a": {"k": '"<<EOF\nEOF"'}})
 
     def test_empty_heredoc_as_a_function_argument(self):
-        # The heredoc stays a heredoc rather than being quoted. Quoting it put
-        # raw newlines inside a quoted string, which OpenTofu rejects with
-        # "Invalid multi-line string"; as a heredoc it is a legal argument, and
-        # `trimspace(<<EOF\n  hi  \nEOF\n)` evaluates to "hi".
-        self.assertEqual(loads("a = trimspace(<<EOF\nEOF\n)\n"), {"a": "${trimspace(<<EOF\nEOF)}"})
+        # Quoting the heredoc's own text is not valid HCL -- Terraform rejects
+        # a quoted string split over lines -- but emitting it as a heredoc
+        # needs the writer to give it its own line first, which is #338. This
+        # pins what the default does today so that fix is a deliberate step.
+        self.assertEqual(loads("a = trimspace(<<EOF\nEOF\n)\n"), {"a": '${trimspace("<<EOF\nEOF")}'})
 
 
 class TestNegativeIntegerLiterals(TestCase):

From b65e913633f2ff9a34a9c584d53a3ac9ef66ee51 Mon Sep 17 00:00:00 2001
From: Tim <code@tim.life>
Date: Wed, 23 Sep 2026 11:43:09 -0700
Subject: [PATCH 3/3] fix: a parenthesised term writes what it wraps as
 expression source

`(...)` is written as `${(...)}`, but the term serialized its inside as a
value, so literals came back in Python's spelling: `(true)` as `${(True)}`
and `(null)` as `${(None)}` on the default options, which dumps wrote back
as references OpenTofu rejects, and a tuple or object inside as a repr that
did not parse. With strip_string_quotes, `("s")` lost its quotes. Every
changed output was one no reader could evaluate; each round trip now
evaluates, in OpenTofu v1.12.6, to the value the source does.
---
 CHANGELOG.md                              |  1 +
 hcl2/rules/expressions.py                 | 11 ++++-
 test/unit/rules/test_expression_source.py | 60 ++++++++++++++++++++++-
 3 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e93bf13b..ec5be326 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - `strip_string_quotes` now writes a heredoc inside an expression as a string instead of splicing its body in bare. `StringRule` checks `inside_dollar_string` to keep its quotes for exactly this reason; the heredoc rules did not, so `upper(<<E\nx\nE\n)` came back as `${upper(x)}` — a reference to a variable nobody declared — and a multi-line body put raw newlines into source that would not parse. Both `<<` and `<<-` are fixed, in every expression context. Thanks, @livingstaccato ([#350](https://github.com/amplify-education/python-hcl2/pull/350))
 - `strip_string_quotes` now keeps the delimiters of a string literal inside a template directive. `TemplateStringRule` only ever appears inside `%{ ... }`, where the text is expression source and the quotes belong to a literal written in it, so dropping them turned `%{ if x == "y" }` into `%{ if x == y }`: a comparison against a variable rather than against a string. Thanks, @livingstaccato ([#350](https://github.com/amplify-education/python-hcl2/pull/350))
+- A parenthesised expression writes what it wraps as HCL rather than as a Python value, on the default options as well: `(true)` used to come back as `${(True)}` and `(null)` as `${(None)}`, which `dumps` wrote back as references to variables nobody declared (OpenTofu rejects both with "Invalid reference"); a tuple or object inside the parentheses came back as a Python repr that `dumps` could not parse; and with `strip_string_quotes`, `("s")` lost its quotes and became `${(s)}`. They now come back as `${(true)}`, `${(null)}`, `${([1, "a"])}` and `${("s")}`, and each round trip evaluates to the value the source does. Thanks, @livingstaccato ([#350](https://github.com/amplify-education/python-hcl2/pull/350))
 
 ## \[8.1.4\] - 2026-09-08
 
diff --git a/hcl2/rules/expressions.py b/hcl2/rules/expressions.py
index 15caa1c3..3c4d09fe 100644
--- a/hcl2/rules/expressions.py
+++ b/hcl2/rules/expressions.py
@@ -100,7 +100,16 @@ def expression(self) -> ExpressionRule:
 
     def serialize(self, options=SerializationOptions(), context=SerializationContext()) -> Any:
         """Serialize, handling parenthesized expression wrapping."""
-        with context.modify(inside_parentheses=self.parentheses or context.inside_parentheses):
+        # A parenthesised term is written as `${(...)}`, so what it wraps is
+        # expression source, exactly as a function's arguments are. Serialized
+        # as a value, `(true)` came back as `${(True)}` and `(null)` as
+        # `${(None)}` -- Python's spelling, which OpenTofu reads as references
+        # to undeclared variables -- and a tuple or object inside came back as
+        # a Python repr that did not parse.
+        with context.modify(
+            inside_parentheses=self.parentheses or context.inside_parentheses,
+            inside_dollar_string=self.parentheses or context.inside_dollar_string,
+        ):
             result = self.expression.serialize(options, context)
 
         if self.parentheses:
diff --git a/test/unit/rules/test_expression_source.py b/test/unit/rules/test_expression_source.py
index d6a31122..d40ef27e 100644
--- a/test/unit/rules/test_expression_source.py
+++ b/test/unit/rules/test_expression_source.py
@@ -9,7 +9,10 @@
 Both defects are in the value form only -- `strip_string_quotes=True`. What
 the other modes emit is unchanged; `TestTheOtherModesAreUntouched` states so,
 including the round trip, because that is the half a change here can break
-without any of the assertions above noticing.
+without any of the assertions above noticing. The one exception is a
+parenthesised term, `TestAParenthesisedTermIsExpressionSource`, whose default
+output was itself not HCL -- `(true)` came back as `${(True)}` -- so fixing it
+changes only output that no reader could evaluate.
 
 Checked against Terraform v1.11.4:
 
@@ -180,3 +183,58 @@ def test_the_value_dict_still_round_trips(self):
             with self.subTest(source=source):
                 written = dumps(loads(source, serialization_options=VALUE))
                 self.assertEqual(dumps(loads(written)), written)
+
+
+class TestAParenthesisedTermIsExpressionSource(TestCase):
+    r"""`(...)` is written as `${(...)}`, so what it wraps is expression source.
+
+    The term wrapped its result in `${(` and `)}` but serialized the inside as
+    a value, so every literal in it came back in Python's spelling rather than
+    HCL's. This was not confined to the value form: on the default options
+    `(true)` came back as `${(True)}` and `(null)` as `${(None)}`, and `dumps`
+    wrote those back as `(True)` and `(None)` -- references to variables
+    nobody declared, which OpenTofu v1.12.6 rejects with "Invalid reference"
+    where the source evaluates to `true` and `null`. A tuple or an object
+    inside the parentheses came back as a Python repr, which `dumps` could not
+    parse at all. With `strip_string_quotes`, `("s")` lost its quotes and became
+    `${(s)}`, another reference.
+
+    Checked against OpenTofu v1.12.6 (`jsonencode` of each local):
+
+        (true) -> "true"    (null) -> "null"    ("s") -> "\"s\""
+        ([1, "a"]) -> "[1,\"a\"]"               ({a = 1}) -> "{\"a\":1}"
+    """
+
+    CASES = {
+        "(true)": "${(true)}",
+        "(null)": "${(null)}",
+        '("s")': '${("s")}',
+        "(1)": "${(1)}",
+        '([1, "a"])': '${([1, "a"])}',
+        "(1 + 2)": "${(1 + 2)}",
+        "((true))": "${((true))}",
+    }
+
+    def test_default_options(self):
+        for source, expected in self.CASES.items():
+            with self.subTest(source=source):
+                self.assertEqual(loads(f"x = {source}\n")["x"], expected)
+
+    def test_the_value_form(self):
+        for source, expected in self.CASES.items():
+            with self.subTest(source=source):
+                self.assertEqual(loads(f"x = {source}\n", serialization_options=QUOTED)["x"], expected)
+
+    def test_an_object_inside_parentheses(self):
+        self.assertEqual(loads("x = ({a = 1})\n")["x"], "${({a = 1})}")
+
+    def test_inside_a_tuple(self):
+        self.assertEqual(loads("x = [(true)]\n")["x"], ["${(true)}"])
+
+    def test_the_round_trip_reads_back_the_same_value(self):
+        for source in (*self.CASES, "({a = 1})", "[(true)]"):
+            for options in (DEFAULT, QUOTED, VALUE):
+                with self.subTest(source=source, options=options):
+                    original = loads(f"x = {source}\n", serialization_options=options)
+                    written = dumps(original)
+                    self.assertEqual(loads(written, serialization_options=options), original)