Symbolon
Trustable contracts between agents. A contract is a precise, content-addressed promise; evidence that someone kept it can be checked by anyone. Software capabilities are the first vertical: a contract specifies a capability, and any implementation, hand-written or AI-generated, is checked against it.
This repository covers MVP steps 1 and 2: the contract format with init, validate, and test, and signed attestations with attest and verify, run in a container or process sandbox.
Install
uv tool install git+https://github.com/kausalflow/symbola # or: pipx install git+https://github.com/kausalflow/symbola
symbola --help
The package and command are symbola (after symbola.sh). pip install symbolon is an unrelated project.
Quick start
From a clone of this repository:
pip install -e ".[dev]"
symbola init acme/shout # scaffold a contract that already validates
symbola validate contracts/acme/shout/versions/1 # check it and print its digest
symbola validate contracts/core/date-parse/versions/1
symbola test contracts/core/date-parse/versions/1 examples/impls/date-parse-strptime # fails: too lenient
symbola test contracts/core/date-parse/versions/1 examples/impls/date-parse-strict # passes
symbola keygen # this runner's signing key
symbola attest contracts/core/date-parse/versions/1 examples/impls/date-parse-strict -o att.json
symbola verify att.json --trust ~/.config/symbolon/runner.pub \
--contract contracts/core/date-parse/versions/1 --impl examples/impls/date-parse-strict --rerun
Commands
| Command | What it does |
|---|---|
symbola init <namespace/name> |
Scaffold a contract that passes validate out of the box |
symbola validate <dir> |
Check structure, schema drift, examples, reference, spec vacuity and mutants; print the digest |
symbola schema <dir> |
Regenerate schema/*.json from schema.py |
symbola test <dir> <impl.py> |
Run the contract's examples and properties against an implementation |
symbola digest <dir> |
Print the contract's content digest |
symbola impl-init <dir> --contract <dir> |
Write an implementation manifest pinned to the contract's digest |
symbola keygen |
Create this runner's Ed25519 signing key |
symbola attest <contract> <impl> |
Run the spec in a sandbox; write a signed in-toto attestation |
symbola verify <attestation> |
Check signature, trust, digests; --rerun reproduces it locally |
symbola diff <contract> <impl> <impl>... |
Run several builds on one input pool; report where they disagree, the ambiguity estimate, and the obligations each split traces to |
symbola extract <source> --pack <ns/product> |
Have a coding agent (Claude Code by default) draft a spec pack from an existing product; check it against the original |
symbola replicate <pack> |
Hand a pack to outside coding agents (Claude Code by default), then attest, holdout-test and diff the builds they make |
symbola pack validate <dir> |
Check a spec pack's brief, assumptions and obligations; report obligations by status |
symbola mutants <dir> |
Show which checks kill which mutants, and the contract's kill rate |
symbola canary plant <dir> <out> / canary check |
Give a builder a copy with one contradictory example; catch builds fitted to the examples |
symbola flag <ref> <reason> |
Report a contradiction in the spec instead of coding around it |
Seed contracts
| Contract | Capability |
|---|---|
core/date-parse@1 |
Parse a date written in ISO, en-US, en-GB, or de-DE conventions |
core/csv-to-records@1, @2 |
Parse RFC 4180 CSV with a header into records (v2 also rejects malformed quoting) |
core/unit-convert@1 |
Convert length, mass, and temperature with exact factors |
The contract format is specified in docs/CONTRACT_FORMAT.md, implementations and attestations in docs/ATTESTATION.md, and spec packs in docs/PACK_FORMAT.md.
Documentation
The docs site is built with Zensical from docs/ and published to GitHub Pages on every push to main. Each pull request gets a preview at pr-preview/pr-<number>/, linked in a comment on the PR.
pip install -e ".[docs]"
zensical serve # http://localhost:8000
Tests
pytest
Sandbox tests run for each sandbox available on the machine: container tests need a Docker daemon, process tests need unprivileged user namespaces. Others are skipped.
Releasing
Bump __version__ in src/symbola/__init__.py, merge, then publish a GitHub release tagged v<version> (for example v0.1.0). The Publish to PyPI workflow builds the package and uploads it to PyPI as symbola through trusted publishing.
1 maintainer
Metadata
1 maintainer
Release files for symbola 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| symbola-0.1.0.tar.gz | 108.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| symbola-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 202.4 kB
Release files / symbola-0.1.0.tar.gz
| Download URL | symbola-0.1.0.tar.gz |
|---|---|
| Size | 108.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
329d90eebd61e84fc226fbf689e014b1366537c1da6cb1ffb409ef59b2617fd2
|
|
BLAKE2b-256 checksum How to use checksums |
a8f5e00c833725fe538619aa695bb40367f8d7ea947b266a1cff978ad1e09207
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / symbola-0.1.0-py3-none-any.whl
| Download URL | symbola-0.1.0-py3-none-any.whl |
|---|---|
| Size | 93.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d94a8b1bcbce99b13bb2d670baeb7a0d399ca74ad0b088852ab7838ddc3ac4ed
|
|
BLAKE2b-256 checksum How to use checksums |
42c885d1580276450a18c925ee8906571e36064819089e993b4c330b6d840834
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for symbola 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for symbola-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
