# Gini Runtime Implementation Notes

These notes describe the current source layout and boundaries. Product direction lives in [Whitepaper](./whitepaper.md). Runtime behavior is documented in [Gateway And Control Plane](./gateway.md), [Conversation And Runs](./conversation-runs.md), and [Memory](./memory.md).

## Source Layout

- `src/types.ts` defines serialized domain contracts and runtime record shapes.
- `src/paths.ts` owns path selection, instance directory layout, ports, and local filesystem conventions.
- `src/server.ts` is the Bun process entrypoint and scheduler loop.
- `src/http.ts` is the authenticated local API router.
- `src/agent.ts` owns task execution and approval-gated tool actions.
- `src/provider.ts` owns provider normalization, health checks, and model calls.
- `src/state/` contains persistence, JSON state store helpers, audit/trace records, IDs, security helpers, SQLite memory storage, and the sandboxed per-agent SQLite database (`agent-data-db.ts`).
- `src/runtime/` contains install/status, public runtime views, parity/readiness checks, and local harness helpers.
- `src/execution/` contains chat, runs, and search behavior.
- `src/memory/` contains retain, recall, reflect, reinforce, embeddings/reranker status, entity, temporal, migration, and schema logic.
- `src/data/` contains the deterministic tabular (CSV/XLSX) → table importer for the agent database.
- `src/jobs/` contains scheduler job creation, execution, replay, run history behavior, and the concern fan-out scheduler — a routed pre-run hook result (`buckets`) dispatches one constrained-subagent worker per non-empty bucket into its `JobRecord.routes[routeKey]` (a `JobRoute`), with the cursor committed per-bucket (ADR `job-concern-fanout.md`).
- `src/hooks/` contains the domain-agnostic pre-run hook primitive: a trusted handler registry, the runner (per-hook timeout, typed result, untrusted-content fence, flat OR routed-`buckets` context rendering), and its barrel. It imports only `src/types`; the scheduler and any other caller consume it, and handlers self-register from their own domains.
- `src/governance/` contains approvals-adjacent runtime workflows such as pairing, improvements, and promotions.
- `src/capabilities/` contains skills, toolsets, agents, and subagent records.
- `src/integrations/` contains connectors, MCP, messaging, import inspection, relay, and notification behavior.
- `src/tools/` contains file, terminal, code, and web tool implementations.
- `src/cli.ts` is the CLI shim.
- `src/cli/` contains CLI routing, API helpers, process management, output helpers, and command modules.
- `web/` is the Next.js control plane and BFF proxy.

## Boundary Rules

- API handlers should delegate behavior to bounded runtime modules instead of embedding state mutation logic.
- Runtime behavior modules may use `src/state/*`, `src/types.ts`, `src/paths.ts`, and neighboring behavior modules when needed.
- Storage modules should remain persistence-oriented: load/save, record constructors, migrations, traces, logs, security helpers, and low-level state utilities.
- API responses must not expose bearer tokens, secret hashes, or credential material.
- CLI commands should prefer public runtime APIs when exercising product behavior.
- Direct module calls from CLI are reserved for local harness/process operations such as install, smoke setup, snapshots, and evidence bundles.
- New connector providers, tools, model providers, and client surfaces should land in focused modules before adding router or CLI commands.
- Hermes-parity features should first add durable runtime records and safe inspection flows before adding live external transports.
- MCP, messaging, and import integrations must fail visibly and must not mutate external installs or credentials by default.

## Current Intentional Compromises

- Most non-memory runtime records still live in a JSON state file for easy local debugging.
- Memory uses SQLite because recall needs structured indexes and durable local query behavior.
- Provider clients still share `src/provider.ts`; split them when provider routing/fallback becomes more complex.
- Some integration surfaces are durable records and health flows before they are full live transports.
- The CLI command set is broad, but command modules now keep behavior out of the top-level shim.
