03 — Die Drei-Schichten-Architektur

# src/commands.py — Kernfunktionen

@lru_cache(maxsize=1)
def load_command_snapshot() -> tuple[PortingModule, ...]:
    # Lädt ~150 Befehle aus JSON, gecached für Performance
    raw_entries = json.loads(SNAPSHOT_PATH.read_text())
    return tuple(
        PortingModule(
            name=entry['name'],
            responsibility=entry['responsibility'],
            source_hint=entry['source_hint'],
            status='mirrored',
        )
        for entry in raw_entries
    )

PORTED_COMMANDS = load_command_snapshot()

def get_command(name: str) -> PortingModule | None:
    # O(1) Lookup durch Tuple-Iteration
    needle = name.lower()
    for module in PORTED_COMMANDS:
        if module.name.lower() == needle:
            return module
    return None

# src/tools.py — Erweiterte Filterung

def filter_tools_by_permission_context(
    tools: tuple[PortingModule, ...],
    permission_context: ToolPermissionContext | None = None
) -> tuple[PortingModule, ...]:
    # Filtert Tools basierend auf Permission-Denials
    if permission_context is None:
        return tools
    return tuple(
        module for module in tools 
        if not permission_context.blocks(module.name)
    )

def get_tools(
    simple_mode: bool = False,
    include_mcp: bool = True,
    permission_context: ToolPermissionContext | None = None,
) -> tuple[PortingModule, ...]:
    # Flexible Tool-Selektion mit Filtern
    tools = list(PORTED_TOOLS)
    if simple_mode:
        tools = [m for m in tools if m.name in 
                 {'BashTool', 'FileReadTool', 'FileEditTool'}]
    if not include_mcp:
        tools = [m for m in tools if 'mcp' not in m.name.lower()]
    return filter_tools_by_permission_context(tuple(tools), permission_context)

# src/runtime.py — Der Routing-Algorithmus

class PortRuntime:
    def route_prompt(self, prompt: str, limit: int = 5) -> list[RoutedMatch]:
        # 1. Tokenisierung: Normalisierung des Prompts
        tokens = {
            token.lower() 
            for token in prompt.replace('/', ' ').replace('-', ' ').split() 
            if token
        }
        
        # 2. Scoring für Commands und Tools
        by_kind = {
            'command': self._collect_matches(tokens, PORTED_COMMANDS, 'command'),
            'tool': self._collect_matches(tokens, PORTED_TOOLS, 'tool'),
        }
        
        # 3. Fair-Share: Je ein bester Treffer pro Kategorie
        selected: list[RoutedMatch] = []
        for kind in ('command', 'tool'):
            if by_kind[kind]:
                selected.append(by_kind[kind].pop(0))
        
        # 4. Auffüllung nach Score bis zum Limit
        leftovers = sorted(
            [m for matches in by_kind.values() for m in matches],
            key=lambda item: (-item.score, item.kind, item.name),
        )
        selected.extend(leftovers[: max(0, limit - len(selected))])
        return selected[:limit]

    @staticmethod
    def _score(tokens: set[str], module: PortingModule) -> int:
        # Scoring: Wie viele Tokens matchen?
        haystacks = [
            module.name.lower(),
            module.source_hint.lower(), 
            module.responsibility.lower()
        ]
        return sum(
            1 for token in tokens 
            if any(token in h for h in haystacks)
        )

# src/query_engine.py — Session-Management

@dataclass
class QueryEnginePort:
    manifest: PortManifest
    config: QueryEngineConfig = field(default_factory=QueryEngineConfig)
    session_id: str = field(default_factory=lambda: uuid4().hex)
    mutable_messages: list[str] = field(default_factory=list)
    total_usage: UsageSummary = field(default_factory=UsageSummary)
    transcript_store: TranscriptStore = field(default_factory=TranscriptStore)

    def submit_message(self, prompt: str, ...) -> TurnResult:
        # Budget-Prüfung vor Verarbeitung
        if len(self.mutable_messages) >= self.config.max_turns:
            return TurnResult(stop_reason='max_turns_reached', ...)
        
        # Verarbeitung und Usage-Tracking
        projected_usage = self.total_usage.add_turn(prompt, output)
        
        # Budget-Überschreitung?
        total = projected_usage.input_tokens + projected_usage.output_tokens
        if total > self.config.max_budget_tokens:
            stop_reason = 'max_budget_reached'
        
        self.compact_messages_if_needed()
        return TurnResult(...)

    def persist_session(self) -> str:
        # Speichert Session nach .port_sessions/
        return save_session(StoredSession(...))

