# Machine10 Main Machine management contract v1

Contract: public v1.

## Authority and base URLs

An owner can use either equivalent base:

```text
https://jmpkit.com/api/apps/<appId>/machine10/main
https://<appHost>/api/machine10/main
```

Every request requires `Authorization: Bearer <identity bearer>`. A delegated
agent also sends `X-JmpKit-Grant: <approved grant id>`. JSON requests use
`Content-Type: application/json`.

The URL identifies the app. Machine ignores an `appId` supplied in JSON.
Successful envelopes use `jmpkit.machine.main-machine-api.v1` and contain
`ok: true` plus a `machine`, `generation`, or `deletion` value.

## Routes

| Method | Relative path | Purpose | Success |
|---|---|---|---|
| `GET` | `/` | Inspect current state | `200` |
| `POST` | `/` | Install the app's Main Machine | `201` |
| `DELETE` | `/` | Delete after stop and confirmation | `200` |
| `PUT` | `/program` | Publish a new program revision | `200` |
| `POST` | `/program/rollback` | Restore an archived program as a new revision | `200` |
| `POST` | `/events` | Admit one occurrence | `202` if new, otherwise `200` |
| `PUT` | `/timer` | Set or replace a durable timer | `200` |
| `DELETE` | `/timer` | Cancel the durable timer | `200` |
| `POST` | `/pause` | Stop pumping while preserving queued work | `200` |
| `POST` | `/resume` | Resume a paused Machine | `200` |
| `POST` | `/stop` | Enter the terminal stopped lifecycle | `200` |
| `POST` | `/retry` | Retry the failed head occurrence | `200` |
| `GET` | `/generations/<n>` | Inspect one committed generation | `200` |

## Install

```json
{
  "programBase64": "<canonical base64>",
  "programVersion": "1",
  "permissions": ["q:append", "q:read"],
  "maxCalls": 2,
  "initPayload": {"source": "starter"}
}
```

The program is at most 256 KiB decoded and uses kind
`jmpkit.machine.program.x86_64-retained.v1`. `programVersion` defaults to `1`.
`maxCalls` is 1–16. Supported permissions are:

```text
q:append
q:read
q:prune
path:read
path:write
path:owner
```

Only a direct owner can install `q:prune` or `path:owner`. Installation creates
the mandatory `init` occurrence at generation zero. The guest initializes its
retained memory during that turn; arbitrary initial snapshots are not a public
input.

## Events and idempotency

```json
{
  "occurrenceId": "occ_stable_retry_key_01",
  "kind": "manual",
  "payload": {"message": "do this once"},
  "deadline": "<optional future ISO-8601 timestamp>"
}
```

Payloads are bounded JSON. Use one stable `occurrenceId` for retries of the
same logical event. A duplicate is acknowledged without executing twice.
`202` means admitted, not committed. Inspect until the occurrence appears in
`lastTurn` or `generationHistory`, or until the Machine reports a failure or
dead letter.

Machine runs one turn at a time. Concurrent arrivals are retained in FIFO
order. A failed turn remains at the head and blocks later work until an
authorized retry or program replacement resolves it.

## Timers

Set a timer with exactly one of absolute `at` or relative `delayMs`, plus an
optional JSON payload:

```json
{"delayMs": 60000, "payload": {"reason": "wake up"}}
```

The maximum delay is 365 days. The timer survives ordinary coordinator and
worker restarts. A guest turn can keep, cancel, or replace the current timer.

## Lifecycle and program changes

Pause preserves the queue and timer but does not pump work. Resume restarts a
paused Machine. Stop rejects new events and cannot be resumed directly;
publishing a replacement program activates it again.

Program replacement preserves retained memory in v1 and queues an ordinary
`program.replaced` occurrence. Rollback never rewrites history: it publishes a
new monotonic program revision whose source points at the selected archived
revision.

Deletion requires a stopped Machine and:

```json
{"confirmAppId": "<exact appId>"}
```

Deletion also clears a configured Machine Origin fallback.

## Inspection

Inspection reports lifecycle/status, program lineage, current generation,
queue and in-flight occurrence, timer, permissions, recent generations, dead
letters, last turn/error, provenance, and cumulative usage. Common statuses:

```text
ready | running | pending | idle | waiting | paused | stopped | failed
```

Generation zero represents the empty pre-init state. Each successful turn
atomically publishes exactly one successor generation. A generation response
contains its memory digest, occurrence/turn identity, and committed output.

## Bounds

Contract v1 bounds include a 256 KiB program, 32 KiB encoded event JSON,
128 queued events, 16 calls per turn, 64 KiB per resource response, and a
365-day timer/deadline horizon. The guest has a 32 MiB logical retained
aperture, but only changed pages are persisted and the encoded sparse snapshot
is capped at 64 KiB. These are enforced service limits; design within them.

Read `machine10-guest-abi-v1.md` for the program interface and
`machine10-capabilities-v1.md` for Q and Path calls.