Summary

• Retain references to @string definitions in the default parse stack.
• Keep ResolveStringReferencesMiddleware available as an explicit dereferencing choice.
• Document and test the required middleware order before enclosure removal.
• Protect macro linkage through the public parse/write entry points.

Closes #590.

Validation

• pytest -p no:cacheprovider -W error tests/middleware_tests/test_interpolate.py: 5 passed.
• Complete upstream suite: 2,578 passed, 12 skipped, with the four existing deprecation warnings in tests/test_entrypoint.py.
• Complete pre-commit hook suite: passed.

Review note

This is a user-visible default change: callers who rely on immediate literal values must add ResolveStringReferencesMiddleware explicitly. The reason for proposing it is that default expansion is irreversible during a write—macro linkage is semantic information, and the original reference cannot be reconstructed reliably from its expanded text.

The PR deliberately uses basic references and does not depend on the broader concatenation work discussed in #396.

AI assistance

This pull request was prepared with ChatGPT Codex using GPT-5.6 Sol with high reasoning effort. Codex assisted with default-policy analysis, standalone test design, documentation, and validation. Automated validation is not a substitute for maintainer review.