Skip to main content

tesseraline invariants: know when a change breaks a business rule

License: PolyForm Noncommercial 1.0.0 Python 3.12+ Typed

tesseraline-invariants

A function makes promises about its output: it never returns a credential, it keeps every number of its input, its result adds up. Write the promise next to the function; invariants check runs the function on many inputs and says, with a minimal failing input, when a later change breaks it.

from dataclasses import dataclass
from tesseraline_invariants import Secret, invariant, never_contains, preserves, holds


@dataclass(frozen=True, slots=True)
class WriteHandle:
    table: str
    credentials: Secret[str]


@invariant(never_contains(Secret), dry_run=True)
def to_query_json(handle: WriteHandle) -> str: ...


@invariant(preserves("numbers", "dates"), dry_run=True)
def restyle(text: str) -> str: ...


@invariant(holds(lambda inp, out: out.total == sum(inp.items)), dry_run=True)
def summarize(order: Order) -> Summary: ...
$ invariants check      # 0 all promises hold, 1 a promise broke, 2 a promise was removed, 3 configuration error
$ invariants list       # every promise, where it lives, whether it can be checked
$ invariants lock --update   # record the current promises in invariants.lock (review the diff)
$ invariants impact --since main          # which promises a change may affect (from imports; never "safe")
$ invariants check --since main           # check only those; the lock is still compared with every promise
$ pytest --invariants                     # the same check as test items (opt-in)
$ semgrep --metrics=off --disable-version-check --config "$(invariants rules)" src/   # point at exits that bypass promises

Install

$ pip install tesseraline-invariants                 # production: Secret and @invariant, standard library only
$ pip install "tesseraline-invariants[check,scan]"   # CI and developers: invariants check, pytest plugin, scan

Block a commit and a push while a promise is broken or an exit is unguarded, in .pre-commit-config.yaml:

- repo: https://github.com/tesseraline/invariants
  rev: v0.0.1
  hooks:
    - id: invariants-check   # promises hold (strict)
    - id: invariants-scan    # the Semgrep rules for unguarded exits

Install the hooks for both moments: pre-commit install --hook-type pre-commit --hook-type pre-push.

Why not a property test?

  • The promise sits next to the code it protects, so nobody has to remember to write the test.
  • never_contains plants canary values in every secret field and searches the output for them, also JSON-escaped, URL-encoded and base64-encoded.
  • invariants.lock records the promises themselves: deleting a decorator to get a green build fails the check.
  • Every check leaves an audit record: which promise, which code version, which result.

What it does not do (read this first)

  • It calls only functions whose author wrote dry_run=True, meaning "safe to run when every dependency is a fake". Every other promise is reported as not checked; it never counts as a pass.
  • The network is blocked during a check. Writes to files outside the temporary working directory are not prevented in v0.1.
  • A secret that is hashed or truncated before it leaves cannot be found by a canary search.
  • No runtime checking in production in v0.1; no model-based judging, ever: checks are code.
  • lock --update can be run by anyone; the protection is that the change shows in review.

Inputs: give your types factories

A check calls each dry_run=True function with saved regressions first, then values from your factories, then values Hypothesis builds from the types. Random values rarely look like real data: a preserves promise on text needs real sentences to mean anything. Name a factory per type in settings (below); the examples/ folder shows the difference.

Settings

pyproject.toml:

[tool.invariants]
modules = ["myapp.exporters", "myapp.reports"]   # imported to collect promises
strict = true                                     # "not checked" fails the run
secret_types = ["myapp.auth:Token"]               # your own secret types ("module:Class")
secret_fields = ["*password*", "api_key"]         # by name: heuristic, opt-in

[tool.invariants.factories]
"myapp.models:WriteHandle" = "myapp.examples.data:example_handles"
"builtins:str" = "myapp.examples.data:example_sentences"

[tool.invariants.fakes]
"myapp.ports:Mailer" = "myapp.examples.fakes:FakeMailer"   # Protocol-typed dependencies

Examples of code the check catches and of the same code done right: examples/README.md.

Licence

PolyForm Noncommercial 1.0.0 (LICENSE.md). Personal and other noncommercial use is free. Use by a company, or any use with a commercial purpose, needs a separate commercial licence: contact Tesseraline through https://github.com/tesseraline.

Required Notice: Copyright 2026 Tesseraline (https://github.com/tesseraline)

No permission is given to use this code or its documentation to train or evaluate machine learning or AI models, for any purpose; text and data mining for that purpose is reserved (Article 4(3), Directive (EU) 2019/790). See LICENSE.md.

Metadata

Release files for tesseraline-invariants 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tesseraline-invariants 0.0.1
File Size Uploaded Provenance Actions
tesseraline_invariants-0.0.1.tar.gz 453.3 kB With provenance Details for tesseraline_invariants-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tesseraline-invariants 0.0.1
File Interpreter ABI Platform Actions
tesseraline_invariants-0.0.1-py3-none-any.whl Python 3 none any Details for tesseraline_invariants-0.0.1-py3-none-any.whl

Total release size: 516.0 kB

Release files / tesseraline_invariants-0.0.1.tar.gz

Download URL tesseraline_invariants-0.0.1.tar.gz
Size 453.3 kB
Tags Source
SHA-256 checksum
How to use checksums
32012a55424e16a8f6a04dfe562674e8a36fbc06f04ce820b00dfd57cc7db4ff
BLAKE2b-256 checksum
How to use checksums
d8e21da69399475920e899b862157f447875da7deb5a6cec2dbc1b9399433085
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 Nov 17, 2026.

Transparency log

Release files / tesseraline_invariants-0.0.1-py3-none-any.whl

Download URL tesseraline_invariants-0.0.1-py3-none-any.whl
Size 62.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
85eb6425a9bf68b8cf58b5e83f3bcfcada96a46b33b363dd9c60ce43e4fc7b6d
BLAKE2b-256 checksum
How to use checksums
d6a513f516df4745ba49c33a8c887fecc913e9dc643b5b51e153b5eb069cd6eb
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 Nov 17, 2026.

Transparency log

Security for tesseraline-invariants 0.0.1

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

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tesseraline_invariants-0.0.1.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 Nov 17, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page