a

1 files changed, 7 insertions, 0 deletions

diff --git a/docs/design/tiering.md b/docs/design/tiering.md
new file mode 100644
index 0000000..21a74c9
--- /dev/null
+++ b/docs/design/tiering.md
@@ -0,0 +1,7 @@
+# automatic tiering
+
+automatic tiering was dropped. the `o3` keyword remains the explicit way to request an optimized native region.
+
+tiering would require runtime information the compiler currently records only for `o3` functions, including frame layout, address-taken slots, arrays and argument placement. `o3` also uses a different calling convention for dynamic arrays and enforces compile-time restrictions such as closure and gate-store limits. promoting an ordinary function would therefore need either a uniform calling convention, duplicate compiled versions with call-site switching, or equivalent runtime checks.
+
+keeping `o3` explicit avoids those changes. the existing optimization work—including direct `o3` calls, llvm inlining, global constant and copy propagation, loop-invariant code motion and cross-block common-subexpression elimination—remains available.