verification-ecology-kit 1.0.0

Python toolkit for verification auditing, residual ledgers, conformance checks, and verifier packet workflows.

verification-ecology-kit

verification-ecology-kit is a Python toolkit for making verification work clear, traceable, and reviewable.

It helps you answer practical questions such as:

• What exactly was checked?
• What evidence was used?
• What is still unresolved?
• Which result is allowed to be reused, shared, or deployed?
• Did a file, JSON object, reference, or digest change after it was checked?
• Are failures being recorded, or are they being hidden behind a single "passed" label?

The project is based on Verifier Ecology Theory by K. Takahashi: https://doi.org/10.5281/zenodo.21147093

The theory uses precise terms. This package turns many of those terms into ordinary software objects: JSON records, Python classes, command line checks, schemas, audit reports, and release gates.

What This Package Does

Use this package when you need to record verification work in a form that other people and other tools can inspect.

It can:

• describe a verifier, check, review step, or evidence source as a structured record
• record open issues instead of dropping them after a partial pass
• validate JSON objects against bundled schemas
• compute stable SHA-256 digests for JSON files
• check whether references and digests still match
• run conformance checks over a bundle of related objects
• keep an append-only ledger of unresolved work
• make authority decisions explicit, such as "usable as evidence" versus "allowed for deployment"
• run local audits for stale evidence, hidden failures, missing counter-checks, schema overclosure, monoculture risk, and local information leakage
• build and smoke-test the Python package before release

It is useful for research tooling, safety review, software quality assurance, schema-based workflows, release checks, and projects where verification claims need a visible paper trail.

What This Package Does Not Do

This is not a theorem prover and does not claim to prove every property in the paper.

It does not replace human review, domain expertise, model checking, formal proof, fuzzing, or security testing. It gives those activities a shared record format and a set of checks so that results, limits, and remaining work are not lost.

In short:

• it records and checks verification evidence
• it keeps unfinished work visible
• it helps decide whether evidence can be reused
• it does not magically prove that a system is correct

Start Here

Choose the path that matches what you want to do.

If you want to...	Start with
Try the tool quickly	Try It In 5 Minutes
Learn the main ideas without theory jargon	Core Ideas In Plain Words
Use the command line	Command Line Overview and docs/cli.md
Use the Python API	Python Example and docs/api.md
Validate JSON records	docs/schemas.md
Check a bundle of related records	docs/conformance.md
Track unresolved work	Track Open Work
Run audits	docs/audits.md
Understand the theory mapping	docs/theory_mapping.md and docs/v1_audit.md
Review release readiness	docs/v1_readiness.md, docs/release_readiness.md, and docs/release_gates.md
Check security posture	SECURITY.md and docs/security.md

Core Ideas In Plain Words

The package uses a few terms from the paper. They are easier to understand if you map them to everyday review work.

Term	Plain meaning
Verifier	Something that checks a claim, file, object, result, or process
Verifier packet	A structured record that says what a verifier is, where it came from, what it checks, and what limits it has
Residual	Work that is not finished yet, such as a missing check, unknown boundary, exception, warning, or unresolved question
Residual ledger	A history of residuals, including when they were added, changed, retired, quarantined, or redacted
Conformance report	A step-by-step report saying whether a group of records follows the selected rules
Authority gate	A deny-by-default decision layer that says whether evidence may be reused, shared, deployed, or used for repair
Bundle	A JSON object that groups packets, ledgers, decisions, references, and related evidence
Audit	A focused check for a known failure pattern, such as stale evidence or missing counter-checks

These words matter because a simple pass or fail result is often too small for real review work. A check can pass while still depending on assumptions. A tool can be useful but too stale for deployment. A record can be valid JSON but still unsafe to circulate. This package keeps those differences visible.

How The Pieces Fit Together

A common workflow looks like this:

1. Create or receive a verifier packet.
2. Validate the packet against a JSON schema.
3. Compute digests for important JSON objects.
4. Put related objects into a bundle.
5. Run a conformance check on the bundle.
6. Record unresolved work in the residual ledger.
7. Run audits for common failure patterns.
8. Use an authority gate to decide what the evidence is allowed to do.

You can use only one part of the package, such as schema validation or digest checking, but the full workflow is designed to keep evidence, gaps, and decisions connected.

Installation

Install from GitHub:

pip install git+https://github.com/kadubon/verification-ecology-kit.git

When the PyPI package is published, installation is:

pip install verification-ecology-kit

Requirements:

• Python 3.11 or newer
• No network access is required at runtime by default

Check that the command line tool is available:

vek doctor

Try It In 5 Minutes

Create a basic verifier packet:

vek packet create --template operational

Create a JSON file and compute its digest:

python -c "from pathlib import Path; Path('object.json').write_text('{\"value\":\"demo\"}\\n', encoding='utf-8')"
vek digest object.json

Create a minimal bundle and run a conformance check:

python -c "from pathlib import Path; Path('bundle.json').write_text('{\"bundle_id\":\"demo\",\"schema_version\":\"1\",\"conformance_profile\":\"core\",\"objects\":[]}\\n', encoding='utf-8')"
vek conformance bundle.json --profile core --format markdown

Scan the current repository for obvious secret-like values and local paths:

vek scan leaks .
vek scan local-info .

Next steps:

• read docs/quickstart.md for a short walkthrough
• read docs/concepts.md for the main ideas
• run the examples in examples/

Python Example

from verification_ecology_kit import ResidualLedger, VerifierPacket

packet = VerifierPacket.minimal()
results = packet.validate()

ledger = ResidualLedger()
for residual in packet.residual_obligations:
    ledger.add(residual, justification="packet validation")

