Skip to content

Artifact Admission

Artifact admission verifies that a regular file about to enter a workflow has the same bytes as one exact input from an explicitly selected completed run. It is separate from cache lookup: admission always computes a full raw-file SHA-256 identity, while Artifact.hash may represent a fast, directory, or caller-supplied fingerprint.

Consist reports evidence without deciding workflow policy. Callers such as PILATES can classify an AdmissionReport as fatal, warning-only, or acceptable for their execution mode.

Basic usage

from consist import check_artifact_identity

report = check_artifact_identity(
    tracker,
    execution_path="inputs/gtfs.zip",
    expected_run_id="baseline-beam-run",
    artifact_key="config:seattle/r5/seattle_gtfs.zip",
)

if report.outcome != "verified":
    raise RuntimeError(report.canonical_json())

The expected run must be completed and must have exactly one input link with the requested artifact key. Historical hashes without explicit full-file semantics remain unverified unless a distinct immutable expected_bytes_path corroborates the stored historical fingerprint.

Runtime-resolved inputs

Applications that already prove the consumer's host/container mapping should pass that evidence through AdmissionReference. Consist hashes only execution_path; it records consumer_path but does not recreate mount or configuration resolution. The report's physical_target_path always comes from resolving execution_path; callers cannot replace that audit value.

from consist import AdmissionReference, check_admission_reference

report = check_admission_reference(
    tracker,
    expected_run_id="baseline-beam-run",
    reference=AdmissionReference(
        artifact_key="linkstats_warmstart",
        execution_path="workspace/beam/input/seattle/warmstart.csv.gz",
        consumer_path="/app/input/seattle/warmstart.csv.gz",
    ),
)

Report schema compatibility

New reports use schema version 2, which adds consumer_path to the serialized payload. Sidecars retain their own report_schema_version; consumers that read both historical and new sidecars should branch on that field, treating a missing consumer_path in version 1 as unavailable rather than as a path claim. Consist does not rewrite existing sidecars.

Public API

consist.core.admission.AdmissionReport

Bases: BaseModel

Represent the policy-neutral result of checking one external file.

Attributes:

Name Type Description
report_schema_version int

Version of the serialized admission-report schema.
outcome {'verified', 'mismatched', 'unverified', 'unreadable'}

High-level result. verified means the observed and expected byte identities match; mismatched means both identities are known and differ; unverified means Consist could not establish a trusted expected identity; and unreadable means the observed file could not be read as a regular file.
input_role str

Logical role supplied by the caller, defaulting to artifact_key.
artifact_key str

Exact persisted input-artifact key selected on the expected run.
config_key str or None

Source configuration key when supplied by a future runtime adapter.
config_reference_key str or None

Canonical configuration-reference key when distinct from config_key.
feed_key str or None

Feed selector associated with the input, when available.
raw_config_value str or None

Unmodified value read from workflow configuration.
canonical_value str or None

Portable canonical value produced by configuration canonicalization.
configured_path str or None

Path derived from configuration before execution-path resolution.
execution_path str

File path supplied for admission and intended for workflow execution.
physical_target_path str or None

Resolved physical target used for path-audit and alias detection.
consumer_path str or None

Final path supplied to the consumer, such as a container path.
expected_source {'prior_run'}

Source used to resolve the expected identity in the V1 contract.
expected_run_id str

Explicit completed run supplying the expected input artifact.
expected_artifact_id str or None

Trusted self-describing expected identity, such as sha256:file:<hex>.
observed_artifact_id str or None

Full-file identity computed from execution_path when readable.
digest_algorithm {'sha256'}

Digest algorithm used by the admission identity contract.
expected_bytes_source {'explicit_immutable_path'} or None

Evidence source used to reverify a historical hash with unknown semantics.
expected_bytes_path str or None

Resolved audit path for the expected-byte evidence.
observations tuple[str, ...]

Stable machine-readable facts supporting outcome.
recommended_action str or None

