Semantic Router コンセプト

[koriym]

定義

ルータの仕事を「翻訳」から「同型」に変える設計。URL の語彙そのものをドメインの意味論と一致させ、マッチング・生成・改名の各責務を消滅させる。

既存ルータ系統との比較

系統	真実の所在	ルータの仕事	語彙
Regex/Declarative (Symfony, Aura.Router)	ルーティングファイル	URL ↔ アクション の翻訳	3つ別々（route name / path / handler）
Convention (AutoRoute, Rails)	クラス階層・命名規則	URL ↔ クラス の規約変換	2つ（path / class）
Identity (BEAR WebRouter)	パス	path → resource URI の恒等写像	1つ（path = resource）だが意味なし
Semantic	ドメイン語彙 (ALPS)	無し（語彙が一致しているので不要）	1つ（URL = ALPS = code）

中核原則

1. URL パラメータは ALPS の semantic 名をそのまま使う
   ?productCode=5 または ?code=5（スコープ相対の最短一意名）。?id= のような無名 procedural ではない
2. パスはリソースURIと同型
   `/products/detail` ↔ `page://self/products/detail`、翻訳テーブル不要
3. HTTP メソッドは ALPS の transition と直結
   `onGet` / `onPost` が ALPS の safe / unsafe descriptor に一対一
4. path がスコープを与え、query が discriminator を与える
   両者の責務を混ぜない。path で referent、query で識別子
5. ルータは「消えていく」
   コードが増えると Regex 系は太り、Semantic Router は変わらない

なぜ "Semantic" と呼ぶべきか

Convention ではない：規約ルータの規約はフレームワークが押し付けるもの（「クラス名はこう書け」「verb-in-classname にしろ」）。Semantic Router の "規約" はドメイン側から来る — ALPS で `productCode` と定義したから URL も対応する名で書く。フレームワークは何も要求しない。

Identity ではない：恒等写像なだけでは意味は乗らない。`/users/5` の `5` が何者かは WebRouter には分からない。語彙が乗って初めて semantic になる。

既存原則との接続

• HATEOAS: ハイパーメディア応答は自己記述的であるべき → Semantic Router はその principle を request URL 側にも適用 する拡張
• ALPS: state transitions の semantic vocabulary → Semantic Router はその vocabulary を URL の wire format として再利用
• Be Framework の Semantic Variable: 型に意味を持たせる → Semantic Router は URL key にも意味を持たせる、同じ哲学の URL レイヤ表現
• AX (Agent Experience): LLM が外部参照ゼロで URL を理解できる → 副産物として手に入る

何が新しいか

2010年代までの API 設計の議論は「人間にとって美しい URL」と「マシンが解釈しやすい URL」の対立で、前者が REST の影響で勝ってきた。LLM が API クライアントになる時代では 「URL 単体で意味が確定するか」が第三の軸として出現する。Semantic Router はその第三軸に最適化した設計。

```
2000s: マシン優先 → /script.php?action=show&id=5
2010s: 人間優先 → /products/5
2020s: AI 優先 → /products?code=5
```

「逆戻り」に見えるが、実は螺旋。`?code=` の名前付き semantic は `?action=` の無名 procedural とは別物。

BEAR.Package #398 との関係

bearsunday/BEAR.Package#398（2022年, Convention-based router 提案）は問題提起としては正しいが、AutoRoute による解は半分しか DRY を実現していない。`/photo/1/edit → onGet(int $photoId)` の `1` が `$photoId` であることはリフレクション参照が必要なまま。

Semantic Router は同じ DRY 哲学を最後までやり切る位置づけ：

```
2022 #398: AutoRoute 方式（規約で routing file を消す）
2026 : Semantic Router（URL 自体に parameter 名を出してリフレクション参照も消す）
```

#398 を閉じずに、問題提起は維持してアプローチだけ更新する形で接続できる。

BeMart での位置づけ

BeMart は Semantic Router の referent implementation として最適な3条件が揃っている：

• ALPS が既に source of truth（語彙が完成している）
• BEAR Resource クラスが ALPS と同型で並んでいる（投影先がある）
• AI-driven migration を標榜（AX 観点と整合）

#15 を「Aura.Router 導入チケット」から「Semantic Router 適用チケット — BeMart を最初の実証ケースにする」に書き換えるのが筋がいい。

関連 issue

• 独自RouteTable/RouterをAura.Routerベースへ移行する #15 BeMart のルーティング層の再設計（本コンセプトの適用先）
• bearsunday/BEAR.Package#398 Convention-based router（本コンセプトの前身）

[koriym]

棚卸しメモ: 即時のルーティング実装は Aura.Router（#17）採用で確定しました。本 issue は Semantic Router の 設計コンセプト（研究 / ADR 的位置づけ） として open のまま残します。Aura は翻訳型ルータで、本コンセプト（URL = ALPS = code で翻訳テーブルを消す）とは別哲学のため、思想としての価値は維持されます。