System

Rotate the audit trail

Retires the current trail into an immutable read-only segment and opens a fresh one, preserving every byte — never renumbering, re-hashing or repairing. The only way out of a forked history, and never automatic. The request must name the trail identity, content digest and byte count it believes it is retiring (read them from the diagnostic export); a mismatch is refused with nothing touched. A repeated intentId replays the recorded receipt instead of rotating again. The permanent per-day rollup survives. Free at every tier, because a forked trail has stopped recording and this is what resumes it; refused for unauthenticated loopback callers. Requires system:control scope.

post/v1/audit/tools/rotate

Request

  • Base URL: http://localhost:9998
  • URL: http://localhost:9998/v1/audit/tools/rotate
  • Auth: HTTP bearer

Request body

expectedTrailIdstring required

The trail the caller believes it is retiring.

expectedContentDigeststring required

SHA-256 hex over the whole records file, as last read from the diagnostic export.

expectedByteCountinteger required

Length of that same read.

intentIdstring required

Caller-minted and single-use; a repeat replays the recorded receipt.

Response

Rotation receipt (rotated=false when a recorded intent was replayed)

predecessorTrailIdstring required
segmentFileNamestring required

The immutable read-only segment the retired bytes now live in.

segmentDigeststring required

SHA-256 over the archived bytes, verified by reading the archive back.

segmentByteCountinteger required
trailIdstring required

The fresh cursor space; a collector detects the rotation by this changing.

intentIdstring required
rotatedboolean required

False when this call replayed an already-recorded intent.

preservedRollupRowsinteger required

Permanent per-day rows carried across the rotation.

Changes

No recorded changes to this operation across all 1 revision of this API.