Workflow-independent remediation, used only when Consist can identify a generally valid action.
reason str or None

Human-readable explanation for the outcome.
Notes

Reports are frozen Pydantic models. They describe evidence but do not assign workflow severity or mutate run state.

artifact_key instance-attribute

canonical_value = None class-attribute instance-attribute

config_key = None class-attribute instance-attribute

config_reference_key = None class-attribute instance-attribute

configured_path = None class-attribute instance-attribute

consumer_path = None class-attribute instance-attribute

digest_algorithm = 'sha256' class-attribute instance-attribute

execution_path instance-attribute

expected_artifact_id = None class-attribute instance-attribute

expected_bytes_path = None class-attribute instance-attribute

expected_bytes_source = None class-attribute instance-attribute

expected_run_id instance-attribute

expected_source = 'prior_run' class-attribute instance-attribute

feed_key = None class-attribute instance-attribute

input_role instance-attribute

model_config = ConfigDict(frozen=True) class-attribute instance-attribute

observations = () class-attribute instance-attribute

observed_artifact_id = None class-attribute instance-attribute

outcome instance-attribute

physical_target_path = None class-attribute instance-attribute

raw_config_value = None class-attribute instance-attribute

reason = None class-attribute instance-attribute

recommended_action = None class-attribute instance-attribute

report_schema_version = ADMISSION_REPORT_SCHEMA_VERSION class-attribute instance-attribute

canonical_json()

Serialize the report deterministically for sidecars and automation.

Returns:

Type Description
str

Compact JSON with sorted keys and all schema fields represented.
Notes

The returned string has no trailing newline or ephemeral timestamp. Identical report values therefore produce identical serialized text.

consist.core.admission.check_artifact_identity(tracker, *, execution_path, expected_run_id, artifact_key, expected_bytes_path=None, input_role=None)

Compare a resolved file with one input from an explicit completed run.

Parameters:

Name Type Description Default
tracker Tracker

Tracker whose provenance database contains the expected run and input artifact.

 required
execution_path str or Path

Resolved regular file that the receiving workflow intends to consume.

 required
expected_run_id str

Exact completed run ID supplying the expected input identity. Consist does not select or infer a baseline run automatically.

 required
artifact_key str

Exact artifact key that must identify one direction="input" link on the expected run.

 required
expected_bytes_path str or Path or None

Distinct immutable copy of the historical bytes used only when the stored artifact hash lacks explicit full-file semantics. Its full-file digest must corroborate the historical 64-character hash, and it must not resolve to the observed file through a path, symlink, or hardlink.

 None
input_role str or None

Stronger logical role to record in the report. Defaults to artifact_key and does not alter expected-artifact lookup.

 None

Returns:

Type Description
AdmissionReport

Versioned report containing the outcome, expected and observed identities, audit paths, and supporting observations.

Raises:

Type Description
RuntimeError

If tracker has no configured provenance database.
Notes

Missing files, placeholder files, unresolved expectations, and byte mismatches are represented in the returned report rather than raised as policy exceptions. This function does not copy files, change run status, or decide whether an observation should stop a workflow.

Examples:

Check a resolved feed against one exact input from a pinned baseline run::

report = check_artifact_identity(
    tracker,
    execution_path="inputs/gtfs.zip",
    expected_run_id="baseline-beam-run",
    artifact_key="config:seattle/r5/seattle_gtfs.zip",
)

if report.outcome != "verified":
    raise RuntimeError(report.canonical_json())

consist.core.admission.AdmissionReference

Bases: BaseModel

Represent caller-proven runtime context for one admitted input.

execution_path is the host-readable file Consist hashes. consumer_path is the final path supplied to the consumer and may be in another namespace, such as a container. Consist derives physical_target_path from execution_path and does not accept caller control over that audit value. The calling workflow is responsible for proving that execution and consumer paths describe the same staged bytes before it creates this value.

Attributes:

Name Type Description
artifact_key str

Exact persisted input-artifact key to resolve on the expected run.
execution_path str or Path