# src/context.py — Workspace-Kontext

@dataclass(frozen=True)
class PortContext:
    source_root: Path
    tests_root: Path
    assets_root: Path
    archive_root: Path
    python_file_count: int
    test_file_count: int
    asset_file_count: int
    archive_available: bool

def build_port_context(base: Path | None = None) -> PortContext:
    root = base or Path(__file__).resolve().parent.parent
    source_root = root / 'src'
    tests_root = root / 'tests'
    assets_root = root / 'assets'
    archive_root = root / 'archive' / 'claude_code_ts_snapshot' / 'src'
    
    return PortContext(
        source_root=source_root,
        tests_root=tests_root,
        assets_root=assets_root,
        archive_root=archive_root,
        python_file_count=sum(1 for p in source_root.rglob('*.py') if p.is_file()),
        test_file_count=sum(1 for p in tests_root.rglob('*.py') if p.is_file()),
        asset_file_count=sum(1 for p in assets_root.rglob('*') if p.is_file()),
        archive_available=archive_root.exists(),
    )

# src/setup.py — System-Initialisierung

@dataclass(frozen=True)
class WorkspaceSetup:
    python_version: str
    implementation: str          # CPython, PyPy, etc.
    platform_name: str
    test_command: str = 'python3 -m unittest discover -s tests -v'

@dataclass(frozen=True)
class SetupReport:
    setup: WorkspaceSetup
    prefetches: tuple[PrefetchResult, ...]
    deferred_init: DeferredInitResult
    trusted: bool               # Trust-Gating Flag
    cwd: Path

def run_setup(cwd: Path | None = None, trusted: bool = True) -> SetupReport:
    root = cwd or Path(__file__).resolve().parent.parent
    
    # Parallele Prefetch-Operationen
    prefetches = [
        start_mdm_raw_read(),         # Geräte-Info
        start_keychain_prefetch(),    # Schlüsselbund
        start_project_scan(root),     # Projekt-Struktur
    ]
    
    return SetupReport(
        setup=build_workspace_setup(),
        prefetches=tuple(prefetches),
        deferred_init=run_deferred_init(trusted=trusted),
        trusted=trusted,
        cwd=root,
    )

# src/deferred_init.py — Verzögerte Initialisierung

@dataclass(frozen=True)
class DeferredInitResult:
    trusted: bool
    plugin_init: bool      # Plugins laden?
    skill_init: bool       # Skills initialisieren?
    mcp_prefetch: bool     # MCP-Tools prefetch?
    session_hooks: bool    # Session-Hooks aktiv?

def run_deferred_init(trusted: bool) -> DeferredInitResult:
    enabled = bool(trusted)
    return DeferredInitResult(
        trusted=trusted,
        plugin_init=enabled,
        skill_init=enabled,
        mcp_prefetch=enabled,
        session_hooks=enabled,
    )

# src/permissions.py — Tool-Blockierung

@dataclass(frozen=True)
class ToolPermissionContext:
    deny_names: frozenset[str] = field(default_factory=frozenset)
    deny_prefixes: tuple[str, ...] = ()

    def blocks(self, tool_name: str) -> bool:
        lowered = tool_name.lower()
        return (
            lowered in self.deny_names or
            any(lowered.startswith(p) for p in self.deny_prefixes)
        )

# Verwendung:
ctx = ToolPermissionContext.from_iterables(
    deny_names=['Bash', 'Write'],
    deny_prefixes=['mcp__']
)
filtered_tools = filter_tools_by_permission_context(tools, ctx)

def _infer_permission_denials(self, matches: list[RoutedMatch]) -> list[PermissionDenial]:
    denials: list[PermissionDenial] = []
    for match in matches:
        if match.kind == 'tool' and 'bash' in match.name.lower():
            denials.append(PermissionDenial(
                tool_name=match.name,
                reason='destructive shell execution remains gated in the Python port'
            ))
    return denials