Skip to content

Symbolon

Trustable contracts between agents. A contract is a precise, content-addressed promise. Evidence that someone kept it can be checked by anyone.

Agents increasingly call tools, run code they generated, and rebuild software on someone's behalf. Each of those is an implicit promise that something behaves a certain way. Symbolon writes the promise down in a form a machine can check, and records signed evidence that a specific implementation kept it.

Software capabilities are the first vertical. A contract specifies a capability, and any implementation, hand-written or AI-generated, in any language, is checked against it.

  • Get started


    Install the CLI, validate a seed contract, and watch a plausible implementation fail it.

    Getting started

  • Concepts


    Contracts, implementations, attestations, spec packs, and how digests tie them together.

    Concepts

  • CLI reference


    Every symbola command and its options.

    CLI

  • Formats


    The contract, implementation, attestation and spec pack formats.

    Contract format

The idea in one example

$ symbola test contracts/core/date-parse/versions/1 examples/impls/date-parse-strptime
...
✗ test_iso_requires_two_digit_month_and_day
    AssertionError
    Failing test case: test_iso_requires_two_digit_month_and_day(
        impl=impl,
        d=datetime.date(2000, 1, 1),  # or any other generated value
    )

FAIL  2 of 21 checks failed

$ symbola test contracts/core/date-parse/versions/1 examples/impls/date-parse-strict
PASS  21 checks

The first implementation looks right and passes the obvious examples, but it accepts 2000-1-1 as an ISO date. The contract's properties catch it. The second, independently written implementation passes the same contract. Neither implementation matters on its own: the contract, and the evidence that something passed it, are the asset.

What is in the repository

Contract format A directory with a manifest, a pydantic schema, examples and hypothesis properties. Identified by a SHA-256 digest of its contents.
Validation symbola validate checks structure, schema drift, examples, and that the spec is not vacuous.
Testing symbola test runs a contract's spec against an implementation in Python or any language that speaks a JSON line protocol.
Attestations symbola attest runs the spec in a sandbox and writes a signed in-toto attestation; symbola verify --rerun reproduces it.
Spec packs Product-level contracts: a brief, assumptions, obligations, and component contracts. symbola pack validate checks them.
Seeds and a pilot Three seed contracts and the lightkone pilot, a spec pack extracted from a real product and rebuilt by an AI from the pack alone.