The filesystem protocol API

httk.workflow.protocol is the one deliberate public home of the language-neutral filesystem protocol: the document shapes, validators, and primitives an implementation reads and writes to interoperate through a workspace. It is the Python expression of the contract; the normative words are in Workflow filesystem API.

The contract

An independent inspection or verification tool — one that reads a workspace it did not write, checks it, or exports from it — should be able to work from httk.workflow.protocol together with Workflow filesystem API alone, without importing anything else from the package. Everything the protocol defines is re-exported there:

• Workspace format and profile — the core-v2 profile, its readable ancestors, the supported and withdrawn extensions, and WorkspacePolicy.

• Immutable job definitions — JobDefinition, job_digest(), Failure, and the validate_* helpers that check every member of a job.

• Markers and transitions — Marker, MarkerFault, StateFrame, and marker_basename().

• Journal records and references — encode and parse an hwref-v1 reference, and read or verify the frame it names.

• Attempt context and outcome documents — AttemptContext and OutcomeDraft, the shape a runner publishes.

• Replayable data transactions — TransactionBuilder and replay_transaction().

• The protocol error family — WorkflowError and its subclasses.

Nothing in this namespace is manager bookkeeping, a subprocess wrapper, a CLI handler, or a scheduling pass; those are implementation and live elsewhere. The modules that implement these shapes are internal detail from the protocol’s point of view — import the names from httk.workflow.protocol.

The complete list of names is the module’s __all__, documented in the API reference.