Rename the runtime namespace from smithy to opal (#201, surface 1 of 3)

[aaylward]

Part of #201. Records the decision as ADR-0024; the issue closes with the third surface.

Targets main directly now that #199 and #206 have merged; the diff is the rename alone. (Earlier revisions of this PR used sable; the name is now opal, chosen after checking it is free on the Bazel Central Registry, vcpkg and Conan Center, and that the only C++ neighbor is the dormant OPAL VoIP library.)

What

Option 3 from #201: rename outright, no alias, one PR per surface. This is the first surface, the C++ namespace. The runtime is opal:

opal::Outcome<Foo> out = client.Foo(input);
opal::http::BeastServerTransport transport(options);
opal::server::Chain({opal::server::Observe(sink)}, server.Handler());

Every smithy:: scope and namespace smithy becomes opal: the hand-written runtime, tests, examples, fuzz targets and docs; the 26 codegen emitters that print the namespace into generated code; and the goldens, regenerated from those emitters rather than edited — a fresh gradle generateFixtures generateProtocolTests on this head is byte-identical to what is checked in. The generated protocol-conformance suites move with it to opal::protocoltests::…, so their headers move to include/opal/protocoltests/ and their guards to OPAL_PROTOCOLTESTS_* (both derive from the configured C++ namespace, not from the runtime's include root; they were always generated code that refers to the runtime, not a model).

Unchanged in this PR, by design: the runtime's include root (smithy/http/transport.h), its include guards and SMITHY_* macros, the smithy: prefix on the runtime's own log lines, and the Bazel module @smithy_cpp. Those are surfaces 2 and 3, each its own PR, per the issue's "a mixed one is unreviewable".

What keeps smithy, and why

The rule the audit applies: a name that refers to the model keeps it; a name that refers to a runtime thing that would exist identically had the service been hand-written does not.

• Smithy namespaces in .smithy files (smithy.cpp.protocols#jsonRpc2), the smithy_cpp_*_library rules, the codegen plugin, prose about "the Smithy operation".
• The rules-test fixture's smithy::cpp::ruletest: it mirrors its own model's smithy.cpp.ruletest namespace, so it is the consumer's C++ namespace and the rule's derivation test depends on that spelling. The first pass caught it and the .smithy files' namespace smithy.cpp.… lines; both reverted, and the ADR names them so the next two surfaces don't repeat it.

Breaking

Pre-1.0 minor, per docs/versioning.md; the CHANGELOG carries the Breaking entry with the migration: smithy:: → opal::, namespace smithy → namespace opal, constrained to the runtime's scopes for a consumer whose own model namespace starts with smithy. (the fixture case above). The out-of-tree consumer module in examples/bazel-consumer needed exactly the unconstrained substitution and nothing else.

Churn to expect in the diff

The shorter name let clang-format re-wrap many lines and spotless re-wrap five Java files, so the hand-written diff is larger than the rename alone. The generated diff is a pure token substitution plus the protocol-test header moves. CHANGELOG.md's released sections keep their historical names; only [Unreleased] was renamed.

Testing

• bazel test //... --config=werror: 129 tests pass.
• examples/bazel-consumer: 15 tests pass against the renamed runtime, with only the substitution applied to its sources.
• --config=noexcept build of every runtime library passes.
• cd codegen && gradle build spotlessCheck: Java tests (they assert on the emitted namespace) and formatting pass.
• Goldens: regenerated from the emitters; a second regeneration is byte-identical (git diff --exit-code -- examples protocol-tests is empty), which is what the codegen CI job checks.
• clang-format over every hand-written file and buildifier are clean.

Not run here: sanitizers and clang-tidy (a rename cannot change what they see; CI runs both).

Checklist

• Tests added/updated for the change (no new behavior; every existing suite exercises the rename, and the consumer module proves the migration is one substitution)
• bazel test //... and (cd codegen && gradle build spotlessCheck) pass locally
• Formatting clean (clang-format, buildifier, spotless)
• Architectural decisions recorded as an ADR (ADR-0024)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jj5X2fKdgrYurHmbwLzUiQ

[aaylward]

bazel (linux-clang) on ad3372d failed during analysis, before any test body ran: GitHub answered 500 Internal Server Error for https://github.com/google/boringssl/releases/download/0.20260730.0/boringssl-0.20260730.0.tar.gz, so @boringssl+ could not be fetched and //runtime:http_beast failed to analyze. This PR does not touch MODULE.bazel, the lockfile, or anything boringssl-adjacent; the other 14 jobs in the same run fetched it fine. This is the class .bazelrc's download-retry comment calls out as not retryable by Bazel (a clean 5xx rather than a truncated transfer) with "rerun the job" as the remedy. Re-running that job once.

---

Generated by Claude Code

[aaylward]

Correction to the above: the re-run request was refused (403 Resource not accessible by integration), so I cannot re-run bazel (linux-clang) from here. It needs a manual "Re-run failed jobs" on run 34297522036, or it re-runs on the next push to this branch. The other 14 jobs on this head are unaffected and still running.

---

Generated by Claude Code

[cursor]

Review

LGTM — surface 1 of #201 is scoped correctly and the rename looks complete. ADR-0024’s model-vs-runtime rule holds on the branch, and CI is green across the full matrix on 3f5e5ee.

What looks right

• Runtime / examples / fuzz / benchmarks: no leftover smithy:: or namespace smithy. Headers stay under runtime/include/smithy/ with SMITHY_* guards and smithy: log lines; only the C++ namespace is opal.
• Intentional stays: .smithy model namespaces (smithy.cpp.protocols, smithy.cpp.ruletest, …), io.smithycpp / software.amazon.smithy, smithy_cpp_*_library, @smithy_cpp, and the rules-test fixture’s smithy::cpp::ruletest are untouched.
• Codegen → goldens: emitters print opal::; includes still "smithy/…". Zero smithy:: under examples/*/generated and protocol-tests/*/generated. Protocol-conformance suites moved to opal::protocoltests::… / include/opal/protocoltests/ as a consequence of the configured cpp namespace (not a premature include-root rename).
• Consumer proof: examples/bazel-consumer is the one-substitution migration the CHANGELOG claims (#include "smithy/…" + opal::).
• Docs / ADR / naming: guides teach opal::; no sable leftovers from the earlier name; MODULE.bazel only updates the Version() comment.

Should-fix (docs)

CHANGELOG migration recipe vs. “leave model-derived namespaces alone.” The Breaking entry says migration is smithy:: → opal:: / namespace smithy → namespace opal, then “leave alone … any C++ namespace you derived from your own model’s Smithy namespace.” Those two conflict for a consumer whose Smithy namespace is smithy.cpp.… and whose C++ namespace is therefore smithy::cpp::… — the pattern the ADR preserves for the rules-test fixture. A blind sed would rewrite that too.

Tighten the recipe to something like: substitute the runtime prefixes (smithy::Outcome, smithy::http::, smithy::json::, smithy::server::, smithy::eventstream::, smithy::testing::, … / namespace smithy { that wraps runtime code), and do not touch namespaces that mirror a Smithy model namespace.

Nits (non-blocking)

1. PR body — “include guards and SMITHY_* macros … unchanged” is true for the runtime. Generated protocoltests guards are now OPAL_PROTOCOLTESTS_* because the include prefix follows the cpp namespace setting. Worth a half-sentence so surface 2 doesn’t re-litigate it.
2. Stop naming runtime surfaces after the IDL: audit smithy in generated code and runtime deps #201 decision comment still says the runtime is sable; ADR/PR correctly say opal. Update the tracking issue when convenient so the next two surfaces don’t inherit the old name.

No correctness issues found; happy to see this land.