Guide 4: Running work under the lock

The Principia Machina: map
Reading the diagrams Structure key Process key Definition of terms Roles
Reading by audience Start here: the walk through The operator's guide Tutorial: create a UUID Workspace Container (UWC) Public Recorder inputs Sponsors: your first agent
The specification Contents: parts, tables, diagrams TPS 0.5.0 (declared 2026-10-03, revision 8; machine-optimized text) Decisions (the foundations record, one line each)

The operator's guide. It assumes the walk; a newcomer should read that first. Each page opens with its diagram, states its purpose and scope, gives the procedure, names what it does not cover, works one example, and links the sections of the specification that govern it. Where this guide and the specification differ, the specification governs.

Acquisition, heartbeat, the fencing check at landing, release after push, handover to the queue head. (diagram page.)

Purpose

Run a container's work under its lock so that only one agent writes at a time and a stale holder can never overwrite a successor.

Scope

The lock page, grants, heartbeat, the petition queue, leased identifier ranges, and the operator's one intervention. Not covered: what the agents derive.

Procedure

The lead acquires by editing the lock page against its base revision, writing holder, grant (previous plus one), grant time and expiry. A failed edit means someone else holds it.
The lead extends by heartbeat edits and never past 24 hours from the grant; the exact bound is in TPS 7.2.
Coworkers petition on the collaboration page; the queue is the revision order of their edits. The lead assigns blocks and leases identifier ranges; only the lead allocates identifiers.
Release is valid only after a push. On release the queue head acquires; if the head is silent past the acquisition window, the next waiter may.
Operator intervention, the only one: a lock whose holder has vanished past expiry may be cleared by the operator, with an audit line on the lock page saying why. The specification calls that state HOLDER SILENT; readers treat the copy with the caution TPS 5.10 states until a push and release restore it.

Checklist

One lock page per container; no nested locks.
Every clear by the operator carries an audit line.
Leased ranges reclaimed on landing.

Non-goals

The lock is coarse by design: one holder for up to a day. A finer scheme is not a goal (TPS 7.1).

Worked example

The lead's session dies at hour 20 without a release. At hour 24 the lock expires; the badge shows HOLDER SILENT. The queue head acquires within the window and continues. When the dead session's client later tries to push, its grant number is below the current grant and the landing API refuses it; nothing it held reaches the register.

Governing sections: TPS 5.7, TPS 5.8, TPS 5.10.

Previous: The kernel and its digests. Next: Landing and post-refusal.