# Harakiri Android Bridge — Design

## Problem

The kernel has 9 agents, a scheduler, and a `/proc/harakiri` control
interface. Android doesn't know any of this exists. For Harakiri to
matter on the phone, something in userspace must:

1. Watch what the user is doing (app launches, calls, notifications)
2. Translate that into kernel actions (tag PIDs, set modes)
3. Feed results back to the Harakiri shell (the prototype)

## Architecture

```
┌─────────────────────────────────────────────┐
│  Harakiri Shell (prototype, WebView/APK)    │
│  - Home, Gate, Messages, Gaming, Engine     │
│  - Vera intent bar, Mira's Gate UI          │
└──────────────────┬──────────────────────────┘
                   │ intents, approvals
┌──────────────────▼──────────────────────────┐
│  harakirid (native daemon)                  │
│  - Watches app launches (UsageStats)        │
│  - Vera: classifies intent → agent           │
│  - Tags PIDs via /proc/harakiri/tag         │
│  - Sets modes via /proc/harakiri/mode       │
│  - Reads /proc/harakiri/status for UI       │
└──────────────────┬──────────────────────────┘
                   │ /proc/harakiri/{status,tag,untag,mode}
┌──────────────────▼──────────────────────────┐
│  Harakiri kernel (9 agents, scheduler)      │
└─────────────────────────────────────────────┘
```

## Component 1: harakirid (native daemon)

A small C daemon (not Java — it needs to run early and stay light)
that:

- Opens `/proc/harakiri/status` to discover agents
- Polls `UsageStatsManager` (via a tiny JNI bridge or a companion
  Java service) for foreground app changes
- Maps package names → intents → agents:
  - Game (com.steam, etc.) → Brood, mode=gaming
  - Phone/Messages → Mira's Gate, mode=phone
  - Camera/Gallery → PainTr (for processing)
- Writes `/proc/harakiri/tag` with the app's PID
- Writes `/proc/harakiri/mode` on mode transitions
- Exposes a Unix socket (`/dev/socket/harakiri`) for the shell

## Component 2: Vera intent classifier

Vera's job in userspace mirrors her kernel role: route intents.
A simple table to start (no ML needed for v1):

```c
struct vera_rule {
    const char *package_pattern;
    u32 agent_id;   /* resolved at runtime from /proc/harakiri/status */
    u8 mode;
};

static struct vera_rule vera_rules[] = {
    { "com.valvesoftware.steam",  0, HK_MODE_GAMING },  /* agent resolved */
    { "com.android.dialer",       0, HK_MODE_PHONE },
    { "com.android.mms",          0, HK_MODE_PHONE },
    ...
};
```

Agent IDs are resolved at startup by parsing `/proc/harakiri/status`
— never hardcoded, since registration order could change.

## Component 3: Shell integration

The Harakiri prototype (hosted artifact `harakiri-prototype`) needs:

- A `HarakiriBridge` JavaScript interface (injected by the WebView
  wrapper APK) with methods:
  - `getStatus()` → JSON from `/proc/harakiri/status`
  - `setMode(mode)` → write `/proc/harakiri/mode`
  - `approveGate(id)` / `denyGate(id)` → Mira's queue
- Vera intent bar sends intents to `harakirid` via the socket
- Engine Task View reads live agent quanta from the status

## What NOT to build yet

- No ML intent classification (rules table is fine for v1)
- No cloud sync (on-device only, per the sovereign principle)
- No fancy UI for harakirid (it's headless, logs to logcat)

## Build order

1. `harakirid` core: proc read/write, PID tagging from a static list
2. App launch detection (the JNI bridge is the hard part)
3. Vera rules table
4. Unix socket + shell bridge
5. Polish: logging, error handling, battery awareness

## Open questions for N8toriousAi

- Should harakirid be a standalone binary or part of the Harakiri
  launcher APK's native code?
- For app launch detection: UsageStats (needs permission) or
  ActivityManager polling (needs system privs)?
- Does Mira's Gate need to intercept notifications at the
  kernel level, or is the Android NotificationListener enough?
