# JMPKit Machine10 Starter Kit

Use Machine when an app needs bounded custom computation that cannot be
composed directly from ordinary JMPKit resources.

## Choose a mode

- **Run Now:** execute one program for one supplied request and return its
  result. Nothing is retained after the run.
- **Main Machine:** install one program for an app, process one event at a
  time, retain sparse memory generations, wake on timers, and optionally answer
  dynamic app-host requests.

Prefer Q, Path, Origin, UWS, Web Push, or another direct resource when those
can finish the job without Machine.

## Read order

1. `protocol/machine10-run-now-v1.md` or
   `protocol/machine10-main-contract-v1.md`
2. `protocol/machine10-guest-abi-v1.md`
3. `protocol/machine10-capabilities-v1.md`
4. `client/machine10.mjs`
5. `examples/README.md`
6. `samples/`

Build every guest on x86-64 Linux with GNU binutils:

```bash
npm run build:guest
```

Run the client and package tests:

```bash
npm test
```

## Safety and authority rules

- Manage Machine only through Gateway. Never call a worker appliance.
- Keep identity bearers and delegated grants out of guest programs and
  published app files.
- A guest receives no credential, app ID, billing identity, arbitrary network,
  host filesystem, or VM-control interface.
- Start with no Main Machine permissions and add only what the program uses.
- `q:prune` and `path:owner` require direct app-owner authority.
- Reuse one `occurrenceId` when retrying the same logical event.
- Treat `202` as admission, not completion. Inspect until that occurrence has
  committed or failed.
- Initialize retained state in the mandatory `init` turn. Public installation
  does not accept an arbitrary initial snapshot.
- Use only the documented, versioned contract. Do not depend on undocumented
  fields or promise an availability level beyond the app's plan.

Private worker routes, execution references, snapshot encoding, VM images,
and transport credentials are intentionally outside this starter.