# Gito Control Plane Contract Candidates

## Transport Policy

- Internal runtime calls use proto-socket first.
- REST remains for health/readiness, provider callbacks, smoke/curl, and simple
  bootstrap endpoints.
- gRPC is excluded from the first design.

## proto-socket Channels

| Channel | Purpose |
| --- | --- |
| `repo` | Register, inspect, and list managed repositories. |
| `workspace` | Lease, release, and inspect workspace slots. |
| `operation` | Create, cancel, inspect, and stream operations. |
| `git` | Request platformless Git operations. |
| `change_request` | Manage provider-neutral PR/MR operations. |
| `agent_shell` | Reserved/legacy shell scaffold metadata; canonical agent UI is `../agent-shell` and backend/runtime is `../iop`. |
| `event` | Subscribe to normalized events. |

## proto-socket Action Registry Scaffold

The first proto-socket surface exposes channel/action registry metadata before
real command execution. Every listed action starts as `placeholder` until its
own Milestone wires storage, worker, or provider behavior.

| Channel | Placeholder actions |
| --- | --- |
| `repo` | `register`, `get`, `list` |
| `workspace` | `lease`, `release`, `get` |
| `operation` | `create`, `cancel`, `get`, `stream` |
| `git` | `clone`, `fetch`, `status`, `diff`, `commit`, `push` |
| `change_request` | `open`, `update`, `list` |
| `agent_shell` | `heartbeat`, `dispatch`, `stream_logs` remain placeholder-only until an explicit compatibility Milestone scopes them. |
| `event` | `subscribe`, `list`, `ack` |

## REST Bootstrap Exceptions

REST may expose temporary repo bootstrap helpers for smoke/curl setup while the
proto-socket `repo` channel is still placeholder-only. Those helpers must stay
limited to bootstrap registration, lookup, and listing, and must use the same
Repo DTO fields documented below.

## Agent Shell / IOP Boundary

`../agent-shell` is the product-agnostic Flutter package for agent interaction
UI and domain models. It is not the Gito backend. Hosts that use that package
should depend on it as `agent_shell: path: ../agent-shell` and route
agent runtime/backend behavior through the sibling `../iop` project.

Gito's responsibility is the Git control plane boundary: repository registry,
workspace leases, operations, revision events, durable event records, and
provider-neutral Git results. IOP owns agent execution, shell command execution,
model/runtime routing, command policy, cancellation, and log redaction source of
truth. Gito may persist IOP results only after they are expressed as operation
state, Git revision/diff, workspace lease state, or normalized event records.
Gito must not expose a competing agent execution API from this contract note
unless a later Milestone explicitly defines an IOP bridge contract.

## MVP: Forgejo Branch Event Flow

Forgejo branch event delivery is now a provided contract:
`agent-contract/provided/gito-forgejo-branch-events-v1.md`.

Read that contract when working on Forgejo webhook intake, `branch.updated`
events, `event.subscribe`, NomadCode branch event wakeups, or the
`/callbacks/forgejo/push` and `/api/listeners/branches` surfaces. This note keeps
only the proto-socket channel registry and DTO candidate overview.

## Core DTO Candidates

### Repo

| Field | Meaning |
| --- | --- |
| `id` | Stable Gito repo id. |
| `name` | Display name. |
| `remote_url` | Git remote URL. |
| `default_branch` | Default source-of-truth branch. |
| `workspace_root` | Local workspace root for slots. |
| `credential_ref` | Reference to credentials, never the raw secret. |

### WorkspaceLease

| Field | Meaning |
| --- | --- |
| `id` | Lease id. |
| `repo_id` | Managed repo id. |
| `slot` | Zero-padded slot index. |
| `path` | Local workspace path. |
| `state` | `available`, `leased`, `dirty`, or `error`. |
| `expires_at` | Optional lease expiry. |

### Operation

| Field | Meaning |
| --- | --- |
| `id` | Operation id. |
| `repo_id` | Target repo. |
| `type` | `clone`, `fetch`, `commit`, `push`, `agent_run`, etc. |
| `state` | `queued`, `running`, `succeeded`, `failed`, `cancelled`. |
| `idempotency_key` | Duplicate guard. |
| `created_by` | Actor id or system source. |

### RevisionEvent

| Field | Meaning |
| --- | --- |
| `repo_id` | Target repo. |
| `branch` | Branch name. |
| `before` | Previous revision. |
| `after` | New revision. |
| `changed_files` | Changed file paths and change types. |
| `observed_at` | Observation timestamp. |

### ChangeRequest

Provider-neutral abstraction for GitHub PR, GitLab MR, Gitea PR, and similar
platform features.

| Field | Meaning |
| --- | --- |
| `provider` | `github`, `gitlab`, `gitea`, etc. |
| `external_id` | Provider PR/MR id. |
| `repo_id` | Target repo. |
| `source_branch` | Source branch. |
| `target_branch` | Target branch. |
| `state` | `open`, `merged`, `closed`, `draft`, etc. |

## Normalized Events

Durable event records use a stable envelope:

| Field | Meaning |
| --- | --- |
| `id` | Stable event id generated by Gito. |
| `type` | Normalized event name from the table below. |
| `subject` | Entity anchor such as `operation:<operation_id>` or `repo:<repo_id>`. |
| `payload` | JSON object encoded as `application/json`; raw provider secrets and credential values are forbidden. |
| `created_at` | Time Gito recorded the event. |

| Event | Meaning |
| --- | --- |
| `repo.changed` | Repo registry changed. |
| `branch.updated` | Watched branch revision changed, initially from Forgejo push webhooks or future revision scans. |
| `workspace.leased` | Workspace lease acquired. |
| `workspace.released` | Workspace lease released. |
| `workspace.dirty` | Workspace has uncommitted changes. |
| `operation.started` | Operation execution started. |
| `operation.completed` | Operation succeeded. |
| `operation.failed` | Operation failed. |
| `agent.run.started` | Agent execution started. |
| `agent.run.completed` | Agent execution completed. |
| `change_request.opened` | PR/MR-like object opened. |
| `change_request.updated` | PR/MR-like object changed. |
| `change_request.merged` | PR/MR-like object merged. |
| `provider.webhook.received` | Provider webhook received. |

### Operation Event Payloads

Operation lifecycle events are stored in the outbox as normalized event records
with `subject=operation:<operation_id>`.

| Event | Required payload fields |
| --- | --- |
| `operation.started` | `operation_id`, `repo_id`, `type`, `state`, `started_at` |
| `operation.completed` | `operation_id`, `repo_id`, `type`, `state`, `completed_at` |
| `operation.failed` | `operation_id`, `repo_id`, `type`, `state`, `failed_at`, optional `error` |

### Outbox Storage Contract

- PostgreSQL is the source of truth for durable events.
- Stored payloads are JSON objects and map to `events.Event.Payload` with
  `events.PayloadEncodingJSON`.
- Outbox readers list events in `(created_at, id)` order.
- Publish retry state belongs to the outbox store boundary; Redis, if added
  later, only accelerates fanout.

### proto-socket Event Mapping

- Stored `type` maps to proto-socket `action` on the `event` channel.
- Stored `payload` maps to the proto-socket envelope `payload` object without
  provider secrets or credential values.
- `event.subscribe` filters by event name and optional payload fields such as
  `repo_id` and `branch`.
- `event.list` returns recent event payloads for smoke/debug use.
- `event.ack` remains placeholder-only until a durable cursor or delivery
  acknowledgement Milestone explicitly scopes it.