Move the runtime include root from smithy/ to opal/ (#201, ADR-0024)

[aaylward]

Part of #201, surface 2 of 3 per ADR-0024 (#207 was the namespace; the Bazel module follows). The issue closes with the third.

What

The runtime's public headers move from runtime/include/smithy/ to runtime/include/opal/, and the test helpers from runtime/testing/include/smithy/testing/ to opal/testing/:

#include "opal/http/transport.h"
#include "opal/server/middleware.h"

Everything that derives from the include root follows it:

• Include guards: SMITHY_HTTP_TRANSPORT_H_ → OPAL_HTTP_TRANSPORT_H_, across the runtime and the hand-written examples.
• The SMITHY_* macro prefix: the one non-guard macro, SMITHY_E2E_HAVE_BEAST, is now OPAL_E2E_HAVE_BEAST.
• The runtime's own log-line prefix: smithy: → opal: on the stderr/clog lines the runtime writes for itself (Fatal, callbacks that threw, the Beast io-thread catch). It names the library that wrote the line, so it moves with the library.
• Codegen: the emitters print "opal/..." includes and the goldens are regenerated from them, not edited — a second gradle generateFixtures generateProtocolTests on this head is byte-identical.
• Docs: every header path in the guides and ADRs, docs/versioning.md's compatibility surface Phase 0: project foundations #3 (runtime/include/opal/**), and comments that cite a header by path.

Unchanged, by design: the Bazel module @smithy_cpp and SMITHY_COPTS (surface 3), and the rules-test fixture's smithy/cpp/ruletest/ headers. Those derive from the fixture's model namespace (smithy.cpp.ruletest), not from the runtime, so the sweep was constrained to the runtime's directories there. Same rule as #207's smithy::cpp::ruletest, and the CHANGELOG entry spells out that constraint for a consumer in the same position.

Churn to expect

"opal/…" sorts differently from "smithy/…" under Google-style include regrouping, so clang-format reordered include blocks in many files. Generated code sorts its own includes, so the golden diff is a pure path substitution.

Testing

• bazel test //... --config=werror: 129 tests pass.
• examples/bazel-consumer (the out-of-tree module): 15 tests pass, with only the #include substitution applied to its sources — which is the migration the CHANGELOG claims.
• --config=noexcept build of every runtime library passes.
• cd codegen && gradle build spotlessCheck passes; the Java tests that assert on emitted includes were updated to the new paths.
• Goldens regenerate byte-identically (git diff --exit-code -- '*/generated/*' after a second run is empty).
• clang-format dry-run, buildifier, and clang-tidy (as CI runs it; the Beast transport findings without a system Boost are identical on main) are clean.

No new tests: the change has no new behavior. Every existing suite compiles against the new root, and the consumer module is the acceptance test for the migration recipe.

Checklist

• Tests added/updated for the change (no new behavior; the consumer module and all suites exercise the new include root)
• bazel test //... and (cd codegen && gradle build spotlessCheck) pass locally
• Formatting clean (clang-format, buildifier, spotless)
• Architectural decisions recorded as an ADR (ADR-0024, landed with Rename the runtime namespace from smithy to opal (#201, surface 1 of 3) #207; one consequence bullet updated to past tense)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jj5X2fKdgrYurHmbwLzUiQ

---

Generated by Claude Code

[cursor]

Review

LGTM — surface 2 of #201 is scoped correctly and complete on 8d614cf. The include-root move matches ADR-0024, intentional stays are intact, and CI is green aside from one still-running sanitizer job (no failures so far).

What looks right

• Layout: runtime/include/smithy/ and runtime/testing/include/smithy/ are gone; opal/ (and opal/testing/) have the same relative tree. Guards are OPAL_*.
• Leftover #include "smithy/: only the model-derived rules-test fixture (smithy/cpp/ruletest/…) — same rule as Rename the runtime namespace from smithy to opal (#201, surface 1 of 3) #207’s smithy::cpp::ruletest. Consumer module is the claimed one-substitution migration ("smithy/ → "opal/).
• Macros / logs: OPAL_E2E_HAVE_BEAST only; runtime clog/fprintf use opal: (52 sites). No leftover "smithy: in runtime.
• Codegen → goldens: emitters print "opal/…"; zero #include "smithy/ under **/generated/**.
• Surface 3 frozen: @smithy_cpp, SMITHY_COPTS, module name untouched.
• CHANGELOG migration recipe correctly constrains dirs (smithy/{core,http,…}/) so a smithy/cpp/ruletest/… consumer isn’t swept. docs/versioning.md surface Phase 0: project foundations #3 is runtime/include/opal/**.

Should-fix (docs)

1. Crash-line examples still say smithy: after Fatal moved to opal::

   • docs/generated-types.md (~L130): `smithy: MilkOption::as_dairy(): …`
   • docs/adr/0009-fail-fast-contract-violations.md (~L39): `smithy: OrderStatus::as_ready(): …`
     Both already cite opal::internal::Fatal / opal/core/fatal.h. The CHANGELOG tells greppers to switch to opal: ; these examples should match.

2. CHANGELOG wording on the macro prefix — “the SMITHY_* macro prefix (OPAL_E2E_HAVE_BEAST)” reads as if the prefix is still SMITHY_*. Parallel with the guard example (OPAL_HTTP_TRANSPORT_H_), say the OPAL_* macro prefix (formerly SMITHY_*), e.g. OPAL_E2E_HAVE_BEAST.

Nit (non-blocking)

• Surface-1 Unreleased bullet (~L46–47) still says the include root “move[s] in the two PRs that follow.” Surface 2 is already the bullet above; only Bazel remains. Easy to confuse readers of [Unreleased].

No correctness issues found; happy to see this land.

[cursor]

Follow-up 2907f49 looks good — crash-line examples now say opal:, CHANGELOG macro wording is OPAL_* (formerly SMITHY_*), and the surface-1 Unreleased bullet no longer claims the include root still has two PRs ahead. CI green on the new head. Nothing further from me.