Maintained repository documentationView source on GitHub

Rendered from docs/API_STABILITY.md at build time without changing its status. The repository source controls if this presentation differs.

Python application programming interface (API) stability#

Term: Verifier Standard (VSTD).

This policy applies beginning with the first release that contains it. It does not retroactively change frozen receipts or earlier release bytes.

Supported boundary#

The supported Python runtime API is the set of names exported by verifier.__all__ and rendered under Top-level Python exports in the generated reference. The implementation tests that the two surfaces agree and that every exported name resolves.

verifier.__version__, verifier.__standard__, and verifier.__standard_status__ are stable read-only metadata names. The standard coordinate and status describe this project; they do not claim standards-body recognition, conformance, adoption, or endorsement.

The supported artifact-control exports are freeze_artifact, seal_artifact, verify_frozen_artifact, thaw_artifact, thawed_artifact_status, ArtifactVerification, and ArtifactControlError. Seal creation and seal verification require the optional seal dependency extra; importing the base package and freeze-only operations retain the zero-third-party-dependency boundary.

freeze_artifact classifies the supplied final source entry before dereferencing it and refuses symbolic links. New freeze bundles, thaw descendants, and generated thaw sidecars require absent lexical destination entries, including refusal of dangling symbolic links. This fail-closed creation contract does not promise universal race-free filesystem security against concurrent privileged replacement.

Verification also requires authoritative internal bundle members to have their ordinary lexical file or directory type. The freeze manifest, payload, seals container, and seal envelopes cannot inherit authoritative bytes through symbolic links or supported reparse-point aliases. This does not change the accepted read-only alias behavior of an outer parent-bundle or explicit thaw-record argument. Ordinary hard links remain regular file byte-and-path semantics rather than an exclusive-inode claim.

thawed_artifact_status treats a VSTD-ARTIFACT-THAW-1 sidecar as unkeyed lineage metadata. Without parent_bundle, it returns NOT_ESTABLISHED even when descendant bytes agree with the sidecar's recorded identifier. THAWED_CLEAN or THAWED_DIRTY requires an actual supplied parent that verifies as cleanly sealed and matches every recorded parent coordinate. Optional expected artifact and key identifiers add external-anchor checks. The result still does not authenticate the historical copy operation.

The supported evidence-bound construction exports are BoundProposition, EvidenceBindingError, EvidenceBounds, EvidenceStore, MechanismDecision, MechanismOutcome, VerificationSession, WitnessBundle, ProvenanceHypergraph, claim_binding_from_dict, establish_vstd4, assess_witness_corroboration, establish_graph_level, graph_collection_binding_digest, and AssuranceLedger. The matching supported portable-record exports are build_evidence_bound_vstd4_receipt, recheck_evidence_bound_vstd4_receipt, build_vstd5_receipt, recheck_vstd5_receipt, build_evidence_bound_graph_level_record, recheck_evidence_bound_graph_level_record, and recheck_assurance_log. Compatibility vstd4_depth and graph_level-style candidate results do not become conformance results merely because the evidence-bound APIs also exist.

assess_witness_corroboration accepts incomplete inputs so it can return a typed diagnostic result. The supported build_vstd5_receipt boundary is stricter: it either raises or returns an object satisfying the published receipt shape with all verdict-material evidence bytes. recheck_vstd5_receipt applies the same zero-dependency structural gate before replay and does not accept a schema-invalid assessment object as a portable receipt. It also compares the complete carried VSTD-4 entry, requires the bundle claim_id to equal the admitted VSTD-4 claim identifier, and mechanism-checks corroboration_class; schema-valid field relabeling cannot retain an established replay result.

ProvenanceHypergraph.from_dict retains the frozen VSTD-DATA-0.1 two-namespace reader: one identifier may occur once as an artifact and once as a transformation. Direct add_* construction and default structural validation are stricter and globally disjoint. Such a historical overlap remains readable but cannot enter evidence-bound Graph establishment or assurance mechanisms. The compatibility candidate computation retains its historical scope and remains NOT_ESTABLISHED.

Direct imports from verifier.core, verifier.data, verifier.hardware, other subpackages, or underscore-prefixed names are internal unless another published policy explicitly names them. They may change in a minor release. That freedom does not override frozen receipt identifiers, schemas, packaged specification bytes, command compatibility, or historical refutation obligations.

Version and deprecation rules#

Semantic Versioning governs only this declared software compatibility surface. It does not increase assurance or establish an external standard.

Separate compatibility surfaces#