affaan-m/ECC · error · ContractError

artifact cites an unknown provenance source

Error message

artifact {relative} cites an unknown provenance source

What it means

After validating the format of each provenance source, the validator checks that the (reference_path, reference_sha256) pair exists in the bundle's known_sources set — the registry of reference files the receipt declared. This error means the artifact cites a source that is not registered, so its provenance cannot be traced to a verified reference.

Solutions

Update the receipt's reference_sha256 to the current digest of the actual reference file
Register the cited reference file in the bundle's known reference list passed to validate_bundle
Fix a renamed/moved reference path in the receipt to match the registered path
Regenerate the artifact and receipt together so provenance is consistent with the current bundle

Example fix

# before (reference was renamed)
'reference_path': 'refs/old_intro.mp4'
# after
'reference_path': 'refs/intro.mp4'  # path that is registered in known_sources

Defensive patterns

Strategy: validation

Validate before calling

known = {(s['reference_path'], s['reference_sha256']) for s in bundle_sources}
for src in entry['provenance']:
    assert (src['reference_path'], src['reference_sha256']) in known, 'unregistered provenance source'

Type guard

def source_is_known(src: dict, known_sources: set) -> bool:
    return (src.get('reference_path'), src.get('reference_sha256')) in known_sources

Try / catch

try:
    validate_artifact_receipt(out_dir)
except ContractError as e:
    if 'unknown provenance source' in str(e):
        sync_receipt_references_with_bundle(out_dir)
    else:
        raise

Prevention

Generate receipt and reference registry in the same run
Re-hash references whenever reference files are updated
Never rename reference files without regenerating the receipt
Keep one source of truth for the reference manifest

When it happens

Trigger: validate_artifact_receipt finding a source tuple absent from known_sources — citing a reference file that was never declared to validate_bundle, a renamed/moved reference, a stale digest after the reference file changed, or a typo in the reference path.

Common situations: Editing the reference file after generating the receipt (digest changed), renaming reference directories, declaring provenance to a reference that was dropped from the bundle manifest, mixing receipts across bundles.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/d241b521250c59fe. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-application/scripts/tasteforge/contract.py:416

        modalities = entry.get("modalities")
        if (not isinstance(modalities, list)
                or any(modality not in _REQUIRED_MODALITIES for modality in modalities)):
            raise ContractError(f"artifact {relative} has invalid modality binding")
        if entry.get("bytes") != path.stat().st_size:
            raise ContractError(f"artifact {relative} byte size does not match receipt")
        if entry.get("sha256") != _sha256(path):
            raise ContractError(f"artifact {relative} SHA-256 does not match receipt")
        provenance = entry.get("provenance")
        if not isinstance(provenance, list) or not provenance:
            raise ContractError(f"artifact {relative} lacks exact reference/time provenance")
        for source in provenance:
            if not isinstance(source.get("reference_path"), str) or not source["reference_path"]:
                raise ContractError(f"artifact {relative} has invalid reference path")
            digest = source.get("reference_sha256")
            if not isinstance(digest, str) or len(digest) != 64:
                raise ContractError(f"artifact {relative} has invalid reference SHA-256")
            if (source["reference_path"], digest) not in known_sources:
                raise ContractError(f"artifact {relative} cites an unknown provenance source")
            times = source.get("reference_times")
            basis = source.get("time_basis")
            if not isinstance(times, list) or basis not in {"media_seconds", "whole_file"}:
                raise ContractError(f"artifact {relative} has invalid reference/time provenance")
            if basis == "media_seconds" and not times:
                raise ContractError(f"artifact {relative} lacks media reference times")
            if basis == "whole_file" and times:
                raise ContractError(f"artifact {relative} whole-file provenance must not invent times")
            if basis == "media_seconds":
                expected_duration = source_durations.get((source["reference_path"], digest))
                if expected_duration is None or source.get("source_duration") != expected_duration:
                    raise ContractError(f"artifact {relative} has an unbound source duration")
                for time in times:
                    _validate_media_time(
                        time, expected_duration,
                        label=f"artifact {relative} media reference time",
                    )

View on GitHub (pinned to 8321021c54)