Host-readable regular file whose bytes Consist checks.
input_role (str, optional)

Stronger logical role to record without changing artifact lookup.
config_key (str, optional)

Source configuration key that selected the input.
config_reference_key (str, optional)

Canonical configuration-reference key when it differs from config_key.
feed_key (str, optional)

Adapter-defined feed selector associated with the input.
raw_config_value (str, optional)

Unmodified configuration value before canonicalization.
canonical_value (str, optional)

Portable configuration value produced during canonicalization.
configured_path (str or Path, optional)

Path derived from configuration before launch-time resolution.
consumer_path (str, optional)

Final path provided to the consumer, such as a container path.
Notes

The model is frozen and forbids unknown fields. It records runtime context but does not validate a mount, staging, or container mapping; that proof is owned by the calling workflow.

artifact_key instance-attribute

canonical_value = None class-attribute instance-attribute

config_key = None class-attribute instance-attribute

config_reference_key = None class-attribute instance-attribute

configured_path = None class-attribute instance-attribute

consumer_path = None class-attribute instance-attribute

execution_path instance-attribute

feed_key = None class-attribute instance-attribute

input_role = None class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', frozen=True) class-attribute instance-attribute

raw_config_value = None class-attribute instance-attribute

consist.core.admission.check_admission_reference(tracker, *, reference, expected_run_id, expected_bytes_path=None)

Check a runtime-resolved input without recreating consumer path logic.

The byte comparison delegates to :func:check_artifact_identity; this wrapper only attaches caller-proven runtime path evidence to its report.

Parameters:

Name Type Description Default
tracker Tracker

Tracker whose provenance database contains the expected prior run.

 required
reference AdmissionReference

Frozen runtime context containing the host execution path and optional configuration and consumer-path evidence.

 required
expected_run_id str

Explicit completed run that supplies the expected input identity.

 required
expected_bytes_path str or Path

Distinct immutable expected-byte fallback for a historical artifact whose stored hash lacks explicit full-file semantics.

 None

Returns:

Type Description
AdmissionReport

The base identity report enriched with validated reference context.

Raises:

Type Description
RuntimeError

If the tracker has no configured provenance database.
Notes

physical_target_path remains derived by the underlying checker from reference.execution_path. This API records a final consumer path but intentionally does not infer or validate host/container mapping itself.

Developer identity helpers

These lower-level helpers define how artifact fingerprints are described and how the admission-specific full-file identity is computed. Most application code should use check_artifact_identity(...) instead.

consist.core.admission.admission_file_identity(path)

Compute the canonical admission identity for one regular file.

Parameters:

Name Type Description Default
path str or Path

File whose raw bytes should be hashed.

 required

Returns:

Type Description
str

Self-describing identity in the form sha256:file:<hex>.

Raises:

Type Description
ValueError

If path is missing or is not a regular file.
OSError

If the file cannot be opened or read.
Notes

This function always hashes full file contents and does not consult or modify a tracker's cache hashing strategy.

consist.core.admission.hash_semantics_for_new_artifact(*, path, hashing_strategy, source)

Describe the semantics of a newly logged artifact fingerprint.

Parameters:

Name Type Description Default
path Path or None

Resolved artifact path. Required when source="computed" and ignored when the hash was supplied by the caller.

 required
hashing_strategy ('full', 'fast')

Tracker hashing strategy active when the fingerprint was computed.

 "full"
source ('computed', 'caller_supplied')

Whether Consist computed the fingerprint or accepted it from a caller.

 "computed"

Returns:

Type Description
dict[str, object]

Versioned metadata containing algorithm, kind, digest_contract, and source. Caller-supplied hashes remain explicitly unknown unless another operation validates their semantics.

Raises:

Type Description
AssertionError

If source="computed" is used without a path.
Notes

This helper describes the existing Artifact.hash value; it does not compute or replace that value. Admission trusts only the exact full-file SHA-256 semantics emitted for a regular file under the full strategy.