Record, do not publish
A small end-of-turn program that records that the turn ended. It refuses to publish, send, delete, or decide that the work succeeded.
When to use
Use this hook at the end of a turn when the harness needs a record that the turn ended and must not gain a side effect from that moment.
When not to
Do not use this hook to publish, send, delete, approve, or mark success. Do not point it at a network call. Recording is the whole job.
Author-attested
Original teaching specimen written for the Campaign Hub library. Not a transcript of a private run.
# Record, do not publish
This file is a hook: a small program that runs at the end of a turn and only records.
## When to use
Use this at the named moment "end of turn," when a harness wants a durable line that the turn ended. The hook reads one JSON object from standard input and writes one JSON object to standard output.
The harness may append that line to a log. The hook itself does not choose a destination, open a network connection, or touch the publish gate.
## When not to
Do not hang this program on a moment where the job is to publish, send mail, delete files, or decide that the work succeeded. Those acts need their own gates and their own roles.
Do not treat a successful record as a successful task. The record says the turn ended. It does not say the specimen is good.
## The specimen
The artifact is this program.
```python
#!/usr/bin/env python3
"""End-of-turn hook. Records that a turn ended. It does not publish, send, delete, or decide success."""
import json
import sys
from datetime import datetime, timezone
FORBIDDEN = ("publish", "send", "delete", "succeeded")
def main() -> int:
try:
event = json.load(sys.stdin)
except json.JSONDecodeError:
print(json.dumps({"ok": False, "error": "stdin is not JSON"}))
return 2
if not isinstance(event, dict):
print(json.dumps({"ok": False, "error": "event must be an object"}))
return 2
if event.get("action") != "record":
print(json.dumps({"ok": False, "error": "this hook only records"}))
return 2
for name in FORBIDDEN:
if event.get(name):
print(json.dumps({"ok": False, "error": "refusing to " + name}))
return 2
record = {
"event": "turn_ended",
"turn_id": str(event.get("turn_id", "")),
"at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
}
print(json.dumps(record))
return 0
if __name__ == "__main__":
raise SystemExit(main())
```
What it accepts: an object whose `action` is `record`. It may carry `turn_id`. It prints one object with `event` set to `turn_ended`, the turn id, and a time, then exits 0.
What it refuses: a missing or non-object payload, any action other than `record`, and any true `publish`, `send`, `delete`, or `succeeded` field. On a refusal it prints an error and exits 2. It never prints `turn_ended` on a refusal, so a log of `turn_ended` lines cannot be read as a series of publishes or successes.
The program has no network client and no delete call. Adding either one makes it a different program and no longer this specimen.
## How a stranger checks it
Save the program as `record_hook.py`. From a shell, run these two observations.
First, a plain record:
```bash
printf '%s' '{"action":"record","turn_id":"turn-1"}' | python3 record_hook.py
```
The process exits 0. The printed JSON has `"event": "turn_ended"` and `"turn_id": "turn-1"`. It has no field that says the work succeeded.
Second, a record that also asks to publish:
```bash
printf '%s' '{"action":"record","turn_id":"turn-1","publish":true}' | python3 record_hook.py
```
The process exits 2. The printed JSON has `"ok": false` and an error that refuses to publish. It does not contain `turn_ended`.
Repeat the second shape with `send`, `delete`, and `succeeded` set true, one at a time. Each exits 2. A hook that performs any of those actions, or that exits 0 while refusing, is a broken copy.
How a stranger checks it
- HOOK-1 A record event prints one turn_ended object and exits 0. An event that also asks to publish exits 2 and does not claim success. Run the program twice as the check section states. The first exit code is 0 and the JSON event is turn_ended. The second exit code is 2 and the error refuses to publish.