> ## Documentation Index
> Fetch the complete documentation index at: https://committ.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocker Module

> Accessibility-based anti-circumvention engine and live GPS tracker.

# Blocker Module

The `blocker-module` is the core enforcement infrastructure for the CommitT accountability platform. It utilizes an Android `AccessibilityService` to intercept application launches and user interactions in real-time.

## Dual Enforcement Vectors

The service guarantees absolute enforcement via two complementary monitoring systems to prevent system-level evasion.

```mermaid theme={null}
graph TD
    A[Android OS] -->|AccessibilityEvent| B(Event-Driven Hook)
    A -->|5000ms Handler| C(Pulse-Based Audit)
    
    B -->|WINDOW_STATE_CHANGED| D{Evaluate Target Package}
    B -->|WINDOW_CONTENT_CHANGED| D
    C -->|Read current top window| D
    
    D -->|Approved| E[Allow Execution]
    D -->|Restricted| F[Initialize Block Protocol]
```

1. **Event-Driven Enforcement**: Responds instantly to `AccessibilityEvent` callbacks to intercept restricted apps the precise millisecond they render.
2. **Pulse-Based Background Audit**: A continuous 5-second background heartbeat (`pulseRunnable`) periodically re-evaluates the foreground package. This mitigates edge cases where the OS drops accessibility events (e.g., split-screen transitions, Picture-in-Picture mode).

## Location Enforcement (Fail-Closed)

When a commitment includes a geofence, the Blocker maintains a real-time 1Hz GPS tracking stream.

* **Strict Live Enforcement**: Spatial access decisions are gated exclusively on live coordinates. The service never defaults to cached `getLastKnownLocation()` data, preventing spoofing via background disconnects.
* **Staleness Threshold**: If a GPS fix is older than 30 seconds (accounting for Android's 20-second background OS polling limitations), the Blocker defaults to a **fail-closed** policy, restricting access until cryptographic location certainty is restored.

## Maximum Escalation (Device Lock & Purge)

If a user attempts a deep security violation (e.g., attempting to uninstall CommitT or disable the accessibility service), the Blocker initiates a **Maximum Escalation** sequence.

On heavily modified OEM variants like Samsung's OneUI, it executes a strict 3-Phase Purge:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant SystemUI as Settings / PackageInstaller
    participant Blocker
    participant OS as Android Kernel

    User->>SystemUI: Attempt uninstallation
    SystemUI->>Blocker: Event Triggered
    Note over Blocker: Violation Detected
    Blocker->>OS: 1. GLOBAL_ACTION_RECENTS
    Note over Blocker,OS: Breaks interaction loop instantly
    Blocker->>OS: 2. Inject automated click on 'Close all'
    Note over Blocker,OS: Purges the crime scene from memory
    Blocker->>OS: 3. GLOBAL_ACTION_LOCK_SCREEN
    OS->>User: Screen powers off, hardware lock engaged
```

## Concurrency and SQLite Stability

Identical to the Scheduler architecture, the Blocker explicitly opens its SQLite database connection in `OPEN_READONLY` mode. This prevents WAL writer contention against the React Native user interface. To eliminate stale reads, the connection is forcefully closed and a fresh WAL snapshot is acquired on every 5-second pulse.