# Protocol V2: design notes

Why tapbundle and `tsrepo test` talk Protocol V2 instead of plain TAP, which designs were considered, and what was built. The API of the implementation is in [readme.md](./readme.md); the code is this folder (`@git.zone/tsrepo/tapbundle_protocol`). This document started as tstest's `protocol.md` design proposal; the sections "What was built" and "Limits" describe tsrepo's code as it is.

## Problems with plain TAP

1. **Delimiter conflict**: TAP puts metadata after `#`, which collides with test descriptions that contain `#`.
2. **Ambiguous parsing**: there is no clear boundary between the test name and its metadata.
3. **Limited extensibility**: every new metadata field needs another regular expression.
4. **Mixed concerns**: protocol data is mixed with human-readable output.

## Design principles

1. **Clear separation**: protocol data is unambiguously separated from user content.
2. **Extensibility**: new metadata does not break parsers.
3. **Backwards compatibility**: the output stays TAP, so it can coexist with standard TAP consumers.
4. **Machine readable**: structured data that parses reliably.
5. **Human friendly**: still readable in raw form.

## Designs considered

| Design | Example | Why it was not taken as is |
| --- | --- | --- |
| Special delimiter suffix | `ok 1 - name ::TSTEST:: {"time":123}` | the delimiter can still occur in a test name |
| Separate metadata lines | `ok 1 - name` then `::METADATA:: {"test":1,"time":123}` | the lines must be correlated, so parsing gets harder |
| TAP 13 YAML blocks | `  ---` / `  time: 123` / `  ...` | verbose, and needs a YAML parser |
| Escape-character markers with base64 JSON | `␛[TSTEST:eyJ0aW1lIjoxMjN9]␛` | not readable in raw form |

The implementation combines the first two ideas with delimiters that test names practically never contain: the Unicode brackets `⟦` (U+27E6) and `⟧` (U+27E7).

## What was built

Every protocol item is a marker `⟦TSTEST:<content>⟧` (`PROTOCOL_MARKERS.START` and `PROTOCOL_MARKERS.END`). `PROTOCOL_VERSION` is `2.0.0`.

| Item | Form | Written by |
| --- | --- | --- |
| Version header | `⟦TSTEST:PROTOCOL:2.0.0⟧`, before `TAP version 13` and the plan | `emitProtocolHeader()`; `tap.start()` writes it first |
| Simple metadata | inline on the test line: `ok 1 - name ⟦TSTEST:time:42⟧`, `⟦TSTEST:time:42,retry:1⟧` | `emitTest()` when the metadata holds only `time`, `retry`, `skip` or `todo` |
| Skip and todo reasons | inline: `ok 3 - name # SKIP reason ⟦TSTEST:SKIP:reason⟧`, `⟦TSTEST:TODO:reason⟧` | `emitTest()` |
| Complex metadata | a line of its own after the test line: `⟦TSTEST:META:{…json…}⟧` (the whole metadata without `skip`/`todo`) | `emitTest()` when the metadata holds an `error`, `custom` data, `tags`, a `file` or a `line` |
| Error block | `⟦TSTEST:ERROR⟧`, pretty-printed JSON `{"testNumber":…,"error":{…}}`, `⟦TSTEST:/ERROR⟧` | `emitError()`; `emitTest()` adds it after the META line of a failed test |
| Snapshot block | `⟦TSTEST:SNAPSHOT:<name>⟧`, the content (JSON or text), `⟦TSTEST:/SNAPSHOT⟧` | `emitSnapshot()` |
| Event | `⟦TSTEST:EVENT:{…json…}⟧` (`test:started`, `test:completed`, `assertion:failed`, `suite:started`, …) | `emitEvent()`; tapbundle writes test, suite and assertion events |

A failed test as `emitTest()` writes it:

```
not ok 2 - second test
⟦TSTEST:META:{"time":120,"error":{"message":"Assertion failed","actual":5,"expected":6}}⟧
⟦TSTEST:ERROR⟧
{
  "testNumber": 2,
  "error": {
    "message": "Assertion failed",
    "actual": 5,
    "expected": 6
  }
}
⟦TSTEST:/ERROR⟧
```

`ProtocolParser` reads this line by line: the version header, `TAP version`, plans, `Bail out!`, comments, test lines with their inline markers (`time`, `retry`, `SKIP`, `TODO` and an inline `META`), `EVENT` lines, and `ERROR` and `SNAPSHOT` blocks, whose start marker must stand alone on its line. `tsrepo test` feeds each output line of a test process through it.

## Limits

- A `META` marker counts only on the test line itself. `ProtocolParser.parseLine()` returns no message for a `META` line of its own, which is the form `emitTest()` writes for complex metadata, so that metadata does not reach the parsed test result.
- Marker content cannot contain `⟧`; the parser reads up to the first one.
- tapbundle sends snapshots to `tsrepo test` as a `###SNAPSHOT###<base64 JSON>###SNAPSHOT###` line, not as a `SNAPSHOT` block.
- There is no protocol version negotiation and no switch between protocol versions: tapbundle always writes Protocol V2, and `tap.settings()` has no protocol option.
