chore: import upstream snapshot with attribution

python/mirage/workspace/route/__init__.py

@@ -0,0 +1,32 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.workspace.route.constants import (JOB_BUILTINS, NAMESPACE_COMMANDS,
+                                              NO_FOLLOW_COMMANDS,
+                                              UNSUPPORTED_BUILTINS)
+from mirage.workspace.route.route import route
+from mirage.workspace.route.types import (SHELL_CONSUMERS, Consumer,
+                                          WordPolicy, word_policy)
+
+__all__ = [
+    "Consumer",
+    "JOB_BUILTINS",
+    "NAMESPACE_COMMANDS",
+    "NO_FOLLOW_COMMANDS",
+    "SHELL_CONSUMERS",
+    "UNSUPPORTED_BUILTINS",
+    "WordPolicy",
+    "route",
+    "word_policy",
+]

python/mirage/workspace/route/constants.py

@@ -0,0 +1,37 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.shell.types import ShellBuiltin
+
+# Bash builtins the parser accepts but the executor cannot honor; they
+# still route to the shell layer so the error names a capability gap.
+UNSUPPORTED_BUILTINS = frozenset({
+    "bg",
+    "disown",
+    "exec",
+    "complete",
+    "compgen",
+    "ulimit",
+})
+
+NAMESPACE_COMMANDS = frozenset({"ln", "readlink"})
+
+# ShellBuiltin subset handled through the job table in the executor.
+JOB_BUILTINS = frozenset({"wait", "fg", "kill", "jobs", "ps"})
+
+# Commands with lstat semantics: they act on the symlink entry itself,
+# so dispatch must not rewrite their operands through the link table.
+NO_FOLLOW_COMMANDS = frozenset({"rm", "mv", "ln", "readlink", "rmdir"})
+
+SHELL_NAMES = frozenset(str(b) for b in ShellBuiltin) | UNSUPPORTED_BUILTINS

python/mirage/workspace/route/route.py

@@ -0,0 +1,41 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.workspace.mount import MountRegistry
+from mirage.workspace.route.constants import NAMESPACE_COMMANDS, SHELL_NAMES
+from mirage.workspace.route.types import Consumer
+from mirage.workspace.session import Session
+
+
+def route(name: str, session: Session, registry: MountRegistry) -> Consumer:
+    """Route a command name to the layer that consumes it.
+
+    Order mirrors dispatch precedence: shell builtins shadow functions,
+    functions shadow mount commands, and a name nobody registers is
+    UNKNOWN (command not found).
+
+    Args:
+        name (str): expanded command name.
+        session (Session): shell session (function table).
+        registry (MountRegistry): mount registry (command registration).
+    """
+    if name in SHELL_NAMES:
+        return Consumer.SESSION
+    if name in NAMESPACE_COMMANDS:
+        return Consumer.NAMESPACE
+    if name in session.functions:
+        return Consumer.FUNCTION
+    if registry.mount_for_command(name) is not None:
+        return Consumer.MOUNT
+    return Consumer.UNKNOWN

python/mirage/workspace/route/types.py

@@ -0,0 +1,69 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from enum import Enum, auto
+
+
+class Consumer(Enum):
+    """The layer that consumes a command: a command belongs to the layer
+    whose state it mutates.
+
+    The verdict drives both the dispatch branch and the word policy:
+    SESSION / NAMESPACE / FUNCTION words are shell-resolved (bash
+    contract: programs receive matches, never patterns); MOUNT words
+    keep glob patterns intact for backend pushdown; UNKNOWN words are
+    never resolved (the command fails, backend I/O for it is waste).
+    """
+
+    SESSION = auto()
+    NAMESPACE = auto()
+    FUNCTION = auto()
+    MOUNT = auto()
+    UNKNOWN = auto()
+
+
+SHELL_CONSUMERS = frozenset({
+    Consumer.SESSION,
+    Consumer.NAMESPACE,
+    Consumer.FUNCTION,
+})
+
+
+class WordPolicy(Enum):
+    """How a command's words are resolved, derived from its consumer.
+
+    SHELL: the shell resolves globs before the command runs and spec
+    hints are ignored; bash expands `echo /data/*.txt` no matter what
+    echo does with its arguments. NAMESPACE and FUNCTION consumers get
+    the same treatment (programs receive matches, never patterns).
+
+    MOUNT: the command's spec classifies words (TEXT stays literal,
+    PATH resolves) and glob PathSpecs stay intact for backend pushdown.
+    UNKNOWN names also land here: nothing resolves their words, the
+    command fails before any backend I/O.
+    """
+
+    SHELL = auto()
+    MOUNT = auto()
+
+
+def word_policy(consumer: Consumer) -> WordPolicy:
+    """Map a consumer to its word policy.
+
+    Args:
+        consumer (Consumer): the layer that consumes the command.
+    """
+    if consumer in SHELL_CONSUMERS:
+        return WordPolicy.SHELL
+    return WordPolicy.MOUNT