prompttest 1.3.0

package/dist/lib/step-handlers.d.ts

@@ -0,0 +1,388 @@
+/**
+ * @module step-handlers
+ * @description
+ * StepHandler pattern (A-04) implementation for PromptTest.
+ *
+ * This module implements the Command/Strategy architectural pattern where each action
+ * type (e.g., TAP, SWIPE, VERIFY) is encapsulated in its own independent handler class.
+ * By isolating step execution logic into discrete classes, the PromptRunner becomes a
+ * thin dispatcher relying on an O(1) map lookup (see STEP_HANDLER_REGISTRY).
+ *
+ * Adding a new step type requires only implementing a new StepHandler class and
+ * registering it, ensuring the core execution engine remains untouched and adhering
+ * to the Open/Closed Principle.
+ */
+import { AndroidDriver } from './adb.js';
+import { MemoryEngine } from './memory.js';
+import { UiNode } from './crawler.js';
+import { PromptStep } from './prompt-runner.js';
+/**
+ * ExecutionContext provides shared resources and utility methods to StepHandlers.
+ * It encapsulates the driver instance, state cache, and common UI interaction logic.
+ */
+export interface ExecutionContext {
+    /** The ADB-based Android UI driver used to interact with the device. */
+    driver: AndroidDriver;
+    /** Memory engine used to record and learn resilient locators over time. */
+    memory: MemoryEngine;
+    /** Optional device serial number for targeting specific devices via ADB. */
+    serial?: string;
+    /** Device screen dimensions used for coordinate calculations. */
+    screenDimensions: {
+        width: number;
+        height: number;
+    };
+    /** Height of the navigation bar, used to prevent interacting with system overlays. */
+    navBarHeight: number;
+    /** Cached snapshot of the last known UI hierarchy to accelerate operations. */
+    lastHierarchy: {
+        xml: string;
+        flat: UiNode[];
+        timestamp: number;
+        hash?: string;
+    } | null;
+    /** Caches the provided hierarchy snapshot for subsequent steps. */
+    setLastHierarchy(h: {
+        xml: string;
+        flat: UiNode[];
+        timestamp: number;
+        hash?: string;
+    } | null): void;
+    /** Fetches a fresh UI hierarchy directly from the device. */
+    getCleanHierarchy(serial?: string): Promise<{
+        xml: string;
+        flat: UiNode[];
+    }>;
+    /** Polls for a specific target node until it appears or times out. */
+    waitForTarget(target: string, serial?: string, timeoutMs?: number, step?: PromptStep): Promise<{
+        flat: UiNode[];
+        matched: UiNode[];
+    }>;
+    /** Evaluates nodes against a natural language query or semantic pattern. */
+    matchNodes(nodes: UiNode[], query: string, step?: PromptStep): UiNode[];
+    /** Checks if a node is visible, scrolling the viewport if necessary. */
+    ensureInViewport(node: UiNode, serial?: string): Promise<boolean>;
+    /** Generates rich, contextual errors when a step fails. */
+    buildDiagnosticError(target: string, flat: UiNode[], context: string): Error;
+    /** Specialized locator for finding form inputs, prioritizing matching hints or labels. */
+    findTargetInputField(nodes: UiNode[], target: string, value?: string): UiNode | null;
+    /** Future steps in the current script, used for fast-forward lookahead optimizations. */
+    upcomingSteps?: PromptStep[];
+    /** Live mutable variables map for storing and interpolating $var values across steps. */
+    variables: Map<string, string>;
+    /** Stack tracking nested loop executions to prevent infinite recursion. */
+    loopStack: Array<{
+        current: number;
+        total: number;
+        variable?: string;
+    }>;
+    /** Callback to execute a sequence of child steps (e.g. inside IF or LOOP). */
+    executeChildSteps?(steps: PromptStep[], ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Represents the outcome of a StepHandler's execution.
+ */
+export interface StepResult {
+    /** Indicates if the step was bypassed because its desired state was already met. */
+    fastForwarded?: boolean;
+    /** Explanation for why the step was fast-forwarded or altered. */
+    reason?: string;
+    /** Number of upcoming steps to skip if fast-forwarded over multiple actions. */
+    skipCount?: number;
+}
+/**
+ * The base interface for all action handlers.
+ * Enforces a strict contract for dispatching PromptStep instructions.
+ */
+export interface StepHandler {
+    /** The specific PromptStep type this handler is responsible for (e.g., 'TAP'). */
+    readonly type: PromptStep['type'];
+    /**
+     * Executes the step using the provided context.
+     *
+     * @param step - The parsed step instruction to execute.
+     * @param ctx - The execution context providing driver and utility access.
+     * @returns A promise resolving to a StepResult, or void if standard execution completes.
+     * @throws Will throw if the step cannot be completed (e.g., element not found).
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles TAP actions by finding the target element and simulating a single touch event.
+ * Incorporates fast-forwarding and auto-scrolling optimizations.
+ */
+export declare class TapHandler implements StepHandler {
+    readonly type: "TAP";
+    /**
+     * Executes the TAP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles LONG_PRESS actions by pressing and holding on a target element.
+ */
+export declare class LongPressHandler implements StepHandler {
+    readonly type: "LONG_PRESS";
+    /**
+     * Executes the LONG_PRESS step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles TYPE actions to input text into form fields.
+ * Manages focus, clearing existing text, and keyboard interactions.
+ */
+export declare class TypeHandler implements StepHandler {
+    readonly type: "TYPE";
+    /**
+     * Executes the TYPE step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles CLEAR actions to empty an input field.
+ * Locates the target input, taps to focus, and clears its contents.
+ */
+export declare class ClearHandler implements StepHandler {
+    readonly type: "CLEAR";
+    /**
+     * Executes the CLEAR step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles VERIFY actions to assert the presence or state of elements on the screen.
+ */
+export declare class VerifyHandler implements StepHandler {
+    readonly type: "VERIFY";
+    /**
+     * Executes the VERIFY step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles BACK actions by simulating a hardware back button press.
+ */
+export declare class BackHandler implements StepHandler {
+    readonly type: "BACK";
+    /**
+     * Executes the BACK step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(_step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles SCROLL actions to navigate through lists or pages.
+ */
+export declare class ScrollHandler implements StepHandler {
+    readonly type: "SCROLL";
+    /**
+     * Executes the SCROLL step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles SWIPE actions to perform directional swipe gestures on the screen or specific elements.
+ */
+export declare class SwipeHandler implements StepHandler {
+    readonly type: "SWIPE";
+    /**
+     * Executes the SWIPE step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles TOGGLE actions for checkboxes and switches, ensuring the element reaches the desired state.
+ */
+export declare class ToggleHandler implements StepHandler {
+    readonly type: "TOGGLE";
+    /**
+     * Executes the TOGGLE step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles SELECT actions to choose an option from a dropdown or picker modal.
+ */
+export declare class SelectHandler implements StepHandler {
+    readonly type: "SELECT";
+    /**
+     * Executes the SELECT step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles LAUNCH_APP actions by starting the application via its package name.
+ */
+export declare class LaunchAppHandler implements StepHandler {
+    readonly type: "LAUNCH_APP";
+    /**
+     * Executes the LAUNCH_APP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles RESTART_APP actions by forcefully stopping and then relaunching the app.
+ */
+export declare class RestartAppHandler implements StepHandler {
+    readonly type: "RESTART_APP";
+    /**
+     * Executes the RESTART_APP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles TERMINATE_APP actions by forcefully stopping the application.
+ */
+export declare class TerminateAppHandler implements StepHandler {
+    readonly type: "TERMINATE_APP";
+    /**
+     * Executes the TERMINATE_APP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles CLEAR_DATA actions by wiping the application's local data and cache.
+ */
+export declare class ClearDataHandler implements StepHandler {
+    readonly type: "CLEAR_DATA";
+    /**
+     * Executes the CLEAR_DATA step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles GRANT_PERMISSION actions to grant specific runtime permissions to the app.
+ */
+export declare class GrantPermissionHandler implements StepHandler {
+    readonly type: "GRANT_PERMISSION";
+    /**
+     * Executes the GRANT_PERMISSION step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles DEEP_LINK actions by opening a URI scheme or Intent.
+ */
+export declare class DeepLinkHandler implements StepHandler {
+    readonly type: "DEEP_LINK";
+    /**
+     * Executes the DEEP_LINK step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles WAIT actions by pausing execution for a specified duration.
+ */
+export declare class WaitHandler implements StepHandler {
+    readonly type: "WAIT";
+    /**
+     * Executes the WAIT step.
+     * @param step - The step instruction.
+     * @param _ctx - The execution context.
+     */
+    execute(step: PromptStep, _ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles conditional branching based on UI element presence.
+ * Executes thenSteps if visible, or elseSteps if present and element not found.
+ */
+export declare class ConditionalHandler implements StepHandler {
+    readonly type: "IF_VISIBLE";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles iterative execution of child steps with loop bound protections.
+ */
+export declare class LoopHandler implements StepHandler {
+    readonly type: "LOOP";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Polls for an element to appear or become enabled without failing immediately.
+ */
+export declare class WaitUntilHandler implements StepHandler {
+    readonly type: "WAIT_UNTIL";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Sets dynamic variables in the execution context for interpolation into subsequent steps.
+ */
+export declare class SetVariableHandler implements StepHandler {
+    readonly type: "SET_VARIABLE";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Executes hardware and connectivity controls (Wi-Fi, Airplane mode, Orientation, Notifications).
+ */
+export declare class DeviceStateHandler implements StepHandler {
+    readonly type: "DEVICE_STATE";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Executes a sandboxed JavaScript snippet for runtime calculations or variable manipulation.
+ */
+export declare class RunJsHandler implements StepHandler {
+    readonly type: "RUN_JS";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles automatic capture and input of One-Time Passwords (OTP) and 2FA codes.
+ * Reads codes from mock environment variables or live ADB logcat streams.
+ */
+export declare class OtpHandler implements StepHandler {
+    readonly type: "ENTER_OTP";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles HTTP requests and API assertions within a test flow.
+ * Capable of extracting JSON response fields into runtime $variables.
+ */
+export declare class ApiHandler implements StepHandler {
+    readonly type: "API_REQUEST";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+    private resolveJsonPath;
+}
+/**
+ * Handles assertions on transactional emails delivered to users during testing.
+ */
+export declare class EmailHandler implements StepHandler {
+    readonly type: "EMAIL_ASSERT";
+    execute(step: PromptStep, _ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * STEP_HANDLER_REGISTRY maps step types to their concrete handler implementations.
+ * Provides an O(1) lookup for dispatching steps in the PromptRunner.
+ */
+export declare const STEP_HANDLER_REGISTRY: Map<import("./runner-utils.js").PromptStepType, StepHandler>;

package/docs/ARCHITECTURE.md

@@ -0,0 +1,154 @@
+# PromptTest Architecture & System Design
+
+PromptTest is a zero-code, AI-assisted Android test automation and visual QA framework. It drives native Android devices over ADB without requiring app instrumentation, agent binaries, or server daemons.
+
+---
+
+## 1. High-Level Architecture Overview
+
+PromptTest operates on a modular layered architecture where test scripts written in natural language or AST-driven directives are compiled, bound to live or synthetic data, executed against connected devices via an isolated locking layer, and reported with visual diffs and interactive HTML reports.
+
+```
+┌───────────────────────────────────────────────────────────┐
+│                    CLI & Runner Interface                 │
+│                 (bin/prompttest.ts, index.ts)             │
+└─────────────────────────────┬─────────────────────────────┘
+                              │
+┌─────────────────────────────▼─────────────────────────────┐
+│                    Compilation & Parsing                  │
+│       lib/runner-utils.ts (AST, Parser, Includes)         │
+│       lib/data-loader.ts  (Dynamic generators, CSV/JSON)  │
+└─────────────────────────────┬─────────────────────────────┘
+                              │
+┌─────────────────────────────▼─────────────────────────────┐
+│                   PromptRunner Orchestrator               │
+│                     (lib/prompt-runner.ts)                │
+└──────┬──────────────────────┬──────────────────────┬──────┘
+       │                      │                      │
+┌──────▼──────────────┐┌──────▼──────────────┐┌──────▼──────────────┐
+│ Modular Handlers    ││ Self-Healing & AI   ││ Device & Locking    │
+│ lib/step-handlers.ts││ lib/memory.ts       ││ lib/lock.ts         │
+│ (Wait, Tap, Type,   ││ lib/patterns.ts     ││ lib/adb.ts          │
+│  Cond, Loop, API,   ││ lib/ai/             ││ lib/ios-driver.ts   │
+│  OTP, Email, Check) ││ (LLM & Vision)      ││                     │
+└─────────────────────┘└─────────────────────┘└─────────────────────┘
+       │                      │                      │
+┌──────▼──────────────────────▼──────────────────────▼──────┐
+│              Visual Testing & Diagnostics                 │
+│          lib/baseline.ts (SSIM / Perceptual Diff)         │
+│          lib/explorer.ts (Autonomous Crawler)             │
+└─────────────────────────────┬─────────────────────────────┘
+                              │
+┌─────────────────────────────▼─────────────────────────────┐
+│                 Reporting & Observability                 │
+│       lib/reporter.ts (HTML, JSON, JUnit XML, Markdown)   │
+│       lib/live-server.ts (SSE / WebSocket Live Dash)      │
+└───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Core Modules & Responsibilities
+
+### 2.1 PromptRunner Orchestrator (`lib/prompt-runner.ts`)
+
+The `PromptRunner` class coordinates the full lifecycle of test execution:
+
+- **Device Provisioning & Locking**: Acquires exclusive locks (`lib/lock.ts`) from device pools or the default ADB device.
+- **Spec Resolution**: Loads script files, resolves data-driven iterations (`#!data`, `--iterations`, `--only-row`), expands modular includes (`#include <spec>`), and tokenizes AST step blocks.
+- **Step Execution Loop**: Delegates individual step execution to registered step handlers (`lib/step-handlers.ts`) while handling error collection, retry policies, screenshot capture, and timeout budgets.
+- **Reporting Hook Dispatch**: Triggers lifecycle callbacks (`onStep`, `onComplete`, `onError`) across reporters and live monitors.
+
+### 2.2 Runner Utilities & Parser (`lib/runner-utils.ts`)
+
+Extracted from the monolithic runner to ensure clean separation of concerns and maintainability:
+
+- `parsePrompt(prompt)`: Tokenizes raw natural language statements into typed `PromptStep` AST definitions with action, target, value, timeout, and regex parameters.
+- `assembleAstBlocks(lines)`: Assembles structured nested blocks (conditionals `IF...ELSE...ENDIF`, loops `LOOP...ENDLOOP`, wait-untils `WAIT_UNTIL...ENDWAIT`) into hierarchical AST trees.
+- `expandSpecIncludes(specPath, visited)`: Recursively resolves and flattens `#include <subspec.txt>` directives with circular dependency detection.
+- `buildDiagnosticError(...)`: Enriches execution failures with element dumps, screenshot paths, and suggested locator fixes.
+- `findTargetInputField(tree, label)` & `matchNodes(tree, query)`: Spatial and attribute-based UI hierarchy matching algorithms.
+
+### 2.3 Modular Step Handlers (`lib/step-handlers.ts`)
+
+Instead of an unwieldy switch-case statement, execution is delegated to decoupled, single-responsibility handlers:
+
+- **Primitive Action Handlers**: `WaitHandler`, `TapHandler`, `TypeHandler`, `VerifyHandler`, `SwipeHandler`, `KeyEventHandler`.
+- **Flow Control Handlers**: `ConditionalHandler` (boolean element visibility checks), `LoopHandler` (fixed or dynamic iteration loops), `WaitUntilHandler` (polling with timeout), `SetVariableHandler`, `RunJsHandler` (sandboxed JavaScript expressions via `node:vm`).
+- **Integration Handlers**:
+  - `OtpHandler`: Extracts verification codes from local mock stores, environment variables, or live SMS/email inboxes.
+  - `ApiHandler`: Dispatches synchronous REST/HTTP assertions (`status`, `jsonPath`, `headers`) directly within the test pipeline.
+  - `EmailHandler`: Asserts transactional email delivery and body content against test stores.
+- **State & Checkpoint Handlers**: `DeviceActionHandler` (network, airplane mode, orientation, notifications), `CheckpointHandler` (named state saves and rollback).
+
+### 2.4 Data-Driven Engine (`lib/data-loader.ts` & `lib/form-filler.ts`)
+
+- **Iterative Testing**: Loads parameter matrices from CSV, JSON, or inline `#!data` tables.
+- **Dynamic Generators**: In-line variable expansion for synthetic data generation:
+  - `$random.firstName`, `$random.lastName`, `$random.email`, `$random.phone`
+  - `$random.string(len)`, `$random.number(min, max)`
+  - `$uuid` (v4 UUID)
+  - `$seq.id` (monotonically incrementing sequence)
+  - `$date.now`, `$date.iso`, `$date.format(...)`
+  - `$calc(expression)`: Runtime arithmetic evaluation.
+
+### 2.5 Hardware & Device Layer (`lib/adb.ts`, `lib/lock.ts`, `lib/ios-driver.ts`)
+
+- `lib/adb.ts`: Wraps Android Debug Bridge commands (`shell input`, `uiautomator dump`, `screencap`, `install`, `forward`, Wi-Fi, airplane mode, orientation).
+- `lib/lock.ts`: File-locking (`flock`/lockfile) mechanism enabling parallel worker execution across multi-device test farms (`--device-pool dev1,dev2`) without device collision.
+- `lib/ios-driver.ts`: Implements `DriverInterface` for Apple iOS physical devices and Simulators via `idb` and `xcrun simctl`.
+
+### 2.6 Visual Baselines & Computer Vision (`lib/baseline.ts`, `lib/explorer.ts`)
+
+- Pixel-by-pixel perceptual diffing and Structural Similarity Index Measure (SSIM) algorithms.
+- Configurable failure thresholds (e.g. `diffThreshold: 0.02` for 2% variance).
+- Automatic bounding box masking for dynamic regions (e.g. status bar clocks, live feeds) to eliminate false positives in visual regression testing.
+
+### 2.7 Self-Healing & Memory (`lib/memory.ts`, `lib/ai/`)
+
+- Persistent memory storage (`.prompttest/memory.json`) mapping natural language queries to confirmed UI element identifiers (`resource-id`, `content-desc`, text).
+- Autonomous self-healing: When an element locator shifts or fails, PromptTest queries the memory cache and fuzzy synonym dictionary (`lib/dictionary.ts`), falling back to optional LLM/Vision providers (`lib/ai/llm-provider.ts`) to repair the locator automatically.
+
+### 2.8 Observability & Reporting (`lib/reporter.ts`, `lib/live-server.ts`)
+
+- Multi-format report generation: Interactive standalone HTML dashboards with embedded base64 screenshots, JSON execution summaries, JUnit XML (for CI/CD pipelines like GitHub Actions and GitLab CI), and Markdown summaries.
+- Real-time event streaming (`lib/live-server.ts`) for browser dashboards and CI progress logs.
+
+---
+
+## 3. Execution Data Flow
+
+```
+[Spec File (.txt)]
+       │
+       ▼
+[expandSpecIncludes] ─── Flat Raw Prompt
+       │
+       ▼
+[DataLoader / Generators] ─── Bound Row Variables ($var)
+       │
+       ▼
+[assembleAstBlocks] ─── Hierarchical AST (PromptStep[])
+       │
+       ▼
+[PromptRunner.runStep] ─── Iterates AST nodes
+       │
+       ├─► [Acquire Device Lock]
+       ├─► [Capture Screen & Dump Hierarchy]
+       ├─► [Resolve Element via Memory / Crawler / AI]
+       ├─► [Dispatch to Handler (lib/step-handlers.ts)]
+       ├─► [Evaluate Baseline Diff if visual step]
+       └─► [Emit Events & Record Step Result]
+       │
+       ▼
+[Reporter.generateReport] ─── Output HTML / JSON / XML
+```
+
+---
+
+## 4. Design Principles & Non-Functional Guarantees
+
+1. **Zero Client Instrumentation**: Target mobile applications require no modified build flavors, no test SDKs, and no debugging permissions beyond standard ADB authorization.
+2. **Deterministic Flow Control**: Programmatic constructs (`IF`, `LOOP`, `WAIT_UNTIL`) execute with predictable time bounds and clear exit conditions.
+3. **Fail-Fast vs. Resilient Execution**: Controlled via CLI flags (`--fail-fast` vs. `--continue-on-failure`), allowing rapid iteration in development or broad test suite discovery in nightly CI runs.
+4. **Strict Modular Decoupling**: File sizes are capped (<1100 lines for core orchestrator), types are strictly enforced without `any` escapes, and modules communicate via well-typed TypeScript interfaces.