Library API

Both verifiers can be called from code. Each returns the report that the specification defines in the report contract, and evidence that fails verification is a report, never an exception.

Python: verify_path

The command line is a thin layer over one call, verify_path, which returns the report that --json writes. From the repository root:

from loquitur.verify import exit_code_for_status, read_trust_root_document, verify_path

report = verify_path("tests/fixtures/valid_bundle.zip")
print(report.status, report.verdict, exit_code_for_status(report.status))

report = verify_path(
    "tests/fixtures/link_valid_bundle.zip",
    registry_entry_path="tests/fixtures/authorization_valid_registry_entry.json",
    trust_registry_path="tests/fixtures/authorization_quickstart_trust_registry.json",
    trust_roots=read_trust_root_document("tests/fixtures/authorization_quickstart_trust_root.json"),
    evaluation_time="2026-05-20T00:00:00Z",
)
payload = report.to_dict()  # the JSON report, as a dict
print(payload["status"], payload["outcome"]["reason"])

It prints OFFLINE_OK PASS 0, then OFFLINE_OK local_integrity_registry_link_and_trust_checks_passed.

verify_path takes the bundle path and, as keywords, registry_entry_path, trust_registry_path, trust_roots, evaluation_time, your evaluation time as a string of the form YYYY-MM-DDTHH:MM:SSZ, and vocabularies, a mapping of a kind (asset_type, workflow or anchoring_method) to the path of a vocabulary document you supply or to a HeldVocabulary; a document that is refused raises VocabularyError before anything is read. Evidence that fails verification is a report, never an exception. A malformed trust_roots or evaluation_time raises TrustRootError or EvaluationTimeError before anything is read, where the command line exits 64. A host that reads the trust-root document itself and fails to read it passes DOCUMENT_READ_FAILED of loquitur.verify as trust_roots: the report is HOST_FAILURE with the error trust_root_read_failed, as the command line reports a --trust-root file it fails to read. Every exception the package raises on purpose is also a LoquiturVerifyError (from loquitur.verify import LoquiturVerifyError), beside the built-in base it has always had (ValueError, OSError or Exception): one except clause catches the verifier’s own errors, and code that catches the built-in base is unaffected. The package ships type information (py.typed).

Included from loquitur-verify-py/README.md, “Python API”. MIT OR Apache-2.0.

TypeScript: verifyBundle

import { verifyBundle } from "@loquitur/verify";

// registryEntry, trustRegistry and trustRoots are documents the host has read,
// for instance with readDocumentPath, which the package exports.
const report = verifyBundle("./my_bundle", {
  registryEntry, // optional: requests the link check
  trustRegistry, // optional: requests the authorization check; FAIL without registryEntry
  trustRoots,    // optional: without it, an authorization that holds is REVIEW
  // The operator's time; without it, authorization is not established (REVIEW).
  evaluationTime: "2026-05-20T00:00:00Z",
});

console.log(report.status, report.verdict, report.exit_code);
console.log(report.checks_requested, report.checks_established, report.review_reasons);
console.log(report.outcome.reason, report.errors.map((e) => e.code)); // the reason surface
console.log(report.trust_registry); // the three authorization statuses, or null
console.log(report.checks); // per-check results, same keys as loquitur-verify

The documents are values, not paths: the host reads them and passes what it found. That is the parsed document, or one of four markers this package exports: DOCUMENT_PATH_NAMES_NOTHING when nothing is found at the path, DOCUMENT_PATH_NAMES_NO_REGULAR_FILE when what is found is a directory or anything else that is not a regular file, DOCUMENT_READ_FAILED when reading the file failed, and DOCUMENT_NOT_STRICT_JSON when the bytes are not strict JSON. report-contract.md section 5.3 gives the first three conditions errors of their own for a registry entry, different from a document that is not strict JSON, so a host that passed a document for them would report what loquitur-verify, which reads the path itself, does not. A file the host failed to read is a host failure for the trust registry and the trust roots too: trust_registry_read_failed and trust_root_read_failed, HOST_FAILURE, exit 5.

Included from loquitur-verify-ts/README.md, “Quick start”. MIT OR Apache-2.0.

The other exports, such as readDocumentPath and the lower-level primitives, are described in the package README and declared in the type declarations the package ships.