> ## Documentation Index
> Fetch the complete documentation index at: https://nativeharness.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Specifications

> Four specs define the harness. An implementation that passes all four conformance sections is a nativeharness.

The specs were published before the implementation so they could be argued with, and the
implementation has sent corrections back to them. They are the contract; the packages are one
implementation of it.

| Spec                                                                                                     | Defines                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`workspace-format.md`](https://github.com/davmixcool/nativeharness/blob/main/specs/workspace-format.md) | the on-disk workspace: manifest, `state.db` schema, `files/`, `blobs/`, export and import, the round-trip guarantee                                                                      |
| [`bash-tool.md`](https://github.com/davmixcool/nativeharness/blob/main/specs/bash-tool.md)               | the one tool: execution sequence, sandbox reuse (meet-or-exceed), hydration with path scope, every guard, the sync report, modes, approval on effects, the connector shim and call token |
| [`protocol.md`](https://github.com/davmixcool/nativeharness/blob/main/specs/protocol.md)                 | the event contract: envelope, every event type, persist-then-emit, reconnect and replay, turn lifecycle, cancellation, versioning                                                        |
| [`connector-schema.md`](https://github.com/davmixcool/nativeharness/blob/main/specs/connector-schema.md) | declared connectors: auth, `verify`, tools, parameter placement, outbound safety, attachment, remote MCP servers                                                                         |

Each spec ends with a conformance section, and `@nativeharness/conformance` is those sections
as tests.

## The interfaces

The four adapter points, as TypeScript, in `@nativeharness/types`:

|                                                                                                                       |                                                                                                         |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`workspace-store.ts`](https://github.com/davmixcool/nativeharness/blob/main/packages/types/src/workspace-store.ts)   | persistence: files, blobs, state, sessions, executions, events, export and import                       |
| [`sandbox-provider.ts`](https://github.com/davmixcool/nativeharness/blob/main/packages/types/src/sandbox-provider.ts) | execution: acquire, hydrate, exec, collect, release, destroy — and the capabilities a provider declares |
| [`connector.ts`](https://github.com/davmixcool/nativeharness/blob/main/packages/types/src/connector.ts)               | declarations, credentials, the gateway, coded connectors                                                |
| [`model-adapter.ts`](https://github.com/davmixcool/nativeharness/blob/main/packages/types/src/model-adapter.ts)       | one decision, as a stream of `ModelEvent`s                                                              |

## Reading order

* **New to it:** `workspace-format.md` §1–3, then `bash-tool.md` §1–3, then `protocol.md` §1–4.
* **Implementing a store:** `workspace-format.md` in full, then `workspace-store.ts`.
* **Implementing a sandbox provider:** `bash-tool.md` §§4–7, then `sandbox-provider.ts`, then run `sandboxConformance()` against it.
* **Writing a connector:** `connector-schema.md` §§2–5, then an existing declaration.
* **Building a UI:** `protocol.md` in full, then the event union in `types.ts`.

## Versioning

Additive changes to a published spec are minor. Anything a conforming reader would misread is
major. The useful contribution while they are drafts is disagreement: a case a rule gets
wrong, a MUST that cannot be implemented, a shape that makes a reasonable UI awkward.