Module scratch 

Scratch/candidate store: content-addressed .zen snapshots indexed in scratch/index.jsonl.

Each CandidateEntry records a page_id (the page or source being snapshotted), a snapshot_hash that addresses the raw .zen bytes in the shared object store, a CandidateStatus, and optional workflow metadata.

Append-only contract

This module is append-only: all writes are appends. put_scratch adds new candidates; set_candidate_status transitions an existing candidate’s status by appending a superseding entry (same id/page_id/snapshot_hash, new status and timestamp). list_scratch resolves the latest status per id via last-write-wins deduplication, returning one entry per distinct candidate in first-appearance order. The raw file is fully auditable.

Structs

CandidateEntry

A single scratch candidate record appended to scratch/index.jsonl.

CandidateMeta

Borrowed optional metadata for a new candidate (mirrors VersionMeta).

FinalizeReport

Report of a finalize pass.

NewCandidate

The describing inputs for a new candidate snapshot: which page it captures, the .zen snapshot bytes, its lifecycle status, and optional metadata.

Enums

CandidateStatus

Lifecycle state of a scratch candidate.

Functions

finalize_candidates

Apply each rejected candidate’s cleanup-policy to the scratch store.

get_scratch_snapshot

Recover the stored .zen snapshot bytes for a candidate entry.

list_scratch

List candidate entries for doc_id, one per distinct candidate id.

put_scratch

Store a candidate snapshot and append a CandidateEntry to the scratch index.

set_candidate_status

Transition a candidate’s lifecycle status by appending a superseding entry (same id/page_id/snapshot_hash, new status + fresh timestamp). The scratch index stays append-only and auditable; list_scratch resolves the latest status per id via last-write-wins.