print([result.to_dict() for result in results])
print(ledger.trace_ok().to_dict())

This creates a minimal verifier packet, validates its accountability fields, records any open residual work, and checks that the ledger trace is internally consistent.

For more complete examples, see:

• examples/basic_packet.py
• examples/residual_ledger.py
• examples/operational_bundle.py
• examples/authority_gate.py
• examples/federated_bundle.py
• examples/runtime_loop.py

Common Workflows

1. Check A JSON Object

vek validate object.json --schema verifier-packet.schema.json --profile core

Use this when you want to confirm that a JSON object matches one of the bundled schemas.

2. Check A Bundle

vek conformance bundle.json --profile core --format json

Use this when you want an ordered report for schema checks, digest checks, reference checks, residual checks, judgment checks, and authority checks.

3. Track Open Work

from verification_ecology_kit import ResidualLedger, ResidualRecord
from verification_ecology_kit.model.records import ResidualKind

ledger = ResidualLedger()
residual = ResidualRecord(
    kind=ResidualKind.UNRESOLVED,
    origin="manual-review",
    scope=("boundary",),
    obligation="Review the destructive boundary before reuse.",
)
ledger.add(residual, justification="manual audit")

Use this when a check cannot honestly be treated as fully closed.

4. Run Local Audits

vek audit packet-ecology packet.json
vek audit residual-metabolism ledger.json
vek audit schema-overclosure schema-audit.json
vek audit monoculture packet.json

Use these when reviewing whether verifier packets have counter-checks, whether residuals remain live, whether a schema is hiding unknown information, or whether the verification process is becoming too uniform.

5. Operate On Packets

vek packet operate fork packet.json --reason new-scope --out forked.json
vek packet operate specialize packet.json --scope payment-flow --out scoped.json
vek packet operate repair packet.json --repair-note "added stale-evidence check" --out repaired.json
vek packet operate quarantine packet.json --reason digest-mismatch --out quarantined.json

Use these commands when a verifier packet changes state and you need the change to be visible.

Command Line Overview

Main commands:

vek init
vek doctor
vek version
vek schema list
vek schema export --out schema-out
vek validate OBJECT.json --schema SCHEMA
vek digest OBJECT.json
vek conformance BUNDLE.json --profile core --format markdown
vek refs check BUNDLE.json
vek ledger replay LEDGER.json
vek packet create --template minimal
vek packet operate fork PACKET.json --out forked-packet.json
vek packet operate compose LEFT.json RIGHT.json --out composed-packet.json
vek audit packet-ecology PACKET.json
vek audit residual-metabolism LEDGER.json
vek runtime run CONFIG.json
vek scan leaks PATH
vek scan local-info PATH

See docs/cli.md for the full command list.

Documentation Map

Use this map when you need more detail than the README.

Topic	Document
First steps	docs/quickstart.md
Main ideas	docs/concepts.md
Short definitions	docs/glossary.md
Command line usage	docs/cli.md
Python API	docs/api.md
Data model	docs/data_model.md
JSON schemas	docs/schemas.md
Conformance checks	docs/conformance.md
Audit checks	docs/audits.md
Runnable examples	docs/examples.md and examples/
Security model	docs/security.md
Theory mapping	docs/theory_mapping.md
v1 implementation audit	docs/v1_audit.md
v1 readiness	docs/v1_readiness.md
Release readiness	docs/release_readiness.md
Release gates	docs/release_gates.md
Pre-publication audit	docs/pre_publication_audit.md

Repository Map

• src/verification_ecology_kit/: package source
• src/verification_ecology_kit/schemas/: bundled JSON schemas
• examples/: small runnable examples
• tests/: unit, property, security, CLI, and golden tests
• tests/golden/: expected behavior cases
• docs/: user and release documentation
• scripts/: local verification and release-support scripts
• security/: scanner allowlist examples

Development

Install development dependencies:

uv sync --all-extras --dev

Run the main local checks:

uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest --cov=verification_ecology_kit --cov-report=term-missing

Run security, schema, docs, and package checks:

uv run python scripts/verify_no_secrets.py .
uv run python scripts/scan_local_info.py .
uv run check-jsonschema --check-metaschema src/verification_ecology_kit/schemas/*.schema.json
uv run bandit -c pyproject.toml -r src scripts
uv run pip-audit
uvx zizmor .
uv run mkdocs build --strict
uv build --no-sources
uv run python scripts/verify_package_contents.py
uv run python scripts/smoke_install_wheel.py
uv run python scripts/check_v1_readiness.py --strict

For release-specific evidence, read docs/release_readiness.md and docs/release_gates.md.

Security And Privacy

• No telemetry is built in.
• Runtime network access is not required by default.
• JSON is used for input data; pickle is not used for untrusted data.
• CI runs secret scanning, local information scanning, Bandit, pip-audit, and GitHub Actions workflow scanning.
• GitHub Actions are pinned to commit hashes and checkout credentials are not persisted in workflow jobs.

If you find a security issue, see SECURITY.md.

Project Status

Current version: 1.0.0

Status:

• first stable OSS implementation
• typed Python package
• command line interface included
• JSON schemas included
• runnable examples included
• golden tests included
• GitHub repository published
• local package build and wheel smoke install pass
• PyPI and GitHub release publication are performed after tagging

Before treating the package as v1.0.0-ready, check:

• docs/v1_audit.md
• docs/v1_readiness.md
• docs/release_readiness.md
• docs/release_gates.md

The public API is intended to stabilize around the classes exported from verification_ecology_kit.

Citation

Takahashi, K. (2026). Verifier Ecology Theory: Packetized Self-Verification Under Residual Accountability. Zenodo. https://doi.org/10.5281/zenodo.21147093

License

Apache-2.0.