Bundles, records, and result contracts¶
Create and verify deterministic collaborator manifests, build screen records, and interpret the shared result/failure taxonomy.
Research bundle manifests¶
A generated result directory can include research_bundle_manifest.json, which
records the script, parameters, package version, primary result, and file
checksums. Use verify_research_bundle_manifest() to check a received bundle.
This checks the files, not the mathematics. It detects changed or missing files but does not run the recorded workflow or decide whether a theorem is correct.
geometric_function_atlas.bundle
¶
Deterministic manifests for collaborator-ready research bundles.
A bundle is a directory of already-generated research artifacts plus one closed JSON manifest. The manifest records replay inputs and software identity and checksums every artifact; it never executes the recorded entrypoint.
BUNDLE_MANIFEST_NAME = 'research_bundle_manifest.json'
module-attribute
¶
BUNDLE_SCHEMA_VERSION = 1
module-attribute
¶
MAX_BUNDLE_ARTIFACTS = 256
module-attribute
¶
MAX_BUNDLE_ARTIFACT_BYTES = 64 * 1024 * 1024
module-attribute
¶
MAX_BUNDLE_TOTAL_BYTES = 256 * 1024 * 1024
module-attribute
¶
MAX_BUNDLE_MANIFEST_BYTES = 4 * 1024 * 1024
module-attribute
¶
write_research_bundle_manifest(directory: str | Path, *, workflow: str, entrypoint: str, parameters: Mapping[str, Any], primary_record: str, artifacts: Sequence[str]) -> Path
¶
Write a deterministic checksum manifest for existing workflow artifacts.
Artifact names are POSIX-style paths relative to directory. Symlinks,
traversal, absolute paths, the manifest itself, duplicates, missing files,
and over-limit bundles are rejected. The manifest excludes timestamps so
identical artifacts and replay inputs produce identical bytes.
verify_research_bundle_manifest(manifest: str | Path) -> dict[str, Any]
¶
Verify a research-bundle manifest and every declared artifact.
geometric_function_atlas.records
¶
Closed, versioned analysis records for screens, searches, and lab metrics.
The exact-result envelope (result.schema.json) remains reserved for
operations that emit proven_exact_under_declared_assumptions or
certified_enclosure evidence. The class-screen, function-verification,
witness-search, and lab operations emit analysis records instead: still
versioned and fail-closed, but carrying an explicit evidence_kind and
tier so a numerical screen can never be mistaken for a proof, an
enclosure for sharpness, or a benchmark metric for a security claim.
SCREEN_RECORD_VERSION = 1
module-attribute
¶
RecordError
dataclass
¶
build_screen_record(*, record_type: str, canonical_inputs: Mapping[str, Any], method: str, evidence_kind: str, tier: str, assumptions: tuple[str, ...] | list[str], source_references: tuple[str, ...] | list[str], verification: VerificationReport, details: Mapping[str, Any] | None = None, failure_state: FailureState | str | None = None) -> dict[str, Any]
¶
Build a closed analysis record; raises :class:RecordError when invalid.
validate_screen_record(record: Mapping[str, Any]) -> None
¶
Validate an analysis record against the closed contract, fail-closed.
screen_payload_finite(record: Mapping[str, Any]) -> bool
¶
Return whether every numeric field in the record is finite.
load_verify_result_schema() -> dict[str, Any]
¶
Load the dedicated, closed JSON contract for function verification records.
geometric_function_atlas.contracts
¶
Versioned, fail-closed result and verification contracts.
The contract module contains data-only records. It deliberately has no dynamic imports, expression parsing, or execution from serialized input.
RESULT_SCHEMA_VERSION = 1
module-attribute
¶
MAX_JSON_DEPTH = 128
module-attribute
¶
MAX_JSON_NODES = 10000
module-attribute
¶
CheckStatus
¶
FailureState
¶
Explicit non-success states for computations and artifact replay.
UNSUPPORTED = 'unsupported'
class-attribute
instance-attribute
¶
UNRESOLVED = 'unresolved'
class-attribute
instance-attribute
¶
INVALID_INPUT = 'invalid_input'
class-attribute
instance-attribute
¶
RESOURCE_LIMIT = 'resource_limit'
class-attribute
instance-attribute
¶
CORRUPT_ARTIFACT = 'corrupt_artifact'
class-attribute
instance-attribute
¶
LiteratureStatus
¶
Literature reconciliation is separate from computational evidence.
NOT_ASSESSED = 'not_assessed'
class-attribute
instance-attribute
¶
KNOWN = 'known'
class-attribute
instance-attribute
¶
CANDIDATE_IMPROVEMENT = 'candidate_improvement'
class-attribute
instance-attribute
¶
NO_EXTRACTED_CLAIM = 'no_extracted_claim'
class-attribute
instance-attribute
¶
UNRESOLVED = 'unresolved'
class-attribute
instance-attribute
¶
InvalidInputError
¶
Raised when a public operation receives malformed or invalid input.
failure_state = FailureState.INVALID_INPUT.value
class-attribute
instance-attribute
¶
ResourceLimitError
¶
Raised before symbolic work exceeds a documented resource bound.
failure_state = FailureState.RESOURCE_LIMIT.value
class-attribute
instance-attribute
¶
UnsupportedError
¶
Raised for an operation or artifact kind outside the package scope.
failure_state = FailureState.UNSUPPORTED.value
class-attribute
instance-attribute
¶
UnresolvedError
¶
Raised when the available evidence cannot discharge a claim.
failure_state = FailureState.UNRESOLVED.value
class-attribute
instance-attribute
¶
CorruptArtifactError
¶
Raised when a supplied artifact fails structural or checksum checks.
failure_state = FailureState.CORRUPT_ARTIFACT.value
class-attribute
instance-attribute
¶
VerificationCheck
dataclass
¶
One check in a verification report.
expected and observed are intentionally typed as Any so exact
expressions, intervals, and structured certificate values can be carried
without coercing them to floating point. to_dict converts them to a
JSON-safe representation.
name: str
instance-attribute
¶
checked: str
instance-attribute
¶
expected: Any
instance-attribute
¶
observed: Any
instance-attribute
¶
status: CheckStatus | str
instance-attribute
¶
scope: str
instance-attribute
¶
failure_reason: str | None = None
class-attribute
instance-attribute
¶
required: bool = True
class-attribute
instance-attribute
¶
__init__(name: str, checked: str, expected: Any, observed: Any, status: CheckStatus | str, scope: str, failure_reason: str | None = None, required: bool = True) -> None
¶
__post_init__() -> None
¶
to_dict() -> dict[str, Any]
¶
Return the closed JSON representation of this check.
VerificationReport
dataclass
¶
Fail-closed aggregate of independently reviewable checks.
checks: tuple[VerificationCheck, ...]
instance-attribute
¶
required_checks: tuple[VerificationCheck, ...]
property
¶
success: bool
property
¶
True only when at least one required check exists and all pass.
status: str
property
¶
Stable aggregate status derived only from required checks.
__init__(checks: tuple[VerificationCheck, ...]) -> None
¶
__post_init__() -> None
¶
to_dict() -> dict[str, Any]
¶
build_result_payload(*, result_type: str, canonical_inputs: Mapping[str, Any], exact_expressions: Mapping[str, Any], method: str, evidence_status: str, assumptions: tuple[str, ...] | list[str], source_references: tuple[str, ...] | list[str], artifact_versions: Mapping[str, str], verification: VerificationReport, legacy_fields: Mapping[str, Any], exact_expression_dag: Mapping[str, Any], provenance: str, literature_status: LiteratureStatus | str = LiteratureStatus.NOT_ASSESSED, failure_state: FailureState | str | None = None) -> dict[str, Any]
¶
Build the stable envelope while retaining established result fields.
failure_payload(state: FailureState | str, message: str) -> dict[str, Any]
¶
Return a stable JSON error record for CLI and future artifact loaders.
load_result_schema() -> dict[str, Any]
¶
Load the shipped closed JSON Schema without evaluating its contents.
load_error_schema() -> dict[str, Any]
¶
Load the shipped closed JSON error schema.
validate_result_payload(payload: Mapping[str, Any]) -> None
¶
Validate a structured result against the closed contract.
This small dependency-free validator is intentionally stricter than merely
checking that json.dumps succeeds. It rejects unknown keys so schema
drift cannot silently enter a released artifact.
validate_error_payload(payload: Mapping[str, Any]) -> None
¶
Validate a stable failure record.